Table of Contents

API guide

Push API

From WMC v3.0 Software release, the push API changed and more relevant details are provided, such as the cluster ID, device address or gwRecvTime for Message buffering (implemented for release 3.2.7).

In this page, the data is presented as a sample and with a mapping table, to ease the migration between the API versions.

Please, refer to the following screenshots to get information about PushDataUP method:

For the response, here is the information that is available :

For instance, here is the type of information received by an HTTP push server (network message detail level):

tda@dsc-tests:~$ nc -klp 8000
POST /dataUp HTTP/1.1
Host: 37.157.227.230:8000
User-Agent: Go-http-client/1.1
Content-Length: 466
Content-Type: application/json
Klk-Unsent-Dataup: true
Accept-Encoding: gzip

{"id":"5d2342ac71a1270001035042","endDevice":{"devEui":"343737394A336F09","devAddr":"24004F6B","cluster":{"id":1}},"fPort":2,"fCntDown":0,"fCntUp":6940,"adr":false,"confirmed":false,"encrypted":false,"payload":"0027800bddfd773b447bf9fede870046","recvTime":1562591916089,"ulFrequency":868.3,"modulation":"LORA","dataRate":"SF12BW125","codingRate":"4/5","gwCnt":1,"gwInfo":[{"gwEui":"7276FF0039030436","rfRegion":"EU868","rssi":-107,"snr":-7,"channel":6,"radioId":1}]}

URL Change

The URL is now appended with /dataUp (instead of rxMessage in previous versions).

So if the URL provisioned for the cluster is https://app.provider.com/xyz/ then the data will be pushed to https://app.provider.com/xyz/dataUp.

Message detail level

3 levels are available: Payload, Radio and Network.

Payload: Returns the contents of PushDataUpDto without dataUpNetworkPayload and dataUpRadioPayload.
PushDataUpDto example:

{
  "id": "5c505781bda6af0001221902",
  "endDevice": {
    "devEui": "323831387C346C22",
    "devAddr": "11223344",
    "cluster": {
      "id": 16
    }
  },
  "fPort": 2,
  "fCntDown": 1,
  "fCntUp": 1,
  "adr": false,
  "confirmed": true,
  "encrypted": false,
  "payload": "00266d0985067200000000000000ffff",
  "encodingType": "HEXA",
  "recvTime": 1548769153024,
  "gwRecvTime": 1548769153024,
  "classB": false,
  "delayed": false 
}

Radio: Same as Payload messages + DataUpRadioPayload
DataUpRadioPayload example:

{
...
  "ulFrequency": 867.9,
  "modulation": "LORA",
  "dataRate": "SF12BW125",
  "codingRate": "4/5"
}

Network: same as Radio messages + dataUpNetworkPayload
DataUpNetworkPayload example:

{
...
  "gwCnt": 2,
  "gwInfo": [
    {
      "gwEui": "7276FF002E060234",
      "rfRegion": "EU868",
      "rssi": -89,
      "snr": 10,
      "channel": 4,
      "radioId": 0,
      "antenna": 0
    },
    {
      "gwEui": "7276FF002E060234",
      "rfRegion": "EU868",
      "rssi": -92,
      "snr": 8.2,
      "channel": 20,
      "radioId": 0,
      "antenna": 1
    }
  ]
}

Data sample

Here is a sample of a payload with the network level of detail:

{
  "id": "5c20c07cd7edec0001f847a2",
  "endDevice": {
    "devEui": "343737395C336A08",
    "devAddr": "0132FBCF",
    "cluster": {
      "id": 16
    }
  },
  "fPort": 2,
  "fCntDown": 0,
  "fCntUp": 61,
  "adr": false,
  "confirmed": false,
  "encrypted": false,
  "payload": "0027ff096cfc8218000000000000ffff",
  "encodingType": "HEXA",
  "recvTime": 1545650300180,
  "gwRecvTime": 1545650300180,
  "classB": false,
  "delayed": false,
  "ulFrequency": 868.5,
  "modulation": "LORA",
  "dataRate": "SF12BW125",
  "codingRate": "4/5",
  "gwCnt": 1,
  "gwInfo": [
    {
      "gwEui": "7276FF003903002E",
      "rfRegion": "EU868",
      "rssi": -60,
      "snr": 9,
      "channel": 7,
      "radioId": 1
    }
  ]
}

Mapping table

For your convenience, here is the mapping from/to the old/new API:

Field API v3.x API v2.3
message identifier .id
end device information .endDevice
device EUI .endDevice.devEui .devEui
device address .endDevice.devAddr
cluster information .endDevice.cluster
cluster identifier .endDevice.cluster.id
frame port .fPort .userdata.fPort
frame counter downlink .fCntDown .fcntDown
frame counter uplink .fCntUp .fcntUp
ADR activated? .adr .moteTx.adr
Acknowledgement required? .confirmed
Is payload encrypted? .encrypted
Payload .payload .userdata.payload
Receive time (ms) .recvTime
Gateway Receive time (ms) .gwRecvTime
Uplink frequency .ulFrequency .moteTx.freq
Uplink modulation .modulation .moteTx.modu
Uplink data rate .dataRate .moteTx.datr
Uplink coding rate .codingRate .moteTx.codr
Gateway count .gwCnt
Gateways information .gwInfo .gwRx
Gateway EUI .gwInfo[].gwEui .gwRx[].eui
Gateway RF region .gwInfo[].rfRegion
Gateway RSSI .gwInfo[].rssi .gwRx[].rssic/rssi
Gateway SNR .gwInfo[].snr .gwRx[].lsnr
Gateway channel number .gwInfo[].channel .gwRx[].chan
Gateway radio identifier .gwInfo[].radioId