Issuing Commands


After the device is connected to the cloud, it allows remote control and monitoring from the cloud. Commands are proactive instructions sent from the cloud to devices, triggering specific actions like turning lights on/off or adjusting temperature. You can remotely send commands to devices and check their delivery status.


The available commands for devices are defined in the device model. You can configure model definition in EnOS Model Management.

Command Types


There are two types of commands:

  • Measurement Point Setting: Update or set parameters for a specific attribute. When the attribute is bound to device control logic, changes in its value will trigger device actions. For example, setting a smart AC’s target temperature to 25°C may trigger cooling/heating when the firmware detects a discrepancy between actual and target temperatures. Ensure:

    • The attribute Is Writable in the model definition.

    • The values comply with model-defined requirements (e.g., valid ranges and format) to prevent invalid commands.

    Note: Cloud-side attribute updates don’t guarantee immediate real-time value changes in cloud queries unless the device reports the updated value.

  • Service Invocation: Trigger predefined services through commands. These services may involve multi-step actions or complex logic pre-embedded in device firmware. For example, remotely activating “Auto” mode on a smart AC triggers automatic cooling/heating based on ambient temperature. Parameters can be set for such commands (e.g., 2-hour timer for “Auto” mode).

Issuance Time


Commands can be divided into two types based on the issuance time:

  • Immediate Issuance: After the device manager sends a command from the cloud, EnOS issues it immediately. If the device is offline or does not receive the command, the issuance fails. Immediate issuance is recommended when the device has a stable connection with the cloud, or when a strict time window is set and failure is acceptable if the device is offline.

  • Cached Issuance: EnOS first adds the command to the cached issuance queue for the device. The cache queue is an ordered queue, and cached commands are issued in sequence once the device re-establishes a connection with the EnOS cloud. Cached issuance is suitable for scenarios where the device is disconnected from EnOS or when low-power devices are in long-term sleep mode and cannot execute commands promptly. EnOS caches a maximum of 50 commands for a single device.

Issuance Process


How a cached command is sent is illustrated in the following figure, assuming pendingTtl=3600:


../../_images/issuing_cached_commands.png


Commands adhere to these rules during issuance:

  • Ordered Issuance: EnOS sends the next command only after the device responds to the previous one. Responses include successful delivery (device receives and responds normally) or timeout (device fails to respond in time).

  • No Priority: New commands, whether for immediate or cached issuance, join the queue and are issued in sequence, even if cached commands are pending. To prioritize a new command, you can use the Cancel Command API to clear cached commands. Immediate issuance commands may enter the cache queue and will fail if the device is offline.

  • Automatic Clearing of Expired Commands: EnOS removes expired cached commands from the queue and marks them as “Expired.”

Command Delivery Procedure

Step 1: Cloud Delivering Commands


You can deliver commands through EnOS APIs in batch or individually:


You can define command validity period in API parameters:

  • Validity=0: Immediate Issuance

  • Validity>0: Cached Issuance

Step 2: Device Returning Execution Status


Devices can include custom business messages in API responses using the message field to describe execution status:

{
    "id": "123",
    "code": 200,
    "message": "Command executed successfully",
    "data": {
               "outputdata1":234,
               "outputdata2":"xyz"
             }
}


Step 3: Checking Command Status


You can also view the execution status of all commands for a specific device over the past 7 days in Application Portal.


Note

The current account requires the Developer role to access the Developer Console in Application Portal. If you don’t have this role, contact the OU administrator.


  1. In the Developer Console of Application Portal, select Device Management > Device Assets.

  2. Select the device for which you want to view commands and click its View icon btn_view.

  3. On the Device Details page, click the Commands tab to query command information and status. Commands can have the following statuses:

    • Created: The cloud has received and created the command but has not yet sent it to the device. You can Cancel commands that are Created but not yet issued. Canceled commands will no longer appear in the issuance queue.

    • Revoked: The command has been canceled. Only commands in the Created state can be canceled.

    • Expired: The command has exceeded its specified validity period. The validity period can be set via API, with a default of 0 (immediate issuance upon creation). The maximum validity period is 48 hours (172,800 seconds). For cached commands that exceed their validity period, the cloud automatically removes them from the cache queue and sets their status to Expired.

    • Sent: The cloud has delivered the command to the downlink message channel for the device, but the device has not yet responded. Note that this status does not guarantee successful delivery.

    • Succeeded: The device has received the command and returned a response, indicating successful execution. The device may include custom business description information in the message field of the response.

    • Failed: The command failed to send due to various reasons, such as failure to deliver to the downlink message channel or the device receiving but failing to execute the command. Possible reasons include: device offline, script parsing errors, or invalid commands.

    • Timeout: The command was sent to the device’s downlink message channel, but the device did not respond within the timeout period.


../../_images/cached_commands.png


Only commands from the past 7 days for the device can be viewed on this page. To view more commands, you can use the Search Command API.