跳到主要内容

JSON 指令发送方式

JSON 指令用于向 ESP32 下位机发送控制或查询请求。网页和 HTTP 请求由树莓派 Web 后端通过串口转发;通过串口直连时,可用 Python 程序发送 JSON,并读取下位机返回的数据。

本页介绍网页命令框、HTTP 请求和直接串口三种发送方式,并提供 PowerShell 与 Python 示例。调用已有指令无需重新烧录固件;以下示例只操作 OLED、灯光和查询机械臂状态,不会驱动底盘或机械臂运动。

认识 JSON 指令​

JSON(JavaScript Object Notation)使用键值对表示数据。以下指令用于在 OLED 第 0 行显示文本:

{"T":3,"lineNum":0,"Text":"Hello-M2"}

外层花括号表示一个对象,各字段之间用逗号分隔。字段名和文本使用英文双引号,数字不加引号。T 指定指令类型,其余字段提供该指令的参数;字段名区分大小写。

发送到网页命令框时,还需要在 JSON 前加上 base -c,由 Web 后端识别并转发。HTTP 示例同样使用这个前缀;直接串口发送时不加此前缀。

操作准备​

  1. 按 Web 控制界面使用 打开 http://<IP>:5000,确认页面与设备连接。
  2. 停止运动和自动任务,确认底盘、机械臂静止。
  3. 选择一种发送方式:网页和 HTTP 需要保持 Web 后端运行;直接串口需要先停止占用串口的程序。不要同时运行 ROS2 实体驱动。
  4. 网页发送时找到页面下方的 Enter Command;HTTP 发送时,在电脑上准备 PowerShell 或 Python 3;直接串口发送时,通过 SSH 登录树莓派宿主机。

只需选择适合的一种方式,无需依次运行全部示例。

通过网页发送​

在网页 Enter Command 中输入以下完整一行,然后点击“Send”:

base -c {"T":3,"lineNum":0,"Text":"Hello-M2"}

命令框与按钮位置见 Web 命令框示意。

OLED 第 0 行应显示 Hello-M2。base -c 是网页应用的转发命令,不是 Linux 或 PowerShell 命令,不要在 SSH 终端中执行。

内容含义
base -c由 Web 程序解析并转发后面的 JSON 对象
T下位机指令类型;3 用于 OLED 文本显示
lineNumOLED 行号,范围为 0~3
Text该行显示的文本

当前网页解析器按空格拆分输入。保留 base、-c 与 JSON 之间的空格,JSON 内部不要加空格;示例文本也使用不带空格的字符串。字段名区分大小写,使用英文双引号,不使用中文引号。

需要修改显示内容时,将 Hello-M2 改为另一个不带空格的英文或数字字符串,再发送一次,观察 OLED 是否随之变化。

在视频区域查看反馈​

在网页命令框发送以下命令,打开接收数据显示:

base -r on

接收数据以滚动文本叠加在视频区域,不是在命令输入框中显示。发送机械臂状态查询:

base -c {"T":105}

在滚动文本中找到 T 字段为 1051 的消息,再查看其中的 x、y、z、b、s、e、t 等字段。字段含义见 串口反馈说明。其间可能夹杂 T 字段为 1001 等其他类型的消息。Web 后端也会持续查询机械臂,仅凭滚动文本无法判断某条消息是否来自刚才的手动查询。

视频区域宽度有限,较长的 JSON 可能被截断,数值显示也可能经过舍入。需要读取完整返回内容时,使用 直接串口方式,不要把视频叠字作为完整原始数据。

结束查看后,在同一命令框发送以下命令,隐藏接收数据叠字:

base -r off

base -r 只控制接收数据的显示,不是底盘或机械臂停止命令。

通过 HTTP 请求发送​

电脑与小车处于同一可互通网络时,可向树莓派 Web 后端发送 HTTP(Hypertext Transfer Protocol)请求。指令仍由 Web 后端转发,不需要在电脑上打开底盘串口。

