设备接入 IoTDA设备接入 IoTDA

更新时间:2021/07/21 GMT+08:00
分享

图形化开发插件

当前华为物联网平台编解码插件的开发只针对NB-IoT设备。

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

本节首先以一个NB-IoT烟感设备的例子讲解如何开发一个支持数据上报和命令下发的编解码插件,并且支持上报命令执行结果,然后再以两个场景举例说明如何完成复杂的插件开发以及调试。

数据上报和命令下发

场景说明

有一款烟感设备,具有如下特征:

  • 具有烟雾报警功能(火灾等级)和温度上报功能。
  • 支持远程控制命令,可远程打开报警功能。比如火灾现场温度,远程打开烟雾报警,提醒住户疏散。
  • 支持上报命令执行结果。

产品模型定义

在烟感产品的开发空间,完成产品模型定义。
  • level:火灾级别,用于表示火灾的严重程度。
  • temperature:温度,用于表示火灾现场温度。
  • SET_ALARM:打开或关闭告警命令,value=0表示关闭,value=1表示打开。

编解码插件开发

  1. 在烟感产品的开发空间,选择“插件开发”,单击“图形化开发”。
  2. 单击“新增消息”,新增“smokerinfo”消息。配置此步骤的主要目的是,将设备上传的二进制码流消息解码成JSON格式,以便物联网平台理解。配置示例如下:

    • 消息名:smokerinfo
    • 消息类型:数据上报。
    • 添加响应字段:是。添加响应字段后,物联网平台在收到设备上报的数据后,会下发用户设置的响应数据到设备。
    • 响应数据:AAAA0000(默认)

    1. 单击“添加字段”,勾选“标记为地址域”,添加messageId字段,表示消息类型。在本场景中,上报火灾等级和温度的消息类型是0x0。设备上报消息时,每条消息首个字段就是messageId。如设备上报消息为0001013A,第一个字段00就是表示此条消息是上报火灾级别和温度的消息。后续字段01和013A分别代表火灾级别和温度。如果只有一条数据上报消息和一条命令下发消息,可以不添加messageId字段。
      • “数据类型”根据数据上报消息种类的数量进行配置。messageId字段默认的数据类型为int8u。
      • “偏移值”是根据字段位置和字段的字节数的配置自动填充的。messageId为此消息的第一个字段,起始位置为0,字节长度为1,终点位置为1。所以偏移值为0-1。
      • “长度”是根据“数据类型”的配置自动填充的。
      • “默认值”可以修改,但必须为十六进制格式,且设备数据上报消息的对应字段必须和此处的默认值保持一致。

    2. 添加level字段,表示火灾级别。
      • “字段名”只能输入包含字母、数字、_和$,且不能以数字开头的字符。
      • “数据类型”根据设备上报数据的实际情况进行配置,需要和产品模型相应字段的定义相匹配。产品模型中定义的火灾级别level属性的数据类型为int,最大值为9。所以选择的数据类型为int8u。
      • “偏移值”是根据字段位置和字段的字节数的配置自动填充的。“level”字段的起始位置就是前一字段的终点,前一字段“messageId”的终点位置为1,所以“level”字段的起始位置为1。“level”字段长度为1个字节,终点为2。所以“偏移值”为1-2。
      • “长度”根据“数据类型”的配置自动填充。
      • “默认值”不填。此处火灾级别level不固定,无默认值。

    3. 添加temperature字段,表示温度。
      • “数据类型”,在产品模型中,temperature属性的“数据类型”为int,最大值1000,因此在插件中定义temperature字段的“数据类型”“int16u”,以满足temperature属性的取值范围。
      • “偏移值”是根据与首字段的间隔的字符数自动配置的。“temperature”字段的起始位置就是前一字段的终点,前一字段“level”的终点位置为2,所以“temperature”字段的起始位置为2。“temperature”字段长度为2个字节,终点为4。所以“偏移值”为2-4。
      • “长度”根据数据类型的配置自动填充。
      • “默认值”不填,此处温度temperature的值不固定,无默认值。

  3. 单击“新增消息”,新增“SET_ALARM”消息,设置火灾告警的温度阈值。例如超过60摄氏度,设备上报告警。配置此步骤的主要目的是,将平台下发的JSON格式命令消息编码成二进制数据,以便烟感设备理解。配置示例如下:

    • 消息名:SET_ALARM
    • 消息类型:命令下发
    • 添加响应字段:是。添加响应字段后,设备在接收命令后,可以上报命令执行结果。您可以根据自己的需求,选择是否添加响应字段。
      1. 单击“添加字段”,添加messageId字段,表示消息类型。例如,设置火灾告警阈值的消息类型为0x3。messageId、数据类型、长度、默认值、偏移值的说明可参考1

      2. 添加mid字段。这里的mid字段是由平台生成和下发的,用于将下发的命令和命令下发响应消息关联。mid字段的数据类型默认为int16u。长度、默认值、偏移值的说明可参考2

      3. 添加value字段,表示下发命令的参数值。例如,下发火灾告警的温度阈值。数据类型、长度、默认值、偏移值的说明可以参考2

      4. 单击“添加响应字段”,添加“messageId”字段,表示消息类型。命令下发响应消息为上行消息,需要通过messageId和数据上报消息进行区分。上报火灾告警温度阈值的消息类型为0x4。messageID、数据类型、长度、默认值、偏移值的说明可参考1

      5. 添加mid字段。这里的mid字段需要跟平台下发的命令里的mid字段保持一致,用于将下发的命令和命令执行结果进行关联。mid字段的数据类型默认为int16u。长度、默认值、偏移值的说明可参考2

      6. 添加errcode字段,用于表示命令执行状态:00表示成功,01表示失败,如果未携带该字段,则默认命令执行成功。errcode字段的数据类型默认为int8u。长度、默认值、偏移值的说明可参考2

      7. 添加result字段,用于表示命令执行结果。例如,设备向平台返回当前的告警阈值。

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

  5. 单击“保存”,并在插件保存成功后单击“部署”,将编解码插件部署到物联网平台。

