中国电信物联网开放平台_设备能力描述文件profile开发指南

中国电信物联网开放平台_设备能力描述文件
profile开发指南
（V1）
中国电信股份有限公司物联网分公司
二〇二三年四月
编制单位：
编制单位中国电信股份有限公司物联网分公司平台运营部
修订记录：
目录
1 前言 (1)
2 概念 (2)
3 设备Profile写作 (3)
4 设备Profile提供形式 (6)
5 设备Profile文件字段含义说明 (7)
6 附录 (17)
1 前言
概述
开发者使用中国电信物联网开放平台集成设备时需要准备此设备的能力描述文件，本
文档针对此文件提供了具体的写作过程和步骤。

本文档能指导开发者快速写作设备能力描述Profile文件。

读者对象
本文档主要适用于智能家居设备厂商的开发人员，他们必须熟悉所要集成的智能家居
产品的功能、掌握相关的物联网协议和接口知识、具备一定的物联网知识背景。

符号约定
在本文中可能出现下列标志，它们所代表的含义如下。

符号说明
表示有高度潜在危险，如果不能避免，会导致人员死亡或
严重伤害。

表示有中度或低度潜在危险，如果不能避免，可能导致人
员轻微或中等伤害。

表示有潜在风险，如果忽视这些文本，可能导致设备损
坏、数据丢失、设备性能降低或不可预知的结果。

表示能帮助您解决某个问题或节省您的时间。

表示是正文的附加信息，是对正文的强调和补充。

2 概念
设备的Profile文件是用来描述一款设备是什么、能做什么以及如何控制该设备的文件。

该文件会被上传到中国电信物联网开放平台。

1. 设备能力(Device Capability)：
描述一款设备的能力特征，包括设备类
型、厂商、型号、协议类型名称以及提
供的服务类型。

如右图：彩灯的制造厂商：aeotec（制造
商ID为0086），型号(0203-0062), 协议
类型(z-wave)
其服务包括：开关(Swtich), 亮度
(Brigthness), 颜色(Color)，其中亮度为主
服务(Master), 开关为必选服务
(Mondatory)，颜色为可选服务(Optional).
2. 服务(Service)：
设备具有的某项服务（也可以理解为物
理设备的功能模块或者虚拟设备提供的
服务，如一个系统提供的天气预报服
务），包括命令和属性。

如右图：
彩灯（Light Bulb）有三个服务
（service），开关（Switch），亮度
（Brightness），颜色（Color）；
插座（Socket）有一个服务，开关
（Switch）；
其中，开关服务有SWITCH ON，OFF命
令，有当前开关状态status (ON, OFF)
等。

3 设备Profile写作
设备的Profile文件为json格式的文件。

参考上面的说明，描述一款设备的能力信息，需要描述这款设备的识别属性和提供的
服务(功能)列表，其中：
设备型号识别属性：设备类型、厂商、型号、协议类型。

服务列表：提供具体的功能服务说明列表。

命名规范
对设备类型（deviceType）、服务类型（serviceType）、服务标识（serviceId）采用单词
首字母大写的命名法：如：MultiSensor、Switch；
参数使用第一个单次首字母小写，其余单词的首字母大写的命名法：如"paraName" :
"color"，"dataType" : "int"；
命令使用所有字母大写，单词间用下划线连接的格式：如DISCOVERY，
CHANGE_COLOR；
设备能力描述json文件固定命名devicetype-capability.json；
服务能力描述json文件固定命名servicetype-capability.json；
开发者需要注意，厂商标识、型号唯一标识一个设备类型，故这两者不能与其他类型
设备同时重复。

仅支持英文。

在一些profile样例中您可能遇到命名为devicetype-display.json或servicetype-display.json的文
件，这些文件是用于智慧家庭领域的一些场景中的，如果中国电信人员与您交流方案的时候没有
涉及到，您的profile中可以不包含这些文件。

设计规范
要注重名称的通用性，简洁性；对于服务能力描述，还要考虑其功能性；
如：对于多传感器设备，就可以命名为Multi（多）Sensor（传感器）；对于某设备具有
显示电量的服务，就可以命名为Battery。

设备Profile
将一款新设备接入到中国电信物联网开放平台，首先需要编写这款设备的profile。

1.设备模板
中国电信物联网开放平台系统已经提供了一批设备的profile（即设备模板，包括组成设备的功能服务描述列表），新增设备的类型和设备功能服务如果已经在中国电信提供的列表中，可以直接选择使用中国电信提供的设备类型和提供的设备功能服务。

例如，接入一款水感(检测是否漏水的Z-wave传感器)，可以使用中国电信定义的设备服务Water（描述检测是否漏水功能）和Battery（描述该传感器的电池电量信息），直接拷贝中国电信提供的模板，修改对应设备型号标识属性和设备服务列表。

