# rtk_nav_project

**Repository Path**: outa/rtk_nav_project

## Basic Information

- **Project Name**: rtk_nav_project
- **Description**: 只用RTK导航
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RTK 导航项目

基于 RTK GPS + MAVLink 的 ROV 水下自主导航系统。双进程架构，传感器与导航引擎解耦，通过 UDP 通讯。支持盲飞巡航模式（无视觉/无 DVL），适用于水下定深航点导航场景。

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                    ROV 伴板计算机 (Linux)                  │
│                                                         │
│  ┌──────────────┐   UDP 9998    ┌──────────────┐        │
│  │  sensor_hub  │ ────────────> │   nav_engine  │        │
│  │  (传感器基座)  │ <─────────── │   (导航引擎)   │        │
│  │              │   UDP 9999    │              │        │
│  │  RTK 串口     │               │  PID 控制器   │        │
│  │  rov_control  │               │  状态机       │        │
│  │  (MAVLink控制) │               │              │        │
│  └──────┬───────┘               └──────────────┘        │
│         │ UDP 8888 (遥测广播)                            │
└─────────┼───────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────┐
│        上位机 (Windows / 任意浏览器)       │
│                                         │
│   dashboard.py (Flask Web 仪表盘)       │
│   ├── 实时轨迹图 (NED 坐标系)            │
│   ├── 飞控 / RTK 状态面板               │
│   ├── 航点管理 (添加 / 删除 / 清空)      │
│   ├── 推力输出监控                       │
│   └── 任务下发 (起飞 / 导航 / 终止)      │
└─────────────────────────────────────────┘
```

### 控制链路

```
nav_engine (PID结算)
    │  send_rc(fwd, yaw, z)
    ▼
rov_api (UDP 9999)
    │
    ▼
sensor_hub (指令接收)
    │
    ▼
rov_control (MAVLink封装)
    │  1Hz GCS heartbeat (保持连接)
    │  20Hz manual_control_send (推力转发)
    ▼
飞控 (ArduSub)
```

`rov_control.py` 参考 `rov_control_examples/rov_control.py` 的控制方式:
- 连接后启动独立心跳线程 (1Hz)，心跳不停控制才有效
- `manual_control_send` 发送推力 (x=前后, y=侧移, z=深度, r=偏航)
- arm/disarm/set_mode 等指令通过 `command_long` 发送
- 后台监听线程解析飞控状态 (HEARTBEAT/ATTITUDE/AHRS2/SYS_STATUS/STATUSTEXT)

## 文件结构

```
rtk_nav_project/
├── main.py                  # 启动入口 — 启动导航引擎
├── run_sensor_hub.py        # 便捷启动 — 传感器基座
├── run_dashboard.py         # 便捷启动 — Web 仪表盘
├── config.json              # 运行时配置 (覆盖默认值)
├── requirements.txt         # Python 依赖
├── .gitignore
│
├── rtk_nav/                 # 核心包
│   ├── __init__.py
│   ├── config.py            # 全局配置 — NavConfig dataclass + config.json 持久化
│   ├── logger.py            # 日志工具 — 按模块分类 + RotatingFileHandler 轮转
│   ├── nmea_utils.py        # NMEA 工具 — 纯函数，无 pymavlink 依赖
│   ├── rov_control.py       # 飞控控制器 — MAVLink 封装 (心跳/推力/解锁/模式)
│   ├── rov_api.py           # ROV 通讯 — UDP 遥测接收 + 指令发送
│   ├── sensor_hub.py        # 传感器基座 — RTK 串口解析 + 遥测广播 + 指令中转
│   ├── nav_engine.py        # 导航引擎 — 状态机 + PID 控制 + 航点导航
│   └── dashboard/           # Web 仪表盘子包
│       ├── __init__.py
│       ├── app.py           # Flask + WebSocket 实时推送
│       └── templates/
│           └── index.html   # 单文件前端 — 暗色主题
│
├── tools/                   # 独立工具
│   ├── fc_helper.py         # 飞控参数读写工具 (纯 pymavlink)
│   └── mock_telemetry.py   # 模拟器 — 无硬件环境下模拟 ROV 巡航
│
└── tests/
    ├── __init__.py
    └── test_nav.py          # 单元测试 (36 tests)
```

## 快速开始

### 环境要求

- Python 3.8+
- pymavlink, pyserial (ROV 伴板计算机)
- flask, flask-socketio (上位机仪表盘)

### 安装依赖

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

### 运行单元测试

```bash
python -m pytest tests/ -v
```

### 无硬件模拟 (开发调试)

```bash
# 终端 1: 启动 Web 仪表盘
python run_dashboard.py

