跳到主要内容

JSON 指令发送方式

在控制机械臂时，我们使用一种特定的控制指令——JSON 指令，来告诉机械臂应该执行什么动作。无论是 Web 控制界面的底层通信，还是通过程序对机械臂进行编程控制，本质上都是在向机械臂发送 JSON 指令。
本节将介绍目前支持的三种 JSON 指令发送方式，以便你根据实际需求选择合适的接入方式。

什么是 JSON 指令？

JSON（JavaScript Object Notation）是一种轻量级的数据格式，可读性高，易于在不同系统之间传输和解析。机械臂通过接收 JSON 格式的指令来执行各类动作。

JSON 指令的基本格式：键:值。

  • 键必须是字符串，用双引号包围；
  • 值可以是多种类型：字符串、数字、对象、数组、布尔值或 null，其中，字符串必须用双引号包围，其它的不需要引号;
  • 多个 键:值 对之间用逗号分隔。

以下是控制机械臂运动到某一坐标位置的 JSON 指令示例：

{"T":1041,"x":200,"y":0,"z":150,"t":3.14}

其中 "T" 是指令类型编号，每条指令的编号都是固定的，其余字段是该指令对应的参数。

通过发送不同的 JSON 指令，可以实现 Web 界面按钮之外的更多功能。关于每条指令的具体含义和参数说明，请参阅 [JSON 指令功能详解]。

使用 JSON 指令前请注意

JSON 指令中的每个字符都很重要，缺少逗号、括号或者引号都会导致指令无法被机械臂正确解析。建议直接复制对应功能的指令模板，再修改其中的参数值，避免手动输入时引起格式错误。

目前支持以下三种方式向机械臂发送 JSON 指令：

方式连接类型适用场景局限性
Web 端界面发送无线（WiFi）快速验证指令、基础调试反馈内容较长时显示不全
HTTP 请求通信无线（WiFi）程序化控制、与其它系统集成依赖 WiFi，信号不稳定时会影响通信
串口通信有线（USB / GPIO）上位机集成、离线部署需要物理布线

1. Web 端界面发送​

这是最快捷的发送方式，无需额外配置，在已打开的 Web 控制界面中操作即可，适合快速验证某条指令的效果或临时调试使用。

RoArm-M2_Web 信息反馈标注图 信息反馈区标注图

  • ① 状态信息显示区：发送的 JSON 指令反馈的信息会在这里显示；
  • ② JSON 指令发送区：输入 JSON 格式指令并点击 SEND 发送，实现对机械臂的精细控制。
缺点：显示长度限制

部分 JSON 指令的反馈内容较长，状态信息显示区会显示不全。如需查看完整反馈信息，建议改用 HTTP 请求通信或串口通信的方式。

使用步骤：

  1. 确认已连接机械臂 WiFi 并打开 Web 控制界面，详见准备工作 → 上电与连接；
  2. 在 Web 控制界面底部的 FEEDBACK INFORMATION 区域的发送区中输入 JSON 指令，点击 SEND 发送；
  3. 机械臂执行指令后会在 ① 状态信息显示区展示机械臂返回的信息。

关于 FEEDBACK INFORMATION 区域的完整功能说明，请参阅 Web 控制界面使用 → FEEDBACK INFORMATION 。

2. HTTP 请求通信​

HTTP（Hypertext Transfer Protocol）是一种基于 WiFi 模块实现无线通信的协议，以无线方式向机械臂持续发送 JSON 指令并获取完整反馈，灵活简便。适合在 PC 或上位机上进行编程控制，或将机械臂集成到其它系统中。

通信特性：

  • 基于 WiFi 的无线通信，无需额外布线；
  • 请求-响应模型，可获取机械臂的完整反馈内容；
  • 支持任意可发起 HTTP 请求的编程语言或工具。

2.1 前提条件​

上位机需与机械臂处于同一 WiFi 网络下，且需确认机械臂当前的 IP 地址：

  • 机械臂处于 AP 模式（出厂默认）：IP 地址固定为 192.168.4.1，将上位机连接至机械臂热点（RoArm-M2，密码：12345678）即可；
  • 机械臂处于 STA 模式（已接入路由器）：IP 地址由路由器分配，请查看机械臂 OLED 显示屏第二行显示的实际 IP 地址。

关于 WiFi 模式的切换方法，请参阅 [WiFi 配置]。

2.2 下载例程​

安装 Git（若已安装可跳过）：

sudo apt update
sudo apt install git

克隆仓库：

git clone https://gitee.com/waveshare/RoArm-M2.git

下载完成后，Python 例程目录结构如下：

RoArm-M2_Python/
├── http_simple_ctrl.py       ← HTTP 通信例程
├── serial_simple_ctrl.py     ← 串口通信例程
└── requirements.txt          ← 依赖库列表

2.3 安装 Python​

在运行例程前，需要确认上位机已安装 Python。

树莓派、Jetson Orin Nano、RDK X5 等设备通常已预装 Python3，可直接在终端输入以下命令验证：

python3 --version

若未安装，执行以下命令安装：

