文档介绍：中国电信IoT 设备能力描述文件profile开发指南
文档版本
01
发布日期
2017-06-26
目录
1 前言 1
2 概念 2
3 设备Profile写作 3
命名规范 3
设计规范 4
设备Profile 4
Profile的打包 5
4 设备Profile提供形式 7
5 设备Profile文件字段含义说明 8
设备能力 8
服务能力 10
6 附录 17
附录一 Water Profile样例 17
附录二 Water自定义服务类型样例 19
附录三已支持的服务列表 21
前言
概述
开发者使用中国电信IoT 平台集成设备时需要准备此设备的能力描述文件,本文档针对此文件提供了具体的写作过程和步骤。
本文档能指导开发者快速写作设备能力描述Profile文件。
读者对象
本文档主要适用于智能家居设备厂商的开发人员,他们必须熟悉所要集成的智能家居产品的功能、掌握相关的物联网协议和接口知识、具备一定的物联网知识背景。
符号约定
在本文中可能出现下列标志,它们所代表的含义如下。
符号
说明
表示有高度潜在危险,如果不能避免,会导致人员死亡或严重伤害。
表示有中度或低度潜在危险,如果不能避免,可能导致人员轻微或中等伤害。
表示有潜在风险,如果忽视这些文本,可能导致设备损坏、数据丢失、设备性能降低或不可预知的结果。
表示能帮助您解决某个问题或节省您的时间。
表示是正文的附加信息,是对正文的强调和补充。
修改记录
修改记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。
概念
设备的Profile文件是用来描述一款设备是什么、能做什么以及如何控制该设备的文件。该文件会被上传到中国电信IoT平台。
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)等。
设备Profile写作
设备的Profile文件为json格式的文件。
参考上面的说明,描述一款设备的能力信息,需要描述这款设备的识别属性和提供的服务(功能)列表,其中:
设备型号识别属性:设备类型、厂商、型号、协议类型;
服务列表:提供具体的功能服务说明列表;
命名规范
设计规范
设备Profile
Profile的打包
命名规范
对设备类型、服务类型、服务标识采用单词首字母大写的命名法:如:MultiSensor、Switch;
参数使用首字母小写,其余单词的首字母大写的命名法:如"paraName" : "color", "dataType" : "int";
命令使用所有字母大写,单词间用下划线连接的格式:如DISCOVERY,CHANGE_COLOR;
设备能力描述json文件固定命名devicetype-;
服务能力描述json文件固定命名servicetype-;
开发者需要注意,厂商标识、型号唯一标识一个设备类型,故这两者不能与其他类型设备同时重复。仅支持英文。
在一些profile样例中您可能遇到命名为devicetype--,这些文件是用于智慧家庭领域的一些场景中的,如果中国电信人员与您交流方案的时候没有涉及到,您的profile中可以不包含这些文件。
设计规范
要注重名称的通用性,简洁性;对于服务能力描述,还要考虑其功能性;
如:对于多传感器设备,就可以命名为Multi(多)Sensor(传感器);对于某设备具有显示电量的服