Difference between revisions of "LoRaWAN"

From HSYCO
Jump to navigation Jump to search
Line 346: Line 346:
 
=== 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''': value for the specified Cayenne channel
+
** '''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 made to deliver the frame to the gateway before discarding it
 
* '''attempts''': number of attempts made to deliver the frame to the gateway before discarding it
Line 358: Line 359:
 
** 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]
  
The attribute "data" or both "channel" and "value" are mandatory; if "data" is specified, "channel" and "value" are ignored. All other attributes are optional. When not specified, default values will be used based on the device's settings and on the latest received packet.
+
Other than "data", all additional attributes are optional. When not specified, default values will be used based on the device's settings and on the latest received packet.
  
 
Example 1 (spaces added for readability):
 
Example 1 (spaces added for readability):
Line 386: Line 387:
 
<pre>
 
<pre>
 
{
 
{
     "channel": 6,
+
     "data": {
    "value": 23.14,
+
        "channel": 6,
 +
        "type": 3,
 +
        "value": 23.14
 +
    },
 
     "attempts": 2
 
     "attempts": 2
 
}
 
}

Revision as of 15:04, 1 May 2019

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 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
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 will be used based on the device's settings and on the latest received packet.

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.7.0

  • initial release



LoRaWAN is a registered trademark of LoRa Alliance.

Semtech is a registered trademark of Semtech Corporation.