Metadata-Version: 2.4
Name: pi-uav-protocol
Version: 0.2.0
Summary: Python protocol-conversion library for heterogeneous UAVs
Project-URL: Homepage, https://gitee.com/pi-lab/pi-uav-protocol
Author: pi-lab
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: mypy>=1.5; extra == 'all'
Requires-Dist: pymavlink; extra == 'all'
Requires-Dist: pytest-asyncio>=0.21; extra == 'all'
Requires-Dist: pytest>=7; extra == 'all'
Requires-Dist: ruff>=0.1; extra == 'all'
Requires-Dist: websockets; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: mavlink
Requires-Dist: pymavlink; extra == 'mavlink'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Provides-Extra: tiantu
Requires-Dist: websockets; extra == 'tiantu'
Description-Content-Type: text/markdown

# PI-无人机通用协议

PI-无人机通用协议是一套运行在机载设备上的 WebSocket 客户端通信协议，专为无人机系统设计。该协议支持实时推送飞机遥测数据，并可异步接收来自服务器的控制命令，为无人机与地面控制站之间提供可靠的通信桥梁。

## 安装、使用
建议使用conda
```bash
# 首次创建环境
conda create -n pi-uav python=3.11
# 激活环境
conda activate pi-uav
```

安装 pi-uav-protocol，安装本地下载的库，方便开发
```bash
git clone git@gitee.com:pi-lab/pi-uav-protocol.git
cd pi-uav-protocol
pip install -e ".[all]"
```

本库主要给其他第三方库提供服务，因此本库主要被调用。


## 主要特性

- 🚀 **实时数据传输** - 支持高频率遥测数据推送（最高3Hz）
- 🎮 **全面飞行控制** - 涵盖起飞、降落、航线规划等完整飞行控制指令
- 📹 **光电吊舱集成** - 支持云台控制、相机操作、目标跟踪等功能
- 💓 **连接监控** - 内置心跳机制确保连接稳定性
- 📋 **指令应答** - 完整的指令执行反馈机制
- 🔌 **WebSocket 协议** - 基于标准 WebSocket 实现，易于集成

## 技术规格

- **协议格式**: JSON
- **传输协议**: WebSocket
- **数据频率**:
  - 遥测数据: 3Hz
  - 云台数据: 3Hz
  - 心跳包: 1Hz
- **设备支持**: 四旋翼飞机、垂起固定翼、机器狗、无人车

## 协议概览

### 消息类型

| 消息类型             | 发送方 | 接收方 | 应答  | 描述      |
| ---------------- | --- | --- | --- | ------- |
| **数据信息类**        |     |     |     |         |
| `uav_nav_data`   | 终端  | 服务器 | 否   | 无人机综合数据 |
| `gimbal_data`    | 终端  | 服务器 | 否   | 云台综合数据  |
| `heart`          | 终端  | 服务器 | 否   | 心跳包     |
| **指令控制类**        |     |     |     |         |
| `uav_control`    | 服务器 | 终端  | 是   | 飞行控制指令  |
| `gimbal_control` | 服务器 | 终端  | 是   | 光电吊舱指令  |
| **应答类**          |     |     |     |         |
| `result`         | 终端  | 服务器 | 否   | 指令执行结果  |

### 支持的控制指令

#### 飞行控制指令

- `takeoff` - 起飞
- `land` - 降落
- `hold` - 悬停
- `RTL` - 返航
- `stop` - 停浆
- `fly_to_des` - 直飞航点
- `point_flight` - 指点飞行
- `upload_route` - 上传航线
- `download_route` - 下传航线
- `start_mission` - 执行任务
- `pause_mission` - 暂停任务
- `switch_control` - 切换控制源
- `set_safety_params` - 设置安全参数

#### 光电吊舱指令

- `gimbal_pitch` - 云台俯仰角控制
- `gimbal_roll` - 云台横滚角控制
- `gimbal_yaw` - 云台航向角控制
- `camera_zoom` - 相机变焦
- `take_photo` - 拍照
- `start_video` - 开启视频流
- `start_tracking` - 开启目标跟踪
- `stop_tracking` - 关闭目标跟踪
- `start_identify` - 开启目标识别
- `stop_identify` - 关闭目标识别
- `start_laser` - 开启激光测距
- `stop_laser` - 关闭激光测距
- `magnetic_calibration` - 磁校准
- `gyro_calibration` - 陀螺仪校准
- `compass_calibration` - 指南针校准

## 数据类型

### 遥测数据

- 飞行姿态：俯仰角、航向角、横滚角
- 位置信息：经纬度、海拔高度、相对高度
- 运动状态：水平速度、垂直速度、地面速度
- 导航信息：GPS收星数量、RTK收星数量
- 飞行状态：飞行模式、解锁状态、任务进度
- 系统状态：电池电量、系统健康状态、错误和警告信息

### 云台数据

- 云台姿态：俯仰角、横滚角、航向角
- 光电信息：光轴方位角、光轴俯仰角、视场角
- 相机状态：变焦倍数、视频流地址
- 目标信息：目标位置、激光测距结果

## 应用场景

- **无人机飞行控制** - 实现对无人机的远程控制和监控
- **任务执行** - 支持航线规划和自主任务执行
- **实时监控** - 提供飞行器状态的实时数据反馈
- **云台控制** - 精确控制光电吊舱进行目标跟踪和识别
- **数据记录** - 支持飞行数据的记录和分析

## 接入要求

- 支持 WebSocket 客户端连接
- 支持 JSON 格式数据解析
- 具备实时数据处理能力
- 遵循协议规定的消息格式和频率要求

## 协议详细文档

完整的协议规范请参考：[pi-uav-protocol.md](docs/pi-uav-protocol.md)
