PI-无人机通用协议

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

安装、使用

建议使用conda

# 首次创建环境
conda create -n pi-uav python=3.11
# 激活环境
conda activate pi-uav

安装 pi-uav-protocol，安装本地下载的库，方便开发

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
• 设备支持: 四旋翼飞机、垂起固定翼、机器狗、无人车

协议概览

消息类型

支持的控制指令

飞行控制指令

• 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