Repository navigation
Home
Welcome to the official dengebot Wiki!
dengebot is an open-source, hardware-independent Arduino library designed for two-wheel self-balancing robots.
The project aims to make balancing control reusable, modular, and accessible across different microcontrollers, sensors, and motor configurations.
Rather than providing firmware for a single robot, dengebot separates the balancing controller from the underlying hardware.
Project: Gmby06/dengebot
Current pre-release: v1.7.6
License: MIT
Many self-balancing robot projects are written for a particular Arduino board, motor driver, or IMU sensor.
This makes it difficult to reuse their control algorithms with different hardware.
dengebot was created to explore a more portable approach.
Our main goals are:
- Hardware-independent balancing control
- Compatibility with resource-constrained microcontrollers
- Modular motor and sensor interfaces
- Safe and predictable control behavior
- Reusable PID and sensor-fusion components
- Clear documentation and reproducible testing
- Community collaboration and experimentation
The project was initially developed and physically tested using an Arduino Nano-based two-wheel robot, demonstrating that practical balancing control does not necessarily require a powerful microcontroller.
The library is designed for the Arduino ecosystem.
| Microcontroller | Compilation |
|---|---|
| Arduino Uno | Verified |
| Arduino Nano | Verified |
| Arduino Mega 2560 | Verified |
| ESP8266 | Verified |
| ESP32 | Verified |
| ESP32-S3 | Verified |
| Adafruit Gemma | Limited, inert example |
Important: Successful compilation does not guarantee physical balancing support for every board.
Some hardware-dependent features require additional platform-specific code.
The EDABalancePID component provides the balancing control foundation.
Features include:
- Configurable PID control
- Gyroscope-based derivative feedback
- Integral management
- Fault reporting
- Controller state management
EDAComplementaryFilter combines accelerometer-derived pitch and gyroscope angular velocity.
It supports fixed-alpha filtering, optional adaptive filtering, and gyroscope bias correction.
dengebot provides motor-command conversion utilities for different motor technologies.
DC Motors
PWM and direction control helpers are available for conventional DC motor drivers.
Stepper Motors — Experimental
Version 1.7.6 introduces STEP/DIR components and separate test examples for:
- A4988
- DRV8825
The current ESP32 LEDC adapter generates hardware-based STEP signals on classic ESP32 targets.
These examples are motor-only tests and do not yet constitute complete stepper-based balancing firmware.
The optional PWM calibration module allows users to identify motor breakaway thresholds without an encoder.
It supports separate measurements for left/right motors and forward/reverse directions, with manual confirmation.
EDASafetyGuard provides optional software protection, including:
- START/STOP control
- Sensor freshness monitoring
- Excessive tilt detection
- Controller fault handling
- Controlled re-arming
Software safety features cannot replace an independent hardware emergency stop or power cutoff.
- Download the latest dengebot release.
- Open Arduino IDE.
- Select Sketch → Include Library → Add .ZIP Library.
- Install the downloaded library.
- Open an example compatible with your microcontroller.
Include the library in your sketch:
#include <dengebot.h>The library does not automatically detect your IMU, configure motor-driver pins, or start motors.
Your application must supply valid sensor measurements and integrate the appropriate motor-output hardware.
| Example | Description |
|---|---|
| BasicBalance | Basic balancing controller demonstration |
| MotorCommandDemo | Motor command conversions |
| FilterTelemetryDemo | Sensor fusion and telemetry |
| GyroBiasCalibrationDemo | Gyroscope bias calibration |
| DeadZoneDemo | DC motor dead-zone compensation |
| SafetyGuardDemo | START/STOP and fault management |
| PwmCalibrationDemo | Manual PWM breakaway calibration |
| ESP32_StepDirFirstTest | Experimental STEP/DIR motor test |
| ESP32_A4988_Demo | A4988 driver test |
| ESP32_DRV8825_Demo | DRV8825 driver test |
Version 1.7.6 is currently available as a pre-release.
This version introduces separate A4988 and DRV8825 demonstration sketches and improvements to the STEP/DIR development infrastructure.
GitHub Actions checks have successfully completed the configured host tests and Arduino compilation jobs, including ESP32 core versions 2.0.17 and 3.0.7.
Still under development:
- Hardware verification of STEP/DIR pulse timing and motor operation
- Broader platform-specific STEP/DIR motor backends
- First-run hardware verification
- IMU axis and sign validation
- Motor-direction confirmation
- PASS/FAIL and user-confirmation procedures
- Complete reference examples for additional hardware combinations
These capabilities are planned or experimental and must not be confused with fully validated hardware support.
Self-balancing robots can move unexpectedly, particularly during calibration, debugging, or incorrect motor-direction configuration.
Before testing:
- Secure the robot with its wheels raised.
- Verify motor-driver wiring and power requirements.
- Set appropriate current limits.
- Confirm motor directions before enabling balancing.
- Provide an accessible physical power disconnect.
- Never assume a software watchdog can stop a motor after the microcontroller locks up.
Always start with controlled, low-risk experiments.
dengebot uses several verification levels:
Host tests: Validate control logic and software behavior.
Arduino compilation: Check source compatibility across configured board packages.
Physical hardware testing: Verify real sensor, motor, timing, and safety behavior.
These results are not interchangeable.
A successful compilation does not prove that a robot will balance successfully or operate safely.
dengebot welcomes developers, students, hobbyists, researchers, and robotics enthusiasts.
Contributions may include:
- Testing on different Arduino boards
- Hardware compatibility reports
- Bug reports and reproducible examples
- Documentation improvements
- New motor-driver integrations
- Performance measurements
- Example projects
If you encounter a problem, please include your board, IMU, motor driver, library version, power supply, and relevant test results.
One balancing library. Different hardware. Shared knowledge.
dengebot is intended to evolve through careful testing, backward-compatible improvements, and community feedback.
The long-term objective is to provide a flexible foundation for experimenting with two-wheel balancing systems, from simple Arduino Nano robots to more advanced ESP32-based platforms.
Developed by Mustafa Bay (Gmby06)
Open-source robotics development.