中国电信物联网开放平台_设备能力描述文件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 属性值