设备型号识别属性：
属性Profile中key 属性值
设备类型deviceType Water
制造商ID manufacturerId 0086
制造商名称manufacturerName aeotec
设备型号Model 0002-002D
协议类型protocolType Z-Wave
设备的服务列表
服务描述服务标识
（serviceId）
服务类型
（serviceType）
选项（option）
检测是否漏水功能Water Water Master
电池服务Battery Battery Mandatory
根据上面的信息写出具体的设备profile，参考附录一Water Profile样例。

其中可以对服务的定义进行实例化修改，如：可以调整属性的取值范围、或枚举值等。

中国电信支持的服务列表参考附录三已支持的服务列表。

开发者的设备类型中国电信是否支持，可以咨询中国电信物联网开放平台管理员。

如果开发者的设备类型或服务类型中国电信已经支持，则开发者可以找中国电信物联网开放平台管理员获取设备及服务的Profile文件参考。

设备型号建议由产品类型ID和产品ID组合构成，例如一家厂商的门磁，通过Z-Wave认证得到的ProductTypeId为0x0168，ProductId为0x0188，则设备型号对应为“0168-0188”。

2.自定义服务类型
例如，接入一款水感(检测是否漏水的Z-wave传感器)，有描述检测是否漏水功能(Water)和电池服务(Battery)而且还有测量温度功能服务（Temperature）,假设该服务中国电信物联网开放平台没有提供则可以自定义。

