# 部署与运维手册（项目总结）

本文面向 **生产/外场部署**：说明 **voice_drone_assistant** 是什么、与 **云端** / **ROS 伴飞桥** / **PX4** 如何衔接，以及 **推荐启动顺序**、**环境变量**与**常见问题**。  
协议细节见 [`llmcon.md`](llmcon.md)，通用配置索引见 [`PROJECT_GUIDE.md`](PROJECT_GUIDE.md)，伴飞桥行为见 [`FLIGHT_BRIDGE_ROS1.md`](FLIGHT_BRIDGE_ROS1.md)，`flight_intent` 字段见 [`FLIGHT_INTENT_SCHEMA_v1.md`](FLIGHT_INTENT_SCHEMA_v1.md)。

---

## 1. 项目总结

### 1.1 定位

**voice_drone_assistant** 是板端 **语音无人机助手**：麦克风 → 降噪/VAD → **SenseVoice STT** → **唤醒词** → 用户一句指令 → **云端 WebSocket**（LLM + TTS）或 **本地 Qwen + Kokoro** → 若服务端返回 **`flight_intent`**，可在本机 **校验后执行**（TCP Socket 旧路径，或 **ROS 伴飞桥** 推荐路径）。

### 1.2 推荐数据流（方案一：云 → 语音程序 → ROS 桥）

```mermaid
flowchart LR
  subgraph cloud [云端]
    WS[WebSocket LLM+TTS]
  end
  subgraph board [机载 香橙派等]
    MIC[麦克风]
    MAIN[main.py TakeoffPrintRecognizer]
    ROSPUB[子进程 publish JSON]
    BRIDGE[flight_bridge ros1_node]
    MAV[MAVROS]
  end
  FCU[PX4 飞控]

  MIC --> MAIN
  MAIN <-->|WSS pcm_asr_uplink + flight_intent| WS
  MAIN -->|ROCKET_FLIGHT_INTENT_ROS_BRIDGE| ROSPUB
  ROSPUB -->|std_msgs/String /input| BRIDGE
  BRIDGE --> MAV --> FCU
```

- **不**把 ROS 直接暴露给公网：云端只连板子的 **WSS/WS**；飞控由 **本机 MAVROS + 伴飞桥** 执行。
- **TCP Socket**（`system.yaml` → `socket_server`）是另一条试飞控通道，与云端 **无关**；未起 Socket 服务端时仅会重连日志，不影响 ROS 方案。

### 1.3 目录与核心入口（仓库根 = `voice_drone_assistant/`）

| 路径 | 说明 |
|------|------|
| `main.py` | 语音助手入口 |
| `with_system_alsa.sh` | 建议包装启动，修正 Conda 与系统 ALSA |
| `voice_drone/main_app.py` | 唤醒、云端/本地 LLM、TTS、`flight_intent` 执行策略 |
| `voice_drone/flight_bridge/ros1_node.py` | ROS1 订阅 `/input`，执行 `flight_intent` |
| `voice_drone/flight_bridge/ros1_mavros_executor.py` | MAVROS：offboard / AUTO.LAND / RTL |
| `voice_drone/tools/publish_flight_intent_ros_once.py` | 单次向 ROS 发布 JSON（主程序 ROS 桥会子进程调用） |
| `scripts/run_flight_bridge_with_mavros.sh` | 一键：roscore（可选）+ MAVROS + 伴飞桥 |
| `scripts/run_flight_intent_bridge_ros1.sh` | 仅伴飞桥（须已有 roscore + MAVROS） |
| `voice_drone/config/system.yaml` | 音频、STT、TTS、云端、`assistant` 等 |
| `requirements.txt` | Python 依赖；**rospy** 来自 `apt` 的 ROS Noetic，见文件内注释 |

---

## 2. 环境与依赖

### 2.1 硬件与系统（典型）

- ARM64 板卡（如 RK3588）、ES8388 等音频编解码器、USB/内置麦克风。
- Ubuntu 20.04 + **ROS Noetic**（伴飞桥 / MAVROS 路径）；同机运行语音进程与 `ros1_node`。
- 飞控串口（如 `/dev/ttyACM0`）与 MAVROS `fcu_url` 一致。

### 2.2 Python

- Python 3.10+（与原仓库一致即可）。
- 在 **`voice_drone_assistant`** 根目录：

  ```bash
  pip install -r requirements.txt
  ```

