华为云 iot 操作说明------

jinchunxing

在线开发插件更新时间： 2020/03/21 GMT+08:00
查看PDF
[url=]分享[/url]

在设备接入控制台，我们可以通过可视化的方式快速开发一款产品的编解码插件。在自定义新建产品时，如果选择使用系统模板，部分模板会包含编解码插件，您可以直接使用或在此基础上进行修改；如果选择自定义产品模板，则需要完成编解码插件的开发。

编解码插件的开发需要基于Profile定义的设备能力进行开发，本节首先以一个烟感设备的例子讲解如何开发一个支持数据上报和命令下发的编解码插件，然后再以四个场景举例说明如何完成复杂的插件开发以及调试。

• 数据上报和命令下发
• 多条数据上报消息
• 字符串及可变长字符串的编解码插件在线开发
• 数组及可变长数组数据类型
• 含命令执行结果的编解码插件
  

数据上报和命令下发

场景说明

有一款烟感设备，具有如下特征：

• 具有烟雾报警功能（火灾等级）和温度上报功能。
• 支持远程控制命令，可远程打开报警功能。比如火灾现场温度，远程打开烟雾报警，提醒住户疏散。
  

Profile定义

在烟感产品的开发空间，完成Profile定义。

• level：火灾级别，用于表示火灾的严重程度。
• temperature：温度，用于表示火灾现场温度。
• SET_ALARM：打开或关闭告警命令，value=0表示关闭，value=1表示打开。

  

  
  

编解码插件开发

• 在烟感产品的开发空间，选择“插件开发”。
  

  

  
  
• 配置数据上报消息。
  

  

  添加level字段，表示火灾级别。
  • “字段名”只能输入包含字母、数字、_和$，且不能以数字开头的字符。
  • “数据类型”根据设备上报数据的实际情况进行配置，需要和Profile相应字段的定义相匹配。
  • “长度”和“偏移值”根据“数据类型”的配置自动填充。

    

    
    
  
  

  添加temperature字段，表示温度。在Profile中，temperature属性最大值1000，因此在插件中定义temperature字段的“数据类型”为“int16u”，以满足temperature属性的取值范围，然后单击“确认”。

  

  
  
• 再次单击“新增消息”，配置命令下发消息。
  

  

  单击“添加字段”，添加value字段，表示下发命令的参数值，然后单击“确认”。

  

  
  
• 拖动右侧“设备模型”区域的属性字段和命令字段，数据上报消息和命令下发消息的相应字段建立映射关系。
  

  

  
  
• 点击“保存”，并在插件保存成功后点击“部署”，将编解码插件部署到物联网平台。
  

  

  
  
  

调测编解码插件

• 在烟感产品的开发空间，选择“在线调测”，并单击“新增测试设备”，使用真实设备进行调试。
  说明：

  [color=rgb(102, 106, 117) !important]新添加的设备处于未激活状态，此时不能进行在线调试，可参考连接鉴权，待设备接入平台后，进行调试。

  
  
  
  
  
• 在弹出的页面中，输入测试设备的参数，设备名称和设备标志码请填写注册设备时输入的设备名称和设备标志码。
  

  

  注：如果使用DTLS传输层安全协议接入时，设备注册方式选择“加密”，且请妥善保存PSK码。

  
  
• 单击“调试”，进入调试界面。
  

  

  
  
• 使用设备模拟器进行数据上报。十六进制码流示例：02013A。02表示火灾级别，长度为1个字节；013A表示温度，长度为2个字节。
  

  在“应用模拟器”区域查看数据上报的结果：{level=2, temperature=314}。2为十六进制数02转换为十进制的数值；314为十六进制数013A转换为十进制的数值。

  

  
  
• 使用应用模拟器进行命令下发：{ "serviceId": "Smoke", "method": "SET_ALARM", "paras": "{\"value\":1}" }。
  

  在“设备模拟器”区域查看命令接收的结果：01。01为十进制数1转换为十六进制的数值。

  

  
  
  

