mavRflyShell 接口文档¶
简介¶
简述：本文件实现了基于MAVLink协议的无人机端shell交互功能，可通过串口连接打开无人机端的命令行交互shell。
本模块属于RflySimSDK的集群工具模块，提供了从地面站端访问无人机飞控命令行shell的通道，支持通过MAVLink协议透传shell命令与飞控响应数据。
该模块适用于需要在仿真环境中远程调试飞控、执行飞控端自定义命令、查看飞控运行状态日志的场景，可帮助开发者快速验证飞控配置、排查集群仿真中飞控端的问题。其中ConnectNsh函数可快速建立连接，MavRflyShell核心类整合了MAVLink通信与shell交互逻辑，支持稳定的命令收发交互。
快速开始¶
最简可用示例，复制后修改最少配置即可运行。
from RflySimSDK.swarm import mavRflyShell
# 初始化MavRflyShell实例
mav_shell = mavRflyShell.MavRflyShell()
# 1. 获取PX4串口通信对象
px4_com = mav_shell.getPX4Com()
print(f"获取到PX4串口对象: {px4_com}")
# 2. 获取本机IP地址
local_ip = mav_shell.getLocalIp()
print(f"本机IP地址: {local_ip}")
# 3. 检查IP是否符合RflySim无人机组网规范(以192.168.151开头)
if local_ip:
is_valid = mav_shell.validate_ip(local_ip)
print(f"当前IP是否符合组网规范: {is_valid}")
else:
# 手动测试自定义IP验证示例
test_ip = "192.168.151.100"
is_valid_test = mav_shell.validate_ip(test_ip)
print(f"测试IP {test_ip} 是否符合规范: {is_valid_test}")
环境与依赖¶
- Python 环境：
>= 3.8.10 - 依赖库：
__future__、argparse、io、json、os、re、socket、subprocess、sys、time、timeit - 前置准备：调用此接口前，必须先确保Mavlink连接已就绪可建立通信。
核心接口说明¶
该模块 mavRflyShell.py 包含了配置变量、辅助函数及核心业务类。
全局常量与枚举定义¶
本节列出模块中所有可直接引用的全局常量和枚举定义。
独立常量¶
无
全局/独立函数¶
ConnectNsh()¶
功能说明：连接PX4仿真环境的nsh控制台，用于实现对PX4飞控的命令行交互控制。 参数列表： 无 返回值： 无 异常： 无
MavlinkSerialPort 类¶
用于实现Mavlink协议的串口通信，支持串口数据的读写与调试输出，适用于RflySim中无人机与地面端或外部设备的串口通信场景。
__init__(portname, baudrate, devnum=0, debug=0)¶
功能说明：初始化Mavlink串口对象，打开指定串口并配置通信参数 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
portname |
是 | - | 串口名称，指定要打开的串口设备 | |
baudrate |
是 | - | 串口波特率，配置串口通信速率 | |
devnum |
否 | 0 |
设备编号，区分多个串口设备 | |
debug |
否 | 0 |
调试开关，非0时开启调试输出 |
返回值 (Returns)：
MavlinkSerialPort实例对象
异常 (Raises)： 无
debug(s, level=1)¶
功能说明：写入调试文本，根据调试等级和初始化配置输出调试信息 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
s |
str |
是 | - | 要输出的调试文本内容 |
level |
int |
否 | 1 |
调试等级，只有等级大于等于初始化配置才会输出 |
返回值 (Returns)：
- 无
异常 (Raises)： 无
write(b)¶
功能说明：向串口写入字节数据，发送Mavlink或其他格式的二进制数据 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
b |
bytes |
是 | - | 要写入串口的字节数据 |
返回值 (Returns)：
- 无
异常 (Raises)： 无
close()¶
功能说明：关闭当前打开的串口，释放串口资源 返回值 (Returns)：
- 无
异常 (Raises)： 无
read(n)¶
功能说明：从串口读取指定长度的字节数据 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
n |
int |
是 | - | 要读取的字节数据长度 |
返回值 (Returns)：
bytes: 从串口读取到的字节数据
异常 (Raises)： 无
示例：
# 初始化打开串口
serial_port = MavlinkSerialPort("COM3", 115200, debug=1)
# 写入字节数据
data = bytes([0x01, 0x03, 0x00])
serial_port.write(data)
# 读取返回数据
recv_data = serial_port.read(10)
# 关闭串口
serial_port.close()
RflyShell 类¶
PX4飞控NuttX shell串口交互类，用于通过串口向PX4飞控发送命令、修改参数、重启飞控等操作，适用于RflySim仿真集群场景下的飞控终端控制。
__init__(port, baudrate=115200)¶
功能说明：初始化RflyShell串口连接对象 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
port |
str |
是 | - | 串口设备名称/端口号，例如Windows下为COMx，Linux下为/dev/ttyUSBx |
baudrate |
int |
否 | 115200 |
串口通信波特率，PX4默认波特率为115200 |
返回值 (Returns)：
RflyShell实例对象
异常 (Raises)： 无
is_prompt(data)¶
功能说明：检查接收的串口数据中是否包含完整的shell提示符，用于判断命令是否输出完成 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
data |
bytes |
是 | - | 从串口读取的原始字节数据 |
返回值 (Returns)：
bool: 若包含完整提示符返回True，否则返回False
异常 (Raises)： 无
SendCmdNsh(cmd)¶
功能说明：向PX4飞控发送一条NuttX shell命令并等待输出返回 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
cmd |
str |
是 | - | 需要发送的NuttX shell命令字符串 |
返回值 (Returns)：
str: 命令执行后返回的输出字符串
异常 (Raises)： 无
示例：
from RflySimSDK.swarm import RflyShell
shell = RflyShell("COM3", 115200)
output = shell.SendCmdNsh("help")
print(output)
SendUpdateParam(ParamKey, ParamValue)¶
功能说明：更新PX4飞控参数值到飞控 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
ParamKey |
str |
是 | - | 需要修改的PX4参数名称 |
ParamValue |
int/float |
是 | - | 需要设置的参数新值 |
返回值 (Returns)： 无 异常 (Raises)： 无
SendCommitParam()¶
功能说明：提交所有修改过的PX4参数，将修改保存到飞控闪存中 返回值 (Returns)： 无 异常 (Raises)： 无
SendChangeParam(ParamKey, ParamValue)¶
功能说明：修改并提交单个PX4飞控参数，组合了更新和提交操作 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
ParamKey |
str |
是 | - | 需要修改的PX4参数名称 |
ParamValue |
int/float |
是 | - | 需要设置的参数新值 |
返回值 (Returns)： 无 异常 (Raises)： 无
示例：
SendShowParam(ParamKey)¶
功能说明：查询PX4飞控指定参数的当前值 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
ParamKey |
str |
是 | - | 需要查询的PX4参数名称 |
返回值 (Returns)：
str: 参数查询结果字符串
异常 (Raises)： 无
SendRebootPX4()¶
功能说明：发送命令让PX4飞控重启 返回值 (Returns)： 无 异常 (Raises)： 无
示例：
SendClose()¶
功能说明：关闭串口连接，释放资源 返回值 (Returns)： 无 异常 (Raises)： 无
SendCmdNshS(ParamKey)¶
功能说明：发送指定Nsh命令，无额外输出返回 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
ParamKey |
str |
是 | - | 需要发送的NuttX shell命令字符串 |
返回值 (Returns)： 无 异常 (Raises)： 无
SendAirframe()¶
功能说明：发送查看当前机架配置的命令 返回值 (Returns)： 无 异常 (Raises)： 无
MavRflyShell 类¶
用于PX4无人机飞控的串口通信管理、IP地址配置与设备检测，支持多无人机组网场景下的飞控网络与串口参数配置。
getPX4Com()¶
功能说明：获取PX4飞控对应的串口设备 参数列表 (Args)：
无参数
返回值 (Returns)：
str: 可用的PX4飞控串口路径
异常 (Raises)： 无
getLocalIp()¶
功能说明：获取本机局域网IP地址 参数列表 (Args)：
无参数
返回值 (Returns)：
str: 本机局域网IP地址字符串
异常 (Raises)： 无
validate_ip(ip)¶
功能说明：检查IP地址是否以192.168.151开头 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
ip |
str |
是 | - | 需要验证的IP地址字符串 |
返回值 (Returns)：
bool: 符合格式返回True，否则返回False
异常 (Raises)： 无
auto_configure_ip(targetID)¶
功能说明：自动配置飞控的IP地址 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
targetID |
int |
是 | - | 需要配置IP的目标飞控ID |
返回值 (Returns)：
- 无
异常 (Raises)： 无
setSysIDIP(com, airplane_id, baud="921600", is_last=False)¶
功能说明：通过串口设置飞控的系统ID与对应IP地址 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
com |
str |
是 | - | 目标串口设备路径 |
airplane_id |
int |
是 | - | 需要设置的无人机系统ID |
baud |
int |
否 | 921600 |
串口通信波特率 |
is_last |
bool |
否 | False |
是否为最后一台需要配置的无人机 |
返回值 (Returns)：
- 无
异常 (Raises)： 无
monitorSerialPorts(com)¶
功能说明：监控指定串口的连接状态 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
com |
str |
是 | - | 需要监控的串口设备路径 |
返回值 (Returns)：
- 无
异常 (Raises)： 无
checkSerialAvailable(com)¶
功能说明：检查当前串口是否仍然可用 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
com |
str |
是 | - | 需要检查的串口设备路径 |
返回值 (Returns)：
bool: 串口可用返回True，否则返回False
异常 (Raises)： 无
getAvailableSerialPorts()¶
功能说明：获取当前系统可用的串口列表 参数列表 (Args)：
无参数
返回值 (Returns)：
list[str]: 所有可用串口设备路径组成的列表
异常 (Raises)： 无
waitForNewDevice()¶
功能说明：等待用户插入新的飞控设备 参数列表 (Args)：
无参数
返回值 (Returns)：
str: 新插入设备的串口路径
异常 (Raises)： 无
示例：
from RflySimSDK.swarm import MavRflyShell
shell = MavRflyShell()
# 获取所有可用串口
ports = shell.getAvailableSerialPorts()
# 等待新设备插入
new_port = shell.waitForNewDevice()
check_udp_data(port)¶
功能说明：从指定的UDP端口读取数据 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
port |
int |
是 | - | 需要读取数据的UDP端口号 |
返回值 (Returns)：
bytes: 从UDP端口读取到的数据
异常 (Raises)： 无
connect_to_device(port, baud)¶
功能说明：连接到指定串口的飞控设备 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
port |
str |
是 | - | 飞控设备所在串口路径 |
baud |
int |
是 | - | 串口通信波特率 |
返回值 (Returns)：
object: 连接成功后的设备对象
异常 (Raises)： 无
query_mav_sys_id(rflyShell, sys_id)¶
功能说明：查询指定系统ID的MAVLink设备信息 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
rflyShell |
object |
是 | - | MavRflyShell实例对象 |
sys_id |
int |
是 | - | 需要查询的MAVLink系统ID |
返回值 (Returns)：
dict: 查询到的设备信息
异常 (Raises)： 无
示例：
from RflySimSDK.swarm import MavRflyShell
shell = MavRflyShell()
# 自动配置ID为1的飞控IP
shell.auto_configure_ip(targetID=1)
# 配置飞控ID和对应IP
shell.setSysIDIP("COM3", airplane_id=1, baud=921600)
进阶用法示例¶
展示复杂组合场景（如多类协作、异步控制、批量操作）
import RflySimSDK.swarm as rfly_swarm
import time
from concurrent.futures import ThreadPoolExecutor
# 多无人机批量参数配置+异步重启进阶场景
# 1. 初始化串口和RflyShell实例，扫描所有可用串口
available_ports = rfly_swarm.MavRflyShell.getAvailableSerialPorts()
mav_shell_list = []
for port in available_ports:
if rfly_swarm.MavRflyShell.checkSerialAvailable(port):
serial_port = rfly_swarm.MavlinkSerialPort(port, 57600)
mav_shell = rfly_swarm.RflyShell(serial_port)
mav_shell_list.append(mav_shell)
# 2. 异步批量修改PX4参数，实现多机协作配置
def config_single_drone(mav_shell, param_list):
for param_name, param_val in param_list:
mav_shell.SendChangeParam(param_name, param_val)
time.sleep(0.1)
mav_shell.SendCommitParam()
return mav_shell.SendRebootPX4()
# 为每架无人机分配不同的PID参数配置
param_configs = [
[("MC_PITCH_P", 0.18), ("MC_ROLL_P", 0.18)],
[("MC_PITCH_P", 0.2), ("MC_ROLL_P", 0.2)],
[("MC_PITCH_P", 0.15), ("MC_ROLL_P", 0.15)]
]
# 异步批量执行配置任务，提升多机调试效率
with ThreadPoolExecutor(max_workers=len(mav_shell_list)) as executor:
results = executor.map(lambda args: config_single_drone(*args), zip(mav_shell_list, param_configs))
# 3. 验证配置结果
for res, mav_shell in zip(results, mav_shell_list):
if res:
print("单无人机参数配置并重启成功")
# 关闭连接释放资源
mav_shell.SendClose()
mav_shell._serial.close()
注意事项与避坑指南¶
- 参数修改提交时效性：调用
SendChangeParam批量修改多个参数后，必须调用SendCommitParam才能将修改写入PX4飞控固件，未提交的参数修改会在飞控重启后丢失。 - 串口资源并发限制：同一串口不支持同时被多个
MavlinkSerialPort实例打开，批量扫描可用串口后需及时调用close方法释放不可用串口的资源，避免后续设备接入检测失败。 - IP地址格式校验要求：调用
setSysIDIP绑定飞控系统ID与IP前，必须先通过validate_ip方法校验IP格式，非法IP会导致UDP通信链路建立失败，且不会主动抛出显性错误。 - 命令发送等待间隔：连续调用
SendCmdNsh发送NSH命令时，需要预留至少100ms的间隔等待飞控响应，连续快速发送会导致命令丢包，飞控只执行最后一条接收的命令。
更新日志¶
2024-12-10: fix:更新API页面2024-12-10: fix:更新集群控制接口注释2024-09-06: fix：新增机架类型HIL刷入2024-09-04: fix:1.增加udp验证函数 2.增加错误处理与重试机制 3.修改飞控重启无法找到mav_id参数BUG 4.修改飞控配置完成程序继续配置BUG2024-09-03: fix：新增ip判断、串口识别、消息延时2024-09-03: fix：新增ip判断、串口识别、消息延时2024-09-03: fix：新增ip判断、串口识别、消息延时2024-08-26: fix: 苏晓MavRflyShell更新2024-08-16: fix: 升级shell库2024-08-16: fix: 新增飞控初始参数配置接口