Mapper-Framework

Mapper-Framework 提供全新Mapper开发框架，集成DMI管理面与数据面能力，允许设备在边缘或云端处理数据，提高设备数据管理的灵活性。 Mapper-Framework可以自动生成用户的Mapper项目，简化Mapper用户设计和实现的复杂度，提高Mapper开发效率。

架构

mapper framework

Mapper-Framework提供数据推送接口用于把设备数据推送到用户应用程序，目的地规则通过CRD定义。
Mapper-Framework提供数据库接口，可以将数据保存到数据库中，通过CRD定义推送规则。
Mapper-Framework提供了REST API，这些API可以访问设备来获取数据。API不支持更改设备属性，因为这会导致云端和边缘之间的消息不一致。
Mapper-Framework提供设备驱动接口来初始化设备、获取设备数据。
Mapper-Framework提供Makefile，可以通过一个命令生成一个Mapper。

DMI设备管理面和设备数据面可以通过Mapper-Framework实现，开发者只需要关注设备驱动即可。Mapper-Framework中灰色部分（Driver）表示需要开发者实现。我们定义了接口DevPanel来管理设备，当添加功能时会添加新的接口。

实现细节

数据流

dmi datapanel

数据标准化

为了在接口模块之间传输数据，需要数据标准化。这些数据应包含数据生成的必要信息。

标准化数据定义是DataModel。

数据推送

数据推送模块可以根据CRD中定义的目的地规则把设备数据至可达的用户消费应用，为了满足新的要求，当前v1beta1 CRD在Device Instance的定义中添加新字段 PushMethod。

定义Mapper将数据推送到用户应用程序的配置文件示例如下：

apiVersion: devices.kubeedge.io/v1beta1
kind: Device
metadata:
  name: beta1-device
spec:
  deviceModelRef:
    name: beta1-model
  nodeName: worker-node1
  properties:
    - name: temp
      pushMethod:
        mqtt:
          address: tcp://127.0.0.1:1883
          topic: temp
          qos: 0
          retained: false
      ...

目前的CRD定义中支持MQTT和HTTP协议，上报周期由DeviceProperty.ReportCycle定义（默认1秒上报一次）。当Mapper执行时，会自动解析pushMethod字段的值并执行DataPanel接口来推送数据。未来DataPanel将会增加更多接口，保证数据安全。

数据库

数据库模块可以根据DBMethod定义的目标规则将设备数据存储到数据库。定义Mapper将数据推送到用户数据库的配置文件示例如下：

apiVersion: devices.kubeedge.io/v1beta1
kind: Device
metadata:
  name: beta1-device
spec:
  deviceModelRef:
    name: beta1-model
  nodeName: worker-node1
  properties:
    - name: temp
      pushMethod:
        dbMethod:
          influxdb2:
            influxdb2ClientConfig:
              url: http://127.0.0.1:8086
              org: test-org
              bucket: test-bucket
            influxdb2DataConfig:
              measurement: stat
              tag:
                unit: temperature
              fieldKey: beta1test
      ...

现在我们提供了Influx2、Redis、TDengine数据库接口，后续我们会添加更多的数据库。

拉取数据

我们创建HTTP服务用以提供API拉取功能，支持直接从设备拉取设备数据。下面列出的 URL 以本地 IP 的形式给出。你可以从Mapper可访问的任何网络使用这些服务。

默认情况下启用端口“7777”。你可以在Mapper的config文件中自行设置端口号。

deviceInstance-ID 根据你自己的 CRD 定义。

propertyName 根据你自己的 CRD 定义。

Ping

检测RESTful服务是否正常启动
Method: GET
Url: https://127.0.0.1:7777/api/v1/ping
Response:

{
 "apiVersion": "v1",
 "statusCode": 200,
 "timeStamp": "2023-08-18T09:57:29+08:00",
 "Message": "This is v1 API, the server is running normally."
 }

设备数据处理

获取设备数据
Method=GET
Url: https://127.0.0.1:7777/api/v1/device/{deviceInstance-ID}/{propertyName}
Response:

{
 "apiVersion": "v1",
 "statusCode": 200,
 "timeStamp": "2023-08-18T09:57:35+08:00",
 "Data": {
     "DeviceName": "deviceInstance-ID",
     "PropertyName": "propertyName",
     "Value": "data",
     "Type": "dataType",
     "CollectTimeStamp": 1692323855044
     }
 }

设备元数据

获取设备模型
Method=GET
Url: https://127.0.0.1:7777/api/v1/meta/model/{deviceInstance-ID}
Response:

{
 "apiVersion": "v1",
 "statusCode": 200,
 "timeStamp": "2023-08-18T09:57:37+08:00",
 "name": "model-name",
 "properties": [
     {
         "name": "propertyName-1",
         "dataType": "property data type",
         "description": "property description",
         "accessMode": "ReadWrite",
         "defaultValue": 100
     },
     ...
     ]
 }

设备写入

在1.19版本中实现了Mapper支持设备写入的特性，增强了原有Mapper API能力。用户能够通过API获取某个设备所有可供外部调用的设备方法，通过返回的调用命令向设备发起写入请求。下面列出的 URL 以本地 IP 的形式给出。你可以从Mapper可访问的任何网络使用这些服务。

默认情况下启用端口“7777”。你可以在Mapper的config文件中自行制定端口号

deviceInstance-ID 根据你自己的 CRD 定义。

propertyName 根据你自己的 CRD 定义。

获取设备的所有设备方法
Url: https://127.0.0.1:7777/api/v1/devicemethod/{deviceInstance-ID}
Response:

{
 "Data": {
     "Methods": [
         {
             "Name": "setValue",
             "Path": "/api/v1/devicemethod/default/random-instance-01/setValue/{propertyName}/{data}",
             "Parameters": [
                 {
                     "PropertyName": "random-int",
                     "ValueType": "int"
                 }
             ]
         }
     ]
 }
 }

获取设备方法的调用命令后，用户可以创建设备写入请求：

创建设备写入请求
Url: https://127.0.0.1:7777/api/v1/devicemethod/{deviceInstance-ID}/{deviceMethodName}/{propertyName}/{data}
Response:
```
 {
 "statusCode": 200,
 "Message": "Write data ** to device ** successfully."
 }
```