Uplink

Last modified: Jul 9, 2019 @ 14:40

Devices can communicate to HTTP gateways when the device setup has the following configuration:

  • Device is installed with HTTP client
  • Device has device certificate which is signed by trusted CA
  • The URI of the Gateway

The format of the Gateway URI is: <Gateway_Name>.<DomainName>

For example:

http-sample-gateway.ddm.iot-accelerator.ericsson.net

Note: URI should be provided by the Ericsson Operations, after instantiating the Gateway.

Once the above mentioned details are defined, the device can start communicating to the gateway by using the REST interface API, as given below:

The uplink messages from device to Gateway has two interfaces, which are exposed:

1. Telemetry Data Interface

This interface accepts SenML format telemetry data from devices and forwards the data to DDM.

Request

Method URL
POST https://{Gateway-URL}:443/v1/senml

Parameters

Type Name Description Schema
Header Content-Type Type of the content. Application / JSON
Header X-Forwarded-For

(optional)

Device IP. IP string
Body senmlMessage

(required)

Senml object that contains the device sensor values. JSON string

X-Forwarded-For: This is an optional header to explicitly send the IP of the device. This is later used for the Downlink operation to reach the device. If this Header is not sent, then the Gateway uses the remote address value which is passed by the network elements.

Note: It is not recommended to use this Header, except for cases like debugging or for a certain network setting. Load balancer is successfully able to pass the device IP to gateway.

senmlMessage: This is a JSON format string that goes in the request body. Data format must be compatible with SenML message format. Refer to section Data Model Definition for more details.

Responses

HTTP Code Response Description
200 {“status”:”Success”} OK
405 {“error”:Bad request”} Bad request
401 {“error”:”Authorization error”} Unauthorized
500 {“error”:”Internal server error“} Internal server error

Example for HTTP request

POST /v1/senml HTTP/1.1
Accept: application/json
Content-Length: 60
X-Forwarded-For: 127.0.0.1
Content-Type: application/json
Host: http-sample-gateway.ddm.iot-accelerator.ericsson.net

[{"n":"3303/0/5700","u":"Celsius","v":"23.9"},{"n":"3303/0/5701
","vs":"Cel"}]

Example for HTTP response

HTTP/1.1 200 OK
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
X-XSS-Protection: 1 ; mode=block

Example for Curl request

$ curl 'https://http-sample-gateway.ddm.iot-accelerator.ericsson.net:443
/v1/senml' -i -X POST \
     --cert client.crt \
     --key client.key \
     --cacert rootca.crt \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d 
'[{"n":"3303/0/5700","u":"Celsius","v":"23.9"},{"n":"3303/0/5701
","vs":"Cel"}]'

2. Device Register Interface

This interface is used to register the device. The registration is required to know the device HTTP server details.

Request

Method URL
POST https://{Gateway-URL}:443/v1/register

Parameters

Type Name Description Schema
Header Content-Type Type of the content. Application / JSON
Header X-Forwarded-For

(optional)

Device IP. IP string
Body register Message

(required)

Senml object that contains the device sensor values. JSON string

X-Forwarded-For: This is an optional header to explicitly send the IP of the device. This is later used for the Downlink operation to reach the device. If this Header is not sent, then the Gateway uses the remote address value which is passed by the network elements.

Note: It is not recommended to use this Header, except for cases like debugging or for a certain network setting. Load balancer is successfully able to pass the device IP to gateway.

registerMessage: This is a JSON string. It has the fields for the device HTTP server.

The details are in the table given below:

Name Schema
port

(optional)

Device HTTP Server port, if it is running in another port.

Default port: 8443

uriPath

(optional)

Device HTTP Server URI path, if it is different from the default path.

Default path: /api/v1/

Responses

HTTP Code Response Description
200 {“status”:”Success”} OK
405 {“error”:Bad request”} Bad Request
401 {“error”:”Authorization error”} Unauthorized
500 {“error”:”Internal server error“} Internal server error

Example for HTTP request

POST /v1/register HTTP/1.1
Content-Length: 41
Accept: application/json
X-Forwarded-For: localhost
Content-Type: application/json
Host: localhost:8080

{"port":8081,"uriPath":"/v1/device/data"}

Example for HTTP response

HTTP/1.1 200 OK
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
X-XSS-Protection: 1 ; mode=block

Example for Curl request

$ curl 'https://http-sample-gateway.ddm.iot-accelerator.ericsson.net:443
/v1/register' -i -X POST \
     --cert client.crt \
     --key client.key \
     --cacert rootca.crt \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"port":8081,"uriPath":"/v1/device/data"}'

3. Device Deregister Interface

This interface is used to deregister the device. The de-registration is required to update the device status as offline in DDM.

Request

Method URL
PUT https://{Gateway-URL}:443/v1/deregister

Parameters

Type Name Description Schema
Header Content-Type Type of the content. Application / JSON

Responses

HTTP Code Response Description
200 {“status”:”Success”} OK
400 {“error”:Bad request”} Bad Request
401 {“error”:”Authorization error”} Unauthorized
500 {“error”:”Internal server error“} Internal server error

Example for HTTP request

PUT /v1/deregister HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: localhost:8443

Example for HTTP response

HTTP/1.1 200 OK
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
X-XSS-Protection: 1 ; mode=block

Example for Curl request

$ curl 'https://http-sample-gateway.ddm.iot-accelerator.ericsson.net:443
/v1/deregister' -i -X PUT \
     --cert client.crt \
     --key client.key \
     --cacert rootca.crt \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \