中國電信物聯(lián)網(wǎng)開放平臺設備能力描述文件profile開發(fā)指引

1、中國電信物聯(lián)網(wǎng)開放平臺設備能力描述文件profile開發(fā)指南(V1)中國電信股份有限公司物聯(lián)網(wǎng)分公司二。一九年二月編制單位：編制單位中國電信股份有限公司物聯(lián)網(wǎng)分公司平臺運營部修訂記錄:版本號日期描述012017/11/06中國電信物聯(lián)網(wǎng)開放平臺_設備能力描述文件profile開發(fā)指南1前言.1.2概念2.3設備Profile寫作3.4設備Profile提供形式6.5設備Profile文件字段含義說明7.6附錄17.1、兒、,刖百概述開發(fā)者使用中國電信物聯(lián)網(wǎng)開放平臺集成設備時需要準備此設備的能力描述文件，本文檔針對此文件提供了具體的寫作過程和步驟。本文檔能指導開發(fā)者快速寫作設備能力描述Profi

2、le文件。讀者對象本文檔主要適用于智能家居設備廠商的開發(fā)人員，他們必須熟悉所要集成的智能家居產(chǎn)品的功能、掌握相關的物聯(lián)網(wǎng)協(xié)議和接口知識、具備一定的物聯(lián)網(wǎng)知識背景。符號約定在本文中可能出現(xiàn)下列標志，它們所代表的含義如下。符號說明危險表7K有高度潛在危險，如果不能避免，會導致人員死亡或嚴重傷害。警告表示有中度或低度潛在危險，如果不能避免，可能導致人員輕微或中等傷害。注意表示有潛在風險，如果忽視這些文本，可能導致設備損壞、數(shù)據(jù)丟失、設備性能降低或不可預知的結果。表示能幫助您解決某個問題或節(jié)省您的時間。2宓門0Q說明表示是正文的附加信息，是對正文的強調(diào)和補充。2概念設備的Profile文件是用來描述一

3、款設備是什么、能做什么以及如何控制該設備的文件。該文件會被上傳到中國電信物聯(lián)網(wǎng)開放平臺。1 .設備能力(DeviceCapability):描述一款設備的能力特征，包括設備類型、廠商、型號、協(xié)議類型名稱以及提供的服務類型。如右圖：彩燈的制造廠商：aeotec(制造商ID為0086),型號(0203-0062),協(xié)議類型億-wave)其服務包括：開關(Swtich),亮度(Brigthness),顏色(Color),其中亮度為主服務(Master),開關為必選服務(Mondatory),顏色為可選服務(Optional).2 .服務(Service):設備具有的某項服務(也可以理解為物理設備的功

4、能模塊或者虛擬設備提供的服務，如一個系統(tǒng)提供的天氣預報服務)，包括命令和屬性。如右圖：彩燈(LightBulb)有三個服務(service),開關(Switch),亮度(Brightness),顏色(Color);插座(Socket)有一個服務，開關(Switch);其中，開關服務有SWITCHON,OFF命令，有當前開關狀態(tài)status(ON,OFF)3設備Prof-寫作設備的Profile文件為json格式的文件。參考上面的說明，描述一款設備的能力信息，需要描述這款設備的識別屬性和提供的服務(功能)列表，其中：設備型號識別屬性：設備類型、廠商、型號、協(xié)議類型。服務列表：提供具體的功能服務說

5、明列表。命名規(guī)范對設備類型(deviceType)、服務類型(serviceType)、服務標識(serviceld)采用單詞首字母大寫的命名法：如：MultiSensor、Switch;參數(shù)使用第一個單次首字母小寫，其余單詞的首字母大寫的命名法：如"paraName":"color","dataType":"int"命令使用所有字母大寫，單詞間用下劃線連接的格式：如DISCOVERY,CHANGE_COLOR;設備能力描述json文件固定命名devicetype-capability.json；服務能力描述jso

