API Reference

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


Overview

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.

Uplinks

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.

Downlinks

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 Table Edit.

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

    • Device Details: Click on the edit button Device Edit.

    Edit Device

  2. Click on the NOTIFICATION TARGET tab.

    Screenshot

  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.

Note

A firewall rule may need to be added to allow incoming uplink messages from the SenRa Network.

SenRa Source IP Addresses: 35.154.228.165

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.


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:

Note

Senet may add additional fields during future Portal updates. Please ensure that your application will ignore any unknown fields and continue to parse the notification data.

{
   "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 receiving Gateway that processed the message
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 gateway
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
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

* 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,
   "txtime":"2017-02-09T11:35:44.384Z"
}



SenRa provides a simple API to programmatically send downlinks to devices on the SenRa Network via the https POST method. The Downlink API can be used to set triggers that respond to events and submit downlink messages to the downlink queue.

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

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

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

    Username

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

    Username

  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.

URL format:

The following URL format describes the parameters required to send a POST request to the Downlink API.

https://portal.senraco.io/rest/current/device/sendmsg?apikey=[Developer API Key]&eui=[EUI]&value=[Data]&confirmed=[Boolean]&port=[FPort]&timeoutMinutes=[Time in Minutes]

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.

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
}

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: AK2:APIKEY" -X POST "https://portal.senraco.io/rest/current/device/clearmsgs?devEui=AAAAAAAAAAAAAAAA&msgId=00001"
{  
   "clearedIds":[00001]}
}