# 微雪机械臂 **Repository Path**: jun626/microsnow-mechanical-arm ## Basic Information - **Project Name**: 微雪机械臂 - **Description**: 微雪机械臂教程资料，给客户使用 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-15 - **Last Updated**: 2026-10-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # RoArm-M2-S 机械臂实战培训 · 课程资料仓库 面向**客户培训**的完整讲义与源码仓库：围绕微雪（Waveshare）**RoArm-M2-S** 桌面 4 自由度机械臂，用 **8 个课时** 带零基础学员完成从「开箱点亮」到「STM32 单片机控臂 + 结课联演」的全过程。 全部课程基于**官方固件与 JSON 协议**，**不需要编译或烧录机械臂固件**——无论走网页、树莓派还是 STM32，本质上都是同一件事：**向机械臂发送一行 JSON 指令**。 > **新手入口：**直接双击打开 [`课件/index.html`](<课件/index.html>)，即可看到课程总览并按卡片进入任意一课。 --- ## 一、三分钟上手 | 你想做的事 | 怎么做 | |---|---| | 浏览全部课程 | 浏览器打开 [`课件/index.html`](<课件/index.html>) | | 看某一课的课堂演示 | 打开该课目录下的 `课件.html`（如 `课件/第1课-初识灵臂/课件.html`） | | 打印讲义 / 随堂查阅 | 打开该课目录下的 `文档/学员手册.md`（含指令速查表、排障表、验收清单） | | 跑示例代码 | 该课目录下的 `源码/`，均带中文注释，多数脚本可直接 `python3 xxx.py` 运行 | | 查完整 JSON 指令 | 打开 [`doc/RoArm-M2-S-JSON协议清单.html`]()（72 条，可搜索、可复制、可打印） | | 查机械臂离线官方资料 | 打开 [`doc/official/index.html`]()（Wiki 离线页、json_cmd.h、示例、图纸、固件） | | 找课后练手项目 | 浏览器打开 [`doc/RoArm-M2-S实战小项目集.html`]()（P1~P8） | | 查固件 / 3D 模型 / 尺寸图 | [`RoArm-M2-repo/`]()（官方开源仓库镜像） | | 看教程与官方 Wiki 的核对结论 | [`doc/教程-WIKI核对报告.md`]()（已修正 6 处偏差） | --- ## 二、仓库结构 ```text 培训/ ├── README.md # 本文件：仓库总说明 ├── 课件/ │ ├── index.html # ★ 课程总览（含课程阶梯、课前准备、安全须知、参考资源） │ ├── 第1课-初识灵臂/ │ ├── 第2课-识令通语/ │ ├── 第3课-御臂以码/ │ ├── 第4课-云端执手/ │ ├── 第5课-运筹成弧/ │ ├── 第6课-探囊取物/ │ ├── 第7课-编舞成章/ │ └── 第8课-融会贯通/ │ ├── 课件.html # 课堂演示幻灯片（双击用浏览器打开） │ ├── 文档/学员手册.md # 可打印讲义（A4） │ ├── 源码/ # 本课示例程序，带详细中文注释 │ └── 图片/ # 自绘示意图 *.svg + 封面.jpg + 官方图/ ├── doc/ │ ├── RoArm-M2-S-JSON协议清单.html # ★ 全 72 条 JSON 指令手册（可搜索/复制/打印） │ ├── RoArm-M2-S实战小项目集.html # 与 8 课时配套的 P1~P8 实战项目 │ ├── 教程-WIKI核对报告.md # 教程 × 官方 Wiki 核对结论与修改记录 │ └── official/ # 官方资料包（离线可用） │ ├── index.html # 资料索引页 │ ├── json_cmd.h # 固件指令定义头文件（权威） │ ├── wiki/ # 10 篇官方 Wiki 离线页面 │ ├── examples/ # 官方 Python 示例 │ ├── hardware/ # STEP 模型、尺寸图、原理图 │ └── firmware/ # 预编译固件 └── RoArm-M2-repo/ # 官方开源仓库镜像：固件源码、示例、3D 模型、原理图 ├── firmware/ # 预编译固件 RoArm-M2.ino.bin ├── examples/python/ # 官方 HTTP / 串口 Python 示例 ├── hardware/ # STEP 模型、尺寸图、驱动板原理图 └── libraries/ # Arduino 依赖库 ``` > 每课的 `源码/__pycache__/` 是 Python 运行产生的缓存，可安全删除，不影响使用。 --- ## 三、课程阶梯（八课成章，约 14.5 学时） | 课时 | 主题 | 时长 | 难度 | 关键内容 | 配套源码 | |:--:|---|:--:|:--:|---|---| | 第 1 课 | **初识灵臂** | 90 min | ★☆☆ | 结构认知、5 颗舵机 ID、接线上电、读懂 OLED、手机连热点网页控制 | `quick_test.py` | | 第 2 课 | **识令通语** | 90 min | ★★☆ | 三种通信通道（网页 / HTTP GET / USB 串口）、JSON 指令语法、115200 8N1 | `serial_simple_ctrl.py`、`json_menu.py` | | 第 3 课 | **御臂以码** | 120 min | ★★☆ | 树莓派 + Python，USB 串口 / GPIO UART 两种接法 | `arm_serial.py`、`arm_http.py`、`demo_joints.py`、`demo_pose.py` | | 第 4 课 | **云端执手** | 120 min | ★★☆ | Flask 自建网页控制面板，手机滑块控臂 | `app.py`、`templates/index.html` | | 第 5 课 | **运筹成弧** | 120 min | ★★★ | 笛卡尔坐标系、可达范围、轨迹规划，画方 / 画圆 | `read_feedback.py`、`coord_move.py`、`draw_square.py`、`draw_circle.py` | | 第 6 课 | **探囊取物** | 120 min | ★★★ | 夹爪标定、定点标定、抓取六步法；选配颜色分拣 | `grip_calib.py`、`grasp_point.py`、`color_sort.py` | | 第 7 课 | **编舞成章** | 90 min | ★★☆ | 机械臂内置任务系统，任务编排、循环播放、开机任务 | `build_task.py`、`play_task.py`、`manage_task.py` | | 第 8 课 | **融会贯通** | 120 min | ★★★ | STM32 通过串口下发 JSON，三按键演示 + 结课联演 | `main.c`、`arm_cmd.h` | **三条控制路线（同一套指令语言）** - **路线 A · 网页控制**：浏览器打开官方控制页，零代码上手（第 1、2 课） - **路线 B · 树莓派 / Python 控制**：程序通过 WiFi 或串口发送 JSON（第 3~7 课） - **路线 C · STM32 单片机控制**：单片机串口下发同样的 JSON（第 8 课） --- ## 四、课前准备 **硬件** | 类别 | 物品 | 用途 | |---|---|---| | 必备 | RoArm-M2-S 机械臂 + 12V/5A 电源适配器 + 桌面固定夹 | 培训主角，**务必先固定底座** | | 必备 | 树莓派套装（含 SD 卡、电源） | 第 3~7 课控制主机 | | 必备 | STM32 开发板（如 F103C8T6）+ ST-Link | 第 8 课单片机控制 | | 线材 | USB-A 转 Type-C 数据线（随箱附带）、杜邦线若干 | 串口通信 / GPIO 接线 | | 选配 | USB 摄像头 | 第 6 课颜色识别 | **软件** - Chrome / Edge 浏览器、**Python 3.9+**、VS Code - **CP2102 串口驱动**（Windows USB 串口通信必备） - STM32 侧：STM32CubeMX + Keil MDK-ARM 或 STM32CubeIDE（仅第 8 课） **Python 依赖（按课时安装）** ```bash pip3 install pyserial requests # 第 2、3、5、6、7 课 pip3 install flask requests # 第 4 课 pip3 install opencv-python numpy # 第 6 课选学：颜色分拣 ``` **树莓派串口权限（第 3 课起）** ```bash sudo usermod -aG dialout $USER # 加入后需注销重新登录 sudo raspi-config # 接口选项 → Serial Port → 关闭登录 Shell、启用硬件串口 ``` --- ## 五、通信约定（背下来这三行） | 项 | 约定 | |---|---| | WiFi AP 模式（出厂默认） | 热点 `RoArm-M2`，密码 `12345678`，网页地址 `192.168.4.1`（**不加 https / www**） | | WiFi STA 模式 | 机械臂 IP 看 **OLED 屏第 2 行**（`ST:` 后） | | HTTP 接口 | `http://<机械臂IP>/js?json={"T":100}`（大括号引号需 URL 编码） | | 串口参数 | **115200** / 8 数据位 / 无校验 / 1 停止位（8N1） | | 串口指令格式 | 一行 JSON 文本 + **换行符 `\n`** 结尾（缺换行指令不执行） | | Python 串口要点 | 打开串口后必须 `ser.setRTS(False); ser.setDTR(False)`，否则 ESP32 可能误入下载模式 | | 设备名 | Linux `/dev/ttyUSB0`、`/dev/ttyACM0`、`/dev/serial0`（GPIO 接法）；Windows `COMx` | **急停与恢复**：任何异常第一时间 `{"T":0}`，排除后 `{"T":999}` 恢复。 --- ## 六、JSON 指令速查（全课程通用） | 分类 | 指令 | 说明 | |---|---|---| | 急停 / 恢复 | `{"T":0}` / `{"T":999}` | 立即停止 / 恢复控制 | | 回中位 | `{"T":100}` | 所有关节回到中位姿态 | | 单关节弧度 | `{"T":101,"joint":1,"rad":0.5,"spd":0.5,"acc":10}` | joint：1 底座 2 肩 3 肘 4 末端 | | 全关节角度 | `{"T":122,"b":0,"s":0,"e":90,"h":180,"spd":10,"acc":10}` | 度数制，**acc ≤ 22.5** | | 坐标控制 | `{"T":104,"x":235,"y":0,"z":234,"t":3.14,"spd":0.25}` | 贝塞尔平滑插值，x 前 / y 左 / z 上（mm），t 弧度 | | 坐标直达 | `{"T":1041,"x":200,"y":0,"z":150,"t":3.14}` | 无插值立即执行，适合轨迹密集描点 | | 单轴移动 | `{"T":103,"axis":1,"pos":220,"spd":0.25}` | axis：1=x 2=y 3=z 4=t | | 夹爪开 / 合 | `{"T":106,"cmd":1.57}` / `{"T":106,"cmd":3.14}` | 行程弧度，范围 1.08~3.14 | | 夹持力 | `{"T":107,"tor":200}` | 上限约 30% 扭矩，从小往大调 | | 读反馈 | `{"T":105}` | 返回末端 `x/y/z/t`（弧度）与扭矩 | | 扭矩锁 | `{"T":210,"cmd":1}` / `{"T":210,"cmd":0}` | 开 / 关（关后方可徒手摆位） | | 任务系统 | `{"T":220}` 建 · `{"T":222}` 加步 · `{"T":224}` 延时 · `{"T":242,"name":"a","times":3}` 播放 · `{"T":221}` 查看 | 存在 ESP32 Flash，**断电不丢** | | 点灯 / 延时 / 重启 | `{"T":114,"led":255}` · `{"T":111,"cmd":3000}` · `{"T":600}` | led 0~255；延时毫秒 | > 各课《学员手册》末尾都附有当课专属指令表，完整指令集见官方 Wiki。 --- ## 七、安全须知（每次实操前必读） 1. **上电会动**：上电初始化时各关节自动运动，运动范围内不得站人、放杂物。 2. **底座必须固定**：用桌面固定夹或螺丝固定，防止运动时倾覆。 3. **禁止手掰**：通电且扭矩锁开启时手掰关节会**损伤减速齿轮**；需手动摆位先 `{"T":210,"cmd":0}` 关闭扭矩。 4. **断电先托臂**：断电瞬间扭矩释放，机械臂会因重力下垂——**先托住再关电源**。 5. **急停在手**：`{"T":0}` 急停，异常排除后 `{"T":999}` 恢复；堵转异响立即断电。 6. **负载与散热**：额定负载 0.5kg@0.5m，首次使用勿挂重物；高负载连续运行每 30 分钟停机散热。 7. **用电安全**：使用原装 12V/5A 适配器（7~12.6V），**禁止带电插拔**接口；STM32 与机械臂**供电各自独立但必须共地**。 8. **Z 值下限**：坐标控制时 **z 不得低于 30mm**，否则有磕桌风险。 --- ## 八、常见问题速查 | 症状 | 先查什么 | |---|---| | 搜不到 `RoArm-M2` 热点 | OLED 是否亮（不亮查供电）？靠近 1~2 米？断电重启 | | 打不开 `192.168.4.1` | 地址写错（无 https / www）？换 Chrome/Edge？等 10 秒刷新 | | 串口找不到端口 | CP2102 驱动装了吗？用的是数据线而不是纯充电线吗？ | | 串口发了没反应 | 结尾 `\n` 加了吗？波特率 115200？`setRTS/setDTR(False)` 了吗？ | | Linux `Permission denied` | `sudo usermod -aG dialout $USER` 后注销重登 | | HTTP 404 | 固定路径是 `/js?json=...` | | 树莓派 Flask 页面打不开 | 服务是否 `Running on http://0.0.0.0:5000`？防火墙放行？IP 用 `hostname -I` 核对 | | STM32 收到乱码 | HSE 晶振值配错导致波特率偏移（常见 8MHz，HCLK 72MHz） | | STM32 发指令无反应 | 是否共地？TX/RX 是否交叉？JSON 是否以 `\n` 结尾？ | | 目标点够不着 | 超出臂长 / 撞关节限位；把点拉近或调高 | | 任务播放没反应 | `{"T":221}` 查任务是否存在（忘了先 `{"T":220}` 建任务） | > 每课《学员手册》中都有更完整的排障表，建议打印放在工位。 --- ## 九、参考资源 | 资源 | 地址 | 用途 | |---|---|---| | 官方文档（微雪百科） | https://docs.waveshare.net/RoArm-M2/ | 参数、教程、注意事项权威来源 | | 官方开源仓库 | https://gitee.com/waveshare/RoArm-M2 | 固件源码、Python 例程、3D 模型 | | 本地仓库镜像 | [`RoArm-M2-repo/`]() | 离线查阅固件、示例、尺寸图与原理图 | | 培训总览 | [`课件/index.html`](<课件/index.html>) | 课程阶梯、目标、课前准备、安全须知 | | **JSON 协议清单** | [`doc/RoArm-M2-S-JSON协议清单.html`]() | **全 72 条指令**完整手册，可搜索、点击复制、直接打印 | | 官方资料包（离线） | [`doc/official/index.html`]() | 10 篇 Wiki 离线页、`json_cmd.h`、示例、图纸、固件 | | 教程核对报告 | [`doc/教程-WIKI核对报告.md`]() | 对照官方 Wiki 的核对结论，已修正 6 处偏差 | | 实战项目集 | [`doc/RoArm-M2-S实战小项目集.html`]() | P1 迎宾 → P8 STM32 控制器，与课时一一对应 | **实战项目集索引：** P1 挥手迎宾动作序列 · P2 树莓派键盘控制台 · P3 网页/手机控制面板 · P4 预设动作编排库 · P5 固定点位抓取演示 · P6 轨迹绘制（画圆/写字） · P7 无线控制（选做） · P8 STM32 控制器发指令控臂。 ---