API Reference
The Application REST APIs allow system administrators and Application Providers to send downlinks and Register/Activate/Deactivate Devices for an Application. An API key is required to authenticate API usage. API keys are created and managed in the API Keys view.
Response messages are JSON-formatted.
To get started with the Application APIs, see the Swagger API Documentation.
Uplink API
Device uplink messages heard by one or more gateways are relayed to the network server which in turn server securely forwards the data to an IoT platform.
For mor information on the data streaming endpoint implementation, see the Swagger Data Stream Documentation.
Application Payload
In addition to streaming the payload data (pdu), network information is included. Optionally, RF information about each transmission can be added by enabling "Include RF Data" in the notification target's configuration.
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:
{
"Key":"String Value",
"Key": Numeric Value
}
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. Duplicate uplinks are also available on Production with a Contract.
All JSON-formatted data contains the following default fields:
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 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 |
| 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
Example:
{
"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"
}
Batching
Batching is the process of delaying the forwarding of a notification to see if it can be grouped with other notifications going to the same endpoint. Batching is more efficient for both the Network Server and for the Customer's endpoint. Many messages can be transferred in the same time that it takes to transfer a single message.
JSON Format:
Example: Batching Disabled.
Each notification is forwarded northbound to the customer individually using the JSON object model.
{"snr": 9.25, "devEui": "000000000000000A", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.721Z", "joinId": 10, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -57, "value1": 239, "value2": 18, "port": 1, "freq": 913.3, "pdu": "01080100EF020012", "channel": 55, "seqno": 74503}
Example: Batching Enabled.
A set of notifications received by the Network Server (within a few milliseconds of each other) are forward to the customer in a JSON Array.
[
{"snr": 9.25, "devEui": "000000000000000A", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.721Z", "joinId": 10, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -57, "value1": 239, "value2": 18, "port": 1, "freq": 913.3, "pdu": "01080100EF020012", "channel": 55, "seqno": 74503},
{"snr": 8.75, "devEui": "000000000000000B", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.722Z", "joinId": 1, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -61, "value1": 239, "value2": 18, "port": 1, "freq": 907.9, "pdu": "01080100EF020012", "channel": 28, "seqno": 23423},
{"snr": 9.25, "devEui": "000000000000000C", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.723Z", "joinId": 2, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -55, "value1": 239, "value2": 18, "port": 1, "freq": 913.5, "pdu": "01080100EF020012", "channel": 56, "seqno": 34532},
{"snr": 8.75, "devEui": "000000000000000E", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.724Z", "joinId": 1, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -61, "value1": 247, "value2": 18, "port": 1, "freq": 907.7, "pdu": "01080100F7020012", "channel": 27, "seqno": 76453},
{"snr": 10.75, "devEui": "000000000000000F", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.725Z", "joinId": 1, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -60, "value1": 247, "value2": 18, "port": 1, "freq": 902.5, "pdu": "01080100F7020012", "channel": 1, "seqno": 18743}
]
When batching is enabled, if only one message is available to be forwarded, it will still be forwarded using the batch format.
[
{"snr": 9.25, "devEui": "000000000000000A", "datarate": 3, "dup": false, "txtime": "2020-10-19T18:58:42.721Z", "joinId": 10, "gwEui": "FFFFFFFFFFFFFFFF", "rssi": -57, "value1": 239, "value2": 18, "port": 1, "freq": 913.3, "pdu": "01080100EF020012", "channel": 55, "seqno": 74503}
]
Downlink API
Senet provides a simple API for sending Application downlinks to devices. In addition to the Application Payload, users can specify the LoRa-level FPort and Confirmed settings, as well as a timeout threshold for how long the Network waits until foregoing transmission or receiving acknowledgement when expected. Downlink queues support up to 3 downlinks and are cleared in one of the following ways: transmission, timeout, a newer downlink request with the 'clear' parameter set 'True', or a separate request to the Clear Downlinks API.
Notifier endpoint implementations can leverage the Downlink API in numerous ways. For example, a downlink POST request is automatically triggered in response to an uplink notification. With low-enough round-trip time between the Notifier and its endpoint, including the 'immediate' parameter set to 'True' in the downlink request ensures the Network will send it against one of the current uplink's receive windows.
When Downlink requests are successful, the response will include a unique-, numeric message identifier ('msgId'). This is distinct from the sequence number (FCntDn) allocated when a downlink is sent, allowing traceability of specific downlink Application payloads.
All Downlink API requests require an authorization key passed either as a URL parameter or in an authorization header. Senet API keys are 44-character alpha-numeric strings with a prefix of either “AK2:” or “AK3:”. See API Key Management for more information about acquiring API Authorization Keys.
Resource URL
https://api.senetco.io/rest/integration/device/sendmsg
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| eui | Device's IEEE EUI-64 identifier. | Yes | Hexadecimal String | |
| pdu | Application payload to send. | Yes | Hexadecimal String | |
| port | LoRaWAN FPort to use in Downlink's MACPayload. | No | 1 | 1-254 |
| confirmed | Flag indicating Device must acknowledge receipt of this downlink. | No | false | true or false |
| timeoutMinutes | Minutes the Network waits until foregoing downlink transmission or receiving acknowledgement when expected. | No | 5 | Positive Integer |
| clear | Flag to forego previously queued downlinks and service this downlink request. | No | false | true or false |
| immediate | Flag indicating downlink should be sent against current uplink and not queued for the next. | 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 was 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 accessed could not be found. |
Curl Example
curl -H "authorization: <API_KEY>" -X POST "https://api.senetco.io/rest/integration/device/sendmsg?eui=AAAAAAAAAAAAAAAA&pdu=0102030405060708090a0b0c0d0e0f&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 Base Stations 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 |
| 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 accessed could not be found. |
Curl Example
curl -H "authorization: <API_KEY>" -X POST "https://api.senetco.io/rest/integration/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://api.senetco.io/rest/integration/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 accessed could not be found. |
Curl Example
curl -H "authorization: AK2:APIKEY" -X POST "https://api.senetco.io/rest/integration/device/clearmsgs?devEui=AAAAAAAAAAAAAAAA&msgId=00001"
{
"clearedIds":[00001]}
}
Device Onboarding APIs
Senet offers a series of APIs that are used to automate the process of onboarding Devices onto the Senet Network, and facilitate the management of these Devices throughout their lifecycle. The onboarding process encompasses the Registration of Devices (loading the DevEUI/RootKey(s) onto the Join Server), followed by the Activation of those Devices (authorizing the DevEUIs to Join the network). Devices may be Deactivated once they have Joined the network or prior to Joining the network, in which case a Join attempt will be prevented. Devices that Joined the network in a Deactivated state and continue to communicate on the network, remain in a billable state until the Device is no longer communicating or is forced to re-Join the network.
The APIs were architected with the expectation the onboarding workflows are used for bulk transactions, such that the Registration, Activation and Deactivation calls would apply to a large number of Devices. To validate the completion of the workflow, calling the Task Status API is required to verify that the requested operation completes successfully prior to initiating another job request. Only one job request can run at a time per Application. Additional API calls initiated prior to the completion of a running job will result in a failure.
The Registration of 1,000 Devices would typically take around 1 second, while Registration of 10,000 Devices completes in less than 5 seconds. Activation of 1,000 Devices will take around 5 seconds and it is expected that Activation of 10,000 Devices will complete in under 40 seconds.
- Please see Overview in Device Management for detailed information on the Device Registration LifeCycle along with associating Contracts and other metadata to each Device.
Device Registration API
The first step in the onboarding process, Registration accomplishes the following: - Provisions the Device EUI to Root Key(s) mappings to the appropriate Join Server. - Initial Customer Contract association for and billing. - Initial assignment of the Device Profile for LoRaWAN management. Note: Registration of a Device does not transition it to an active billing state.
Note: If "Do Not Set" is selected for either Contract or Device Profile during Registration, these may set during Activation.
Note: Registration requests must be submitted with a security token. Refer to Device Registration for information about obtaining a token.
Because Registration may involve large amounts of data, this API works in conjunction with the Task Status API: responses to successful Registration requests contain a Task Job ID that can be used to monitor the progress of the Registration task. Although only one task can run per Application, Senet recommends ensuring previous operations are complete prior to initiating a new Device Management job.
Resource URL
https://api.senetco.io/rest/integration/device/register
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| token | Value required to authenticate the Registration request. | Yes | Six digit number | |
| appEui | Application's IEEE EUI-64 identifier. | No | Application associated with the API key | Hexadecimal String |
| joinEui | Join Server's IEEE EUI-64 identifier. | No | Default Join Server for the Application | Hexadecimal String |
| contractId | Contract ID to be associated with the Devices being registered. | No | Integer | |
| profId | Device Profile assigned to the Devices being registered. | No | Integer | |
| tags | One or more human-readable strings - separated by commas - used to identify and organize the Devices being registered. | No | Comma separated Strings |
Data Object
| Field | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| devEui | The IEEE EUI-64 identifier for the Device. | Yes | Hexadecimal String | |
| appKey | The Device's AES-128 root key used to derive session keys (Application Key). | Yes | Hexadecimal String | |
| lat | The Device's latitude in decimal degrees. | No | Float | |
| lng | The Device's longitude in decimal degrees. | No | Float | |
| tags | Informational tag(s) for the Device. | No | Comma separated list of Strings | |
| metadata | Custom information for the Device. | No | String | |
| devType | The type of the Device. | No | Senet supported type String |
{
"data":[
{
"devEui":"123000000000ABC0",
"appKey":"123AAAAAAAAAAAAAAAA000000000ABC0",
"lat":40.7484445,
"lng":-73.9878584,
"tags":"tag1",
"devType":"WATER_SENSOR"
},
{
"devEui":"123000000000ABC1",
"appKey":"123AAAAAAAAAAAAAAAA000000000ABC1"
}
]
}
Curl Example
curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -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/register?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. An Activated Device may join the network and start uplinking.
Note: Activating a Device transitions it to an active billing state.
Because Activation may involve large amounts of data, this API works in conjunction with the Task Status API: responses to successful Activation requests contain a Task Job ID that can be used to monitor the progress of the Activation task. Although only one task can run per Application, Senet recommends ensuring previous operations are complete prior to initiating a new Device Management job.
Bulk Activation
Resource URL
https://api.senetco.io/rest/integration/device/activate
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| appEui | Application's IEEE EUI-64 identifier. | No | Application associated with the API key | Hexadecimal String |
| joinEui | Join Server's IEEE EUI-64 identifier. | No | Default Join Server for the Application | Hexadecimal String |
| contractId | Contract ID to be associated with the Devices being activated. | No | Integer | |
| profId | Device Profile assigned to the Devices being activated. | No | Integer | |
| tags | One or more human-readable strings - separated by commas - used to identify and organize the Devices being registered. | No | Comma separated Strings |
Data Object
| Field | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| devEui | The IEEE EUI-64 identifier for the Device. | Yes | Hexadecimal String | |
| lat | The Device's latitude in decimal degrees. | No | Float | |
| lng | The Device's longitude in decimal degrees. | No | Float | |
| tags | Informational tag(s) for the Device. | No | Comma separated list of Strings | |
| metadata | Custom information for the Device. | No | String | |
| devType | The type of the Device. | No | Senet supported type String |
{
"data":[
{
"devEui":"123000000000ABC0",
"lat":40.7484445,
"lng":-73.9878584,
"tags":"tag1",
"devType":"WATER_SENSOR"
},
{
"devEui":"123000000000ABC1"
}
]
}
Curl Example
curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -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"
}
Individual Activation
Resource URL
https://api.senetco.io/rest/integration/device/activateOne
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| appEui | The IEEE EUI-64 identifier for the Application. | No | Application associated with the API key | Hexadecimal String |
| joinEui | The IEEE EUI-64 identifier for the Join Server. | No | Default Join Server for the Application | Hexadecimal String |
| contractId | The Contract Id assigned to the Activated Device. | No | Integer | |
| profId | The Device Profile Id assigned to the Activated Device. | No | Integer | |
| tags | Informational tags added to the Activated Device. | No | Comma separated Strings | |
| metadata | Custom information for the Device. | No | String | |
| lat | The Device's latitude in decimal degrees. | No | Float | |
| lng | The Device's longitude in decimal degrees. | No | Float | |
| devType | The type of the Device. | No | Senet supported type String |
Curl Example
curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -X POST "https://api.senetco.io/rest/integration/device/activateOne?appEui=<application>&joinEui=<joinSvr>&contractId=<contract>&devEui=0A00000012000002&devType=WATER_SENSOR&tags=test1,test2&lat=42.356959&lng=-71.053271"
Response Example
{
"message":"Device successfully Activated"
}
Device Deactivation API
Deactivated Devices cannot join or rejoin the Network. Previously joined Devices that are Deactivated will continue uplinking in the context of their previously established security session
Note: Deactivated Devices that continue communicating on the Network are in an active billing state. The Network must not hear Deactivated Devices for a complete billing cycle to prevent billing.
Because Deactivation may involve large amounts of data, this API works in conjunction with the Task Status API: responses to successful Deactivation requests contain a Task Job ID that can be used to monitor the progress of the Deactivation task. Although only one task can run per Application, Senet recommends ensuring previous operations are complete prior to initiating a new Device Management job.
Resource URL
https://api.senetco.io/rest/integration/device/deactivate
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| appEui | Application's IEEE EUI-64 identifier. | No | Application associated with the API key | Hexadecimal String |
| joinEui | Join Server's IEEE EUI-64 identifier. | No | Default Join Server for the Application | Hexadecimal String |
| contractId | Contract ID to be associated with the Devices being Deactivated. | No | Integer | |
| profId | Device Profile assigned to the Devices being Deactivated. | No | Integer |
Data Object
| Field | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| devEui | The IEEE EUI-64 identifier for the Device. | Yes | Hexadecimal String |
{
"data":[
{
"devEui":"123000000000ABC0"
},
{
"devEui":"123000000000ABC1"
}
]
}
Curl Example
curl -H "authorization: <API_KEY>" -H "Content-Type: application/json" -d '{"data":[{"devEui":"0A00000012000001"},{"devEui":"0A00000012000002"}]}' "https://api.senetco.io/rest/integration/device/deactivate?appEui=<application>&joinEui=<joinSvr>&contractId=<contract>"
Response Example
{
"statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevMgmtJobReq:00000000000100E0"
}
Device Update API
Update fields of Devices that have joined on the managed Application. The Devices' latitude, longitude and tags fields can be edited. Tags in the update can append, replace or delete existing tags based on the selected operation. The tags can be specified for individual Devices in the JSON data or for the full set of Devices in the request by using the tags parameter. The latitude and longitude values in the JSON will always replace the existing Device data.
Only one task per Application is allowed to run at the same time. 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 the Application. | Yes | Hexadecimal String | |
| profId | The Device Profile Id assigned to the Devices. | No | Integer | |
| tagsOperation | The action performed against the existing Device tags (only required if tags are updated). | Yes | APPEND, REPLACE or DELETE | |
| tags | Informational tags applied to the Devices. | No | Comma separated list of Strings |
Data Object
| Field | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| devEui | The IEEE EUI-64 identifier for the Device. | Yes | Hexadecimal String | |
| lat | The Device's latitude in decimal degrees. | No | Float | |
| lng | The Device's longitude in decimal degrees. | No | Float | |
| tags | Informational tag(s) for the Device. | No | Comma separated list of Strings | |
| metadata | Custom information for the Device. | No | String | |
| devType | The type of the Device. | No | Senet supported type String | |
| devClass | The classification of the Device, either Class A, B, or C. | No | CLASS_A or CLASS_B or CLASS_C | |
| fwVer | The firmware version of the Device. | No | String |
{
"data":[
{
"devEui":"123000000000ABC0",
"lat":43.0775992,
"lng":-70.7596765,
"tags":"tag1;tag2",
"devType":"WATER_SENSOR",
"devClass":"CLASS_B",
"fwVer" : "1.0.0"
},
{
"devEui":"123000000000ABC1",
"lat":40.7484445,
"lng":-73.9878584,
"tags":"tag1",
"devType":"WATER_SENSOR",
"devClass":"CLASS_C",
"fwVer" : "1.0.0"
}
]
}
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","devType":"WATER_SENSOR","devClass":"CLASS_B","fwVer":"1.0.0"},{"devEui":"123000000000ABC1","lat":40.7484445,"lng":-73.9878584,"tags":"tag1","devType":"WATER_SENSOR","devClass":"CLASS_C","fwVer":"1.0.0"}]}' -X POST "https://api.senetco.io/rest/integration/device/update?appEui=00000000000100E0&tagsOperation=APPEND"
Response Example
{
"statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevUpdateJobReq:00000000000100E0"
}
Device Export API
Export Device data from the managed Application. The data returned from the API is formatted for a CSV file.
Resource URL
https://api.senetco.io/rest/integration/device/csvExport
HTTP Method
GET
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| appEui | The IEEE EUI-64 identifier for the Application | No | Application used to generate API key | Hexadecimal String |
| fields | A filter to limit the columns in the exported data | No | devEui, contract, tags, state, lastHeardFrom | Comma separated list of Device fields |
| state | A filter to export Devices based on their current state | No | ALL | ALL, REGISTERED, ACTIVATED, DEACTIVATED, or JOINED |
| psrDays | The number of days to export PSR data | No | No PSR data | Integer value between 1 and 31 |
| contractId | A filter to export Devices for a specific contract ID | No | None | Long value |
| devEuis | A list of comma separated Device EUIs to retrieve | No | None | Comma separated list of Hexadecimal Strings |
Device Fields
The following Device fields can be used with the 'fields' parameter:
devEui, contract, tags, metadata, state, registrationDate, activationDate, deactivationDate, lastHeardFrom, lastJoinTime, firstJoinTime, yestBstns, yestPsr, yestAvgRssi, yestAvgSnr, lat, lng, profId,devType, devAddr, estLat, estLng, txPeriod, txPower, curDr, adrChg, fwVer, serviceMetrics, metricA, metricB, metricC, joinEui
Curl Example
curl -H "authorization: <API_KEY>" "https://api.senetco.io/rest/integration/device/csvExport?fields=devEui,contract,tags,state,registrationDate,activationDate,deactivationDate,lastHeardFrom" > device_export.csv
Response Example
Dev EUI,Contract,Tags,State,Registration Date,Activation Date,Deactivation Date,Last Heard From
123000000000ABC0,99,,ACTIVATED,03/31/2017 11:37:30 PM UTC,03/31/2017 11:37:30 PM UTC,,04/03/2018 01:54:02 PM UTC
123000000000ABC1,99,,ACTIVATED,03/31/2017 11:25:49 PM UTC,03/31/2017 11:25:49 PM UTC,,04/03/2018 00:27:38 PM UTC
123000000000ABC2,99,,ACTIVATED,03/31/2017 11:04:48 PM UTC,03/31/2017 11:04:48 PM UTC,,09/25/2019 09:38:10 AM UTC
Service Metric Data Curl Example
curl -H "authorization: <API_KEY>" "https://api.senetco.io/rest/integration/device/csvExport?appEui=00250C000001BEEF&contractId=2&fields=devEui,contract,tags,state,registrationDate,activationDate,deactivationDate,lastHeardFrom,serviceMetrics" > service_metric_data.csv
Service Metric Data Response Example
Dev EUI,Contract,Tags,State,Registration Date,Activation Date,Deactivation Date,Last Heard From,Metric A,Metric B,Metric C
00250C0100000302,2,"Test,tag1,tag22",ACTIVATED,10/22/2017 04:00:00 AM UTC,09/03/2019 09:04:37 PM UTC,09/03/2019 09:04:07 PM UTC,07/07/2020 02:39:46 PM UTC,80,100,100
Device Transfer API
Devices may be transferred between Accounts, specifically between Applications. Transfer between Applications belonging to the same Account is also supported.
The response to a successful Device Transfer request contains a job status URL which in turn can be used to check the progress of the transfer task. Task Status API for more information.
All Transfers are constrained by or require the following:
- Only one task per Application may run at a time.
- An API key with sufficient access for the source and as well as the destination Application. These API keys must be included in the HTTP Header as fields: Authorization (source) and Authorization2 (destination).
- The destination Application must support the Join Server(s) associated with the Devices being transferred.
- The destination Account must have access to identified Contract and Device Profile to be used by the transferred Devices.
Resource URL
https://api.senetco.io/rest/integration/device/transfer
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| fromAppEui | The IEEE EUI-64 identifier for the current Application. | Yes | Hexadecimal String | |
| toAppEui | The IEEE EUI-64 identifier for the new Application. | Yes | Hexadecimal String | |
| contractId | The contract ID to assign to the Devices when they are moved to the new Application. | Yes | Positive Integer | |
| profId | The Device Profile ID to assign to the Devices when they are moved to the new Application. | No | Application Default | Positive Integer |
Data Object
| Field | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| devEui | The IEEE EUI-64 identifier for the Device. | Yes | Hexadecimal String |
{
"data":[
{
"devEui":"123000000000ABC0"
},
{
"devEui":"123000000000ABC1"
}
]
}
Response
| Field | Description |
|---|---|
| message | Message indicating the status or error of the API request in plaintext. |
| Code | Reason | Description |
|---|---|---|
| 200 | Success | Request was successfully processed. |
| 403 | Authorization failure | Access to this resource was rejected due to an authorization issue. |
| 400 | Bad Request | Invalid request due to insufficient or malformed parameters. |
| 404 | Device or Application EUI was not found | The Device being transfered or the Application it is being transfered to could not be found. |
Curl Example
curl -H "authorization: <CUR_APP_API_KEY>" -H "authorization2: <NEW_APP_API_KEY>" -H "Content-Type: application/json" -d '{"data":[{"devEui":"0A00000012000001"},{"devEui":"0A00000012000002"}]}' -X POST "https://api.senetco.io/rest/integration/device/transfer?fromAppEui=A1A1A1A1A1A1A1A1&toAppEui=A2A2A2A2A2A2A2A2&contractId=123456"
{
"statusUrl":"https://api.senetco.io/rest/integration/device/status?reqId=DevTransferJobReq:A1A1A1A1A1A1A1A1-A2A2A2A2A2A2A2A2"
}
Task Status API
Get the status of an ongoing Device Registration, Activation or Deactivation task. The Task Status API is used to confirm the preceding operation completes prior to initiating a subsequent request. The status is available for 15 minutes after the task completes.
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>" "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."
],
"stats":{
"activated":0,
"updated":0,
"notChanged":0,
"errors":1
}
},
"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. |
FUOTA API
Initiate a firmware update over the air for a set of Devices on an Application.
Resource URL
https://api.senetco.io/rest/integration/mcastTransfer
HTTP Method
POST
Parameters
| Parameter | Description | Required | Default Value | Allowed Values |
|---|---|---|---|---|
| appEui | The IEEE Application EUI identifier for the Devices to initiate the FUOTA transfer for. | Yes | Hexadecimal String | |
| devEuis | The list of IEEE Device EUIs to initiate the FUOTA transfer for. | No | Comma Separated Hexadecimal String | |
| devTags | The list of Device Tags used to initiate the FUOTA transfer for (devEuis must be empty). | No | Comma Separated Tag Names | |
| startDelaySecs | The delay in seconds before initiating the file transfer. This should include enough time for the network server to configure all Devices for the FUOTA transfer. | Yes | Positive Integer | |
| txChnl | The channel to use when transmitting the multicast fragments to the Devices. | No | RX2 Channel | Positive Integer, Valid Channel For Regional ISM Band |
| txDr | The datarate to use when transmitting the multicast fragments to the Devices. | No | RX2 DR | Positive Integer, Valid Datarate For Regional ISM Band |
| contractId | The Contract ID to use for billing when transferring the multicast fragments to the Devices. | Yes | Positive Integer, Valid Contract ID for Application | |
| fragAlg | The algorithm to use to fragment the file. | Yes | FWD_ERR_CORR | |
| devClass | The class of the multicast session. | No | C | B/C |
| redundancy | The amount of file redundancy to use when building the fragments to send. 1.0 = 100%. | Yes | Double value from 0 – 1.0. | |
| millisBetweenPkts | The number of milliseconds to force to wait between packet sends. This is here for Devices that take longer to write fragments. | No | 5000 | Positive Integer |
| descriptor | The 4 byte file descriptor field required by FUOTA to describe the firmware image to the Device receiving it. | No | 00000000 | Hexadecimal String |
| "Request Body" | The binary file to multicast to all the Devices. | Yes | A firmware file to send to Devices. |
Curl Example
curl -H "authorization: <API_KEY>" --insecure -X POST -F "file=@patch-to_new.bin" "https://api.senetco.io/rest/integration/mcastTransfer?appEui=00000000000100E0&devEuis=123000000000ABC0,123000000000ABC1&devClass=C&txChnl=7&txDr=13&startDelaySecs=120&fragAlg=FWD_ERR_CORR&redundancy=1.0&millisBetweenPkts=4000&contractId=20"
Response Example
{
"jobId":"MCastXferJobReq:00000000000100E0",
"responseMsg":"MCastXferJobReq job starting in: 00:01:59",
"statusCode":200
}