Hexapod

Hexapod

This is the old (V1) version of the project. Active development has moved to V2: quick-brown-bot/hexapod_v2. This repo is closed — kept for reference and continued use, not further development.

An ESP32-powered hexapod robot built as a long-term robotics and embedded systems project.

The goal is not just to make a robot walk, but to learn and at the same time build a platform that is easy to experiment with, tune, and extend. Most robot behavior is configurable at runtime, control inputs are transport-independent, and the motion stack is organized into separated components.

The project combines firmware, hardware design, and system documentation in a single repository.

6 legs, 18 servos, ESP32, ESP-IDF, FreeRTOS, direct PWM.

The distributed RS485/RP2040 leg-controller generation of this project has moved to a separate repository: quick-brown-bot/hexapod_v2. This repo covers the original ESP32 direct-PWM robot only. V1 is closed: the hardware and firmware here are done and kept for reference and continued use, not further development.

What Is In This Repository

The repository contains software and hardware assets used to develop and validate the robot.

firmware/
└── mainboard/         Main robot firmware (ESP32, direct PWM)

hardware/
├── servo_mainboard/   Central ESP32 board driving the servos directly
├── leg/               Leg controller board
├── esp32_connector/   ESP32 carrier / breakout
├── symbols/           Symbol libraries
├── footprints/        Footprint libraries
└── models/            Mechanical models

docs/
├── common/            Docs shared across subsystems (RPC, WiFi, config)
├── architecture/       System and hardware architecture docs
├── development/        Development docs
└── plans/             Project-wide backlog and research items

Mainboard firmware overview: firmware/mainboard/README.md

The main firmware is built around a fixed 100 Hz control loop and a modular motion pipeline:

Controller Input
        ↓
Gait Scheduler
        ↓
Foot Trajectory Generation
        ↓
Inverse Kinematics
        ↓
Motion Limiting
        ↓
Servo Outputs

Current Technical Highlights

Effort Summary

Hardware Snapshot

• MCU: ESP32 running FreeRTOS through ESP-IDF.
• Robot layout: 6 legs, 3 degrees of freedom per leg, 18 hobby servos total.
• Power: 4S LiPo, separate UBEC paths for servo and logic power.
• PWM: mixed MCPWM and LEDC to reach all 18 outputs on the ESP32.
• Mechanical: custom 3D-printed chassis and leg parts.

High-Level Architecture

flowchart LR
        Control[Controller stack]
        Config[RPC and config]
        App[Application loop]
        Loc[Locomotion]
        Limits[Motion limiting]
        Act[Actuation]
        Robot[Robot hardware]

        Control --> App
        Config --> App
        App --> Loc --> Limits --> Act --> Robot
        Config --> Control

• Controller stack: receives operator input from supported transports and normalizes it.
• RPC and config: handles runtime commands, parameter discovery, persistence, and save flows.
• Application loop: owns boot order and the 100 Hz control cycle.
• Locomotion: turns operator intent into gait phase, foot targets, and joint-space commands.
• Motion limiting: constrains commanded motion to configured dynamic envelopes.
• Actuation: maps joint commands to the PWM outputs that drive the robot.

Runtime Configuration

Configuration is treated as a first-class subsystem rather than a collection of compile-time constants.

Parameters are organized into namespaces. Each namespace owns:

• parameter definitions,
• default values,
• validation rules,
• persistence behavior,
• migration logic,
• RPC discovery metadata.

The configuration manager provides:

• runtime parameter inspection,
• runtime modification,
• save/load operations,
• namespace registration,
• NVS persistence,
• version-aware migration support.

Robot geometry, calibration data, controller settings, motion limits, and other runtime behavior are loaded through this system rather than being hardcoded throughout the codebase.

Motion Pipeline

The locomotion stack converts user commands into joint targets through a sequence of dedicated subsystems:

• gait scheduling,
• swing trajectory generation,
• inverse kinematics,
• velocity limiting,
• acceleration limiting,
• jerk limiting,
• servo actuation.

The motion loop runs at 100 Hz.

Controller Abstraction

Controller transports are separated from locomotion.

Supported ingress paths currently include:

• FlySky iBUS,
• Wi-Fi TCP,
• Bluetooth Classic.

Each transport driver translates incoming data into a normalized controller state consumed by the motion system.

This allows locomotion, gait generation, and motion limiting to remain independent of transport-specific protocols.

Hardware-Aware Design

The robot uses 18 servos arranged as three joints per leg:

• Coxa
• Femur
• Tibia

Servo signal generation is implemented on ESP32 using a combination of MCPWM and LEDC peripherals to fit within available hardware resources.

Power for logic and servos is separated to improve stability under heavy load.

Engineering Problems Being Explored

This project is primarily a learning and engineering platform.

Current focus areas include:

• real-time control on resource-constrained hardware,
• gait generation and scheduling,
• inverse kinematics,
• motion smoothing and trajectory constraints,
• configuration architecture for embedded systems,
• transport-independent control interfaces,
• robotics software maintainability,
• practical servo-driven locomotion.

Documentation

The repository contains detailed documentation covering implementation details and architecture decisions.

• docs/architecture/SYSTEM_ARCHITECTURE.md
• docs/architecture/HARDWARE_AND_MECHANICS.md
• firmware/mainboard/README.md

Common:

• docs/common/interfaces/RPC_USER_GUIDE.md
• docs/common/configuration/CONFIGURATION_PERSISTENCE_DESIGN.md

Full documentation index: docs/README.md

Project Status

The project is under active development.

Current work focuses on improving locomotion quality, refining control architecture boundaries, and preparing the next generation of leg electronics while keeping the existing robot operational as a test platform.

License

This repository uses Apache License 2.0 for the mainboard firmware.

License file location: LICENSE

Include the following notice in derivative works:

Copyright 2025 Pawel Grudzien

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.