From 31401afbbd00479d8edae12a3c92c67e92db9108 Mon Sep 17 00:00:00 2001
From: Vertax42 <1007644658@qq.com>
Date: Sun, 18 Oct 2026 14:11:24 +0800
Subject: [PATCH 1/4] =?UTF-8?q?docs:=20=E4=B8=AD=E6=96=87=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E7=BB=9F=E4=B8=80=E5=91=BD=E5=90=8D=E4=B8=BA=20<?=
 =?UTF-8?q?=E5=90=8D=E7=A7=B0>-zh.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README_CN.md -> README-zh.md,docs/USAGE_CN.md -> docs/USAGE-zh.md,仓库内链接
同步更新(README.md、docs/USAGE.md、两份中文文档互链、wrist_camera.py 的提示)。
CHANGELOG 历史条目保留当时的文件名。外部仓库(文档站、lerobot、三个工具)未引用旧名。

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                      |  6 ++++++
 README_CN.md => README-zh.md      |  2 +-
 README.md                         |  4 ++--
 docs/{USAGE_CN.md => USAGE-zh.md} | 10 +++++-----
 docs/USAGE.md                     |  2 +-
 python/examples/wrist_camera.py   |  2 +-
 6 files changed, 16 insertions(+), 10 deletions(-)
 rename README_CN.md => README-zh.md (99%)
 rename docs/{USAGE_CN.md => USAGE-zh.md} (99%)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index eae2949..14bcf7d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Chinese documents are named `<NAME>-zh.md`.** `README_CN.md` is now
+  `README-zh.md` and `docs/USAGE_CN.md` is `docs/USAGE-zh.md`; links inside the
+  repository are updated. English files stay authoritative.
+
 ## [0.4.3] - 2026-10-10
 
 ### Fixed
diff --git a/README_CN.md b/README-zh.md
similarity index 99%
rename from README_CN.md
rename to README-zh.md
index 584d97c..0e01e75 100644
--- a/README_CN.md
+++ b/README-zh.md
@@ -344,7 +344,7 @@ python python/examples/follower_status.py left
 
 ## 文档
 
-- [docs/USAGE_CN.md](docs/USAGE_CN.md)([English](docs/USAGE.md))—— 夹爪、腕部相机、视触觉传感器的完整上手流程
+- [docs/USAGE-zh.md](docs/USAGE-zh.md)([English](docs/USAGE.md))—— 夹爪、腕部相机、视触觉传感器的完整上手流程
 - [docs/INSTALL.md](docs/INSTALL.md) —— 构建选项、纯 C++ 构建、环境陷阱
 - [docs/CALIBRATION.md](docs/CALIBRATION.md) —— 编码器零点、行程、鱼眼内参
 - [docs/EXAMPLES.md](docs/EXAMPLES.md) —— 每个示例脚本与控制器参数
diff --git a/README.md b/README.md
index b3ebade..8b777be 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # taccap-gripper
 
-[中文](README_CN.md)
+[中文](README-zh.md)
 
 C++17 / Python SDK for the **TacCap-Gripper**, XenseRobotics' multimodal tactile
 data-collection gripper. One namespace: `xense::taccap::` in C++,
@@ -378,7 +378,7 @@ Logs: every process writes a DEBUG log to `~/.taccaplogs/session_*.log`
 
 ## Documentation
 
-- [docs/USAGE.md](docs/USAGE.md) ([中文](docs/USAGE_CN.md)) — end-to-end bring-up of gripper, wrist camera and tactile sensor
+- [docs/USAGE.md](docs/USAGE.md) ([中文](docs/USAGE-zh.md)) — end-to-end bring-up of gripper, wrist camera and tactile sensor
 - [docs/INSTALL.md](docs/INSTALL.md) — build options, C++-only builds, environment traps
 - [docs/CALIBRATION.md](docs/CALIBRATION.md) — encoder zero, travel span, fisheye intrinsics
 - [docs/EXAMPLES.md](docs/EXAMPLES.md) — every example script and controller parameter