项目内容
请求地址http://<小车IP>:5000/send_command
请求方法POST
请求格式表单,application/x-www-form-urlencoded
表单字段command,值为完整的 base -c ... 命令

接口接收的是表单字段,不是将下位机 JSON 对象作为 HTTP 请求体直接发送。HTTP 发送时也应保持 Web 后端运行。

Windows PowerShell 示例​

在电脑上打开 Windows PowerShell,复制以下代码。热点连接使用示例地址;连接路由器时,将地址替换为 OLED 显示的实际 IP。

$m2Address = 'http://192.168.50.5:5000'

Invoke-RestMethod `
-Uri "$m2Address/send_command" `
-Method Post `
-Body @{command='base -c {"T":3,"lineNum":0,"Text":"HTTP-M2"}'} `
-TimeoutSec 10 |
ConvertTo-Json

请求返回的内容如下,JSON 字段顺序可能不同:

{"message":"Command received","status":"success"}

观察 OLED 第 0 行是否显示 HTTP-M2。该响应是 Web 后端的接收提示,不包含下位机执行回执或关节反馈;命令解析出错时也可能返回相同内容,不能只凭 success 判断执行结果。

Python 示例​

在电脑上检查 Python 版本:

python --version

使用 Python 3,将以下代码保存为 m2_http_json.py。示例只使用 Python 标准库,无需安装额外依赖。将 address 改为小车实际地址。

import json
import urllib.parse
import urllib.request

address = "http://192.168.50.5:5000"

command = {"T": 3, "lineNum": 0, "Text": "PYTHON-M2"}
command_text = "base -c " + json.dumps(command, separators=(",", ":"))

body = urllib.parse.urlencode({"command": command_text}).encode("utf-8")
request = urllib.request.Request(
address + "/send_command",
data=body,
headers={"Content-Type": "application/x-www-form-urlencoded"},
method="POST",
)

with urllib.request.urlopen(request, timeout=10) as response:
print(response.read().decode("utf-8"))

在 Windows PowerShell 中进入文件所在目录,运行:

python .\m2_http_json.py

终端应打印上述接收提示,OLED 第 0 行应显示 PYTHON-M2。

修改指令时,只需修改 command 字典中的字段。json.dumps(..., separators=(",", ":")) 将字典转换为不带格式空格的 JSON 文本,以适应 Web 命令解析;文本字段本身也不要包含空格。urlencode 将完整命令编码为接口需要的表单。

通过树莓派串口发送与读取反馈​

以下以树莓派 5 的配套系统为例,使用宿主机串口 /dev/ttyAMA0,波特率 115200,数据格式为 8 位数据位、无校验、1 位停止位(8N1)。使用配套 ugv-env 中的 Python 和 pyserial,无需进入 ROS2 容器。

本例使用树莓派与驱动板已有的串口连接,无需连接电脑 USB 下载线。驱动板 USB 串口与 40PIN 串口共用同一路串口,不能同时使用。

释放串口​

确认底盘和机械臂静止、夹爪无夹持物。通过 SSH 登录后,在树莓派宿主机执行以下命令,记下三个服务原先的状态,再停止服务:

for unit in ugv-app.service ugv-jupyter.service roarm_web_app.service; do
printf '%s: ' "$unit"
systemctl --user is-active "$unit"
done

systemctl --user stop \
ugv-app.service \
ugv-jupyter.service \
roarm_web_app.service

pgrep -af '/home/ws/ugv_rpi/app[.]py'
sudo fuser -v /dev/ttyAMA0
printf '串口检查退出码:%s\n' "$?"

pgrep 无输出表示未匹配到 Web 主程序;fuser 无占用输出且退出码为 1,表示此次检查未发现串口占用。工具不存在、权限错误或其他报错不能按串口空闲处理。