多条数据上报消息

如果该烟感设备需要支持同时上报烟雾报警（火灾等级）和温度，也支持单独上报温度，则按照以下步骤创建消息。

编解码插件开发

• 在烟感产品的开发空间，选择“编解码插件开发”。
  

  

  
  
• 配置数据上报消息，上报火灾等级和温度。
  

  

  单击“添加字段”，添加messageId字段，表示消息种类。

  • 在本场景中，数据上报消息有两种，所以需要用messageId来标识消息种类。
  • “数据类型”根据数据上报消息种类的数量进行配置。在本场景中，仅有两种数据上报消息，配置为“int8u”即可满足需求。
  • “默认值”可以修改，但必须为十六进制格式，且数据上报消息的对应字段必须和默认值保持一致。在本场景中，用0x0标识上报火灾等级和温度的消息。
    

  

  添加level字段，表示火灾级别。
  • “字段名”只能输入包含字母、数字、_和$，且不能以数字开头的字符。
  • “数据类型”根据设备上报数据的实际情况进行配置，需要和Profile相应字段的定义相匹配。
  • “长度”和“偏移值”根据“数据类型”的配置自动填充。
    
  
  

  

  添加temperature字段，表示温度。在Profile中，temperature属性最大值1000，因此在插件中定义temperature字段的“数据类型”为“int16u”，以满足temperature属性的取值范围。

  

  
  
• 配置数据上报消息，只上报温度。
  

  

  添加messageId字段，表示消息种类。在本场景中，用0x1标识只上报温度的消息。

  

  添加temperature字段，表示温度。

  

  
  
• 配置命令下发消息。
  

  

  添加value字段，表示下发命令的参数值。

  

  
  
• 拖动右侧“设备模型”区域的属性字段和命令字段，与数据上报消息和命令下发消息的相应字段建立映射关系。
  

  level字段和temperature字段分别与Profile中的对应属性建立映射关系，messageId用于帮插件识别消息种类，不需要建立映射关系。

  

  
  
• 点击“保存”，并在插件保存成功后点击“部署”，将编解码插件部署到物联网平台。
  

  

  
  
  

调测编解码插件

• 在烟感产品的开发空间，选择“在线调测”，并单击“新增测试设备”，使用真实设备进行调试。
  

  

  说明：

  [color=rgb(102, 106, 117) !important]新添加的设备处于未激活状态，此时不能进行在线调试，可参考连接鉴权，待设备接入平台后，进行调试。

  
  
  
  
• 在弹出的页面中，输入测试设备的参数，设备名称和设备标志码请填写注册设备时输入的设备名称和设备标志码。
  

  

  注：如果使用DTLS传输层安全协议接入时，设备注册方式选择“加密”，且请妥善保存PSK码。

  
  
• 单击“调试”，进入调试界面。
  

  

  
  
• 使用设备模拟器进行数据上报。
  

  十六进制码流示例：000100F1。00表示messageId，此消息上报火灾等级和温度；01表示火灾级别，长度为1个字节；00F1表示温度，长度为2个字节。

  在“应用模拟器”区域查看数据上报的结果：{level=1, temperature=241}。1为十六进制数01转换为十进制的数值；241为十六进制数00F1转换为十进制的数值。

  

  十六进制码流示例：0100F1。01表示messageId，此消息只上报火灾温度；00F1表示温度，长度为2个字节。

  在“应用模拟器”区域查看数据上报的结果：{temperature=241}。241为十六进制数00F1转换为十进制的数值。

  

  
  
• 使用应用模拟器进行命令下发：{ "serviceId": "Smoke", "method": "SET_ALARM", "paras": "{\"value\":1}" }。
  

  在“设备模拟器”区域查看命令接收的结果：01。01为十进制数1转换为十六进制的数值。

  

  
  
  

