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

1、中国电信物联网开放平台设备能力描述文件profile开发指南(V1)中国电信股份有限公司物联网分公司二。一九年二月编制单位：编制单位中国电信股份有限公司物联网分公司平台运营部修订记录:版本号日期描述012017/11/06中国电信物联网开放平台_设备能力描述文件profile开发指南1前言.1.2概念2.3设备Profile写作3.4设备Profile提供形式6.5设备Profile文件字段含义说明7.6附录17.1、儿、,刖百概述开发者使用中国电信物联网开放平台集成设备时需要准备此设备的能力描述文件，本文档针对此文件提供了具体的写作过程和步骤。本文档能指导开发者快速写作设备能力描述Profi

2、le文件。读者对象本文档主要适用于智能家居设备厂商的开发人员，他们必须熟悉所要集成的智能家居产品的功能、掌握相关的物联网协议和接口知识、具备一定的物联网知识背景。符号约定在本文中可能出现下列标志，它们所代表的含义如下。符号说明危险表7K有高度潜在危险，如果不能避免，会导致人员死亡或严重伤害。警告表示有中度或低度潜在危险，如果不能避免，可能导致人员轻微或中等伤害。注意表示有潜在风险，如果忽视这些文本，可能导致设备损坏、数据丢失、设备性能降低或不可预知的结果。表示能帮助您解决某个问题或节省您的时间。2宓门0Q说明表示是正文的附加信息，是对正文的强调和补充。2概念设备的Profile文件是用来描述一

3、款设备是什么、能做什么以及如何控制该设备的文件。该文件会被上传到中国电信物联网开放平台。1 .设备能力(DeviceCapability):描述一款设备的能力特征，包括设备类型、厂商、型号、协议类型名称以及提供的服务类型。如右图：彩灯的制造厂商：aeotec(制造商ID为0086),型号(0203-0062),协议类型亿-wave)其服务包括：开关(Swtich),亮度(Brigthness),颜色(Color),其中亮度为主服务(Master),开关为必选服务(Mondatory),颜色为可选服务(Optional).2 .服务(Service):设备具有的某项服务(也可以理解为物理设备的功

4、能模块或者虚拟设备提供的服务，如一个系统提供的天气预报服务)，包括命令和属性。如右图：彩灯(LightBulb)有三个服务(service),开关(Switch),亮度(Brightness),颜色(Color);插座(Socket)有一个服务，开关(Switch);其中，开关服务有SWITCHON,OFF命令，有当前开关状态status(ON,OFF)3设备Prof-写作设备的Profile文件为json格式的文件。参考上面的说明，描述一款设备的能力信息，需要描述这款设备的识别属性和提供的服务(功能)列表，其中：设备型号识别属性：设备类型、厂商、型号、协议类型。服务列表：提供具体的功能服务说

5、明列表。命名规范对设备类型(deviceType)、服务类型(serviceType)、服务标识(serviceld)采用单词首字母大写的命名法：如：MultiSensor、Switch;参数使用第一个单次首字母小写，其余单词的首字母大写的命名法：如"paraName":"color","dataType":"int"命令使用所有字母大写，单词间用下划线连接的格式：如DISCOVERY,CHANGE_COLOR;设备能力描述json文件固定命名devicetype-capability.json；服务能力描述jso

6、n文件固定命名servicetype-capability.json；开发者需要注意，厂商标识、型号唯一标识一个设备类型，故这两者不能与其他类型设备同时重复。仅支持英文。GQ说明在些profile样例中您可能遇至U命名为devicetype-display.json或servicetype-display.json的文件，这些文件是用于智慧家庭领域的一些场景中的，如果中国电信人员与您交流方案的时候没有涉及到，您的profile中可以不包含这些文件。设计规范要注重名称的通用性，简洁性；对于服务能力描述，还要考虑其功能性；如：对于多传感器设备，就可以命名为Multi(多)Sensor(传感器)；对

7、于某设备具有显示电量的服务，就可以命名为Battery。设备Profile将一款新设备接入到中国电信物联网开放平台，首先需要编写这款设备的profile。1 .设备模板中国电信物联网开放平台系统已经提供了一批设备的profile（即设备模板，包括组成设备的功能服务描述列表），新增设备的类型和设备功能服务如果已经在中国电信提供的列表中，可以直接选择使用中国电信提供的设备类型和提供的设备功能服务。例如，接入一款水感（检测是否漏水的Z-wave传感器），可以使用中国电信定义的设备服务Water（描述检测是否漏水功能）和Battery（描述该传感器的电池电量信息），直接拷贝中国电信提供的模板，修改对应

