Developing a Product Model Offline

Overview

A product model is essentially a ZIP package that combines one devicetype-capability.json file and several serviceType-capability.json files in the following hierarchy, in which WaterMeter indicates the device type, TestUtf8Manuld identifies the manufacturer ID, and WaterMeterBasic, WaterMeterAlarm, and Battery indicates the service types.

In this regard, defining an offline product model is to define device capabilities in the devicetype-capability.json file and service capabilities in the servicetype-capability.json files in JSON format based on the product model definition rules, which is time-consuming and requires familiarity with the JSON format.

Developing a Product Model Online is recommended.

Naming Rules

The product model must comply with the following naming rules:

• Use upper camel case for device types, service types, and service IDs, for example, WaterMeter and Battery.
• Use lower camel case for property names, for example, batteryLevel and internalTemperature.
• For commands, capitalize all characters, with words separated by underscores, for example, DISCOVERY and CHANGE_COLOR.
• Name a device capability profile (.json file) in the format of devicetype-capability.json.
• Name a service capability profile (.json file) in the format of servicetype-capability.json.
• The manufacturer ID must be unique in different product models and can only be in English.
• Names are universal and concise and service capability descriptions clearly indicate corresponding functions. For example, you can name a multi-sensor device MultiSensor and name a service that displays the battery level Battery.

Product Model Templates

To connect a new device to the IoT platform, you must first define a product model for the device. The IoT platform provides some product model templates. If the types and functions of devices newly connected to the IoT platform are included in these templates, directly use the templates. If the types and functions are not included in the product model templates, define your product model.

For example, if a water meter is connected to the IoT platform, you can directly select the corresponding product model on the IoT platform and modify the device service list.

The product model templates provided by the IoT platform are updated continuously. The following uses a water meter as an example to describe how to define a product model.

Device identification properties

Service list

Device Capability Definition Example

The devicetype-capability.json file records basic information about a device.

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

The fields are described as follows:

Description of the omCapability structure

Service Capability Definition Example

The servicetype-capability.json file records service information about a device.

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

The fields are described as follows:

Product Model Packaging

After the product model is completed, package it in the format shown below.

The following requirements must be met for product model packaging:

• The product model hierarchy must be the same as that shown above and cannot be added or deleted. For example, the second level can contain only the profile and service folders, and each service must contain the profile folder.
• The product model is compressed in .zip format.
• The product model must be named in the format of deviceType_manufacturerId. The values of deviceType and manufacturerId must be the same as those in the devicetype-capability.json file. For example, the following provides the main fields of the devicetype-capability.json file.

  {  
      "devices": [  
          {  
              "manufacturerId": "TestUtf8ManuId",  
              "manufacturerName": "HZYB",  
            
              "protocolType": "CoAP",  
              "deviceType": "WaterMeter",  
              "serviceTypeCapabilities": **** 
          }  
      ]  
  }

• WaterMeterBasic, WaterMeterAlarm, and Battery in the figure are services defined in the devicetype-capability.json file.

The product model is in the JSON format. After the product model is edited, you can use format verification websites on the Internet to check the validity of the JSON file.