调测编解码插件

  1. 在烟感产品的开发空间,选择“在线调试”,并单击“新增测试设备”。
  2. 用户可根据自己的业务场景,选择使用真实设备或者模拟设备进行调测。具体请参考在线调试。本文以模拟设备为例,调测编解码插件。

    在弹出的“新增测试设备”窗口,选择“模拟设备”,单击“确定”,创建一个虚拟设备。虚拟设备名称包含 “Simulator”字样,每款产品下只能创建一个虚拟设备。

  3. 单击“调试”,进入调试界面。

  4. 使用设备模拟器进行数据上报。十六进制码流示例:0008016B。00为地址域meaasgeID,08表示火灾级别level,长度为1个字节;016B表示温度,长度为2个字节。

    “应用模拟器”区域查看数据上报的结果:{level=8, temperature=363}。8为十六进制数08转换为十进制的数值;363为十六进制数016B转换为十进制的数值。

    在设备模拟器区域看到平台下发的响应数据AAAA0000。

  5. 使用应用模拟器进行命令下发,输入value值为1,可看到应用模拟下发命令{ "serviceId": "Smokeinfo", "method": "SET_ALARM", "paras": "{\"value\":1}" }。

    “设备模拟器”区域查看命令接收的结果:03000E01。03为地址域messageID,000E为mid字段,01为十进制数1转换为十六进制的数值。

总结

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

字符串及可变长字符串的编解码插件

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

产品模型定义

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

编解码插件开发

  1. 在烟感产品的开发空间,选择“插件开发”,单击“图形化开发”。
  2. 单击“新增消息”,新增消息“otherinfo”,上报字符串类型的描述信息。配置此步骤的主要目的是,将设备上传的字符串二进制码流消息解码成JSON格式,以便物联网平台理解。配置示例如下:

    • 消息名:otherinfo
    • 消息类型:数据上报
    • 添加响应字段:是。添加响应字段后,物联网平台在收到设备上报的数据后,会下发用户设置的响应数据到设备。
    • 响应数据:AAAA0000(默认)

    1. 单击“添加字段”,添加messageId字段,表示消息种类。在本场景中,0x0用于标识上报火灾等级和温度的消息,0x1用于标识只上报温度的消息,0x2用于标识上报描述信息(字符串类型)的消息。messageID、数据类型、长度、默认值、偏移值的说明可参考1

    2. 添加other_info字段,表示字符串类型的描述信息。在本场景中,字符串类型的字段数据类型选择“string”,“长度”配置 6个字节。字段名、默认值、偏移值的说明可参考2

  3. 单击“新增消息”,新增“other_info2”消息名,配置数据上报消息,上报可变长度字符串类型的描述信息。配置此步骤的主要目的是,将设备上传的可变长度字符串二进制码流消息解码成JSON格式,以便物联网平台理解。配置示例如下:

    • 消息名:other_info2
    • 消息类型:数据上报
    • 添加响应字段:是。添加响应字段后,物联网平台在收到设备上报的数据后,会下发用户设置的响应数据到设备。
    • 响应数据:AAAA0000(默认)

    1. 添加messageId字段,表示消息种类。在本场景中,0x0用于标识上报火灾等级和温度的消息,0x1用于标识只上报温度的消息,0x3用于标识上报描述信息(可变长度字符串类型)的消息。messageID、数据类型、长度、默认值、偏移值的说明可参考1

    2. 添加length字段,表示可变字符串长度。“数据类型”根据可变长度字符串的长度进行配置,此场景可变字符串长度在255以内,配置为“int8u”。长度、默认值、偏移值的说明可参考2

    3. 添加other_info字段,数据类型选择“varstring”,表示可变长度字符串类型的描述信息。“长度关联字段”选择“length”“长度关联字段差值”“数值长度”自动填充。“掩码”默认为“0xff”。偏移值说明可参考2

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

  5. 单击“保存”,并在插件保存成功后单击“部署”,将编解码插件部署到物联网平台。

