Connecting to sources…

How to build ESP-Hi AI chat robot dog: the whole process

229 steps to build ESP-Hi AI chat robot dog, from buying parts, printing and assembly to software, calibration and training, with the bill of materials, shop links and t…

The OSHWHub build-cost field reads CN¥49.9 (the creator's estimate, with no BOM breakdown and nothing said about the servo base, battery, 3D printing or shipping); Espressif does not sell it, and a third-party Tindie seller asks $49.00 (2026‑11‑01, shipping extra)

Buy parts

  • Choose the MAX98357A amplifier

    Use a MAX98357A digital amplifier module with digital I2S input. Connect the speaker to the amplifier’s two output terminals.

  • Identify the HT517 amplifier

    Identify the HT517 module by its appearance. If used, verify its input, power supply, enable, and speaker plug against the actual module specifications rather than relying on header positions.

  • Choose the 8-ohm speaker

    Choose an 8Ω, 3W speaker for this build.

  • Check a 4-ohm speaker option

    If choosing a 4Ω speaker, separately check the amplifier load and power margin.

  • Choose two 400-hole breadboards

    Choose two combinable 400-hole breadboards.

  • Choose short breadboard jumpers

    Choose short jumpers intended for breadboard use.

  • Choose matching Dupont wires

    Choose Dupont wire end connectors that match the module and controller headers.

  • Choose the optional pushbutton

    A pushbutton is optional. Before installation, check its continuity because pins on the same side may already be connected.

  • Choose a 128 by 32 OLED

    Choose a 0.91-inch, 128×32 OLED display if this resolution is required.

  • Choose a 128 by 64 OLED

    Choose a 0.96-inch, 128×64 OLED display if this resolution is required.

  • Skip the 4G module initially

    Do not purchase the 4G module when building the Wi-Fi version for the first time.

  • Prepare Body Assembly Materials

    Prepare the materials listed in the materials table before assembling the ESP-Hi body.

  • Prepare Base Assembly Materials

    Prepare the materials listed in the materials table before assembling the robot dog base.

  • Prepare the ESP-Hi speaker

    Prepare an 8-ohm, 1-watt, 2014B square-cavity speaker.

  • Prepare the ESP-Hi microphones

    Prepare four 1.5 mm microphones.

  • Prepare the ESP-Hi display

    Prepare a 0.96-inch BOE TFT plug-in integrated display.

  • Prepare the base battery

    Prepare a 702040 polymer lithium battery to power the servos and power circuits in the base.

  • Prepare the base servos

    Prepare 180-degree SG92R servos. The robot-dog base consists of four servos.

  • Buy the HU-087 watch-form-factor kit

    Buy the watch-form-factor kit from the product link given in the document; it is one of the cheapest kits.

Print and make

  • Download Open Structure Files

    Download the open-source ESP-Hi structural files from the attachments for replication.

  • Prepare Body Print Parts

    Prepare one printed enclosure and one light-blocking noise-reduction part; the front acrylic panel is 1 mm thick.

  • Prepare Robot Dog Base Parts

    Prepare four 3D-printed parts for the robot dog base and use the exploded view to identify their positions.

  • Fabricate 1.2 mm Mainboard

    When fabricating the ESP-Hi MainBoard PCB, select a board thickness of 1.2 mm.

  • Fabricate Robot Dog Base PCB

    Fabricate the ServoDogBoard PCB used in the robot dog base.

Assemble

  • Arrange the breadboard layout

    Join the two breadboards and place the controller in the middle, with modules inserted on the two sides.

  • Check breadboard hole groups

    Account for the groove separating each row’s two groups of five holes. Verify continuity and any breaks in the power rails before wiring.

  • Wire the OLED over shared I2C

    Both display sizes can share the I2C connections on GPIO41 and GPIO42.

  • Disconnect all power before wiring

    Disconnect every power source before making any connections.

  • Locate pins by GPIO labels

    Find connections using the board's GPIO numbers and power silkscreen, not the photo orientation or header sequence. Check that the breadboard's power rails are not split in the middle.

  • Power the microphone and OLED

    Connect the INMP441 and the OLED described here to 3V3; do not connect either to 5V.

  • Power the amplifier from 5V

    Power the MAX98357A from the board's 5V power node. First verify that the board schematic agrees; this instruction applies only to a USB-powered DevKitC-1 with matching power wiring.

  • Connect module signal grounds

    Connect each module's signal ground to the development board's GND. The amplifier speaker negative terminal is not a signal ground.

  • Avoid raw regulator and duplicate power

    Do not take power from bare regulator pins or inject a second power supply into the board's 5V or 3V3 rail.

  • Complete the fixed wiring scheme

    Connect the microphone, amplifier, speaker, and OLED according to the complete wiring diagram, then use the following table to check each wire individually.

  • Map the 44-pin Espressif board

    Use the 44-pin position diagram to locate the labeled pins. For the Wi-Fi version, omit the entire 4G/LDO branch and power the amplifier from the board's 5V node.

  • Map the 42-pin GOOUUU board

    Use the 42-pin position diagram because the power header positions differ. For the Wi-Fi version, omit the entire 4G/LDO branch and power the amplifier from the board's 5V node.

  • Match signals across board variants

    Both diagrams use microphone GPIO4/5/6, amplifier GPIO7/15/16, and OLED GPIO41/42 for the same signal relationships. Verify that the chip, memory, and modules also match before using the same bread-compact-wifi build.

  • Do not infer GPIO by board orientation

    Identify every connection by the named GPIO rather than treating the board's left or right position as a GPIO number.

  • Connect the INMP441 microphone

    Connect the microphone using the GPIO4/5/6 signal relationships, 3V3 power, and board GND shown for the INMP441. Its SD signal is an output and connects to the firmware input DIN; consult the INMP441 data sheet for power and channel-selection details.

  • Check microphone pin orientation

    Determine which side of the module faces up and match identically named signals from the silkscreen. For the reverse-mounted 44-pin or 42-pin boards, use the corresponding position diagram; electrical signals remain matched as WS, SCK, and SD.

  • Configure amplifier and connect speaker

    Connect the amplifier and speaker, treating SD/MODE and GAIN according to the module manufacturer’s default operating settings. If a bare board requires an external resistor or enable signal, complete that circuit first rather than leaving the input floating.

  • Connect microphone directly to amplifier

    When not using a breadboard, use the diagram to identify the connections between the microphone and MAX98357A. Keep the signal correspondence consistent with the audio table, and adjust the shown 3V3 amplifier branch and shorting connections for the selected power supply and actual module settings.

  • Connect OLED over I2C

    Connect the OLED’s VCC, GND, SDA, and SCL wires. This board type uses I2C address 0x3C; 128×32 and 128×64 displays require different firmware variants, while SH1106, SPI displays, and other addresses cannot become equivalent through rewiring alone.

  • Connect optional external buttons

    Connect GPIO0, GPIO40, and GPIO39 separately through buttons to GND, corresponding to BOOT, volume up, and volume down in this version. Before using a four-pin tactile switch, identify which two pins are internally connected and do not insert both ends into the same connected breadboard row.

  • Inspect hidden wiring under modules

    Before installing the modules, photograph and inspect the area beneath them. Check that power, GND, and signals are not shifted by one row and that the jumper across the breadboard’s long power rail is complete.

  • Check the assembled layout and wiring

    Use the photos to check the overall layout, soldered or Dupont wiring, and OLED completion state.

  • Connect power according to the chosen plan

    Wire the amplifier and 4G power supply according to the selected plan; do not infer signal names from wire colors in the photos.

  • Secure Speaker and PCB

    First secure the speaker to the body structure, then secure the PCB to the printed enclosure.

  • Fit Antenna and USB Port

    Insert the left side and top into the enclosure first, then use the printed enclosure's flexibility to fit the USB port; the antenna is very close to the enclosure.

  • Install Noise-Reduction Structure

    Install the light-blocking noise-reduction part between the PCB and printed panel to reduce microphone pickup noise.

  • Attach Display to Acrylic Panel

    Stick the display onto the front acrylic panel. First secure it in the attachment's display-adhesive jig, apply the adhesive, and then remove the display.

  • Install Base PCB Battery and Servos

    Install the PCB, battery, and four servos into the bottom enclosure in that order.

  • Connect Servo Pins by Labels

    Insert the servo pins according to the silkscreen labels on the PCB to avoid reversing their order.

  • Install PCB Front Cover

    Fit the PCB front cover onto the base.

  • Install Enclosure Top Cover

    Fit the enclosure top cover onto the base.

  • Attach Servo Arm to Printed Leg

    Select the smallest servo arm from the servo accessory pack and secure it to the 3D-printed leg with the smallest screw.

  • Mount Printed Leg on Servo

    Mount the printed leg with its servo arm onto the servo and secure it with a screw.

  • Connect USB Type-C Power

    Use USB Type-C for power and use the RT9013 to reduce the voltage to 3.3 V for the MCU and audio sections.

  • Select Low-Dropout Regulator

    Because ESP32-C3 has high transient current during Wi-Fi transmission, use an LDO or DCDC chip with the lowest possible load-regulation rate.

  • Separate Microphone Power Noise

    Add an extra low-pass filter circuit to separate the microphone and MCU power rails and prevent power noise from reaching the microphone.

  • Connect Electret Microphone Circuit

    Use an electret microphone capsule with a transimpedance amplifier to convert its output current to voltage, then apply resistor bias and send it to the ESP32 ADC.

  • Connect Differential I2S-PDM Output

    Use a direct I2S-PDM output and transmit it differentially to prevent Wi-Fi transmission from interfering with the output signal.

  • Configure NS4150B Audio Amplifier

    Pass the I2S-PDM output through RC filtering, amplify it with an NS4150B audio operational amplifier, and set the output gain to 7.2 times.

  • Assemble the four-servo base

    Build the robot-dog base with four servos and connect the servo control lines directly to the ESP-Hi unit through USB-C. Power the servos directly from the battery and boost the battery voltage to 5 V to power the ESP-Hi unit.

Software

  • Keep the Custom Board Configuration Separate

    Create a new board type for a custom IO configuration, or use the `builds` array in `config.json` to produce a distinct firmware name with different `sdkconfig` macros. Give every board a unique identity and its own firmware update channel.

  • Create the Custom Board Directory

    Create a directory under `main/boards/` using the `[vendor]-[model]` naming style, such as `m5stack-tab5`.

  • Build the Custom Board Firmware

    Use the board directory as the argument to `python scripts/build.py` to build the firmware.

  • Create the board JSON configuration
  • Validate the board and build names

    Use only lowercase letters, digits, periods, and hyphens in both `type` and `name`; underscores, spaces, and uppercase letters are not allowed. Keep `type` stable after release, and `name` typically matches `type`.

  • Add common sdkconfig entries

    The documented common entries configure either 4MB or 8MB flash, either 4MB or 8MB partition table, and on-device AEC with `CONFIG_USE_DEVICE_AEC=y`. Add the entries required by the board configuration to `sdkconfig_append`.

  • Avoid redundant default settings

    The project defaults to 16MB flash and `partitions/v2/16m.csv` on applicable targets. Do not repeat values that already match the effective project configuration.

  • Create the Board Source File

    Create `my_custom_board.cc` for the board-level implementation.

  • Declare the Board Class

    Declare the board class by deriving from `WifiBoard` or `Ml307Board`.

  • Add Board Initialization Helpers

    Add initialization helpers for I2C, the display, buttons, and IoT/MCP tools. The example defines I2C and SPI initialization helpers and stores the codec I2C bus, boot button, and display.

  • Implement Required Virtual Overrides

    Implement virtual overrides such as `GetAudioCodec()`, `GetDisplay()`, and `GetBacklight()`.

  • Register the Board Class

    Register the board class with `DECLARE_BOARD(ClassName)`.

  • Initialize the SPI Bus

    Complete SPI 2 initialization using the bus configuration and automatic DMA channel.

  • Configure the Boot Button

    Register a boot-button click callback. During device startup, enter Wi-Fi configuration mode; otherwise, toggle the chat state.

  • Configure the Display SPI Interface

    Create the LCD SPI interface configuration with the defined CS and DC pins, SPI mode 2, and an 80 MHz pixel clock.

  • Configure LCD Command Parameters

    Set the SPI transaction queue depth to 10 and use 8 bits for both LCD commands and parameters before creating the panel SPI interface.

  • Create the ST7789 Display Panel

    Configure the panel with no reset GPIO, RGB element order, and 16 bits per pixel, then create the ST7789 panel.

  • Initialize and Orient the Panel

    Initialize the panel, enable color inversion, and apply the defined axis swap and mirror settings.

  • Create the SPI LCD Display

    Create an SpiLcdDisplay with the panel interface, panel handle, defined dimensions and offsets, mirror settings, and axis swap setting.

  • Add the MCP Tools Hook

    Keep the InitializeTools function as the place to register MCP tools according to docs/mcp-usage.md.

  • Initialize the Custom Board

    Construct the board with the configured boot-button GPIO, initialize I2C, SPI, the display, buttons, and tools, and set backlight brightness to 100.

  • Configure the ES8311 Audio Codec

    Create an ES8311 audio codec on I2C bus 0 using the defined input and output sample rates.

  • Connect the Audio Codec Pins

    Configure the codec with the defined I2S MCLK, BCLK, WS, data output, data input, amplifier, and ES8311 address pins, then return the codec.

  • Return the Display Instance

    Return the display instance created by the board initialization.

  • Configure the PWM Backlight

    Create a PWM backlight using the defined backlight GPIO and output inversion setting, then return the backlight instance.

  • Declare the Custom Board

    Declare MyCustomBoard as a board using the board declaration macro.

  • Add a custom board Kconfig entry

    Add `BOARD_TYPE_MY_CUSTOM_BOARD` to the `choice BOARD_TYPE` block in `main/Kconfig.projbuild`. Use an uppercase, underscore-separated identifier and set `depends on` to the matching target, such as `IDF_TARGET_ESP32S3` or `IDF_TARGET_ESP32C3`.

  • Add the custom board CMake branch

    Open `main/CMakeLists.txt` and add an `elseif(CONFIG_BOARD_TYPE_MY_CUSTOM_BOARD)` branch to the board-type chain. Set `BOARD_DIR` to `my-custom-board`, choose `BUILTIN_TEXT_FONT` and `BUILTIN_ICON_FONT`, and optionally set `DEFAULT_EMOJI_COLLECTION` to `twemoji_64`.

  • Choose display fonts and emoji collection
  • Set the ESP32 target chip

    Select ESP32-S3, ESP32-C3, or ESP32 for the custom board. Run this when configuring the board for the first time or switching targets.

  • Clean stale build configuration

    Remove stale configuration before configuring and building the board.

  • Select the custom board type

    Open menuconfig, navigate to `Xiaozhi Assistant -> Board Type`, and select the custom board.

  • Build, flash, and monitor firmware

    Build the firmware, flash it to the board, and start the serial monitor.

  • Build the board automatically

    When the custom board directory contains `config.json`, run the build script with the board name to configure and build it automatically.

  • Select language and wake word

    Set the interface language and voice prompts with `--language`, and override the language-based wake-word default with `--wake-word`. The default is `en-US`; Chinese uses `zh-CN`, and other locales are listed under `main/assets/locales/`.

  • Match wake models to the target

    ESP32-C3, C5, and C6 targets use WakeNet9s (`wn9s_*`) models. ESP32-S3, P4, and S31 targets use the AFE engine and require PSRAM; ESP32 also requires PSRAM and uses the engine without AFE.

  • Enable wake-word detection on the board

    Requests to enable wake-word detection on an unsupported or explicitly disabled board are rejected before SDK configuration. Supported targets select compatible models and respect their stated PSRAM requirements.

  • Prepare custom and Emote assets

    Custom and Emote assets retain their UI resources, while their packed speech models are replaced by the models selected in the current `sdkconfig`, or removed when wake-word detection is disabled. The resulting package must fit the assets partition.

  • List languages and wake words

    Query accepted language and wake-word values as text or in JSON format.

  • Resolve ESP-SR before listing

    The wake-word list is read from the currently resolved ESP-SR component. Run `idf.py reconfigure` first if `managed_components/` has not been populated.

Calibrate and test

  • Do not rely on the RGB LED

    Do not treat an illuminated RGB LED as proof that the wiring is correct. Check the buttons, display, recording/playback, and conversation instead.

  • Check substitute microphone modules

    If replacing the INMP441 with a ZTS6672 or ICS43434, verify pin orientation, channel, and firmware configuration before use.

  • Check the HT517 module specifications

    Identify the HT517 module, then check its actual input, supply, enable behavior, and speaker connector specifications. Do not swap it based on header position alone.

  • Check a 4Ω speaker separately

    Treat the 4Ω enclosed speaker as an example and check amplifier loading and power headroom separately.

  • Check OLED compatibility

    Do not treat SH1106 displays, SPI displays, or displays at other addresses as equivalent to this OLED by rewiring alone.

  • Use the current button behavior

    Use the current board implementation to determine button behavior, rather than a “reset Wi-Fi” label in an older picture.

  • Check connections before module installation

    Photograph and check the power, GND, and signal connections before installing the modules. Include any bridges across split power rails.

  • Check all wiring while unpowered

    Disconnect the power and check every power and signal wire.

  • Confirm the electrical connections

    Confirm that there are no rail shorts, neither amplifier output is grounded, and no connection is one pin out.

  • Verify display and startup sound

    Restart the board and check the display and startup sound.

  • Do not rely on LED color alone

    Do not use LED color alone as a success check because RGB pins differ between DevKit revisions.

  • Test one BOOT conversation

    Start one conversation with BOOT before testing the wake word supported by the selected firmware.

  • Review automatic wake-word selection
  • Choose a valid wake-word option

    The wake-word option accepts an ESP-SR model name, `nihaoxiaozhi`, `hiesp`, or `disabled`. The two aliases select a compatible model for the target.

  • Configure wake words for manual builds

    For direct `idf.py` builds, explicitly select the wake-word implementation and models in `menuconfig`. Chip defaults do not select a model, and a fresh manual configuration leaves wake-word detection disabled.

  • Bring Up the Board Incrementally

    Bring up the display first, then audio, and finally the full stack.

  • Check Hardware Compatibility

    Check the compatibility of codec, PMIC, and touch controller combinations.

  • Troubleshoot Display Appearance

    If the display looks wrong, verify the SPI configuration, mirroring, and color inversion.

  • Troubleshoot Missing Audio

    If there is no audio, check the I2S wiring, PA enable pin, and codec I2C address.

  • Troubleshoot WiFi Connection

    If the board cannot connect to WiFi, re-check the WiFi credentials and provisioning method.

  • Troubleshoot Server Connection

    If the board cannot reach the server, verify the WebSocket or MQTT endpoint configuration.

  • Test breadboard power rails

    With power disconnected, use a continuity test to confirm whether the power rails are connected or interrupted midway.

  • Verify OLED pin order

    Check the pin order and the VCC/GND positions against the silkscreen on the particular display.

  • Begin testing at low volume

    Start the initial test at a low volume because USB power capability, cables, and amplifier load can affect stability.

  • Perform a power-off wiring check

    Disconnect power and inspect every power and signal wire. Confirm that the power rails are not shorted, neither amplifier output is grounded, and no wire has entered an adjacent header pin.

  • Test conversation and wake word

    First press BOOT to begin a conversation, then test a wake word supported by the selected firmware.

  • Verify the completed robot

    Confirm that the OLED display is complete, the startup prompt is audible, and the device is online and visible in your own console.

  • Test conversation and playback

    Press the button to start a conversation, check that questions are heard and answers play, and verify that playback does not restart the device.

  • Configure BUTTON3 Short Press

    Configure BUTTON3 to interrupt or wake the device on a short press.

  • Configure BUTTON1 Volume Up

    Configure BUTTON1 to increase the volume.

  • Configure BUTTON2 Volume Down

    Configure BUTTON2 to decrease the volume.

  • Restart and check startup

    Close the connection, press RESET/EN or power-cycle the device, and check its startup prompts.

  • Verify the flashed firmware

    Confirm that writing and verification succeeded. After restart, check that the expected board firmware and version are running and that the expected display and startup sound appear.

  • Set Servo Trim

    Use `self.electron.set_trim` to set a single servo trim value from `-30` to `30`. The trim value is permanently saved; the example sets the `head` servo `trim_value` to `0`.

  • Read Servo Trims

    Call `self.electron.get_trims` to read the current trim values.

  • Adjust R18 for Microphone Sensitivity

    The ESP32-C3 voltage sampling range is approximately 0–1 V; adjust R18 according to the actual sensitivity of the selected microphone capsule.

Use it

  • Perform Head Actions

    Call `self.electron.head_move` to raise the head, lower the head, nod once, return to center, or nod continuously. The example uses `steps: 1`, `speed: 1000`, and `angle: 5`.

  • Adjust Head Servo

    Call `self.electron.servo_move` to adjust one servo using either its full name or short key. The example moves the `head` servo to `position: 100` at `speed: 800`; the angle is automatically clipped to the firmware safety range.

  • Adjust Body Servo

    Use the short key `rp` with `self.electron.servo_move` to move the corresponding servo to `position: 120` at `speed: 800`. The angle is automatically clipped to the firmware safety range.

  • Create Ordinary Movement Sequence

    Call `self.electron.servo_sequences` with `sequence` as a JSON string. The ordinary movement example sets `rp`, `lp`, and `h` servo positions, plus speed `v` and duration `d`.

  • Create Oscillation Sequence

    Use `osc` inside the `sequence` JSON string to define an oscillation action. The example sets amplitude `a`, oscillation range `o`, phase `ph`, period `p`, and cycle count `c`.

  • Call Sequence Over WebSocket

    Call the complete action sequence over WebSocket using `self.electron.servo_sequences`. The example `sequence` JSON string contains both an ordinary movement action and an oscillation action.

  • Home the Servos

    After the actions finish, call `self.electron.home` to explicitly home the robot.

  • Query Robot Status

    Call self.electron.get_status to query the robot status.

  • Query Robot IP Address

    Call self.electron.get_ip to query the robot's IP address.

  • Query Battery Level

    Call self.battery.get_level to query the battery level.

  • Set Robot Role and DOF

    Set the role to a cute desktop robot with six degrees of freedom: left-hand pitch/roll, right-hand pitch/roll, body rotation, and head up/down.

  • Configure Expressive Gestures

    Configure nodding, waving, raising a hand, lowering the head, and raising the head to express agreement, greeting, happiness, thinking, curiosity, and farewell.

  • Prefer Short Natural Gestures

    During conversations, prefer short and natural gestures.

  • Sequence Complex Gestures and Reset

    For complex expressions, use self.electron.servo_sequences to arrange gestures in segments, then call self.electron.home to reset.

  • Use the USB connector only for charging

    The onboard USB connector is not wired to the ESP32-S3 USB pins and can only be used for charging.

Common problems

  • Camera module compatibility causes crashes, failures, or corrupted images #1588 #1394 #1457
  • Camera captures cannot be uploaded #1039
  • MCP or IoT commands target the wrong device or skip actions #204 #1011 #1142
  • Custom wake words and far-field speech recognition often fail #668 #1190 #1191 #2262
  • Upgrades cause SSL linking and I2S channel build errors #991
  • Device screen freezes during operation #478
  • Audio state changes unexpectedly interrupt playback or conversations #1014 #1114 #1652
  • Provisioning, device verification, or online flashing fails #1201 #1353 #1802

Parts

  • Head: ESP-Hi MainBoard (ESP32‑C3, 4 MB flash, 1.2 mm board), RT9013 LDO for 3.3V
  • 4×1.5 mm electret microphone, 8Ω 1W 2014B cavity speaker, NS4150B amplifier, 0.96-inch BOE plug-in TFT
  • Head structure: 3D-printed shell and light-blocking, noise-damping insert, 1 mm acrylic panel, M2×4 self-tapping screws
  • Dog base: ServoDogBoard, 4 × 180° SG92R servos, a 702040 500 mAh Li-ion cell, 4 printed parts and a TC‑005 male USB-C plug; the battery is boosted to 5V for the head

Tools

  • PCBs ordered at 1.2 mm; SMD soldering tools
  • A 3D printer; the files include a jig for gluing the screen straight
  • A USB cable for flashing (power up with Boot held to enter download mode)

Skills

  • SMD soldering and small-part assembly (plug the servos in by the silkscreen order)
  • ESP‑IDF builds and flashing, or flashing the supplied binary at 0x00
  • XiaoZhi AI Wi‑Fi provisioning and the xiaozhi.me console

Software

  • The espressif/esp-hi board in xiaozhi-esp32 (python scripts/build.py espressif/esp-hi), with the esp-hi.local web controls built in
  • Gitee examples: web_control, servo_dog, audio_loop_test, wake_word_test, lcd_audio, music_player, sensor_test and the factory binary
  • espfriends/servo_dog_ctrl 0.2.0 on the ESP Component Registry (2026‑07‑15, adapted to IDF v6)

Documents