BETAFLIGHT CLI教程 带有串口软件进入cli模式教程

Betaflight 的 CLI（命令行界面）看似复杂，其实核心是 “用简单命令完成图形界面做不到的配置”—— 比如硬件引脚重映射、批量参数修改、传感器适配等。下面从 “入门准备→进入 CLI→核心命令→实战场景→避坑指南” 一步步讲透，全程结合实例，新手也能跟着操作。

一、先搞懂：CLI 到底是干啥的？为什么要用它？

CLI 是 Betaflight 提供的 “高级配置入口”，图形界面（如 Betaflight Configurator 的 “设置”“接收机” tab）能搞定 80% 基础配置，但剩下 20% 关键操作（比如你之前关注的陀螺仪引脚映射、电机端口修复、批量参数备份）必须用 CLI 完成。简单说：图形界面是 “傻瓜式按钮”，CLI 是 “手动输入指令”，但能实现更灵活的定制。

二、第一步：准备工作（3 分钟搞定）

在进入 CLI 前，先做好这 2 件事，避免连接失败或配置丢失：

1. 硬件连接

• 飞控供电：用 USB 线连接飞控（或通过 USB 转串口模块连接，如 FTDI 模块），不要插电池（避免电机误启动，安全第一）；
• 卸螺旋桨：如果飞控已接电机，务必卸下螺旋桨，防止 CLI 配置时电机突然转动。

2. 软件准备

• 安装 Betaflight Configurator（地面站）：官网下载最新版（https://github.com/betaflight/betaflight-configurator/releases），支持 Windows/macOS/Linux；
• 连接飞控：打开地面站，点击右上角 “端口” 下拉框，选择飞控对应的串口（如 COM3），波特率默认 115200（摘要 1、3 均提及），点击 “连接” 按钮，待地面站显示飞控信息（如固件版本、传感器状态），说明连接成功。

三、第二步：进入 CLI（2 种方式，新手优先第一种）

Betaflight 提供两种进入 CLI 的方式，新手优先用 “地面站内置 CLI”，简单无门槛；进阶用户可用品 “串口工具”（如 PuTTY）。

方式 1：通过 Betaflight Configurator 进入（推荐新手）

1. 飞控连接地面站后，点击左侧菜单栏的 CLI 选项卡（图标是 “命令行” 样式）；
2. 进入后会看到一个黑色输入框，下方有 “输入命令” 的提示，这就是 CLI 操作界面；
3. 测试：在输入框中输入 help，按回车，会显示所有支持的 CLI 命令列表（摘要 1、6 提及），说明 CLI 正常工作。

方式 2：通过串口工具进入（进阶，适合无地面站场景）

如果地面站无法启动，可用品 PuTTY、SecureCRT 等串口工具：

1. 打开串口工具，选择飞控对应的串口（如 COM3），波特率设为 115200（摘要 1 明确默认波特率），数据位 8、停止位 1、校验位无；
2. 点击 “打开”，然后在串口界面输入 # 字符（摘要 1 要求），会看到 CLI 欢迎信息（如 “Betaflight CLI”），表示进入成功；
3. 后续操作和地面站 CLI 完全一致，只是界面不同。

四、第三步：CLI 核心命令详解（必学 10 个，附实例）

CLI 命令虽多，但新手只需掌握以下 10 个核心命令，就能应对 90% 场景。每个命令都按 “作用 + 语法 + 实例 + 注意事项” 讲解，结合你之前关注的 “陀螺仪适配”“引脚映射” 场景。

1. 基础操作命令（3 个，必记）

（1）help：查看所有命令（不懂就查它）

• 作用：列出所有支持的 CLI 命令，及每个命令的简要说明；
• 语法：直接输入 help 按回车；
• 实例：输入 help 后，会看到类似内容：

  plaintext

  Commands:
  adjrange   - show/set adjustment ranges settings
  aux        - show/set aux settings
  beeper     - configure beeper
  dump       - print configurable settings
  exit       - exit CLI without saving
  feature    - list or enable/disable features
  get        - get variable value
  help       - show this help message
  save       - save settings and reboot
  set        - set variable value
  status     - show system status
  

