HTTP-based Connection


Developers can upload real-time device data to EnOS over HTTP.


The procedure of HTTP communication with EnOS is as follows:

  1. Integrate the device authentication keys (including the ProductKey, DeviceKey and DeviceSecret) with the device.

  2. The device connects to EnOS over HTTP or HTTPS, and sends data to EnOS.

HTTP Version

EnOS supports connection over the following HTTP versions.

  • Hypertext Transfer Protocol - HTTP/1.0 protocol. See RFC 1945.

  • Hypertext Transfer Protocol — HTTP/1.1 protocol. See RFC 2616

Connection Security

EnOS supports either HTTP or HTTPS. You can opt for HTTPS to ensure connection security.

Limitations

  • HTTP-based connection uses the same topic specifications as MQTT. The topic for uploading device data is https://{HTTP-Broker-URL}/topic/{Topic}, where the variable {Topic} is the same as the real-time-data-uploading topic for MQTT. For more information on MQTT topics, see MQTT Connection.

  • The formats of requests and responses over HTTP are the same as those for MQTT.

  • The error codes in responses over HTTP are the same as those in MQTT.

  • Only the POST method is supported for a request over HTTP.

  • Content-Type in the header of a device authentication request over HTTP must be application/json.

  • Content-Type in the header of a device-data-uploading request over HTTP must be application/octet-stream.

Connection Process

  1. EnOS authenticates the device to get the session ID.

  2. The device uses the session ID to upload data to EnOS.

Device Authentication

Authentication Request Sample

POST /auth/{ProductKey}/{DeviceKey} HTTP/1.1
Host: {HTTP-Broker-URL}
Content-Type: application/json

body: {"signMethod":"sha256","sign":"4870141D4067227128CBB4377906C3731CAC221C","lifetime":"300000"}


Parameter

Description

POST

The request method. Only POST is supported.

/auth/{ProductKey}/{DeviceKey}

The URL used for authentication.

Host: {HTTP-Broker-URL}

To obtain the MQTT Broker Address of your EnOS instance, log in to EnOS Console and select Help > Environment Information.

Content-Type: application/json

The encoding scheme of the authentication data the device sends to EnOS.

body: {“signMethod”: “sha256”,”sign”: “4870141D4067227128CBB4377906C3731CAC221C”,”lifetime”: “300000”}

The information required for authentication in JSON.


The format of the information required for authentication in JSON is as follows:

Parameter

Mandatory/Optional

Description

signMethod

Mandatory

The signature algorithm. Supports SHA256.

lifetime

Mandatory

The parameter used to determine device state in milliseconds. If the device has not uploaded any data to EnOS, it is required to authenticate the device again to obtain a new session ID.

sign

Mandatory

The device signature. Refer to the below for generating the device signature.

Generating the Device Signature

  1. The device signature is generated by concatenating the following parameters preceded by their respective parameter names:

    • deviceKey: The device key of the device.

    • lifetime: The parameter used to determine the device state.

    • productKey：The product key of the device.

    • signMethod：The signature algorithm. Only SHA256 is supported.


    If Device A has the following values for the above parameters:

    • deviceKey=dK987654

    • lifetime=300000

    • productKey=pK11111

    • signMethod=sha256

    The concatenated string would be: deviceKeydK987654lifetime300000productKeypK11111signMethodsha256.


2. Attach the device secret of the device to the end of the concatenated string.

If the device secret of Device A is ds54321, then the new string would be: deviceKeydK987654lifetime300000productKeypK11111signMethodsha256ds54321


3. Use SHA256 to calculate the string. Convert the letters in the resulted key into capital letters using toUpperCase. The converted result is the value to the parameter sign.

The calculation process of sign for Device A can be expressed as: sign=toUpperCase(sha256(deviceKeydK987654lifetime300000productKeypK11111signMethodsha256ds54321))

Note

Do not attach deviceSecret (the parameter name) to the end of the concatenated string in step 2. Just attach the value of deviceSecret.

Response Sample

body:
{
  "code": 200,
  "msg": "success",
  "data": {
     "sessionId": "262dc4cb-dc31-4610-b5e5-417b93e4f008"
   }
}

Note

  • The returned sessionId needs to be saved locally because it needs to be included every time a device attempts to upload data.

  • If sessionId authentication fails, it needs to be obtained again.


Error code

Message

Description

400

Bad Request

One or more parameters in the request is invalid.

401

Unauthorized

The device authentication failed.

500

Internal Server Error

Internal server error.

Uploading Measurement Point Data

The topic used for uploading measurement point data is the same as that of MQTT: /sys/{productKey}/{deviceKey}/thing/measurepoint/post


The URL of the reported data is https://{HTTP_Broker_URL}/topic/sys/{productKey}/{deviceKey}/thing/measurepoint/post, where：

  • {productKey} indicates the product key of the device

  • {deviceKey} indicates the device key of the device

Request Sample

POST /topic/sys/{ProductKey}/{DeviceKey}/thing/measurepoint/post HTTP/1.1
Host: {HTTP_Broker_URL}
Query-Parameter: sessionId={SessionId}
Content-Type: application/json

body:
{
    "id":"123",
    "version":"1.0",
    "params":{
        "measurepoints":{
            "Power":{
                "value":1,
                "quality":9
            },
            "temp":1.02,
            "branchCurr":[
                "1.02",
                "2.02",
                "7.93"
            ]
        },
        "time":123456
    },
    "method":"thing.measurepoint.post"
}

Response Sample

body:
{
    "id":"123",
    "code":200,
    "data":{}
}


For more information on error codes, see the Return Codes section in Report Device Measurement Points.