bus_dc_motor_driver

Backward-compatible four-channel DC motor driver with optional encoder RPM, independent PID control and supply voltage monitoring

1.1.0 yangcong-bit 更新时间: 2026-11-09
安装包
本地安装
mpremote mip install https://upypi.net/pkgs/bus_dc_motor_driver/1.1.0
远程安装
mip.install("https://upypi.net/pkgs/bus_dc_motor_driver/1.1.0")
版本选择
README

BusDCMotor(MicroPython)

BusDCMotor 是 I2C 四路直流电机驱动库,面向基于 PCA9685 与 SS6285L 的总线电机模块。保留原有开环调速、方向、停止与刹车接口,并提供可选编码器反馈、四路独立 PID 和供电电压查询。

版本:1.1.0。包名:bus_dc_motor_driver。

主要功能

  • 最多四路电机独立调速、正反转、停止及刹车。
  • 可选 AB 编码器累计计数、方向和输出轴 RPM 查询。
  • 独立 PID、在线目标转速与增益设置。
  • 开环、PID 和刹车模式隔离。
  • 可配置无反馈保护、故障查询及显式恢复。
  • 可选 ADC 电压监测,按实际分压比换算。

环境与安装

需要支持 machine、time、math、ustruct、micropython 的 MicroPython 固件。编码器采用 GPIO 中断计数。可选电压监测依赖 ADC 的 read_uv() 与相应衰减配置;不使用电压功能时无需初始化 ADC。

设备联网后可使用 mip 安装:

import mip
mip.install("https://upypi.net/pkgs/bus_dc_motor_driver/1.1.0")

也可以将 code/ 下七个运行文件复制到设备的 /lib/。七个文件需要配套更新。

文件 用途
bus_dc_motor.py BusDCMotor 公开入口与模式管理
pca9685.py I2C 与 PWM 输出
motor.py 双输入电机控制
encoder.py 编码器计数、方向和转速换算
pid.py PID 计算
motor_controller.py 多路反馈与闭环调度
voltage_monitor.py 电压采样与换算

接线

电机电源与主控共地,SDA、SCL 接入主控 I2C,引脚电平应与主控匹配。电机供电按实际电机和模块规格选择。

每路电机占用两个 PCA9685 通道:M1 为 CH0/CH1,M2 为 CH2/CH3,M3 为 CH4/CH5,M4 为 CH6/CH7。I2C 地址按模块地址配置填写。

编码器 A/B 相连接到可用 GPIO;PPR、减速比与方向需要与实际电机对应。当前计数方式为 A 相上升沿计数、B 相判断方向。

快速开始

下面使用 ESP32-C3 的 SCL=GPIO9、SDA=GPIO10 和地址 0x4F 作为接线示例。按实际接线修改后,显式开启 ARM_MOTORS 才运行电机。

import time
from machine import Pin, I2C
from pca9685 import PCA9685
from bus_dc_motor import BusDCMotor

ARM_MOTORS = False

def main():
    if not ARM_MOTORS:
        print("Motion disabled. Check wiring before enabling.")
        return
    i2c = I2C(0, scl=Pin(9), sda=Pin(10), freq=400000)
    motor = None
    try:
        if 0x4F not in i2c.scan():
            raise OSError("Motor module not found at 0x4F")
        pca = PCA9685(i2c, 0x4F)
        motor = BusDCMotor(pca, 4, startup_brake=False)
        motor.set_motor_speed(1, 1900, 0)
        time.sleep(2)
        motor.stop_motor(1)
    finally:
        try:
            if motor is not None:
                motor.deinit()
        finally:
            i2c.deinit()

main()

旧接口 speed 为 1900~4095 的 PWM 数值,方向 0 为正转、1 为反转,不表示 RPM 或百分比。break_motor() 保留原拼写,表示双输入置高刹车。

构造器默认保留原库刹车行为;新应用使用 startup_brake=False,让初始化保持关闭输出。模块默认 PWM 为 1000Hz,各通道共享频率。