### 2.3 ROS / MAVROS（伴飞桥方案必选）

```bash
sudo apt install ros-noetic-ros-base ros-noetic-mavros ros-noetic-mavros-extras
# 按官方文档执行 mavros 地理库安装（如有）
```

- 语音主程序的 **ROS 桥**子进程会 `source /opt/ros/noetic/setup.bash` 并 **prepend** `PYTHONPATH`，**不要**在未 source ROS 的 shell 里把 `PYTHONPATH` 设成「只有工程根」，否则会找不到 `rospy`（参见 `main_app` 中 `_publish_flight_intent_to_ros_bridge`）。

### 2.4 模型与权重

- STT / TTS /（可选）VAD 放入 `models/`，或 `bash scripts/bundle_for_device.sh` 从原仓库打包。
- 本地 LLM：GGUF 默认路径或 `ROCKET_LLM_GGUF`；**纯云端对话**时可弱化本地模型，但回退/混合模式仍需。

---

## 3. 部署拓扑

### 3.1 单机一体化（常见）

同一台香橙派上同时运行：

1. **roscore**（若尚无 master，由 `run_flight_bridge_with_mavros.sh` 拉起）。
2. **MAVROS**（`px4.launch`，串口连 PX4）。
3. **伴飞桥** `python3 -m voice_drone.flight_bridge.ros1_node`（订阅 **`/input`**）。
4. **语音** `bash with_system_alsa.sh python main.py`。

`ROS_MASTER_URI` / `ROS_HOSTNAME`：一键脚本内默认 `http://127.0.0.1:11311` 与 `127.0.0.1`；**新开调试终端** 执行 `rostopic`/`rosservice` 前须自行 `source /opt/ros/noetic/setup.bash` 并 export **同一** `ROS_MASTER_URI`（见下文「常见问题」）。

### 3.2 网络

- 板子能访问 **云端 WebSocket**（`ROCKET_CLOUD_WS_URL`）。
- PX4 + 遥控 + 安全开关等按外场规范配置；本文不替代安全检校清单。

---

## 4. 启动顺序（推荐）

### 4.1 终端 A：飞控栈 + 伴飞桥

在 **`voice_drone_assistant`** 根目录：

```bash
cd /path/to/voice_drone_assistant
bash scripts/run_flight_bridge_with_mavros.sh /dev/ttyACM0 921600
```

脚本会：

- 设置 `ROS_MASTER_URI`、`ROS_HOSTNAME`（未预设时默认为本机 master）；
- 如无 master 则启动 **roscore**；
- 启动 **MAVROS** 并等待 `/mavros/state` **connected**；
- 前台启动伴飞桥，日志中应出现：`flight_intent_bridge 就绪：订阅 /input`。

**仅桥（已有 MAVROS 时）**：

```bash
source /opt/ros/noetic/setup.bash
export ROS_MASTER_URI="${ROS_MASTER_URI:-http://127.0.0.1:11311}"
export ROS_HOSTNAME="${ROS_HOSTNAME:-127.0.0.1}"
bash scripts/run_flight_intent_bridge_ros1.sh
```

### 4.2 终端 B：语音助手 + 云端 + 执行飞控

```bash
cd /path/to/voice_drone_assistant

export ROCKET_CLOUD_VOICE=1
export ROCKET_CLOUD_WS_URL='ws://<云主机>:8766/v1/voice/session'
export ROCKET_CLOUD_AUTH_TOKEN='<token>'
export ROCKET_CLOUD_DEVICE_ID='drone-001'   # 可选

# 云端返回 flight_intent 时是否在机端执行
export ROCKET_CLOUD_EXECUTE_FLIGHT=1
# 走 ROS 伴飞桥（与 Socket/offboard 序列互斥，勿双开重复执行）
export ROCKET_FLIGHT_INTENT_ROS_BRIDGE=1
# 可选：ROCKET_FLIGHT_BRIDGE_TOPIC=/input  ROCKET_FLIGHT_BRIDGE_WAIT_SUB=2

# 默认关闭本地「起飞演示」口令直起 offboard；需要时再设为 1
# export ROCKET_LOCAL_KEYWORD_TAKEOFF=1

bash with_system_alsa.sh python main.py
```

成功时日志类似：`[飞控-ROS桥] 已发布至 /input`；伴飞桥端出现 `执行 flight_intent：steps=...`。