设备型号识别属性：
属性Profile中key 属性值
属性Profile中key 属性值
设备类型deviceType Water
制造商ID manufacturerId 010F
制造商名称manufacturerName Fibargroup
设备型号model 0B00-3003
协议类型protocolType Z-Wave
设备的服务列表：
选项（option）服务描述服务标识(serviceId 服务类型
(serviceType
检测是否漏水功能Water Water Master
电池服务Battery Battery Mandatory
测量温度功能Temperature Temperature Optional
具体的profile参考附录二Water自定义服务类型样例。

Profile的打包
Profile写作完成后，需要按如下表格形式打包。

下面以附录四中
WaterMeter_Huawei_NBIoTDevice.zip为例介绍。

关于上图有几点说明：
①Profile文件的目录层级结构必须如图所示，不能增删；
比如第二层级必须只有“profile”和“service”两个文件夹，每个服务下面必须包含“profile”等。

②图中橙色的命名不能改动；
③整个Profile以zip形式压缩；
④Profile文件的命名必须按照deviceType_manufacturerId_model的格式命名，其中的deviceType、manufacturerId、model必须与devicetype-capability.json中的对应字段的定义一致，例如，本例中的devicetype-capability.json的主要字段如下：
{
"devices": [
{
"manufacturerId": "Huawei",
"manufacturerName": "Huawei",
"model": "NBIoTDevice",
"protocolType": "CoAP",
"deviceType": "WaterMeter",
"serviceTypeCapabilities": ****
}
]
}
⑤图中的Brightness、Electricity、Temperature都是devicetype-capability.json中定义的服务。

⑥Profile文件中的文档格式都是json，在编辑完成后可以在互联网上查找一些格式校验网站，检查json的合法性。

4 设备Profile提供形式
设备Profile写作完成后，需要发给中国电信物联网开放平台管理员审核，审核通过后，中国电信物联网开放平台管理员会将Profile导入到中国电信物联网开放实验室。

5 设备Profile文件字段含义说明
设备能力
devicetype-capability.json记录了该设备的基础信息，以附录四中的
WaterMeter_Huawei_NBIoTDevice.zip为例，如下：
{
"devices": [
{
"manufacturerId": "Huawei",
"manufacturerName": "Huawei",
"model": "NBIoTDevice",
"protocolType": "CoAP",
"deviceType": "WaterMeter",
"omCapability":{
"upgradeCapability" : {
"supportUpgrade":true,
"upgradeProtocolType":"PCP"
},
"fwUpgradeCapability" : {
"supportUpgrade":true,
"upgradeProtocolType":"LWM2M"
},
"configCapability" : {
"supportConfig":true,
"configMethod":"file",
"defaultConfigFile": {
"multiSensorInfo" : {
"multiSensorPirTime" : "300"
}
}
}
},
"serviceTypeCapabilities": [
{
"serviceId": "Brightness",
"serviceType": "Brightness",
"option": "Master"
},
{
"serviceId": "Electricity",
"serviceType": "Electricity",
"option": "Optional"
},
{
"serviceId": "Temperature",
"serviceType": "Temperature",
"option": "Optional"
}
]
}
]
}
对各字段的解释：
omCapability结构描述
服务能力
servicetype-capability.json记录了该设备的服务信息，以附录四中的
WaterMeter_Huawei_NBIoTDevice.zip中的服务Brightness为例，如下：
{
"services": [
{
"serviceType": "Brightness",
"description": "Brightness",
"commands": [
{
"commandName": "SET_DEVICE_LEVEL",
"paras": [
{
"paraName": "value",
"dataType": "string",
"required": true,
"min": 0,
"max": 200,
"step": 1,
"maxLength": 10,
"unit": null,
"enumList": null
}
],
"responses": [
{
"responseName": "SET_DEVICE_LEVEL_RSP",
"paras": [
{
"paraName": "result",
"dataType": "int",
"required": true,
"min": -1000000,
"max": 1000000,
"step": 1,
"maxLength": 10,
"unit": null,
"enumList": null
}
]
}
]
},
{
"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": "brightness",
"dataType": "int",
"required": true,
"min": 0,
"max": 100,
"step": 1,
"maxLength": null,
"method": "RE",
"unit": null,
"enumList": null
}
]
}
]
}
对各字段的解释：
6 附录
附录一Water Profile样例
样例由三个文件构成，文件名和文件内容如下。

1.devicetype-capability.json
{
"devices": [
{
"manufacturerId": "0086",
"manufacturerName": "aeotec",
"model": "0002-002D",
"protocolType": "Z-Wave",
"deviceType": "Water",
"omCapability":{
"upgradeCapability" : {
"supportUpgrade":false
},
"fwUpgradeCapability" : {
"supportUpgrade":true,
"upgradeProtocolType":"LWM2M",
"downloadProtocolType":"CoAP"
}
},
"serviceTypeCapabilities": [
{
"serviceId": "Water",
"serviceType": "Water",
"option": "Master"
},
{
"serviceId": "Battery",
"serviceType": "Battery",
"option": "Mandatory"
}
]
}
]
}
2.servicetype-capability.json（Battery）
{
"services": [
{
"serviceType": "Battery",
"description": "Battery",
"commands": null,
"properties": [
{
"propertyName": "batteryLevel",
"dataType": "int",
"required": true,
"min": 0,
"max": 100,
"step": 1,
"maxLength": null,
"method": "RE",
"unit": null,
"enumList": null
},
{
"propertyName": "batteryThreshold",
"dataType": "int",
"required": false,
"min": 0,
"max": 100,
"step": 1,
"maxLength": null,
"method": "RE",
"unit": null,
"enumList": null
}
]
}
]
}
3.servicetype-capability.json（Water）
{
"services": [
{
"serviceType": "Water",
"description": "Water Sensor",
"commands": null,
"properties": [
{
"propertyName": "Water",
"dataType": "string",
"required": true,
"min": null,
"max": null,
"step": null,
"maxLength": null,
"method": "RE",
"unit": null,
"enumList": [
"DETECTED",
"DROPPED"
]
}
]
}
]
}
附录二Water自定义服务类型样例
样例由四个文件构成，文件名和文件内容如下。

1.devicetype-capability.json
{
"devices": [
{
"manufacturerId": "010F",
"manufacturerName": "Fibargroup",
"model": "0B00-3003",
"protocolType": "Z-Wave",
"deviceType": "Water",
"serviceTypeCapabilities": [
{
"serviceId": "Water",
"serviceType": "Water",
"option": "Master"
},
{
"serviceId": "Temperature",
"serviceType": "Temperature",
"option": "Optional"
},
{
"serviceId": "Battery",
"serviceType": "Battery",
"option": "Mandatory"
}
]
}
]
}
2.servicetype-capability.json（Battery）
{
"services": [
{
"serviceType": "Battery",
"description": "Battery",
"commands": null,
"properties": [
{
"propertyName": "batteryLevel",
"dataType": "int",
"required": true,
"min": 0,
"max": 100,
"step": 1,
"maxLength": null,
"method": "RE",
"unit": null,
"enumList": null
},
{
"propertyName": "batteryThreshold",
"dataType": "int",
"required": false,
"min": 0,
"max": 100,
"step": 1,
"maxLength": null,
"method": "RE",
"unit": null,
"enumList": null
}
]
}
]
}
3.servicetype-capability.json（Water）
{
"services": [
{
"serviceType": "Water",
"description": "Water Sensor",
"commands": null,
"properties": [
{
"propertyName": "Water",
"dataType": "string",
"required": true,
"min": null,
"max": null,
"step": null,
"maxLength": null,
"method": "RE",
"unit": null,
"enumList": [
"DETECTED",
"DROPPED"
]
}
]
}
]
}
4.servicetype-capability.json（Temperature）
{
"services": [
{
"serviceType": "Temperature",
"description": "Temperature",
"commands": null,
"properties": [
{
"propertyName": "temperature",
"dataType": "decimal",
"required": true,
"min": 0,
"max": 100,
"step": null,
"maxLength": null,
"method": "R",
"unit": "C",
"enumList": null
}
]
}
]
}
附录三已支持的服务列表
如有需要可向中国电信支撑人员索取。

服务类型名称描述对应模板内json文件
WindowCovering 控制窗帘开闭WindowCovering.json
ZoomActuator 缩放焦距ZoomActuator.json
附录四Profile文件压缩包。