Difference between revisions of "LoRaWAN"

From HSYCO
Jump to navigation Jump to search
 
(21 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
HSYCO acts as a server for one or more LoRaWAN gateways configured as standard Semtech packet forwarders. Communication is carried on UDP packets.
 
HSYCO acts as a server for one or more LoRaWAN gateways configured as standard Semtech packet forwarders. Communication is carried on UDP packets.
  
−
The implementation complies with the  [https://github.com/Lora-net/packet_forwarder Semtech's paket forwarder protocol] v4.0.1 and supports Class A end devices using unconfirmed data frames and ABP authentication.
+
The implementation complies with the  [https://github.com/Lora-net/packet_forwarder Semtech's paket forwarder protocol] v4.0.1 and supports Class A and Class C end devices, using unconfirmed data frames and ABP authentication.
  
 
[[Category:I/O Server]]
 
[[Category:I/O Server]]
Line 11: Line 11:
 
Add a LORAWAN I/O Server in the [[Settings#I/O Servers|I/O Servers section of the Settings]] and set its parameters:
 
Add a LORAWAN I/O Server in the [[Settings#I/O Servers|I/O Servers section of the Settings]] and set its parameters:
  
−
{{note|Note that only one instance of the LORAWAN I/O Server is allowed and it consumes one item for each defined gateway from the I/O Servers license total.}}
+
{{note|'''Note''': only one instance of the LORAWAN I/O Server is allowed and it consumes one item for each defined gateway from the I/O Servers license total.}}
  
 
=== High Availability ===
 
=== High Availability ===
Line 27: Line 27:
  
 
|localport
 
|localport
−
|
+
|1700
 
|<port_number>
 
|<port_number>
 
|the IP port number used locally by HSYCO to listen for incoming UDP packets sent by the gateways
 
|the IP port number used locally by HSYCO to listen for incoming UDP packets sent by the gateways
 +
 +
|-
 +
 +
|downlinkpower
 +
|
 +
|2...20
 +
|default power value for downlink frames (attribute "txpk" > "powe")
  
 
|-
 
|-
Line 44: Line 51:
 
=== LoRaWAN Utility ===
 
=== LoRaWAN Utility ===
  
−
Use the [[LoRaWAN Utility]] to automatically discover gateways and devices and setup the communication and functional parameters.
+
Use the [[LoRaWAN Utility]] to automatically discover gateways and devices and setup communication and functional parameters.
  
 
== Gateways Configuration ==
 
== Gateways Configuration ==
−
Configure the gateway(s) as standard Semtech packet forwarder(s). Make sure the network configuration allows for the communication with HSYCO and use HSYCO's IP address and the port number specified in the "localport" option for the network server's configuration.
+
The LoRaWAN gateway(s) that will be used need to be configured to forward the received device data frames to HSYCO.
 +
 
 +
To this end, configure the gateway(s) as standard Semtech packet forwarder(s). Make sure the network configuration allows for the communication with HSYCO and use HSYCO's IP address and the port number specified in the "localport" option for the network server's configuration.
  
 
== Datapoints ==
 
== Datapoints ==
 +
 +
When no gateway nor device is configured, the LoRaWAN I/O Server starts in automatic discovery mode. Datapoints are created for all discovered gateways and devices; the <id> portion of the datapoints is set to the MAC address for gateways and to the LoRaWAN address for devices.
 +
 +
After configuration through the [[LoRaWAN Utility]], datapoints will be generated only for defined gateways and devices. To re-enable discovery it must be done manually from the utility.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 85: Line 98:
  
 
|gw.<id>.stat.time
 
|gw.<id>.stat.time
−
|<time>
+
|<nowiki><time></nowiki>
 
|R
 
|R
−
|UTC 'system' time reported in the latest status message from gateway <id>
+
|UTC system time reported in the latest status message from gateway <id>
  
 
|-
 
|-
Line 158: Line 171:
 
|R
 
|R
 
|timestamp of the last packet received from device <id>
 
|timestamp of the last packet received from device <id>
 +
 +
|-
 +
 +
|dev.<id>.data
 +
|<bytes>
 +
|R
 +
|Hexadecimal representation of the data transmitted in the last valid packet received from device <id>. E.g.: "010fbb"
 +
 +
|-
 +
 +
|dev.<id>.data.ch<n>
 +
|<val>
 +
|R
 +
|Cayenne channel <n>'s value. Possible values depend on the channel's type, refer to [[#Cayenne LLP format]] for details. Datapoint available only if Cayenne data format is enabled on this device
 +
 +
|-
 +
 +
|style="white-space:nowrap" rowspan="2" |dev.<id>.data.ch<n>.type
 +
|rowspan="2" |<t>
 +
|R
 +
|Cayenne channel <n>'s type. Refer to [[#Cayenne LLP format]] for details. Datapoint available only if Cayenne data format is enabled on this device
 +
|-
 +
|W
 +
|Set Cayenne channel <n>'s type. To be used to write output channels for which no data has been received. Possible values are "1" (digital output) or "3" (analog output). Datapoint available only if Cayenne data format is enabled on this device
  
 
|-
 
|-
Line 164: Line 201:
 
|rowspan="2" |<n>
 
|rowspan="2" |<n>
 
|R
 
|R
−
|server-side uplink frame counter for device <id>. Used for frames validation. If never set and no frame has ever been received it is set to -1
+
|server-side uplink frame-counter for device <id>. Used for frames validation. If never set and no frame has ever been received it is set to -1
 
|-
 
|-
 
|W
 
|W
Line 178: Line 215:
 
|W
 
|W
 
|set the downlink frame counter for device <id>
 
|set the downlink frame counter for device <id>
 +
 +
|-
 +
 +
|dev.<id>.datr
 +
|SF<sf>BW<bw>
 +
|R
 +
|Data rate of last valid packet received from device <id>. <sf> ranges from 7 to 12 and <bw> is either 125, 250 or 500. E.g.: "SF7BW125"
 +
 +
|-
 +
 +
|dev.<id>.codr
 +
|<cr>
 +
|R
 +
|Coding rate of last valid packet received from device <id>. Possible <cr> values: "4/5", "4/6", "4/7", "4/8"
 +
 +
|-
 +
 +
|dev.<id>.freq
 +
|<fr>
 +
|R
 +
|TX central frequency in MHz (float, Hz precision) of last valid packet received from device <id>
 +
 +
|-
 +
 +
|dev.<id>.lsnr
 +
|<val>
 +
|R
 +
|LoRa SNR ratio in dB (float, 0.1 dB precision) of last valid packet received from device <id>
 +
 +
|-
 +
 +
|dev.<id>.rssi
 +
|<val>
 +
|R
 +
|RSSI in dBm (signed integer, 1 dB precision) of last valid packet received from device <id>
 +
 +
|-
 +
 +
|dev.<id>.tmst
 +
|<val>
 +
|R
 +
|gateway internal timestamp of the instant the last valid frame from device <id> was received
 +
 +
|-
 +
 +
|dev.<id>.gw
 +
|<gw_id>
 +
|R
 +
|ID of the gateway from which the latest packet from device <id> was received
  
 
|-
 
|-
Line 211: Line 297:
 
|R
 
|R
 
|the message integrity code (MIC) in the latest uplink frame from device <id> was not valid
 
|the message integrity code (MIC) in the latest uplink frame from device <id> was not valid
 +
 +
|-
 +
 +
|rowspan="3" |dev.<id>.queue
 +
|<nowiki><data></nowiki>
 +
|W
 +
|add a frame with the specified data (hexadecimal representation, e.g. "010fbb") to the downlink queue of device <id>, using the default transmission parameters.
 +
|-
 +
|<JSON>
 +
|W
 +
|add a frame with the specified data and transmission parameters to the downlink queue of device <id>. See [[#Downlink frame JSON format]] for details
 +
|-
 +
|clear
 +
|W
 +
|clear the downlink queue of device <id>
 +
 +
|-
 +
 +
|dev.<id>.queue.ch<n>
 +
|<val>
 +
|W
 +
|add a frame to the downlink queue of device <id> with Cayenne-encoded data for setting channel <n> to <val>. Possible values depend on the channel's type. Make sure the channel's type is set before writing this datapoint. The packet will be sent using the default transmission parameters. Datapoint available only if Cayenne data format is enabled on this device
  
 
|-
 
|-
Line 229: Line 337:
 
|R
 
|R
 
|the gateway responded with the reported error code to the last downlink request for device <id>. Possible values are "TOO_LATE", "TOO_EARLY", "COLLISION_PACKET", "COLLISION_BEACON", "TX_FREQ", "TX_POWER", "GPS_UNLOCKED"
 
|the gateway responded with the reported error code to the last downlink request for device <id>. Possible values are "TOO_LATE", "TOO_EARLY", "COLLISION_PACKET", "COLLISION_BEACON", "TX_FREQ", "TX_POWER", "GPS_UNLOCKED"
 +
 +
|-
 +
 +
|rowspan="2"|dev.<id>.error.data
 +
|0
 +
|R
 +
|data in the last frame received from device <id> was processed correctly. Datapoint available only if Cayenne data format is enabled on this device
 +
|-
 +
|1
 +
|R
 +
|error processing data in the last frame received from device <id>. Datapoint available only if Cayenne data format is enabled on this device
 +
 +
|}
 +
 +
=== Downlink frame JSON format ===
 +
Datapoint "dev.<id>.queue" accepts as value a JSON object with the following attributes:
 +
* '''data''': hexadecimal representation of the data bytes (as string) ''or'' JSON object with Cayenne fields:
 +
** '''channel''': Cayenne channel number
 +
** '''type''': Cayenne channel type
 +
** '''value''': Cayenne channel value
 +
* '''port''': port number to send the data to
 +
* '''attempts''': number of attempts made to deliver the frame to the gateway before discarding it
 +
* '''txpk''': JSON object with the metadata fields to include in the downlink packet:
 +
** '''codr''': Coding rate
 +
** '''datr''': Data rate
 +
** '''powe''': Power
 +
** '''rfch''': RF chain
 +
** For additional fields see [https://github.com/Lora-net/packet_forwarder/blob/master/PROTOCOL.TXT#L351 here]
 +
 +
Other than "data", all additional attributes are optional. When not specified, default values, based on the device's settings and on the last received packet, will be used .
 +
 +
Example 1 (spaces added for readability):
 +
<pre>
 +
{
 +
    "data": "aa330b",
 +
    "port": 7,
 +
    "attempts": 5,
 +
    "txpk" : {
 +
        "codr": "4/5",
 +
        "powe": 14,
 +
        "datr": "SF7BW125",
 +
        "rfch":0
 +
    }
 +
}
 +
</pre>
 +
 +
Example 2:
 +
<pre>
 +
{
 +
    "data": "020304aa330bff",
 +
    "port": 5
 +
}
 +
</pre>
 +
 +
Example 3:
 +
<pre>
 +
{
 +
    "data": {
 +
        "channel": 6,
 +
        "type": 3,
 +
        "value": 23.14
 +
    },
 +
    "attempts": 2
 +
}
 +
</pre>
 +
 +
=== Cayenne LLP format ===
 +
 +
{| class="wikitable"
 +
!Type value
 +
!Type description
 +
!Value format
 +
 +
|-
 +
 +
|0
 +
|digital input
 +
|0 or 1
 +
 +
|-
 +
 +
|1
 +
|digital output
 +
|0 or 1
 +
 +
|-
 +
 +
|2
 +
|analog input
 +
|signed decimal number with 0.01 resolution
 +
 +
|-
 +
 +
|3
 +
|analog output
 +
|signed decimal number with 0.01 resolution
 +
 +
|-
 +
 +
|101
 +
|illuminance sensor
 +
|integer value in Lux
 +
 +
|-
 +
 +
|102
 +
|presence sensor
 +
|0 or 1
 +
 +
|-
 +
 +
|103
 +
|style="white-space:nowrap" |temperature sensor
 +
|signed decimal value in &deg;C with 0.1 resolution
 +
 +
|-
 +
 +
|104
 +
|humidity sensor
 +
|unsigned decimal value in % with 0.5 resolution
 +
 +
|-
 +
 +
|113
 +
|accelerometer
 +
|[''x'', ''y'', ''z''] where ''x'', ''y'' and ''z'' represent the acceleration on each axis. They are signed decimal values in G with 0.001 resolution
 +
 +
|-
 +
 +
|115
 +
|barometer
 +
|unsigned decimal value in hPa with 0.1 resolution
 +
 +
|-
 +
 +
|134
 +
|gyrometer
 +
|[''x'', ''y'', ''z''] where ''x'', ''y'' and ''z'' represent the rotation on each axis. They are signed decimal values in &deg;/s with 0.01 resolution
 +
 +
|-
 +
 +
|136
 +
|GPS location
 +
|[''latitude'', ''longitude'', ''altitude''] where ''latitude'' and ''longitude'' are signed decimal values in &deg; with 0.0001 resolution and ''altitude'' is a signed decimal value in meters with 0.01 resolution
  
 
|}
 
|}
  
 
== Release Notes ==
 
== Release Notes ==
 +
=== 3.8.0 ===
 +
*added "downlinkpower" I/O server option
 +
*fixed license limits check when I/O server restarts
 +
*fixed bug affecting devices with disabled frame-counter validation upon uplink counter roll-over
 +
 
=== 3.7.0 ===
 
=== 3.7.0 ===
 
*initial release
 
*initial release

Latest revision as of 16:54, 6 April 2022

The LoRaWAN I/O Server implements both a LoRaWAN Network and Application servers for the integration of a LoRaWAN network.

HSYCO acts as a server for one or more LoRaWAN gateways configured as standard Semtech packet forwarders. Communication is carried on UDP packets.

The implementation complies with the Semtech's paket forwarder protocol v4.0.1 and supports Class A and Class C end devices, using unconfirmed data frames and ABP authentication.


HSYCO Configuration

Add a LORAWAN I/O Server in the I/O Servers section of the Settings and set its parameters:

Note: only one instance of the LORAWAN I/O Server is allowed and it consumes one item for each defined gateway from the I/O Servers license total.


High Availability

  • Shutdown when inactive: defaults to true.

Options

ID Default Values Description
localport 1700 <port_number> the IP port number used locally by HSYCO to listen for incoming UDP packets sent by the gateways
downlinkpower 2...20 default power value for downlink frames (attribute "txpk" > "powe")
debug false true print debugging information to the logs
false don't print debugging information to the logs

LoRaWAN Utility

Use the LoRaWAN Utility to automatically discover gateways and devices and setup communication and functional parameters.

Gateways Configuration

The LoRaWAN gateway(s) that will be used need to be configured to forward the received device data frames to HSYCO.

To this end, configure the gateway(s) as standard Semtech packet forwarder(s). Make sure the network configuration allows for the communication with HSYCO and use HSYCO's IP address and the port number specified in the "localport" option for the network server's configuration.

Datapoints

When no gateway nor device is configured, the LoRaWAN I/O Server starts in automatic discovery mode. Datapoints are created for all discovered gateways and devices; the <id> portion of the datapoints is set to the MAC address for gateways and to the LoRaWAN address for devices.

After configuration through the LoRaWAN Utility, datapoints will be generated only for defined gateways and devices. To re-enable discovery it must be done manually from the utility.

ID Value R/W Description
connection online R ready to receive packets
offline R not ready
gw.<id>.lastseen <ts> R timestamp of the last packet received from gateway <id>
gw.<id>.lastpull <ts> R timestamp of the last "pull data" packet received from gateway <id>
gw.<id>.stat.time <time> R UTC system time reported in the latest status message from gateway <id>
gw.<id>.stat.lati <n> R GPS latitude in degree (float, N is +) reported in the latest status message from gateway <id>
gw.<id>.stat.long <n> R GPS longitude in degree (float, E is +) reported in the latest status message from gateway <id>
gw.<id>.stat.alti <n> R GPS altitude in meter reported in the latest status message from gateway <id>
gw.<id>.stat.rxnb <n> R number of radio packets received reported in the latest status message from gateway <id>
gw.<id>.stat.rxok <n> R number of radio packets received with a valid PHY CRC reported in the latest status message from gateway <id>
gw.<id>.stat.rxfw <n> R number of radio packets forwarded reported in the latest status message from gateway <id>
gw.<id>.stat.ackr <n> R percentage of upstream datagrams that were acknowledged reported in the latest status message from gateway <id>
gw.<id>.stat.dwnb <n> R number of downlink datagrams received reported in the latest status message from gateway <id>
gw.<id>.stat.txnb <n> R number of packets emitted reported in the latest status message from gateway <id>
dev.<id>.lastseen <ts> R timestamp of the last packet received from device <id>
dev.<id>.data <bytes> R Hexadecimal representation of the data transmitted in the last valid packet received from device <id>. E.g.: "010fbb"
dev.<id>.data.ch<n> <val> R Cayenne channel <n>'s value. Possible values depend on the channel's type, refer to #Cayenne LLP format for details. Datapoint available only if Cayenne data format is enabled on this device
dev.<id>.data.ch<n>.type <t> R Cayenne channel <n>'s type. Refer to #Cayenne LLP format for details. Datapoint available only if Cayenne data format is enabled on this device
W Set Cayenne channel <n>'s type. To be used to write output channels for which no data has been received. Possible values are "1" (digital output) or "3" (analog output). Datapoint available only if Cayenne data format is enabled on this device
dev.<id>.fcnt.up <n> R server-side uplink frame-counter for device <id>. Used for frames validation. If never set and no frame has ever been received it is set to -1
W set the server-side downlink frame counter for device <id>
dev.<id>.fcnt.down <n> R value of the last frame counter used to send a downlink to device <id>. If never set o no frame has ever been sent it is set to -1
W set the downlink frame counter for device <id>
dev.<id>.datr SF<sf>BW<bw> R Data rate of last valid packet received from device <id>. <sf> ranges from 7 to 12 and <bw> is either 125, 250 or 500. E.g.: "SF7BW125"
dev.<id>.codr <cr> R Coding rate of last valid packet received from device <id>. Possible <cr> values: "4/5", "4/6", "4/7", "4/8"
dev.<id>.freq <fr> R TX central frequency in MHz (float, Hz precision) of last valid packet received from device <id>
dev.<id>.lsnr <val> R LoRa SNR ratio in dB (float, 0.1 dB precision) of last valid packet received from device <id>
dev.<id>.rssi <val> R RSSI in dBm (signed integer, 1 dB precision) of last valid packet received from device <id>
dev.<id>.tmst <val> R gateway internal timestamp of the instant the last valid frame from device <id> was received
dev.<id>.gw <gw_id> R ID of the gateway from which the latest packet from device <id> was received
dev.<id>.warning.data 0 R the latest uplink frame from device <id> has been decoded correctly
1 R error decoding the latest uplink frame from device <id>
dev.<id>.warning.fcnt 0 R the frame counter in the latest uplink frame from device <id> was valid
n >= 10 R the frame counter in the latest uplink frame from device <id> was not valid (n = 10: repetition)
dev.<id>.warning.mic 0 R the message integrity code (MIC) in the latest uplink frame from device <id> was valid
1 R the message integrity code (MIC) in the latest uplink frame from device <id> was not valid
dev.<id>.queue <data> W add a frame with the specified data (hexadecimal representation, e.g. "010fbb") to the downlink queue of device <id>, using the default transmission parameters.
<JSON> W add a frame with the specified data and transmission parameters to the downlink queue of device <id>. See #Downlink frame JSON format for details
clear W clear the downlink queue of device <id>
dev.<id>.queue.ch<n> <val> W add a frame to the downlink queue of device <id> with Cayenne-encoded data for setting channel <n> to <val>. Possible values depend on the channel's type. Make sure the channel's type is set before writing this datapoint. The packet will be sent using the default transmission parameters. Datapoint available only if Cayenne data format is enabled on this device
dev.<id>.queue.size <n> R number of downlink frames in the device's queue
dev.<id>.error.tx NONE R last downlink for device <id> was sent correctly to the gateway
<err_code> R the gateway responded with the reported error code to the last downlink request for device <id>. Possible values are "TOO_LATE", "TOO_EARLY", "COLLISION_PACKET", "COLLISION_BEACON", "TX_FREQ", "TX_POWER", "GPS_UNLOCKED"
dev.<id>.error.data 0 R data in the last frame received from device <id> was processed correctly. Datapoint available only if Cayenne data format is enabled on this device
1 R error processing data in the last frame received from device <id>. Datapoint available only if Cayenne data format is enabled on this device

Downlink frame JSON format

Datapoint "dev.<id>.queue" accepts as value a JSON object with the following attributes:

  • data: hexadecimal representation of the data bytes (as string) or JSON object with Cayenne fields:
    • channel: Cayenne channel number
    • type: Cayenne channel type
    • value: Cayenne channel value
  • port: port number to send the data to
  • attempts: number of attempts made to deliver the frame to the gateway before discarding it
  • txpk: JSON object with the metadata fields to include in the downlink packet:
    • codr: Coding rate
    • datr: Data rate
    • powe: Power
    • rfch: RF chain
    • For additional fields see here

Other than "data", all additional attributes are optional. When not specified, default values, based on the device's settings and on the last received packet, will be used .

Example 1 (spaces added for readability): 

{
    "data": "aa330b",
    "port": 7,
    "attempts": 5,
    "txpk" : {
        "codr": "4/5",
        "powe": 14,
        "datr": "SF7BW125",
        "rfch":0
    }
}

Example 2: 

{
    "data": "020304aa330bff",
    "port": 5
}

Example 3: 

{
    "data": {
        "channel": 6,
        "type": 3,
        "value": 23.14
    },
    "attempts": 2
}

Cayenne LLP format

Type value Type description Value format
0 digital input 0 or 1
1 digital output 0 or 1
2 analog input signed decimal number with 0.01 resolution
3 analog output signed decimal number with 0.01 resolution
101 illuminance sensor integer value in Lux
102 presence sensor 0 or 1
103 temperature sensor signed decimal value in °C with 0.1 resolution
104 humidity sensor unsigned decimal value in % with 0.5 resolution
113 accelerometer [x, y, z] where x, y and z represent the acceleration on each axis. They are signed decimal values in G with 0.001 resolution
115 barometer unsigned decimal value in hPa with 0.1 resolution
134 gyrometer [x, y, z] where x, y and z represent the rotation on each axis. They are signed decimal values in °/s with 0.01 resolution
136 GPS location [latitude, longitude, altitude] where latitude and longitude are signed decimal values in ° with 0.0001 resolution and altitude is a signed decimal value in meters with 0.01 resolution

Release Notes

3.8.0

  • added "downlinkpower" I/O server option
  • fixed license limits check when I/O server restarts
  • fixed bug affecting devices with disabled frame-counter validation upon uplink counter roll-over

3.7.0

  • initial release


LoRaWAN is a registered trademark of LoRa Alliance.

Semtech is a registered trademark of Semtech Corporation.

Retrieved from "https://wiki.hsyco.com/3.8/index.php?title=LoRaWAN&oldid=10473"