锁定mavsdk<4: v4为全新原生API与经典gRPC API不兼容

树莓派实测mavsdk 4.0.0无mavsdk.offboard/System/telemetry(LegacyModuleError),
且其原生库libcmavsdk.so有libstdc++符号问题; 3.x(最新3.17.4, aarch64 wheel可用)
为gRPC架构内嵌mavsdk_server, 无此问题。同步更新两份requirements与部署文档§2/§3

docs/树莓派4B部署注意事项.md

@@ -32,9 +32,9 @@
 
 ```text
 # requirements-pod.txt(桥接最小集)
-mavsdk
+mavsdk<4    # ⚠ 锁版本,原因见 §3
 pyserial
-pytest    # 仅上机自测需要,部署运行可省
+pytest      # 仅上机自测需要,部署运行可省
 ```
 
 - `pod_bridge` 本身纯 Python + 惰性导入:`pyserial` 只在 `PodSerial` 实例化时加载,
@@ -46,29 +46,24 @@ pytest    # 仅上机自测需要,部署运行可省
 
 ## 3. MAVSDK 在 ARM 上的坑
 
-- pip 的 `mavsdk` 包内嵌 `mavsdk_server` 二进制;**aarch64 有官方 wheel**
-  (PyPI 核对:mavsdk 4.0.0 提供 `cp38-abi3 manylinux2014_aarch64`,
-  abi3 兼容 Python 3.11/3.13,要求 glibc≥2.17)。32 位 armv7l 支持不稳定——
-  这是必须 64 位镜像的主因。
-- **libstdc++ 符号**:wheel 内嵌库要求 GCC≥12 的运行时符号;官方镜像
-  Bookworm(GCC 12)/ Trixie(GCC 14)均满足,此前 Ubuntu 镜像上出现的
-  `undefined symbol: ..._M_futex_wait_until...` 不应复现。若仍报:
-  `ldd <libcmavsdk.so 路径> | grep stdc` 确认链接对象,必要时用
-  `LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libstdc++.so.6` 兜底。
-- 安装后别只验证 import,要让原生库真加载一次。**mavsdk 4.x 已无独立
-  `mavsdk_server` 可执行文件**(2.x gRPC 架构的旧物),原生库是
-  `mavsdk/lib/libcmavsdk.so`,正确自检:
+- **mavsdk 4.x 是全新原生 API 重写,与经典 gRPC API 完全不兼容**(2026-09-24
+  树莓派实测):没有 `mavsdk.offboard` / `System` / `telemetry`,本仓库全部
+  飞控代码(Px4Gateway / MavsdkCommandGateway / test.py)都是经典 API,
+  装 4.x 直接 `LegacyModuleError`。**必须锁 `mavsdk<4`**(最新 3.17.4,
+  aarch64 官方 wheel `manylinux2014_aarch64`,PyPI 已核对);
+  32 位 armv7l 支持不稳定——这是必须 64 位镜像的主因。
+- 3.x 为 gRPC 架构,pip 包内嵌 `mavsdk_server` 可执行文件,**不加载
+  libcmavsdk.so,没有 libstdc++ 符号问题**——此前两系统上轮番出现的
+  `undefined symbol: ..._M_futex_wait_until...` 是 4.x 原生库专属坑,
+  换回 <4 后自然消失。
+- 安装后自检三步(缺一不可;单测全绿**不**证明 mavsdk 已装,测试已打桩脱钩):
 
   ```bash
-  # 复现设定点构造(原生库在此加载),打印 cmavsdk OK 即通过
-  python -c "from mavsdk import offboard; offboard.VelocityBodyYawspeed(0,0,0,0); print('cmavsdk OK')"
-  # 动态链接齐全性(无输出=齐全)
-  ldd ~/venv-pod/lib/python3*/site-packages/mavsdk/lib/libcmavsdk.so | grep "not found"
+  pip list | grep -i mavsdk           # 必须显示 3.x(如 3.17.4)
+  python -c "from mavsdk import System; print('api OK')"
+  find ~/venv-pod -name mavsdk_server # 应有输出;直接执行能起服务更佳
   ```
 
-  报 `undefined symbol` 按上面 libstdc++ 条目排查;`Exec format error` 是架构装错。
-  注意:单测全绿**不**证明 mavsdk 已装或原生库健康(测试已打桩脱钩),
-  本步不可替代。
 - 连接串写法(`pod_bridge.json` 的 `px4.connection_string`):
   - Pi 串口直连飞控 TELEM:`serial:///dev/ttyUSB0:57600`(波特率按飞控侧设置);
   - 经数传/仿真:`udp://:14540`。