文档首页/ IoT物联网/ 开发指南/ 平台侧开发/ 开发Profile/ 离线开发Profile(联通用户专用)
更新时间:2023-04-07 GMT+08:00
分享

离线开发Profile(联通用户专用)

非联通用户请查看设备接入服务

Profile本质上就是一个devicetype-capability.json文件和若干个serviceType-capability.json文件,按照如下目录打包的一个zip包。其中WaterMeter是deviceType,TestUtf8Manuld是manufactureId,NBIoTDevice是model,WaterMeterBasic/WaterMeterAlarm/Battery是服务名。

所以离线开发profile就是按照Profile编写规则和JSON格式规范在devicetype-capability.json中定义设备能力,在servicetype-capability.json中定义服务能力。因此离线开发Profile需要熟悉JSON的格式。

由于离线开发Profile文件相对在线开发比较耗时,因此推荐在线开发Profile(联通用户专用)

命名规范

在Profile的开发过程中,需要遵循如下命名规范:

  • 设备类型(deviceType)、服务类型(serviceType)、服务标识(serviceId)采用单词首字母大写的命名法。例如:WaterMeter、Battery。
  • 属性使用第一个单词首字母小写,其余单词的首字母大写的命名法。例如:batteryLevel、internalTemperature。
  • 命令使用所有字母大写,单词间用下划线连接的格式。例如:DISCOVERY,CHANGE_COLOR。
  • 设备能力描述json文件固定命名devicetype-capability.json。
  • 服务能力描述json文件固定命名servicetype-capability.json。
  • 厂商ID和型号唯一标识一款产品,故这些信息的组合在不同的Profile文件中不能重复,且仅支持英文。
  • 要注重名称的通用性,简洁性;对于服务能力描述,还要考虑其功能性。例如:对于多传感器设备,可以命名为MultiSensor;对于具有显示电量的服务,可以命名为Battery。

Profile模板

将一款新设备接入到物联网平台,首先需要编写这款设备的Profile。物联网平台提供了一些Profile文件模板,如果新增接入设备的类型和功能服务已经在物联网平台提供的设备Profile模板中包含,则可以直接选择使用;如果在物联网平台提供的设备Profile模板中未包含,则需要自己定义。

例如:接入一款水表 ,可以直接选择物联网平台上对应的Profile模板,修改设备型号标识属性和设备服务列表。

物联网平台提供的Profile模板会不断更新,如下表格列举设备类型和服务类型示例,仅供参考。

设备型号识别属性:

属性

Profile中key

属性值

设备类型

deviceType

WaterMeter

厂商ID

manufacturerId

TestUtf8ManuId

厂商名称

manufacturerName

HZYB

型号

model

NBIoTDevice

协议类型

protocolType

CoAP

设备的服务列表

服务描述

服务标识(serviceId)

服务类型(serviceType)

选项(option)

水表的基本功能

WaterMeterBasic

Water

Mandatory

告警服务

WaterMeterAlarm

Battery

Mandatory

电池服务

Battery

Battery

Optional

数据的上报规则

DeliverySchedule

DeliverySchedule

Mandatory

水表的连通性

Connectivity

Connectivity

Mandatory

设备能力定义样例

devicetype-capability.json记录了该设备的基础信息:

{
    "devices": [
        {
            "manufacturerId": "TestUtf8ManuId",
            "manufacturerName": "HZYB",
            "model": "NBIoTDevice",
            "protocolType": "CoAP",
            "deviceType": "WaterMeter",
            "omCapability":{ 
                          "upgradeCapability" : { 
                               "supportUpgrade":true,
                               "upgradeProtocolType":"PCP"
                         }, 
                         "fwUpgradeCapability" : {                  
                               "supportUpgrade":true,    
                               "upgradeProtocolType":"LWM2M"
                         },
                         "configCapability" : {                  
                               "supportConfig":true,
                               "configMethod":"file",
                               "defaultConfigFile": {
                                  "waterMeterInfo" : {
                                       "waterMeterPirTime" : "300"
                                   }
                               }
                         } 
             }, 
             "serviceTypeCapabilities": [
                {
                    "serviceId": "WaterMeterBasic",
                    "serviceType": "WaterMeterBasic",
                    "option": "Mandatory"
                },
                {
                    "serviceId": "WaterMeterAlarm",
                    "serviceType": "WaterMeterAlarm",
                    "option": "Mandatory"
                },
                {
                    "serviceId": "Battery",
                    "serviceType": "Battery",
                    "option": "Optional"
                },
                {
                    "serviceId": "DeliverySchedule",
                    "serviceType": "DeliverySchedule",
                    "option": "Mandatory"
                },
                {
                    "serviceId": "Connectivity",
                    "serviceType": "Connectivity",
                    "option": "Mandatory"
                }
            ]
        }
    ]
}

各字段的解释:

字段

子字段

可选/必选

描述

devices

     

必选

包含了一个设备的完整能力信息(根节点不能修改)。

  

manufacturerId

  

必选

指示设备的制造商ID。

  

