一、EdgeX Ready 计划

EdgeX Ready 计划旨在让供应商展示使用 EdgeX 的能力，该名称可帮助其他社区参与者和解决方案供应商识别已通过自我评估流程的供应商，以证明他们能够使用 EdgeX 将其产品之一与解决方案集成。加入该计划的供应商会在 EdgeX Foundry 网站上突出显示，其徽标旁边带有 EdgeX Ready 徽章。

edgex-ready.png

[图片上传失败...(image-b2508a-1639623365593)]

意义与用途

• EdgeX Ready成员向社区成员展示和分享EdgeX知识
• EdgeX Ready成员通过社区被全球EdgeX用户了解
• 提升社区EdgeX微服务的数量和质量
• 促进社区成员之间的商业合作
• 外部商业机会，优先推荐到适合的EdgeX Ready成员

二、加入EdgeX Ready计划需要什么条件

• 熟悉EdgeX使用，有能力展示和分享EdgeX知识
• 申请成为EdgeX会员或加入到EdgeX用户生态计划。
• 使用官网已有的或自行开发的EdgeX设备微服务完成EdgeX Ready 自我评估过程。

三、准备工作

1.加入EdgeX User Ecosystem

如果不是EdgeX会员或者未注册为EdgeX用户，您需要进入EdgeX User Ecosystem网站注册成为EdgeX用户，注册成为用户是免费的。

点击此处EdgeX User Ecosystem，完成注册内容填写。

User Ecosystem.png

2.准备EdgeX-Foundry的运行环境

你可以选择在X86电脑或者树莓派上运行EdgeX-Foundry 2.0或以上版本。

推荐直接使用docker-compose方式运行。

1）预装docker及docker-compose

• 点击此处跳转到Docker安装说明
• 点击此处跳转到Docker Compose安装说明

2）安装运行EdgeX Ireland版本 (v 2.0)

docker-compose文件最新支持到EdgeX-Ireland (v 2.0)

# 下载运行x86版本的Edgex-Foundry
curl https://raw.githubusercontent.com/edgexfoundry/edgex-compose/ireland/docker-compose-no-secty.yml -o docker-compose.yml
sudo docker-compose up -d

# 下载运行ARM64版本的Edgex-Foundry
curl https://raw.githubusercontent.com/edgexfoundry/edgex-compose/ireland/docker-compose-no-secty-arm64.yml -o docker-compose.yml
sudo docker-compose up -d

验证安装

docker-compose ps 

image

注意：如果需要edgex容器可以被外部设备访问，需要把docker-compose.yml中的"127.0.0.1:"去掉，然后重新启动。

3.准备EdgeX设备微服务的开发环境

1）安装Go环境

