部署文档目标系统回改为Raspberry Pi OS官方镜像

用户在Ubuntu镜像上遇串口问题换回官方镜像: §1改Bookworm(3.11)/Trixie(3.13)
口径, §3补libstdc++符号说明(GCC12+官方镜像均满足), §4恢复raspi-config与
/dev/serial0指引, §7注明单测已与原生库脱钩

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

@@ -1,6 +1,8 @@
 # pod_bridge 移交树莓派 4B 部署注意事项
 
-> 目标平台:树莓派 4B + **Ubuntu 24.04(aarch64)**。
+> 目标平台:树莓派 4B + **Raspberry Pi OS 官方镜像(64 位,Bookworm / Trixie)**。
+> (2026-09-23 由 Ubuntu 24.04 换回官方镜像:Ubuntu 镜像上串口配置与
+> libstdc++ 符号问题频出,官方镜像对 Pi 串口/固件支持最完整。)
 > 范围:`utils/pod_bridge`(及其依赖的 `visual_track_control` 控制原语库)。
 > 核对日期:2026-09-23,对照规格《光电吊舱控制协议G版-PB.docx》;
 > 依赖轮子已按 PyPI 2026-09-23 上游信息复核。
@@ -9,13 +11,13 @@
 
 ## 1. 系统与 Python 版本(硬性)
 
-- **Ubuntu 24.04(aarch64)**:Ubuntu 的 Pi 镜像只有 64 位,天然满足 MAVSDK
-  对 aarch64 的要求(见 §3);不要自行改装任何 32 位系统。
-- **Python 3.12**(Ubuntu 24.04 自带)满足 PEP 604 标注(`float | None` /
-  `FrameParser | None`)要求的 ≥3.10,直接用,无需另装。
-- Ubuntu 24.04 系统 Python 受 PEP 668 保护,**禁止 `pip install` 进系统环境**
-  (报 externally-managed-environment),一律建 venv。注意 Ubuntu 默认
-  **不带 venv 支持**,先 apt 补齐:
+- **必须烧录 64 位镜像**(Raspberry Pi Imager 里选 "Raspberry Pi OS (64-bit)"),
+  理由见 §3 MAVSDK 对 aarch64 的要求;32 位镜像不要碰。
+- 烧完先确认:`cat /etc/os-release`。**Bookworm 自带 Python 3.11、
+  Trixie 自带 Python 3.13**,均满足 PEP 604 标注(`float | None` /
+  `FrameParser | None`)要求的 ≥3.10,直接用。
+- Bookworm 起系统 Python 受 PEP 668 保护,**禁止 `pip install` 进系统环境**
+  (报 externally-managed-environment),一律建 venv;venv 支持若缺失先 apt 补:
 
   ```bash
   sudo apt update && sudo apt install -y python3-venv python3-pip
@@ -46,8 +48,13 @@ pytest    # 仅上机自测需要,部署运行可省
 
 - pip 的 `mavsdk` 包内嵌 `mavsdk_server` 二进制;**aarch64 有官方 wheel**
   (PyPI 核对:mavsdk 4.0.0 提供 `cp38-abi3 manylinux2014_aarch64`,
-  abi3 向前兼容 Python 3.12,要求 glibc≥2.17,Ubuntu 24.04 为 2.39 ✅)。
-  32 位 armv7l 支持不稳定——Ubuntu 24.04 Pi 镜像只有 64 位,无此问题。
+  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,要让内嵌二进制真跑一次:
   `find ~/venv-pod -name mavsdk_server` 找到路径后直接执行(无参数即起服务,
   Ctrl+C 退出),能打印启动信息说明架构匹配;`Exec format error` 则装错了架构。
@@ -62,14 +69,12 @@ pytest    # 仅上机自测需要,部署运行可省
   - **RS232 → 必须加电平转换或直接用 USB 转串口模块**(FTDI/CH340,推荐,
     免折腾 GPIO UART,设备号 `/dev/ttyUSB0`);
   - TTL 3.3V → 可用 Pi GPIO14/15(`/dev/serial0`)。
-- 用 GPIO UART 时(**Ubuntu 没有 raspi-config**,手工配置):
-  - `/boot/firmware/config.txt` 确认有 `enable_uart=1`;若控制台占着串口,
-    关掉:`sudo systemctl disable --now serial-getty@ttyAMA0.service`;
-  - Pi 4B 上 GPIO UART 默认是 mini-UART(ttyS0,波特率随主频漂移),115200 下
-    不稳——同一文件加 `dtoverlay=disable-bt` 把 PL011(ttyAMA0)换回来
-    (设备树 overlay 由固件加载,与发行版无关,Ubuntu 同样生效);
-  - **Ubuntu 没有 Raspberry Pi OS 的 `/dev/serial0` 软链**,设备名直接写
-    `/dev/ttyAMA0`(或 ttyS0);
+- 用 GPIO UART 时(官方镜像自带 `raspi-config`):
+  - `sudo raspi-config` → Interface Options → Serial Port:**控制台选 No、
+    串口硬件选 Yes**(等价于 `enable_uart=1` + 关闭 serial-getty 抢占);
+  - Pi 4B 上 `/dev/serial0` 默认指向 mini-UART(ttyS0,波特率随主频漂移),
+    115200 下不稳——在 `/boot/firmware/config.txt` 加 `dtoverlay=disable-bt`
+    把 PL011(ttyAMA0)换回来,`/dev/serial0` 随之改指 ttyAMA0;
   - **Pi 是 3.3V 电平,绝不直连 5V/RS232 电平**,会烧 GPIO。
 - 接线三线:TX/RX **交叉**、**必须共地(GND)**,不共地是通讯乱码的第一大原因。
 - 用户权限:`sudo usermod -aG dialout $USER`,重登录生效,否则 open 串口 Permission denied。
@@ -95,7 +100,8 @@ pytest    # 仅上机自测需要,部署运行可省
 ## 7. 上机验证顺序(每步过了再下一步)
 
 1. **纯软件自测**(无需任何接线):
-   `cd utils && ~/venv-pod/bin/python -m pytest tests/pod_bridge -q` → 应 92 全绿。
+   `cd utils && ~/venv-pod/bin/python -m pytest tests/pod_bridge -q` → 应 92 全绿
+   (单测已打桩 mavsdk 设定点类型,与 libcmavsdk 原生库健康状态无关)。
 2. **串口回环**:USB 转串口模块 TX/RX 短接,跑一个 feed/echo 小脚本验证字节收发。
 3. **只接吊舱**:观察能否解析出 表2-2(60Hz EE 16)帧;用 `send_control(归中 0x2B)`
    验证下行。