字符串及可变长字符串的编解码插件在线开发

如果该烟感设备需要支持描述信息上报功能，描述信息支持字符串和可变长度字符串两种类型，则按照以下步骤创建消息。

Profile定义

在烟感产品的开发空间完成Profile定义。

编解码插件开发

• 在烟感产品的开发空间，选择“编解码插件开发”。
  

  

  
  
• 配置数据上报消息，上报字符串类型的描述信息。
  

  

  添加messageId字段，表示消息种类。在本场景中，0x0用于标识上报火灾等级和温度的消息，0x1用于标识只上报温度的消息，0x2用于标识上报描述信息（字符串类型）的消息。

  

  添加other_info字段，表示字符串类型的描述信息。在本场景中，“长度”配置 6个字节。

  

  
  
• 配置数据上报消息，上报可变长度字符串类型的描述信息。
  

  

  添加messageId字段，表示消息种类。在本场景中，0x0用于标识上报火灾等级和温度的消息，0x1用于标识只上报温度的消息，0x3用于标识上报描述信息（可变长度字符串类型）的消息。

  

  添加length字段，表示字符串长度。“数据类型”根据可变长度字符串的长度进行配置，长度在255以内，配置为“int8u”。

  

  添加other_info字段，表示可变长度字符串类型的描述信息。“长度关联字段”选择“length”，“长度关联字段差值”和“数值长度”自动填充。

  

  
  
• 拖动右侧“设备模型”区域的属性字段，与数据上报消息的相应字段建立映射关系。
  

  

  
  
• 点击“保存”，并在插件保存成功后点击“部署”，将编解码插件部署到物联网平台。
  

  

  
  
  

调测编解码插件

• 在烟感产品的开发空间，选择“在线调测”，并单击“新增测试设备”，使用真实设备进行调试。
  

  

  说明：

  [color=rgb(102, 106, 117) !important]新添加的设备处于未激活状态，此时不能进行在线调试，可参考连接鉴权，待设备接入平台后，进行调试。

  
  
  
  
• 在弹出的页面中，输入测试设备的参数，设备名称和设备标志码请填写注册设备时输入的设备名称和设备标志码。
  

  

  注：如果使用DTLS传输层安全协议接入时，设备注册方式选择“加密”，且请妥善保存PSK码。

  
  
• 单击“调试”，进入调试界面。
  

  

  
  
  
• 使用设备模拟器上报字符串类型的描述信息。
  

  十六进制码流示例：0231。02表示messageId，此消息上报字符串类型的描述信息；31表示描述信息，长度为1个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=null}。描述信息不足6个字节，编解码插件无法解析。

  

  十六进制码流示例：02313233343536。02表示messageId，此消息上报字符串类型的描述信息；313233343536表示描述信息，长度为6个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=123456}。描述信息长度为6个字节，编解码插件解析成功。

  

  十六进制码流示例：023132333435363738。02表示messageId，此消息上报字符串类型的描述信息；3132333435363738表示描述信息，长度为8个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=123456}。描述信息长度超过6个字节，编解码插件截取前6个字节进行解析。

  

  十六进制码流示例：02013132333435。02表示messageId，此消息上报字符串类型的描述信息；013132333435表示描述信息，长度为6个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=\u000112345}。01在ASCII码表里表示“标题开始”，无法用具体字符表示，因此编解码插件解析为\u0001。

  

  
  
