下发命令¶

设备连接上云后，允许云端远程控制和监控。命令是云端向设备主动发送的指令，可触发特定动作，如开灯、关灯、调节温度等。你可以远程向设备发送命令，以及查看命令下发的状态。

设备可调用的命令已在设备模型中定义。可前往 EnOS 模型管理配置模型定义。

命令的类型¶

命令的类型可分为以下两种：

测点设置：更新或设置某个测点的参数值，当该测点与设备控制逻辑绑定时，测点值的变化将作为设备执行动作的触发条件。例如将智能空调的目标温度值设置为 25℃，当设备固件监控到实时温度与目标温度存在差异时，将触发制冷或加热的动作。设置测点值时，必须确保：
- 该测点在模型定义中 支持可写。
- 且更新后的值符合模型定义的数值要求，例如在有效值范围內，防止无效命令。
需要注意的是，云端设置测点值后，云端查询的设备实时测点值并不一定会立即更新，如果设备没有将更新后的测点值回传给云端，云端查询的值就不会变化。
服务调用：通过命令触发设备执行某项预定义的服务，服务可能涉及多个步骤或复杂逻辑，已经预封装在设备固件中。例如远程调用智能空调的“自动”模式，空调将根据实时环境温度，自动执行制冷或制热的动作。你也可以为这类型的命令设置参数，例如为“自动”模式定时 2 小时。

命令下发的时间¶

命令根据下发时间可分为两种：

立即下发：设备管理人员在云端发送命令后，EnOS 立即下发，如果设备不在线或者设备没收到命令，则下发失败。当设备与云端建立稳定连接时，或时间窗口严格且设备不在线时可接受失败时，可使用立即下发命令。
缓存下发：EnOS 首先将该条命令加入到此设备的缓存下发队列中。缓存队列是一个有序的队列，等待设备重新与 EnOS 云端建立连接后，缓存的命令将按顺序进行下发。缓存下发适合在设备与 EnOS 连接断开，或低功耗设备因长期休眠无法及时执行命令的场景。EnOS 为单个设备缓存最多 50 条命令。

命令下发流程¶

假定命令的有效期设为 3600 秒，命令下发的流程如下图：

../../_images/issuing_cached_commands.png

命令在下发的过程中，遵守以下规则：

有序下发：设备处理并返回上一条命令的响应信息后，EnOS 才会发送下一条命令。上一条命令的处理结果包括：发送成功（设备接收命令并正常响应）和响应超时（EnOS 已经发送了命令但是设备没有及时响应）。
无优先级：无论设备是否在线，在缓存的命令尚未处理完，而应用又发送了一条新命令的情况下，无论新命令是立即下发的还是缓存下发的，都会加入到队列中等待按照顺序下发。如果要优先发送新命令，应用应当调用 Cancel Command API 对缓存的命令进行撤销，才可下发新的命令。也就是说，缓存队列中也可以存储本应立即下发的命令，所有命令按顺序下发。如果此时设备下线了，则立即下发的命令将自动失败。
自动清除超期命令：超过有效期的缓存命令，EnOS 从缓存队列中自动清除，并将状态置为“已超期”。

下发命令操作步骤¶

步骤 1：云端下发命令¶

你可以通过 EnOS API 向设备批量下发命令或单次下发命令：

为多个设备批量下发命令：
1. 使用 Create Command Job API 创建批量下发任务，EnOS 将自动为每个设备单独创建下发命令的任务。
2. 使用 Search Command Tasks API 查询单个命令下发任务的执行状态。
为某一设备单次下发命令：
- 使用 Invoke Service API 调用某一设备的服务。
- 使用 Set Measurement Point API 设置某一设备的测点值。
- 使用 Get Command API 查询命令的状态。

你可以在 API 请求参数中定义命令的有效期：当有效期为 0 时，表示立即下发。当有效期大于 0 时，表示可以缓存下发。

步骤 2：设备返回执行状态¶

设备可以在 API 响应信息中带上自定义的业务描述信息，以说明命令执行的状态。响应数据格式如下，message 为描述命令执行状态的字段。

{
    "id": "123",
    "code": 200,
    "message": "该命令已成功执行"
    "data": {
               "outputdata1":234,
               "outputdata2":"xyz"
              }
}

步骤 3：云端查看命令状态¶

你也可以在应用门户中查看某一设备最近 7 天所有命令的执行状态。

备注

当前账号需要有开发者角色，以访问应用门户的开发者控制台，如果没有需联系 OU 管理员添加。

在应用门户的开发者控制台中选择 设备管理 > 设备资产。
选择需查看命令的设备，并点击其查看图标。
在 设备详情 页面，点击命令页签，你可以在该页面查询命令的信息和状态。命令有以下几种状态：
- 已创建：云端接收命令并创建，但未发送给设备。你可以对 已创建 而未下发的命令进行撤销。撤销后，命令将不再出现在下发队列中。
- 已撤销：该命令已被撤销，只有处于 已创建 状态的命令才能被撤销。
- 已超期：命令超过指定的有效期。有效期可以通过 API 指定，默认值为 0，即创建后立即下发命令。有效期最大值不超过 48 小时（172,800s）。对于超过有效期的缓存命令，云端将自动从缓存队列中清除该命令，并将状态置为 已超期。
- 已下发：云端已将命令投递到发往设备的下行消息通道中，但设备尚未响应。注意，该状态不代表一定发送成功。
- 发送成功：设备接收命令并返回响应信息，表示设备已执行命令成功。设备可能在响应信息中的 message 里带上自定义的业务描述信息。
- 发送失败：命令因为各种原因发送失败，例如该条命令无法被正确投递到下行消息通道中，或者设备已收到命令，但执行失败。可能原因为：设备离线、脚本解析错误、无效命令等。
- 响应超时：命令发送到设备下行消息通道，设备在超时周期内无响应。

仅支持在页面中查看该设备最近 7 天的命令，如需查看更多命令，可使用 Search Command API。