manufacturerName

  

必选

指示设备的制造商名称 (只允许英文)。

  

model

  

必选

指示设备的型号,考虑到一款设备下的多种型号,建议包含字母或数字以保证可扩展性。

  

protocolType

  

必选

指示设备接入物联网平台的协议类型。如NB-IoT的设备取值为CoAP。

  

deviceType

  

必选

指示设备的类型。

  

omCapability

  

可选

定义设备的软件升级、固件升级和配置更新的能力,字段含义详情见下文中的:omCapability结构描述。

如果设备不涉及软件/固件升级,本字段可以删除。

  

serviceTypeCapabilities

  

必选

包含了设备具备的服务能力描述。

     

serviceId

必选

服务的Id,如果设备中同类型的服务类型只有一个则serviceId与serviceType相同, 如果有多个则增加编号,如三键开关 Switch01、Switch02、Switch03。

     

serviceType

必选

服务类型,与servicetype-capability.json中serviceType字段保持一致。

     

option

必选

标识服务字段的类型,取值范围:Master(主服务), Mandatory(必选服务), Optional(可选服务)。

目前本字段为非功能性字段,仅起到描述作用。

omCapability结构描述

字段

子字段

可选/必选

描述

upgradeCapability

  

可选

设备软件升级能力。

  

supportUpgrade

可选

true:设备支持软件升级。

false:设备不支持软件升级。

  

upgradeProtocolType

可选

升级使用的协议类型,此处不同于设备的protocolType,例如CoAP设备软件升级协议使用PCP。

fwUpgradeCapability

  

可选

设备固件升级能力。

  

supportUpgrade

可选

true:设备支持固件升级。

false:设备不支持固件升级。

  

upgradeProtocolType

可选

升级使用的协议类型,此处不同于设备的protocolType,当前物联网平台仅支持LWM2M固件升级。

configCapability

  

可选

设备配置更新能力。

  

supportConfig

可选

true:设备支持配置更新。

false:设备不支持配置更新。

  

configMethod

可选

file:使用文件的方式下发配置更新。

  

defaultConfigFile

可选

设备默认配置信息(Json格式),具体配置信息由设备商自定义。物联网平台只储存该信息供下发时使用,不解析处理配置字段的具体含义。

服务能力定义样例

servicetype-capability.json记录了该设备的服务信息:

{
    "services": [
        {
            "serviceType": "WaterMeterBasic",
            "description": "WaterMeterBasic",
            "commands": [
                {
                    "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_PERIOD_RSP",
                            "paras": [
                                {
                                    "paraName": "result",
                                    "dataType": "int",
                                    "required": true,
                                    "min": -1000000,
                                    "max": 1000000,
                                    "step": 1,
                                    "maxLength": 10,
                                    "unit": null,
                                    "enumList": null
                                }
                            ]
                        }
                    ]
                }
            ],
            "properties": [
                {
                    "propertyName": "registerFlow",
                    "dataType": "int",
                    "required": true,
                    "min": 0,
                    "max": 0,
                    "step": 1,
                    "maxLength": 0,
                    "method": "R",
                    "unit": null,
                    "enumList": null
                },
                {
                    "propertyName": "currentReading",
                    "dataType": "string",
                    "required": false,
                    "min": 0,
                    "max": 0,
                    "step": 1,
                    "maxLength": 0,
                    "method": "W",
                    "unit": "L",
                    "enumList": null
                },
                {
                    "propertyName": "timeOfReading",
                    "dataType": "string",
                    "required": false,
                    "min": 0,
                    "max": 0,
                    "step": 1,
                    "maxLength": 0,
                    "method": "W",
                    "unit": null,
                    "enumList": null
                },
                ......
            ]
        }
    ]
}

各字段的解释:

字段

子字段

必选/可选

描述

services

           

必选

包含了一个服务的完整信息(根节点不可修改)。

  

serviceType

        

必选

指示服务的类型,与devicetype-capability.json中serviceType字段保持一致。

  

description

        

必选

指示服务的描述信息。

非功能性字段,仅起到描述作用,可置为null。

  

commands

        

必选

指示设备可以执行的命令,如果本服务无命令则置null。

     

commandName

     

必选

指示命令的名字,命令名与参数共同构成一个完整的命令。

     

paras

     

必选

命令包含的参数。

        

paraName

  

必选

命令中参数的名字。

        

dataType

  

必选

指示命令参数的数据类型。

取值范围:string、int、string list、decimal、DateTime、jsonObject、enum、boolean。

上报数据时,复杂类型数据格式如下:

  • string list:["str1","str2","str3"]
  • DateTime:yyyyMMdd’T’HHmmss’Z’如:20151212T121212Z
  • jsonObject:自定义json结构体,物联网平台不解析,仅进行透传
        

required

  

必选

指示本命令是否必选,取值为true或false,默认取值false(非必选)。

目前本字段是非功能性字段,仅起到描述作用。

        

min

  

必选

指示最小值。

仅当dataType为int、decimal时生效。

        

