Mappers

概述

Mapper是用来连接并控制设备的应用，它负责的功能如下：

  • 扫描并连接设备。
  • 收集设备观测到的值。
  • 对设备数据进行标准化处理。
  • 推送或拉取设备数据。
  • 设置设备孪生的期望值。
  • 对设备进行健康检查。(todo)

KubeEdge使用Device Controller、Device Twin和Mapper来控制设备。Device Controller位于云端，它使用CRD来定义和控制设备。 Device Twin位于边缘侧，它能够存储来自Mapper的值/状态并在Mapper与Device Controller之间传递消息。 同时，Device Twin中的DMI用于向云端注册Mapper并把Device Model与Device Instance传递给Mapper。

如何创建Mapper

现在用户能够使用 mapper framework 来生成自己的Mapper并控制边缘设备。

1. 设计设备模型与设备实例的CRDs

如果你不清楚如何定义Device Model和Device Instance的配置文件，你可以从page中获取更多细节。

2. 生成Mapper工程

下方的命令能够生成一个基础的Mapper框架。运行命令并输入定义的Mapper名称：

  1. make generate
  2. Please input the mapper name (like 'Bluetooth', 'BLE'): foo

上述命令将生成一个以您的输入命名的项目。文件树如下：

  1. mapper
  2. ├── cmd ------------------------ Main process.
  3. │ └── main.go ------------------ Almost need not change.
  4. ├── config.yaml ---------------- Configuration file including DMI's grpc settting
  5. ├── data ----------------------- Publish data and database implementation layer, almost need not change
  6. │ ├── dbmethod ----------------- Provider implement database interfaces to save data
  7. │ │ ├── influxdb2 -------------- Implementation of Time Series Database(InfluxDB)
  8. │ │ │ └── client.go ------------ InfluxDB client
  9. │ │ ├── redis -------------------Implementation of K/V Database(Redis)
  10. │ │ │ └── client.go ------------ Redis client
  11. │ │ └── tdengine  ---------------Implementation of Time Series Database(TDengine)
  12. │ │   └── client.go ------------ TDengine client
  13. │ └── publish ------------------ Publisher implement push interfaces to push data,will add more protocols in the future
  14. │     ├── http ----------------- HTTP client will push data to server
  15. │     │ └── client.go  --------- WIP
  16. │     └── mqtt ----------------- MQTT client will push data to broker
  17. │         └── client.go  ------- WIP
  18. ├── device --------------------- Implementation device layer, almost need not change
  19. │ ├── device.go ---------------- Device control, almost need not change
  20. │ └── devicetwin.go ------------ Push twin data to EdgeCore, almost need not change
  21. ├── Dockerfile
  22. ├── driver --------------------- Device driver layer, complete TODO item in this 
  23. │ ├── devicetype.go ------------ Refine the struct as your CRD
  24. │ └── driver.go ---------------- Fill in the functions like getting data/setting register.
  25. ├── hack
  26. │ └── make-rules
  27. │     └── mapper.sh
  28. └── Makefile

大多数情况下，需要在Driver文件夹中填写如下代码：

  • 在devicetype.go文件中，需要按照设备实例yaml文件中定义的方式填写ProtocolConfig和VisitorConfig结构体信息，以便Mapper能够正确解析配置信息。
  • 在driver.go文件中，需要自定义初始化设备和获取设备数据的方法，并对Mapper收集的数据进行标准化。
  • 在config.yaml中，需要定义Mapper的协议名称。

3. 部署Mapper

生成Mapper项目并填充Driver文件夹后，用户可以根据Dockerfile文件制作自己的Mapper镜像，随后通过Deployment等方式将Mapper部署在集群中。

  1. docker build -t [YOUR MAPPER IMAGE NAME] .

一个Mapper Deployment配置文件的例子如下：

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: mapper-test
  5.   namespace: default
  6. spec:
  7.   replicas: 1
  8.   selector:
  9.     matchLabels:
  10.       app: demo
  11.   template:
  12.     metadata:
  13.       labels:
  14.         app: demo
  15.     spec:
  16.       nodeName: edge-node  # Replace with your edge node name
  17.       containers:
  18.         - name: demo
  19.           volumeMounts:  #Required, mapper need to communicate with grpcclient
  20.             - mountPath: /etc/kubeedge
  21.               name: test-volume  
  22.           env:  #Not Required, this field is used to mount the user database key
  23.             - name: TOKEN   
  24.               valueFrom:
  25.                 secretKeyRef:
  26.                   name: demo-secret
  27.                   key: token
  28.           image: docker.io/library/mapper-demo:v1.0.1 # Replace with your mapper image name
  29.           imagePullPolicy: IfNotPresent
  30.           resources:
  31.             limits:
  32.               cpu: 300m
  33.               memory: 500Mi
  34.             requests:
  35.               cpu: 100m
  36.               memory: 100Mi
  37.           command: [ "/bin/sh","-c" ]
  38.           args: [ "/kubeedge/main --config-file /kubeedge/config.yaml --v 4" ]
  39.       volumes:
  40.         - name: test-volume
  41.           hostPath:
  42.             path: /etc/kubeedge
  43.             type: Directory

你可以使用Kubernetes原生方式部署Mapper：

  1. kubectl apply -f <path to mapper yaml>

如果你想先在本地调试，也可以直接编译运行Mapper代码：

  1. go run cmd/main.go --v <log level,like 3> --config-file <path to config yaml>

Examples

我们当前提供虚拟设备virtualdevice mapper、modbus协议mapper以及USB协议mapper作为Mapper Framework的例子：

我们之后将提供更多内置的Mapper工程，如bluetooth和onvif。