diff --git a/docs/USAGE_CN.md b/docs/USAGE-zh.md
similarity index 99%
rename from docs/USAGE_CN.md
rename to docs/USAGE-zh.md
index 90756da..dbeeb01 100644
--- a/docs/USAGE_CN.md
+++ b/docs/USAGE-zh.md
@@ -23,7 +23,7 @@
 > [EXAMPLES.md](EXAMPLES.md#选择设备统一用-left--right)。
 
 安装见 [docs/INSTALL.md](INSTALL.md);请先完成一次性的
-[主机配置](../README_CN.md#主机配置一次性)(`dialout` 组、ModemManager udev 规则、
+[主机配置](../README-zh.md#主机配置一次性)(`dialout` 组、ModemManager udev 规则、
 相机 MJPEG 格式)。下文假定 `taccap` 环境已激活、
 `import xense.taccap` 能成功。
 
@@ -625,7 +625,7 @@ finally:
   一路未压缩的 YUYV(640×480 @ 30 fps ≈ 147 Mbit/s)就足以让下一台相机报
   `No space left on device` 或丢帧。保持 `use_mjpg=True`,并用
   `v4l2-ctl -d <设备> --get-fmt-video` 确认(见 README 的
-  [主机配置](../README_CN.md#3-腕部相机必须使用-mjpeg))。即使是 MJPEG,两个 OG + 一个
+  [主机配置](../README-zh.md#3-腕部相机必须使用-mjpeg))。即使是 MJPEG,两个 OG + 一个
   腕相机也会占掉相当一部分总线,满配采集时先实测帧率,别假设标称值。夹爪本身走串口,
   不受影响。
 - **谁持有 UVC 设备。** 生产环境里外部相机服务持有 `/dev/video*`,这时
@@ -648,9 +648,9 @@ finally:
 
 | 现象 | 多半是 |
 | --- | --- |
-| `scan_grippers()` 返回空,或 `role=Unknown` | 用户不在 `dialout` 组(见 README 的[主机配置](../README_CN.md#主机配置一次性)),或线没插好 |
-| 插上后立即打开报 `Device or resource busy` | ModemManager 在探测串口 —— 添加[主机配置](../README_CN.md#2-让-modemmanager-不要占用夹爪串口)里的 udev 规则 |
-| 相机报 `No space left on device` 或丢帧 | 没用 MJPEG —— 见[主机配置](../README_CN.md#3-腕部相机必须使用-mjpeg) |
+| `scan_grippers()` 返回空,或 `role=Unknown` | 用户不在 `dialout` 组(见 README 的[主机配置](../README-zh.md#主机配置一次性)),或线没插好 |
+| 插上后立即打开报 `Device or resource busy` | ModemManager 在探测串口 —— 添加[主机配置](../README-zh.md#2-让-modemmanager-不要占用夹爪串口)里的 udev 规则 |
+| 相机报 `No space left on device` 或丢帧 | 没用 MJPEG —— 见[主机配置](../README-zh.md#3-腕部相机必须使用-mjpeg) |
 | `fw_sn` 为空 / `Side.Unknown` | 固件没烧 SN,或固件早于 V1.6 |
 | 矫正后画面全黑 | 用了 `read_fisheye()` 的全零记录 —— 改用 `resolve_fisheye()` |
 | 矫正后画面偏心 | 未必是错的,主点本来就不一定在画面中心 |
diff --git a/docs/USAGE.md b/docs/USAGE.md
index e1f466c..03b5791 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -1,6 +1,6 @@
 # Usage — bringing up the three data paths
 
-> A Chinese version is available at [USAGE_CN.md](USAGE_CN.md). This English file is authoritative.
+> A Chinese version is available at [USAGE-zh.md](USAGE-zh.md). This English file is authoritative.
 
 <!-- For anyone bringing the hardware up for the first time: one section each for
      tactile, vision, and gripper readout/control, and each section is the complete
diff --git a/python/examples/wrist_camera.py b/python/examples/wrist_camera.py
index 6d0533f..d7867af 100755
--- a/python/examples/wrist_camera.py
+++ b/python/examples/wrist_camera.py
@@ -232,7 +232,7 @@ def resolve_wrist_camera(target: str) -> dict:
     if TACTILE_SN_RE.search(key):
         raise SystemExit(
             f"{key} 是视触觉(GSPS)传感器,不是腕相机。它的采集与矫正在 xensesdk 里,"
-            "不走本 SDK —— 见 docs/USAGE_CN.md 的触觉一节。"
+            "不走本 SDK —— 见 docs/USAGE-zh.md 的触觉一节。"
         )
     if key.startswith("/dev/"):
         raise SystemExit(

From 5536b3982c0475b045f1688c5f18a7f9c584eebc Mon Sep 17 00:00:00 2001
From: Vertax42 <1007644658@qq.com>
Date: Sun, 18 Oct 2026 14:22:45 +0800
Subject: [PATCH 2/4] =?UTF-8?q?fix(examples):=20motor=5Fota=5Fupdate=20?=
 =?UTF-8?q?=E6=94=AF=E6=8C=81=20EL05,=E5=88=B7=E5=90=8E=E8=AE=B0=E5=BD=95?=
 =?UTF-8?q?=E7=89=88=E6=9C=AC=E5=B9=B6=E4=BF=AE=E6=AD=A3=E8=BF=90=E5=8A=A8?=
 =?UTF-8?q?=E5=8C=85=E7=BB=9C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 识别 EL05 五段版本号(1.0.5.0.x),按厂家写法 vendor_str 比对
- 两遍流程:第一遍切私有协议,断电后第二遍刷写、核对、写入版本记录、切回 MIT
- 包络与电机额定不一致时默认改为额定值(--keep-envelope 可跳过)
- 新增 --to-mit;离线测试覆盖文件名/版本解析与各分支
- 新增客户文档 docs/MOTOR_OTA.md 与中文版 MOTOR_OTA-zh.md

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/MOTOR_OTA-zh.md                  | 152 +++++++++++++++++
 docs/MOTOR_OTA.md                     | 170 +++++++++++++++++++
 python/examples/motor_ota_update.py   | 211 ++++++++++++++++++-----
 python/tests/test_motor_ota_update.py | 233 ++++++++++++++++++++++++++
 4 files changed, 722 insertions(+), 44 deletions(-)
 create mode 100644 docs/MOTOR_OTA-zh.md
 create mode 100644 docs/MOTOR_OTA.md
 create mode 100644 python/tests/test_motor_ota_update.py

diff --git a/docs/MOTOR_OTA-zh.md b/docs/MOTOR_OTA-zh.md
new file mode 100644
index 0000000..67fae58
--- /dev/null
+++ b/docs/MOTOR_OTA-zh.md
@@ -0,0 +1,152 @@
+# 升级从夹爪的电机固件
+
+> 本文是 [MOTOR_OTA.md](MOTOR_OTA.md) 的中文版，以英文版为准。
+
+从夹爪里的 RobStride 电机运行着自己的固件，和夹爪主控（MCU）的固件是两套。本文介绍如何用
+`python/examples/motor_ota_update.py`，通过夹爪的 USB-C 线升级电机固件。电机不需要拆下来。
+
+| 电机 | 电机固件要求 |
+| --- | --- |
+| EL05 | ≥ 1.0.5.0.4 |
+
+## 开始之前
+
+- **夹爪固件 1.2.16**（升级电机至少需要 1.2.8）。用 `follower_status.py` 查看，看 `[fw]`
+  那一行。如果版本较旧，先用 `ota_update.py` 升级夹爪固件并断电重启。升级夹爪固件会把电机切回
+  常规协议，所以必须先升级夹爪、再升级电机，顺序不能反。
+- **SDK 0.4.3 或更新版本**，并且 `import xense.taccap` 能正常导入。
+- **我们提供的电机固件镜像**，例如 `EL05_1.0.5.0.4.bin`。请保持原文件名：脚本会从文件名读出
+  电机型号和版本，并与镜像内容和夹爪记录核对。
+- **没有别的程序在使用夹爪。** 先停掉你自己的程序。
+- **两指之间清空。** 每次断电重启后，夹爪会自动开合一次做标定。
+
+下文的"断电重启"一律指：拔下夹爪的 **24V 电源线**，等约 2 秒再插回。USB 线可以不拔，夹爪主控和
+电机都由 24V 供电。
+
+## 为什么同一条命令要运行两遍
+
+我们的 SDK 让电机工作在 **MIT 协议**下。电机只在**私有协议**下接受固件升级，而切换协议要到下次
+上电才生效。所以一次升级的过程是：
+
+1. 运行脚本：脚本把电机切到私有协议；
+2. 断电重启；
+3. 再运行一遍同样的命令：脚本刷写固件、核对版本、把新版本记进夹爪，如果运动安全包络和电机额定值
+   不一致就顺带改正，最后把电机切回 MIT；
+4. 断电重启。
+
+私有协议只在升级时使用。全部完成后夹爪回到 MIT，可以正常使用。
+
+## 操作步骤
+
+下面以左侧从夹爪为例；右侧用 `right`，或者用完整序列号（例如 `TCGU01A25Z0017s`）指定。
+
+### 1. 查看当前状态
+
+```bash
+python python/examples/follower_status.py left
+```
+
+看 `[fw]`（夹爪固件）和 `[motor fw]`（电机固件）两行。此时电机固件可能显示读不到：电机在 MIT 下、
+且夹爪里还没有记录时就是这样，属于正常现象。
+
+### 2. 第一遍：切到私有协议
+
+```bash
+python python/examples/motor_ota_update.py EL05_1.0.5.0.4.bin left
+```
+
+```text
+=== motor OTA, step 1 of 2 ===
+  the motor is on the MIT protocol and does not answer OTA frames there,
+  so it has to be switched to its private protocol first.
+Switch the motor to the private protocol? type 'yes': yes
+
+done. Now unplug the gripper's 24 V power cable for ~2 s and plug it back (USB may stay in),
+wait ~10 s, then run the same command again to flash.
+```
+
+**断电重启**，等约 10 秒。私有协议下电机保持不使能，夹爪不会做标定，这是正常的。
+
+### 3. 第二遍：刷写
+
+```bash
+python python/examples/motor_ota_update.py EL05_1.0.5.0.4.bin left
+```
+
+```text
+=== motor OTA, step 2 of 2 ===
+  gripper      : TCGU01A25Z0017s  firmware FirmwareVersion(1.2.16.0)
+  motor        : EL05  can_id 1  uid ...
+  motor fw now : 1.0.5.0.2
+  image        : EL05_1.0.5.0.4.bin
+                 92,584 B, 11,573 packs, version 1.0.5.0.4
+  envelope     : at the motor's rating, unchanged
+Flash the MOTOR with this image? type 'yes': yes
+  [########################################] 100.0%  11,573/11,573
+=== done in 28s; waiting for the motor ===
+  recorded     : motor fw 1.0.5.0.4 in follower flash
+  motor fw     : 1.0.5.0.2 -> 1.0.5.0.4
+  switched the motor back to the MIT protocol.
+
+Done. Now unplug the gripper's 24 V power cable for ~2 s and plug it back (USB may stay in);
+the gripper auto-calibrates (~10 s, keep the jaws clear) and is ready to use.
+```
+
+刷写大约需要半分钟。开始时出现 `motor OTA start: no reply (attempt 1/6)` 这类警告是正常的：
+电机要先重启进 bootloader，之后的某次重试才会应答。
+
+**运动安全包络。** 如果夹爪里存的运动安全包络（力矩和过热保护）和电机额定值不一致，脚本会在刷写
+之后把它改成额定值（EL05：cont 1.1 / peak 1.8 N·m），并在你确认刷写前提示：
+
+```text
+  envelope     : stored cont 1.000 / peak 2.000 N*m, will be set to cont 1.100 / peak 1.800 after flashing
+```
+
+行程标定和开合方向保持不变。加 `--keep-envelope` 可以不改包络。
+
+### 4. 断电重启并确认
+
+**断电重启**，等夹爪标定完（约 10 秒），然后运行：
+
+```bash
+python python/examples/follower_status.py left
+```
+
+`[motor fw]` 应显示新版本，例如 `MotorVersion(1.0.5.0.4, flash: host-written)`。版本已经记在
+夹爪里，之后在 MIT 下也能直接读到。
+
+## 出现问题时
+
+| 现象 | 处理方法 |
+| --- | --- |
+| `cannot tell the motor model from ...` | 镜像文件被改了名。恢复原文件名，或加 `--model EL05`。 |
+| `this gripper records a ... motor, the image is for ...` | 镜像对应的是另一种电机型号。不要强行刷写，请联系我们。 |
+| `follower firmware ... lacks the 0x5B relay` | 先升级夹爪固件（见"开始之前"）。 |
+| `motor OTA ...: no reply after N attempts` | 断电重启后再运行一遍同样的命令。中断的升级会从头开始，电机不会损坏。 |
+| 刷写后提示 `!! expected ...` | 断电重启后再运行一遍同样的命令。 |
+| 脚本中途停止，之后夹爪不再标定 | 电机还停在私有协议。运行 `python python/examples/motor_ota_update.py --to-mit left`，再断电重启。 |
+
+不刷写、只把电机切回 MIT：
+
+```bash
+python python/examples/motor_ota_update.py --to-mit left
+```
+
+然后断电重启。
+
+## 在自己的代码里调用
+
+这个脚本只是对 `xense.taccap.MotorOtaSession` 的简单封装：
+
+```python
+import xense.taccap as t
+
+g = t.FollowerGripper(t.find_left().mcu_device)
+m = g.motor
+# the motor must already be on the private protocol (see step 2)
+session = t.MotorOtaSession(m, m.get_can_id())
+session.preflight("EL05")                       # private protocol + recorded model
+session.update_from_file("EL05_1.0.5.0.4.bin", lambda done, total: None)
+m.set_motor_fw_version("1.0.5.0.4")             # record it for MIT reads
+m.switch_protocol(t.MotorProtocol.Mit)          # then power-cycle
+```
diff --git a/docs/MOTOR_OTA.md b/docs/MOTOR_OTA.md
new file mode 100644
index 0000000..9093951
--- /dev/null
+++ b/docs/MOTOR_OTA.md
@@ -0,0 +1,170 @@
+# Updating the follower's motor firmware
+
+> Chinese version: [MOTOR_OTA-zh.md](MOTOR_OTA-zh.md)
+
+The follower gripper carries a RobStride motor that runs its own firmware,
+separate from the gripper's MCU firmware. This guide updates the motor firmware
+over the gripper's USB-C cable with `python/examples/motor_ota_update.py`. The
+motor stays mounted.
+
+| Motor | Required motor firmware |
+| --- | --- |
+| EL05 | ≥ 1.0.5.0.4 |
+
+## Before you start
+
+- **Gripper firmware 1.2.16** (at least 1.2.8 for motor updates). Check it with
+  `follower_status.py` (the `[fw]` line). If it is older, update the gripper
+  firmware first with `ota_update.py` and power-cycle; a gripper firmware update
+  also resets the motor to its normal protocol, so it must come before the motor
+  update, never after.
+- **SDK 0.4.3 or newer**, installed so that `import xense.taccap` works.
+- **The motor firmware image** from us, for example `EL05_1.0.5.0.4.bin`. Keep the
+  file name as delivered: the script reads the motor model and version from it
+  and checks them against the image and the gripper.
+- **Nothing else using the gripper.** Stop your own programs first.
+- **Jaws clear.** After each power cycle the gripper opens and closes once to
+  calibrate.
+
+"Power-cycle" below always means: unplug the gripper's **24 V power cable** for
+about 2 seconds and plug it back. The USB cable can stay connected; the MCU and
+the motor both run from 24 V.
+
+## Why the command runs twice
+
+Our SDK drives the motor on the **MIT protocol**. The motor accepts firmware
+updates only on its **private protocol**, and a protocol change takes effect at
+the next power-up. So one update is:
+
+1. run the script: it switches the motor to the private protocol;
+2. power-cycle;
+3. run the same command again: it flashes, verifies, records the new version in
+   the gripper, sets the motion envelope to the motor's rating if it differs, and
+   switches the motor back to MIT;
+4. power-cycle.
+
+The private protocol is used only for the update. The gripper is back on MIT,
+ready for normal use, at the end.
+
+## Steps
+
+The examples assume the left follower; use `right` or the full serial number
+(for example `TCGU01A25Z0017s`) for another one.
+
+### 1. Check the current state
+
+```bash
+python python/examples/follower_status.py left
+```
+
+Look at `[fw]` (gripper firmware) and `[motor fw]` (motor firmware). The motor
+firmware may show as unreadable at this point; that is expected while the motor
+is on MIT and nothing has been recorded yet.
+
+### 2. First run: switch to the private protocol
+
+```bash
+python python/examples/motor_ota_update.py EL05_1.0.5.0.4.bin left
+```
+
+```text
+=== motor OTA, step 1 of 2 ===
+  the motor is on the MIT protocol and does not answer OTA frames there,
+  so it has to be switched to its private protocol first.
+Switch the motor to the private protocol? type 'yes': yes
+
+done. Now unplug the gripper's 24 V power cable for ~2 s and plug it back (USB may stay in),
+wait ~10 s, then run the same command again to flash.
+```
+
+**Power-cycle** and wait about 10 seconds. On the private protocol the motor
+stays disabled and the gripper does not calibrate; that is expected.
+
+### 3. Second run: flash
+
+```bash
+python python/examples/motor_ota_update.py EL05_1.0.5.0.4.bin left
+```
+
+```text
+=== motor OTA, step 2 of 2 ===
+  gripper      : TCGU01A25Z0017s  firmware FirmwareVersion(1.2.16.0)
+  motor        : EL05  can_id 1  uid ...
+  motor fw now : 1.0.5.0.2
+  image        : EL05_1.0.5.0.4.bin
+                 92,584 B, 11,573 packs, version 1.0.5.0.4
+  envelope     : at the motor's rating, unchanged
+Flash the MOTOR with this image? type 'yes': yes
+  [########################################] 100.0%  11,573/11,573
+=== done in 28s; waiting for the motor ===
+  recorded     : motor fw 1.0.5.0.4 in follower flash
+  motor fw     : 1.0.5.0.2 -> 1.0.5.0.4
+  switched the motor back to the MIT protocol.
+
+Done. Now unplug the gripper's 24 V power cable for ~2 s and plug it back (USB may stay in);
+the gripper auto-calibrates (~10 s, keep the jaws clear) and is ready to use.
+```
+
+Flashing takes about half a minute. Warnings like `motor OTA start: no reply
+(attempt 1/6)` at the start are normal: the motor restarts into its bootloader
+first and answers on a later attempt.
+
+**Motion envelope.** If the gripper's stored motion envelope (its torque and
+thermal protection) differs from the motor's rating, the script sets it to the
+rating after flashing (EL05: cont 1.1 / peak 1.8 N·m) and says so before you
+confirm:
+
+```text
+  envelope     : stored cont 1.000 / peak 2.000 N*m, will be set to cont 1.100 / peak 1.800 after flashing
+```
+
+The travel calibration and open direction are kept. Pass `--keep-envelope` to
+leave the envelope as it is.
+
+### 4. Power-cycle and check
+
+**Power-cycle** and let the gripper calibrate (about 10 seconds), then:
+
+```bash
+python python/examples/follower_status.py left
+```
+
+`[motor fw]` should show the new version, for example
+`MotorVersion(1.0.5.0.4, flash: host-written)`. The version is recorded in the
+gripper, so it stays readable on MIT from now on.
+
+## If something goes wrong
+
+| Symptom | What to do |
+| --- | --- |
+| `cannot tell the motor model from ...` | The image file was renamed. Restore the original name, or pass `--model EL05`. |
+| `this gripper records a ... motor, the image is for ...` | The image is for a different motor model. Do not override this; contact us. |
+| `follower firmware ... lacks the 0x5B relay` | Update the gripper firmware first (see *Before you start*). |
+| `motor OTA ...: no reply after N attempts` | Power-cycle and run the same command again. An interrupted update restarts from the beginning; the motor is not damaged. |
+| `!! expected ...` after flashing | Power-cycle and run the same command again. |
+| The script stopped and the gripper does not calibrate any more | The motor is still on the private protocol. Run `python python/examples/motor_ota_update.py --to-mit left`, then power-cycle. |
+
+To switch the motor back to MIT at any time without flashing:
+
+```bash
+python python/examples/motor_ota_update.py --to-mit left
+```
+
+then power-cycle.
+
+## Doing it from your own code
+
+The script is a thin wrapper around `xense.taccap.MotorOtaSession`:
+
+```python
+import xense.taccap as t
+
+g = t.FollowerGripper(t.find_left().mcu_device)
+m = g.motor
+# the motor must already be on the private protocol (see step 2)
+session = t.MotorOtaSession(m, m.get_can_id())
+session.preflight("EL05")                       # private protocol + recorded model
+session.update_from_file("EL05_1.0.5.0.4.bin", lambda done, total: None)
+m.set_motor_fw_version("1.0.5.0.4")             # record it for MIT reads
+m.switch_protocol(t.MotorProtocol.Mit)          # then power-cycle
+```
diff --git a/python/examples/motor_ota_update.py b/python/examples/motor_ota_update.py
index 9a2d941..500d0ae 100644
--- a/python/examples/motor_ota_update.py
+++ b/python/examples/motor_ota_update.py
@@ -1,27 +1,47 @@
 #!/usr/bin/env python3
 # Copyright (c) 2026 XenseRobotics Co., Ltd. — Apache-2.0
 """
-电机固件升级:刷 RobStride 电机模组**自己**的程序,经从爪 USB-C 串口。
-
-不是夹爪固件升级 —— 那是 ota_update.py。这里每一帧 CAN 都由从爪 MCU 经
-Motor.can_ext_xfer(0x5B)转发,所以需要从爪固件 >= 1.2.8。
-
-前提,缺一条就拒绝:
-  - 电机在**私有协议**下。MIT 下电机不回 OTA 帧(实测)。切过去:
-        motor.switch_protocol(MotorProtocol.Private),然后断电重插
-    (拔 24V 电源线约 2 秒再插回,USB 可不拔)。夹爪 OTA 会把电机切回 MIT,所以先刷夹爪、
-    再刷电机。
-  - 本机记录的电机型号与镜像一致。**RobStride 的 OTA 协议不校验型号**,
-    RS00 的包刷进 EL05 电机也会被接受。型号取自文件名前缀(rs00-/el05-),
-    可以用 --model 显式指定。
-  - 文件名里的版本号(如 rs00-0.0.3.32.bin)与镜像内嵌的版本字符串一致。
-
-刷完之后(0086s 首次实刷实测):电机重启回到 **MIT**,从爪 MCU 跟着切过去,
-所以刷完当场读不到版本(版本帧要私有协议)。断电重插一次,自动标定能跑完即说明
-电机在正常工作;要核对版本号,再切私有、断电、读。
-
-用法:
-    python python/examples/motor_ota_update.py ~/Downloads/rs00-0.0.3.32.bin TCGU01A28Z0086s
+Motor firmware update: reflash the RobStride motor's OWN firmware over the
+follower gripper's USB-C cable.
+
+This is not the gripper firmware update -- that is ota_update.py. Every CAN
+frame here is relayed by the follower MCU through Motor.can_ext_xfer (0x5B), so
+follower firmware >= 1.2.8 is required. Full procedure: docs/MOTOR_OTA.md.
+
+The motor answers OTA frames only on its PRIVATE protocol (measured: not on
+MIT), while the SDK normally runs it on MIT. So one update runs the same
+command twice, with a 24 V power cycle after each (USB may stay in):
+  1. First run: the motor is on MIT -> the script switches it to the private
+     protocol and exits. Power-cycle.
+  2. Second run: the motor is on the private protocol -> flash, verify, record
+     the new version in the follower's flash, and switch back to MIT.
+     Power-cycle; once auto-calibration finishes the gripper is ready to use.
+     (An RS00 comes back on MIT by itself after flashing; an EL05 stays on the
+     private protocol and the script switches it back.)
+If a run stops with the motor still on the private protocol, --to-mit switches
+it back.
+
+Checks before flashing; any failure refuses:
+  - The gripper's recorded motor model matches the image. RobStride's OTA
+    protocol does NOT check the model -- an RS00 image is accepted by an EL05
+    motor -- so the model comes from the file name prefix (rs00- / el05-, any
+    case, - or _) or from --model.
+  - The version in the file name matches the version string inside the image.
+    Versions are written the vendor's way: four parts for RS00
+    (rs00-0.0.3.32.bin), five for EL05 (EL05_1.0.5.0.4.bin -- the motor itself
+    answers the four bytes 10.5.0.4, and the vendor splits the 10 into "1.0").
+  - Flash the gripper firmware first: a gripper OTA switches the motor to MIT.
+
+After a successful flash the script also sets the motion envelope to the
+motor's rating (EL05 cont 1.1 / peak 1.8 N*m, FollowerGripper.ensure_envelope(),
+which writes flash only if the stored record differs). Early example scripts
+wrote other values (for example cont 1.0 / peak 2.0) and the device never
+corrects them itself. --keep-envelope skips this.
+
+Usage:
+    python python/examples/motor_ota_update.py EL05_1.0.5.0.4.bin left   # run twice
+    python python/examples/motor_ota_update.py rs00-0.0.3.32.bin TCGU01A28Z0086s
+    python python/examples/motor_ota_update.py --to-mit left             # back to MIT only
 """
 
 from __future__ import annotations
@@ -38,12 +58,20 @@
 
 KNOWN_MODELS = ("RS00", "EL05")
 MIN_FW = (1, 2, 8)
+POWER_CYCLE = (
+    "unplug the gripper's 24 V power cable for ~2 s and plug it back (USB may stay in)"
+)
+# A RobStride version as the vendor writes it: four parts (RS00 0.0.3.32) or
+# five (EL05 1.0.5.0.4, the vendor's split of a leading byte 10). Five first, so
+# an EL05 string is never cut down to its first four parts -- that is how the
+# first version of this script read EL05_1.0.5.0.4.bin as "1.0.5.0".
+_VERSION_RE = r"\d+(?:\.\d+){3,4}"
 
 
 def image_facts(path: str, data: bytes, model_arg: str | None):
     """(model, version) from the filename, cross-checked against the image."""
     name = os.path.basename(path)
-    m = re.match(r"(?i)(rs00|el05)[-_](\d+\.\d+\.\d+\.\d+)\.bin$", name)
+    m = re.match(r"(?i)(rs00|el05)[-_](" + _VERSION_RE + r")\.bin$", name)
     model = (model_arg or (m.group(1) if m else "")).upper()
     if model not in KNOWN_MODELS:
         sys.exit(
@@ -51,7 +79,14 @@ def image_facts(path: str, data: bytes, model_arg: str | None):
             f"({'/'.join(KNOWN_MODELS)})"
         )
     version = m.group(2) if m else None
-    embedded = sorted({v.decode() for v in re.findall(rb"\d+\.\d+\.\d+\.\d+", data)})
+    embedded = sorted(
+        {
+            v.decode()
+            for v in re.findall(
+                rb"(?<![\d.])" + _VERSION_RE.encode() + rb"(?![\d.])", data
+            )
+        }
+    )
     if version is not None and embedded and version not in embedded:
         sys.exit(f"error: filename says {version}, the image contains {embedded}")
     return model, version or (embedded[0] if len(embedded) == 1 else None)
@@ -65,24 +100,64 @@ def read_version(motor, timeout_s: float = 20.0):
             # Live reads only: follower >= 1.2.14 answers from its flash record
             # when the motor is silent, and that would be the OLD version.
             if v.valid and not getattr(v, "from_flash", False):
-                return ".".join(str(x) for x in v.version)
+                # Vendor form, so it compares with the image's version: an EL05
+                # answers bytes 10.5.0.4 and the image says 1.0.5.0.4.
+                return v.vendor_str
         except Exception:  # the motor is restarting; keep asking
             pass
         time.sleep(1.0)
     return None
 
 
+def repair_envelope(g) -> None:
+    """Set the motion envelope to the motor's rating. Never fails the update."""
+    try:
+        w = g.ensure_envelope()
+        if w.wrote:
+            e = w.written
+            print(
+                f"  envelope     : set to cont {e.cont_torque_nm:.3f} / peak "
+                f"{e.peak_torque_nm:.3f} N*m (takes effect after the power cycle)"
+            )
+    except Exception as exc:  # the motor update itself already succeeded
+        print(
+            f"  envelope     : NOT repaired ({exc}); run impedance_control.py --set-envelope"
+        )
+
+
+def confirm(question: str, assume_yes: bool) -> bool:
+    if assume_yes:
+        return True
+    return input(f"{question} type 'yes': ").strip() == "yes"
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
-    ap.add_argument("image", help="RobStride motor firmware .bin")
+    ap.add_argument("image", nargs="?", help="RobStride motor firmware .bin")
     add_target_argument(ap, required=True)
     ap.add_argument("--model", help="override the model taken from the filename")
-    ap.add_argument("--yes", action="store_true", help="do not ask before flashing")
+    ap.add_argument(
+        "--yes", action="store_true", help="do not ask before switching or flashing"
+    )
+    ap.add_argument(
+        "--keep-envelope",
+        action="store_true",
+        help="do not repair the motion envelope after flashing",
+    )
+    ap.add_argument(
+        "--to-mit",
+        action="store_true",
+        help="only switch the motor back to the MIT protocol (no flashing)",
+    )
     args = ap.parse_args()
 
-    with open(args.image, "rb") as f:
-        data = f.read()
-    model, version = image_facts(args.image, data, args.model)
+    if not args.to_mit and not args.image:
+        ap.error("an image is required (or pass --to-mit)")
+    data = model = version = None
+    if not args.to_mit:
+        with open(args.image, "rb") as f:
+            data = f.read()
+        model, version = image_facts(args.image, data, args.model)
 
     ep, _, _ = resolve_target(args.target)
     if not ep.firmware_sn.endswith("s"):
@@ -99,12 +174,41 @@ def main() -> int:
         )
 
     motor = g.motor
+    proto = motor.get_protocol()
+
+    if args.to_mit:
+        if proto == MotorProtocol.Mit:
+            print("the motor is already on the MIT protocol; nothing to do")
+            return 0
+        motor.switch_protocol(MotorProtocol.Mit)
+        print(f"switched the motor to MIT. Now {POWER_CYCLE};")
+        print(
+            "the gripper auto-calibrates (~10 s, keep the jaws clear) and is ready to use."
+        )
+        return 0
+
+    # Step 1 of 2: the motor answers OTA frames only on its private protocol.
+    if proto != MotorProtocol.Private:
+        print("=== motor OTA, step 1 of 2 ===")
+        print(f"  gripper      : {ep.firmware_sn}  firmware {fw}")
+        print(
+            "  the motor is on the MIT protocol and does not answer OTA frames there,"
+        )
+        print("  so it has to be switched to its private protocol first.")
+        if not confirm("Switch the motor to the private protocol?", args.yes):
+            print("aborted, nothing changed")
+            return 1
+        motor.switch_protocol(MotorProtocol.Private)
+        print(f"\ndone. Now {POWER_CYCLE},")
+        print("wait ~10 s, then run the same command again to flash.")
+        return 0
+
     session = MotorOtaSession(motor, motor.get_can_id())
     session.preflight(model)  # private protocol + recorded model, raises otherwise
     before = read_version(motor, 5.0)
     uid = session.read_uid()
 
-    print("=== motor OTA ===")
+    print("=== motor OTA, step 2 of 2 ===")
     print(f"  gripper      : {ep.firmware_sn}  firmware {fw}")
     print(f"  motor        : {model}  can_id {motor.get_can_id()}  uid {uid.hex()}")
     print(f"  motor fw now : {before or 'unknown'}")
@@ -113,12 +217,25 @@ def main() -> int:
         f"                 {len(data):,} B, {(len(data) + 7) // 8:,} packs, "
         f"version {version or 'unknown'}"
     )
+    fix_envelope = False
+    if not args.keep_envelope:
+        audit = g.audit_envelope()
+        fix_envelope = audit.needs_write
+        if fix_envelope:
+            rec = audit.recommended
+            print(
+                f"  envelope     : stored cont {audit.stored.cont_torque_nm:.3f} / peak "
+                f"{audit.stored.peak_torque_nm:.3f} N*m, will be set to cont "
+                f"{rec.cont_torque_nm:.3f} / peak {rec.peak_torque_nm:.3f} after flashing"
+            )
+        else:
+            print("  envelope     : at the motor's rating, unchanged")
     if before and version and before == version:
         print("  note         : same version as installed -- this is a reflash")
-    if not args.yes:
-        if input("Flash the MOTOR with this image? type 'yes': ").strip() != "yes":
-            print("aborted, nothing sent")
-            return 1
+    if not confirm("Flash the MOTOR with this image?", args.yes):
+        print("aborted, nothing sent. The motor is still on the private protocol;")
+        print("run with --to-mit to switch it back.")
+        return 1
 
     t0 = time.monotonic()
 
@@ -133,6 +250,8 @@ def progress(done, total):
     # Record the new version in the follower's flash (0x5C, follower >= 1.2.14),
     # so motor_version() reports it once the motor is back on MIT -- where the
     # motor itself cannot answer. The image's own version is what was flashed.
+    if fix_envelope:
+        repair_envelope(g)
     if version:
         try:
             motor.set_motor_fw_version(version)
@@ -145,26 +264,30 @@ def progress(done, total):
     # answer" says nothing about whether the update took.
     time.sleep(3.0)
     if motor.get_protocol() != MotorProtocol.Private:
+        # RS00 (0086s): the update restarts the motor on MIT and the MCU
+        # follows, so the version frame cannot be read here.
+        print("  the motor restarted on the MIT protocol by itself.")
         print(
-            "  the motor restarted on the MIT protocol (seen before: the update "
-            "resets it),\n  so its version cannot be read here. Power-cycle "
-            "(cut 24 V for ~2 s; USB may stay in);\n  if auto-calibration completes the motor is "
-            "running. To confirm the version,\n  switch_protocol(Private), "
-            f"power-cycle, and expect {version or 'the new version'}."
+            f"\nNow {POWER_CYCLE}; the gripper auto-calibrates (~10 s, keep the jaws clear)."
         )
+        print("follower_status.py then shows the recorded motor firmware version.")
         return 0
     after = read_version(motor)
     print(f"  motor fw     : {before or '?'} -> {after or 'no answer'}")
     if version and after != version:
         print(
-            f"!! expected {version}. Power-cycle (cut 24 V for ~2 s) and read again "
-            "before drawing conclusions."
+            f"!! expected {version}. The motor stays on the private protocol so you can"
+        )
+        print(
+            f"   {POWER_CYCLE} and run the same command again. Use --to-mit to give up."
         )
         return 2
+    # EL05 (0017s): the motor stays on the private protocol after the update.
+    motor.switch_protocol(MotorProtocol.Mit)
+    print("  switched the motor back to the MIT protocol.")
+    print(f"\nDone. Now {POWER_CYCLE};")
     print(
-        "\nThe motor is on the PRIVATE protocol. To use the gripper, switch it "
-        "back:\n    motor.switch_protocol(MotorProtocol.Mit)\nthen power-cycle "
-        "(cut 24 V for ~2 s; USB may stay in)."
+        "the gripper auto-calibrates (~10 s, keep the jaws clear) and is ready to use."
     )
     return 0
 
diff --git a/python/tests/test_motor_ota_update.py b/python/tests/test_motor_ota_update.py
new file mode 100644
index 0000000..4871223
--- /dev/null
+++ b/python/tests/test_motor_ota_update.py
@@ -0,0 +1,233 @@
+"""motor_ota_update.py without hardware: image identification and the two-run
+flow (switch to private, flash, repair the envelope, back to MIT).
+
+The script's module-level imports are satisfied by stubs that are torn down
+again right after loading -- see the note in test_ota_update_all.py on why a
+stub left in sys.modules masks failures in other test modules.
+"""
+
+import importlib.util
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+xense = types.ModuleType("xense")
+taccap = types.ModuleType("xense.taccap")
+
+
+class MotorProtocol:
+    Mit = "mit"
+    Private = "private"
+
+
+class _StubGripper:
+    pass
+
+
+class _StubSession:
+    pass
+
+
+taccap.MotorProtocol = MotorProtocol
+taccap.FollowerGripper = _StubGripper
+taccap.MotorOtaSession = _StubSession
+
+_target = types.ModuleType("_target")
+_target.add_target_argument = lambda ap, required=False: ap.add_argument(
+    "target", nargs=None if required else "?"
+)
+_target.resolve_target = lambda target: (None, False, [])
+
+ROOT = Path(__file__).resolve().parents[1]
+SPEC = importlib.util.spec_from_file_location(
+    "motor_ota_update_example", ROOT / "examples" / "motor_ota_update.py"
+)
+_STUBS = {"xense": xense, "xense.taccap": taccap, "_target": _target}
+_SAVED = {name: sys.modules.get(name) for name in _STUBS}
+sys.modules.update(_STUBS)
+try:
+    mod = importlib.util.module_from_spec(SPEC)
+    SPEC.loader.exec_module(mod)
+finally:
+    for name, previous in _SAVED.items():
+        if previous is None:
+            sys.modules.pop(name, None)
+        else:
+            sys.modules[name] = previous
+
+
+# ---------------------------------------------------------------------------
+# Image identification
+# ---------------------------------------------------------------------------
+
+
+def test_el05_five_part_version_is_read_from_name_and_image():
+    """EL05 versions have five parts; the first cut kept four ("1.0.5.0")."""
+    data = b"\x00junk EL05 app 1.0.5.0.4 build\x00"
+    assert mod.image_facts("EL05_1.0.5.0.4.bin", data, None) == ("EL05", "1.0.5.0.4")
+
+
+def test_rs00_four_part_version_still_works():
+    data = b"\x00RS00 0.0.3.32\x00"
+    assert mod.image_facts("rs00-0.0.3.32.bin", data, None) == ("RS00", "0.0.3.32")
+
+
+def test_renamed_image_takes_its_version_from_the_content():
+    data = b"\x00 1.0.5.0.4 \x00"
+    assert mod.image_facts("motor.bin", data, "EL05") == ("EL05", "1.0.5.0.4")
+
+
+def test_name_and_content_disagreeing_is_refused():
+    with pytest.raises(SystemExit):
+        mod.image_facts("EL05_1.0.5.0.4.bin", b"\x00 1.0.5.0.2 \x00", None)
+
+
+def test_unknown_model_is_refused():
+    with pytest.raises(SystemExit):
+        mod.image_facts("motor.bin", b"\x00 1.0.5.0.4 \x00", None)
+
+
+# ---------------------------------------------------------------------------
+# The two-run flow
+# ---------------------------------------------------------------------------
+
+
+class FakeVersion:
+    def __init__(self, vendor, from_flash=False):
+        self.valid = True
+        self.vendor_str = vendor
+        self.from_flash = from_flash
+        self.version = tuple(int(x) for x in vendor.split("."))
+
+
+class FakeEnvelope:
+    def __init__(self, cont, peak):
+        self.cont_torque_nm = cont
+        self.peak_torque_nm = peak
+
+
+class FakeAudit:
+    def __init__(self, needs_write):
+        self.needs_write = needs_write
+        self.stored = FakeEnvelope(1.0, 2.0)
+        self.recommended = FakeEnvelope(1.1, 1.8)
+
+
+class FakeMotor:
+    def __init__(self, protocol, version="1.0.5.0.2"):
+        self.protocol = protocol
+        self.version = version
+        self.switches = []
+        self.recorded = None
+
+    def get_protocol(self):
+        return self.protocol
+
+    def switch_protocol(self, p):
+        self.switches.append(p)
+
+    def get_can_id(self):
+        return 1
+
+    def motor_version(self, timeout_ms=0):
+        return FakeVersion(self.version)
+
+    def set_motor_fw_version(self, v):
+        self.recorded = v
+
+
+class FakeGripper:
+    def __init__(self, motor, needs_envelope):
+        self.motor = motor
+        self.firmware_version = types.SimpleNamespace(major=1, minor=2, patch=16)
+        self._needs = needs_envelope
+        self.envelope_writes = 0
+
+    def audit_envelope(self):
+        return FakeAudit(self._needs)
+
+    def ensure_envelope(self):
+        self.envelope_writes += 1
+        return types.SimpleNamespace(wrote=True, written=FakeEnvelope(1.1, 1.8))
+
+
+class FakeSession:
+    def __init__(self, motor, can_id):
+        self.motor = motor
+
+    def preflight(self, model):
+        assert model == "EL05"
+
+    def read_uid(self):
+        return bytes(8)
+
+    def update_from_bytes(self, data, progress):
+        self.motor.version = "1.0.5.0.4"  # what the motor answers after flashing
+        progress(1, 1)
+
+
+@pytest.fixture
+def run(monkeypatch, tmp_path):
+    image = tmp_path / "EL05_1.0.5.0.4.bin"
+    image.write_bytes(b"\x00 1.0.5.0.4 \x00")
+    endpoint = types.SimpleNamespace(
+        firmware_sn="TCGU01A25Z0017s", mcu_device="/dev/fake"
+    )
+    monkeypatch.setattr(mod, "resolve_target", lambda target: (endpoint, False, []))
+    monkeypatch.setattr(mod, "MotorOtaSession", FakeSession)
+    monkeypatch.setattr(mod.time, "sleep", lambda s: None)
+
+    def _run(motor, *argv, needs_envelope=False):
+        gripper = FakeGripper(motor, needs_envelope)
+        monkeypatch.setattr(mod, "FollowerGripper", lambda mcu_device: gripper)
+        args = [a if a != "IMAGE" else str(image) for a in argv]
+        monkeypatch.setattr(sys, "argv", ["motor_ota_update.py", *args])
+        return mod.main(), gripper
+
+    return _run
+
+
+def test_first_run_on_mit_switches_to_private_and_flashes_nothing(run):
+    motor = FakeMotor(MotorProtocol.Mit)
+    rc, g = run(motor, "IMAGE", "left", "--yes")
+    assert rc == 0
+    assert motor.switches == [MotorProtocol.Private]
+    assert motor.recorded is None and g.envelope_writes == 0
+
+
+def test_second_run_flashes_records_repairs_envelope_and_returns_to_mit(run):
+    motor = FakeMotor(MotorProtocol.Private)
+    rc, g = run(motor, "IMAGE", "left", "--yes", needs_envelope=True)
+    assert rc == 0
+    assert motor.recorded == "1.0.5.0.4"
+    assert g.envelope_writes == 1
+    assert motor.switches == [MotorProtocol.Mit]
+
+
+def test_envelope_at_rating_is_not_written(run):
+    motor = FakeMotor(MotorProtocol.Private)
+    rc, g = run(motor, "IMAGE", "left", "--yes", needs_envelope=False)
+    assert rc == 0 and g.envelope_writes == 0
+
+
+def test_keep_envelope_skips_the_repair(run):
+    motor = FakeMotor(MotorProtocol.Private)
+    rc, g = run(motor, "IMAGE", "left", "--yes", "--keep-envelope", needs_envelope=True)
+    assert rc == 0 and g.envelope_writes == 0
+
+
+def test_version_mismatch_after_flash_stays_on_private(run, monkeypatch):
+    motor = FakeMotor(MotorProtocol.Private)
+    monkeypatch.setattr(FakeSession, "update_from_bytes", lambda self, d, p: None)
+    rc, _ = run(motor, "IMAGE", "left", "--yes")
+    assert rc == 2
+    assert motor.switches == []  # left on private so the user can retry
+
+
+def test_to_mit_only_switches_back(run):
+    motor = FakeMotor(MotorProtocol.Private)
+    rc, g = run(motor, "--to-mit", "left")
+    assert rc == 0
+    assert motor.switches == [MotorProtocol.Mit] and g.envelope_writes == 0

From c1a37ab214fa014f75b79f3fdf9b552f8cb44c2b Mon Sep 17 00:00:00 2001
From: Vertax42 <1007644658@qq.com>
Date: Sun, 18 Oct 2026 14:24:52 +0800
Subject: [PATCH 3/4] =?UTF-8?q?fix(examples):=20=E7=94=B5=E6=9C=BA=20OTA?=
 =?UTF-8?q?=20=E5=8F=AA=E5=9C=A8=E6=A0=B8=E5=AF=B9=E9=80=9A=E8=BF=87?=
 =?UTF-8?q?=E5=90=8E=E8=AE=B0=E5=BD=95=E7=89=88=E6=9C=AC;=E8=A1=A5?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E7=B4=A2=E5=BC=95=E4=B8=8E=20CHANGELOG?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- EL05 刷后先读回核对，一致才写 0x5C 记录;失败不留错误记录
- RS00 刷后回到 MIT 无法读回，仍按镜像版本记录(新增离线测试)
- MOTOR_OTA 文档 SDK 要求改为 0.4.4,README 加入口链接
- CLAUDE.md:0017s 回刷复现记录;英文注释与 -zh.md 命名规则

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                          | 21 +++++++++++++++++++++
 README.md                             |  4 +++-
 docs/MOTOR_OTA-zh.md                  |  4 ++--
 docs/MOTOR_OTA.md                     |  4 ++--
 python/examples/motor_ota_update.py   | 27 ++++++++++++++++++---------
 python/tests/test_motor_ota_update.py | 14 ++++++++++++++
 6 files changed, 60 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 14bcf7d..83712b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **`motor_ota_update.py` mis-read EL05 images.** EL05 versions have five
+  parts (`1.0.5.0.4`); the example kept four and compared the motor's raw
+  bytes (`10.5.0.4`), so a good flash was reported as a mismatch. It now
+  parses five-part versions and compares the vendor spelling.
+
+### Added
+
+- **`motor_ota_update.py` runs as two passes of the same command**: the first
+  switches the motor to its private protocol, the second (after a 24 V power
+  cycle) flashes, verifies, records the version in the follower (0x5C) and
+  switches back to MIT. The version is recorded only after the motor confirmed
+  it, or blind when the motor returned to MIT by itself (RS00). `--to-mit`
+  switches back without flashing.
+- **The motor OTA sets the motion envelope to the motor's rating** when it
+  differs (`ensure_envelope()`); travel calibration and open direction are
+  kept. `--keep-envelope` skips it.
+- **`docs/MOTOR_OTA.md`** (and `MOTOR_OTA-zh.md`): customer guide to updating
+  the motor firmware over USB-C.
+
 ### Changed
 
 - **Chinese documents are named `<NAME>-zh.md`.** `README_CN.md` is now
diff --git a/README.md b/README.md
index 8b777be..4257112 100644
--- a/README.md
+++ b/README.md
@@ -345,7 +345,8 @@ looking healthy while it drops status frames.
 `FollowerGripper` refuses followers below firmware 1.2.5. Leader and follower
 firmware are versioned independently. Required motor firmware: EL05 ≥ 1.0.5.0.4,
 RS00 ≥ 0.0.3.32. Image table, motor model, RS00 setup and motor OTA:
-[firmware/README.md](firmware/README.md).
+[firmware/README.md](firmware/README.md). Step-by-step motor firmware update:
+[docs/MOTOR_OTA.md](docs/MOTOR_OTA.md) ([中文](docs/MOTOR_OTA-zh.md)).
 
 ### Checking versions
 
@@ -380,6 +381,7 @@ Logs: every process writes a DEBUG log to `~/.taccaplogs/session_*.log`
 
 - [docs/USAGE.md](docs/USAGE.md) ([中文](docs/USAGE-zh.md)) — end-to-end bring-up of gripper, wrist camera and tactile sensor
 - [docs/INSTALL.md](docs/INSTALL.md) — build options, C++-only builds, environment traps
+- [docs/MOTOR_OTA.md](docs/MOTOR_OTA.md) ([中文](docs/MOTOR_OTA-zh.md)) — updating the follower's motor firmware over USB-C
 - [docs/CALIBRATION.md](docs/CALIBRATION.md) — encoder zero, travel span, fisheye intrinsics
 - [docs/EXAMPLES.md](docs/EXAMPLES.md) — every example script and controller parameter
 - [firmware/README.md](firmware/README.md) — firmware images, flashing, motor setup
diff --git a/docs/MOTOR_OTA-zh.md b/docs/MOTOR_OTA-zh.md
index 67fae58..25c9ced 100644
--- a/docs/MOTOR_OTA-zh.md
+++ b/docs/MOTOR_OTA-zh.md
@@ -14,7 +14,7 @@
 - **夹爪固件 1.2.16**（升级电机至少需要 1.2.8）。用 `follower_status.py` 查看，看 `[fw]`
   那一行。如果版本较旧，先用 `ota_update.py` 升级夹爪固件并断电重启。升级夹爪固件会把电机切回
   常规协议，所以必须先升级夹爪、再升级电机，顺序不能反。
-- **SDK 0.4.3 或更新版本**，并且 `import xense.taccap` 能正常导入。
+- **SDK 0.4.4 或更新版本**，并且 `import xense.taccap` 能正常导入。
 - **我们提供的电机固件镜像**，例如 `EL05_1.0.5.0.4.bin`。请保持原文件名：脚本会从文件名读出
   电机型号和版本，并与镜像内容和夹爪记录核对。
 - **没有别的程序在使用夹爪。** 先停掉你自己的程序。
@@ -84,8 +84,8 @@ python python/examples/motor_ota_update.py EL05_1.0.5.0.4.bin left
 Flash the MOTOR with this image? type 'yes': yes
   [########################################] 100.0%  11,573/11,573
 === done in 28s; waiting for the motor ===
-  recorded     : motor fw 1.0.5.0.4 in follower flash
   motor fw     : 1.0.5.0.2 -> 1.0.5.0.4
+  recorded     : motor fw 1.0.5.0.4 in follower flash
   switched the motor back to the MIT protocol.
 
 Done. Now unplug the gripper's 24 V power cable for ~2 s and plug it back (USB may stay in);
diff --git a/docs/MOTOR_OTA.md b/docs/MOTOR_OTA.md
index 9093951..ebe48c8 100644
--- a/docs/MOTOR_OTA.md
+++ b/docs/MOTOR_OTA.md
@@ -18,7 +18,7 @@ motor stays mounted.
   firmware first with `ota_update.py` and power-cycle; a gripper firmware update
   also resets the motor to its normal protocol, so it must come before the motor
   update, never after.
-- **SDK 0.4.3 or newer**, installed so that `import xense.taccap` works.
+- **SDK 0.4.4 or newer**, installed so that `import xense.taccap` works.
 - **The motor firmware image** from us, for example `EL05_1.0.5.0.4.bin`. Keep the
   file name as delivered: the script reads the motor model and version from it
   and checks them against the image and the gripper.
@@ -97,8 +97,8 @@ python python/examples/motor_ota_update.py EL05_1.0.5.0.4.bin left
 Flash the MOTOR with this image? type 'yes': yes
   [########################################] 100.0%  11,573/11,573
 === done in 28s; waiting for the motor ===
-  recorded     : motor fw 1.0.5.0.4 in follower flash
   motor fw     : 1.0.5.0.2 -> 1.0.5.0.4
+  recorded     : motor fw 1.0.5.0.4 in follower flash
   switched the motor back to the MIT protocol.
 
 Done. Now unplug the gripper's 24 V power cable for ~2 s and plug it back (USB may stay in);
diff --git a/python/examples/motor_ota_update.py b/python/examples/motor_ota_update.py
index 500d0ae..48188bc 100644
--- a/python/examples/motor_ota_update.py
+++ b/python/examples/motor_ota_update.py
@@ -109,6 +109,19 @@ def read_version(motor, timeout_s: float = 20.0):
     return None
 
 
+def record_version(motor, version) -> None:
+    """Record the flashed version in the follower's flash (0x5C, follower >=
+    1.2.14), so motor_version() reports it on MIT, where the motor itself
+    cannot answer."""
+    if not version:
+        return
+    try:
+        motor.set_motor_fw_version(version)
+        print(f"  recorded     : motor fw {version} in follower flash")
+    except Exception as exc:  # older follower firmware has no 0x5C
+        print(f"  not recorded : {exc}")
+
+
 def repair_envelope(g) -> None:
     """Set the motion envelope to the motor's rating. Never fails the update."""
     try:
@@ -247,17 +260,8 @@ def progress(done, total):
     session.update_from_bytes(data, progress)
     print(f"\n=== done in {time.monotonic() - t0:.1f}s; waiting for the motor ===")
 
-    # Record the new version in the follower's flash (0x5C, follower >= 1.2.14),
-    # so motor_version() reports it once the motor is back on MIT -- where the
-    # motor itself cannot answer. The image's own version is what was flashed.
     if fix_envelope:
         repair_envelope(g)
-    if version:
-        try:
-            motor.set_motor_fw_version(version)
-            print(f"  recorded     : motor fw {version} in follower flash")
-        except Exception as exc:  # older follower firmware has no 0x5C
-            print(f"  not recorded : {exc}")
 
     # Measured on the first real flash: the motor restarts on MIT, and the MCU
     # follows it there. The version frame needs private, so under MIT "no
@@ -267,6 +271,8 @@ def progress(done, total):
         # RS00 (0086s): the update restarts the motor on MIT and the MCU
         # follows, so the version frame cannot be read here.
         print("  the motor restarted on the MIT protocol by itself.")
+        # Nothing to verify against here, so the image's version is recorded.
+        record_version(motor, version)
         print(
             f"\nNow {POWER_CYCLE}; the gripper auto-calibrates (~10 s, keep the jaws clear)."
         )
@@ -282,6 +288,9 @@ def progress(done, total):
             f"   {POWER_CYCLE} and run the same command again. Use --to-mit to give up."
         )
         return 2
+    # Recorded only once the motor confirmed it: a record that outlives a failed
+    # flash would make every later MIT read report the wrong version.
+    record_version(motor, version)
     # EL05 (0017s): the motor stays on the private protocol after the update.
     motor.switch_protocol(MotorProtocol.Mit)
     print("  switched the motor back to the MIT protocol.")
diff --git a/python/tests/test_motor_ota_update.py b/python/tests/test_motor_ota_update.py
index 4871223..dcc1d51 100644
--- a/python/tests/test_motor_ota_update.py
+++ b/python/tests/test_motor_ota_update.py
@@ -224,6 +224,20 @@ def test_version_mismatch_after_flash_stays_on_private(run, monkeypatch):
     rc, _ = run(motor, "IMAGE", "left", "--yes")
     assert rc == 2
     assert motor.switches == []  # left on private so the user can retry
+    assert motor.recorded is None  # a failed flash must not be recorded
+
+
+def test_motor_back_on_mit_after_flash_records_the_image_version(run, monkeypatch):
+    """RS00: the motor restarts on MIT, so its version cannot be read back."""
+    motor = FakeMotor(MotorProtocol.Private)
+
+    def flash(self, data, progress):
+        self.motor.protocol = MotorProtocol.Mit
+
+    monkeypatch.setattr(FakeSession, "update_from_bytes", flash)
+    rc, _ = run(motor, "IMAGE", "left", "--yes")
+    assert rc == 0
+    assert motor.recorded == "1.0.5.0.4" and motor.switches == []
 
 
 def test_to_mit_only_switches_back(run):

From 3109e2ba5ff75df7beed67d996acdaf1d65b52a7 Mon Sep 17 00:00:00 2001
From: Vertax42 <1007644658@qq.com>
Date: Sun, 18 Oct 2026 14:28:49 +0800
Subject: [PATCH 4/4] =?UTF-8?q?docs(changelog):=20=E7=94=B5=E6=9C=BA=20OTA?=
 =?UTF-8?q?=20=E4=BF=AE=E5=A4=8D=E5=B9=B6=E5=85=A5=200.4.3(=E7=A7=BB?=
 =?UTF-8?q?=E5=8A=A8=20tag,=E4=B8=8D=E5=8D=87=E7=89=88=E6=9C=AC)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md         | 44 +++++++++++++++++++-------------------------
 docs/MOTOR_OTA-zh.md |  2 +-
 docs/MOTOR_OTA.md    |  2 +-
 3 files changed, 21 insertions(+), 27 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 83712b8..7959772 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,37 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.3] - 2026-10-10
+
+_The `v0.4.3` tag was moved on 2026-10-18 to include the EL05 motor OTA
+fix and docs below; the version number is unchanged._
+
 ### Fixed
 
 - **`motor_ota_update.py` mis-read EL05 images.** EL05 versions have five
   parts (`1.0.5.0.4`); the example kept four and compared the motor's raw
   bytes (`10.5.0.4`), so a good flash was reported as a mismatch. It now
   parses five-part versions and compares the vendor spelling.
-
-### Added
-
-- **`motor_ota_update.py` runs as two passes of the same command**: the first
-  switches the motor to its private protocol, the second (after a 24 V power
-  cycle) flashes, verifies, records the version in the follower (0x5C) and
-  switches back to MIT. The version is recorded only after the motor confirmed
-  it, or blind when the motor returned to MIT by itself (RS00). `--to-mit`
-  switches back without flashing.
-- **The motor OTA sets the motion envelope to the motor's rating** when it
-  differs (`ensure_envelope()`); travel calibration and open direction are
-  kept. `--keep-envelope` skips it.
-- **`docs/MOTOR_OTA.md`** (and `MOTOR_OTA-zh.md`): customer guide to updating
-  the motor firmware over USB-C.
-
-### Changed
-
-- **Chinese documents are named `<NAME>-zh.md`.** `README_CN.md` is now
-  `README-zh.md` and `docs/USAGE_CN.md` is `docs/USAGE-zh.md`; links inside the
-  repository are updated. English files stay authoritative.
-
-## [0.4.3] - 2026-10-10
-
-### Fixed
-
 - **Force-position could not close a left-hand RS00 follower to 0.0.** Root
   cause (0089s, diagnostic firmware, 2026-10-10): a RobStride motor takes an MIT
   motion frame whose byte 0 equals its own CAN ID for another command and
@@ -53,6 +33,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`motor_ota_update.py` runs as two passes of the same command**: the first
+  switches the motor to its private protocol, the second (after a 24 V power
+  cycle) flashes, verifies, records the version in the follower (0x5C) and
+  switches back to MIT. The version is recorded only after the motor confirmed
+  it, or blind when the motor returned to MIT by itself (RS00). `--to-mit`
+  switches back without flashing.
+- **The motor OTA sets the motion envelope to the motor's rating** when it
+  differs (`ensure_envelope()`); travel calibration and open direction are
+  kept. `--keep-envelope` skips it.
+- **`docs/MOTOR_OTA.md`** (and `MOTOR_OTA-zh.md`): customer guide to updating
+  the motor firmware over USB-C.
 - **RS00 followers use motor CAN ID 17 (left) / 18 (right).**
   `detail::expected_motor_can_id(model_id, side)` (Python
   `expected_motor_can_id`) is the rule; `FollowerGripper` warns on open when the
@@ -76,6 +67,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **Chinese documents are named `<NAME>-zh.md`.** `README_CN.md` is now
+  `README-zh.md` and `docs/USAGE_CN.md` is `docs/USAGE-zh.md`; links inside the
+  repository are updated. English files stay authoritative.
 - Shipped follower image is now **1.2.16** (was 1.2.14 in 0.4.2; leader
   unchanged at 1.2.6). It carries 1.2.15: an RS00's open direction follows the
   side in its firmware SN, auto-calibration corrects a stored direction that
diff --git a/docs/MOTOR_OTA-zh.md b/docs/MOTOR_OTA-zh.md
index 25c9ced..5fd3be4 100644
--- a/docs/MOTOR_OTA-zh.md
+++ b/docs/MOTOR_OTA-zh.md
@@ -14,7 +14,7 @@
 - **夹爪固件 1.2.16**（升级电机至少需要 1.2.8）。用 `follower_status.py` 查看，看 `[fw]`
   那一行。如果版本较旧，先用 `ota_update.py` 升级夹爪固件并断电重启。升级夹爪固件会把电机切回
   常规协议，所以必须先升级夹爪、再升级电机，顺序不能反。
-- **SDK 0.4.4 或更新版本**，并且 `import xense.taccap` 能正常导入。
+- **SDK 0.4.3 或更新版本**，并且 `import xense.taccap` 能正常导入。
 - **我们提供的电机固件镜像**，例如 `EL05_1.0.5.0.4.bin`。请保持原文件名：脚本会从文件名读出
   电机型号和版本，并与镜像内容和夹爪记录核对。
 - **没有别的程序在使用夹爪。** 先停掉你自己的程序。
diff --git a/docs/MOTOR_OTA.md b/docs/MOTOR_OTA.md
index ebe48c8..e256b4a 100644
--- a/docs/MOTOR_OTA.md
+++ b/docs/MOTOR_OTA.md
@@ -18,7 +18,7 @@ motor stays mounted.
   firmware first with `ota_update.py` and power-cycle; a gripper firmware update
   also resets the motor to its normal protocol, so it must come before the motor
   update, never after.
-- **SDK 0.4.4 or newer**, installed so that `import xense.taccap` works.
+- **SDK 0.4.3 or newer**, installed so that `import xense.taccap` works.
 - **The motor firmware image** from us, for example `EL05_1.0.5.0.4.bin`. Keep the
   file name as delivered: the script reads the motor model and version from it
   and checks them against the image and the gripper.