基于RTIO远程控制LED

1. 说明

生产环境中，RTIO服务通常部署于云端服务器。

本文分享在开发环境中如何使用一台Windows PC（WSL2）作为服务器，并对所连接的设备进行控制。模型如下图，因篇幅限制，本文仅通过curl命令模拟手机端HTTP调用。后续文章会演示完整的手机端控制设备。

+----------+          +--------------------+
|          |          |     WINDOWS11      |
| ESP32-C6 | -------> |                    |
|          |          |                    |
+----------+          | +----------------+ |
                      | |      WSL2      | |
+----------+          | |                | |
|          |          | | RTIO-Container | |
| Phone    | -------> | |                | |
|          |          | +----------------+ |
+----------+          +--------------------+

如开发环境如果是Linux（比如Ubuntu PC），可跳过WSL相关设置。

2. 硬件及环境设置

ESP32-C6-DevKitC-1 开发板（官方手册）。
Windows，并安装WSL2。

WSL实验客户机关键信息如下：

$ hostnamectl
# ...
  Virtualization: wsl
Operating System: Ubuntu 22.04.3 LTS                      
          Kernel: Linux 5.15.167.4-microsoft-standard-WSL2
    Architecture: x86-64

该WSL Linux（下文简称WSL）主要用于，

ESP32-C6端的Demo源码编译。
部署RTIO服务端（运行RTIO Docker）。
通过curl发出HTTP请求，模拟手机端控制设备。

需要以下设置，

安装docker软件。建议Windows主机安装“Docker Desktop”，同时使能“WSL Docker”功能。可参考Get started with Docker remote containers on WSL 2。
安装ESP32 SDK，可参考Standard Toolchain Setup for Linux and macOS。

3. 实验步骤

3.1. 服务端部署

拉取RTIO Docker, 运行RTIO服务并使能TLS设备接入。

$ sudo docker pull registry.cn-guangzhou.aliyuncs.com/rtio/rtio:v0.8.0
# ...
Digest: sha256:...
$ sudo docker run -it --entrypoint ./rtio \
--rm  -p 17017:17017 -p 17917:17917 registry.cn-guangzhou.aliyuncs.com/rtio/rtio:v0.8.0  \
-disable.deviceverify -disable.hubconfiger \
-enable.hub.tls \
-hub.tls.certfile ./certificates/demo_server.crt \
-hub.tls.keyfile ./certificates/demo_server.key \
-log.level info
2024-12-26 09:13:41.998 INF rtio starting ...

使用WSL对外进行服务，需要一些额外设置，比如设定防火墙、端口映射到WSL，参考 4.1. WSL网络配置。

3.2. 设备端编译

第一步，下载rtio-device-sdk-c源码，并切换到demos-esp32/rtio/remote_switch目录。

git clone https://github.com/mkrainbow/rtio-device-sdk-c.git
cd rtio-device-sdk-c/demos-esp32/rtio/remote_switch

第二步，选定目标平台。

$ idf.py set-target esp32c6
-- Configuring done
-- Generating done
-- Build files have been written to: rtio-device-sdk-c/demos-esp32/rtio/remote_switch/build

$ idf.py menuconfig

第三步，设定WiFi SSID、WiFi密码和目标服务器地址。

$ idf.py menuconfig
    Serial flasher config  --->
    Partition Table  --->
    Example Configuration  --->
    ...

运行idf.py menuconfig后选中Example Configuration --->,配置如下选项。

(myssid) WiFi SSID
(mypassword) WiFi Password
(demo.rtio.mkrainbow.com) RTIO Service HOST
(17017) RTIO Service PORT

第四步，编译, 显示如下信息编译成功。

$ idf.py build
#...
Successfully created esp32c6 image.
#...
Project build complete. To flash, run:
 idf.py flash

第五步，将开发板的串口（type-c口，并标注“UART”字样）连接到Windows主机，通过以下指令开始烧录。注意，需要先将开发板USB映射到WSL中，可参考 4.2. WSL连接USB 。

$ idf.py flash

# ...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 508.7 kbit/s)...
Hash of data verified.

烧录成功，可以监视设备日志，以下为WiFi和RTIO服务器都连接成功的日志。

I (7265) wifi station: got ip:192.168.xxx.xxx
I (7265) wifi station: connected to ap SSID: xxx password: xxx
# ...
[INFO] [RTIO] [7479] [core_rtio.c:481 connectRTIOServer] Device verification successful.

3.3. 通过`curl`发送请求开关LED

将参数编码“on”、“off” base64编码。

$ echo -n "on" | base64
b24=
$ echo -n "off" | base64
b2Zm

在WSL中执行以下命令打开LED。

curl http://localhost:17917/cfa09baa-4913-4ad7-a936-3e26f9671b10 -d '{"method":"copost", "uri":"/switch","id":1234,"data":"b24="}'

执行以下命令关闭LED。