6、n文件固定命名servicetype-capability.json；開發(fā)者需要注意，廠商標識、型號唯一標識一個設備類型，故這兩者不能與其他類型設備同時重復。僅支持英文。GQ說明在些profile樣例中您可能遇至U命名為devicetype-display.json或servicetype-display.json的文件，這些文件是用于智慧家庭領域的一些場景中的，如果中國電信人員與您交流方案的時候沒有涉及到，您的profile中可以不包含這些文件。設計規(guī)范要注重名稱的通用性，簡潔性；對于服務能力描述，還要考慮其功能性；如：對于多傳感器設備，就可以命名為Multi(多)Sensor(傳感器)；對

7、于某設備具有顯示電量的服務，就可以命名為Battery。設備Profile將一款新設備接入到中國電信物聯(lián)網(wǎng)開放平臺，首先需要編寫這款設備的profile。1 .設備模板中國電信物聯(lián)網(wǎng)開放平臺系統(tǒng)已經(jīng)提供了一批設備的profile（即設備模板，包括組成設備的功能服務描述列表），新增設備的類型和設備功能服務如果已經(jīng)在中國電信提供的列表中，可以直接選擇使用中國電信提供的設備類型和提供的設備功能服務。例如，接入一款水感（檢測是否漏水的Z-wave傳感器），可以使用中國電信定義的設備服務Water（描述檢測是否漏水功能）和Battery（描述該傳感器的電池電量信息），直接拷貝中國電信提供的模板，修改對應

8、設備型號標識屬性和設備服務列表。設備型號識別屬性：屬性Profile中key屬性值設備類型deviceTypeWater制造商IDmanufacturerId0086制造商名稱manufacturerNameaeotec設備型號Model0002-002D協(xié)議類型protocolTypeZ-Wave設備的服務列表服務描述服務標識(serviceId)服務類型(serviceType)選項(option)檢測是否漏水功能WaterWaterMaster電池服務BatteryBatteryMandatory根據(jù)上面的信息寫出具體的設備profile,參考附錄一WaterPro巾le樣例。其中可以對

9、服務的定義進行實例化修改，如：可以調(diào)整屬性的取值范圍、或枚舉值等。電說明中國電信支持的服務列表參考附錄三已支持的服務列表。開發(fā)者的設備類型中國電信是否支持，可以咨詢中國電信物聯(lián)網(wǎng)開放平臺管理員。如果開發(fā)者的設備類型或服務類型中國電信已經(jīng)支持，則開發(fā)者可以找中國電信物聯(lián)網(wǎng)開放平臺管理員獲取設備及服務的Profile文件參考。設備型號建議由產(chǎn)品類型ID和產(chǎn)品ID組合構成，例如一家廠商的門磁，通過Z-Wave認證得到的ProductTypeld為0x0168,ProductId為0x0188,則設備型號對應為“0168-0188”。2 .自定義服務類型例如，接入一款水感（檢測是否漏水的Z-wave傳

10、感器），有描述檢測是否漏水功能（Water）和電池服務（Battery）而且還有測量溫度功能服務（Temperature）,假設該服務中國電信物聯(lián)網(wǎng)開放平臺沒有提供則可以自定義。設備型號識別屬性：屬性Profile中key屬性值屬性Profile中key屬性值設備類型deviceTypeWater制造商IDmanufacturerId010F制造商名稱manufacturerNameFibargroup設備型號model0B00-3003協(xié)議類型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,在編輯完成后可以在互聯(lián)網(wǎng)上查找一些格式校驗網(wǎng)站，檢查json的合法性。4設備Profile提供形式設備Profile寫作完成后，需要發(fā)給中國電信物聯(lián)網(wǎng)開放平臺管理員審核，審核通過后，中國電信物聯(lián)網(wǎng)開放平臺管理員會將Profile導入到中國電信物聯(lián)網(wǎng)開放實驗室。設備能力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必選包含了一個設備的完整能力信息（根節(jié)點不能修改）manufacturerld必選指示設備的制造商IDmanufacturerName必選指示設備的制造商名稱（只允許英文）model必

