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

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

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

8、viceTypeWater制造商IDmanufacturerId0086制造商名稱manufacturerNameaeotec設備型號Model0002-002D協(xié)議類型protocolTypeZ-Wave設備的服務列表服務描述服務標識(serviceId)服務類型(serviceType)選項(option)檢測是否漏水功能WaterWaterMaster電池服務BatteryBatteryMandatory根據(jù)上面的信息寫出具體的設備profile,參考附錄一WaterPro巾le樣例。其中可以對服務的定義進行實例化修改，如：可以調整屬性的取值范圍、或枚舉值等。電說明中國電信支持的服務列表

9、參考附錄三已支持的服務列表。開發(fā)者的設備類型中國電信是否支持，可以咨詢中國電信物聯(lián)網(wǎng)開放平臺管理員。如果開發(fā)者的設備類型或服務類型中國電信已經支持，則開發(fā)者可以找中國電信物聯(lián)網(wǎng)開放平臺管理員獲取設備及服務的Profile文件參考。設備型號建議由產品類型ID和產品ID組合構成，例如一家廠商的門磁，通過Z-Wave認證得到的ProductTypeld為0x0168,ProductId為0x0188,則設備型號對應為“0168-0188”。2 .自定義服務類型例如，接入一款水感（檢測是否漏水的Z-wave傳感器），有描述檢測是否漏水功能（Water）和電池服務（Battery）而且還有測量溫度功能服

10、務（Temperature）,假設該服務中國電信物聯(lián)網(wǎng)開放平臺沒有提供則可以自定義。設備型號識別屬性：屬性Profile中key屬性值屬性Profile中key屬性值設備類型deviceTypeWater制造商IDmanufacturerId010F制造商名稱manufacturerNameFibargroup設備型號model0B00-3003協(xié)議類型protocolTypeZ-Wave設備的服務列表:服務描述服務標識（serviceId服務類型（serviceType選項（option）檢測是否漏水功能WaterWaterMaster電池服務BatteryBatteryMandatory測

11、量溫度功能TemperatureTemperatureOptional具體的profile參考附錄二Water自定義服務類型樣例。Profile的打包Profile寫作完成后，需要按如下表格形式打包。下面以附錄四中WaterMeter_Huawei_NBIoTDevice.zip為例介紹。Water忸jHuawe_NBloT&evke.iipproElctncity關于上圖有幾點說明:Profile文件的目錄層級結構必須如圖所示，不能增刪；比如第二層級必須只有profile和service”兩個文件夾，每個服務下面必須包含“profile”等。圖中橙色的命名不能改動； 整個Profile以zi

12、p形式壓縮； Profile文件的命名必須按照deviceType_manufacturerId_model的格式命名，其中的deviceType、manufacturerId、model必須與devicetype-capability.json中的對應字段的定義一致，例如，本例中的devicetype-capability.json的主要字段如下：devices:manufacturerId:Huawei,manufacturerName:Huawei,model:NBIoTDevice,protocolType:CoAP,deviceType:WaterMeter,serviceTypeC

13、apabilities:*) 圖中的BrightnessElectricity、Temperature者B是devicetype-capability.json中定義的服務。 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_H

