Cleanflight项目MSP协议扩展详解：模式与调整范围配置指南

Cleanflight项目MSP协议扩展详解：模式与调整范围配置指南

cleanflight Clean-code version of the baseflight flight controller firmware 项目地址: https://gitcode.com/gh_mirrors/cl/cleanflight

前言

在无人机飞控系统中，Cleanflight作为一款开源的飞控固件，对MultiWii Serial Protocol(MSP)协议进行了多项功能扩展。本文将深入解析这些扩展协议的技术细节，帮助开发者理解如何通过MSP协议与Cleanflight飞控进行模式配置和调整范围设置。

MSP协议扩展概述

Cleanflight在基础MSP协议上增加了多个扩展命令，主要用于：

1. 模式范围配置（飞行模式设置）
2. 调整范围配置（飞行中参数调整）
3. 1-Wire总线控制

这些扩展需要通过MSP_API_VERSION命令确认固件是否支持。

模式范围配置详解

1. 模式范围数据结构

模式范围配置允许用户通过辅助通道（Aux Channel）设置各种飞行模式。Cleanflight使用以下三个关键命令进行管理：

MSP_MODE_RANGES (ID:34)

功能：获取当前所有模式范围的配置

数据结构： 每个模式槽位(slot)返回4字节数据：

• permanentId (uint8): 模式永久ID，对应特定飞行模式
• auxChannelIndex (uint8): 使用的辅助通道索引(从0开始)
• rangeStartStep/rangeEndStep (uint8): 范围起始/结束值，以25为单位的块表示(0=900μs，48=2100μs)

技术要点：

• 未分配的槽位表现为rangeStartStep == rangeEndStep
• 客户端应通过返回消息总长度/4计算槽位总数

MSP_MODE_RANGES_EXTRA (ID:238)

功能：获取模式额外配置参数

数据结构： 每个槽位返回3字节数据：

• permanentId (uint8): 同上
• modeLogic (uint8): 模式逻辑(0=AND，1=OR)
• linkedTo (uint8): 关联模式的永久ID

特殊处理： 消息前会附加3字节表示每个元素的字节数

MSP_SET_MODE_RANGE (ID:35)

功能：设置模式范围配置

数据结构：

• sequence id (uint8): 序列ID(0到槽位数-1)
• 其余字段与MSP_MODE_RANGES相同

重要原则：

• 必须发送所有槽位的配置，包括禁用和未定义的
• 未使用的槽位应发送全0值(sequence id除外)

2. 模式配置最佳实践

1. 配置流程：

   • 先获取当前配置(MSP_MODE_RANGES + MSP_MODE_RANGES_EXTRA)
   • 修改所需参数
   • 完整回传所有槽位配置(MSP_SET_MODE_RANGE)

2. 注意事项：

   • 不要假设槽位数量，应动态计算
   • 禁用模式也需要显式发送配置
   • 序列ID必须严格递增且连续

调整范围配置详解

1. 调整范围数据结构

调整范围用于飞行中实时调整参数，如PID值、速率等。

MSP_ADJUSTMENT_RANGES (ID:52)

功能：获取当前所有调整范围配置

数据结构： 每个槽位返回6字节数据：

• adjustmentStateIndex (uint8): 调整状态索引
• auxChannelIndex (uint8): 激活调整的辅助通道
• rangeStartStep/rangeEndStep (uint8): 范围值
• adjustmentFunction (uint8): 调整功能类型
• auxSwitchChannelIndex (uint8): 执行功能的辅助通道

MSP_SET_ADJUSTMENT_RANGE (ID:53)

功能：设置调整范围配置

数据结构与获取命令相同，增加sequence id字段

2. 关键概念解析

adjustmentStateIndex: 飞控维护4个独立的调整状态，相同索引的多个调整范围会共享状态。开发者需确保不会产生冲突。

adjustmentFunction: 对应CLI中adjrange命令支持的调整类型，如PID调整、速率调整等。

3. 实现注意事项

• 与模式配置类似，必须处理所有槽位
• 未使用的槽位应发送全0值(sequence id除外)
• 客户端应避免创建会产生冲突的调整范围配置

1-Wire总线控制

MSP_SET_1WIRE (ID:243)

功能：启用串行1-Wire透传模式

参数：

• esc id (uint8): 电调ID(从0开始递增)

安全建议： 应在非解锁状态下使用此功能

已弃用命令

以下命令已被新模式范围命令取代，Cleanflight不再支持：

• MSP_BOX
• MSP_SET_BOX

总结

Cleanflight的MSP扩展提供了强大的飞行模式和实时调整配置能力。开发者在使用时应注意：

1. 严格遵守配置协议流程
2. 正确处理所有槽位，包括未使用的
3. 避免创建会产生冲突的配置
4. 动态计算槽位数量而非硬编码

理解这些扩展协议的工作原理，可以帮助开发者构建更稳定、功能更丰富的地面站软件，充分发挥Cleanflight飞控的潜力。

cleanflight Clean-code version of the baseflight flight controller firmware 项目地址: https://gitcode.com/gh_mirrors/cl/cleanflight