更新时间:2024-07-03 GMT+08:00

离线开发产品模型

概述

产品模型本质上就是一个devicetype-capability.json文件和若干个serviceType-capability.json文件,其中devicetype-capability.json是描述产品模型包含的服务能力的文件,serviceType-capability.json文件是用于描述devicetype-capability.json文件中的service_capabilities的每一个能力的详细描述。按照如下目录打包的一个zip包。其中WaterMeter是deviceType,TestUtf8Manuld是manufactureId,WaterMeterBasic/WaterMeterAlarm/Battery是服务类型。

所以离线开发产品模型就是按照产品模型编写规则和JSON格式规范在devicetype-capability.json中定义设备能力,在servicetype-capability.json中定义服务能力。因此离线开发产品模型需要熟悉JSON的格式。

由于离线开发产品模型文件相对在线开发比较耗时,因此推荐在线开发产品模型

命名规范

在产品模型的开发过程中,需要遵循如下命名规范:

  • 设备类型(deviceType)、服务类型(serviceType)、服务标识(serviceId)采用单词首字母大写的命名法。例如:WaterMeter、Battery。
  • 属性使用第一个单词首字母小写,其余单词的首字母大写的命名法。例如:batteryLevel、internalTemperature。
  • 命令使用所有字母大写,单词间用下划线连接的格式。例如:DISCOVERY,CHANGE_COLOR。
  • 设备能力描述json文件固定命名devicetype-capability.json。
  • 服务能力描述json文件固定命名servicetype-capability.json。
  • 厂商id在不同的产品模型文件中不能重复,且仅支持英文。
  • 要注重名称的通用性,简洁性;对于服务能力描述,还要考虑其功能性。例如:对于多传感器设备,可以命名为MultiSensor;对于具有显示电量的服务,可以命名为Battery。

产品模型模板

将一款新设备接入到物联网平台,首先需要编写这款设备的产品模型。物联网平台提供了一些产品模型文件模板,如果新增接入设备的类型和功能服务已经在物联网平台提供的设备产品模型模板中包含,则可以直接选择使用;如果在物联网平台提供的设备产品模型模板中未包含,则需要自己定义。

例如:接入一款水表 ,可以直接选择物联网平台上对应的产品模型模板,修改设备服务列表。

物联网平台提供的产品模型模板会不断更新,如下表格列举设备类型和服务类型示例,仅供参考。

设备类型识别属性:

属性

产品模型中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]

目前本字段是非功能性字段,仅起到描述作用,建议准确定义。

产品模型打包

产品模型写作完成后,需要按如下层级结构打包:

产品模型打包需要遵循如下几点要求:

  • 产品模型文件的目录层级结构必须如上图所示,不能增删。例如:第二层级只能有“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的合法性。