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)