### 4.3 配置写进 YAML（可选）

- 云端：`system.yaml` → `cloud_voice`（`enabled`、`server_url`、`auth_token` 等）。
- 本地口令起飞：`assistant.local_keyword_takeoff_enabled`（默认 `false`）；环境变量 `ROCKET_LOCAL_KEYWORD_TAKEOFF` **非空时优先生效**。

---

## 5. 环境变量速查（飞控与云端）

| 变量 | 含义 |
|------|------|
| `ROCKET_CLOUD_VOICE` | `1`：对话走云端 WebSocket |
| `ROCKET_CLOUD_WS_URL` | 云端会话地址 |
| `ROCKET_CLOUD_AUTH_TOKEN` | WS 鉴权 |
| `ROCKET_CLOUD_DEVICE_ID` | 设备 ID（可选） |
| `ROCKET_CLOUD_EXECUTE_FLIGHT` | `1`：云端 `flight_intent` 在机端执行 |
| `ROCKET_FLIGHT_INTENT_ROS_BRIDGE` | `1`：执行方式为 **发布到 ROS `/input`**，不跑机内 Socket+offboard 序列 |
| `ROCKET_FLIGHT_BRIDGE_TOPIC` | 默认 `/input` |
| `ROCKET_FLIGHT_BRIDGE_SETUP` | 子进程内 source ROS 的命令，默认 `source /opt/ros/noetic/setup.bash` |
| `ROCKET_FLIGHT_BRIDGE_WAIT_SUB` | 发布前等待订阅者的秒数，默认 `2`；`0` 即尽可能快发 |
| `ROCKET_LOCAL_KEYWORD_TAKEOFF` | 非空时：`1/true/yes` 开启 **`keywords.yaml` takeoff → 本地 offboard** |
| `ROCKET_CLOUD_PX4_CONTEXT_FILE` | 覆盖 `cloud_voice.px4_context_file`，合并进 session.start |

更多调试变量见 **`voice_drone/main_app.py` 文件头注释** 与 [`PROJECT_GUIDE.md`](PROJECT_GUIDE.md) 第 5 节。

---

## 6. 联调与自测

### 6.1 仅测 ROS 链（无语音）

终端已 `source /opt/ros/noetic/setup.bash` 且与 master 一致：

```bash
rostopic pub -1 /input std_msgs/String \
  "data: '{\"is_flight_intent\":true,\"version\":1,\"actions\":[{\"type\":\"land\",\"args\":{}}],\"summary\":\"测\"}'"
```

注意：`std_msgs/String` 在命令行里只能写 **`data: '...json...'`**，不能把 JSON 放在消息顶层。

### 6.2 确认话题与 master

```bash
source /opt/ros/noetic/setup.bash
export ROS_MASTER_URI=http://127.0.0.1:11311
rosnode list
rostopic info /input
rosservice list | grep set_mode
```

若 `Unable to communicate with master!`：当前 shell 未连上正在运行的 **roscore**（或未 export 正确 `ROS_MASTER_URI`）。

---

## 7. 常见问题（摘录）

| 现象 | 可能原因 | 处理 |
|------|----------|------|
| `ModuleNotFoundError: rospy` | 子进程未继承 ROS 的 `PYTHONPATH` | 已修复为 `PYTHONPATH=<根>:$PYTHONPATH`；确保 `ROCKET_FLIGHT_BRIDGE_SETUP` 能 source Noetic |
| 语音端「已发布」但桥无日志 | 曾用相对 `input`，与全局 `/input` 不一致 | 伴飞桥默认已改为订阅 **`/input`**；重启桥 |
| `set_mode unavailable` / land 失败 | OFFBOARD 断流、MAVROS 异常等 | 伴飞桥降落逻辑已带持续 setpoint + 重连 proxy；仍失败则查 `rosservice`、`/mavros/state`、链路 |
| takeoff 超时 | 未进 OFFBOARD、未解锁、定位未就绪 | 查地面站、`/mavros/state`、适当增大 `~takeoff_timeout_sec`（ROS 私有参数） |
| ALSA underrun | 播放与采集竞争 | 板端常见；可调缓冲区/设备或 `recognizer.ack_pause_mic_for_playback` |

---

## 8. 安全与运维建议

