Developing a Product Model Offline

Updated on 2024-11-04 GMT+08:00

View PDF

Overview

A product model is essentially a devicetype-capability.json file and several serviceType-capability.json files. The devicetype-capability.json file describes the service capabilities contained in the product model, and the serviceType-capability.json file describes each capability of service_capabilities in the devicetype-capability.json file. A .zip package in the following directory: in which WaterMeter indicates the device type, TestUtf8Manuld identifies the manufacturer ID, and WaterMeterBasic, WaterMeterAlarm, and Battery indicates the service types.

Click to enlarge

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.

NOTE:

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

Property	Key in the Product Model	Value
Device Type	deviceType	WaterMeter
Manufacturer ID	manufacturerId	TestUtf8ManuId
Manufacturer Name	manufacturerName	HZYB
Protocol Type	protocolType	CoAP

Service list

Service	Service ID	Service Type	Value
Basic water meter function	WaterMeterBasic	Water	Mandatory
Alarm service	WaterMeterAlarm	Battery	Mandatory
Battery service	Battery	Battery	Optional
Data reporting rule	DeliverySchedule	DeliverySchedule	Mandatory
Connectivity	Connectivity	Connectivity	Mandatory

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:

Field	Sub-field		Mandatory	Description
devices	-	-	Yes	Complete capability information about a device. The root node cannot be modified.
-	manufacturerId	-	No	Manufacturer ID of the device.
-	manufacturerName	-	Yes	Manufacturer name of the device. The name must be in English.
-	protocolType	-	Yes	Protocol used by the device to connect to the IoT platform. For example, the value is CoAP for NB-IoT devices.
-	deviceType	-	Yes	Type of the device.
-	omCapability	-	No	Software upgrade, firmware upgrade, and configuration update capabilities of the device. For details, see the description of the omCapability structure below. If software or firmware upgrade is not involved, this field can be deleted.
-	serviceTypeCapabilities	-	Yes	Service capabilities of the device.
-	-	serviceId	Yes	Service ID. If a service type includes only one service, the value of serviceId is the same as that of serviceType. If the service type includes multiple services, the services are numbered correspondingly, such as Switch01, Switch02, and Switch03.
-	-	serviceType	Yes	Type of the service. The value of this field must be the same as that of serviceType in the servicetype-capability.json file.
-	-	option	Yes	Type of the service field. The value can be Master, Mandatory, or Optional. This field is not a functional field but a descriptive one.

Description of the omCapability structure

Field	Sub-field	Mandatory	Description
upgradeCapability	-	No	Software upgrade capabilities of the device.
-	supportUpgrade	No	true: The device supports software upgrades. false: The device does not support software upgrades.
-	upgradeProtocolType	No	Protocol type used by the device for software upgrades. It is different from protocolType of the device. For example, the software upgrade protocol of CoAP devices is PCP.
fwUpgradeCapability	-	No	Firmware upgrade capabilities of the device.
-	supportUpgrade	No	true: The device supports firmware upgrades. false: The device does not support firmware upgrades.
-	upgradeProtocolType	No	Protocol type used by the device for firmware upgrades. It is different from protocolType of the device. Currently, the IoT platform supports only firmware upgrades of LwM2M devices.
configCapability	-	No	Configuration update capabilities of the device.
-	supportConfig	No	true: The device supports configuration updates. false: The device does not support configuration updates.
-	configMethod	No	file: Configuration updates are delivered in the form of files.
-	defaultConfigFile	No	Default device configuration information (in JSON format). The specific configuration information is defined by the manufacturer. The IoT platform stores the information for delivery but does not parse the configuration fields.

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:

Field	Sub-field				Mandatory	Description
services	-	-	-	-	Yes	Complete information about a service. The root node cannot be modified.
-	serviceType	-	-	-	Yes	Type of the service. The value of this field must be the same as that of serviceType in the devicetype-capability.json file.
-	description	-	-	-	Yes	Description of the service. This field is not a functional field but a descriptive one. It can be set to null.
-	commands	-	-	-	Yes	Command supported by the device. If the service has no commands, set the value to null.
-	-	commandName	-	-	Yes	Name of the command. The command name and parameters together form a complete command.
-	-	paras	-	-	Yes	Parameters contained in the command.
-	-	-	paraName	-	Yes	Name of a parameter in the command.
-	-	-	dataType	-	Yes	Data type of the parameter in the command. Value: string, int, string list, decimal, DateTime, jsonObject, enum, or boolean Complex types of reported data are as follows: string list:["str1","str2","str3"] DateTime: The value is in the format of yyyyMMdd'T'HHmmss'Z', for example, 20151212T121212Z. jsonObject: The value is in the customized JSON format, which is not parsed by the IoT platform and is transparently transmitted only.
-	-	-	required	-	Yes	Whether the command is mandatory. The value can be true or false. The default value is false, indicating that the command is optional. This field is not a functional field but a descriptive one.
-	-	-	min	-	Yes	Minimum value. This field is valid only when dataType is set to int or decimal.
-	-	-	max	-	Yes	Maximum value. This field is valid only when dataType is set to int or decimal.
-	-	-	step	-	Yes	Step. This field is not used. Set it to 0.
-	-	-	maxLength	-	Yes	Character string length. This field is valid only when dataType is set to string, string list, or DateTime.
-	-	-	unit	-	Yes	Unit. The value is determined by the parameter, for example: Temperature unit: C or K Percentage unit: % Pressure unit: Pa or kPa
-	-	-	enumList	-	Yes	List of enumerated values. For example, the status of a switch can be set as follows: "enumList" : ["OPEN","CLOSE"] This field is not a functional field but a descriptive one. It is recommended that this field be defined accurately.
-	-	responses	-	-	Yes	Responses to command execution.
-	-	-	responseName	-	Yes	You can add _RSP to the end of commandName.
-	-	-	paras	-	Yes	Parameters contained in a response.
-	-	-	-	paraName	Yes	Name of a parameter in the command.
-	-	-	-	dataType	Yes	Data type. Value: string, string list, decimal, DateTime, jsonObject, or int Complex types of reported data are as follows: string list:["str1","str2","str3"] DateTime: The value is in the format of yyyyMMdd'T'HHmmss'Z', for example, 20151212T121212Z. jsonObject: The value is in the customized JSON format, which is not parsed by the IoT platform and is transparently transmitted only.
-	-	-	-	required	Yes	Whether the command response is mandatory. The value can be true or false. The default value is false, indicating that the command response is optional. This field is not a functional field but a descriptive one.
-	-	-	-	min	Yes	Minimum value. This field is valid only when dataType is set to int or decimal.
-	-	-	-	max	Yes	Maximum value. This field is valid only when dataType is set to int or decimal.
-	-	-	-	step	Yes	Step. This field is not used. Set it to 0.
-	-	-	-	maxLength	Yes	Character string length. This field is valid only when dataType is set to string, string list, or DateTime.
-	-	-	-	unit	Yes	Unit. The value is determined by the parameter, for example: Temperature unit: C or K Percentage unit: % Pressure unit: Pa or kPa
-	-	-	-	enumList	Yes	List of enumerated values. For example, the status of a switch can be set as follows: "enumList" : ["OPEN","CLOSE"] This field is not a functional field but a descriptive one. It is recommended that this field be defined accurately.
-	properties	-	-	-	Yes	Reported data. Each sub-node indicates a property.
-	-	propertyName	-	-	Yes	Name of a property.
-	-	dataType	-	-	Yes	Data type. Value: string, string list, decimal, DateTime, jsonObject, or int Complex types of reported data are as follows: string list:["str1","str2","str3"] DateTime: The value is in the format of yyyyMMdd'T'HHmmss'Z', for example, 20151212T121212Z. jsonObject: The value is in the customized JSON format, which is not parsed by the IoT platform and is transparently transmitted only.
-	-	required	-	-	Yes	Whether the property is mandatory. The value can be true or false. The default value is false, indicating that the property is optional. This field is not a functional field but a descriptive one.
-	-	min	-	-	Yes	Minimum value. This field is valid only when dataType is set to int or decimal.
-	-	max	-	-	Yes	Maximum value. This field is valid only when dataType is set to int or decimal.
-	-	step	-	-	Yes	Step. This field is not used. Set it to 0.
-	-	method	-	-	Yes	Access mode. R indicates reading, W indicates writing, and E indicates subscription. Value: R, RW, RE, RWE, or null
-	-	unit	-	-	Yes	Unit. The value is determined by the parameter, for example: Temperature unit: C or K Percentage unit: % Pressure unit: Pa or kPa
-	-	maxLength	-	-	Yes	Character string length. This field is valid only when dataType is set to string, string list, or DateTime.
-	-	enumList	-	-	Yes	List of enumerated values. For example, batteryStatus can be set as follows: "enumList" : [0, 1, 2, 3, 4, 5, 6] This field is not a functional field but a descriptive one. It is recommended that this field be defined accurately.

Product Model Packaging

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

Click to enlarge

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.

Parent topic: Developing a Product Model

Previous topic: Developing a Product Model Online

Next topic: Exporting and Importing a Product Model