# 终端 2: 启动模拟器 (模拟 ROV 沿 3 个航点巡航)
python tools/mock_telemetry.py

# 浏览器打开 http://127.0.0.1:5000
```

### 实际部署

```bash
# === ROV 伴板计算机 (Linux) ===
python3 run_sensor_hub.py &   # 后台运行传感器基座
python3 main.py               # 前台运行导航引擎

# === 上位机 (Windows) ===
python run_dashboard.py       # 启动 Web 仪表盘
# 浏览器打开 http://<上位机IP>:5000
```

## 配置说明

所有参数集中在 `config.py`，支持环境变量覆盖，方便多环境部署。

| 参数 | 环境变量 | 默认值 | 说明 |
|------|---------|--------|------|
| MAVLink 连接 | `RTK_MAV_CONN` | `udp:192.168.2.2:14551` | 飞控连接串 |
| RTK 串口 | `RTK_SERIAL_PORT` | `/dev/ttyCOM1` | RTK GPS 串口设备 |
| RTK 波特率 | `RTK_SERIAL_BAUD` | `115200` | 串口波特率 |
| GCS IP | `RTK_GCS_IP` | `192.168.2.1` | 上位机 IP (遥测广播目标) |
| GCS 端口 | `RTK_GCS_PORT` | `8888` | 遥测广播 UDP 端口 |
| ROV IP | `RTK_ROV_IP` | `192.168.2.2` | ROV 伴板计算机 IP |
| 仪表盘端口 | `RTK_DASH_PORT` | `5000` | Web 仪表盘 HTTP 端口 |

### PID 参数

```python
PID_FWD = {"Kp": 350.0, "Ki": 20.0, "Kd": 60.0}   # 前进控制
PID_YAW = {"Kp": 13.0, "Ki": 2.0, "Kd": 10.0}      # 航向控制
```

### 安全参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `RC_TIMEOUT` | 1.5s | RC 指令超时挂起 |
| `RTK_LOST_TIMEOUT` | 10.0s | RTK 丢失超时切入悬停 |
| `WAYPOINT_TIMEOUT` | 120.0s | 单航点到达超时 |
| `ARRIVAL_THRESHOLD` | 0.20m | 到达判定距离 |
| `MAX_THRUST` | 750 | 最大推力输出 |

## 导航状态机

```
IDLE ──takeoff──> TAKEOFF ──sequence_done──> NAVIGATE
                                                   │
                                              (航点循环)
                                                   │
                                                   ▼
                                              EVALUATING ──arrival──> 下一航点
                                                   │
                                              timeout/fail
                                                   │
                                                   ▼
                                              EVALUATING (重试/悬停)
                                                   │
                                              abort
                                                   │
                                                   ▼
                                                 IDLE
```

## 通讯协议

### UDP 端口分配

| 端口 | 方向 | 用途 |
|------|------|------|
| 8888 | sensor_hub → GCS | 遥测广播 (飞控状态 + RTK 状态) |
| 9998 | sensor_hub → engine | 引擎遥测推送 |
| 9999 | engine → sensor_hub | 推力指令 |
| 10000 | dashboard → engine | 任务指令 |
| 5000 | HTTP | Web 仪表盘 |

### 遥测数据格式 (JSON)

```json
{
  "fc_state": {
    "mode": "MANUAL",
    "is_armed": true,
    "battery_voltage": 14.8
  },
  "rtk_state": {
    "lat": 31.0000307,
    "lon": 116.9999919,
    "heading": 6.7,
    "fix_quality": 4,
    "satellites": 12
  }
}
```

## 技术要点

- **盲飞巡航**: 无需视觉/声纳，纯靠 RTK GPS + 深度保持实现航点导航
- **双天线航向**: RTK TRA 报文提供绝对航向，无需陀螺仪校准
- **积分安全**: PID 积分限幅 + 积分分离 + 误差过零重置，防止积分饱和
- **航向处理**: wrap-around 归一化 (-180°~180°)，避免跨 0°/360° 跳变
- **非阻塞状态机**: TAKEOFF 序列采用子状态机，避免阻塞主循环
- **NMEA 校验**: 逐条校验和验证，丢弃损坏数据
- **日志轮转**: RotatingFileHandler 10MB × 5 份，防止磁盘爆满