API Reference

SenRa offers a variety of methods to stream device messages transmitted over the SenRa Network.

---

Overview

Uplink Messages

Devices transmit an uplink message to one or more gateways that relays the message to the network server. The network server forwards the message to an IoT platform.

Downlink Messages

IoT platforms make calls to the network server. The network server sends each downlink message to a single gateway that transmits the message to a single device.

Notification Targets

Data streaming is setup by creating a Notification Target for a devices. The Notification Target configures the network server to stream device uplinks to a user specified destination or 3rd party IoT platform. In other words, uplink messages are forwarded as they are received by the SenRa Network.

Configure a Notification Target:

1. Open the Edit Device window.

   • Table View: Select a row in the device table. Click on the edit button .

   • Tile View: Click on the menu button . Click on the edit button .

   • Device Details: Click on the edit button .

   

2. Click on the NOTIFICATION TARGET tab.
   
   
   
   

3. In the Forward To dropdown menu, choose a Notification Target type to display the required fields and options.

4. Complete the required fields and click Save.

Supported Notification Targets

The SenRa Network supports a variety of options to forward messages as they are received by the network. Options may be to forward messages to a private socket listener or a public subscription based analytics solution. By Default, only the packet with the best Signal to Noise Ratio (SNR) will be forwarded. To receive packets received by multiple gateways (Duplicate Packets) enable “Include Duplicate Uplinks” when setting up the notification target.

For a list of the supported notifications targets and configurations use the drop-down API menu above.

Consecutive Errors

Notification Targets that produce 10 consecutive errors when forwarding data will be disabled by the network server. This is to prevent excessive load on the target and on the network server. A short outage in network connectivity should not trigger the 10 consecutive error limit on most devices. However, if your device has a very short transmit interval, it may be possible to reach the 10 consecutive error limit in a very short period of time. If your Notification Target is disabled by the network server, review the Last Error message field in the device details. This error message will help you understand why the notifications are failing. If you believe the errors were caused by an interruption in service that has now been corrected, you can re-enable the Notification Target to restore message forwarding. If the error condition persists, the Notification Target will again be disabled when the error limit is reached.

---

Uplink API

The SenRa Network receives payload data from devices via one or more gateways that receive the transmission. In addition to streaming the payload data (pdu), network information is also included. The data is formatted using JSON and contains the following default fields. Optional RF fields can also be added by enabling "Include RF Data" in the notification target.

The SenRa Network supports the standard JSON object model where each object contains one-to-many key/values pairs. The JSON object is in the following format:

{
   "Key":"String Value",
   "Key": Numeric Value
}

Fields

FieldName	DataType	Category	Description
devEui	String	Default	64-bit Extended Unique Identifier of the Device transmitting the message
gwEui	String	Default	64-bit Extended Unique Identifier of the Base Station that received the message. Without Duplicates included this identifies Base Station that first relayed the message, though not necessarily the one preferred for downlink communication.
joinId	Number	Default	Incrementing Integer used to Identify the last join
pdu	String	Default	Protocol Data Unit or Customer Payload data
port	Number	Default	0 indicates that the FRMPayload contains MAC commands only and 1..223 are application specific
seqno	Number	Default	Incrementing Integer used to Identify an uplink
txtime	String	Default	Time the message was received by the Network Server
channel	Number	RF Field	Frequency Channel of the transmission
datarate	Number	RF Field	Integer that maps to a spreading factor, bandwidth and bitrate
freq	Number	RF Field	Transmit Frequency in MHz
rssi	Number	RF Field	Received Signal Strength Indicator reported by receiving Gateway
snr	Number	RF Field	Average Signal to Noise Ratio reported by receiving Gateway
ismBand	String	RF Field	The ISMBand (US915,EU868,EU433,CN779,AU915,CN470, etc) reported by the receiving Gateway
maxPayload	Number	RF Field	Max Payload size in bytes that can be sent at the current datarate by this Device
appEui	String	Optional	The Application's IEEE EUI-64 identifier.
ack	Boolean	Optional	Flag indicating if the uplink was acknowledging the receipt of a downlink
ackDnMsgId	Number	Optional	When present, indicates that a Device has acknowledged a specific downlink message ID
devClass	String	Optional	LoRaWAN Class designation ("A", "B", "C") of the Device
devType	String	Optional	The type of the Device
dup*	Boolean	Optional	Flag indicating if the uplink was already forwarded because it was heard by multiple Gateways
estLat*	Number	Optional	Estimated latitude of the Device in decimal degrees
estLng*	Number	Optional	Estimated longitude of the Device in decimal degrees
cfgLat	Number	Optional	Configured latitude of the Device in decimal degrees
cfgLng	Number	Optional	Configured longitude of the Device in decimal degrees
tags	String	Optional	A comma separated list of tags configured on this device
metadata	String	Optional	The metadata value configured on this Device
devProfile	String	Optional	The name of the Profile applied to this Device
fwVersion	String	Optional	The firmware version of this Device
gwRxTime	String	Optional	Time the message was received by the Gateway

* Requires contractual agreement in Production

Example with Payload Fields:

{
   "ack":true,
   "ackDnMsgId": 100000,
   "devClass": "A" ,
   "devEui":"FFFFFFFFFFFFFFFF",
   "gwEui":"AAAAAAAAAAAAAAAA",
   "joinId":216,
   "pdu":"01000016D7011400060E06",
   "port":1,
   "seqno":1,
   "txtime":"2017-02-09T12:38:38.375Z"

}

Example with RF Fields:

