Skip to content
Mustafa Bay edited this page Nov 6, 2026 · 2 revisions

Build, experiment, and learn with two-wheel balancing robots.

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


1. Why dengebot?

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.

2. Supported Microcontrollers

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.

3. Main Library Features

Balancing Controller

The EDABalancePID component provides the balancing control foundation.

Features include:

  • Configurable PID control
  • Gyroscope-based derivative feedback
  • Integral management
  • Fault reporting
  • Controller state management

Sensor Fusion

EDAComplementaryFilter combines accelerometer-derived pitch and gyroscope angular velocity.

It supports fixed-alpha filtering, optional adaptive filtering, and gyroscope bias correction.

Motor Control

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.

Motor Calibration

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.

Safety Features

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.

4. Getting Started

  1. Download the latest dengebot release.
  2. Open Arduino IDE.
  3. Select Sketch → Include Library → Add .ZIP Library.
  4. Install the downloaded library.
  5. 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.

5. Available Examples

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

6. Version 1.7.6 — Development Status

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.

7. Safety First

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.

8. Testing and Validation

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.

9. Contributing

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.

Open an Issue

Read the Contributing Guide

10. Project Philosophy

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.

GitHub Repository | Releases | MIT License