调测编解码插件

  1. 在烟感产品的开发空间,选择“在线调试”,并单击“新增测试设备”。
  2. 用户可根据自己的业务场景,选择使用真实设备或者模拟设备进行调测。具体请参考在线调试。本文以模拟设备为例,调测编解码插件。

    在弹出的“新增测试设备”窗口,选择“模拟设备”,单击“确定”,创建一个虚拟设备。虚拟设备名称包含 “Simulator”字样,每款产品下只能创建一个虚拟设备。

  3. 单击“调试”,进入调试界面。

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

    十六进制码流示例: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。

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

    十六进制码流示例: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);如果解析结果可以使用具体字符表示,则使用具体字符。

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

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

产品模型定义

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

编解码插件开发

  1. 在烟感产品的开发空间,选择“插件开发”,单击“图形化开发”。
  2. 单击“新增消息”,新增消息“otherinfo”,上报数组类型的描述信息。配置此步骤的主要目的是,将设备上传的数组二进制码流消息解码成JSON格式,以便物联网平台理解。配置示例如下:

    • 消息名:otherinfo
    • 消息类型:数据上报
    • 添加响应字段:是。添加响应字段后,物联网平台在收到设备上报的数据后,会下发用户设置的响应数据到设备。
    • 响应数据:AAAA0000(默认)

    1. 单击“添加字段”,添加messageId字段,表示消息种类。在本场景中,0x0用于标识上报火灾等级和温度的消息,0x1用于标识只上报温度的消息,0x2用于标识上报描述信息(数组类型)的消息。messageID、数据类型、长度、默认值、偏移值的说明可参考1

    2. 添加other_info字段,“数据类型”选择“array”,表示数组类型的描述信息。在本场景中,“长度”配置为5个字节。字段名、默认值、偏移值的说明可参考2

  3. 单击“新增消息”,新增“other_info2”消息,上报可变长度数组类型的描述信息。配置此步骤的主要目的是,将设备上传的可变长度数组二进制码流消息解码成JSON格式,以便物联网平台理解。配置示例如下:

    • 消息名:other_info2
    • 消息类型:数据上报
    • 添加响应字段:是。添加响应字段后,物联网平台在收到设备上报的数据后,会下发用户设置的响应数据到设备。
    • 响应数据:AAAA0000(默认)

    1. 单击“添加字段”,添加messageId字段,表示消息种类。在本场景中,0x0用于标识上报火灾等级和温度的消息,0x1用于标识只上报温度的消息,0x3用于标识上报描述信息(可变长度数组类型)的消息。messageID、数据类型、长度、默认值、偏移值的说明可参考1

    2. 添加length字段,表示数组长度。“数据类型”根据可变长度数组的长度进行配置,长度在255以内,配置为“int8u”。长度、默认值、偏移值的说明可参考2

    3. 添加other_info字段,“数据类型”选择“variant”,表示可变长度数组类型的描述信息。“长度关联字段”选择“length”“长度关联字段差值”“数值长度”自动填充。“掩码”默认为“0xff”。偏移值说明可参考2

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

  5. 单击“保存”,并在插件保存成功后单击“部署”,将编解码插件部署到物联网平台。

调测编解码插件

  1. 在烟感产品的开发空间,选择“在线调试”,并单击“新增测试设备”。
  2. 用户可根据自己的业务场景,选择使用真实设备或者模拟设备进行调测。具体请参考在线调试。本文以模拟设备为例,调测编解码插件。

    在弹出的“新增测试设备”窗口,选择“模拟设备”,单击“确定”,创建一个虚拟设备。虚拟设备名称包含 “Simulator”字样,每款产品下只能创建一个虚拟设备。

  3. 单击“调试”,进入调试界面。

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

    十六进制码流示例: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个字节进行解析。

  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进制码流当做数值进行编码。
分享:

    相关文档

    相关产品