Skip to content

Latest commit

 

History

History
180 lines (118 loc) · 4.01 KB

README.md

File metadata and controls

180 lines (118 loc) · 4.01 KB

DRV8833

DRV8833 is a lightweight PlatformIO library for driving dual DC motors on the ESP32 using the DRV8833 dual H-bridge motor driver and the ESP32 LEDC (PWM) peripheral.

The library provides a clean, human-friendly API for direction and speed control, while handling PWM scaling, dead-zone compensation, and safety guards internally.

Overview

DRV8833 is designed to simplify common dual-motor use cases in ESP32 projects by providing:

  • A normalized speed control interface (-100 … +100)
  • Safe initialization handling to prevent undefined GPIO behavior
  • ESP32-native hardware PWM via LEDC
  • Dead-zone compensation for low-speed motor stability

The library intentionally focuses on DC motor control only and does not attempt to implement closed-loop control, current sensing, or encoder feedback.

Features

  • ESP32 LEDC-based PWM motor control
  • Direction control with signed speed input
  • Normalized speed range (-100 … +100)
  • Configurable dead-zone compensation
  • Safe guards against uninitialized motor access
  • Deterministic LEDC channel allocation
  • Minimal and extensible API surface
  • Designed for ESP32 + Arduino framework

Platform Support

  • ESP32 only

This library relies on the ESP32 LEDC hardware PWM peripheral and is not portable to AVR or other microcontrollers without modification.

Dependencies

  • Arduino framework for ESP32

No external libraries are required.

Installation

PlatformIO (GitHub source)

Add the following to your platformio.ini:

lib_deps =
  https://github.com/tabah-mly/drv8833.git

Local Library

Alternatively, place the library in your project’s lib directory:

lib/
└── drv8833/
    ├── include/
    │   └── DRV8833.h
    └── src/
        └── DRV8833.cpp

Basic Usage

Include and Initialize

#include <DRV8833.h>

DRV8833 motor;

void setup() {
  motor.setDeadZone(10);

  motor.set(0, 25, 26); // Motor A
  motor.set(1, 27, 14); // Motor B

}

void loop () {
  // forward
  motor.drive(0, 100);
  motor.drive(1, 100);

  delay(2000);

  // reverse
  motor.drive(0, -100);
  motor.drive(1, -100);
  
  delay(2000);
}

Motor pins must be assigned using set() before calling drive().

API Reference

set

Assigns GPIO pins to a motor and initializes PWM channels.

driver.set(id, in1, in2);

Parameters

Name Type Description
id uint8_t Motor index (0 or 1)
in1 uint8_t GPIO pin connected to IN1
in2 uint8_t GPIO pin connected to IN2

drive

Stops any currently playing tone.

driver.drive(id, speed);

Parameters

Name Type Description
id uint8_t Motor index
speed int8_t Speed value (-100 … +100)
  • Positive values rotate forward
  • Negative values rotate reverse
  • Zero stops the motor (coast)

setDeadZone

Sets the dead-zone threshold used to compensate for static friction.

driver.setDeadZone(value);

Parameters

Name Type Description
value int8_t Dead-zone value (0 … 100)

Design Considerations

  • PWM output is implemented using the ESP32 LEDC peripheral
  • Speed control is normalized and mapped internally to PWM duty
  • Dead-zone handling is symmetric for forward and reverse directions
  • Safety guards prevent motor access before initialization
  • Braking behavior is not enabled by default (coast mode)

Project Status

DRV8833 is currently in development (v1.0.0-dev). The API and internal logic are implemented, but hardware validation on a physical DRV8833 board is still pending. Minor behavior changes may occur after real-world testing.

Roadmap

Planned enhancements include:

  • Acceleration ramping (soft start / stop)
  • Brake vs coast mode selection
  • Per-motor dead-zone configuration
  • Optional encoder integration
  • Extended motor count support

License

This project is licensed under the MIT License.

Author

Tabah Mulya

GitHub: https://github.com/tabah-mly