# 离线开发产品模型 #### 概述 产品模型本质上就是一个**devicetype-capability.json** 文件和若干个**serviceType-capability.json** 文件，其中**devicetype-capability.json** 是描述产品模型包含的服务能力的文件，**serviceType-capability.json** 文件是用于描述**devicetype-capability.json**文件中的service_capabilities的每一个能力的详细描述。按照如下目录打包的一个zip包。其中WaterMeter是deviceType，TestUtf8ManuId是manufactureId，WaterMeterBasic/WaterMeterAlarm/Battery是服务类型。 ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0263668818.png "点击放大") 因为离线开发产品模型就是按照产品模型编写规则和JSON格式规范在devicetype-capability.json中定义设备能力，在servicetype-capability.json中定义服务能力，所以离线开发产品模型需要熟悉JSON的格式。 由于离线开发产品模型文件相对在线开发比较耗时，因此推荐[在线开发产品模型](https://support.huaweicloud.com/devg-iothub/iot_02_0005.html)。 #### 命名规范 在产品模型的开发过程中，需要遵循如下命名规范： - 设备类型（deviceType）、服务类型（serviceType）、服务标识（serviceId）采用单词首字母大写的命名法。例如：WaterMeter、Battery。 - 属性使用第一个单词首字母小写，其余单词的首字母大写的命名法。例如：batteryLevel、internalTemperature。 - 命令使用所有字母大写，单词间用下划线连接的格式。例如：DISCOVERY，CHANGE_COLOR。 - 设备能力描述json文件固定命名devicetype-capability.json。 - 服务能力描述json文件固定命名servicetype-capability.json。 - 厂商id在不同的产品模型文件中不能重复，且仅支持英文。 - 要注重名称的通用性，简洁性；对于服务能力描述，还要考虑其功能性。例如：对于多传感器设备，可以命名为MultiSensor；对于具有显示电量的服务，可以命名为Battery。 #### 产品模型模板 将一款新设备接入到物联网平台，首先需要编写这款设备的产品模型。物联网平台提供了一些产品模型文件模板，如果新增接入设备的类型和功能服务已经在物联网平台提供的设备产品模型模板中包含，则可以直接选择使用；如果在物联网平台提供的设备产品模型模板中未包含，则需要自己定义。 例如：接入一款水表 ，可以直接选择物联网平台上对应的产品模型模板，修改设备服务列表。 ![](https://support.huaweicloud.com/devg-iothub/public_sys-resources/note_3.0-zh-cn.png) 物联网平台提供的产品模型模板会不断更新，如下表格列举设备类型和服务类型示例，仅供参考。 **设备类型识别属性：** | 属性 | 产品模型JSON文件key | 属性值 | |:---|:---|:---| | 设备类型 | deviceType | WaterMeter | | 厂商ID | manufacturerId | TestUtf8ManuId | | 厂商名称 | manufacturerName | HZYB | | 协议类型 | 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", "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 | - | 必选 | 指示设备的制造商名称 （只允许英文）。 | | - | 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。 上报数据时，复杂类型数据格式如下： - string list：\["str1","str2","str3"\] - DateTime：yyyyMMdd'T'HHmmss'Z'如:20151212T121212Z - jsonObject：自定义json结构体，物联网平台不解析，仅进行透传 | | - | - | - | 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 上报数据时，复杂类型数据格式如下： - string list：\["str1","str2","str3"\] - DateTime：yyyyMMdd'T'HHmmss'Z'如:20151212T121212Z - jsonObject：自定义json结构体，物联网平台不解析，仅进行透传 | | - | - | - | - | 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 上报数据时，复杂类型数据格式如下： - string list：\["str1","str2","str3"\] - DateTime：yyyyMMdd'T'HHmmss'Z'如:20151212T121212Z - jsonObject：自定义json结构体，物联网平台不解析，仅进行透传 | | - | - | 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\] 目前本字段是非功能性字段，仅起到描述作用，建议准确定义。 | #### 产品模型打包 产品模型写作完成后，需要按如下层级结构打包： ![](https://support.huaweicloud.com/devg-iothub/figure/zh-cn_image_0263669248.png "点击放大") 产品模型打包需要遵循如下几点要求： - 产品模型文件的目录层级结构必须如上图所示，不能增删。例如：第二层级只能有"profile"和"service"两个文件夹，每个服务下面必须包含"profile"文件夹等。 - 产品模型文件以zip形式压缩。 - 产品模型文件的命名必须按照deviceType_manufacturerId的格式命名，其中的deviceType、manufacturerId必须与devicetype-capability.json中对应字段的定义一致。例如：本实例中devicetype-capability.json的主要字段如下： ``` { "devices": [ { "manufacturerId": "TestUtf8ManuId", "manufacturerName": "HZYB", "protocolType": "CoAP", "deviceType": "WaterMeter", "serviceTypeCapabilities": **** } ] } ``` - 图中的WaterMeterBasic、WaterMeterAlarm、Battery等都是devicetype-capability.json中定义的服务。 产品模型文件中的文档格式都是JSON，在编写完成后可以在互联网上查找一些格式校验网站，检查JSON的合法性。