sudo apt update
sudo apt install python3 python3-pip

安装完成后再次运行 python3 --version 确认版本。

2.4 创建虚拟环境并安装依赖​

什么是虚拟环境？

虚拟环境是一个独立的 Python 运行空间，在其中安装的依赖库不会影响系统中其它 Python 项目。推荐为每个项目单独创建虚拟环境，避免不同项目之间的库版本冲突。

① 进入例程目录

cd RoArm-M2/examples/python

② 创建虚拟环境

python3 -m venv 虚拟环境名称[一般为项目名-env]

# 例：python3 -m venv roarm-env

执行后，当前目录下会生成一个名为 roarm-env 的文件夹，这就是创建好的虚拟环境。

③ 激活虚拟环境，将 项目名-env 替换为你实际的虚拟环境名称：

source 项目名-env/bin/activate

激活成功后，命令提示符最前方会出现 (项目名-env) 的标识，如：(roarm-env) user@hostname:~/RoArm-M2/examples/python$。

④ 在虚拟环境中安装依赖库：

pip3 install -r requirements.txt
requirements.txt 是什么？

requirements.txt 是一个记录了例程所需依赖库的清单文件，Python 可以读取这个文件并一次性安装所有需要的库，无需手动逐个安装。

等待安装完成，出现 Successfully installed... 即表示安装成功。

提示

虚拟环境只需创建和安装依赖一次。后续每次运行例程前，都需先激活虚拟环境，再运行例程。若命令提示符前有 项目名-env 标识，说明虚拟环境已处于激活状态，无需重复激活。

2.5 运行例程​

确认虚拟环境已激活（命令提示符/终端前方显示 项目名-env）后，运行以下命令启动 HTTP 请求通信例程，将 IP 地址替换为机械臂的实际 IP 地址：

#Linux(树莓派/Linux/RDK)
python3 http_simple_ctrl.py 192.168.4.1

#Windows
python http_simple_ctrl.py 192.168.4.1

运行成功后，终端会显示以下提示，即表示已与机械臂建立通信连接：

input your json cmd：

RoArm-M2_HTTP

此时可在光标后输入 JSON 指令并按回车发送，机械臂执行后会返回反馈信息并显示在终端中。每次发送一条指令，可持续输入。按 Ctrl + C 退出程序。

例：发送一条查看机械臂信息的指令：
input your json cmd：{"T":105}
输入该指令后，会返回机械臂末端点位置坐标及各关节角度、负载等信息，如下图。
RoArm-M2_HTTP 示例

使用完毕后退出虚拟环境在命令提示符 / 终端中输入以下命令退出虚拟环境（Windows 和 Linux 通用）：

deactivate

关于可用的 JSON 指令及其参数说明，请参阅 [JSON 指令功能详解]。

3. 串口通信​

串口通信是一种通过物理线缆直接连接机械臂与上位机的有线通信方式，稳定性好、延时低，适合需要可靠连接或不便使用 WiFi 的场景，也适合将机械臂长期集成到上位机控制系统中。

什么是上位机？

上位机是指用于发送指令来控制机械臂的计算设备，例：个人电脑（PC）、树莓派、Jetson Orin Nano、RDK X5 等。机械臂在接收到上位机发送的指令后执行对应动作，并将执行结果反馈给上位机。

通信参数：

参数值
波特率115200
数据位8
停止位1
校验位无

按设备快速选择连接方式：

设备推荐连接接口推荐发送方式
PC（Windows / Linux）USB Type-C 接口串口助手软件或 Python 例程
树莓派GPIO 引脚（RX / TX）Python 例程
Jetson 系列GPIO 引脚（RX / TX）Python 例程
RDK 系列GPIO 引脚（RX / TX）Python 例程

3.1 硬件连接​

串口通信支持以下两种硬件连接方式，两种连接方式不可同时使用。

方式一：USB 连接【推荐初学者】​

USB 连接时最简单的有线连接方式，推荐初次使用串口通信的用户选择此方式。

使用随产品赠送的 USB 线（Type A 公转 Type C 公），将机械臂底座的 ESP32 串口通信（Type-C）接口连接至上位机的 USB 接口。

【图片待补充：PC / 树莓派 / Jetson / RDK 与机械臂相连接的示意图】

连接成功后，上位机系统会将机械臂识别为一个串口设备，后续需要通过该串口与机械臂通信。

什么是串口设备识别？

上位机通过 USB 连接机械臂后，上位机系统会自动为其分配一个串口设备编号，用于标识这个连接：

  • Windows：设备管理器中显示为 COMx（x 为数字，如 COM3）；
  • Linux：显示为 /dev/ttyUSB0 或 /dev/ttyACM0。

后续在串口助手软件或 Python 例程中，需要填写这个编号来指定通信端口。

如何查看串口设备编号？

在终端中执行以下命令，机械臂与上位机连接前后各执行一次，对比新出现的设备即为机械臂的串口编号：

ls /dev/ttyUSB*
# 或
ls /dev/ttyACM*

【教程持续更新中...】