设备端开发 - 以全指令协议开发 - 《IoT开放平台》

前提条件
背景信息
操作步骤

当操作设备时，一次性将所有云食谱的操作指令从云端发送到设备端的协议方式，称为全指令协议方式。请您根据以下操作来开发云食谱全指令协议。

前提条件

该品类支持全指令协议的物模型。相关介绍，请参见协议开发概述。

背景信息

全指令协议开发流程如下。
以全指令协议开发 - 图1
请您根据App端的实现方式，来开发全指令协议的流程。

如果您的App端集成小程序，则只需处理设备端的相关操作即可（对应以下操作的步骤3、步骤4、步骤6、步骤7）。
说明如果您希望最大程度节省开发工作量，或最短时间内上线云食谱应用，推荐您App端选择快速集成小程序的方式、设备端选择开发全指令协议的方式。
如果您使用H5方式自行开发App端，除了处理设备端的相关操作外，您还需要处理App端的相关操作。

操作步骤

天猫精灵App端调用行业设备控制接口，向服务端发送启动云食谱的指令。接口的请求参数payload配置如下。
```
payload: JSON.stringify({"businessRecipeId": 100,"command":"deviceStart"}) 
//deviceStart表示开始指令或继续指令
```

服务端向设备端下发云食谱所有步骤的物模型指令。例如：完整云食谱操作分三个操作步骤，则服务端连续向设备端下发三次指令，每次为一个完整操作步骤的指令。物模型示例代码如下。

//云食谱第一步操作
{
"cloudRecipeStatus":1, //云食谱状态
"cloudRecipeStepSequence":1, //云食谱顺序序号
"cloudRecipeIntegrityCheck":"e", //云食谱完整性校验码
"runTime":30
...
}
//云食谱第二步操作
{
"cloudRecipeStepSequence":2, //云食谱顺序序号
"cloudRecipeIntegrityCheck":"e", //云食谱完整性校验码
"runTime":30
...
}
//云食谱第三步操作
{
"cloudRecipeStepSequence":3, //云食谱顺序序号
"cloudRecipeIntegrityCheck":"e", //云食谱完整性校验码
"runTime":30
...
}

设备端校验验证码的完整性。设备端需对接收到的物模型指令进行完整性校验码，由此来物模型指令是否全部接收。完整性校验的方法如下。
1. 向左移项二进制数000001，移动位数为cloudRecipeStepSequence的值。例如：食谱A拥有3个智能食谱步骤，即cloudRecipeStepSequence的值分别为1、2、3。则将二进制数000001分别向左移项1位、2位、3位。移项后得到的新二进制数为000010、000100、001000。
2. 将所有步骤移项后的二进制转化数相加，并转换为十六进制。以上示例000010、000100、001000相加的结果为001110。转换成十六进制表示为：e。
设备端向服务端上报指令接收结果。
- 设备端在3分钟内收到的指令完整设备端向服务端上报物模型属性cloudRecipeStatus=1，表示开始运行云食谱。
- 设备端在3分钟内收到的指令不完整设备端向服务端上报workstatus=0，表示云食谱停止或未启动。

服务端通过长连接消息向App端推送消息，更新App端显示的设备状态。

App端向服务端推送消息。示例代码如下。

// 在store/modules/public.js 找到deviceStatusChange方法，加上recipe逻辑
AI.deviceStatusChange({
callback: resp => {
  console.log('长链接返回的设备状态：', Object.assign({}, resp.model));
  if (resp.recipe) {
    console.error('recipe', resp) // 云食谱返回数据
    // 当云食谱的长链接推送过来，返回的数据在resp.recipe中
    return
  }
  // 返回的设备状态，在resp.model中
},
errorCallback: (error) => { console.log('stateChange ERROR:', error) }
});

App端收到消息后向服务端返回响应消息。示例代码如下。