- 外场前在 **SITL 或系留** 环境验证完整 **`flight_intent`** 序列。
- 云端 token、WS URL 勿提交到公开仓库；用环境变量或本机 **overlay** 配置注入。
- 升级伴飞桥或 MAVROS 后清日志重试一遍 **`/input`** 手发 JSON。

---

## 9. 迁移到另一台香橙派：是否只拷贝 `voice_drone_assistant` 即可？

**结论：目录是「代码 + 配置」的核心载体，但仅靠「整文件夹 scp 过去」通常不够；新板必须再装系统级依赖、模型与（可选）ROS，并按现场改配置。**

### 9.1 拷贝目录本身会带上什么

| 已包含 | 说明 |
|--------|------|
| 全部 Python 源码、`voice_drone/config/*.yaml` 默认配置 | 可直接改 YAML / 环境变量适配新环境 |
| `scripts/`、`with_system_alsa.sh`、`docs/` | 启动与说明在包内 |

### 9.2 新板必须单独准备（不随目录自动存在）

| 项 | 说明 |
|----|------|
| **Ubuntu + 音频/ALSA** | 与当前开发板同代或自行适配；录音设备索引可能变化，需重选或设 `ROCKET_INPUT_DEVICE_INDEX` |
| **`pip install -r requirements.txt`** | 每台新 Python 环境执行一次（或整体迁移同一 conda 目录） |
| **`models/`** | STT/TTS/VAD 体积大，**务必**在本机先 `bash scripts/bundle_for_device.sh /path/to/rocket_drone_audio` 或手工拷入，见 `models/README.txt` |
| **`cache/` GGUF** | 纯云端可不强依赖；若需本地 Qwen 回退，拷贝或设 `ROCKET_LLM_GGUF` |
| **ROS Noetic + MAVROS** | **apt** 安装；伴飞桥方案 **必选**；`rospy` **不要**指望只靠 pip |
| **云端连通** | 新板 IP/防火墙能访问 `ROCKET_CLOUD_WS_URL`；token 用环境变量注入 |
| **`dialout` 等权限** | 访问 `/dev/ttyACM0` 的用户加入 `dialout`，否则 MAVROS 无串口 |
| **`system.yaml` 现场差异** | `socket_server` IP、可选 `tts.output_device`、若麦索引固定可写 `audio.input_device_index` |

### 9.3 推荐迁移流程（简表）

1. 在旧机或 CI：**bundle 模型** → 打包整个 `voice_drone_assistant`（含 `models/`，按需含 `cache/`）。  
2. 新香橙派：解压到任意路径，安装 **`requirements.txt`**、**ROS+MAVROS**、系统音频工具。  
3. 用 **`with_system_alsa.sh python main.py`** 试麦与 STT；再按本文 **§4** 双终端起 **桥 + 语音**。  
4. 首次外场前做一次 **`rostopic pub /input`** 手发 JSON（见 **§6**）。

### 9.4 常见误区

- **只拉 Git、不拷 `models/`**：STT/TTS 启动即失败。  
- **新板 Noetic 未装却开 `ROCKET_FLIGHT_INTENT_ROS_BRIDGE`**：发布子进程仍可能报错。  
- **假设麦克风设备号一定相同**：Orange Pi 刷机或换内核后常变，以首次启动日志为准。  

---

## 10. 文档索引

| 文档 | 用途 |
|------|------|
| [`README.md`](../README.md) | 仓库简介、模型、`bundle` |
| [`PROJECT_GUIDE.md`](PROJECT_GUIDE.md) | 配置项与日常用法索引 |
| **本文** | 部署拓扑、启动顺序、环境变量、联调、**§9 迁移清单** |
| [`FLIGHT_BRIDGE_ROS1.md`](FLIGHT_BRIDGE_ROS1.md) | 伴飞桥参数、PX4 行为、`rostopic pub` 注意 |
| [`FLIGHT_INTENT_SCHEMA_v1.md`](FLIGHT_INTENT_SCHEMA_v1.md) | JSON 协议 |
| [`llmcon.md`](llmcon.md) | 云端协议 |
| [`CLOUD_VOICE_FLIGHT_CONFIRM_v1.md`](CLOUD_VOICE_FLIGHT_CONFIRM_v1.md) | **飞控口头二次确认**（闲聊不变、确认/取消/超时）云端与机端字段约定 |

---

*文档版本与仓库同步；若行为与代码不一致，以当前 `main_app.py`、`flight_bridge/*.py` 为准。*