OneNET IoT Platform Platform Introduction Introduction Manual Guidline for Device Development Guideline for Application Development
API
API Usage API List SDK MQTT LwM2M EDP Modbus TCP
HTTP Push

Developer Manual

When using push service, OneNET is a client, while user's third-party application is server. The third-party application needs to support two parts services of URL verification and data receiving .

URL Verification

The URL verification process is shown below:

url验证流程

When user completes configuration on the configuration page and clicks “Submit”, OneNET platform sends an HTTP GET request to the URL filling address for URL verification. The request form is as follows:

http://url?msg=xxx&nonce=xxx&signature=xxx

Among above, url is entered by the user during page configuration, nonce, msg, signature are used for URL and token verification.

The token verification process is as follows:

  1. Calculate MD5 with the values of token and nonce , msg configured in the configuration page, and code them as Base64 string values

  2. Compare above Base64 string values calculated by URL Decode with value of the request parameter signature. If they are equal, the token is successfully verified

If token verification succeeds, the msg parameter value is returned, indicating that the URL verification is passed.

If user does not want to verify the token, he/she can choose to skip the MD5 calculation and return the msg parameter value directly

Data Acceptance

The platform pushes data to the URL address of the third-party platform in the form of HTTP POST request, and related information of the pushed data is placed in the body part of the HTTP request in the form of JSON string, where the meanings of each field are as follows

Field Type Field description
Type Int Identification message type
1: Data point messages uploaded by device
2: Online and offline messages of device
7: Results reporting after cache command issue (only support NB devices)
Dev_id Int Device ID
Ds_id String Datastream name
At Int Platform timestamp, unit is ms
Value Specific data part, is related data uploaded to platform or triggered by the device
Status Int Device online and offline identifications
0: Device offline
1: Device online
Login_type Int Device login protocol type
1-EDP, 6-MODBUS, 7-MQTT, 10-NB-IoT
Cmd_type Int Command response type
1: Device receives the ACK response information of cmd
2: Device receives the Confirm response message of cmd
Cmd_id String Command ID
msg_signature String Message digest
nonce string Random string used to calculate the message digest
enc_msg string Encrypt ciphertext message body, encryption on plaintext JSON string (msg field)

Example 1: Datapoint messages

{
    "msg": {
        "type": 1,
        "dev_id": 2016617,
        "ds_id": "datastream_id",
        "at": 1466133706841,
        "value": 42
    },
    "msg_signature": "message signature",
    "nonce": "abcdefgh"
}

Example 2: Batch Datapoint messages (need to configure data cache)

{
    "msg": [{
            "type": 1,
            "dev_id": 2016617,
            "ds_id": "datastream_id",
            "at": 1466133706841,
            "value": 42
        },
        {
            "type": 1,
            "dev_id": 2016617,
            "ds_id": "datastream_id",
            "at": 1466133706842,
            "value": 43
        },
        ...
    ],
    "msg_signature": "message signature ",
    "nonce": "abcdefgh"
}

Example 3:Online and offline message of device

{
    "msg": {
        "type": 2,
        "dev_id": 2016617,
        "status": 0,
        "login_type": 1,
        "at": 1466133706841
    },
    "msg_signature": "message signature",
    "nonce": "abcdefgh"
}

Example 4: Results report after cache command issue

{
    "msg": {
        "type": 7,
        "cmd_id": "3a351323-c4fe-5f21-9e9e-a9adc321182f",
        "imei": "865820060031939",
        "dev_id": 2016690,
        "cmd_type": 0,
        "send_time": 1466133706841,
        "send_status": 5,
        "confirm_time": 146613371921,
        "confirm_status": 0,
        "confirm_body": {
            "obj_id": 3,
            "obj_inst": [{
                "obj_inst_id": 0,
                "res": [{
                        "res_inst": [{
                            "val": 0,
                            "res_inst_id": 0
                        }],
                        "res_id": 11
                    },
                    {
                        "val": 1530496927000,
                        "res_id": 13
                    }
                ]
            }]
        }
    },
    "msg_signature": "message signature",
    "nonce": "abcdefgh"
}

Instruction:

  1. When response results contain binary data, will convert the binary data byte[] to an array of ASCII code, and stored in the JSON data, such as: [98, 105, 110, 97, 114, 121]
  2. When the command type is READ, the confirm_body field will carry the object id and object instance id when ommand request for the user to parse the data.

Example 5: Ciphertext format

{
    "enc_msg": "XXXXXXXXXXX",
    "msg_signature": "message signature",
    "nonce": "abcdefgh"
}

Suggestions on Service Realization

  • In order to ensure that data is not lost, the OneNET platform has retransmission mechanism. If duplicate data has an impact on the service, the data receiver needs to eliminate duplicate data
  • After each POST data request, there’s a time limit (currently 5 secs) for OneNET to wait for the client response. If no response is received within the specified time limit, will consider transmission fails. When it fails 2000 times in total, the third-party service is considered unavailable and the service will be stopped. Therefore, it is recommended that when the third-party application receives the data, caches the data first, then processes the service logic

results matching ""

    No results matching ""