{
\"traceId\": \"1234567890abcdefghijkl0123456789\",    // 追踪ID
\"timestamp\": 1547714598977,                         // 时间戳
\"deviceId\": \"456A23FBE******094FD92AB0B\",   // 设备ID
\"domain\": 1,                           // 领域：1食谱
\"payload\": {                           // 领域参数
\"contentRecipeId\": 100,              // 内容食谱ID
\"currentContentRecipeStepId\": 9000,  // 当前内容食谱步骤ID
\"runStatus\": 2,                      // 运行状态，0表示停止、1表示运行、2表示暂停、3表示食谱完成、4表示中断暂停
\"timeLeftTotal\": 10,                 // 剩余时间总时间，单位秒
\"totalTime\": 180,                    // 总时间，单位秒
\"productName\": "破壁机",              // 产品名称
\"productKey\": \"6001\",              // 产品key
\"controlApiName\": \"alibaba.ailabs.iot.saas.devicecontrol\",    // 控制接口名
\"deviceStatusApiName\": \"alibaba.ailabs.iot.saas.deviceStatus\" // 设备状态接口名
\"businessRecipeId\": 100,                          // 行业食谱id
\"deviceStatus\": {\"name\":\"start/开始\",\"value\":1}, // 设备状态
\"interruptErrorInfo\": {\"code\": 302007,\"message\":\"设备处于离线状态\"} // 中断错误码
}
}

（可选）在设备制作云食谱过程中，如果App端或设备端收到其他操作指令时，需主动向服务端上报物模型指令。
- 设备端向服务端上报指令
  - 设备端上报属性设备端向服务端上报当前云食谱的信息。示例代码如下。
```
{
"workstatus":1, //工作状态，0表示停止、1表示开始、2表示暂停、3表示待机状态，其余状态统称为运行中状态
"cloudRecipeStepSequence":1, //云食谱步骤顺序号
"lefttime":80  //剩余时间
...
}
```
  - 设备端上报事件在云食谱运行过程中，如果发生互斥操作，设备端需主动向服务端上报相关事件。例如：终端用户在设备端增加了火力、时间等。示例代码如下。
```
{
"eventName":"deviceSideOperationEvent",
"params":"{\"opreationName\":\"updateTime\"}"
}
```
  - 云食谱暂停消息事件当终端用户暂时云食谱操作添加食材时，设备端需向服务端告知云食谱暂停消息事件。示例代码如下。
```
{
"eventName":"cloudRecipeSuspendMsgEvent"
}
```
- App端向服务端上报指令在云食谱操作过程中，如果终端用户通过App端发起变更云食谱的操作，此时App端调用行业设备控制接口向服务端上报消息。
  - 查询设备制作状态行业设备控制接口的请求参数payload配置示例如下。
```
payload: JSON.stringify({"businessRecipeId": 2})
```
  - 暂停云食谱制作行业设备控制接口的请求参数payload配置示例如下。
```
payload: JSON.stringify({"businessRecipeId": 100,"command":"deviceSuspend"})
//deviceSuspend表示暂停指令
```
  - 服务端收到该指令后，向设备端下发"workSwitch":2的物模型指令。
  - 继续云食谱制作行业设备控制接口的请求参数payload配置示例如下。
```
payload: JSON.stringify({"businessRecipeId": 100,"command":"deviceStart"}) 
//deviceStart表示开始指令或继续指令
```
  - 停止云食谱制作行业设备控制接口的请求参数payload配置示例如下。
```
payload: JSON.stringify({"businessRecipeId": 100,"command":"deviceStop"})
//deviceStop表示暂停指令
```
  - 服务端收到该指令后，向设备端下发"workSwitch":0, "cloudRecipeStatus":0的物模型指令。
设备完成云食谱制作后，设备端向服务端上报完成事件。物模型的示例代码如下。
```
{
"eventName":"cloudRecipeDoneEvent"
}
```
服务端通过长连接消息向App端推送消息，更新App端显示的设备状态。