How to build Hexapod: the whole process
252 steps to build Hexapod, from buying parts, printing and assembly to software, calibration and training, with the bill of materials, shop links and the official sourc…
This is an 18-DOF, 3D-printed hexapod robot project powered by an ESP32. The repository provides each robot's bill of materials, printed parts, assembly instructions, firmware, and gait-generation tools.
Buy parts
- Purchase the ESP32 controller board
Purchase the controller board with dual PCA9685 drivers; the servos are powered directly from the batteries.
- Purchase 18 25 kg servos
Choose 180°-rotation, 25 kg-class servos that support an 8.4V supply voltage, and ensure all servos are from the same batch for consistency.
- Purchase the SPST toggle switch
Purchase one SPST single-pole single-throw toggle switch with a 12 mm diameter; it can be bought together with the controller board.
- Purchase four 18650 batteries
Purchase four 3.7V Li-ion 18650 batteries with a recommended capacity of 2000mAh or more; use protected batteries for safety.
- Purchase the four-cell battery holder
Prepare one wired four-cell 2S2P 18650 battery holder; use the available 3D-printable version or purchase it together with the controller board.
- Use the Li-ion pack safely
Use protected cells only and a proper 2S charger, and never charge the pack unattended.
- Buy Standard Metric Hardware
The required hardware uses standard metric sizes and is available from Amazon, AliExpress, or local hardware stores.
- Select 18 matching MG92B servos
Prepare 18 MG92B Servos with 180° rotation, ensuring all servos are from the same batch for consistency.
- Prepare two protected batteries
Prepare 2 18650 Batteries rated 3.7V Li-ion, with 2000mAh+ recommended. Use protected batteries for safety.
- Choose the main controller
Choose either a Raspberry Pi PICO or an ESP32, and prepare eighteen 21G servos.
Print and make
- Print all parts
Print all parts listed in the parts list.
- Locate the 3D print files
All STL files are in the `3d print` folder, along with ready-to-print Bambu Studio projects named `bambu_studio_*.3mf`.
- Set layer height and infill
Use a 0.2 mm layer height and 20–30% infill.
- Choose structure and foot materials
Use PLA or PETG for the structure and TPU for the foot tips.
- Check supports and STL orientation
Some parts require supports; check the orientation of each STL.
- Test-print and fit one leg
Print one leg’s worth of parts and test-fit it before committing to all six legs.
- Distinguish standard and mirrored joints
Use six joints total: three standard and three mirrored. Left-side legs use mirrored joints, and right-side legs use standard joints; refer to the fully assembled robot images for orientation.
- Print the Foot Components
Prepare 6 foot_bottom, 6 foot_top, 6 foot_ground, and 6 foot_tip parts. The foot_tip is recommended to be printed with TPU.
- 3D print all robot parts
3D print all parts using the parts list below.
- Prepare and test-print hexapod parts
Use the STL files in the 3d print folder or the ready-to-print Bambu Studio project hexapod_mochi.3mf. Use 0.2 mm layers, 20-30% infill, PLA or PETG for the structure and TPU for the foot tips; supports are required for some parts, so print one leg's worth first and test-fit it.
- Print and assemble body components
Print 1 body_base, 6 body_side, 1 body_top, 1 body_head, 1 body_battery_top, and 12 body_servo_side parts. Install the servos before closing the body, route the wires neatly to avoid pinching, and test-fit all parts before final assembly.
- Print and orient joint components
Print 12 joint_bottom, 6 joint_cross, and 12 joint_top parts for six legs. Use mirrored joints for the left-side legs and standard joints for the right-side legs, and refer to the fully assembled robot images for the correct orientations.
- Print and assemble leg components
Print 6 leg_bottom, 12 leg_side, and 6 leg_top parts. Ensure the bearings are properly seated, the pins slide in smoothly without forcing, and the joints rotate smoothly before proceeding.
- Print and match foot components
Print the foot components for six legs: 3 standard feet and 3 mirrored feet. Use mirrored feet with mirrored joints on the left-side legs and standard feet with standard joints on the right-side legs.
- Print the robot structure
Print the robot's structural parts. The 3D-printed parts are designed for strength and easy assembly.
- Prepare the 3D Print Files
All STL files are located in the `3d print` folder, together with a ready-to-print Bambu Studio project, `nougat.3mf`.
- Set Print Parameters
Use a 0.2 mm layer height and 20–30% infill; use PLA or PETG for the structure and TPU for the foot tips. Supports are required for some parts, and STL orientation should be checked.
- Print and Test-Fit One Leg
Print one leg's worth of parts first and test-fit it before committing to all six legs.
- Print Feet with Matching Orientation
Print six feet in total: three standard and three mirrored. Left-side legs use mirrored feet with mirrored joints, and right-side legs use standard feet with standard joints.
Assemble
- Prepare the hardware
Organize screws, nuts, bearings, and pins.
- Assemble the body
Install the servos and controller.
- Build the legs
For each leg, assemble the joint, then the leg, then the foot.
- Attach the legs to the body
Attach the assembled legs to the body.
- Install servos before closing body
Install the servos before closing the body.
- Route the wires neatly
Route the wires neatly to avoid pinching them.
- Test-fit all parts before assembly
Test-fit all parts before final assembly.
- Assemble Six Leg Joints
Assemble the legs with 6 joint_cross, 12 joint_top, 6 leg_bottom, 12 leg_side, and 6 leg_top. Ensure the bearings are properly seated, the pins slide in smoothly without forcing, and the joints rotate smoothly.
- Fit Six Feet by Side
Use mirrored feet with mirrored joints on the left-side legs, and standard feet with standard joints on the right-side legs. Refer to the fully assembled robot images for the correct foot orientation.
- Sort All Hardware
Before assembly, organize all hardware into labeled containers to save time.
- Organize the assembly hardware
Organize the screws, nuts, bearings, and pins before assembly.
- Assemble the robot body
Assemble the body, then install the servos and controller.
- Build each robot leg
For each leg, assemble the joint, then the leg, and finally the foot.
- Attach the legs to the body
Attach the assembled legs to the robot body.
- Leave servo horn screws loose
Do not tighten the servo horn screws during assembly; leave them loose so the servos can rotate.
- Connect the pre-assembled controller board
Use the pre-assembled Controller Board and plug the servos, switch, and battery leads directly into it; no soldering is needed.
- Organize Hardware Before Assembly
Place all hardware into labeled containers before starting assembly.
Software
- Wire, test, and calibrate
Connect the servos, upload the firmware, and calibrate the robot.
- Install Arduino IDE 2.x
Install Arduino IDE; version 2.x is recommended.
- Connect the Controller USB Cable
Prepare a USB cable compatible with the controller board.
- Install Required Arduino Libraries
Install Adafruit_PWMServoDriver through Arduino Library Manager for PCA9685 control. Also install AsyncUDP, ArduinoOTA, EEPROM, and WebServer, which are included with arduino-esp32.
- Install Arduino IDE
Download and install Arduino IDE from arduino.cc.
- Add ESP32 board support
Follow the official ESP32 Arduino installation guide, or add the specified package index under Arduino IDE’s File → Preferences → “Additional Board Manager URLs”.
- Install the ESP32 board package
Search for “ESP32” in Tools → Board → Boards Manager and install it.
- Install the PWM servo library
Open Sketch → Include Library → Manage Libraries, search for “Adafruit PWM Servo Driver”, and click Install.
- Configure the ESP32 board settings
Select ESP32 Dev Module, set Upload Speed to 115200, Flash Frequency to 80MHz, and Partition Scheme to “Default 4MB with spiffs”.
- Open the hexapod firmware
Open ./software/hexapod_esp32/hexapod_esp32.ino in Arduino IDE.
- Select the Macaroon robot configuration
Uncomment ROBOT_MACAROON in robot.h and ensure it is the only uncommented ROBOT_* line. This selects Macaroon’s motion tables and settings in the shared family firmware.
- Configure the WiFi access point
The default SSID is hexapod_macaroon and the password is hexapod_1234; APSSID is in src/robots/macaroon/robot_config.h and APPSK is in config.h.
- Configure custom servo pins
When using custom wiring, configure the three servo pin mappings for the left and right legs in the code.
- Connect ESP32 and select its port
Connect the ESP32 via USB, then select the correct COM port under Tools → Port.
- Upload the hexapod firmware
Click the Upload button to upload the firmware to the connected ESP32.
- Install Python and Edit Parameters
Install Python with `numpy`, then edit `robots/macaroon.json`, or add a generator in `path_tool.py`.
- Regenerate the Macaroon Motion Table
From `software/path_tool`, run `python generate_motion.py macaroon` to write `software/hexapod_esp32/src/robots/macaroon/motion.h` directly; `lut_generator.ipynb` does the same interactively.
- Re-upload the ESP32 Firmware
Re-upload the ESP32 firmware after generating the new motion table.
- Register a New Custom Motion
A brand-new table also needs an entry in `motion_config[]` in `motion_control.ino`; see “Adding Custom Motions”.
- Flash firmware with default offsets
Flash the code to the controller with the default offset values.
- Choose an installation method
Use your favorite IDE; the availability of other options depends on the operating system. Users in China should use the Jihulab mirror as the repository source.
- Check the chip support status
Consult the Supported Soc’s table to determine whether the particular chip is under a stable or development release.
- Add the ESP32 package URLs
Enter the stable package index URL in Arduino Boards Manager; the development package index URL is also provided. Use the Jihulab package indexes instead when the Espressif links have connection or download problems in China.
- Install ESP32 through Boards Manager
Starting with Arduino IDE version 1.6.4, use Boards Manager to install third-party platform packages. The Arduino-ESP32 packages are available for Windows, macOS, and Linux.
- Complete Windows Installation Step 1
Follow the first manual Windows installation action shown in media 4.
- Complete Windows Installation Step 2
Follow the second manual Windows installation action shown in media 5.
- Complete Windows Installation Step 3
Follow the third manual Windows installation action shown in media 6.
- Complete Windows Installation Step 4
Follow the fourth manual Windows installation action shown in media 7.
- Complete Windows Installation Step 5
Follow the final manual Windows installation actions shown in media 8 and media 9.
- Update Arduino ESP32 Code
Follow the update actions shown in media 10 and media 11; media 7 also appears with this update section.
- Install Linux Serial Tools
Run the listed commands to add the user to the dialout group, install Git, download and install pip, and install pyserial.
- Clone Arduino ESP32 Support
Create the Arduino hardware directory, clone the Arduino ESP32 repository, and run the repository tools installer.
- Use Alternative Clone Path
The document also provides an alternative command sequence that creates the Espressif directory before cloning the repository and running get.py.
- Install ESP32 Arduino Support on Fedora
Add the user to the dialout group, install Git, Python pip, and pyserial, then clone the Arduino-ESP32 repository and download its tools. The note warns that installing the arduino package with dnf will most likely install an older release.
- Install ESP32 Arduino Support on openSUSE
Add the user to the dialout group and install the required tools, selecting Python 2.7 or Python 3 packages according to the detected Python version. Then clone the Arduino-ESP32 repository and download its tools.
- Install ESP32 Arduino Support on macOS
Create the Espressif hardware directory in the Arduino sketchbook location, clone the Arduino-ESP32 repository, and download its tools. Adjust the path if the sketchbook location shown in Arduino Preferences differs.
- Install macOS Command Line Tools
If the macOS setup reports an invalid active developer path and a missing xcrun command, install the Command Line Tools with xcode-select.
- Install the Arduino libraries
Open Arduino Library Manager and install the seven libraries listed in the Dependencies table.
- Install Arduino IDE 2.x
Install Arduino IDE 2.x from the Arduino website.
- Install ESP32 board support
Install ESP32 board support for Arduino IDE using the linked Espressif guide.
Calibrate and test
- Adjust the gait frame delay
DELAY_MS is the time between LUT frames, and the frame period is exactly DELAY_MS. Increase DELAY_MS in src/robots/<name>/robot_config.h if the gait feels rushed.
- Connect to the hexapod WiFi
Power on the hexapod and connect your device to its WiFi network. On first boot, calibrations saved by older firmware in EEPROM are imported automatically.
- Open the calibration interface
Open a web browser, navigate to `http://192.168.4.1/`, and switch to the **Calibrate** tab.
- Enter the calibration posture
Click the **Enter calibration** button. The robot will move to its neutral calibration posture.
- Adjust every joint offset
Use the `+` and `-` buttons to fine-tune each joint, keeping offsets within ±100 ticks. Align the coxa parallel to the body, the femur horizontal, and the tibia vertical until all legs are aligned and the robot stands evenly.
- Save calibration to flash
Once the posture is satisfactory, click **Save to robot** to permanently save the calibration values to flash. When you save, the web interface prints the configured arrays to the Serial Monitor so the offsets can be backed up.
- Exit calibration mode
Click **Exit**. The robot eases back to its standby posture.
- Set gait playback speed
Append a speed byte to make a 7-byte command; values are clamped to 20-100%, and `0` leaves the speed unchanged. The 6-byte form never changes the speed.
- Use smooth reduced-speed playback
Interpret playback speed as a percentage of the tuned frame rate (`DELAY_MS`); at 50%, a gait takes twice as long per cycle. Below 100%, the firmware blends adjacent LUT frames while continuing to update the servos every `DELAY_MS`.
- Keep gait transitions unchanged
Apply playback speed only to gait LUT playback. Transitions between gaits retain their own pace so the robot can still stop promptly.
- Check the default speed
Check that the motion speed starts at 60% after boot, as defined by `MOTION_SPEED_DEFAULT_PCT` in `config.h`. Clients using only the 6-byte form therefore walk at 60% unless the speed is raised.
- Re-enable OTA after motion
OTA is disabled after the first motion command or real-time session. Reboot the robot to enable OTA again.
- Set the OTA password
Define `OTA_PASSWORD` in `config.h` to require a password for OTA updates. The document gives the same default-security warning for the web page and its WiFi settings.
- Verify the robot WiFi credentials
Verify the SSID in `src/robots/<name>/robot_config.h` and the password in `config.h`.
- Check the robot IP address
Open the serial monitor and check for the IP address. The address is 192.168.4.1 in access point mode.
- Connect using the robot IP address
If the robot joined your network but `hexapod-<robot>.local` does not resolve, use the IP address from the serial monitor or your router.
- Check the saved 2.4 GHz network
If the robot keeps starting its access point, check the saved network and password on the **WiFi** tab. Confirm that the network is 2.4 GHz.
- Use a 2.4 GHz WiFi client
Ensure the client device supports 2.4 GHz WiFi.
- Check the PWM driver addresses
Check that the PWM driver I2C addresses match the hardware addresses 0x40 and 0x41.
- Verify the active-low enable pins
Verify that the enable pins are connected correctly. They are active LOW.
- Confirm the servo pin mappings
Confirm the servo pin mappings in `config.h`.
- Test individual servos
Test individual servos with the `posture_calibration()` function.
- Use OTA before the first motion
OTA only works before the first motion command.
- Reboot the robot to enable OTA
Reboot the robot to re-enable OTA.
- Connect to the robot WiFi network
Ensure the upload device is connected to the robot's WiFi network.
- Check the upload computer firewall
Check the firewall settings on the upload computer.
- Calibrate the ESP32 servos
On the ESP32 version, calibrate the servos through a web browser with real-time adjustment.
- Check Battery Polarity Twice
Check battery polarity twice before the first power-up; reversed polarity will destroy the controller board.
- Keep Fingers Clear of Joints
Keep fingers clear of the joints when powered; eighteen servos have enough torque between them to pinch hard.
- Support the Robot on First Power-On
Support the robot on the first power-on; it runs its stand-up sequence automatically as soon as a client joins its WiFi network.
- Handle the Li-ion Pack Safely
Use protected cells only and a proper 2S charger, and never charge unattended.
- Configure ESP32 Board Settings
Set Board to “ESP32 Dev Module,” Upload Speed to “115200,” Flash Frequency to “80MHz,” and Partition Scheme to “Default 4MB with spiffs.”
- Select the Nougat Robot
In robot.h, ensure ROBOT_NOUGAT is the only uncommented ROBOT_* line. This selects Nougat’s motion tables and settings.
- Configure Default WiFi Details
The default SSID is hexapod_nougat and the password is hexapod_1234. Set the SSID as APSSID in src/robots/nougat/robot_config.h and the password as APPSK in config.h.
- Configure Custom Servo Pins
When using custom wiring, configure the servo pins for the left and right sets of three legs using the mappings in the sketch.
- Power on the hexapod
Connect the batteries and flip the toggle switch. The robot then powers on.
- Join the robot WiFi
Connect your phone or computer directly to the robot's own Access Point; it never joins your home router. The robot runs its stand-up sequence as soon as a client connects.
- Send commands or open calibration
Send commands to `192.168.4.1:1234`. Alternatively, open `http://192.168.4.1` for the calibration interface.
- Set the gait speed
Append an optional seventh byte to set the gait speed as a percentage of the tuned speed, from 20–100; `0` leaves it unchanged. ESP32 firmware starts at 60%, and the speed can also be changed with the **Motion Speed** slider at `http://192.168.4.1`.
- Save Servo Offsets
Click "Save Offsets" in the web interface to write the calibration values to the device.
Data and training
- Open control or calibration interface
Send commands to 192.168.4.1:1234, or open http://192.168.4.1 for the calibration interface.
- Send a forward motion command
Construct a 6-byte little-endian packet with 0xA5 in byte 0, the command ID in byte 1, and a 32-bit sequence number in bytes 2–5, then send it over UDP to 192.168.4.1:1234.
- Set or retain motion speed
When only the 6-byte form is sent, the ESP32 firmware walks at 60%. Raise the speed with the Motion Speed slider at http://192.168.4.1, or set the gait speed from 20–100% in optional byte 6; 0 leaves it unchanged.
- Send a session control command
Use the same 6-byte layout as a motion command, with 0xA7 as the magic number and the session action in byte 1.
- Control real-time joint pose
Send a 44-byte packet containing raw servo ticks for all 18 joints. The robot enters real-time mode, and each joint slews by at most max_step ticks per 20 ms cycle; after 1 second without a packet, it returns to standby and LUT control.
- Keep the real-time mode active
Send a ping while real-time mode is idle to prevent the robot from returning to standby after 1 second without a packet. Sending a 0xA5 motion command also exits real-time mode.
- Use a legacy text command
When a packet matches none of the binary layouts, the firmware can still parse plain command strings. The colon delimiters are optional, leading delimiters are skipped, and the command ends at the first delimiter; new clients should use the binary protocol.
- Send a binary motion command
The ESP32 firmware uses a binary protocol whose first byte selects the packet type. The example packs magic byte `0xA5`, Walk forward command ID `1`, and sequence number `0` in little-endian, unpadded form, then sends it over UDP.
- Send plain-text commands
Both firmwares accept plain command strings; `:` delimiters are optional, leading delimiters are skipped, and the command ends at the first one. This is the only interface on the Pico, while new ESP32 clients should use the binary protocol.
Use it
- Open the browser controller
Connect to the robot's WiFi network and open `http://192.168.4.1/`, or the robot's address on your network. The page opens on the Drive tab with a control panel that fills the whole window.
- Drive with the touch pads
Hold and slide your finger between zones without lifting it. The right dial walks in eight directions on its inner ring, uses the top and bottom for fast forward/backward and the sides for turning in place, and stops from the centre; the left grid plays body moves and the climbing gait. Let go to return the robot to standby.
- Drive with the keyboard
Use **W A S D** or the arrow keys to walk, pressing two together for diagonals. Use **Q** and **E** to turn and **Space** to stop.
- Relax and wake the servos
Select **Relax** to cut power to the servos so the robot sags to the ground. Select **Wake**, or use any control, to power the servos again.
- Set the controller orientation
Use landscape for the Android app's layout, with the speed slider and buttons between the two pads. In portrait, these controls stack.
- Use full screen or Home Screen
On Android, iPad and desktop, tap **Full screen** to hide the browser bars. On iPhone Safari, use **Share > Add to Home Screen** and open the page from the icon because Safari has no full-screen mode.
- Understand the browser failsafe
While a control is held, the page resends the command every 150 ms over HTTP using `POST /motion`, and sends the gait speed with every move. The robot's 500 ms failsafe stops it if the phone drops off the WiFi or the page goes to the background.
- Avoid simultaneous remote control
Do not drive from the browser page and a UDP remote at the same time because they will fight over the robot. The last command wins.
- Build the motion command packet
Construct the 6-byte motion command with `0xA5` as the magic number, a command ID from the enum, and a 32-bit unsigned sequence number in bytes 2-5.
- Keep motion packets arriving
Keep resending the UDP command while the robot should move; if no packet arrives for 500 ms (`MOTION_TIMEOUT_MS`), the robot returns to standby.
- Change gaits at cycle boundaries
Change gaits only at the start or midpoint of a gait cycle. The robot always passes through the standby posture while changing to the next gait.
- Override speed with each packet
Send 7-byte packets to override the speed with every packet. The arcade remote is given as an example of this client type.
- Start the Python motion client
Begin the Python example by importing the socket and struct modules for the motion command client.
- Register the motion path
Add the motion path to `gen_luts()` in `../path_tool/generate_motion.py` so it is generated for every robot.
- Regenerate all motion LUTs
Regenerate the LUTs for all robots with `python generate_motion.py --all`. This rewrites each `src/robots/<name>/motion.h`.
- Add the custom motion command
Add a command ID before `CMD_COUNT` in `protocol.h`, then add the matching entry at the same position in `motion_config[]` in `motion_control.ino`. A `static_assert` checks that the counts match.
- Keep fingers clear of joints
Keep fingers clear of the powered joints because eighteen 25 kg servos have enough torque to pinch hard.
- Cut power for unexpected movement
If a leg moves somewhere unexpected, cut power with the toggle switch instead of holding the leg back.
- Connect with the Android app
Use the hexapod app on a WiFi-capable Android device to connect to the robot's WiFi network.
- Control movement on screen
Use the app's on-screen buttons to control the hexapod's movement.
- Execute available motion commands
Execute all available hexapod motion commands through the app.
- Monitor the connection status
View the hexapod's connection status in the app.
- Control live with Hexapod Link
Use Hexapod Link to drive the robot live through the real-time pose streaming protocol.
- Retain calibration after power cycles
The EEPROM calibration values persist, so the hexapod remembers them even after power cycles.
- Control the hexapod with the Android app
Connect to the hexapod's WiFi network, use on-screen buttons to control movement, execute all available motion commands, and monitor connection status. An Android device with WiFi capability is required.
- Control live with Hexapod Link
Use Hexapod Link to drive the robot live through the real-time pose streaming protocol for ESP32 firmware.