max

  

必选

指示最大值。

仅当dataType为int、decimal时生效。

        

step

  

必选

指示步长。

暂不使用,填0即可。

        

maxLength

  

必选

指示字符串长度。

仅当dataType为string、string list、DateTime时生效。

        

unit

  

必选

指示单位,英文。

取值根据参数确定,如:

温度单位:“C”或“K”

百分比单位:“%”

压强单位:“Pa”或“kPa”

        

enumList

  

必选

指示枚举值。

如开关状态status可有如下取值:

"enumList" : ["OPEN","CLOSE"]

目前本字段是非功能性字段,仅起到描述作用,建议准确定义。

     

responses

     

必选

命令执行的响应。

        

responseName

  

必选

命名可以在该responses对应命令的commandName后面添加“_RSP”。

        

paras

  

必选

命令响应的参数。

           

paraName

必选

命令中参数的名字。

           

dataType

必选

指示数据类型。

取值范围:string、int、string list、decimal、DateTime、jsonObject

上报数据时,复杂类型数据格式如下:

  • string list:["str1","str2","str3"]
  • DateTime:yyyyMMdd’T’HHmmss’Z’如:20151212T121212Z
  • jsonObject:自定义json结构体,物联网平台不解析,仅进行透传
           

required

必选

指示本命令响应是否必选,取值为true或false,默认取值false(非必选)。

目前本字段是非功能性字段,仅起到描述作用。

           

min

必选

指示最小值。

仅当dataType为int、decimal时生效,逻辑大于等于。

           

max

必选

指示最大值。

仅当dataType为int、decimal时生效,逻辑小于等于。

           

step

必选

指示步长。

暂不使用,填0即可。

           

maxLength

必选

指示字符串长度。

仅当dataType为string、string list、DateTime时生效。

           

unit

必选

指示单位,英文。

取值根据参数确定,如:

温度单位:“C”或“K”

百分比单位:“%”

压强单位:“Pa”或“kPa”

           

enumList

必选

指示枚举值。

如开关状态status可有如下取值:

"enumList" : ["OPEN","CLOSE"]

目前本字段是非功能性字段,仅起到描述作用,建议准确定义。

  

properties

        

必选

上报数据描述,每一个子节点为一条属性。

     

propertyName

     

必选

指示属性名称。

     

dataType

     

必选

指示数据类型。

取值范围:string、int、string list、decimal、DateTime、jsonObject

上报数据时,复杂类型数据格式如下:

  • string list:["str1","str2","str3"]
  • DateTime:yyyyMMdd’T’HHmmss’Z’如:20151212T121212Z
  • jsonObject:自定义json结构体,物联网平台不解析,仅进行透传
     

required

     

必选

指示本条属性是否必选,取值为true或false,默认取值false(非必选)。

目前本字段是非功能性字段,仅起到描述作用。

     

min

     

必选

指示最小值。

仅当dataType为int、decimal时生效,逻辑大于等于。

     

max

     

必选

指示最大值。

仅当dataType为int、decimal时生效,逻辑小于等于。

     

step

     

必选

指示步长。

暂不使用,填0即可。

     

method

     

必选

指示访问模式。

R:可读;W:可写;E:可订阅。

取值范围:R、RW、RE、RWE 、null。

     

unit

     

必选

指示单位,英文。

取值根据参数确定,如:

温度单位:“C”或“K”

百分比单位:“%”

压强单位:“Pa”或“kPa”

     

maxLength

     

必选

指示字符串长度。

仅当dataType为string、string list、DateTime时生效。

     

enumList

     

必选

指示枚举值。

如电池状态(batteryStatus)可有如下取值:

"enumList" : [0, 1, 2, 3, 4, 5, 6]

目前本字段是非功能性字段,仅起到描述作用,建议准确定义。

Profile打包

Profile写作完成后,需要按如下层级结构打包:

Profile打包需要遵循如下几点要求:

  • Profile文件的目录层级结构必须如上图所示,不能增删。例如:第二层级只能有“profile”和“service”两个文件夹,每个服务下面必须包含“profile”文件夹等。
  • 图中橙色字体的命名不能改动。
  • Profile文件以zip形式压缩。
  • Profile文件的命名必须按照deviceType_manufacturerId_model的格式命名,其中的deviceType、manufacturerId、model必须与devicetype-capability.json中对应字段的定义一致。例如:本实例中devicetype-capability.json的主要字段如下:
    {  
        "devices": [  
            {  
                "manufacturerId": "TestUtf8ManuId",  
                "manufacturerName": "HZYB",  
                "model": "NBIoTDevice",  
                "protocolType": "CoAP",  
                "deviceType": "WaterMeter",  
                "serviceTypeCapabilities": **** 
            }  
        ]  
    }
  • 图中的WaterMeterBasic、WaterMeterAlarm、Battery等都是devicetype-capability.json中定义的服务。

Profile文件中的文档格式都是JSON,在编写完成后可以在互联网上查找一些格式校验网站,检查JSON的合法性。

相关文档