Open-source hexapod robot
Build the Hexapod Macaroon
A complete four-phase guide — from 3D printing through electronics, firmware, and calibration. Powered by stronger 25kg servos.
Critical: Do NOT tighten servo horn screws during assembly. Leave them loose — you’ll tighten them properly during calibration after setting each servo to its neutral position.
What you’ll build
Degrees of freedom18 (6 legs × 3)
Build time8–12 hours
Skill levelBeginner–Intermediate
ToolsSoldering iron, hex keys, wire cutters
Print settings
Layer height0.2 mm
Infill20–30%
MaterialPLA / PETG
SupportsSome parts
All STL files — plus ready-to-print Bambu Studio projects (
bambu_studio_*.3mf) — are in the 3d print folder ↗.
Body components — ×1 set
Install servos before closing the body. Route wires neatly to avoid pinching. Test-fit all parts before final assembly.
body_base×1
body_side×6
body_top×1
body_head×1
body_battery×1
body_servo_side×12
fence Optional×1Joint components — 3 standard + 3 mirrored
Left side legs use mirrored joints. Right side legs use standard joints. Refer to assembled robot images for correct orientations.
joint_bottom×12
joint_cross×6
joint_top×12Leg components — ×6
Ensure bearings are properly seated. Pins should slide in smoothly without forcing. Verify smooth joint rotation before proceeding.
leg_bottom×6
leg_side×12
leg_top×6Foot components — 3 standard + 3 mirrored
Match foot orientation with joint — left = mirrored, right = standard.
foot_bottom×6
foot_top×6
foot_ground×6
foot_tip TPU×6Hardware
Organize all hardware into labeled containers before assembly. Standard metric parts — available from Amazon, AliExpress, or local hardware stores.
| Item | Spec | Qty | Use |
|---|---|---|---|
| Screw | M2 × 6mm hex socket | 36 | Servo mounting |
| Screw | M2 × 12mm countersunk | 180 | General assembly |
| Nut | M2 hex nut | 216 | Securing screws |
| Pin | M4 × 6mm stainless steel (304) | 18 | Joint pivots |
| Bearing | MR74-2RS — 4mm ID, 7mm OD, 2.5mm bore | 18 | Smooth joint rotation |
Assembly order
1
Install servos in body before closing it — route wires neatly to avoid pinching
2
Assemble joints: bottom → cross → top. Pay close attention to left vs right orientation
3
Build each leg — seat bearings, insert pins (should slide smoothly without forcing)
4
Attach feet — verify orientation matches the joint (standard or mirrored)
5
Attach all 6 completed legs to the body
6
Connect servos and controller — then proceed to Electronics and Software before final tightening
Components
| Image | Component | Spec | Qty | Note |
|---|---|---|---|---|
 | Controller board | ESP32 version — RookiDroid custom PCB | 1 | Purchase ↗ |
 | Servo | 25kg — 180° rotation | 18 | Same batch |
 | Toggle switch | SPST, 6mm diameter | 1 | |
 | 18650 battery | 3.7V Li-ion, 2000mAh+ | 4 | Protected cells only |
 | Battery holder | 4-cell (2S2P) with wire leads | 1 | Printable STL ↗ |
