如何看懂deviceprofile文件

灰哥哥

1、先看一个简单的MBUS-RTH-LCD.profile.yaml文件


name: "MBUS_RTH_LCD"                #设备名称
manufacturer: "DATANAB"               #设备制造商
model: "MBUS_RTH_LCD"               #设备型号
labels:                                               #设备标签 ，可定义多个
- "temperature"
- "modbus"
- "industrial"
description: "Modbus Enabled Room Temperature/Humididty Sensor with LCD"  #设备描述

#1、object片段（ 设备资源片段）

deviceResources:                         #设备所有资源，在java代码里它也叫object
      -
        name: "TemperatureDegF"      #设备资源名称
        description: "Room Temperature in Degrees Fahrenheit."  #设备资源描述
        attributes:                             #设备资源的特性，若用device SDK生成时 ，生成的*Attribute.java的这个要改对应的
            { HoldingRegister: "100" }
        properties:               #设备资源属性
                         #设备资源值属性，用来定义此资源值属性，它与  sources 片段中的   get / set  中的property对应   
                        #下面一行说的是：
                        type：数据类型float，其它类型还有Bool,Integer,String,JSON
                        readWrite: 这个属性比较重要，当  sources 片段中没有定义与此同名（即TemperatureDegF）的resource时，会这样处理：‘R’会创建get  ‘W’会set，
                                           source（也叫operation）的object与paramter均为本资源名称（即TemperatureDegF）， 所以简单的情况下sources片段可以省略
                        put时pross前解析size长度为1（当put传时入值长度小于此时会在前面补0）                        返值相关：当类型为float时（其它类型无视），结果*scale(即0.1）  

                        导出外部系统相关：minimum最小值， maximum最大值
                         当put 没有传入parameter指定的内容时，取defaultValue的值
            value:                     
                { type: "Float", readWrite: "R", size: "1", scale: "0.1", minimum: "40.0", maximum: "122.0", defaultValue: "1"}   
            units: #这个不需太关注，是上面返回值的单位描述，只需修改defaultValue的值就可以，其它的不用变
                { type: "String", readWrite: "R", defaultValue: "degrees fahrenheit"}
      -
        name: "TemperatureDegC"
        description: "Room Temperature in Degrees Celsius."
        attributes:
            { HoldingRegister: "101" }
        properties:
            value:
                { type: "Float", size: "1", scale: "0.1", readWrite: "R", minimum: "5.0", maximum: "50.0", defaultValue: "1"}
            units:
                { type: "String", readWrite: "R", defaultValue: "degrees celsius"}
      -
        name: "HumidityPercentRH"
        description: "Room Humidity in %RH."
        attributes:
            { HoldingRegister: "102" }
        properties:
            value:
                { type: "Float", size: "1", scale: "0.1", readWrite: "R", minimum: "0.0", maximum: "95", defaultValue: "1"}
            units:
                { type: "String", readWrite: "R", defaultValue: "%RH"}


#2、source片段 （java代码里也叫operation，设备操作）
此片段可以省略，因为上面的readWrite中的RW隐含会创建下面的get或set，如果在这里定义了，会优先用这里的定义

resources:
      -
        name: "TemperatureDegF"  #这个名称下面的command片段中的path属于最后字串（“TemperatureDegF”）对应，即紫色部分 path: "/api/v1/device/{deviceId}/TemperatureDegF”
        #get方法
          object：对应object片段中的资源
         parameter：这个参数比较重要，是用于result返回的参数定义,如果ValueDescriptors中没有parameter定义的，则返回object.name的对应的ValueDescriptor
         property: "value" 这是固定的写法，不用动它，它是对应object片段properties下的value
        get:  
          - { index: "1", operation: "get", object: "TemperatureDegF", parameter: "TemperatureDegF", property: "value" }
      -
        name: "TemperatureDegC"
        get:
          - { index: "1", operation: "get", object: "TemperatureDegC", parameter: "TemperatureDegC", property: "value" }
      -
        name: "HumidityPercentRH"
        get:
          - { index: "1", operation: "get", object: "HumidityPercentRH", parameter: "HumidityPercentRH", property: "value" }

#3、command片段
commands:
      -
        name: "TemperatureDegF"  #命令名字，同一deviceprofile文件中唯一,并下面的path末端字串（TemperatureDegF）相同
        get:
            path: "/api/v1/device/{deviceId}/TemperatureDegF"  #此行的“TemperatureDegF” 需要与上面的 name 命令名字相同，并与source片段或object片段中能找到相应的
            responses:
              -
                code: "200" # code响应代码，这个暂时没有用到，只是说明一下此命令会有可能有这些响应码
                description: "Get the temperature in degrees F"
                expectedValues: ["TemperatureDegF"] #这个比较重要，定义了它才会写入ValueDescriptors，它对应get/set中的parameter定义，如果ValueDescriptors中没有，就不会返回了。
              -
                code: "503"
                description: "service unavailable"
                expectedValues: []
      -
        name: "TemperatureDegC"
        get:
            path: "/api/v1/device/{deviceId}/TemperatureDegC"
            responses:
              -
                code: "200"
                description: "Get the temperature in degrees C"
                expectedValues: ["TemperatureDegC"]
              -
                code: "503"
                description: "service unavailable"
                expectedValues: []
      -
        name: "HumidityPercentRH"
        get:
            path: "/api/v1/device/{deviceId}/HumidityPercentRH"
            responses:
              -
                code: "200"
                description: "Get the humidity in %RH"
                expectedValues: ["HumidityPercentRH"]
              -
                code: "503"
                description: "service unavailable"
                expectedValues: []

2、现在看一个稍复杂点的GS1-10P5.profile.yaml 文件

# Copyright 2017 Dell Inc. All rights reserved.
name: "GS1-VariableSpeedMotor"
manufacturer: "Automation Direct"
model: "GS1-10P5"
labels: [ 'motor', 'Industrial', 'Motor Controller', 'variable speed']
description: "GS1 AC Drive Motor Controller"
deviceResources:
      -   
        name: OutputFrequency
        description: "PWM Output Frequency for driving motor."
        attributes:
            { HoldingRegister: "8451" }
        properties:
            value:
                { type: "Integer", size: "2", readWrite: "RW", defaultValue: "1"}
            units:
                { type: "String", readWrite: "R", defaultValue: "Hz"}
      -            
        name: RPM
        description: "RPM speed of the motor."
        attributes:
            { HoldingRegister: "8455" }
        properties:
            value:
                { type: "Integer", size: "2", readWrite: "RW", minimum: "0", maximum: "1500", defaultValue: "1"}
            units:
                { type: "String", readWrite: "R", defaultValue: "rpm"}
      -
        name: OutputVoltage
        description: "Output Voltage driving the motor."
        attributes:
            { HoldingRegister: "8454" }
        properties:
            value:
                { type: "Integer", size: "2", readWrite: "RW", scale: "0.1", defaultValue: "1"}
            units:
                { type: "String", readWrite: "R", defaultValue: "Volts"}
      -
        name: Status
        description: "On/Off Status of the motor."
        attributes:
            { HoldingRegister: "2331" }
        properties:
            value:
                { type: "Integer", size: "2", readWrite: "RW", minimum: "0", maximum: "1", defaultValue: "0"}
            units:
                { type: "String", readWrite: "R", defaultValue: "Enabled/Disabled"}

      -         
        name: Direction
        description: "Clockwise/Counterclockwise Direction of the motor."
        attributes:
            { HoldingRegister: "2332" }
        properties:
            value:
                { type: "Integer", size: "2", readWrite: "RW", minimum: "0", maximum: "1", defaultValue: "0"}
            units:
                { type: "String", readWrite: "R", defaultValue: "Clockwise/CounterClockwise"}
      -              
        name: Frequency
        description: "PWM Frequency driving the motor."
        attributes:
            { HoldingRegister: "2330" }
        properties:
            value:
                { type: "Integer", size: "2", readWrite: "RW", scale: "2.875", defaultValue: "0"}
            units:
                { type: "String", readWrite: "R", defaultValue: "Hz"}

resources:
  -
    name: OutputVoltage
    get:
      - { operation: "get", object: "OutputVoltage", parameter: "OutputVoltage", property: "value" }

  -   
    name: Status
    get:
      - { operation: "get", object: "Status", parameter: "Status", property: "value" }

    set:
      - { index: "1", operation: "set", object: "Status", property: "value", parameter: "Status" }
  -
    name: RPM
    get:
      - { operation: "get", object: "RPM", parameter: "RPM", property: "value" }

    set: #下面以列表的方式定义了设置设备两个属性场景，一个是 Status一个是RPM，并返回设置后的此两设备属性，因为parameter: "1"不存在，所以采用object: "Status"
      - { index: "1", operation: "set", object: "Status", property: "value", parameter: "1" }
      - { index: "2", operation: "set", object: "Frequency", property: "value", parameter: "RPM"}
  -
    name: AllValues
    get:  #下面以列表的方式定义了获取设备两个属性场景，一个是 RPM 一个OutputVoltage
      - { index: "1", operation: "get", object: "RPM", parameter: "RPM", property: "value" }
      - { index: "2", operation: "get", object: "OutputVoltage", parameter: "OutputVoltage", property: "value" }
      
  -
    name: MotorControl
    get:
      - { operation: "get", resource: "AllValues" } #此行的 resource: AllValues对应上面的resource片段的 name: AllValues
    set:
      - { operation: "set", resource: "RPM", parameter: "RPM" }
      

               
commands:
  -
  
    name: MotorControl
    get:
        path: "/api/v1/device/{deviceId}/MotorControl"
        responses:
          -
            code: "200"
            description: "Control the motor."
            expectedValues: ["RPM", "OutputVoltage"]
          -
            code: "503"
            description: "service unavailable"
            expectedValues: []

    put:
        path: "/api/v1/device/{deviceId}/MotorControl"
        parameterNames: ["RPM","Status"]      #put时写入ValueDescriptors，get不用写parameterNames
        responses:
          -
            code: "204"
            description: "Control the motor."
            expectedValues: []
          -
            code: "503"
            description: "service unavailable"
            expectedValues: []

3、图片示意