• 使用设备模拟器上报可变长度字符串类型的描述信息。
  

  十六进制码流示例：030141。03表示messageId，此消息上报可变长度字符串类型的描述信息；01表示描述信息长度（1个字节），长度为1个字节；41表示描述信息，长度为1个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=A}。41是A的十六进制ASCII码。

  

  十六进制码流示例：03024142。03表示messageId，此消息上报可变长度字符串类型的描述信息；02表示描述信息长度（2个字节），长度为1个字节；4142表示描述信息，长度为2个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=AB}。4142是AB的十六进制ASCII码。

  

  十六进制码流示例：030341424344。03表示messageId，此消息上报可变长度字符串类型的描述信息；03表示描述信息长度（3个字节），长度为1个字节；41424344表示描述信息，长度为4个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=ABC}。描述信息长度超过3个字节，编解码插件截取前3个字节进行解析，414243是ABC的十六进制ASCII码。

  

  十六进制码流示例：0304414243。03表示messageId，此消息上报可变长度字符串类型的描述信息；04表示字符串长度（4个字节），长度为1个字节；414243表示描述信息，长度为4个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=null}。描述信息长度不足4个字节，编解码插件解析失败。

  

  
  
  

总结

• 当数据类型为字符串或可变长度字符串时，插件是按照ASCII码进行编解码的：上报数据时，将16进制码流解码为对应字符串，比如：21解析为“!”、31解析为“1”、41解析为“A”；下发命令时，将字符串编码对应的16进制码流，比如：“！”编码为21，“1”编码为31，“A”编码为41。
• 当某字段的数据类型为可变长度字符串时，该字段需要关联长度字段，长度字段的数据类型必须为int。
• 针对可变长度字符串，命令下发和数据上报的编解码插件开发方式相同。
• 在线开发的编解码插件使用ASCII码16进制的标准表对字符串和可变长度字符串进行编解码。解码时（数据上报），如果解析结果无法使用具体字符表示，如：标题开始、正文开始、正文结束等，则使用\u+2字节码流值表示（例如：01解析为\u0001，02解析为\u0002）；如果解析结果可以使用具体字符表示，则使用具体字符。
  

数组及可变长数组数据类型

如果该烟感设备需要支持描述信息上报功能，描述信息描述信息支持数组和可变长度数组两种类型，则按照以下步骤创建消息。

Profile定义

在烟感产品的开发空间完成Profile定义。

编解码插件开发

• 在烟感产品的开发空间，选择“编解码插件开发”。
  

  

  
  
• 配置数据上报消息，上报数组类型的描述信息。
  

  

  
  

  添加messageId字段，表示消息种类。在本场景中，0x0用于标识上报火灾等级和温度的消息，0x1用于标识只上报温度的消息，0x2用于标识上报描述信息（数组类型）的消息。

  

  添加other_info字段，表示数组类型的描述信息。在本场景中，“长度”配置为5个字节。

  

  
  
• 配置数据上报消息，上报可变长度数组类型的描述信息。
  

  

  添加messageId字段，表示消息种类。在本场景中，0x0用于标识上报火灾等级和温度的消息，0x1用于标识只上报温度的消息，0x3用于标识上报描述信息（可变长度数组类型）的消息。

  

  添加length字段，表示数组长度。“数据类型”根据可变长度数组的长度进行配置，长度在255以内，配置为“int8u”。

  

  添加other_info字段，表示可变长度数组类型的描述信息。“长度关联字段”选择“length”，“长度关联字段差值”和“数值长度”自动填充。

  

  
  
• 拖动右侧“设备模型”区域的属性字段，与数据上报消息的相应字段建立映射关系。
  

  

  
  
• 点击“保存”，并在插件保存成功后点击“部署”，将编解码插件部署到物联网平台。
  

  

  
  
  

调测编解码插件

• 在烟感产品的开发空间，选择“在线调测”，并单击“新增测试设备”，使用真实设备进行调试。
  

  

  说明：

  [color=rgb(102, 106, 117) !important]新添加的设备处于未激活状态，此时不能进行在线调试，可参考连接鉴权，待设备接入平台后，进行调试。

  
  
  
  
• 在弹出的页面中，输入测试设备的参数，设备名称和设备标志码请填写注册设备时输入的设备名称和设备标志码。
  

  

  注：如果使用DTLS传输层安全协议接入时，设备注册方式选择“加密”，且请妥善保存PSK码。

  
  
