Difference between revisions of "LoRaWAN"
Jump to navigation
Jump to search
(→3.8.0) |
|||
| (14 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 | + | {{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 30: | Line 30: | ||
|<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 | + | Use the [[LoRaWAN Utility]] to automatically discover gateways and devices and setup communication and functional parameters. |
== Gateways Configuration == | == 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 == | == 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 188: | 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 229: | Line 242: | ||
|<val> | |<val> | ||
|R | |R | ||
| − | | | + | |LoRa SNR ratio in dB (float, 0.1 dB precision) of last valid packet received from device <id> |
|- | |- | ||
| Line 340: | Line 353: | ||
=== Downlink frame JSON format === | === Downlink frame JSON format === | ||
Datapoint "dev.<id>.queue" accepts as value a JSON object with the following attributes: | Datapoint "dev.<id>.queue" accepts as value a JSON object with the following attributes: | ||
| − | * '''data''': hexadecimal representation of the data | + | * '''data''': hexadecimal representation of the data bytes (as string) ''or'' JSON object with Cayenne fields: |
| − | * '''channel''': Cayenne channel | + | ** '''channel''': Cayenne channel number |
| − | * '''value''': | + | ** '''type''': Cayenne channel type |
| + | ** '''value''': Cayenne channel value | ||
* '''port''': port number to send the data to | * '''port''': port number to send the data to | ||
| − | * '''attempts''': number of attempts | + | * '''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: | * '''txpk''': JSON object with the metadata fields to include in the downlink packet: | ||
** '''codr''': Coding rate | ** '''codr''': Coding rate | ||
| Line 352: | Line 366: | ||
** For additional fields see [https://github.com/Lora-net/packet_forwarder/blob/master/PROTOCOL.TXT#L351 here] | ** 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): | Example 1 (spaces added for readability): | ||
| Line 380: | Line 394: | ||
<pre> | <pre> | ||
{ | { | ||
| − | "channel": 6, | + | "data": { |
| − | + | "channel": 6, | |
| + | "type": 3, | ||
| + | "value": 23.14 | ||
| + | }, | ||
"attempts": 2 | "attempts": 2 | ||
} | } | ||
| Line 468: | Line 485: | ||
== 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.
Contents
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.
