How to build NodeHexa: the whole process
87 steps to build NodeHexa, from buying parts, printing and assembly to software, calibration and training, with the bill of materials, shop links and the official sourc…
NodeHexa is an open-source ESP32 hexapod that also supports a quadruped configuration. The repository provides printable structural parts, mechanism and fastener information, hardware and firmware documentation, Web control, calibration, motion planning, and replication tutorials.
Buy parts
- Select ESP32 controller
Use an ESP32 as the main controller, specifically the NodeMCU-32S.
- Select PCA9685 driver board
Use a PCA9685 PWM driver board for servo control.
- Buy the hexapod and quadruped robot kits
Buy the NodeHexa hexapod robot kit or the NodeQuadMini quadruped robot kit.
- Buy the hexapod robot circuit board
Buy the NodeHexa hexapod robot circuit board.
- Buy the recommended MG90s servos
The document strongly recommends the MG90s servos from the listed link and notes that low-quality servos are more likely to overheat or burn out.
- Buy the voice AI expansion board
Buy the Xiaozhi AI expansion board, which supports quadruped and hexapod robots.
- Open the hexapod replication tutorial
- Prepare materials using the tutorial
- Prepare hexapod fasteners
Prepare the fasteners listed in the hexapod BOM; the quantities exclude spares, so prepare a small extra margin. Include M2×12mm screws and matching nuts only if using the optional connection structure.
- Prepare quadruped fasteners
Prepare the fasteners listed in the quadruped BOM. Do not prepare the reserved case-cover screws because the cover has not been designed; include M2×12mm screws and matching nuts only if using the optional connection structure.
- Download the corresponding PCB project files
Download the required PCB project files, including PiHexaSub, PiHexa-V4, or PiHexaHatXiaozhi.
Print and make
- Modify design parameters as needed
Modify the PCB design parameters according to your needs.
- Export Gerbers for PCB fabrication
Export the Gerber files and use them for PCB fabrication.
Assemble
- Add ESP32-S3 CAM Mini
Connect the ESP32-S3 CAM Mini to the same Wi-Fi as the robot and display MJPEG in the separate video-control mode.
- Connect ultrasonic diagnostics
Connect the ultrasonic module with Trigger on GPIO4 and Echo on GPIO35; Echo must be 3.3 V. Perform distance measurements on demand and count errors without affecting motion decisions.
- Configure Wi-Fi and UART2
Use Wi-Fi and the UART2 serial port for robot communication.
- Connect passive buzzer
If using the optional passive buzzer, connect it to GPIO26.
- Assemble the legs using the tutorial
- Assemble the body using the tutorial
- Solder the left-board SJ1 jumper
DIY builders must solder the SJ1 jumper on the left servo driver board so its IIC address differs from the right board. Purchased kits are already soldered and need no step.
- Use specified fastener quantities
Before assembly, confirm that the fastener specifications and quantities meet the requirements, then use them at the corresponding connection points.
- Use locknuts where loosening must be prevented
Use self-locking nuts at connections that require resistance to loosening.
- Connect joints with axle pins
Use axle pins for joint connections and ensure that joint movement remains smooth.
- Protect the GPIO35 input level
If the ultrasonic module's Echo output is 5 V, add reliable level shifting or a voltage divider before connecting it. Never connect a 5 V Echo output directly to GPIO35.
Software
- Display voltage and estimated charge
Display battery voltage and estimated charge percentage in real time on the main control and motion-planning pages.
- Configure XiaoZhi voice expansion
Connect the XiaoZhi AI expansion board and use UART v2; the system automatically supports the legacy serial protocol.
- Enable the SPIFFS filesystem
Use the SPIFFS filesystem for firmware storage.
- Create firmware entry point
Place the main program entry point at firmware/src/main.cpp.
- Create unified robot interface
Provide a unified robot abstraction interface shared by hexapods and quadrupeds in robot.h.
- Implement hexapod modules
Implement the hexapod with hexapod.h/cpp and the quadruped with quad_robot.h/cpp.
- Implement leg control
Implement single-leg control in leg.h/cpp, separately implemented or reused by the hexapod and quadruped.
- Configure movement modules
Store movement-control algorithms and configuration tables in movement*.h/cpp.
- Implement motion planner
Use motion_controller* to execute action sequences and motion plans.
- Implement power management
Implement battery sampling, low-voltage latching, and state snapshots with power_manager*.
- Implement UART streaming protocol
Use uart_protocol* for bounded streaming with UART v2 and the legacy protocol.
- Implement camera link control
Use camera_link* for camera-device status and network-configuration control.
- Implement forward kinematics
Calculate the foot-end position from joint angles.
- Implement inverse kinematics
Calculate joint angles from a target position.
- Implement coordinate transforms
Transform between the world coordinate system and the local coordinate system.
- Compile and flash using the tutorial
- Install the PlatformIO extension
Use VSCode IDE with the PlatformIO extension installed.
- Select the firmware build environment
Select the environment according to the motherboard generation; NodeHexa v2 uses the nodehexa-v2 environment.
- Build the application firmware
Enter the firmware directory and build the application firmware in the nodehexa-v2 environment.
- Build and flash SPIFFS together
Build SPIFFS with the nodehexa-v2 environment and flash it together with the application firmware. The release package's version.json records supportedHardware, uartProtocolVersion, and legacyUartSupported.
- Configure single ultrasonic measurement
Make the ultrasonic sensor perform one measurement only when explicitly requested through REST, without automatically triggering obstacle avoidance or movement.
- Implement the UART v2 format
Use a binary outer frame and a UTF-8 JSON payload. Multi-byte integers use little-endian order, and the maximum payload is 512 bytes.
- Handle UART partial-frame timeout
Discard a received partial frame and resynchronize when it exceeds 250 ms.
- Validate UART v2 frames
Use CRC poly 0x1021 and init 0xffff, covering Version through the end of Payload. A REQUEST RESPONSE uses the same Sequence, while EVENT does not participate in request waiting.
- Complete the peripheral HELLO handshake
After startup, the peripheral sends HELLO with device set to camera, xiaozhi, or a generic device. The controller returns the protocol, robot type, firmware version, and explicit power.lowBatteryLatched.
- Detect UART peripheral offline state
Mark a V2 peripheral as offline in the capability interface when no valid frame is received for more than 6 seconds.
- Connect the camera to the network
After the video board is identified through UART HELLO, the controller sends the current AP's SSID and password. The camera joins the NodeHexa network only as an STA and does not create a user-configured hotspot.
- Set the camera image profile
Use QVGA by default and switch to VGA when needed; JPEG quality is fixed at 80.
- Report camera errors
Report camera overflow, acquisition errors, and encoding errors through cameraStatus EVENT and /api/caps statistics.
- Read capabilities and diagnostics
Request GET /api/caps to read robot, firmware, hardware, UART statistics, power, and peripheral capability information.
- Switch the profile through REST
Submit {"profile":"qvga"} or {"profile":"vga"} to POST /api/camera/profile to select the camera image profile.
- Set the PlatformIO PATH
Run the script in PowerShell to add PlatformIO to the PATH for the current session. To make it permanent, manually add it to the system environment variables, or run the script before each use.
- Open the project in EasyEDA Standard
Import and open the downloaded PCB project using EasyEDA Standard.
Calibrate and test
- Monitor battery voltage
Monitor battery voltage in real time.
- Configure low-voltage protection
Enable latched low-voltage warnings, a buzzer alarm that cannot be dismissed, and one of the safe unloading, posture-holding, or alarm-only policies.
- Debug robot functions using the tutorial
- Open servo calibration
Visit the /calibration page to calibrate the servos.
- Adjust robot settings
Optionally adjust the WiFi AP, low-battery policy, and action-button mode in Settings.
- Enter calibration mode
Use the calibration function to enter calibration mode with one action.
- Fine-tune each servo angle
Fine-tune each servo angle on the calibration page, view the adjustment live, and let the calibration data save automatically.
- Confirm low-battery latching behavior
After two consecutive samples confirm a low battery, the state is latched and only a power cycle can clear it.
- Configure low-battery handling
Use /api/settings to configure the low-battery policy and how movement and servo outputs are handled. The LED, Web, UART, and buzzer always report the latched state.
- Test the low-battery alarm
The low-battery alarm has the highest priority over startup and remote-controller connection sounds and cannot be disabled through Web or serial.
- Read and save robot settings
Read settings with GET /api/settings and save the low-battery policy and action-button mode with POST /api/settings.
- Check ultrasonic measurement results
The driver uses a hard timeout of 30 ms. If the module is disconnected or Echo times out, it returns valid=false and increments the timeout count.
Use it
- Connect to the robot WiFi
After powering on the robot, connect to the “NodeHexa” WiFi hotspot with password roboticscv666.
- Open the web control interface
Open http://192.168.4.1 in a browser to enter the robot control interface.
- Open the motion planner
Visit the /planner page to arrange and send robot action sequences.
- Start controlling the robot
Begin controlling the robot's motion after completing the connection and configuration.
- Use basic motion controls
Use motion controls for forward, backward, turning, sideways movement, and similar actions.
- Control robot posture
Control the robot's posture with three-axis rotation and twisting actions.
- Run performance modes
Run the free rhythm, beat swing, and entrance show performance modes.
- Control one hexapod leg
On hexapod robots only, select one leg and control its translation or lifting in real time.
- Check the battery status
Use the battery badge to view the live voltage, estimated charge, and low-battery status.
- Manage settings and firmware information
Use Settings to modify the WiFi AP, low-battery policy, and action-button mode, and to view the firmware version.
- Program and send action sequences
Enter /planner to program and send action sequences, or directly execute a single action.
- Check planner battery display
The motion planner displays live voltage and battery percentage in sync with the main page.
- Execute one limited action
Execute an action limited by cycle, step count, or distance; posture actions support cycles only.
- Run an action sequence
Execute multiple actions in series, with a maximum sequence length of 5 actions.
- Control the action queue
Append actions to the queue, clear the queue, and use emergency stop.
- Open the camera video stream
Access the camera's port 81 directly from a browser. The video does not pass through UART or controller memory.
- Manage MJPEG client connections
Actively disconnect MJPEG when the page enters the background, video mode exits, or the camera goes offline, and allow only one MJPEG client at a time.
- Request an ultrasonic measurement
GET /api/ultrasonic returns the latest distance measurement; add ?fresh=1 to start a new asynchronous measurement, with pending indicating the background measurement state.