• 单击“调试”，进入调试界面。
  

  

  
  
  
• 使用设备模拟器上报数组类型的描述信息。
  

  十六进制码流示例：0211223344。02表示messageId，此消息上报数组类型的描述信息；11223344表示描述信息，长度为4个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=null}。描述信息不足5个字节，编解码插件无法解析。

  

  十六进制码流示例：021122334455。02表示messageId，此消息上报数组类型的描述信息；1122334455表示描述信息，长度为5个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=ESIzRF=}。描述信息长度为5个字节，编解码插件解析成功。

  

  十六进制码流示例：02112233445566。02表示messageId，此消息上报数组类型的描述信息；112233445566表示描述信息，长度为6个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=ESIzRF=}。描述信息长度超过5个字节，编解码插件截取前5个字节进行解析。

  

  
  
• 使用设备模拟器上报可变长度数组类型的描述信息。
  

  十六进制码流示例：030101。03表示messageId，此消息上报可变长度数组类型的描述信息；01表示描述信息长度（1个字节），长度为1个字节；01表示描述信息，长度为1个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=AQ==}。AQ==是01经过base64编码后的值。

  

  十六进制码流示例：03020102。03表示messageId，此消息上报可变长度数组类型的描述信息；02表示描述信息长度（2个字节），长度为1个字节；0102表示描述信息，长度为2个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=AQI=}。AQI=是01经过base64编码后的值。

  

  十六进制码流示例：03030102。03表示messageId，此消息上报可变长度数组类型的描述信息；03表示描述信息长度（3个字节），长度为1个字节；0102表示描述信息，长度为2个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=null}。描述信息长度不足3个字节，编解码插件解析失败。

  

  十六进制码流示例：0303010203。03表示messageId，此消息上报可变长度数组类型的描述信息；03表示描述信息长度（3个字节），长度为1个字节；010203表示描述信息，长度为3个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=AQID}。AQID是010203经过base64编码后的值。

  

  十六进制码流示例：030301020304。03表示messageId，此消息上报可变长度数组类型的描述信息；03表示描述信息长度（3个字节），长度为1个字节；01020304表示描述信息，长度为4个字节。

  在“应用模拟器”区域查看数据上报的结果：{other_info=AQID}。描述信息长度超过3个字节，编解码插件截取前3个字节进行解析，AQID是010203经过base64编码后的值。

  

  
  
  

base64编码方式说明

base64编码方式会把3个8位字节（3*8=24）转化为4个6位字节（4*6=24），并在每个6位字节前补两个0，构成4个8位字节的形式。如果要进行编码的码流不足3个字节，则在码流后用0填充，使用0填充的字节经编码输出的字符为“=”。

base64可以将16进制码流当做字符或者数值进行编码，两种方式获得的编码结果不同。以16进制码流01为例进行说明：

• 把01当作字符，不足3个字符，补1个0，得到010。通过查询ASCII码表，将字符转换为8位二进制数，即：0转换为00110000、1转换为00110001，因此010可以转换为001100000011000100110000（3*8=24）。再转换为4个6位字节：001100、000011、000100、110000，并在每个6位字节前补两个0，得到：00001100、00000011、00000100、00110000。这4个8位字节对应的10进制数分别为12、3、4、48，通过查询base64编码表，获得M（12）、D（3）、E（4），由于3个字符中，最后一个字符通过补0获得，因此第4个8位字节使用“=”表示。最终，把01当做字符，通过base64编码得到MDE=。
• 把01当作数值（即1），不足3个字符，补两个0，得到100。将数值转换为8位2进制数，即：0转换为00000000、1转换为00000001，因此100可以转换为000000010000000000000000（3*8=24）。在转换为4个6位字节：000000、010000、000000、000000，并在每个6位字节前补两个0，得到：00000000、00010000、00000000、00000000。这4个8位字节对应的10进制数分别为：0、16、0、0，通过查询base64编码表，获得A（0）、Q（16），由于3个数值中，最后两个数值通过补0获得，因此第3、4个8位字节使用“=”表示。最终，把01当作数值，通过base64编码得到AQ==。
  