• 注意：如果记不清某个命令的用法，输入 help 命令名（如 help set），会显示该命令的详细用法。

（2）save：保存配置（修改后必执行）

• 作用：将 CLI 中修改的参数保存到飞控闪存，不执行 save 则配置会丢失；
• 语法：直接输入 save 按回车；
• 实例：修改陀螺仪引脚后，输入 save，飞控会提示 “Saved, rebooting...”，然后自动重启；
• 注意：save 会触发飞控重启，重启后地面站可能需要重新连接。

（3）exit：退出 CLI 不保存

• 作用：放弃所有未保存的修改，退出 CLI（或重启飞控）；
• 语法：直接输入 exit 按回车；
• 场景：修改参数后发现错误，不想保存，用 exit 放弃，避免影响原有配置。

2. 参数查看与修改（2 个，最常用）

（1）get：查看参数当前值

• 作用：查看某个参数的当前设置（如陀螺仪总线、电机 PWM 协议、电池电压阈值）；
• 语法：
  • 查看指定参数：get 参数名（如 get gyro_1_spibus）；
  • 查看一类参数：get 关键词（如 get gyro，会列出所有含 “gyro” 的参数）；
• 实例 1：查看陀螺仪使用的 SPI 总线（你之前关注的场景）：输入 get gyro_1_spibus，回车后显示：

  gyro_1_spibus = 2
  

  表示陀螺仪 1 使用 SPI2 总线（1=SPI1，2=SPI2，3=SPI3）；
• 实例 2：查看电机 PWM 协议：输入 get motor_pwm_protocol，回车后显示：

  motor_pwm_protocol = DSHOT600
  

  表示电机使用 DSHOT600 协议；
• 注意：参数名区分大小写，输入时需准确（可输入部分关键词按 Tab 键自动补全，如输入 get gyro 按 Tab，会自动补全相关参数）。

（2）set：修改参数值

• 作用：修改某个参数的设置（如陀螺仪地址、电机最小油门、GPS 救援模式）；
• 语法：set 参数名 = 值（等号前后可加空格，也可不加）；
• 实例 1：修改陀螺仪 I2C 地址（适配 MPU6050，摘要 5 的场景）：如果 MPU6050 的 AD0 引脚接高电平（地址 0x69，十进制 105），输入：

  set gyro_i2c_address = 105
  

  回车后显示 “gyro_i2c_address = 105”，表示修改成功，需执行 save 生效；
• 实例 2：开启 GPS 无定位时允许解锁（摘要 6 的场景）：输入 set gps_rescue_allow_arming_without_fix = ON，回车后保存；
• 注意：修改后必须执行 save，否则参数不会生效；如果不知道参数的取值范围，可先 get 查看默认值，或参考官方文档（如 vtx_power 取值 0-5，对应不同功率）。

3. 硬件资源配置（1 个，核心：引脚映射）

resource：重映射引脚功能（解决硬件适配问题）

• 作用：将飞控的引脚与具体功能绑定（如 “把 PB12 引脚设为陀螺仪 CS”“把 A06 引脚设为电机 1”），这是你之前最关注的 “陀螺仪引脚配置” 核心命令（摘要 1、4、6 均重点提及）；

• 语法：

  • 映射功能到引脚：resource 功能类型 序号 引脚（如 resource GYRO_CS 1 B12）；
  • 取消映射：resource 功能类型 序号 NONE（如 resource GYRO_CS 1 NONE）；
  • 查看所有映射：resource list（列出所有引脚的功能分配）；

• 关键概念：

  • 功能类型：如 GYRO_CS（陀螺仪片选）、MOTOR（电机）、SPI_SCK（SPI 时钟）、I2C_SCL（I2C 时钟）；
  • 序号：如 MOTOR 1 表示电机 1，GYRO_CS 1 表示第一个陀螺仪；
  • 引脚：格式为 “字母 + 数字”（如 B12、A05，对应飞控芯片的引脚编号，需参考芯片手册）；

