mavRflyShell 接口文档¶
简介¶
简述：本文件实现了基于MAVLink协议的无人机端shell交互功能，可通过串口连接打开无人机端的命令行交互shell。
本模块属于RflySimSDK的集群工具模块，提供了从地面站端访问无人机飞控命令行shell的通道，支持通过MAVLink协议透传shell命令与飞控响应数据。
该模块适用于需要在仿真环境中远程调试飞控、执行飞控端自定义命令、查看飞控运行状态日志的场景，可帮助开发者快速验证飞控配置、排查集群仿真中飞控端的问题。其中ConnectNsh函数可快速建立连接，MavRflyShell核心类整合了MAVLink通信与shell交互逻辑，支持稳定的命令收发交互。
快速开始¶
以下示例检测当前连接的 PX4 飞控串口。未检测到设备时返回非正值。
参考例程：[RflySim安装路径]\RflySimAPIs\1.RflySimIntro\2.AdvExps\e9.ConfigTools\e1.FCUETH_NetConfig
import sys
import mavRflyShell
nsh = mavRflyShell.MavRflyShell()
com = nsh.getPX4Com()
if com <= 0:
print("未检测到 PX4 飞控，请连接设备后重试")
sys.exit(0)
print("检测到飞控串口:", com)
环境与依赖¶
- 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)
进阶用法示例¶
以下示例在用户确认目标 SysID 后，通过同一串口依次配置多块飞控的系统 ID 和网络地址。该操作会修改飞控参数，必须核对编号顺序。
参考例程：[RflySim安装路径]\RflySimAPIs\1.RflySimIntro\2.AdvExps\e9.ConfigTools\e1.FCUETH_NetConfig
import sys
import mavRflyShell
nsh = mavRflyShell.MavRflyShell()
com = nsh.getPX4Com()
if com <= 0:
print("未检测到 PX4 飞控")
sys.exit(0)
targetIDs = input("输入要配置的 SysID，以英文逗号分隔: ")
targetIDList = [int(value.strip()) for value in targetIDs.split(",")]
input("确认飞控连接顺序无误后按 Enter 开始配置")
for index, targetID in enumerate(targetIDList):
isLast = index == len(targetIDList) - 1
success = nsh.setSysIDIP(com, targetID, is_last=isLast)
print("SysID", targetID, "配置结果:", success)
if not success:
break
注意事项与避坑指南¶
- 参数修改提交时效性：调用
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: 新增飞控初始参数配置接口