离线开发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模板，修改设备型号标识属性和设备服务列表。
说明：
物联网平台提供的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的合法性。