• 实例 1：配置陀螺仪 SPI 引脚（你之前的飞控场景）：要将陀螺仪接 SPI2 总线，引脚映射命令如下（对应 STM32F405 芯片）：

  // 1. 映射SPI2总线的SCK/MISO/MOSI引脚
  resource SPI_SCK 2 B13    // SPI2的时钟引脚 → B13
  resource SPI_MISO 2 B14   // SPI2的数据输入引脚 → B14
  resource SPI_MOSI 2 B15   // SPI2的数据输出引脚 → B15
  // 2. 映射陀螺仪CS引脚（片选）
  resource GYRO_CS 1 B12    // 陀螺仪1的CS引脚 → B12
  // 3. 保存生效
  save
  

  执行后，飞控会将 SPI2 总线与陀螺仪绑定，重启后即可识别；

• 实例 2：修复损坏的电机引脚（摘要 6 的场景）：如果电机 2 的原引脚 A07 损坏，想将其映射到空闲的 A10 引脚：

  // 1. 取消电机2原有的A07映射
  resource MOTOR 2 NONE
  // 2. 将电机2映射到A10引脚
  resource MOTOR 2 A10
  // 3. 保存生效
  save
  

• 注意：引脚必须是飞控芯片支持的 “功能引脚”（如 SPI_SCK 必须用芯片手册中标注的 SPI 总线引脚，不能用普通 GPIO），否则配置无效。

4. 配置备份与恢复（2 个，避免配置丢失）

（1）diff：备份用户修改的配置（推荐）

• 作用：只导出 “用户修改过的参数”（默认值不导出），备份文件小，恢复时不覆盖新固件的默认值（摘要 1、3 重点推荐）；
• 语法：
  • 备份当前配置：diff（只导出当前 PID 和速率配置）；
  • 备份所有配置：diff all（导出所有修改过的配置，包括多个 PID profile）；
• 实例：备份所有用户配置：输入 diff all，回车后 CLI 会输出所有修改过的命令，如：

  # diff all
  board_name GETFUNF405V3
  manufacturer_id GFUN
  resource GYRO_CS 1 B12
  resource SPI_SCK 2 B13
  set gyro_1_spibus = 2
  set motor_pwm_protocol = DSHOT600
  set min_throttle = 1070
  

  将这些内容复制到记事本，保存为 “backup_diff.txt”，就是你的配置备份；
• 优势：恢复时只执行这些修改过的命令，不会覆盖新固件的优化默认值（如摘要 1 提到 “避免盲目恢复备份导致无法受益于新默认值”）。

（2）dump：导出所有配置（包括默认值）

• 作用：导出飞控的所有参数（包括默认值），备份文件大，但能完整复制飞控配置；
• 语法：
  • 导出当前配置：dump；
  • 导出指定配置文件：dump profile 1（导出 PID profile 1）、dump rates（导出速率配置）；
• 实例：导出所有配置：输入 dump，回车后 CLI 会输出上千行命令，包括引脚映射、参数设置、功能开关等；
• 场景：需要完整复制飞控配置到另一块相同飞控时使用，新手优先用 diff 备份（更简洁）。

5. 状态查看与调试（2 个，排错必备）

（1）status：查看飞控整体状态

• 作用：快速查看飞控的核心状态（固件版本、传感器识别、电池电压、CPU 负载），是排错的第一步（摘要 4、5、6 均提及）；
• 语法：直接输入 status 按回车；
• 实例：查看陀螺仪是否识别成功（你关心的场景）：输入 status 后，显示类似内容：

  System status: OK
  MCU: STM32F405
  Firmware: Betaflight / S405 4.5.1
  Gyro: MPU6500 (SPI2)
  Gyro CS pin: B12
  Battery voltage: 3.81V
  CPU load: 5%
  

  关键信息解读：
  • Gyro: MPU6500 (SPI2)：陀螺仪识别为 MPU6500，使用 SPI2 总线；
  • System status: OK：飞控无硬件故障；