14、uawei_NBIoTDevice.zip為例，如下：(devices:(manufacturer:Huawei,manufacturerName:Huawei,model:NBIoTDevice,protocolType:CoAP,deviceType:WaterMeter,omCapability:upgradeCapability:supportUpgrade:true,upgradeProtocolType:PCP,fwUpgradeCapability:supportUpgrade:true,upgradeProtocolType:LWM2M,configCapability:sup

15、portConfig:true,configMethod:file,defaultConfigFile:multiSensorInfo:multiSensorPirTime:300,serviceTypeCapabilities:serviceId:Brightness,serviceType:Brightness,option:Master,serviceId:Electricity,serviceType:Electricity,option:Optional,serviceId:Temperature,serviceType:Temperature,option:Optional）對各字

16、段的解釋:字段可選/必選描述devices必選包含了一個設備的完整能力信息（根節(jié)點不能修改）manufacturerld必選指示設備的制造商IDmanufacturerName必選指示設備的制造商名稱（只允許英文）model必選指示設備的型號，考慮到一款設備下的多種型號建議包含字母或數(shù)字來保證可擴展性。protocolType必選指示設備接入平臺的協(xié)議類型。如NB-IoT的設備取值為CoAPdeviceType必選指示設備的類型omCapability可選定義設備的軟件升級、固件升級和配置更新的能力，字段含義詳情見卜義中的：omCapability結構描述。如果設備不涉及軟件/固件升級，本字段

17、可以刪除。字段可選/必選描述serviceTypeCapabilities必選包含了設備具備的服務能力描述serviceld必選服務的Id,如果設備中同類型的服務類型只有一個則serviceld與serviceType相同，如果有多個則增加編號，如三鍵開關Switch01,Switch02,Switch03;serviceType必選服務類型比如DoorLock（門磁）、Smoke（煙感）與servicetype-capability.json中serviceType字段保持一aoption必選標識服務字段option可選范圍Master（主服務），Mandatory（必選服務），Option

18、al（可選服務）目前本字段是非功能性字段，僅起到描述作用。omCapability結構描述字段子字段可選/必選描述upgradeCapabilit可選設備軟件升級能力字段子字段可選/必選描述ysupportUpgrade可選true:設備支持軟件升級false:設備小支持軟件升級upgradeProtocolType可選升級使用的協(xié)議類型，此處不向于設備的protocolType,例如CoAP設備軟件升級協(xié)議使用PCPfwUpgradeCapability可選設備固件升級能力supportUpgrade可選true:設備支持固件升級false:設備小支持固件升級upgradeProtocolT

19、ype可選升級使用的協(xié)議類型，此處不向于設備的protocolType,當前中國電信物聯(lián)網(wǎng)開放平臺僅支持LWM2M固件升級configCapability可選設備配置更新能力supportConfig可選true:設備支持配置更新false:設備不支持配置更新configMethod可選file:使用文件的方式下發(fā)配置更新defaultConfigFile可選設備默認配置信息，Json格式，具體配置信息由設備商自定義，I中國電信物聯(lián)網(wǎng)開放平臺只儲存下發(fā)使用，不解析處理配置字段的具體含義。服務能力servicetype-capability.json記錄了該設備的服務信息，以附錄四中的Water

20、Meter_Huawei_NBIoTDevice.zip中的服務Brightness為例，如下:(services:(serviceType:Brightness,description:Brightness,commands:(commandName:SET_DEVICE_LEVEL,paras:(paraName:value,dataType:string,required:true,min:0,max:200,step:1,maxLength:10,unit:null,enumList:null,responses:responseName:SET_DEVICE_LEVEL_RSP,pa

21、ras:paraName:result,dataType:int,required:true,min:-1000000,max:1000000,step:1,maxLength:10,unit:null,enumList:null,commandName:SET_PRESSURE_READ_PERIOD,paras:paraName:value,dataType:int,required:true,min:1,max:24,step:1,maxLength:10,unit:hour,enumList:null,responses:responseName:SET_PRESSURE_READ_P

22、ERIOD_RSP,paras:paraName:result,dataType:int,required:true,min:-1000000,max:1000000,step:1,maxLength:10,unit:null,enumList:null),properties:(propertyName:brightness,dataType:int,required:true,min:0,max:100,step:1,maxLength:null,method:RE,unit:null,enumList:null)對各字段的解釋：字段必選/可選描述services必選包含了一個服務的完整信

23、息（根節(jié)點/、可修改）serviceType必選指示服務的類型如DoorLock(門磁)、Smoke(煙感)與devicetype-capability.json中serviceType子段保description必選指示服務的描述信息文本描述，不影響實際功能，可置nullcommands必選指示設備可以執(zhí)行的命令，如果本服務無命令則置nullcommandName必選指示命令的名字,如門磁的LOCK命令、攝像頭的VIDEO_RECORD字段必選/可選描述命令，命令名與參數(shù)共向構成一個完整的命令paras必選命令包含的參數(shù)paraName必選命令中參數(shù)的名字dataType必選指示數(shù)據(jù)類型（必

24、填）取值范圍:stringint、stringlist、decimal、DateTime、jsonObject上報數(shù)據(jù)時，復雜類型數(shù)據(jù)格式如下：stringlist:str1,str2,str3DateTime:yyyyMMddTHHmmssZ如:20151212T121212ZjsonObject:自定義json結構體，平臺不理解只透傳required必選指示本條屬性是否必選，取值為true或false,默認取值false（非必選）。目前本字段是非功能性字段，僅起到描述作用。min必選指示最小值僅當dataType為int、decimal時生效，邏輯大丁等于max必選指小取大值僅當dataT

25、ype為int、decimal時生效，邏輯小于等于step必選指示步長暫不使用，填。即可maxLength必選指示字符串長度僅當dataType為string、stringlist、DateTime時生效unit必指示單位，英義字段必選/可選描述選取值根據(jù)參數(shù)確定，如：溫度單位：“C”或“K”百分比單位：“”壓強單位：“Pa”或“kPa”enumList必選指示枚舉值如升天狀態(tài)statuspJ有如下取值enumList:OPEN,CLOSE目前本字段是非功能性字段，僅起到描述作用。建議準確定義。responses必選命令執(zhí)行的響應responseName必選命名可以在該responses對應的

26、命令的commandName后面添加“_RSP”paras必選命令響應的參數(shù)paraName必選命令中參數(shù)的名字dataType必選指示數(shù)據(jù)類型（必填）取值范圍:stringint、stringlist、decimalDateTime、jsonObject上報數(shù)據(jù)時，復雜類型數(shù)據(jù)格式如下：stringlist:str1,str2,str3DateTime:yyyyMMddTHHmmssZ如:20151212T121212ZjsonObject:自定義json結構體，平臺不理解只透傳required必選指示本條屬性是否必選，取值為true或false,默認取值false（非必選）。目前本字段是非

27、功能性字段，僅起到描述作用。字段必選/可選描述min必選指示最小值僅當dataType為int、decimal時生效，邏輯大丁等于max必選指小取大值僅當dataType為int、decimal時生效，邏輯小于等于step必選指示步長暫不使用，填。即可maxLength必選指示字符串長度僅當dataType為string、stringlist、DateTime時生效unit必選指示單位，英文取值根據(jù)參數(shù)確定，如：溫度單位：“C”或“K”百分比單位：“”壓強單位：“Pa”或“kPa”enumList必選指示枚舉值如升天狀態(tài)statuspJ有如下取值enumList:OPEN,CLOSE目前本字段

28、是非功能性字段，僅起到描述作用。建議準確定義。properties選上報數(shù)據(jù)描述，每一個子節(jié)點步-條屬性propertyName必選指示屬性名稱（必填）dataType必選指示數(shù)據(jù)類型（必填）取值范圍:stringint、stringlist、decimal、DateTime、jsonObject上報數(shù)據(jù)時，復雜類型數(shù)據(jù)格式如下：stringlist:str1,str2,str3DateTime:yyyyMMddTHHmmssZ如:20151212T121212Z字段必選/可選描述jsonObject:自定義json結構體，平臺不理解只透傳required必選指示本條屬性是否必選，取值為tru

29、e或false,默認取值false（非必選）。目前本字段是非功能性字段，僅起到描述作用。min必選指示最小值僅當dataType為int、decimal時生效，邏輯大丁等于max必選指小取大值僅當dataType為int、decimal時生效，邏輯小于等于step必選指示步長暫不使用，填。即可method必選指示訪問模式R:可讀；W:可寫；E可訂閱取值范圍：R、RW、RE、RWE、nullunit必選指示單位，英文取值根據(jù)參數(shù)確定，如：溫度單位：“C”或“K”百分比單位：“”壓強單位：“Pa”或“kPa”maxLength必選指示字符串長度僅當dataType為string、stringlis

30、t、DateTime時生效enumList必選指示枚舉值如煙感屬性activityStatus可后如下取值enumList:STANDBY,RECORDING,LIVING目前本字段是非功能性字段，僅起到描述作用。建議準確定義。6附錄附錄一WaterProfile樣例樣例由三個文件構成，文件名和文件內容如下。1. devicetype-capability.json(devices:(manufacturerld:0086,manufacturerName:aeotec,model:0002-002D,protocolType:Z-Wave,deviceType:Water,omCapabil

31、ity:upgradeCapability:supportUpgrade:false,fwUpgradeCapability:supportUpgrade:true,upgradeProtocolType:LWM2M,downloadProtocolType:CoAP,serviceTypeCapabilities:serviceId:Water,serviceType:Water,option:Master,serviceId:Battery,serviceType:Battery,option:Mandatory2. servicetype-capability.json(Battery)

32、services:serviceType:Battery,description:Battery,commands:null,properties:(propertyName:batteryLevel,dataType:int,required:true,min:0,max:100,step:1,maxLength:null,method:RE,unit:null,enumList:null,(propertyName:batteryThreshold,dataType:int,required:false,min:0,max:100,step:1,maxLength:null,method:

33、RE,unit:null,enumList:null3. servicetype-capability.json(Water)(services:(serviceType:Water,description:WaterSensor,commands:null,properties:(propertyName:Water,dataType:string,required:true,min:null,max:null,step:null,maxLength:null,method:RE,unit:null,enumList:DETECTED,DROPPED)附錄二Water自定義服務類型樣例樣例由

34、四個文件構成，文件名和文件內容如下。1. devicetype-capability.json(devices:(manufacturerld:010F,manufacturerName:Fibargroup,model:0B00-3003,protocolType:Z-Wave,deviceType:Water,serviceTypeCapabilities:(serviceId:Water,serviceType:Water,option:Master),(serviceId:Temperature,serviceType:Temperature,option:Optional),(ser

35、viceId:Battery,serviceType:Battery,option:Mandatory)2. servicetype-capability.json(Battery)(services:(serviceType:Battery,description:Battery,commands:null,properties:(propertyName:batteryLevel,dataType:int,required:true,min:0,max:100,step:1,maxLength:null,method:RE,unit:null,enumList:null).(propertyName:batteryThreshold,dataType:int,required:false,min:0,max:100,step:1