停止命令长时间不返回或服务报错时,不要仅凭网页失去连接继续操作。确认停止操作已经结束、原程序无残留且串口无占用后再运行示例;仍有占用或状态无法确认时,停止后续操作,记录服务报错和串口占用情况。

发送显示指令并查询状态​

在同一宿主机终端执行以下整段代码。程序先让 OLED 显示 SERIAL-M2,再发送 {"T":105} 查询机械臂状态。程序最多等待 8 秒,收到 T 字段为 1051 的 JSON 反馈后结束。

/home/ws/ugv_rpi/ugv-env/bin/python - <<'PY'
import json
import time
import serial

port = None

try:
with serial.Serial(
"/dev/ttyAMA0",
baudrate=115200,
timeout=0.2,
write_timeout=1,
exclusive=True,
) as port:
print("串口已打开:/dev/ttyAMA0,115200,8N1", flush=True)

def send(command):
packet = (json.dumps(command) + "\n").encode("utf-8")
port.write(packet)
port.flush()
print("发送:", command, flush=True)

port.reset_input_buffer()
send({"T": 3, "lineNum": 0, "Text": "SERIAL-M2"})
time.sleep(0.3)

port.reset_input_buffer()
send({"T": 105})

buffer = b""
reply = None
other_types = set()
deadline = time.monotonic() + 8

while time.monotonic() < deadline and reply is None:
buffer += port.read(min(port.in_waiting or 1, 4096))

while b"\n" in buffer:
line, buffer = buffer.split(b"\n", 1)
try:
message = json.loads(line.decode("utf-8"))
except (UnicodeDecodeError, json.JSONDecodeError):
continue

if not isinstance(message, dict):
continue

message_type = str(message.get("T"))
if message_type == "1051":
reply = message
break
other_types.add(message_type)

if reply is not None:
print("收到机械臂查询反馈:", flush=True)
print(json.dumps(reply, ensure_ascii=False, indent=2), flush=True)
else:
print("8 秒内没有收到 T 字段为 1051 的查询反馈", flush=True)
print("期间收到的其他消息类型:", sorted(other_types), flush=True)

except (serial.SerialException, OSError) as exc:
print("串口测试未完成:", exc, flush=True)
finally:
if port is not None:
print("串口已关闭:", not port.is_open, flush=True)
PY

OLED 第 0 行应显示 SERIAL-M2。终端应打印 T 字段为 1051 的 JSON 对象,结束时显示“串口已关闭:True”。发送指令成功不等于已经收到反馈。等待超时时,不要把空结果解释为关节角度为零。

返回字段含义
T返回数据类型,1051 为机械臂状态反馈
x、y、z机械臂末端坐标,单位为 mm,不是 ROS2 底盘或相机坐标
b、s、e底座、肩、肘关节角度,单位为 rad
t夹爪角度,单位为 rad
torB、torS、torE、torH舵机负载相关字段,不应直接按 kg·cm 或 N·m 解释

直接串口使用 UTF-8 编码,并在每条 JSON 后添加换行符。Python 字典可以包含格式空格,不受网页命令框的空格限制。串口可能持续收到其他类型的数据,因此示例按换行拆分消息,只把 T 字段为 1051 的消息作为查询结果。

退出并恢复 Web​

程序结束后检查串口是否释放:

sudo fuser -v /dev/ttyAMA0
printf '串口检查退出码:%s\n' "$?"

确认无占用后,恢复切换前运行的服务。启动 Web 可能发送机械臂初始化姿态目标,恢复前清空运动范围、确认夹爪无夹持物。若某个服务原先没有运行,不要将其加入恢复命令。

若三个服务原先均为 active,执行:

systemctl --user start \
ugv-app.service \
ugv-jupyter.service \
roarm_web_app.service

for unit in ugv-app.service ugv-jupyter.service roarm_web_app.service; do
printf '%s: ' "$unit"
systemctl --user is-active "$unit"
done