8、设备型号标识属性和设备服务列表。设备型号识别属性：属性Profile中key属性值设备类型deviceTypeWater制造商IDmanufacturerId0086制造商名称manufacturerNameaeotec设备型号Model0002-002D协议类型protocolTypeZ-Wave设备的服务列表服务描述服务标识(serviceId)服务类型(serviceType)选项(option)检测是否漏水功能WaterWaterMaster电池服务BatteryBatteryMandatory根据上面的信息写出具体的设备profile,参考附录一WaterPro巾le样例。其中可以对

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

10、感器），有描述检测是否漏水功能（Water）和电池服务（Battery）而且还有测量温度功能服务（Temperature）,假设该服务中国电信物联网开放平台没有提供则可以自定义。设备型号识别属性：属性Profile中key属性值属性Profile中key属性值设备类型deviceTypeWater制造商IDmanufacturerId010F制造商名称manufacturerNameFibargroup设备型号model0B00-3003协议类型protocolTypeZ-Wave设备的服务列表:服务描述服务标识（serviceId服务类型（serviceType选项（option）检测是否漏

11、水功能WaterWaterMaster电池服务BatteryBatteryMandatory测量温度功能TemperatureTemperatureOptional具体的profile参考附录二Water自定义服务类型样例。Profile的打包Profile写作完成后，需要按如下表格形式打包。下面以附录四中WaterMeter_Huawei_NBIoTDevice.zip为例介绍。Water忸jHuawe_NBloT&evke.iipproEl«ctncity关于上图有几点说明:Profile文件的目录层级结构必须如图所示，不能增删；比如第二层级必须只有"profi

12、le"和"service”两个文件夹，每个服务下面必须包含“profile”等。图中橙色的命名不能改动； 整个Profile以zip形式压缩； Profile文件的命名必须按照deviceType_manufacturerId_model的格式命名，其中的deviceType、manufacturerId、model必须与devicetype-capability.json中的对应字段的定义一致，例如，本例中的devicetype-capability.json的主要字段如下："devices":"manufacturerId":&q

13、uot;Huawei","manufacturerName":"Huawei","model":"NBIoTDevice","protocolType":"CoAP","deviceType":"WaterMeter","serviceTypeCapabilities":*) 图中的Brightness>Electricity、Temperature者B是devicetype-capability.j