Use protected 18650 batteries. Unprotected cells can be hazardous — the protection circuit guards against overcharge, over-discharge, and short circuits.
Wiring
1
Connect each 25kg servo to the numbered ports on the controller board — 18 servos total (3 per leg)
2
Install the toggle switch for main power
3
Connect the 4-cell (2S2P) 18650 battery holder to the board’s power input (7.4V nominal)
4
Refer to the wiring diagram below for exact pin assignments
The custom controller board simplifies wiring significantly — all servo connectors and power management are built in. Available from the RookiDroid shop.
Dependencies
| Library | How to install |
|---|---|
arduino-esp32 | Add board support URL in Arduino IDE → Boards Manager |
Adafruit PWM Servo Driver | Arduino IDE → Library Manager → search and install |
AsyncUDP, ArduinoOTA, EEPROM, WebServer | Included with arduino-esp32 — nothing extra to install |
Upload steps
1
Install Arduino IDE (2.x recommended) from arduino.cc ↗
2
Install
arduino-esp32 board support following the Espressif instructions ↗, or add https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json to Preferences → Additional Board Manager URLs3
Install Adafruit PWM Servo Driver through Arduino Library Manager
4
Download the firmware from GitHub — hexapod_esp32 ↗ and open
hexapod_esp32.ino5
Select board
ESP32 Dev Module — Upload Speed 115200, Flash Frequency 80MHz, Partition Scheme Default 4MB with spiffs6
Select the COM port and upload. Open Serial Monitor at 115200 baud to see the AP address — the robot stands up when a client connects to its WiFi
Default WiFi config
SSID
hexapod_macaroon
Password
hexapod_1234
UDP port
1234
AP address
192.168.4.1
Change the credentials in
config.h (APSSID / APPSK). The hexapod creates its own 2.4 GHz access point — connect to it directly rather than looking for it on your router.
Source files
📄
hexapod_esp32.ino — main sketch with setup() / loop() and shared system state📄
motion_control.ino — PWM drivers and motion look-up table playback📄
realtime.ino — real-time pose streaming and its slew limiter📄
network.ino — WiFi AP, OTA, UDP endpoint and packet parsing📄
calibration.ino — servo offsets loaded from / saved to EEPROM📄
web_ui.ino / web_page.h — web calibration interface📄
hexapod.h / protocol.h — shared state and UDP packet layouts📄
config.h — WiFi credentials, servo pin mappings, and hardware settings📄
motion.h — pre-generated motion look-up tables for smooth walkingControl commands
| Command | Action |
|---|---|
:standby: | Stop and hold position |
:walk0: / :walk180: | Walk forward / backward |
:walkr45: :walkr90: :walkr135: | Walk right at 45° / 90° / 135° |
:walkl45: :walkl90: :walkl135: | Walk left at 45° / 90° / 135° |
:turnleft: / :turnright: | Rotate in place |
:fastforward: / :fastbackward: | Fast walking |
:climbforward: / :climbbackward: | Climbing gait |
:rotatex: :rotatey: :rotatez: | Body rotation (pitch / roll / yaw) |
:twist: | Body twist motion |
Send commands as UDP packets to
192.168.4.1:1234, or use the Android app ↗. The ESP32 firmware also supports a binary protocol for real-time pose streaming of all 18 servos — the hexapod-robot-simulator ↗ can drive the robot live.
OTA updates supported. Connect to the hexapod WiFi network, pick the robot under Arduino IDE → Tools → Port → Network Ports, and upload without USB. OTA is disabled after the first motion command — reboot the robot to re-enable it.
Troubleshooting
- Upload fails: use a data-capable USB cable, try another port, confirm board and port, and hold BOOT during upload if needed
- Servos not responding: check battery voltage (7.4V nominal), servo connections, PCA9685 addresses (0x40 left, 0x41 right) and enable pins (GPIO 19 left, GPIO 26 right)
- WiFi issues: verify SSID/password in
config.hand make sure your device supports 2.4 GHz - OTA not working: reboot before uploading, stay connected to the hexapod AP, and check your computer’s firewall
The ESP32 firmware includes a web-based calibration interface — no need to edit code or re-upload firmware. All adjustments happen live through your browser.
Target neutral positions (all servos at 90°)
Left legs 1, 2, 3
Joint 1 — Coxa (hip)⊥ body
Joint 2 — Femur (thigh)horizontal
Joint 3 — Tibia (shin)90° to femur
Right legs 1, 2, 3
Joint 1 — Coxa (hip)⊥ body
Joint 2 — Femur (thigh)horizontal
Joint 3 — Tibia (shin)90° to femur
Calibration procedure
1
Flash firmware with default offsets, insert batteries, turn on power switch
2
Connect your device to the
hexapod_macaroon WiFi network (password: hexapod_1234)3
Open a browser and navigate to
http://192.168.4.14
Click “Enter Calibration Mode” — motion stops, current offsets load, and a grid of all 18 servos appears (6 legs × 3 joints)
5
For each misaligned servo, use +/− buttons (1 tick ≈ 0.44°) or type a value — changes apply immediately
6
Compare each leg against the reference images: coxa ⊥ body, femur horizontal, tibia at 90° to femur
7
Click “Save Offsets” — values are written to EEPROM and survive power cycles. Also printed to Serial Monitor as backup
8
Now tighten servo horn screws — with each servo in its correct neutral position, firmly tighten all horn screws
9
Click “Exit Calibration Mode” and send a walk command to verify smooth motion
Tips for good calibration
- Calibrate one leg completely before moving to the next
- Use +/− buttons for fine control — avoid jumping to large values
- If offsets exceed ±25 ticks, physically reposition the servo horn instead of relying on software offset
- Loose servo horns throw off calibration — make sure the horn is seated firmly on the spline before adjusting
- Servos respond immediately as you adjust, so you get real-time visual feedback
- Save your offsets — values persist in EEPROM but always note them from Serial Monitor as backup
- Re-enter calibration mode any time to fine-tune if walking looks uneven