curl http://localhost:17917/cfa09baa-4913-4ad7-a936-3e26f9671b10 -d '{"method":"copost", "uri":"/switch","id":1234,"data":"b2Zm"}'

执行以上操作可观察开发板上LED状态，结果可参考附录三：成果展示。关键日志如下。

[INFO] [RTIO_SWITCH] [739574] [rtio_switch.c:51 uriSwitch] Handling the copost req with uri=/switch, pReqData=on.
[INFO] [RTIO_SWITCH] [746024] [rtio_switch.c:51 uriSwitch] Handling the copost req with uri=/switch, pReqData=off.

4. 附录一：WSL相关设定

4.1. WSL网络配置

首先，确保Windows主机网络是“专用”网络，而不是“公用”网络。如果设置为公用，Windows 防火墙会限制局域网流量。

打开Windows设置，“网络和Internet”页面，点击顶部的“属性”，选择“专用网络”。

第二步，打开RTIO对外服务的端口，防火墙增加17017端口。管理员权限下打开Windows PowerShell，执行以下命令。

netsh advfirewall firewall add rule name="17017 for RTIO" protocol=TCP dir=in action=allow

如果通过Ping进行网络测试，默认下Windows主机可能禁用“ICMP Echo”，可以尝试增加以下规则。

netsh advfirewall firewall add rule name="ICMP for RTIO" protocol=ICMPV4 dir=in action=allow

第三步，端口转发，将开发板请求转发到WSL上。(这里WSL采用默认网络模型，也可尝试其他网络模式，比如 Mirrored mode networking，则可跳过下面步骤。)

获取目标WSL IP地址。

> wsl --list --running
Ubuntu-22.04

> wsl -d Ubuntu-22.04  hostname -I
172.22.3.95

以下以“172.22.3.95”为例，注意替换该地址。执行以下命令进行端口转发。

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=17017 connectaddress=172.22.3.95 connectport=17017

可通过下面命令查看端口转发。

netsh interface portproxy show all

4.2. WSL连接USB设备

详细参考： Install the USBIPD-WIN project。

安装usbipd，管理员权限下打开Windows PowerShell,运行如下命令。

winget install --interactive --exact dorssel.usbipd-win

连接开发板，使用usbipd列出设备。

> usbipd list
Connected:
BUSID  VID:PID    DEVICE                                                        STATE
1-10   0b05:1939  AURA LED Controller, USB 输入设备                             Not shared
5-3    10c4:ea60  Silicon Labs CP210x USB to UART Bridge (COM5)                Not shared

附加设备到WSL，ESP32-C6-DevKitC-1 USB 设备为“Silicon Labs CP210x USB to UART Bridge”， BUSID为“5-3”。

> usbipd bind --busid 5-3

> usbipd list
Connected:
BUSID  VID:PID    DEVICE                                                        STATE
1-10   0b05:1939  AURA LED Controller, USB 输入设备                             Not shared
5-3    10c4:ea60  Silicon Labs CP210x USB to UART Bridge (COM5)                 Shared

> usbipd attach --wsl --busid 5-3
usbipd: info: Using WSL distribution 'Ubuntu-22.04' to attach; the device will be available in all WSL 2 distributions.

显示如上信息表示添加成功。WSL客户机里查看设备。

$ lsusb
Bus 001 Device 002: ID 10c4:ea60 Silicon Labs CP210x UART Bridge

$ ls /dev/ttyUSB0
/dev/ttyUSB0

/dev/ttyUSB0 即可用于固件烧录。

5. 附录二：实验结束（选做）

5.1. 恢复WSL网络相关设置

管理员权限下打开Windows PowerShell，运行如下命令。

关闭端口转发。

netsh interface portproxy show all
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=17017

查询为RTIO添加的规则。

> netsh advfirewall firewall show rule name=all | Select-String "RTIO"
Rule Name:                             17017 for RTIO
Rule Name:                             ICMP for RTIO

删除相关规则。

netsh advfirewall firewall delete rule name="17017 for RTIO"
netsh advfirewall firewall delete rule name="ICMP for RTIO"

5.2. 恢复网络属性

如果实验前为“公用网络”，记得恢复网络属性。

打开Windows设置，“网络和Internet”页面，点击顶部的“属性”，选择“公用网络”。

5.3. USB设备解除绑定

管理员权限下打开Windows PowerShell，使用以下命令解绑，将BUSID替换为目标ID。

usbipd detach --busid BUSID
usbipd unbind --busid BUSID

6. 附录三：成果展示

alt text

如上图。报文中data字段使用base64编码，解码如下。

$ echo -n "b24=" | base64 -d
on
$ echo -n "b2Zm" | base64 -d
off
$ echo -n "b2s=" | base64 -d
ok

结论，在开发环境（WSL2）中，使用curl发出HTTP请求，成功点亮或熄灭LED，方便在本地环境中实验。如果将RTIO部署在云端Linux环境则不必进行WSL相关操作，部署更为简单。