离线开发产品模型

概述

产品模型本质上就是一个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。

产品模型模板

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

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

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

设备类型识别属性：

设备的服务列表

设备能力定义样例

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"
                }
            ]
        }
    ]
}

各字段的解释：

omCapability结构描述

服务能力定义样例

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
                },
                ......
            ]
        }
    ]
}

各字段的解释：

产品模型打包

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

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

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