等待控制页可以打开后刷新页面,检查视频和状态更新,并确认底盘与机械臂最终静止。Web 启动后会重新写入 OLED 状态信息;服务为 active 不能代替页面和实物检查。

清除示例文字​

完成网页或 HTTP 显示示例后,在网页命令框中发送:

base -c {"T":3,"lineNum":0,"Text":""}

检查 OLED 第 0 行的示例文字是否清除。也可将 Text 改为需要显示的内容;该操作不会自动重建原有的网络信息画面。

T=-3 用于切换下位机默认显示,但 Web 后端会持续发送自定义 OLED 内容,因此不能用它保证恢复 Web 的整套状态画面。

控制车体照明灯​

车体前方的一对照明灯由驱动板 IO4 灯光输出控制。IO4 和 IO5 是驱动板输出名称,不是树莓派 GPIO 编号。IO5 不控制这对灯,以下示例保持其输出为零。

在网页命令框发送以下指令,开启照明灯:

base -c {"T":132,"IO4":64,"IO5":0}

观察车体前方的一对灯是否亮起。64 是 PWM 输出值,取值范围为 0~255,不涉及底盘或机械臂速度。

发送以下指令关闭灯光:

base -c {"T":132,"IO4":0,"IO5":0}

观察两盏灯是否熄灭。灯光已经关闭时,再次发送关闭指令不会产生可见变化。不要根据输出名称连接未知负载。

不同发送入口的区别​

入口传入内容串口管理
网页命令框带 base -c 前缀的文本使用正在运行的 Web 后端,不另开串口
HTTP 请求(含 HTTP Python 示例)表单字段 command,内容为完整网页命令由 Web 后端管理串口,调用端不另开串口
Python 串口封装Python 字典,由封装编码和添加换行独立程序需要先释放其他程序占用的串口
直接串口(本页串口示例)UTF-8 编码、以换行结束的 JSON 字节停止其他占用程序后,由示例管理收发、超时和关闭

HTTP Python 示例调用现有 Web 后端;串口 Python 示例则直接打开设备串口。不要将 base -c 前缀发给原始串口,也不要将整行网页命令作为 Python 字典传给串口封装。

常见问题​

现象处理方式
终端提示找不到 base 命令返回网页 Enter Command 输入框发送,不在终端运行
JSON 解析错误检查英文双引号、字段大小写和逗号,删除 JSON 内部空格;先复制本页 OLED 示例排查
网页或 HTTP 发送后 OLED 没有变化确认设备供电、网页连接,以及 Web 后端没有被停止;不要连续发送运动指令试探
HTTP 请求超时或连接失败检查 IP、网络连通性和 Web 后端状态,确认控制页可通过同一地址的 :5000 打开
HTTP 返回 success,但 OLED 没有变化检查 command 字段、base -c 前缀与 JSON 格式;该响应不能作为下位机执行成功的依据
其他程序同时访问串口只保留所选发送方式需要的程序;独立串口示例需先停止 Web 后端
直接串口打开失败检查设备路径、运行账户权限和串口占用,不重复启动另一份串口程序
通过串口发送 {"T":105} 查询机械臂状态,超时仍未收到 T 字段为 1051 的 JSON 反馈先检查串口通信。确认选对串口、波特率设置正确,且没有其他程序占用串口。确认发送的是完整 JSON,末尾带换行符。如果能收到其他类型的数据,保留原始输出,再核对整机固件和机械臂模块配置

点击发送只表示提交了命令,不能证明 ESP32 已完成执行。网页反馈可按 视频区域查看反馈开启,但显示可能被截断,不能代替完整的原始串口数据。

网页或 HTTP 显示示例结束后,清除示例文字;直接串口示例结束后,按上述步骤释放串口并恢复 Web。未知指令可能改变产品配置、舵机扭矩或运动目标,不要从其他产品复制维护、校准或整臂回位命令。