• 场景：陀螺仪不识别时，先输 status，若显示 “No gyro detected”，再排查硬件接线或引脚配置。

（2）i2c probe：扫描 I2C 总线设备

• 作用：扫描 I2C 总线上的设备（如 I2C 陀螺仪 MPU6050、磁力计 HMC5883L），判断设备是否正常连接（摘要 5 的排错场景）；
• 语法：直接输入 i2c probe 按回车；
• 实例：扫描 I2C 总线找 MPU6050：输入 i2c probe 后，显示：

  Probe I2C bus 1:
  Address 0x68: Found device
  Address 0x1E: Found device
  

  解读：
  • 0x68：MPU6050 的默认 I2C 地址（AD0 接地）；
  • 0x1E：HMC5883L 磁力计的地址；若未显示 0x68，说明 MPU6050 未连接或接线错误；
• 注意：只对 I2C 设备有效，SPI 设备（如 MPU6500）无法用此命令扫描。

五、第四步：实战场景（3 个，解决实际问题）

结合你之前关注的 “陀螺仪适配”“硬件故障修复”，用 CLI 解决 3 个常见问题，巩固命令用法。

场景 1：适配 I2C 陀螺仪 MPU6050（AD0 接高电平）

问题：MPU6050 的 AD0 引脚接高电平，地址变为 0x69（十进制 105），飞控默认扫描 0x68，无法识别。解决步骤：

1. 进入 CLI，输入 i2c probe，确认 I2C 总线是否有 0x69 设备：

   Probe I2C bus 1:
   Address 0x69: Found device
   

2. 修改陀螺仪 I2C 地址：

   set gyro_i2c_address = 105  // 105是0x69的十进制
   

3. 保存配置：

   save
   

4. 验证：重启后输入 status，显示 “Gyro: MPU6050”，说明适配成功。

场景 2：修复损坏的电机 2 引脚

问题：电机 2 的原引脚 A07 损坏，想将其映射到空闲的 A10 引脚。解决步骤：

1. 查看当前电机引脚映射：

   resource list | grep MOTOR  // 筛选电机相关映射
   

   显示：

   A06: MOTOR 1
   A07: MOTOR 2  // 损坏的引脚
   A08: MOTOR 3
   A09: MOTOR 4
   A10: MOTOR 5  // 空闲引脚
   

2. 取消电机 2 原映射，重新映射到 A10：

   resource MOTOR 2 NONE  // 取消A07的电机2映射
   resource MOTOR 2 A10   // 将电机2映射到A10
   

3. 保存配置：

   save
   

4. 验证：进入 “电机” tab，测试电机 2，A10 引脚对应的电机应正常转动。

场景 3：备份飞控配置到新飞控

问题：旧飞控配置调试好，想复制到新的相同型号飞控。解决步骤：

1. 旧飞控进入 CLI，输入 diff all，复制输出的所有命令，保存为 “backup.txt”；
2. 新飞控刷写相同版本固件，进入 CLI，将 “backup.txt” 中的命令全部粘贴到输入框，按回车；
3. 输入 save，新飞控重启后，配置与旧飞控完全一致。

六、避坑指南（5 个新手常犯错误，提前规避）

1. 命令拼写错误：CLI 命令区分大小写，且参数名必须准确（如 gyro_1_spibus 不能写成 gyro1_spibus），不确定时用 get 关键词 查找（如 get gyro）；
2. 忘记 save：修改参数后必须输 save 才能生效，否则重启后配置丢失；
3. 插电池操作：CLI 配置时不要插电池，避免电机误启动（即使卸了螺旋桨，也可能损坏电调）；
4. 引脚乱映射：resource 命令的引脚必须是飞控芯片支持的功能引脚（如 SPI_SCK 必须用芯片手册中的 SPI 总线引脚），不能用普通 GPIO 引脚模拟；
5. 盲目恢复备份：不同固件版本的参数可能有变化，恢复旧备份前，先输 dump 查看新固件默认值，避免参数不兼容（摘要 1 提醒 “不要盲目恢复备份，需受益于新默认值”）。