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, and WaterMeterBasic/WaterMeterAlarm/Battery indicates the service type.

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

Therefore, Developing a Product Model Online is recommended.

Naming Rules

The profile must comply with the following naming rules:

• Capitalize device types, service types, and service IDs. Example: WaterMeter and Battery.
• Capitalize the first letter of each word in a property name except the first word, for example, batteryLevel and internalTemperature.
• For commands, capitalize all characters, with words separated by underscores. For example: DISCOVERY and CHANGE_COLOR.
• A device capability profile (.json file) must be named devicetype-capability.json.
• A service capability profile (.json file) must be named servicetype-capability.json.
• The manufacturer ID must be unique in different product models and can only be in English.
• You must ensure that 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.

Profile Templates

To connect a new device to the IoT platform, you need to define a profile for the device. The IoT platform provides some profile 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 device profile templates, define your profile.

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 profile template provided by the IoT platform is updated continuously. The following table provides some examples of device types and service types, which are for reference only.

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 profile 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 names in orange cannot be changed.
• The product model is compressed in .zip format.
• The product model must be named in the format of deviceType_manufacturerId. The values of deviceType, 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 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.