Connecting to sources…

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.

Documents