API Reference
The application provider REST APIs allow system administrators to send downlinks and register/activate/deactivate devices on an application. Senet provides application administrators with an API key to authenticate API usage. If you have not received an API key from Senet, please email your request to support@senetco.com or call the technical support phone number shown on https://www.senetco.com/support/.
Response messages are JSON-formatted.
Downlink API
Send downlink messages to devices on the managed application.
Resource URL
https://api.senetco.io/rest/integration/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 |
Curl Example
curl -H "authorization: <API_KEY>" --insecure -X POST "https://api.senetco.io/rest/integration/device/sendmsg?eui=00250C010000030B&pdu=0102030405060708090a0b0c0d0e0f&confirmed=true&timeoutMinutes=2"
Response Example
{
"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://api.senetco.io/rest/integration/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 |
| confirmed | The flag to tell the receiving device to acknowledge the reception of the PDU. | No | false | true or false |
| bstnEuis | The comma separated list of gateway EUIs to have broadcasting the multicast PDU. | Yes | Comma Separated Hexadecimal String |
Curl Example
curl -H "authorization: <API_KEY>" --insecure -X POST "https://api.senetco.io/rest/integration/device/sendmcastmsg?addr=12FFFFFF&pdu=0102030405060708090a0b0c0d0e0f&bstnEuis=00250C00010186A5,00250C00010000FC"
Response Example
{
"message":"Success!",
"msgId":119
}
Uplink API
A Device transmits an uplink messages to one or more gateways that relay the message to the network server. The network server forwards the message to an IoT platform.
Application Payload
The Senet 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 Senet 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 the application ignores any unknown fields and continue to parse the notification data.
{
"Key":"String Value",
"Key": Numeric Value
}
Fields
| FieldName | DataType | Description |
|---|---|---|
| ack | Boolean | Flag indicating if the uplink was acknowledging the receipt of a downlink |
| devClass | String | LoRaWAN Class designation ("A", "B", "C") of the device |
| devEui | String | 64-bit Extended Unique Identifier of the device transmitting the message |
| gwEui | String | 64-bit Extended Unique Identifier of the receiving Gateway that processed the message |
| joinId | Number | Incrementing Integer used to Identify the last join |
| pdu | String | Protocol Data Unit or Customer Payload data |
| port | Number | 0 indicates that the FRMPayload contains MAC commands only and 1..223 are application specific |
| seqNo | Number | Incrementing Integer used to Identify an uplink |
| txtime | String | Time the message was received by the gateway |
Example:
{
"ack":true,
"devClass": "A" ,
"devEui":"FFFFFFFFFFFFFFFF",
"gwEui":"AAAAAAAAAAAAAAAA",
"joinId":216,
"pdu":"01000016D7011400060E06",
"port":1,
"seqno":1,
"txtime":"2017-02-09T12:38:38.375Z"
}
RF Fields
The following fields can be added to the payload by enabling "Include RF Data" in the the notification target editor. This is only available to a user with with administrative privileges.
| FieldName | DataType | Description |
|---|---|---|
| channel | Number | Frequency Channel of the transmission |
| datarate | Number | Integer that maps to a spreading factor, bandwidth and bitrate |
| freq | Number | Transmit Frequency in MHz |
| rssi | Number | Received Signal Strength Indicator reported by receiving gateway |
| snr | Number | Average Signal to Noise Ratio reported by receiving gateway |
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"
}
Optional Fields
The following data fields are available on Production with contractual agreement:
| FieldName | DataType | Description |
|---|---|---|
| estLat | Number | Estimated latitude of the device in decimal degrees |
| estLng | Number | Estimated longitude of the device in decimal degrees |
Duplicate uplinks are also available on Production with a contract.
Senet Packet Format
In addition to the above JSON payload types, Senet also offers an extended payload if the device implements the standard Senet Packet Format. See the Senet Packet format documentation for more details.
Device Registration API
Register new devices on the managed application. See Device Registration to learn how to request a token. Only one task can be running at a time per application. The response of a successful request is a URL to GET the status of the registration task. See Task Status API for more information.
Resource URL
https://api.senetco.io/rest/integration/device/register
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| token | Randomly generated token used for two-factor authentication. | Yes | Six digit number | |
| appEui | The IEEE EUI-64 identifier for application. | No | EUI of managed application | Hexadecimal String |
| joinEui | The IEEE EUI-64 identifier for the join server. | No | Default join server for managed application | Hexadecimal String |
| cotractId | Contract Id for the registred devices. | No | Integer | |
| profId | Device profile Id to be applied to registered devices. | No | Integer | |
| tags | Informational tags to be added to registered devices. | No | Comma separated Strings |
Message Data Object
| Feild | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| devEui | Device EUI to be registered. | Yes | Hexadecimal String | |
| appKey | Application key of device being registered. | Yes | Hexadecimal String/td> | |
| lat | Known lattitude of a device. | No | Float | |
| lng | Known longitude of a device. | No | Float |
{
"data":[
{
"devEui":"123000000000ABC0",
"appKey":"1230000000000000000000000000ABC0"
},
{
"devEui":"123000000000ABC1",
"appKey":"1230000000000000000000000000ABC1"
}
]
}
Curl Example
curl -H "authorization: <API KEY>" -H "Content-Type: application/json" --insecure -d '{"data":[{"devEui":"0A00000012000001","appKey":"0ABCDEF0120000010A00000012000001","lat":42.356959, "lng":-71.053271},{"devEui":"0A00000012000002","appKey":"0ABCDEF0120000010A00000012000002","lat":42.356779, "lng":-71.065271}]}' "https://api.senetco.io/rest/integration/device/activate?appEui=<application>&joinEui=<joinSvr>&contractId=<contract>&profId=<devProfile>&token=<token>&tags=test1,test2"
Response Example
{
"statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevMgmtJobReq:00000000000100E0"
}
Device Activation API
Activate registered or deactivated devices on the managed application. Only one task can be running at a time per application. The response of a successful request is a URL to GET the status of the activation task. See Task Status API for more information.
Resource URL
https://api.senetco.io/rest/integration/device/activate
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| appEui | The IEEE EUI-64 identifier for application. | No | EUI of managed application | Hexadecimal String |
| joinEui | The IEEE EUI-64 identifier for the join server. | No | Default join server for managed application | Hexadecimal String |
| cotractId | Contract Id for the registred devices. | No | Integer | |
| profId | Device profile Id to be applied to registered devices. | No | Integer | |
| tags | Informational tags to be added to registered devices. | No | Comma separated Strings |
Message Data Object
| Feild | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| devEui | Device EUI to be activated. | Yes | Hexadecimal String/td> | |
| lat | Known lattitude of a device. | No | Float | |
| lng | Known longitude of a device. | No | Float |
{
"data":[
{
"devEui":"123000000000ABC0"
},
{
"devEui":"123000000000ABC1"
}
]
}
Curl Example
curl -H "authorization: <API KEY>" -H "Content-Type: application/json" --insecure -d '{"data":[{"devEui":"0A00000012000001","appKey":"0ABCDEF0120000010A00000012000001","lat":42.356959, "lng":-71.053271},{"devEui":"0A00000012000002","appKey":"0ABCDEF0120000010A00000012000002","lat":42.356779, "lng":-71.065271}]}' "https://api.senetco.io/rest/integration/device/activate?appEui=<application>&joinEui=<joinSvr>&contractId=<contract>&profId=<devProfile>&token=<token>&tags=test1,test2"
Response Example
{
"statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevMgmtJobReq:00000000000100E0"
}
Device Deactivation API
Deactivate activated or registered devices on the managed application. Only one task can be running at a time per application. The response of a successful request is a URL to GET the status of the deactivation task. See Task Status API for more information.
Resource URL
https://api.senetco.io/rest/integration/device/deactivate
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| appEui | The IEEE EUI-64 identifier for application. | No | EUI of managed application | Hexadecimal String |
| joinEui | The IEEE EUI-64 identifier for the join server. | No | Default join server for managed application | Hexadecimal String |
Message Data Object
| Feild | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| devEui | Device EUI to be deactivated. | Yes | Hexadecimal String/td> |
{
"data":[
{
"devEui":"123000000000ABC0"
},
{
"devEui":"123000000000ABC1"
}
]
}
Curl Example
curl -H "authorization: <API KEY>" -H "Content-Type: application/json" --insecure -d '{"data":[{"devEui":"0A00000012000001"},{"devEui":"0A00000012000002"}]}' "https://api.senetco.io/rest/integration/device/deactivate?appEui=<application>&joinEui=<joinSvr>"
Response Example
{
"statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevMgmtJobReq:00000000000100E0"
}
Device Update API
Update the fields of devices that have joined on the managed application. The latitude and longitude fields can be edited and new tags can be added. Only one task can be running at a time per application. The response of a successful request is a URL to GET the status of the update task. See Task Status API for more information.
Resource URL
https://api.senetco.io/rest/integration/device/update
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| appEui | The IEEE EUI-64 identifier for application. | Yes | Hexadecimal String |
Message Data Object
{
"data":[
{
"devEui":"123000000000ABC0",
"lat":43.0775992,
"lng":-70.7596765,
"tags":"tag1;tag2"
},
{
"devEui":"123000000000ABC1",
"lat":40.7484445,
"lng":-73.9878584,
"tags":"tag1"
}
]
}
Curl Example
curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -d '{"data":[{"devEui":"123000000000ABC0","lat":43.0775992,"lng":-70.7596765,"tags":"tag1;tag2"},{"devEui":"123000000000ABC1","lat":40.7484445,"lng":-73.9878584,"tags":"tag1"}]}' --insecure -X POST "https://api.senetco.io/rest/integration/device/update?appEui=00000000000100E0"
Response Example
{
"statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevUpdateJobReq:00000000000100E0"
}
Task Status API
Get the status of an ongoing device registration, activation or deactivation task. The status is available for 15 minutes after the task is complete.
Resource URL
https://api.senetco.io/rest/integration/device/status
HTTP Method
GET
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| reqId | Identifier of the ongoing task. | Yes | Id String |
Curl Example
curl -H "authorization: <API_KEY>" --insecure "https://api.senetco.io/rest/integration/device/status?reqId=DevMgmtJobReq:00000000000100E0"
Response Example
{
"state":"DONE_SUC",
"result":{
"status":"Device activation on App EUI: 00000000000100E0 completed. Activated: 0 Updated: 0 Not Changed: 0 Errors: 1",
"msgs":[
"DevEUI: 1230000000000ABC has not been registered. The device cannot be activated on JoinEUI: 00000000000100E0."
]
},
"pctDone":100
}
Status Codes
200 The task specified was successfully found. The latest status is returned.
400 The reqId parameter is missing or invalid.
403 The API key is not authorized to get the status of the task.
404 No task could be found with the requested reqId.
Response Details
pctDone
Current status of the task expressed as a percentage (0 to 100).
state
Current state of the task.
| DONE_SUC | The task finished successfully. |
| DONE_FAIL | An internal server exception occurred while running the task. |
| INITIAL | The task has been created and is waiting to be queued. |
| QUEUED | The task has been queued and is waiting to be run. |
| RUNNING | The task is running. |
status
Summary of the task after completion.
| Registered | Number of devices successfully registered. |
| Activated | Number of devices successfully activated. |
| Deactivated | Number of devices successfully deactivated. |
| Updated | Number of device appKeys updated. |
| Not Changed | Number of devices in the request that did not change. |
| Errors | Number of errors that occurred. |
msgs
Messages describing any errors that occurred while running the task.
| Registration Messages | |
|---|---|
| An internal server error occurred while registering devices. <NUM_SKIPPED> devices were skipped. |
| Activation Messages | |
|---|---|
| The AppKey for DevEUI: <DEV_EUI> has been updated. Old AppKey: <APP_KEY> New AppKey: <APP_KEY>. | |
| DevEUI: <DEV_EUI> has not been registered. The device cannot be activated on JoinEUI: <JOIN_EUI>. | |
| An internal server error occurred while activating DevEUI: <DEV_EUI>. | |
| DevEUI: <DEV_EUI> has already joined on AppEUI: <APP_EUI>. The device cannot be activated on AppEUI: <APP_EUI>. | |
| DevEUI: <DEV_EUI> was already activated on AppEUI: <APP_EUI>. The device cannot be activated on AppEUI: <APP_EUI>. | |
| An internal server error occurred while activating devices. |
| Deactivation Messages | |
|---|---|
| DevEUI: <DEV_EUI> has not been registered. The device cannot be deactivated. | |
| An internal server error occurred while deactivating devices. |