总结

• 当数据类型为数组或可变长度数组时，插件是按照base64进行编解码的：上报数据时，将16进制码流进行base64编码，比如：01编码为“AQ==”；命令下发时，将字符进行base64解码，比如：“AQ==”解码为01。
• 当某字段的数据类型为可变长度数组时，该字段需要关联长度字段，长度字段的数据类型必须为int。
• 针对可变长度数组，命令下发和数据上报的编解码插件开发方式相同。
• 在线开发的编解码插件使用base64进行编码时，是将16进制码流当做数值进行编码。
  

含命令执行结果的编解码插件

如果该烟感设备需要支持支持上报命令执行结果，则按照以下步骤创建消息。

Profile定义

在烟感产品的开发空间完成Profile定义。

编解码插件开发

• 在烟感产品的开发空间，选择“插件开发”。
  

  

  
  
• 配置命令下发消息。
  

  

  添加messageId字段，表示消息种类。如果只有一种命令下发消息，则可以不配置此字段。

  

  添加mid字段，用于将下发的命令和命令执行结果进行关联。

  

  添加value字段，表示下发命令的参数值。

  

  
  
• 配置命令下发响应消息。
  

  添加messageId，表示消息种类。命令执行结果为上行消息，需要通过messageId和数据上报消息进行区分。

  

  添加mid字段，用于将下发的命令和命令执行结果进行关联。

  

  添加errcode字段，用于表示命令执行状态：00表示成功，01表示失败，如果未携带该字段，则默认命令执行成功。

  

  添加result字段，用于表示命令执行结果。

  

  
  
• 拖动右侧“设备模型”区域的属性字段和命令字段，数据上报消息和命令下发消息的相应字段建立映射关系。
  

  

  
  
• 点击“保存”，并在插件保存成功后点击“部署”，将编解码插件部署到物联网平台。
  

  

  
  
  

调测编解码插件

• 在烟感产品的开发空间，选择“在线调测”，并单击“新增测试设备”，使用真实设备进行调试。
  

  

  说明：

  [color=rgb(102, 106, 117) !important]新添加的设备处于未激活状态，此时不能进行在线调试，可参考连接鉴权，待设备接入平台后，进行调试。

  
  
  
  
• 在弹出的页面中，输入测试设备的参数，设备名称和设备标志码请填写注册设备时输入的设备名称和设备标志码。
  

  

  注：如果使用DTLS传输层安全协议接入时，设备注册方式选择“加密”，且请妥善保存PSK码。

  
  
• 单击“调试”，进入调试界面。
  

  

  
  
  
• 使用应用模拟器进行命令下发：{ "serviceId": "Smoke", "method": "SET_ALARM", "paras": "{\"value\":0}" }。
  

  在“设备模拟器”区域查看命令接收的结果：01000100。01为messageId字段，0001为mid字段，00为value字段。

  

  
  
• 使用设备模拟器进行数据上报。
  

  十六进制码流示例：0200010000。02表示messageId，此消息上报命令执行结果；0001表示mid，长度为2个字节；00表示命令执行状态，长度为1个字节；00表示命令执行结果，长度为1个字节。

  在“设备详情 > 历史命令”查看命令执行状态：执行成功。

  

  
  
  

总结

• 如果插件需要对命令执行结果进行解析，则必须在命令和命令响应中定义mid字段。
• 命令下发的mid是2个字节，对于每个设备来说，mid从1递增到65535，对应码流为0001到FFFF。
• 设备执行完命令，命令执行结果上报中的mid要与收到命令中的mid保持一致，这样平台才能刷新对应命令的状态。