离线开发Profile(联通用户专用)
非联通用户请查看设备接入服务。
Profile本质上就是一个devicetype-capability.json文件和若干个serviceType-capability.json文件,按照如下目录打包的一个zip包。其中WaterMeter是deviceType,TestUtf8Manuld是manufactureId,NBIoTDevice是model,WaterMeterBasic/WaterMeterAlarm/Battery是服务名。
所以离线开发profile就是按照Profile编写规则和JSON格式规范在devicetype-capability.json中定义设备能力,在servicetype-capability.json中定义服务能力。因此离线开发Profile需要熟悉JSON的格式。
由于离线开发Profile文件相对在线开发比较耗时,因此推荐在线开发Profile(联通用户专用)。
命名规范
在Profile的开发过程中,需要遵循如下命名规范:
- 设备类型(deviceType)、服务类型(serviceType)、服务标识(serviceId)采用单词首字母大写的命名法。例如:WaterMeter、Battery。
- 属性使用第一个单词首字母小写,其余单词的首字母大写的命名法。例如:batteryLevel、internalTemperature。
- 命令使用所有字母大写,单词间用下划线连接的格式。例如:DISCOVERY,CHANGE_COLOR。
- 设备能力描述json文件固定命名devicetype-capability.json。
- 服务能力描述json文件固定命名servicetype-capability.json。
- 厂商ID和型号唯一标识一款产品,故这些信息的组合在不同的Profile文件中不能重复,且仅支持英文。
- 要注重名称的通用性,简洁性;对于服务能力描述,还要考虑其功能性。例如:对于多传感器设备,可以命名为MultiSensor;对于具有显示电量的服务,可以命名为Battery。
Profile模板
将一款新设备接入到物联网平台,首先需要编写这款设备的Profile。物联网平台提供了一些Profile文件模板,如果新增接入设备的类型和功能服务已经在物联网平台提供的设备Profile模板中包含,则可以直接选择使用;如果在物联网平台提供的设备Profile模板中未包含,则需要自己定义。
例如:接入一款水表 ,可以直接选择物联网平台上对应的Profile模板,修改设备型号标识属性和设备服务列表。
![](https://support.huaweicloud.com/devg-IoT/public_sys-resources/note_3.0-zh-cn.png)
物联网平台提供的Profile模板会不断更新,如下表格列举设备类型和服务类型示例,仅供参考。
设备型号识别属性:
属性 |
Profile中key |
属性值 |
---|---|---|
设备类型 |
deviceType |
WaterMeter |
厂商ID |
manufacturerId |
TestUtf8ManuId |
厂商名称 |
manufacturerName |
HZYB |
型号 |
model |
NBIoTDevice |
协议类型 |
protocolType |
CoAP |
设备的服务列表
服务描述 |
服务标识(serviceId) |
服务类型(serviceType) |
选项(option) |
---|---|---|---|
水表的基本功能 |
WaterMeterBasic |
Water |
Mandatory |
告警服务 |
WaterMeterAlarm |
Battery |
Mandatory |
电池服务 |
Battery |
Battery |
Optional |
数据的上报规则 |
DeliverySchedule |
DeliverySchedule |
Mandatory |
水表的连通性 |
Connectivity |
Connectivity |
Mandatory |
设备能力定义样例
devicetype-capability.json记录了该设备的基础信息:
{ "devices": [ { "manufacturerId": "TestUtf8ManuId", "manufacturerName": "HZYB", "model": "NBIoTDevice", "protocolType": "CoAP", "deviceType": "WaterMeter", "omCapability":{ "upgradeCapability" : { "supportUpgrade":true, "upgradeProtocolType":"PCP" }, "fwUpgradeCapability" : { "supportUpgrade":true, "upgradeProtocolType":"LWM2M" }, "configCapability" : { "supportConfig":true, "configMethod":"file", "defaultConfigFile": { "waterMeterInfo" : { "waterMeterPirTime" : "300" } } } }, "serviceTypeCapabilities": [ { "serviceId": "WaterMeterBasic", "serviceType": "WaterMeterBasic", "option": "Mandatory" }, { "serviceId": "WaterMeterAlarm", "serviceType": "WaterMeterAlarm", "option": "Mandatory" }, { "serviceId": "Battery", "serviceType": "Battery", "option": "Optional" }, { "serviceId": "DeliverySchedule", "serviceType": "DeliverySchedule", "option": "Mandatory" }, { "serviceId": "Connectivity", "serviceType": "Connectivity", "option": "Mandatory" } ] } ] }
各字段的解释:
字段 |
子字段 |
可选/必选 |
描述 |
|
---|---|---|---|---|
devices |
必选 |
包含了一个设备的完整能力信息(根节点不能修改)。 |
||
manufacturerId |
必选 |
指示设备的制造商ID。 |
||
manufacturerName |
必选 |
指示设备的制造商名称 (只允许英文)。 |
||
model |
必选 |
指示设备的型号,考虑到一款设备下的多种型号,建议包含字母或数字以保证可扩展性。 |
||
protocolType |
必选 |
指示设备接入物联网平台的协议类型。如NB-IoT的设备取值为CoAP。 |
||
deviceType |
必选 |
指示设备的类型。 |
||
omCapability |
可选 |
定义设备的软件升级、固件升级和配置更新的能力,字段含义详情见下文中的:omCapability结构描述。 如果设备不涉及软件/固件升级,本字段可以删除。 |
||
serviceTypeCapabilities |
必选 |
包含了设备具备的服务能力描述。 |
||
serviceId |
必选 |
服务的Id,如果设备中同类型的服务类型只有一个则serviceId与serviceType相同, 如果有多个则增加编号,如三键开关 Switch01、Switch02、Switch03。 |
||
serviceType |
必选 |
服务类型,与servicetype-capability.json中serviceType字段保持一致。 |
||
option |
必选 |
标识服务字段的类型,取值范围:Master(主服务), Mandatory(必选服务), Optional(可选服务)。 目前本字段为非功能性字段,仅起到描述作用。 |
omCapability结构描述
字段 |
子字段 |
可选/必选 |
描述 |
---|---|---|---|
upgradeCapability |
可选 |
设备软件升级能力。 |
|
supportUpgrade |
可选 |
true:设备支持软件升级。 false:设备不支持软件升级。 |
|
upgradeProtocolType |
可选 |
升级使用的协议类型,此处不同于设备的protocolType,例如CoAP设备软件升级协议使用PCP。 |
|
fwUpgradeCapability |
可选 |
设备固件升级能力。 |
|
supportUpgrade |
可选 |
true:设备支持固件升级。 false:设备不支持固件升级。 |
|
upgradeProtocolType |
可选 |
升级使用的协议类型,此处不同于设备的protocolType,当前物联网平台仅支持LWM2M固件升级。 |
|
configCapability |
可选 |
设备配置更新能力。 |
|
supportConfig |
可选 |
true:设备支持配置更新。 false:设备不支持配置更新。 |
|
configMethod |
可选 |
file:使用文件的方式下发配置更新。 |
|
defaultConfigFile |
可选 |
设备默认配置信息(Json格式),具体配置信息由设备商自定义。物联网平台只储存该信息供下发时使用,不解析处理配置字段的具体含义。 |
服务能力定义样例
servicetype-capability.json记录了该设备的服务信息:
{ "services": [ { "serviceType": "WaterMeterBasic", "description": "WaterMeterBasic", "commands": [ { "commandName": "SET_PRESSURE_READ_PERIOD", "paras": [ { "paraName": "value", "dataType": "int", "required": true, "min": 1, "max": 24, "step": 1, "maxLength": 10, "unit": "hour", "enumList": null } ], "responses": [ { "responseName": "SET_PRESSURE_READ_PERIOD_RSP", "paras": [ { "paraName": "result", "dataType": "int", "required": true, "min": -1000000, "max": 1000000, "step": 1, "maxLength": 10, "unit": null, "enumList": null } ] } ] } ], "properties": [ { "propertyName": "registerFlow", "dataType": "int", "required": true, "min": 0, "max": 0, "step": 1, "maxLength": 0, "method": "R", "unit": null, "enumList": null }, { "propertyName": "currentReading", "dataType": "string", "required": false, "min": 0, "max": 0, "step": 1, "maxLength": 0, "method": "W", "unit": "L", "enumList": null }, { "propertyName": "timeOfReading", "dataType": "string", "required": false, "min": 0, "max": 0, "step": 1, "maxLength": 0, "method": "W", "unit": null, "enumList": null }, ...... ] } ] }
各字段的解释:
字段 |
子字段 |
必选/可选 |
描述 |
|||
---|---|---|---|---|---|---|
services |
必选 |
包含了一个服务的完整信息(根节点不可修改)。 |
||||
serviceType |
必选 |
指示服务的类型,与devicetype-capability.json中serviceType字段保持一致。 |
||||
description |
必选 |
指示服务的描述信息。 非功能性字段,仅起到描述作用,可置为null。 |
||||
commands |
必选 |
指示设备可以执行的命令,如果本服务无命令则置null。 |
||||
commandName |
必选 |
指示命令的名字,命令名与参数共同构成一个完整的命令。 |
||||
paras |
必选 |
命令包含的参数。 |
||||
paraName |
必选 |
命令中参数的名字。 |
||||
dataType |
必选 |
指示命令参数的数据类型。 取值范围:string、int、string list、decimal、DateTime、jsonObject、enum、boolean。 上报数据时,复杂类型数据格式如下:
|
||||
required |
必选 |
指示本命令是否必选,取值为true或false,默认取值false(非必选)。 目前本字段是非功能性字段,仅起到描述作用。 |
||||
min |
必选 |
指示最小值。 仅当dataType为int、decimal时生效。 |
||||
max |
必选 |
指示最大值。 仅当dataType为int、decimal时生效。 |
||||
step |
必选 |
指示步长。 暂不使用,填0即可。 |
||||
maxLength |
必选 |
指示字符串长度。 仅当dataType为string、string list、DateTime时生效。 |
||||
unit |
必选 |
指示单位,英文。 取值根据参数确定,如: 温度单位:“C”或“K” 百分比单位:“%” 压强单位:“Pa”或“kPa” |
||||
enumList |
必选 |
指示枚举值。 如开关状态status可有如下取值: "enumList" : ["OPEN","CLOSE"] 目前本字段是非功能性字段,仅起到描述作用,建议准确定义。 |
||||
responses |
必选 |
命令执行的响应。 |
||||
responseName |
必选 |
命名可以在该responses对应命令的commandName后面添加“_RSP”。 |
||||
paras |
必选 |
命令响应的参数。 |
||||
paraName |
必选 |
命令中参数的名字。 |
||||
dataType |
必选 |
指示数据类型。 取值范围:string、int、string list、decimal、DateTime、jsonObject 上报数据时,复杂类型数据格式如下:
|
||||
required |
必选 |
指示本命令响应是否必选,取值为true或false,默认取值false(非必选)。 目前本字段是非功能性字段,仅起到描述作用。 |
||||
min |
必选 |
指示最小值。 仅当dataType为int、decimal时生效,逻辑大于等于。 |
||||
max |
必选 |
指示最大值。 仅当dataType为int、decimal时生效,逻辑小于等于。 |
||||
step |
必选 |
指示步长。 暂不使用,填0即可。 |
||||
maxLength |
必选 |
指示字符串长度。 仅当dataType为string、string list、DateTime时生效。 |
||||
unit |
必选 |
指示单位,英文。 取值根据参数确定,如: 温度单位:“C”或“K” 百分比单位:“%” 压强单位:“Pa”或“kPa” |
||||
enumList |
必选 |
指示枚举值。 如开关状态status可有如下取值: "enumList" : ["OPEN","CLOSE"] 目前本字段是非功能性字段,仅起到描述作用,建议准确定义。 |
||||
properties |
必选 |
上报数据描述,每一个子节点为一条属性。 |
||||
propertyName |
必选 |
指示属性名称。 |
||||
dataType |
必选 |
指示数据类型。 取值范围:string、int、string list、decimal、DateTime、jsonObject 上报数据时,复杂类型数据格式如下:
|
||||
required |
必选 |
指示本条属性是否必选,取值为true或false,默认取值false(非必选)。 目前本字段是非功能性字段,仅起到描述作用。 |
||||
min |
必选 |
指示最小值。 仅当dataType为int、decimal时生效,逻辑大于等于。 |
||||
max |
必选 |
指示最大值。 仅当dataType为int、decimal时生效,逻辑小于等于。 |
||||
step |
必选 |
指示步长。 暂不使用,填0即可。 |
||||
method |
必选 |
指示访问模式。 R:可读;W:可写;E:可订阅。 取值范围:R、RW、RE、RWE 、null。 |
||||
unit |
必选 |
指示单位,英文。 取值根据参数确定,如: 温度单位:“C”或“K” 百分比单位:“%” 压强单位:“Pa”或“kPa” |
||||
maxLength |
必选 |
指示字符串长度。 仅当dataType为string、string list、DateTime时生效。 |
||||
enumList |
必选 |
指示枚举值。 如电池状态(batteryStatus)可有如下取值: "enumList" : [0, 1, 2, 3, 4, 5, 6] 目前本字段是非功能性字段,仅起到描述作用,建议准确定义。 |
Profile打包
Profile写作完成后,需要按如下层级结构打包:
Profile打包需要遵循如下几点要求:
- Profile文件的目录层级结构必须如上图所示,不能增删。例如:第二层级只能有“profile”和“service”两个文件夹,每个服务下面必须包含“profile”文件夹等。
- 图中橙色字体的命名不能改动。
- Profile文件以zip形式压缩。
- Profile文件的命名必须按照deviceType_manufacturerId_model的格式命名,其中的deviceType、manufacturerId、model必须与devicetype-capability.json中对应字段的定义一致。例如:本实例中devicetype-capability.json的主要字段如下:
{ "devices": [ { "manufacturerId": "TestUtf8ManuId", "manufacturerName": "HZYB", "model": "NBIoTDevice", "protocolType": "CoAP", "deviceType": "WaterMeter", "serviceTypeCapabilities": **** } ] }
- 图中的WaterMeterBasic、WaterMeterAlarm、Battery等都是devicetype-capability.json中定义的服务。
Profile文件中的文档格式都是JSON,在编写完成后可以在互联网上查找一些格式校验网站,检查JSON的合法性。