# 舵机控制 ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- 本项目是一个基于Quectel Pi M2智能主控板实现的二自由度舵机云台控制示例。 系统通过PCA9685舵机驱动板驱动二维云台上的两只LFD-01舵机，结合图形界面实现滑块、按钮、快捷键与自动演示等多种操控方式，左侧3D视图与实物同步转动，完整展示"UI角度指令 → PWM脉宽 → 舵机实际姿态"的控制链路。 ```{image} images/image_FBbnbES6SoziyMxvTMmcAi15n4g.webp :width: 1192px :height: 670px :align: center ``` # 开发资源汇总 ## 开发配件清单 ```{note} ``` |   |   |   | | --- | --- | --- | | **配件名称** | **数量** | **规格参数** | | Quectel Pi M2智能主控板 | 1块 | - | | PCA9685舵机驱动板 | 1块 | [16路PWM 舵机驱动板模块]() | | 二维舵机云台（含摄像头） | 1个 | [二维舵机云台含摄像头]() | | 双路降压稳压模块 | 1个 | [可调降压稳压模块]() | | 18650电池盒（2S） | 1个 | [18650锂电池组7.4v]() | | 显示屏（可选） | 1个 | 有HDMI显示器也可 | | 杜邦线/万用表/螺丝刀 | 若干 | - | ## 配件实物参考 ```{image} images/image_Pw09bXEwSovi6SxR5lTc4UNCnno.webp :width: 912px :height: 437px :align: center ``` # 快速上手 ## 开发准备 **Quectel Pi M2** 智能主控板出厂默认搭载 **Debian 13** 系统镜像，因此无需再次烧录镜像，仅需按照如下步骤操作即可。 ## 硬件连接 完成以下所有硬件连接操作，序号与接口示意图保持一致： ```{image} images/image_KUCbbALRKoELHcxuZVycVvdYnQR.webp :width: 627px :height: 463px :align: center ``` 1. **信号连接**：将PCA9685驱动板与 **Quectel Pi M2** 40pin排针按如下对应关系连接—— **Pin1(3.3V)→VCC**、**Pin9(GND)→GND**、**Pin27(SDA)→SDA**、**Pin28(SCL)→SCL**（即 `/dev/i2c-7`）。 2. **动力连接**：电池盒正负极接入稳压模块IN端（建议串电源开关/保险）；稳压模块 **固定5V输出口** 接入 **Pin2/Pin4** 给主控板回灌供电（也可使用Type-C给开发板供电，但是注意两者不能同时供电）；稳压模块 **自定义口调至5.0~5.5V** 后接入PCA9685**V+**端子给舵机提供动力电。 3. **共地连接**：将稳压模块GND与 **Quectel Pi M2** 的 **Pin9**、PCA9685的GND连接至同一节点——**共地是I2C通信正常的前提，务必接好**。 4. **舵机连接**：舵机2（偏航YAW）信号线接PCA9685 **CH0**，舵机1（俯仰PITCH）信号线接 **CH1**；两只舵机电源线并联接入V+/GND排针。注意LFD-01线序 **棕/红/橙=GND/5V/信号**，接反会烧毁舵机。 5. **供电连接**：最后开启电池开关即可——稳压模块同时为主控板与舵机供电；程序启动后会自动下发"校正后的归中位置"，云台上电即居中，无需再分两步先后上电。 > Note:tips > > 连接完成后可用 i2cdetect -y 7 验证，输出显示 0x40 即代表PCA9685通信正常。VCC（逻辑电，数mA）与V+（动力电，≥1A）务必分离供电，不可混接。 ## 项目实现 ### 获取代码 在智能主控板上打开终端，使用git克隆项目代码。 ```bash sudo apt update sudo apt install -y git git clone https://github.com/Quectel-Pi/demo-servo-gimbal-control.git ``` 执行完成后，当前目录下应生成*demo-servo-gimbal-control*文件夹。 ### 安装依赖 进入工程目录，创建隔离环境并安装Python依赖。 ```bash cd demo-servo-gimbal-control python3 -m venv .venv .venv/bin/pip install -r requirements.txt ``` ### 运行程序 ```bash python3 run_gimbal.py ``` *run_gimbal.py* 会自动定位工程内的隔离环境并补全显示授权，随后启动程序；若程序正常启动，会弹出 **Servo Control Center** 窗口，左侧为3D实物视图，右侧为控制面板。 ## 操控方式 > 左侧 3D 视图 + 右侧控制面板，拖动滑块/快捷键/演示时 3D 与实物 **同步平滑转动**；状态灯绿色 `I2C connected: /dev/i2c-7 · 0x40` 为实机在线，琥珀色 `Simulation mode` 为仿真。 |   |   | | --- | --- | | 操控方式 | 控制功能 | | 拖动Yaw滑块 | 偏航角度调节 | | 拖动Pitch滑块 | 俯仰角度调节 | | `◀−5 / Center / +5▶` | 偏航步进/归中 | | `▼−5 / Center / +5▲` | 俯仰步进/归中 | | 键盘 `A`/`D` | 偏航±5° | | 键盘 `W`/`S` | 俯仰±5° | | 键盘 `Space` | 双轴归中 | | `Left/Up/Right/Down` | 一键预设姿态 | | `▶ Auto Demo` | 自动演示（3周期扫掠） | # 应用演示
servo_control_demo
# 常见问题及解决方案 ## 程序显示Simulation mode **现象：** ```plaintext Simulation mode (no PCA9685 on /dev/i2c-7) ``` **解决方案：** - 检查PCA9685供电是否正常：V+端子应量到5.0~5.5V电压。 - 使用命令确认总线与芯片是否在位： ```shell ls /dev/i2c-7 i2cdetect -y 7 ``` - 确认SDA/SCL是否接反、共地是否接好（稳压模块GND↔Pin9）。 - 检查 `smbus2` 是否已安装，必要时重新执行依赖安装步骤。 ## 舵机有电（卡紧）但完全不动 **现象：** ```plaintext i2cdetect -y 7 能看到0x40，舵机有阻力但完全不转动 ``` **解决方案：** 该现象通常是PCA9685芯片进入SLEEP休眠所致，本程序已内置 **唤醒强制清SLEEP位 + 每秒保醒自愈** 机制，升级到当前版本并重启程序即可自愈。 - 若重启后仍不动，检查板上 **OE** 引脚是否接地（悬空/接高电平会禁用全部输出）。 ## 舵机转动时抖动/异响 **现象：** 云台运动过程中舵机出现抖动或异响。 **解决方案：** - 多为稳压模块纹波偏大或电压跌落引起，可在V+/GND端并接1000µF电解电容。 - 确认自定义口输出电压处于5.0~5.5V区间，避免低于4.5V或长期高于6V。 ## 舵机只有一侧转动 **现象：** 偏航或俯仰只有其中一轴响应。 **解决方案：** - 检查对应CH通道信号线连接（CH0=偏航、CH1=俯仰）。 - 检查该舵机电源线是否接好，可用万用表测量V+/GND电压。 # 技术支持与贡献 如在使用过程中遇到问题，欢迎在 [移远官方论坛]() 提交技术咨询，我们的技术支持团队将及时为您解答。 项目开源地址： https://github.com/Quectel-Pi/demo-servo-gimbal-control 欢迎提交Issue反馈问题或Pull Request贡献代码改进！