14、son中定义的服务。 Profile文件中的文档格式都是json,在编辑完成后可以在互联网上查找一些格式校验网站，检查json的合法性。4设备Profile提供形式设备Profile写作完成后，需要发给中国电信物联网开放平台管理员审核，审核通过后，中国电信物联网开放平台管理员会将Profile导入到中国电信物联网开放实验室。设备能力devicetype-capability.json记录了该设备的基础信息，以附录四中的WaterMeter_Huawei_NBIoTDevice.zip为例，如下：("devices":("manufacturer":&qu

15、ot;Huawei","manufacturerName":"Huawei","model":"NBIoTDevice","protocolType":"CoAP","deviceType":"WaterMeter","omCapability":"upgradeCapability":"supportUpgrade":true,"upgradeProtoc

16、olType":"PCP","fwUpgradeCapability":"supportUpgrade":true,"upgradeProtocolType":"LWM2M","configCapability":"supportConfig":true,"configMethod":"file","defaultConfigFile":"multiSensorInfo&quo

17、t;:"multiSensorPirTime":"300","serviceTypeCapabilities":"serviceId":"Brightness","serviceType":"Brightness","option":"Master","serviceId":"Electricity","serviceType":"Electric

18、ity","option":"Optional","serviceId":"Temperature","serviceType":"Temperature","option":"Optional"）对各字段的解释:字段可选/必选描述devices必选包含了一个设备的完整能力信息（根节点不能修改）manufacturerld必选指示设备的制造商IDmanufacturerName必选指示设备的制造商名称（只允许英文）model必

19、选指示设备的型号，考虑到一款设备下的多种型号建议包含字母或数字来保证可扩展性。protocolType必选指示设备接入平台的协议类型。如NB-IoT的设备取值为CoAPdeviceType必选指示设备的类型omCapability可选定义设备的软件升级、固件升级和配置更新的能力，字段含义详情见卜义中的：omCapability结构描述。如果设备不涉及软件/固件升级，本字段可以删除。字段可选/必选描述serviceTypeCapabilities必选包含了设备具备的服务能力描述serviceld必选服务的Id,如果设备中同类型的服务类型只有一个则serviceld与serviceType相同，如

20、果有多个则增加编号，如三键开关Switch01,Switch02,Switch03;serviceType必选服务类型比如DoorLock（门磁）、Smoke（烟感）与servicetype-capability.json中serviceType字段保持一aoption必选标识服务字段option可选范围Master（主服务），Mandatory（必选服务），Optional（可选服务）目前本字段是非功能性字段，仅起到描述作用。omCapability结构描述字段子字段可选/必选描述upgradeCapabilit可选设备软件升级能力字段子字段可选/必选描述ysupportUpgrade可选t

21、rue:设备支持软件升级false:设备小支持软件升级upgradeProtocolType可选升级使用的协议类型，此处不向于设备的protocolType,例如CoAP设备软件升级协议使用PCPfwUpgradeCapability可选设备固件升级能力supportUpgrade可选true:设备支持固件升级false:设备小支持固件升级upgradeProtocolType可选升级使用的协议类型，此处不向于设备的protocolType,当前中国电信物联网开放平台仅支持LWM2M固件升级configCapability可选设备配置更新能力supportConfig可选true:设备支持配置

22、更新false:设备不支持配置更新configMethod可选file:使用文件的方式下发配置更新defaultConfigFile可选设备默认配置信息，Json格式，具体配置信息由设备商自定义，I中国电信物联网开放平台只储存下发使用，不解析处理配置字段的具体含义。服务能力servicetype-capability.json记录了该设备的服务信息，以附录四中的WaterMeter_Huawei_NBIoTDevice.zip中的服务Brightness为例，如下:("services":("serviceType":"Brightness&q

23、uot;,"description":"Brightness","commands":("commandName":"SET_DEVICE_LEVEL","paras":("paraName":"value","dataType":"string","required":true,"min":0,"max":200,"step&

24、quot;:1,"maxLength":10,"unit":null,"enumList":null,"responses":"responseName":"SET_DEVICE_LEVEL_RSP","paras":"paraName":"result","dataType":"int","required":true,"min":-1

25、000000,"max":1000000,"step":1,"maxLength":10,"unit":null,"enumList":null,"commandName":"SET_PRESSURE_READ_PERIOD","paras":"paraName":"value","dataType":"int","required":t

26、rue,"min":1,"max":24,"step":1,"maxLength":10,"unit":"hour","enumList":null,"responses":"responseName":"SET_PRESSURE_READ_PERIOD_RSP","paras":"paraName":"result","dat

27、aType":"int","required":true,"min":-1000000,"max":1000000,"step":1,"maxLength":10,"unit":null,"enumList":null),"properties":("propertyName":"brightness","dataType":"int&q

28、uot;,"required":true,"min":0,"max":100,"step":1,"maxLength":null,"method":"RE","unit":null,"enumList":null)对各字段的解释：字段必选/可选描述services必选包含了一个服务的完整信息（根节点/、可修改）serviceType必选指示服务的类型如DoorLock(门磁)、Smoke(烟感)与devicetype

29、-capability.json中serviceType子段保description必选指示服务的描述信息文本描述，不影响实际功能，可置nullcommands必选指示设备可以执行的命令，如果本服务无命令则置nullcommandName必选指示命令的名字,如门磁的LOCK命令、摄像头的VIDEO_RECORD字段必选/可选描述命令，命令名与参数共向构成一个完整的命令paras必选命令包含的参数paraName必选命令中参数的名字dataType必选指示数据类型（必填）取值范围:string>int、stringlist、decimal、DateTime、jsonObject上报数据时，

30、复杂类型数据格式如下：stringlist:"str1","str2","str3"DateTime:yyyyMMdd'T'HHmmss'Z'如:20151212T121212ZjsonObject:自定义json结构体，平台不理解只透传required必选指示本条属性是否必选，取值为true或false,默认取值false（非必选）。目前本字段是非功能性字段，仅起到描述作用。min必选指示最小值仅当dataType为int、decimal时生效，逻辑大丁等于max必选指小取大值仅当dataType为i

31、nt、decimal时生效，逻辑小于等于step必选指示步长暂不使用，填。即可maxLength必选指示字符串长度仅当dataType为string、stringlist、DateTime时生效unit必指示单位，英义字段必选/可选描述选取值根据参数确定，如：温度单位：“C”或“K”百分比单位：“”压强单位：“Pa”或“kPa”enumList必选指示枚举值如升天状态statuspJ有如下取值"enumList":"OPEN","CLOSE"目前本字段是非功能性字段，仅起到描述作用。建议准确定义。responses必选命令执行的响应r

32、esponseName必选命名可以在该responses对应的命令的commandName后面添加“_RSP”paras必选命令响应的参数paraName必选命令中参数的名字dataType必选指示数据类型（必填）取值范围:string>int、stringlist、decimalDateTime、jsonObject上报数据时，复杂类型数据格式如下：stringlist:"str1","str2","str3"DateTime:yyyyMMdd'T'HHmmss'Z'如:20151212T121

33、212ZjsonObject:自定义json结构体，平台不理解只透传required必选指示本条属性是否必选，取值为true或false,默认取值false（非必选）。目前本字段是非功能性字段，仅起到描述作用。字段必选/可选描述min必选指示最小值仅当dataType为int、decimal时生效，逻辑大丁等于max必选指小取大值仅当dataType为int、decimal时生效，逻辑小于等于step必选指示步长暂不使用，填。即可maxLength必选指示字符串长度仅当dataType为string、stringlist、DateTime时生效unit必选指示单位，英文取值根据参数确定，如：温

34、度单位：“C”或“K”百分比单位：“”压强单位：“Pa”或“kPa”enumList必选指示枚举值如升天状态statuspJ有如下取值"enumList":"OPEN","CLOSE"目前本字段是非功能性字段，仅起到描述作用。建议准确定义。properties选上报数据描述，每一个子节点步-条属性propertyName必选指示属性名称（必填）dataType必选指示数据类型（必填）取值范围:string>int、stringlist、decimal、DateTime、jsonObject上报数据时，复杂类型数据格式如下：str

35、inglist:"str1","str2","str3"DateTime:yyyyMMdd'T'HHmmss'Z'如:20151212T121212Z字段必选/可选描述jsonObject:自定义json结构体，平台不理解只透传required必选指示本条属性是否必选，取值为true或false,默认取值false（非必选）。目前本字段是非功能性字段，仅起到描述作用。min必选指示最小值仅当dataType为int、decimal时生效，逻辑大丁等于max必选指小取大值仅当dataType为int、de

36、cimal时生效，逻辑小于等于step必选指示步长暂不使用，填。即可method必选指示访问模式R:可读；W:可写；E可订阅取值范围：R、RW、RE、RWE、nullunit必选指示单位，英文取值根据参数确定，如：温度单位：“C”或“K”百分比单位：“”压强单位：“Pa”或“kPa”maxLength必选指示字符串长度仅当dataType为string、stringlist、DateTime时生效enumList必选指示枚举值如烟感属性activityStatus可后如下取值"enumList":"STANDBY","RECORDING&quo

37、t;,"LIVING"目前本字段是非功能性字段，仅起到描述作用。建议准确定义。6附录附录一WaterProfile样例样例由三个文件构成，文件名和文件内容如下。1. devicetype-capability.json("devices":("manufacturerld":"0086","manufacturerName":"aeotec","model":"0002-002D","protocolType":&q

38、uot;Z-Wave","deviceType":"Water","omCapability":"upgradeCapability":"supportUpgrade":false,"fwUpgradeCapability":"supportUpgrade":true,"upgradeProtocolType":"LWM2M","downloadProtocolType":"C

39、oAP","serviceTypeCapabilities":"serviceId":"Water","serviceType":"Water","option":"Master","serviceId":"Battery","serviceType":"Battery","option":"Mandatory"2. servi

40、cetype-capability.json(Battery)"services":"serviceType":"Battery","description":"Battery","commands":null,"properties":("propertyName":"batteryLevel","dataType":"int","required":tr

41、ue,"min":0,"max":100,"step":1,"maxLength":null,"method":"RE","unit":null,"enumList":null,("propertyName":"batteryThreshold","dataType":"int","required":false,"min&qu

42、ot;:0,"max":100,"step":1,"maxLength":null,"method":"RE","unit":null,"enumList":null3. servicetype-capability.json(Water)("services":("serviceType":"Water","description":"WaterSensor&quo

43、t;,"commands":null,"properties":("propertyName":"Water","dataType":"string","required":true,"min":null,"max":null,"step":null,"maxLength":null,"method":"RE","unit&qu

44、ot;:null,"enumList":"DETECTED","DROPPED")附录二Water自定义服务类型样例样例由四个文件构成，文件名和文件内容如下。1. devicetype-capability.json("devices":("manufacturerld":"010F","manufacturerName":"Fibargroup","model":"0B00-3003",&quo

45、t;protocolType":"Z-Wave","deviceType":"Water","serviceTypeCapabilities":("serviceId":"Water","serviceType":"Water","option":"Master"),("serviceId":"Temperature","serviceT

46、ype":"Temperature","option":"Optional"),("serviceId":"Battery","serviceType":"Battery","option":"Mandatory")2. servicetype-capability.json(Battery)("services":("serviceType":"Batte

47、ry","description":"Battery","commands":null,"properties":("propertyName":"batteryLevel","dataType":"int","required":true,"min":0,"max":100,"step":1,"maxLength":null,

48、"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