• 推荐安装 Go 1.16 及其更新，较旧版本的 Go（尤其是 1.10 或更早版本），可能会导致问题。

  # 安装 C 工具
  $ sudo apt-get install bison ed gawk gcc libc6-dev make
  
  $ cd ~
  # 下载go二进制文件并安装
  $ wget https://golang.org/dl/go1.16.7.linux-arm64.tar.gz      #  下载arm64版本
  # wget https://golang.org/dl/go1.16.7.linux-amd64.tar.gz   #  下载 x86版本
  $ sudo tar -zxvf go1.16.7.linux-arm64.tar.gz -C  /usr/local
  $ sudo ln -s  /usr/local/go/bin/* /usr/bin/
  
  # 修改PATH 环境变量，分别修改普通用户和root的配置
  $ sudo vim $HOME/.profile 
    export PATH=$PATH:/usr/local/go/bin
  $ source  $HOME/.profile 
  
  # 测试go
  $ go version
  go version go1.16.7 linux/arm64
  

2）安装build-essential

• 一般ubuntu系统自带

3）安装ZeroMQ

• 方法1：点击此处下载安装脚本setup-zeromq.sh，实测适用于X86 Ubuntu 16.04及18.04。

  # 运行脚本安装ZeroMQ
  $ bash setup-zeromq.sh
  

• 方法2：通过命令行安装，实测适用于raspberry pi 4b ubuntu 20.10

  $ sudo apt-get update && \
  $ sudo apt-get install -y libtool pkg-config build-essential autoconf automake uuid-dev
  $ sudo apt-get install -y libzmq3-dev
  
  $ ldconfig -p | grep zmq
    libzmq.so.5 (libc6,AArch64) => /lib/aarch64-linux-gnu/libzmq.so.5
    libzmq.so (libc6,AArch64) => /lib/aarch64-linux-gnu/libzmq.so
  

4.准备一个EdgeX设备微服务

要求准备一个可以在EdgeX Ireland 版本 (V2.0) 下运行的一个设备微服务。这里可以使用现有设备服务或自定义的设备微服务。重要的部分是您必须能够证明您可以使用 EdgeX 的设备配置文件获取设备/传感器的输入数据。

一个设备微服务的一些重要文件说明：

• 设备配置文件（device profile）：描述设备的基础信息（设备名、厂商信息、标签和设备用途等），以及可以通过核心服务core-command能对设备资源（device resource）进行哪些类型的命令或操作。
  • 存放路径：<device-service>/cmd/res/profiles/xxx.yaml
• 微服务配置文件（Configuration file）：对微服务自身的配置，关联EdgeX核心微服务、设备配置文件和预定义设备文件。
  • 存放路径：<device-service>/cmd/res/configuration.toml
• 预定义设备文件（Pre-defined devices）：在EdgeX微服务实例运行时，由设备配置文件（device profile）生成的设备实例。
  • 存放路径：<device-service>/cmd/res/devices/xxx.toml
• 设备驱动文件（driver.go）：对真实设备或传感器的驱动控制接口的实现
  • 存放路径：<device-service>/internel/dirver/driver.go

本次以江行智能开发的一个EdgeX设备微服务（device-gpio）为例进行讲解。

mkdir -p ~/go/src/github.com/edgexfoundry/
cd ~/go/src/github.com/edgexfoundry/
git clone https://github.com/edgexfoundry/device-gpio.git

1）device-gpio说明

该设备服务可以使用 sysfs ABI（默认）或 chardev ABI（实验）来控制系统的GPIO资源，如对一个gpio资源进行打开、关闭、设置输入、设置输出、设置状态，读状态。

在设备配置文件中，可以定义需要使用的gpio资源，就可以通过过core-command对该gpio设备进行读（设置为gpio输入，并获取状态）或写（设置为gpio为输出，并置为高电平或低电平）。

device-gpio的设备配置文件如下：

name: "Custom-GPIO-Device"
manufacturer: "Jiangxing Intelligence"
model: "SP-01"
labels:
  - "device-custom-gpio"
description: "Example of custom gpio device"

deviceResources:
  -
    name: "Power"
    isHidden: false
    description: "mocking power button"
    attributes: { line: 17 }
    properties:
      valueType: "Bool"
      readWrite: "RW"

  -
    name: "LED"
    isHidden: false
    description: "mocking LED"
    attributes: { line: 27 }
    properties:
      valueType: "Bool"
      readWrite: "W"

  -
    name: "Switch"
    isHidden: false
    description: "mocking switch"
    attributes: { line: 22 }
    properties:
      valueType: "Bool"
      readWrite: "R"

• 是示例设备配置文件中配置了三个GPIO设备，分别是Power(gpio17)、LED(gpio27)和Switch(gpio27)，它们分别用于电源使能或检测（读写），LED控制（写），Switch开关状态检测（读）。

2）edgex-gpio工程目录

edgex-gpio目录.png

四、完成自我评估过程

1.什么是EdgeX Ready的自我评估过程

“自我评估过程”的初始阶段是简单地验证设备配置文件。用户证明他们已经编写了设备配置文件，并通过他们自己设置的 EdgeX 实例获取到设备数据，从而证明了对 EdgeX 设备服务及其相关设备配置文件有一定的了解。

要求供应商执行以下操作：

1. 使用其设备配置文件实例化 EdgeX 参考实现的实例
2. 使用由其设备配置文件描述的设备，生成示例数据，并将其发送到适当的设备服务
3. 确认数据到达Core Data
4. 使用认证工作组提供的工具之一验证他们的设备配置文件【暂不支持edgex2.0】
5. 将他们经过验证的设备配置文件和样本数据提交给 EdgeX Ready 计划

工作流程图如下：

[图片上传失败...(image-db0ab7-1639623365593)]

需要提交的材料如下：

• 设备配置文件 (Device Profile) – YAML (.yaml)
• 示例传感器数据 (Sample sensor data) – JSON (.json)
• 示例数据描述文件 (sample data schema) – text (.txt)
• EdgeX Ready参与表 (EdgeX Ready Participation Form) – PDF (.pdf)
• 提交在线申请表到EdgeX Foundry 认证组

2.编写（或使用现有的）设备配置文件

根据上述已准备好的EdgeX设备微服务，明确其所使用的设备配置文件，如device-gpio的device.custom.gpio.yaml。

设备配置文件包含以下几个方面

• 设备名、厂商信息、标签和设备描述等基础信息
• deviceResources：定义一个设备中某种传感器的特征或数据，可以对其进行读或写操作。
• deviceCommands[可选]：定义对多个deviceResources进行同步读或写操作。

EdgeX通过核心服务core-command能对deviceCommands或deviceResources发送某种类型的命令或操作。

3.验证设备配置文件（跳过）

社区提供 IOTech DCT 工具验证或生成设备配置文件，但是edgex 2.0 版本的配置文件暂时无法验证。

未来，EdgeX 社区希望有其他工具来帮助用户创建和验证配置文件。

4.运行EdgeX微服务实例

根据已准备的运行环境，将设备/传感器与主控连接好。device-gpio微服务示例在树莓派4B设备上运行。

$ cd ~/go/src/github.com/edgexfoundry/device-gpio

# 下载golang工程相关依赖库
$ make tidy

# 编译微服务
$ make build

# 关闭安全模式
$ export EDGEX_SECURITY_SECRET_STORE=false

# 由于edgex服务组件使用容器以bridge网络启动，因此需要修改SERVICE_HOST为docker0 ip，否则会绑定127.0.0.1
$ export SERVICE_HOST="172.17.0.1"

# 运行微服务
$ cd cmd/ && ./device-gpio
level=INFO ts=2021-12-03T07:06:57.117923363Z app=device-gpio source=config.go:359 msg="Loaded service configuration from ./res/configuration.toml"
level=INFO ts=2021-12-03T07:06:57.119353737Z app=device-gpio source=variables.go:352 msg="Variables override of 'Service.Host' by environment variable: SERVICE_HOST=172.17.0.1"
level=INFO ts=2021-12-03T07:06:57.119736344Z app=device-gpio source=config.go:494 msg="Using local configuration from file (1 envVars overrides applied)"
level=INFO ts=2021-12-03T07:06:57.119857843Z app=device-gpio source=httpserver.go:114 msg="Web server starting (172.17.0.1:59910)"
......
level=INFO ts=2021-12-03T07:06:57.143892878Z app=device-gpio source=autodiscovery.go:42 msg="AutoDiscovery stopped: ProtocolDiscovery not implemented"
level=INFO ts=2021-12-03T07:06:57.14392886Z app=device-gpio source=message.go:50 msg="Service dependencies resolved..."
level=INFO ts=2021-12-03T07:06:57.143967655Z app=device-gpio source=message.go:51 msg="Starting device-gpio 0.0.0 "
level=INFO ts=2021-12-03T07:06:57.144004062Z app=device-gpio source=message.go:55 msg="device gpio started"
level=INFO ts=2021-12-03T07:06:57.144038729Z app=device-gpio source=message.go:58 msg="Service started in: 27.569833ms"

5.从EdgeX实例中获取传感器数据

根据设备配置文件定义的deviceResources和deviceCommands，通过RESTful API向EdgeX微服务发送命令以获取传感器的数据。

提供 JSON 格式的传感器/设备发送的数据集样本，此示例可帮助社区成员了解您的设备如何运行以及它如何与 EdgeX 交互。

有两种方式捕获方式：

• 捕获设备微服务发送到coredata的数据
• 通过在coredata中执行查询命令：http://<host>:59880/api/v2/event/device/name/<devicename>，并从查询命令响应中捕获 JSON 响应。

以device-gpio为例，通过设备配置文件定义的deviceResources，获取其传感器的状态。

1）示例1

假设树莓派4B的gpio22已经连接到一个开关设备，通过读取deviceResource - Switch的值，来取得开关设备的状态（开启或闭合）。

$ curl http://localhost:59882/api/v2/device/name/GPIO-Device01/Switch

返回数据：Sample sensor data of Switch for GPIO-Device01

{
    "apiVersion": "v2",
    "statusCode": 200,
    "event": {
        "apiVersion": "v2",
        "id": "49daef08-7c02-4bd4-a338-c48dc5bd1576",
        "deviceName": "GPIO-Device01",
        "profileName": "Custom-GPIO-Device",
        "sourceName": "Switch",
        "origin": 1633959349650360339,
        "readings": [
            {
                "id": "798a5d7c-1b21-4069-a18c-4e9c09e62a3c",
                "origin": 1633959349650360339,
                "deviceName": "GPIO-Device01",
                "resourceName": "Switch",
                "profileName": "Custom-GPIO-Device",
                "valueType": "Bool",
                "binaryValue": null,
                "mediaType": "",
                "value": "false"
            }
        ]
    }
}

将数据保存为：Sample data of switch gpio state for device-gpio.json

2）示例2

假设树莓派4B的gpio17已经连接到一个电源控制器，通过读取deviceResource - Power的值，来取得电源控制器的状态（开启或闭合）。

$ curl http://localhost:59882/api/v2/device/name/GPIO-Device01/Power

返回数据：Sample sensor data of Power for GPIO-Device01

{
    "apiVersion": "v2",
    "statusCode": 200,
    "event": {
        "apiVersion": "v2",
        "id": "190b2d12-9ba1-4d04-b810-2d8140bea506",
        "deviceName": "GPIO-Device01",
        "profileName": "Custom-GPIO-Device",
        "sourceName": "Power",
        "origin": 1633958325057867303,
        "readings": [
            {
                "id": "cc9c4140-cc2d-4d3b-95b4-7f5ca8943c20",
                "origin": 1633958325057867303,
                "deviceName": "GPIO-Device01",
                "resourceName": "Power",
                "profileName": "Custom-GPIO-Device",
                "valueType": "Bool",
                "binaryValue": null,
                "mediaType": "",
                "value": "false"
            }
        ]
    }
}

将数据保存为：Sample data of power gpio state for device-gpio.json

6.编写示例数据描述文件

需要在简单的文本文档中，对上一步拿到的示例数据中的每个 JSON 元素进行描述，以便了解数据的含义。 示例如下：

Sample data schema of power gpio state for device-gpio.txt

"id": "cc9c4140-cc2d-4d3b-95b4-7f5ca8943c20"- EdgeX reading id
"origin": 1633958325057867303 - The unix timestamp of when the data was created by the "Power"  gpio pin of gpio-device  (in nanoseconds)
"deviceName": "GPIO-Device01" - The device name that originated the data - assigned when the device gets provisioned
"resourceName": "Power" - The device resource name associated to the reading
"profileName": "Custom-GPIO-Device"  - The device profile for the  "GPIO-Device01" device
"valueType": "Bool" - The type of the value - Bool
"binaryValue": null,
"mediaType": "",
"value": "false" - The "Power" gpio pin status of the device is low

Sample data schema of switch gpio state for device-gpio.txt

"id": "798a5d7c-1b21-4069-a18c-4e9c09e62a3c" - EdgeX reading id
"origin": 1633959349650360339 - The unix timestamp of when the data was created by the "Switch"  gpio pin of gpio-device  (in nanoseconds)
"deviceName": "GPIO-Device01" - The device name that originated the data - assigned when the device gets provisioned
"resourceName": "Switch" - The device resource name associated to the reading
"profileName": "Custom-GPIO-Device", - The device profile for the  "GPIO-Device01" device
"valueType": "Bool" - the type of the value - Bool
"binaryValue": null,
"mediaType": "",
"value": "true"  The "Switch" gpio pin status of the device is high

7.下载并填写EdgeX Ready参与表

点击此处下载 EdgeX Ready Participation Form.pdf，完成表格内容填写并签名。

EdgeX Ready Participation Form.png

8.通过在线申请表提交资料

点击此处跳转到在线在线申请表，完成内容填写，并将上述得到文件添加到在线申请表中，最后完成提交。

on-line form.png

根据device-gpio示例微服务，需添加的文件列表如下：

• EdgeX Ready Participation Form.pdf
• device.custom.gpio.yaml
• Sample data of power gpio state for device-gpio.json
• Sample data of switch gpio state for device-gpio.json
• Sample data schema of power gpio state for device-gpio.txt
• Sample data schema of switch gpio state for device-gpio.txt

提交的所有材料都被视为对 Apache 许可证 2.0 版下的 EdgeX Foundry 项目的贡献。

认证小组将审核您提交的结果并将结果通过电子邮件发送给您。

五、实操经验分享

1.GPIO微服务设备配置文件构思

• 设备本身具备能被进行哪些操作？

  • 可以设置gpio的导出、关闭
  • 可以设置gpio的读写模式：输入或输出
  • 可以设置gpio的状态或者读取gpio的状态

• 系统对gpio的操作方式有哪些？

  • sysfs：通过 sysfs 中的 /sys/class/gpio 接口去访问 GPIO
  • chardev：Linux 4.8开始，引入chardev方式控制gpio
  • 通过configuration.toml配置文件来选择sysfs或chardev接口方式

• edgex如何操作关联gpio的设备

  • 将一个gpio设备抽象为一个device-resource，通过attributes参数来指定系统具体的gpio。
  • 通过readWrite权限定义gpio设备的读写模式：是否可输出或输入。
  • edgex对device-resource的发送的restful命令会自带attributes参数（所使用的gpio编号）。
  • 对device-resource进行读，会将gpio设备设置为输入，并读取当前状态。
  • 对device-resource进行写，会将gpio设备设置为输出，并设置gpio设备状态为高电平或低电平。

2.edgex 2.0常用操作

1）查看EdgeX服务的状态

• 访问consul http://localhost:8500/

2）本地读取设备微服务信息

核心服务API

• Edgex Foundry - Core Command API 2.0.0：59882端口

• Edgex Foundry - Core Metadata API 2.0.0：59881端口

• Edgex Foundry - Core Data API 2.0.0：59880端口

常用操作

# 查询本地所有edgex设备
curl http://localhost:59882/api/v2/device/all

# 查询本地edgex设备信息
curl http://localhost:59882/api/v2/device/name/<device-name>

# 对微服务发送HTTP GET命令 
    # curl -X GET http://localhost:59882/api/v2/device/name/<device-name>/<device-resource>
curl -X GET http://localhost:59882/api/v2/device/name/Random-Integer-Device/Int16

# 对微服务发送HTTP PUT命令 
    # curl -X PUT -d <body>  http://localhost:59882/api/v2/device/name/<device-name>/<device-resource>
curl -X PUT -d '{"Int16":"42", "EnableRandomization_Int16":"false"}' http://localhost:59882/api/v2/device/name/Random-Integer-Device/WriteInt16Value

# 删除edgex设备
curl -X DELETE http://localhost:59881/api/v2/device/name/Random-Integer-Device

# 删除edgex设备配置文件
curl -X DELETE http://localhost:59881/api/v2/deviceprofile/name/Random-Integer-Device