Device Manager

KubeEdge supports device management with the help of Kubernetes CRDs and a Device Mapper (explained below) corresponding to the device being used. We currently manage devices from the cloud and synchronize the device updates between edge nodes and cloud, with the help of device controller and device twin modules.

Notice

Device Management features are updated from v1alpha1 to v1alpha2 in release v1.4. It is not compatible for v1alpha1 and v1alpha2. Details can be found device-management-enhance

Device Model

A device model describes the device properties such as ‘temperature’ or ‘pressure’. A device model is like a reusable template using which many devices can be created and managed.

Details on device model definition can be found here.

Device Model Sample

A sample device model like below,

  1. apiVersion: devices.kubeedge.io/v1alpha2
  2. kind: DeviceModel
  3. metadata:
  4.  name: sensor-tag-model
  5.  namespace: default
  6. spec:
  7.  properties:
  8.   - name: temperature
  9.     description: temperature in degree celsius
  10.     type:
  11.      int:
  12.       accessMode: ReadWrite
  13.       maximum: 100
  14.       unit: degree celsius
  15.   - name: temperature-enable
  16.     description: enable data collection of temperature sensor
  17.     type:
  18.       string:
  19.         accessMode: ReadWrite
  20.         defaultValue: 'OFF'

Device Instance

A device instance represents an actual device object. It is like an instantiation of the device model and references properties defined in the model which exposed by property visitors to access. The device spec is static while the device status contains dynamically changing data like the desired state of a device property and the state reported by the device.

Details on device instance definition can be found here.

Device Instance Sample

A sample device instance like below,

  1. apiVersion: devices.kubeedge.io/v1alpha2
  2. kind: Device
  3. metadata:
  4.   name: sensor-tag-instance-01
  5.   labels:
  6.     description: TISimplelinkSensorTag
  7.     manufacturer: TexasInstruments
  8.     model: CC2650
  9. spec:
  10.   deviceModelRef:
  11.     name: sensor-tag-model
  12.   protocol:
  13.     modbus:
  14.       slaveID: 1
  15.     common:
  16.       com:
  17.         serialPort: '1'
  18.         baudRate: 115200
  19.         dataBits: 8
  20.         parity: even
  21.         stopBits: 1
  22.   nodeSelector:
  23.     nodeSelectorTerms:
  24.     - matchExpressions:
  25.       - key: ''
  26.         operator: In
  27.         values:
  28.         - node1
  29.   propertyVisitors:
  30.     - propertyName: temperature
  31.       modbus:
  32.         register: CoilRegister
  33.         offset: 2
  34.         limit: 1
  35.         scale: 1
  36.         isSwap: true
  37.         isRegisterSwap: true
  38.     - propertyName: temperature-enable
  39.       modbus:
  40.         register: DiscreteInputRegister
  41.         offset: 3
  42.         limit: 1
  43.         scale: 1.0
  44.         isSwap: true
  45.         isRegisterSwap: true
  46. status:
  47.   twins:
  48.     - propertyName: temperature
  49.       reported:
  50.         metadata:
  51.           timestamp: '1550049403598'
  52.           type: int
  53.         value: '10'
  54.       desired:
  55.         metadata:
  56.           timestamp: '1550049403598'
  57.           type: int
  58.         value: '15'

Customized Protocols and Customized Settings

From KubeEdge v1.4, we can support customized protocols and customized settings, samples like below

  • customized protocols
  1.   propertyVisitors:
  2.     - propertyName: temperature
  3.       collectCycle: 500000000
  4.       reportCycle: 1000000000
  5.       customizedProtocol:
  6.         protocolName: MY-TEST-PROTOCOL
  7.         configData:
  8.           def1: def1-val
  9.           def2: def2-val
  10.           def3:
  11.             innerDef1: idef-val
  • customized values
  1.   protocol:
  2.     common:
  3.       ...
  4.       customizedValues:
  5.         def1: def1-val
  6.         def2: def2-val

Data Topic

From KubeEdge v1.4, we add data section defined in device spec. Data section describe a list of time-series properties which will be reported by mappers to edge MQTT broker and should be processed in edge.

  1. apiVersion: devices.kubeedge.io/v1alpha1
  2. kind: Device
  3. metadata:
  4.     ...
  5. spec:
  6.   deviceModelRef:
  7.     ...
  8.   protocol:
  9.     ...
  10.   nodeSelector:
  11.     ...
  12.   propertyVisitors:
  13.     ...
  14.   data:
  15.     dataTopic: "$ke/events/device/+/data/update"
  16.     dataProperties:
  17.       - propertyName: pressure
  18.         metadata:
  19.           type: int
  20.       - propertyName: temperature
  21.         metadata:
  22.           type: int

Device Mapper

Mapper is an application that is used to connect and control devices. Following are the responsibilities of mapper: 1) Scan and connect to the device. 2) Report the actual state of twin-attributes of device. 3) Map the expected state of device-twin to actual state of device-twin. 4) Collect telemetry data from device. 5) Convert readings from device to format accepted by KubeEdge. 6) Schedule actions on the device. 7) Check health of the device.

Mapper can be specific to a protocol where standards are defined i.e Bluetooth, Zigbee, etc or specific to a device if it a custom protocol.

Mapper design details can be found here

An example of a mapper application created to support bluetooth protocol can be found here

Usage of Device CRD

The following are the steps to

  1. Create a device model in the cloud node.

    1.         kubectl apply -f <path to device model yaml>

  2. Create a device instance in the cloud node.

    1.        kubectl apply -f <path to device instance yaml>

    Note: Creation of device instance will also lead to the creation of a config map which will contain information about the devices which are required by the mapper applications The name of the config map will be as follows: device-profile-config-< edge node name >. The updates of the config map is handled internally by the device controller.

  3. Run the mapper application corresponding to your protocol.

  4. Edit the status section of the device instance yaml created in step 2 and apply the yaml to change the state of device twin. This change will be reflected at the edge, through the device controller and device twin modules. Based on the updated value of device twin at the edge the mapper will be able to perform its operation on the device.

  5. The reported values of the device twin are updated by the mapper application at the edge and this data is synced back to the cloud by the device controller. User can view the update at the cloud by checking his device instance object.

  1.     Note: Sample device model and device instance for a few protocols can be found at $GOPATH/src/github.com/kubeedge/kubeedge/build/crd-samples/devices

Last updated on Jan 11, 2021