19、選指示設備的型號，考慮到一款設備下的多種型號建議包含字母或數(shù)字來保證可擴展性。protocolType必選指示設備接入平臺的協(xié)議類型。如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可選升級使用的協(xié)議類型，此處不向于設備的protocolType,例如CoAP設備軟件升級協(xié)議使用PCPfwUpgradeCapability可選設備固件升級能力supportUpgrade可選true:設備支持固件升級false:設備小支持固件升級upgradeProtocolType可選升級使用的協(xié)議類型，此處不向于設備的protocolType,當前中國電信物聯(lián)網(wǎng)開放平臺僅支持LWM2M固件升級configCapability可選設備配置更新能力supportConfig可選true:設備支持配置

22、更新false:設備不支持配置更新configMethod可選file:使用文件的方式下發(fā)配置更新defaultConfigFile可選設備默認配置信息，Json格式，具體配置信息由設備商自定義，I中國電信物聯(lián)網(wǎng)開放平臺只儲存下發(fā)使用，不解析處理配置字段的具體含義。服務能力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必選包含了一個服務的完整信息（根節(jié)點/、可修改）serviceType必選指示服務的類型如DoorLock(門磁)、Smoke(煙感)與devicetype

29、-capability.json中serviceType子段保description必選指示服務的描述信息文本描述，不影響實際功能，可置nullcommands必選指示設備可以執(zhí)行的命令，如果本服務無命令則置nullcommandName必選指示命令的名字,如門磁的LOCK命令、攝像頭的VIDEO_RECORD字段必選/可選描述命令，命令名與參數(shù)共向構成一個完整的命令paras必選命令包含的參數(shù)paraName必選命令中參數(shù)的名字dataType必選指示數(shù)據(jù)類型（必填）取值范圍:string>int、stringlist、decimal、DateTime、jsonObject上報數(shù)據(jù)時，

30、復雜類型數(shù)據(jù)格式如下：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必指示單位，英義字段必選/可選描述選取值根據(jù)參數(shù)確定，如：溫度單位：“C”或“K”百分比單位：“”壓強單位：“Pa”或“kPa”enumList必選指示枚舉值如升天狀態(tài)statuspJ有如下取值"enumList":"OPEN","CLOSE"目前本字段是非功能性字段，僅起到描述作用。建議準確定義。responses必選命令執(zhí)行的響應r

32、esponseName必選命名可以在該responses對應的命令的commandName后面添加“_RSP”paras必選命令響應的參數(shù)paraName必選命令中參數(shù)的名字dataType必選指示數(shù)據(jù)類型（必填）取值范圍:string>int、stringlist、decimalDateTime、jsonObject上報數(shù)據(jù)時，復雜類型數(shù)據(jù)格式如下：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必選指示單位，英文取值根據(jù)參數(shù)確定，如：溫

34、度單位：“C”或“K”百分比單位：“”壓強單位：“Pa”或“kPa”enumList必選指示枚舉值如升天狀態(tài)statuspJ有如下取值"enumList":"OPEN","CLOSE"目前本字段是非功能性字段，僅起到描述作用。建議準確定義。properties選上報數(shù)據(jù)描述，每一個子節(jié)點步-條屬性propertyName必選指示屬性名稱（必填）dataType必選指示數(shù)據(jù)類型（必填）取值范圍:string>int、stringlist、decimal、DateTime、jsonObject上報數(shù)據(jù)時，復雜類型數(shù)據(jù)格式如下：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必選指示單位，英文取值根據(jù)參數(shù)確定，如：溫度單位：“C”或“K”百分比單位：“”壓強單位：“Pa”或“kPa”maxLength必選指示字符串長度僅當dataType為string、stringlist、DateTime時生效enumList必選指示枚舉值如煙感屬性activityStatus可后如下取值"enumList":"STANDBY","RECORDING&quo

37、t;,"LIVING"目前本字段是非功能性字段，僅起到描述作用。建議準確定義。6附錄附錄一WaterProfile樣例樣例由三個文件構成，文件名和文件內(nèi)容如下。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自定義服務類型樣例樣例由四個文件構成，文件名和文件內(nèi)容如下。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