Calling Device Services

Typical Scenario

The device profile file defines commands that the IoT platform can deliver to a device. When an NA needs to configure or modify the service attributes of a device, the NA can call this API to deliver commands to the device.

The IoT platform does not cache commands but delivers commands immediately. If a device is offline, the commands fail to be delivered. The command formats are defined by the NA and the device, and the IoT platform performs encapsulation and transparent transmission for messages over the API.

This API applies to devices that use MQTT, for example, devices that have integrated the AgentLite SDK.

API Function

This API is used by an NA to deliver a command to a device to control the device.

API Prototype

Method	POST
URL	https://server:port/iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/{serviceId}/sendCommand?appId={appId}
Transport Protocol	HTTPS

Request Parameters

Parameter	Mandatory or Optional	Type	Location	Description
app_key	Mandatory	String	header	Identifies an application that can be accessed on the IoT platform. The value of this parameter is allocated by the IoT platform when the application is created on the platform.
Authorization	Mandatory	String	header	Indicates the authentication information for accessing the IoT platform. The value is Bearer {accessToken}, in which {accessToken} indicates the access token returned by the Authentication API.
deviceId	Mandatory	String(1-64)	path	Uniquely identifies a device. The value of this parameter is allocated by the IoT platform during device registration.
serviceId	Mandatory	String(1-64)	path	Identifies the service corresponding to the command. The value of this parameter must be the same as serviceId defined in the profile.
appId	Optional	String	query	Identifies an application that can be accessed on the IoT platform. The value of this parameter is allocated by the IoT platform when the application is created on the platform. Set this parameter to the value of appId of the authorized application.
header	Mandatory	CommandNA2CloudHeader	body	Indicates the message header.
body	Optional	ObjectNode	body	Indicates the message body. The content of the JsonObject is a list of key-value pairs. Every key is the paraName of a command defined in the profile.

CommandNA2CloudHeader structure

Parameter	Mandatory or Optional	Type	Location	Description
requestId	Optional	String(0-128)	body	Identifies a command. The value of this parameter must be unique.
mode	Mandatory	Enum	body	Indicates whether an ACK message is required. NOACK: No ACK message is required. ACK: An ACK message is required. Other values: invalid
from	Optional	String(128)	body	Indicates the address of the message sender. Request initiated by an application: /users/{userId} Request initiated by an NA: /{serviceName} Request initiated by the IoT platform: /cloud/{serviceName}
toType	Optional	Enum	body	Indicates the type of the message recipient. The value options are CLOUD and GATEWAY. The default value is GATEWAY.
to	Optional	String(128)	body	Indicates the address of the message recipient.
method	Mandatory	String(1-32)	body	Indicates the command name. The value of this parameter must be the same as the command name defined in the profile file.
callbackURL	Optional	String(1024)	body	Indicates the URL for receiving command status change notifications. When the command status changes, such as execution failure, execution success, timeout, sending, or sent, the NA is notified.

Response Parameters

Status Code: 202 Accepted

Parameter	Type	Description
status	String(128)	Indicates the command status. sent: The command has been sent. delivered: The device has received the command. failed: The command delivery fails.
timestamp	String(128)	Indicates the timestamp when the command is sent. The value is in the format of yyyyMMdd'T'HHmmss'Z'. An example value is 20151212T121212Z.
requestId	String(128)	Identifies a device command. If requestId is carried in a request, the response carries the same requestId as the request; if requestId is not carried in a request, the IoT platform allocates a sequence number for the response.

Parameter

Type

Description

status

String(128)

Indicates the command status.

sent: The command has been sent.
delivered: The device has received the command.
failed: The command delivery fails.

timestamp

String(128)

Indicates the timestamp when the command is sent. The value is in the format of yyyyMMdd'T'HHmmss'Z'. An example value is 20151212T121212Z.

requestId

String(128)

Identifies a device command. If requestId is carried in a request, the response carries the same requestId as the request; if requestId is not carried in a request, the IoT platform allocates a sequence number for the response.

Request Example

Method: POST
Request:
https://server:port/iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/{serviceId}/sendCommand
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json
Body:
{
  "header": {
    "mode": "ACK",
    "from": "/users/23212121",
    "method": "INVITE-INIT",
    "callbackURL": "http://10.10.10.10:8043/na/iocm/message/confirm"
  },
  "body": {
    "from": "************",
    "sessionID": "**********",
    "sdp": "**********"
  }
}

Response Example

Response:
Status Code: 202 Accepted
Content-Type: application/json
Body:
{
  "requestId": "************",
  "status": "sent",
  "timestamp": "**********"
}

Error Codes

HTTP Status Code	Error Code	Error Description	Remarks
200	100203	The application is not existed.	The application does not exist. Recommended handling: Check whether appId carried in the HTTP request header is correct. Check whether appId in the request path (URL) is correct.
200	100217	The application hasn't been authorized.	The application has not been authorized. Recommended handling: In scenarios where applications are not authorized, ensure that request parameter appId is null.
200	100418	The deviceData is not existed.	The device data does not exist. Recommended handling: If deviceId carried in the request is incorrect, check whether deviceId belongs to appId or whether deviceId is incorrect. Check whether appId carried in the header contains deviceId. If the URL contains the optional parameter appId, check whether the value of appId is correct.
200	100428	The device is not online.	The device is not online. Recommended handling: Check whether the connection between the device and the gateway is normal.
200	100432	The device command is muted.	The device command is muted. Recommended handling: Check whether the command carried in the API request parameter method is correct.
400	100022	The input is invalid.	An input parameter is invalid. Recommended handling: Check whether parameters carried in the API call request are valid.
400	102203	CommandName is invalid.	The command name is invalid. Recommended handling: Check whether the command carried in the API request parameter method is correct.
403	100450	The gateway is not online.	The gateway is offline. Recommended handling: Check whether the connection between the gateway and the IoT platform is normal.
403	1010009	app throttle exceed.	The NA calls the API at a frequency that exceeds the flow control threshold (100 calls per minute by default). Recommended handling: Contact IoT platform maintenance personnel to adjust the flow control threshold or control the API call frequency.
403	1010005	App_key or access_token is invalid.	The access token is invalid. Recommended handling: Check whether accessToken carried in the API request is correct.
404	100444	The serviceType is not exist.	The service type does not exist. Recommended handling: Check whether the service type carried in the API request parameter toType is correct.
500	100001	Internal server error.	An internal server error occurs. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel.
500	100023	The data in database is abnormal.	The database is abnormal. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel.
500	50252	Internal server error.	An internal server error occurs. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel.
503	100501	Congestion occurs, and the current network has been flow-controlled	Congestion occurs. The current network is under flow control.