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

1、中国电信物联网开放_设备能力描述文件profile 开发指南（V1）中国电信物联网二二一年八月编制：编制中国电信物联网运营部修订：版本号日期描述012017/11/06中国电信物联网开放_设备能力描述文件 profile 开发指南目录123456前言1概念2设备 Profile 写作3设备 Profile 提供形式6设备 Profile 文件字段含义说明7附录171前言概述开发者使用中国电信物联网开放集成设备时需要准备此设备的能力描述文件，本文档针对此文件提供了具体的写作过程和步骤。本文档能指导开发者快速写作设备能力描述 Profile 文件。读者对象本文档主要适用于智能家居设备厂商的开发，他

2、们必须熟悉所要集成的智能家居产品的功能、掌握相关的物联网协议和接口知识、具备一定的物联网知识背景。符号约定在本文中可能出现下列标志，它们所代表的含义如下。符号说明表示有高度潜在，如果不能避免，会导致或严重。表示有中度或低度潜在，如果不能避免，可能导致人员轻微或中等。表示有潜在风险，如果忽视这些文本，可能导致设备损坏、数据丢失、设备性能降低或不可预知的结果。表示能帮助您解决某个问题或节省您的时间。表示是正文的附加信息，是对正文的强调和补充。2概念设备的 Profile 文件是一款设备是什么、能做什么以及如何控制该设备的文件。该文件会被上传到中国电信物联网开放。设备能力 (Device Capab

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

4、b）有三个服务（service），开关（Switch），亮度（Brightness），颜色（Color）；插座（Socket）有一个服务，开关（Switch）；其中，开关服务有SWITCH ON，OFF 命令，有当前开关状态 sus (ON, OFF)等。3 设备 Profile 写作设备的 Profile 文件为 json 格式的文件。参考上面的说明，描述一款设备的能力信息，需要描述这款设备的识别属性和提供的服务(功能)列表，其中：设备型号识别属性：设备类型、厂商、型号、协议类型。服务列表：提供具体的功能服务说明列表。命名规范对设备类型（deviceType）、服务类型（serviceTyp

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

6、一些profile 样例中您可能遇到命名为devicetype-display.json 或servicetype-display.json 的文件，这些文件是用于智慧家庭领域的一些场景中的，如果中国电信涉及到，您的profile 中可以不包含这些文件。与您交流方案的时候没有设计规范要注重名称的通用性，简洁性；对于服务能力描述，还要考虑其功能性；如：对于多传感器设备，就可以命名为Multi（多）Sensor（传感器）；对于某设备具有显示电量的服务，就可以命名为 Battery。设备 Profile将一款新设备接入到中国电信物联网开放，首先需要编写这款设备的profile。1.设备模板中国电信物

7、联网开放系统已经提供了一批设备的profile（即设备模板，包括组成设备的功能服务描述列表），新增设备的类型和设备功能服务如果已经电信提供的列表中，可以直接选择使用中国电信提供的设备类型和提供的设备功能服务。例如，接入一款水感 (检测是否漏水的 Z-wave 传感器)，可以使用中国电信定义的设备服务 Water（描述检测是否漏水功能）和 Battery（描述该传感器的电池电量信息），直接拷贝中国电信提供的模板，修改对应设备型号标识属性和设备服务列表。设备型号识别属性：设备的服务列表根据上面的信息写出具体的设备 profile，参考附录一 Watrofile 样例。其中可以对服务的定义进行实例化

8、修改，如：可以调整属性的取值范围、或枚举值等。中国电信支持的服务列表参考附录三 已支持的服务列表。开发者的设备类型中国电信是否支持，可以中国电信物联网开放管理员。如果开发者的设备类型或服务类型中国电信已经支持，则开发者可以找中国电信物联网开放设备型号建议由产品类型 ID 和产品 ID 组合管理员获取设备及服务的 Profile 文件参考。，例如一家厂商的门磁，通过Z-Wave 认证得到的ProductTypeId 为 0 x0168，ProductId 为 0 x0188，则设备型号对应为“0168-0188”。2.自定义服务类型例如，接入一款水感 (检测是否漏水的 Z-wave 传感器)，有

9、描述检测是否漏水功能 (Water)和电池服务(Battery)而且还有测量温度功能服务（Temperature）,假设该服务中国电信物联网开放没有提供则可以自定义。设备型号识别属性：属性Profile 中 key属性值服务描述服务标识（serviceId）服务类型（serviceType）选项（option）检测是否漏水功能WaterWaterMaster电池服务BatteryBatteryMandatory属性Profile 中 key属性值设备类型deviceTypeWater制造商 IDmanufacturerId0086制造商名称manufacturerNameaeotec设备型号M

10、0002-002D协议类型protocolTypeZ-Wave设备的服务列表：具体的 profile 参考附录二 Water 自定义服务类型样例。Profile 的打包Profile 写作完成后，需要按如下表格形式打包。下面以附录四中WaterMeter_NBIoTDevice.zip 为例介绍。关于上图有几点说明：服务描述服务标识(serviceId服务类型(serviceType选项（option）检测是否漏水功能WaterWaterMaster电池服务BatteryBatteryMandatory测量温度功能TemperatureTemperatureOptional属性Profile

11、中 key属性值设备类型deviceTypeWater制造商 IDmanufacturerId010F制造商名称manufacturerNameFibargroup设备型号m0B00-3003协议类型protocolTypeZ-Wave Profile 文件的目录层级结构必须，不能增删；比如第二层级必须只有“profile”和“service”两个文件夹，每个服务下面必须包含 “profile”等。 图中橙色名不能改动； 整个 Profile 以 zip 形式压缩； Profile 文件名必须按照 deviceType_manufacturerId_m的格式命名，其中的deviceType、m

12、anufacturerId、m必须与 devicetype-capability.json 中的对应字段的定义一致，例如，本例中的 devicetype-capability.json 的主要字段如下：devi: manufacturerId: ,manufacturerName: ,m: NBIoTDevice,protocolType: CoAP,deviceType: WaterMeter,serviceTypeCapabilities: * 图中的 Brightne的服务。ectricity、Temperature 都是devicetype-capability.json 中定义 Pr

13、ofile 文件中的文档格式都是 json，在编辑完成后可以在互联网上查找一些格式校验，检查 json 的。4 设备 Profile 提供形式设备 Profile 写作完成后，需要发给中国电信物联网开放管理员审核，审核通过后，中国电信物联网开放管理员会将 Profile 导入到中国电信物联网开放。5 设备 Profile 文件字段含义说明设备能力devicetype-capability.json了该设备的基础信息，以附录四中的WaterMeter_NBIoTDevice.zip 为例，如下：devi: manufacturerId: ,manufacturerName: ,m: NBIoTD

14、evice,protocolType: CoAP,deviceType: WaterMeter,omCapability:upgradeCapability : supportUpgrade:true,upgradeProtocolType:PCP,fwUpgradeCapability : supportUpgrade:true,upgradeProtocolType:LWM2M,configCapability : supportConfig:true,configMethod:file,defaultConfigFile: multiSensorInfo : multiSensorPir

15、Time : 300,serviceTypeCapabilities: serviceId: Brightness,serviceType: Brightness,option: Master,serviceId: Electricity,serviceType: Electricity,option: Optional,serviceId: Temperature,serviceType: Temperature,对各字段的解释：字段可选/必选描述devi必选包含了一个设备的完整能力信息（根节点不能修改）manufacturerId必选指示设备的制造商 IDmanufacturerNa me

16、必选指示设备的制造商名称 （只允许英文）m必选指示设备的型号，考虑到一款设备下的多种型号建议包含字母或数字来保证可扩展性。protocolType必选指示设备接入的协议类型。如 NB-IoT的设备取值为 CoAPdeviceType必选指示设备的类型omCapability可选定义设备的软件升级、固件升级和配置更新的能力，字段含义详情见下文中的： omCapability结构描述。如果设备不涉及 /固件升级，本字段可以删除。option: OptionalomCapability 结构描述字段子字段可选/必选描述upgradeCapabilit可选设备升级能力字段可选/必选描述serviceT

17、ypeCap abilities必选包含了设备具备的服务能力描述serviceId必选服务的 Id，如果设备中同类型的服务类型只有一个则 serviceId 与 serviceType 相同， 如果有多个则增加编 号，如三键开关 Switch01, Switch02, Switch03；serviceType必选服务类型比如 DoorLock（门磁）、 Smoke（烟感）与 servicetype- capability.json中 serviceType字段保持一致option必选标识服务字段 option 可选范围Master（主服务）, Mandatory（必选服务）, Optional

18、（可选服务）目前本字段是非功能性字 段，仅起到描述作用。服务能力servicetype-capability.json了该设备的服务信息，以附录四中的WaterMeter_NBIoTDevice.zip 中的服务 Brightness 为例，如下：servi: serviceType: Brightness,description: Brightness,ds: dName: SET_DEVICE_LEVEL,paras: 字段子字段可选/必选描述ysupportUpgrade可选true: 设备支持升级false:设备不支持升级upgradeProtocolTyp e可选升级使用的协议类型，

19、此处不同于设备的 protocolType，例如 CoAP 设备升级协议使用 PCPfwUpgradeCapab ility可选设备固件升级能力supportUpgrade可选true: 设备支持固件升级false:设备不支持固件升级upgradeProtocolTyp e可选升级使用的协议类型，此处不同于设备的 protocolType，当前中国电信物联网开放仅支持 LWM2M 固件升级configCapability可选设备配置更新能力supportConfig可选true: 设备支持配置更新false:设备不支持配置更新configMethod可选file: 使用文件的方式下发配置更新d

20、efaultConfigFile可选设备默认配置信息，Json 格式，具体配置信息由设备商自定义，I中国电信物联网开放 只下发使用，不 处理配置字段的具体含义。required: true,min: -1000000,max: 1000000,step: 1,maxLength: 10,unit: null,enumList: null,dName: SET_PRERE_READ_PERIOD,paras: paraName: value,daype: ,required: true,min: 1,max: 24,step: 1,maxLength: 10,unit: hour,enumLis

21、t: null,responses: responseName: SET_PRERE_READ_PERIOD_RSP,paras: paraName: result,daype: ,required: true,min: -1000000,max: 1000000,required: true,min: 0,max: 200,step: 1,maxLength: 10,unit: null,enumList: null,responses: responseName: SET_DEVICE_LEVEL_RSP,paras: paraName: result,daype: ,paraName:

22、value,daype: string,required: true,min: 0,max: 100,step: 1,maxLength: null,method: RE,unit: null,enumList: null对各字段的解释：字段必选/可选描述servi必选包含了一个服务的完整信息（根节点不可修改）servic eType必选指示服务的类型如 DoorLock（门磁）、Smoke（烟感）与 devicetype-capability.json 中serviceType 字段保持一致descri ption必选指示服务的描述信息文本描述，不影响实际功能，可置nullcomm ands

23、必选指示设备可以执行令，如果本服务无命令则置 nulldName必选指示命令的名字，如门磁的 LOCK命令、头的_RECORDstep: 1,maxLength: 10,unit: null,enumList: null,properties: propertyName: brightness,daype: ,字段必选/可选描述命令，命令名与参数共同一个完整令paras必选命令包含的参数para Nam e必选命令中参数的名字da ype必选指示数据类型（必填）取值范围：string、 、string list、 decimal、DateTime、jsonObject上报数据时，复杂类型数据格

24、式如下：string list：str1,str2,str3DateTime：yyyyMMddT HHmmssZ如:20151212T121212ZjsonObject：自定义 json 结构体，不理解只透传requi red必选指示本条属性是否必选，取值为 true 或false，默认取值 false（非必选）。目前本字段是非功能性字段，仅起到描述作用。min必选指示最小值仅当 daype 为、decimal 时生效，逻辑大于等于max必选指示最大值仅当 daype 为、decimal 时生效，逻辑小于等于step必选指示步长暂不使用，填 0 即可maxL ength必选指示字符串长度仅当

25、daype 为 string、string list、DateTime 时生效unit必指示，英文字段必选/可选描述选取值根据参数确定，如：温度：“C”或“K”百分比：“%”压强：“Pa”或“kPa”enum List必选指示枚举值如开关状态 sus 可有如下取值enumList : OPEN,CLOSE目前本字段是非功能性字段，仅起到描述作用。建议准确定义。responses必选命令执行的响应respo nseN ame必选命名可以在该 responses 对应令的dName 后面添加 “_RSP”paras必选命令响应的参数par aN am e必选命令中参数的名字dat aTy pe必选

26、指示数据类型（必填）取值范围：string、 、string list、 decimal、DateTime、jsonObject上报数据时，复杂类型数据格式如下：string list：str1,str2,str3DateTime：yyyyMMddT HHmmssZ如:20151212T121212ZjsonObject：自定义 json 结构体，不理解只透传req uire d必选指示本条属性是否必选，取值为 true 或false，默认取值 false（非必选）。目前本字段是非功能性字段，仅起到描述作用。字段必选/可选描述min必选指示最小值仅当 daype 为、decimal 时生效，逻

27、辑大于等于ma x必选指示最大值仅当 daype 为、decimal 时生效，逻辑小于等于ste p必选指示步长暂不使用，填 0 即可ma xLe ngt h必选指示字符串长度仅当 daype 为 string、string list、DateTime 时生效unit必选指示，英文取值根据参数确定，如：温度：“C”或“K”百分比：“%”压强：“Pa”或“kPa”enu mL ist必选指示枚举值如开关状态 sus 可有如下取值enumList : OPEN,CLOSE目前本字段是非功能性字段，仅起到描述作用。建议准确定义。proper ties必选上报数据描述，每一个子节点为一条属性prope

28、rtyN ame必选指示属性名称（必填）daype必选指示数据类型（必填）取值范围：string、 、string list、 decimal、DateTime、jsonObject上报数据时，复杂类型数据格式如下：string list：str1,str2,str3DateTime：yyyyMMddT HHmmssZ如:20151212T121212Z字段必选/可选描述jsonObject：自定义 json 结构体，不理解只透传required必选指示本条属性是否必选，取值为 true 或false，默认取值 false（非必选）。目前本字段是非功能性字段，仅起到描述作用。min必选指示最小

29、值仅当 daype 为、decimal 时生效，逻辑大于等于max必选指示最大值仅当 daype 为、decimal 时生效，逻辑小于等于step必选指示步长暂不使用，填 0 即可method必选指示模式R:可读；W:可写；E 可订阅取值范围：R、RW、RE、RWE 、nullunit必选指示，英文取值根据参数确定，如：温度：“C”或“K”百分比：“%”压强：“Pa”或“kPa”maxLengt h必选指示字符串长度仅当 daype 为 string、string list、DateTime 时生效enumList必选指示枚举值如烟感属性activitySus 可有如下取值enumList :

30、 STANDBY, RECORDING, LIVING目前本字段是非功能性字段，仅起到描述作用。建议准确定义。6附录附录一 Watrofile 样例样例由三个文件，文件名和文件内容如下。1.devicetype-capability.jsondevi: manufacturerId: 0086,manufacturerName: aeotec,m: 0002-002D,protocolType: Z-Wave,deviceType: Water,omCapability:upgradeCapability : supportUpgrade:false,fwUpgradeCapability :

31、 supportUpgrade:true,upgradeProtocolType:LWM2M,downlorotocolType:CoAP,serviceTypeCapabilities: serviceId: Water,serviceType: Water,option: Master,serviceId: Battery,serviceType: Battery,option: Mandatoryservicetype-capability.json（Battery）servi: serviceType: Battery,description: Battery,2.ds: null,r

32、equired: true,min: 0,max: 100,step: 1,maxLength: null,method: RE,unit: null,enumList: null,propertyName: batteryThreshold,daype: ,required: false,min: 0,max: 100,step: 1,maxLength: null,method: RE,unit: null,enumList: nullservicetype-capability.json（Water）servi: serviceType: Water,description: Water

33、 Sensor,ds: null,properties: propertyName: Water,daype: string,required: true,min: null,max: null,step: null,maxLength: null,method: RE,unit: null,enumList: DETECTED,DROPPED3.properties: propertyName: batteryLevel,daype: ,附录二 Water 自定义服务类型样例样例由四个文件，文件名和文件内容如下。1.devicetype-capability.jsondevi: manufa

34、cturerId: 010F,manufacturerName: Fibargroup,m: 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: Mandatoryservicetype-capability.json（Battery）servi: serviceType: Battery,description: Battery,ds: null,properties: propertyName: batteryLevel,daype: ,required: true,min: 0,max: 100,step: 1,maxLength: null,method: RE,unit: null,2.required: false,min: 0,max: 100,step: 1,maxLength: null,method: RE,unit