Profile Writing Guide

Naming Rules

The profile file must comply with the following naming rules:

• Capitalize device types, service types, and service IDs. Example: WaterMeter and Battery.
• For the attribute name, uncapitalize the first character in the first world and capitalize the first characters in subsequent words. Example: batteryLevel and internalTemperature.
• For the order, capitalize all characters, with words separated by underscores. For example: DISCOVERY and CHANGE_COLOR.
• A device capability profile file (.json file) must be named devicetype-capability.json.
• A service capability profile file (.json file) must be named servicetype-capability.json.
• The manufacturer ID, manufacturer name, and device model uniquely identify a device. Therefore, their combinations must be unique in different profile files and only English is supported.
• 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.

NOTE:

In some profile file samples, files named devicetype-display.json or servicetype-display.json may exist. These files are used in some SmartHome scenarios. If they are not involved in the solution communication between you and the IoT platform service provider, these files may not be included in your profile file.

If you need to create a profile file for the SmartHome scenarios, contact the IoT platform support personnel.

Device Profile File

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

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

NOTE:

The profile file 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 attributes

Service list

For details about a complete sample, see Appendix I: Water Meter Profile Sample. The service definition can be modified as required. For example, the value ranges or enumerated values of attributes can be modified.

NOTE:

Developers can consult IoT platform support personnel to determine whether the IoT platform supports their own device types. If the device types or service types are supported, developers can obtain the profile file references from the IoT platform support personnel.

A device model is composed of a product type ID and a product ID. For example, if the values of ProducTypeId and ProductId are 0x0168 and 0x0188, respectively, the device model is 0168-0188.

Profile Packaging

After the profile file is completed, package it in the format shown in Figure 1.

Figure 1 Profile file hierarchy

The following requirements must be met for profile packaging:

• The profile file hierarchy must be the same as that shown in Figure 1 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 in Figure 1 cannot be changed.
• The profile file must be compressed in ZIP format.
• The profile file must be named in the format of deviceType_manufacturerId_model. The values of deviceType, manufacturerId, and model 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", 
            "model": "NBIoTDevice", 
            "protocolType": "CoAP", 
            "deviceType": "WaterMeter", 
            "serviceTypeCapabilities": ****
        } 
    ] 
}

• WaterMeterBasic, WaterMeterAlarm, and Battery in Figure 1 are services defined in the devicetype-capability.json file.
• The profile file is in JSON format. After the file is edited, you can search for some format verification websites on the Internet to check the validity of the JSON file.