{
   "ack":true,
   "channel":64,
   "datarate":4,
   "devEui":"FFFFFFFFFFFFFFFF",
   "freq":903,
   "gwEui":"AAAAAAAAAAAAAAAA",
   "joinId":209,
   "pdu":"01000016D7011400060E06",
   "port":1,
   "rssi":-77,
   "seqno":1,
   "snr":10,
   "ismBand":"US915",
   "maxPayload":242,
   "txtime":"2017-02-09T11:35:44.384Z"
}

---

Downlink API

SenRa provides a simple API for sending downlinks to devices on the SenRa Network using HTTP POST. The Downlink API can be leveraged by a Notifier endpoint where in response to receiving uplinks, downlinks are automatically submitted to the downlink queue. All API requests require an authorization key passed either as a parameter or in an authorization header of a Curl command. SenRa API keys are 44-character alpha-numeric strings with a prefix of either “AK2:” or “AK3:”.

Implementing the Downlink API

The SenRa Downlink API is available to all Portal users. It is implemented as a standard parameterized URL.

1. Click on the username in the top-right corner.

2. From the dropdown menu, select Edit Account Info.

   

3. Click on the Generate API Key button on the right side under Developer API Key to generate and display a new API Key.

   

4. Copy the key, storing it securely and safely: this key uniquely identifies the user's account to the Portal. All incoming API calls must be validated with this key in conjunction with registered devices and gateways.

5. Using the API Key and parameterized URL described below, downlinks can now be sent to the user's devices with the Downlink API. In the examples below, the "<API_KEY>" value should be replaced with the generated key.

Resource URL

https://portal.senraco.io/rest/current/device/sendmsg

HTTP Method

POST

Parameters

Parameter	Description	Required	Default Value	Allowed Values
eui	The IEEE EUI-64 identifier for the LoRa Device.	Yes		Hexadecimal String
pdu	The PDU to send to the Device.	Yes		Hexadecimal String
port	The port (fport) to send to the Device.	No	1	1-254
confirmed	The flag to tell the receiving Device to acknowledge the reception of the PDU.	No	false	true or false
timeoutMinutes	The amount of time in minutes to allow the transaction to be sent prior to timing out the request.	No	5	Positive Integer
clear	A flag to clear the downlink queue prior to sending a message	No	false	true or false
immediate	The flag to request sending the downlink only if can be sent immediately.	No	false	true or false

Response

Field	Description
message	Message indicating the status or error of the API request in plaintext.
msgId	Message Id of the downlink being processed, only present on successful responses.

Code	Reason	Description
200	Success	Request was successfully processed.
403	Authorization failure	Access to this resource has been rejected due to an authorization issue.
400	Bad Request	Invalid request due to insufficient or malformed parameters.
404	Device EUI was not found	The device being access could not be found.

Curl Example:

        curl -H "authorization: <API_KEY>" -X POST "https://portal.senraco.io/rest/current/device/sendmsg?eui=FFFFFFFFFFFFFFFF&pdu=0102&confirmed=true&port=88&timeoutMinutes=2"

{  
   "message":"Success!",
   "msgId":119
}

---

Downlink API - Multicast

Send multicast downlink messages to a multicast session allowing a user specified list of gateways to transmit on.

Resource URL

https://portal.senraco.io/rest/current/device/sendmcastmsg

HTTP Method

POST

Parameters

Parameter	Description	Required	Default Value	Allowed Values
addr	The IEEE device address identifier for the LoRa device that holds the session keys.	Yes		Hexadecimal String
pdu	The PDU to multicast to the device(s).	Yes		Hexadecimal String
port	The port (fport) to send to the device.	No	1	1-254
bstnEuis	The comma separated list of gateway EUIs to have broadcasting the multicast PDU.	Yes		Comma Separated Hexadecimal String

Response

Field	Description
message	Message indicating the status or error of the API request in plaintext.
msgId	Message Id of the downlink being processed, only present on successful responses.

Code	Reason	Description
200	Success	Request was successfully processed.
403	Authorization failure	Access to this resource has been rejected due to an authorization issue.
400	Bad Request	Invalid request due to insufficient or malformed parameters.
404	Device EUI was not found	The device being access could not be found.

Curl Example

curl -H "authorization: <API_KEY>" -X POST "https://portal.senraco.io/rest/current/device/sendmcastmsg?addr=12FFFFFF&pdu=0102030405060708090a0b0c0d0e0f&bstnEuis=AAAAAAAAAAAAAAAA,AAAAAAAAAAAAAAAB"

{  
   "message":"Success!",
   "msgId":119
}

Downlink API - Clear Downlinks

Clears queued downlink messages. If a specific message ID is supplied, only that downlink will be cleared, otherwise all queued messages are cleared.

Resource URL

https://portal.senraco.io/rest/current/device/clearmsgs

HTTP Method

POST

Parameters

Parameter	Description	Required	Default Value	Allowed Values
eui	The IEEE EUI-64 identifier for the LoRa device.	Yes		Hexadecimal String
msgId	Optional message ID of the downlink to clear. If not specified, all will be cleared.	No		Positive Integer

Response

Field	Description
msgId	List of the message IDs cleared from the downlink queue.

Code	Reason	Description
200	Success	Request was successfully processed.
403	Authorization failure	Access to this resource has been rejected due to an authorization issue.
400	Bad Request	Invalid request due to insufficient or malformed parameters.
404	Device EUI was not found	The device being access could not be found.

Curl Example

curl -H "authorization: <API_KEY>" -X POST "https://portal.senraco.io/rest/current/device/clearmsgs?devEui=AAAAAAAAAAAAAAAA&msgId=00001"

{  
   "clearedIds":[00001]}
}