Deutsch | English

MausDroid

ESP32-based embedded robotics showcase with FreeRTOS, Time-of-Flight sensors, motor/servo control, telemetry and a CoppeliaSim test bridge.

Status: prototype / technical showcase. This repository is intended to demonstrate embedded software architecture, sensor integration, safety-aware drive logic and simulation coupling. It is not maintained as a ready-to-use product or general-purpose robotics kit.

Project Scope

MausDroid is a mobile indoor robot platform built around an ESP32 WROVER. The project combines mechanical prototyping, electronics, sensor evaluation and firmware design into one practical embedded system.

The core idea is a modular control stack:

• read and validate distance sensors independently from the drive logic
• convert already processed sensor states into safe drive commands
• keep time-critical movement and safety decisions independent from telemetry
• make the drive logic reusable in both the real vehicle and CoppeliaSim
• model fault states explicitly instead of treating missing data as free space

What This Demonstrates

• Embedded C/C++ development on ESP32
• FreeRTOS-oriented task separation and timing awareness
• Hardware abstraction for I2C, PWM, ToF sensors and actuator output
• Safety-aware state logic for a mobile robot
• Distance sensor processing with validity checks and calibrated thresholds
• Simulation-assisted testing with CoppeliaSim and a C++ bridge
• Telemetry and logging for debugging movement decisions
• Incremental architecture work from prototype toward testable modules

Hardware Concept

Component	Purpose
ESP32 WROVER	Central controller for firmware, communication and control logic
VL53L7CX	Front and rear 8x8 Time-of-Flight distance sensing
VL53L4CD	Side distance sensing for left/right obstacle awareness
TCA9548A	I2C multiplexer for multiple sensors with overlapping addresses
PCA9685	Optional PWM expander for servo control
Motor controller / ESC	Drive motor output stage
UBEC / DC-DC converters	Separate and stable supply for logic, servos and drive electronics

The hardware concept separates logic supply, motor/servo supply and sensor interfaces as far as practical. Motor noise, voltage drops and undefined startup states are treated as relevant design constraints, not as afterthoughts.

Software Architecture

The repository is organized around small components with explicit responsibilities:

Module	Responsibility
MausDroid.ino	Main embedded entry point and integration layer
DriveController.*	Converts movement intent and processed distances into speed and steering commands
VL53L7CXAdapter.*	Reads and evaluates the VL53L7CX 8x8 ToF sensor matrix
VL53L4CDAdapter.*	Integrates side-facing distance sensors
PCA9685Adapter.*	Encapsulates PWM output for servo/actuator control
TCA9548AAdapter.h	Encapsulates I2C channel selection
TelemetryLogController.*	Collects telemetry-relevant state
UdpTelemetryLogger.*	Sends runtime diagnostics over UDP
SdCardLogger.*	Persists diagnostic data locally
GameController.*	Handles external/manual control input

The important design boundary is that the DriveController does not directly talk to hardware. It receives already prepared distance values and returns drive targets such as:

velocityPercent
steeringDeg

This keeps movement decisions easier to test and allows the same logic to be used against real sensors or simulated data.

Drive Logic

The current drive model focuses on safe, explainable behavior instead of complex navigation. The DriveController works with processed distances in millimeters:

• front
• rear
• frontLeft
• frontRight

The controller distinguishes normal driving, escape behavior and emergency stops:

State	Purpose
Drive	Normal forward movement, speed limiting, wall correction and obstacle response
Escape	Controlled recovery when no safe forward movement is available
EmergencyStop	Immediate stop for critical or not safely assessable situations

Speed and steering are limited continuously from the environment:

• front distance limits maximum forward speed
• strong steering reduces allowed speed
• narrow side distances reduce steering range
• invalid or missing sensor data is never interpreted as free space
• 0 mm is treated as a confirmed critical near-field condition

See DriveController.md for the detailed specification, thresholds and open calibration points.

Sensor Evaluation

The front/rear VL53L7CX adapter uses the sensor in continuous 8x8 mode at 15 Hz. Instead of using one global distance value, the matrix is split into overlapping direction regions:

L  L  LF F  F  FR R  R
L  L  LF F  F  FR R  R
L  L  LF F  F  FR R  R
L  L  LF F  F  FR R  R
L  L  LF F  F  FR R  R
L  L  LF F  F  FR R  R
L  L  LF F  F  FR R  R
L  L  LF F  F  FR R  R

Each zone has its own calibrated threshold. A zone must be confirmed across two new sensor frames before it is accepted. This avoids reacting to single-frame noise or repeated reads of the same frame.

Public direction readings:

• readLeftDistance()
• readFrontDistance()
• readRightDistance()

See VL53L7CXAdapter.md and VL53L7CXThresholdZones.md for the sensor evaluation details.

FreeRTOS Design Direction

The project is designed around a FreeRTOS-style separation of responsibilities. The exact task split is refined as hardware integration and timing measurements progress.

Task concept	Responsibility	Priority idea
Safety task	Monitor critical distances, sensor timeouts and input loss	Very high
Drive task	Update motor and steering targets	High
Sensor task	Read ToF sensors and update validated distance state	High
Control task	Process gamepad, RC or network input	Medium
Telemetry task	Send/debug state without blocking control	Low

Time-critical tasks should not depend on Wi-Fi, logging or long blocking delays. Safety-relevant state should be propagated immediately through suitable FreeRTOS primitives such as queues, event groups, mutexes or atomic state.

CoppeliaSim Test Bridge

The repository includes a CMake-based C++ bridge for CoppeliaSim. Its purpose is to validate drive logic and sensor scenarios in a repeatable virtual test environment before or alongside tests on the physical robot.

The simulation concept covers:

• simplified vehicle geometry
• virtual front/side distance sensors
• indoor test scenes with walls, passages and obstacles
• repeated validation of stop, slow-down, wall correction and escape behavior
• comparison of controller behavior between simulated and real distances

Relevant files:

• CMakeLists.txt
• build_coppelia_drive_bridge.bat
• start_coppelia_drive_bridge.bat
• build-coppelia-mingw/CoppeliaDriveBridge.cpp

The CMake setup expects CoppeliaSim Edu and the ZeroMQ Remote API C++ client. It also uses cppzmq, jsoncons and Boost headers.

Telemetry And Diagnostics

The project contains both UDP and SD-card logging components. The goal is to make movement decisions inspectable during tests:

• current distance state
• selected drive state
• requested speed and steering
• safety and fallback decisions
• sensor validity and timeout information

This is especially important for embedded robotics work because many errors are timing-related, sensor-related or only visible while the vehicle is moving.

Repository Notes

This repository currently contains prototype code, design notes and generated simulation/build artifacts. For a cleaner public portfolio presentation, the next housekeeping step would be moving generated build output out of version control and keeping only source files, documentation and reproducible build instructions.

Documentation

• Project documentation
• DriveController specification
• VL53L7CX adapter notes
• VL53L7CX threshold zones

License

No open-source license is currently provided. Unless a license is added later, the code and documentation are published as portfolio material only and all rights are reserved by the author.