编码器与 PID

创建控制器时指定每路编码器 A/B 引脚、PPR 和减速比。以下参数是配置写法,GPIO、计数分辨率、目标和 PID 增益应按应用选择。

motor = BusDCMotor(
    pca,
    4,
    encoder_pins=((5, 6), (7, 8), (3, 2), (1, 0)),
    ppr=13,
    gear_ratio=20,
    startup_brake=False,
    output_limit=(-50, 50),
)
motor.set_pid(1, 0.15, 0.6, 0)
motor.set_target_rpm(1, 30)
motor.start_motor(1)

设置目标不会自动启动;应用需要持续调用 motor.update()。默认控制周期为 100ms,到达周期才更新。运行中可直接改变目标正负号实现换向,也可使用 set_target_rpms() 一次设置四路不同目标。结束时调用 stop_all() 或 deinit()。

PID 增益不是所有电机和负载的通用值。output_limit 限制输出百分比,integral_limit 限制尚未乘 Ki 的积分状态。一个电机同一时刻只采用一种输出模式;开环调速会退出该路 PID。

常用接口

接口 说明
set_motor_speed(id, speed, direction=0) 旧开环调速接口
stop_motor(id) / stop_all() 立即停止并禁用对应 PID,保留目标
break_motor(id) 退出 PID 并刹车
set_target_rpm(id, rpm) / set_target_rpms(rpms) 设置带符号目标 RPM
set_pid(id, kp, ki, kd) 设置 PID 增益,None 保留对应原值
start_motor(id) / start_all() 显式启用闭环,下次 update 输出
update() 周期采样、闭环更新及可选电压缓存更新
get_motor_rpm(id) 最近一次更新的实际 RPM
get_encoder_count(id) / get_encoder_direction(id) 累计计数与最近脉冲方向
get_modes() / get_telemetry() 模式与遥测快照
get_voltage() 可选电压监测器的缓存电压
configure_feedback_protection(**settings) 配置无反馈保护
get_feedback_protection() / get_faults() 查询配置与锁存故障
clear_faults(id=None) 再次关闭输出成功后清故障,不自动启动
deinit() 停止电机并释放本对象创建的编码器 IRQ

无反馈保护与资源管理

配置编码器后默认启用无反馈保护。PID 已启用、目标非零且输出超过阈值时,持续无计数达到超时,并结束启动/换向宽限,才触发 no_feedback。默认宽限 4000ms、超时 2500ms、PWM 阈值 25%、停机策略 all;这些参数应按应用配置。

故障会锁存,停止对应输出并清除 PID 积分。默认策略停止全部电机,也可配置 stop_policy="motor" 仅停止故障路。查询原因、排除问题后,分别调用 clear_faults() 和 start_motor() / start_all();改目标、恢复反馈或继续 update 不会自行重启。

保护只随 update() 执行,不覆盖开环自身的反馈缺失。主循环停止调度或 I2C 完全失联时,软件无法保证物理输出已经关闭。换向时先关闭旧方向输入,成功后再开启新方向;I/O 异常会尽力关闭其余通道并保留原异常。

BusDCMotor.deinit() 不释放调用方注入的 PCA9685、电压监测器和 I2C。应用应在正常退出和异常路径中关闭自己创建的资源;共享总线由其所有者管理。

联系方式

如有任何问题或需要帮助,请通过以下方式联系开发者:

📧 邮箱:a413liqingshui@gmail.com

💻 GitHub:https://github.com/FreakStudioCN


许可协议

MIT License

Copyright (c) 2025 FreakStudio

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
文件列表
Name Size Type
LICENSE 1.0KB File
README.md 7.9KB Doc
code/bus_dc_motor.py 32.4KB Python
code/encoder.py 8.1KB Python
code/motor.py 6.0KB Python
code/motor_controller.py 32.1KB Python
code/pca9685.py 10.3KB Python
code/pid.py 11.0KB Python
code/voltage_monitor.py 7.6KB Python
package.json 913B Conf