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

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

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

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

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

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

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

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

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

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

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

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

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

13、apabilities:*) 圖中的BrightnessElectricity、Temperature者B是devicetype-capability.json中定義的服務(wù)。 Profile文件中的文檔格式都是json,在編輯完成后可以在互聯(lián)網(wǎng)上查找一些格式校驗(yàn)網(wǎng)站，檢查json的合法性。4設(shè)備Profile提供形式設(shè)備Profile寫作完成后，需要發(fā)給中國(guó)電信物聯(lián)網(wǎng)開放平臺(tái)管理員審核，審核通過(guò)后，中國(guó)電信物聯(lián)網(wǎng)開放平臺(tái)管理員會(huì)將Profile導(dǎo)入到中國(guó)電信物聯(lián)網(wǎng)開放實(shí)驗(yàn)室。設(shè)備能力devicetype-capability.json記錄了該設(shè)備的基礎(chǔ)信息，以附錄四中的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）對(duì)各字

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

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

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

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

20、Meter_Huawei_NBIoTDevice.zip中的服務(wù)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)對(duì)各字段的解釋：字段必選/可選描述services必選包含了一個(gè)服務(wù)的完整信

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

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

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

26、命令的commandName后面添加“_RSP”paras必選命令響應(yīng)的參數(shù)paraName必選命令中參數(shù)的名字dataType必選指示數(shù)據(jù)類型（必填）取值范圍:stringint、stringlist、decimalDateTime、jsonObject上報(bào)數(shù)據(jù)時(shí)，復(fù)雜類型數(shù)據(jù)格式如下：stringlist:str1,str2,str3DateTime:yyyyMMddTHHmmssZ如:20151212T121212ZjsonObject:自定義json結(jié)構(gòu)體，平臺(tái)不理解只透?jìng)鱮equired必選指示本條屬性是否必選，取值為true或false,默認(rèn)取值false（非必選）。目前本字段是非

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

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

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

30、t、DateTime時(shí)生效enumList必選指示枚舉值如煙感屬性activityStatus可后如下取值enumList:STANDBY,RECORDING,LIVING目前本字段是非功能性字段，僅起到描述作用。建議準(zhǔn)確定義。6附錄附錄一WaterProfile樣例樣例由三個(gè)文件構(gòu)成，文件名和文件內(nèi)容如下。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自定義服務(wù)類型樣例樣例由

34、四個(gè)文件構(gòu)成，文件名和文件內(nèi)容如下。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