Development Guide

When the push service is applied, OneNET is used as the client, and the user’s third-party application as the server. The third-party application needs to support URL verification and data reception.

URL verification

The URL verification process is shown in the figure below:

After the user completes the configuration in the configuration page and clicks “Submit”, the OneNET platform will send a HTTP GET request to the URL address for URL verification. An example of request is as follows:

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

url is the URL that the user fills in the page configuration, and nonce, msg and signature are used for URL and token verification.

The token verification process is as follows:

1. Calculate MD5 with the token, nonce and msg values in the configuration page, and encode it to a Base64 string value.

2. Compare the URL Decode value of the Base64 string in the previous step and the value of the request parameter signature. If they are equal to each other, it means that the token has been successfully verified.

After the token is verified successfully, the msg value will be returned, indicating that the URL verification succeeds.

If the user does not need token verification, skip MD5 calculation to directly return the msg value.

Data reception

The platform pushes data to the URL address of the third-party platform in the form of HTTP POST request. The third-party platform needs to return HTTP 200 after receiving the data. Otherwise, OneNET will deem the push invalid and try to push again.

Relevant messages of the pushed data are saved in the body part of the HTTP request in the form of JSON string. The meaning of each field is as follows.

Example 1: Data point message

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

Example 2: Batch data point messages (data cache needs to be configured)

{
    "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: Device online/offline message

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

Example 4: Result report after the cache command is issued (support NB devices only)

{
    "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"
}

Description:

1. When the response result contains binary data, the binary data byte[] will be converted into an array of ASCII codes and saved in 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 of the command request to facilitate data analysis.

Encrypted transmission

While configuring the push service, users can configure encrypted transmission. OneNET supports AES symmetric encryption. Users can configure the key in the page, and perform decryption via the key on the application side.

Example: Ciphertext format

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

Suggestions on service implementation

• In order to prevent data loss, the OneNET platform has a retransmission mechanism. The duplicate data affecting services will be eliminated by the data receiver.

• OneNET has a time limit (currently 5 seconds) of waiting for client response after each POST data request. In case of no response within the specified time limit, it is deemed that transmission fails. When transmission failure occurs for 2,000 times cumulatively, the third-party service will be considered unavailable and disabled. It is recommended to cache the received data via the data reception program of the third-party application before service logic processing.

• To use the data push service of the OneNET platform continuously and stably, please add the export IP address of the data push service of the OneNET platform into the IP whitelist of your application.