How to build ESP-SparkBot: the whole process
232 steps to build ESP-SparkBot, from buying parts, printing and assembly to software, calibration and training, with the bill of materials, shop links and the official …
Not sold by Espressif, and OSHWHub gives no BOM or build cost; third-party Tindie seller innoelement lists a kit at $79 and an assembled unit at $108 (2026‑10‑31, before shipping; the page says Espressif does not supply it and two reviews report non-delivery); individual Taobao sellers' prices not checked
Buy parts
- Prepare the head power switch
The main head now includes a power-off switch, and its link has been added to the bill of materials.
- Buy the listed components
Obtain an ESP32-S3-WROOM-1-N16R8 and a 4P pogopin magnetic connector according to the bill of materials.
- Buy the 15P bent-pin female header
Buy a 1.27 mm single-row 15P bent-pin female header.
- Buy the electret condenser microphone
Buy the B4013AM422-42 electret condenser microphone, φ4.0*1.3 mm, 1.0V-10V.
- Buy the N20 geared motors
Buy the N20 geared motors.
- Buy a Finished Robot or Parts
If you do not want to replicate the robot, search Taobao for “esp-sparkbot” or use the purchase links provided. The document lists links for a line-following car robot, a desktop robot, and a group order.
- Identify the correct modules
Identify the modules from the reference photos and check their markings, model numbers, and soldering orientation. The connection steps specifically use an INMP441 microphone and a MAX98357A amplifier.
Print and make
- Print the revised head rear shell
The revised structure changes only the head rear shell. One corresponding 3D file was added to the attachments.
- Fabricate the fixed touch FPC
Fabricate the touch FPC with its known issue fixed.
- Fabricate the single-touch FPC
A new FPC file for a single top touch button has been added to the attachments.
- Fabricate two PCBs and one FPC
For the latest fabrication, only the three red-boxed items are needed: two PCBs and one FPC.
- Download the 3D print files
Download the 3D printing files from the attachments, including the ESP-SparkBot body and tracked-car chassis structures.
- Set the PCB thickness to 1mm
Select a 1mm board thickness when fabricating the PCB.
- Print or order the robot enclosure
Assemble
- Check the board model and layout
Read the complete module model printed on the metal shield and identify the development board’s header layout. Use the position diagram for either the 44-pin standard board or the 42-pin GOOUUU board; different header counts do not imply different GPIO firmware.
- Identify the digital microphone module
Identify the INMP441 module and its VDD, GND, WS, SCK, SD, and L/R pins. If substituting a ZTS6672 or ICS43434, check pin orientation, channel, and firmware configuration before installation.
- Connect the amplifier and speaker
Use the MAX98357A digital I2S amplifier and connect the speaker across its two output terminals. If using the HT517 module, check the actual input, supply, enable behavior, and speaker connector specifications rather than relying on header position.
- Select the speaker for the amplifier
The guide uses an enclosed 8Ω, 3W speaker. A 4Ω enclosed speaker is shown as an example, but amplifier loading and power headroom require a separate check.
- Inspect the breadboards and connections
Use two interlocking 400-point breadboards with the controller in the middle. With power disconnected, check power-rail continuity and whether each long rail is split midway.
- Check the optional tactile switch
Check the optional tactile switch for continuity before installation because pins on the same side may already be connected.
- Prepare the OLED display
Choose a 0.91-inch 128×32 or 0.96-inch 128×64 OLED. Both can use GPIO41/42 for I2C and need firmware matching the resolution; check the pin order and VCC/GND positions against the display markings.
- Disconnect power and identify pins
Disconnect all power before wiring. Locate pins by their printed GPIO numbers and power labels rather than photo orientation or header position numbers; breadboard power rails may be split midway.
- Power microphone and OLED from 3V3
Supply the INMP441 and the guide's OLED from 3V3, not 5V.
- Verify MAX98357A five-volt supply
Supply the MAX98357A from the board's 5V node only on a DevKitC-1 whose power wiring matches the official schematic and is powered solely through USB. Check the schematic first and do not copy this connection to an unverified compatible board.
- Connect signal grounds and prevent back-powering
Connect module signal grounds to board GND; the amplifier's negative speaker terminal is not signal ground. Do not draw power from exposed regulator pins or inject a second supply into the board's 5V/3V3 rails.
- Check the complete basic wiring
Use the complete setup diagram and tables to check every microphone, amplifier, speaker, and OLED wire. The amplifier VIN uses the verified onboard USB 5V node, while the microphone and OLED use 3V3.
- Apply the fixed Wi-Fi wiring choices
Although the layout photos show amplifier VIN on a 3V3 branch, the fixed setup uses the verified 5V node. Handle SD/MODE and GAIN according to the module's operating configuration.
- Match the 44-pin standard board
Use the 44-pin Espressif standard-board layout to find headers and place modules. Match every labeled GPIO to the physical board and omit the 4G/LDO branch for the Wi-Fi build.
- Match the 42-pin GOOUUU board
Use the 42-pin GOOUUU layout to find headers and place modules. Match every labeled GPIO to the physical board and omit the 4G/LDO branch for the Wi-Fi build.
- Use the shared GPIO assignments
Use microphone GPIO4/5/6, amplifier GPIO7/15/16, and OLED GPIO41/42 for both layouts. Confirm that the chip, memory, and modules also match before using the bread-compact-wifi build.
- Connect the microphone to the firmware
Connect the INMP441 microphone's SD output to the firmware DIN input. Use the TDK datasheet for INMP441 power and channel selection.
- Match reversed microphone header signals
Identify which side of the board faces upward and follow the matching signal labels. Do not exchange VDD and GND merely because the microphone is physically reversed.
- Connect the amplifier and speaker
Connect the amplifier and speaker according to the audio table. Configure SD/MODE and GAIN according to the module manufacturer's default operating setup.
- Add required amplifier support circuitry
If a bare amplifier module needs resistors or an enable signal, provide that circuitry before operating it. Do not rely on floating pins.
- Observe amplifier and output compatibility
Do not use MAX98357B as a drop-in replacement for A. Do not connect headphones to the speaker outputs.
- Identify direct microphone-to-amplifier wiring
Use the illustration to identify connections between the audio modules when no breadboard is used. Adjust the shown amplifier 3V3 supply and SD/GAIN links to the guide's power scheme and the actual module's operating requirements.
- Connect the OLED
Connect the OLED VCC, GND, SDA, and SCL connections.
- Connect optional external buttons
Connect buttons from GPIO0, GPIO40, and GPIO39 to GND for BOOT, volume up, and volume down respectively.
- Check tactile switch continuity
Check which four-legged tactile switch pins are internally connected. Keep both switched sides out of the same connected breadboard row.
- Inspect connections beneath modules
Photograph and inspect the power, GND, and signal connections before installing the amplifier and microphone. Check for bridges across split power rails.
- Place and connect the modules
Use the photos to check the overall module placement and soldered or Dupont connections. Connect the amplifier and 4G module according to the stated power scheme, using the signal labels rather than wire colors.
- Install the head power switch
Install the power-off switch in the main head so the robot can be shut down.
- Mount the touch-button FPC
Stick the touch buttons to the top of ESP-SparkBot with an FPC flexible cable and install two side buttons. The camera structure divides the top button into left and right sections, but both connect to the same touch pin.
- Attach the magnetic tracked chassis
Use or design a tracked-car chassis that requires a separate controller; this project uses an ESP32-C2. Connect the chassis 4P magnetic connector to the bottom connector of ESP-SparkBot.
- Connect chassis power and communication
The chassis supplies ESP-SparkBot through 5V and GND, while the other two GPIO pins can be configured as UART or I2C communication pins.
- Choose the robot power supply
ESP-SparkBot can use USB Type-C, a magnetic dock, or a lithium battery; the magnetic dock can be self-designed.
- Cut apart and sand the panels
After the PCB arrives, cut apart the panelized boards and sand them.
- Check the head board orientation
Confirm the orientation before connecting the two head boards; the document warns that reversing them may burn the boards.
- Start from a Similar Board
Copy and tweak an existing board instead of starting from scratch.
- Bring Up the Board Incrementally
Bring up the display first, then audio, and finally the full stack.
- Check Pin Assignments
Check that every pin defined in `config.h` matches the schematic.
- Check Hardware Compatibility
Check hardware compatibility, especially the codec, PMIC, and touch controller combination.
- Identify the board USB interfaces
Use the board documentation to identify its native USB and USB-UART interfaces.
- Check settings and connect the device
Recheck the chip, board variant, and language in the task details. Connect the device with a data cable.
Software
- Keep the custom board identity unique
Create a new board type, or use the `builds` array in `config.json` to produce a distinct firmware name with different `sdkconfig` macros. Do not overwrite an existing board's configuration.
- Create the custom board directory
Create `main/boards/my-custom-board` under `main/boards/` using the `[vendor]-[model]` naming style.
- Create the board configuration files
Create `config.h` for the hardware settings and `config.json` for the reported board type and build configuration.
- Prepare the config.h include guard
Wrap the board definitions in the `_BOARD_CONFIG_H_` guard and include `<driver/gpio.h>`.
- Set the audio sample rates
Set `AUDIO_INPUT_SAMPLE_RATE` to 24000 and `AUDIO_OUTPUT_SAMPLE_RATE` to 24000 in the example configuration.
- Map the audio I2S pins
Map MCLK to GPIO 10, WS to GPIO 12, BCLK to GPIO 8, DIN to GPIO 7, and DOUT to GPIO 11.
- Configure the audio codec
Set the codec PA pin to GPIO 13, I2C SDA to GPIO 0, I2C SCL to GPIO 1, and the address to `ES8311_CODEC_DEFAULT_ADDR`.
- Define button and LED pins
Define the required button and LED pin settings; the example assigns the boot button to GPIO 9.
- Set the display SPI pins
Set display SPI SCK to GPIO 3, MOSI to GPIO 5, DC to GPIO 6, and CS to GPIO 4.
- Set the display dimensions
Set the display width to 320 and height to 240.
- Set display orientation and offsets
Enable X mirroring, disable Y mirroring, enable XY swapping, and set both display offsets to 0.
- Configure the display backlight
Set the backlight pin to GPIO 2 and enable inverted backlight output.
- Create the board build configuration
Define `type` as `my-custom-board`, `target` as `esp32s3`, and a build named `my-custom-board`. Append the 8MB flash and `partitions/v2/8m.csv` settings.
- Choose the reported board type
Set `type` to the compatibility-sensitive board family reported by the firmware and keep it stable after release.
- Match the target chip
Set `target` to the real hardware chip, such as `esp32`, `esp32s3`, `esp32c3`, `esp32c6`, or `esp32p4`.
- Name the firmware build
Set the build `name` to the compatibility-sensitive firmware variant name reported by release builds; it typically matches `type`.
- Append the sdkconfig entries
Place extra sdkconfig lines in `sdkconfig_append`; they are merged into the defaults.
- Apply the naming restrictions
Allow only lowercase letters, digits, periods, and hyphens in `type` and `name`; underscores, spaces, and uppercase letters are not allowed.
- Add common sdkconfig entries
Use the listed 4MB or 8MB flash entries and 4MB or 8MB partition-table entries as needed. Add `CONFIG_USE_DEVICE_AEC=y` to enable on-device AEC.
- Avoid duplicate default settings
Do not repeat values that already match the effective project and its defaults. Applicable targets default to 16MB flash and `partitions/v2/16m.csv`.
- Create the Custom Board File
Create `my_custom_board.cc` to hold the board-level implementation.
- Declare the Board Class
Declare `MyCustomBoard` by deriving it from either `WifiBoard` or `Ml307Board`.
- Add Board Initialization Helpers
Add initialization helpers for I2C, the display, buttons, and IoT/MCP tools. The shown implementation configures an I2C master bus and prepares the display SPI bus.
- Implement Board Virtual Overrides
Override board virtual methods such as `GetAudioCodec()`, `GetDisplay()`, and `GetBacklight()`.
- Register the Custom Board
Register the board class using `DECLARE_BOARD(ClassName)` with the custom class name.
- Initialize the SPI2 Bus
Initialize the SPI bus on SPI2_HOST with the supplied bus configuration and automatic DMA channel.
- Configure the Display SPI Interface
Configure the display panel I/O with DISPLAY_SPI_CS_PIN, DISPLAY_DC_PIN, SPI mode 2, an 80 MHz pixel clock, queue depth 10, and 8-bit command and parameter fields.
- Create and Initialize the ST7789 Panel
Configure the panel with GPIO_NUM_NC as reset, RGB element order, and 16 bits per pixel. Create the ST7789 panel, then reset and initialize it.
- Orient and Create the Display
Invert the panel colors, apply DISPLAY_SWAP_XY, and mirror it with DISPLAY_MIRROR_X and DISPLAY_MIRROR_Y. Create SpiLcdDisplay with the configured dimensions, offsets, mirroring, and XY swapping.
- Program the Boot Button Behavior
Handle the boot-button click by entering Wi-Fi configuration mode when the device is starting. Otherwise, toggle the application chat state.
- Register the Board MCP Tools
Register MCP tools in InitializeTools(). The referenced usage document is docs/mcp-usage.md.
- Initialize the Custom Board
The MyCustomBoard constructor initializes I2C, SPI, the display, buttons, and tools in that order.
- Configure the ES8311 Audio Codec
Create an Es8311AudioCodec using codec_i2c_bus_, I2C_NUM_0, the configured input and output sample rates, I2S MCLK/BCLK/WS/DOUT/DIN pins, codec PA pin, and ES8311 address.
- Return the Board Display
Override GetDisplay() to return the display_ instance created during display initialization.
- Return the PWM Backlight
Override GetBacklight() to return a PwmBacklight using DISPLAY_BACKLIGHT_PIN and DISPLAY_BACKLIGHT_OUTPUT_INVERT.
- Declare the Custom Board
Register MyCustomBoard with the board declaration macro.
- Add the Custom Board Kconfig Entry
Add a `BOARD_TYPE_MY_CUSTOM_BOARD` entry inside the `choice BOARD_TYPE` block in `main/Kconfig.projbuild`. Use an uppercase, underscore-separated identifier, set `depends on` to the matching target such as `IDF_TARGET_ESP32S3` or `IDF_TARGET_ESP32C3`, and localize the label if needed.
- 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 the built-in text and icon fonts, and optionally set `DEFAULT_EMOJI_COLLECTION` to `twemoji_64`.
- Select Display Fonts and Emoji Size
- Set the ESP32 target chip
Set the target to ESP32-S3, ESP32-C3, or ESP32 the first time or when switching targets.
Calibrate and test
- Start testing at low volume
USB supply capability, cables, and amplifier loading affect stability, so begin testing at low volume.
- Confirm display compatibility
Do not treat SH1106 displays, SPI displays, or displays at other addresses as equivalent by rewiring.
- Check every wire
Disconnect power and check every power and signal wire.
- Confirm safe and correct wiring
Confirm that the power rails are not shorted, neither amplifier output is grounded, and no connection is one pin out.
- Check startup output
Restart the board, then check the OLED display and startup sound.
- Do not rely only on LED color
Do not use LED color alone as a success check because RGB pins differ between DevKit revisions.
- Check the OLED, audio, and connection
Verify that the OLED displays correctly, the startup prompt is audible, and the device connects and appears in the Console.
- Test conversation controls
Press the button to start a conversation, speak into the microphone, and confirm that replies play without restarting the device.
- Record the current board and firmware state
Record the firmware version, board ID, Flash/PSRAM, display specifications, and current provisioning state.
- Keep account settings separate from flashing
Retain agent settings in the Console account; reflashing firmware and unbinding an account are different operations.
- Verify Web Serial support
Loading the web page does not by itself establish serial support.
- Check firmware after validation errors
If the page reports a chip mismatch or invalid partition table, check the firmware. Do not bypass validation by changing addresses or erasing the entire chip.
- Verify the firmware write
Confirm that writing and verification both succeed.
- Check the restarted board
After restarting, confirm that the expected board firmware and version run, and check for the expected display and startup sound.
- Set the Backlight Brightness
Set the board backlight brightness to 100 after initializing the board components.
- 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, recheck the WiFi credentials and provisioning method.
- Troubleshoot Server Connection
If the server cannot be reached, verify the WebSocket or MQTT endpoint configuration.
- Set a Servo Trim
Set one servo's trim value from -30 to 30. The value is saved permanently.
- Read the Current Trims
Read all current servo trim values.
- Configure touch-button functions
Set the top touch button for confirmation. The left and right side buttons move the function selection up and down.
Data and training
- Connect to the WebSocket controller
Connect electronBot to WiFi, then connect to its local WebSocket control service from a device on the same LAN.
- List the available MCP tools
Send a tools/list MCP message to retrieve the available tools.
- Request the robot status
Call self.electron.get_status through the MCP tools/call method with no arguments.
Use it
- Command the robot’s hands
Give the robot commands to raise both hands, wave, clap, or lower its arms.
- Command the robot’s body
Give the robot commands to turn left by 30 degrees, turn right by 45 degrees, or return to the middle.
- Command the robot’s head
Give the robot commands to look up, lower its head as if thinking, nod, or nod repeatedly.
- Command combined robot actions
Give the robot commands to wave goodbye, show agreement, or look around.
- Perform a hand action
Set action to 1 to raise hands, 2 to release them, 3 to wave, or 4 to clap. Set hand to 1 for the left hand, 2 for the right hand, or 3 for both hands; the example uses speed 1000.
- Reset held robot poses
Raising hands, releasing hands, turning the body, looking up, and looking down remain in their completed poses. Call the corresponding release or centering action, or explicitly call self.electron.home, to return to the initial pose.
- Turn or center the robot body
Set direction to 1 to turn left, 2 to turn right, or 3 to return to the middle. The example turns left by 45 degrees with speed 1000.
- Control Head Movement
Choose action 1 to raise the head, 2 to lower it, 3 to nod once, 4 to return to center, or 5 to nod continuously.
- Adjust an Individual Servo
Use either the full servo name or its short key. The firmware automatically clips the angle to its safe range.
- Send an Ordinary Servo Move
Pass the sequence as a JSON string to `self.electron.servo_sequences`. The example contains an `a` array with an `s` target map, `v` speed, and `d` duration.
- Call the Sequence Over WebSocket
Send the ordinary movement and oscillation objects together in one WebSocket call, with the sequence embedded as a JSON string.
- Reset After the Action
Explicitly call the home action after the movement sequence finishes.
- Query Robot Status
Call self.electron.get_status with the given JSON-RPC request.
- Query Robot IP Address
Call self.electron.get_ip with the given JSON-RPC request.
- Query Battery Level
Call self.battery.get_level with the given JSON-RPC request.
- Sequence Actions and Return Home
During conversation, prefer short, natural actions. For complex performances, arrange actions in segments with self.electron.servo_sequences, then call self.electron.home to reset.
- Display weather and clock information
Use the IP address to have ESP-SparkBot display the local live date, weather, and temperature.
- Set up the Bluetooth speaker
- Play music and spoken content
Adjust the volume, select a specific announcer voice, and bind a QQ Music account to play music. The robot also supports news and audiobooks.
- Use the cyber wooden-fish feature
Enter the wooden-fish screen and tap the top button to knock and accumulate merit; after filling the meter, the relaxed fishing state begins. Multiple devices can knock together through ESP-NOW broadcasts.
- Play the cyber dice game
Rotate or shake ESP-SparkBot, and the onscreen 3D die turns using accelerometer data. When movement stops, the die gradually stops and shows its final value.
- Play gesture-controlled 2048
After entering the 2048 game, use the built-in accelerometer for gesture recognition and interaction. Touch the top touch button to reset the game.
- Use USB display output
Connect to a computer with a single USB cable and use ESP-SparkBot as a secondary display for video or games.
- Enable USB two-way audio
USB display output supports bidirectional audio, allowing ESP-SparkBot to serve as either a speaker or a microphone.
- Control the chassis and stream video
This project uses UART, with ESP-SparkBot sending control commands to the chassis controller for motion control. The camera provides live video transmission and the robot can be controlled from a phone.
- Control the car by voice
Use voice commands to make the car move forward, backward, turn left, or turn right.
- Control and use robot features
Use the wireless remote interface for robot motion control and wireless image transmission, and take photos or switch lighting effects.
- Use the onboard BOOT button
Use the onboard BOOT button for the initial conversation test.
- Test one BOOT conversation
Start one conversation with BOOT before testing the wake word supported by the selected firmware.
- Continue with portable battery power
Follow the battery power guide for portable use.
- Review custom board support
Before changing pins or adding peripherals, read the custom board support guide and establish a separate firmware identity.
- Provision the network and bind
Continue with network provisioning and binding, or reconnect automatically to the saved network.
- Run the breadboard demo
Run the breadboard demo after completing the linked tutorial.
Common problems
- Custom wake words fail to activate because resources or configuration are invalid #1191 #1190
- Camera integration crashes, fails to initialize or upload, or corrupts images #1588 #1039 #1457 #1394
- MCP tool calls intermittently fail, skip later commands, or execute only the first #1142 #1011
- Provisioning, activation, or online theme flashing fails, often with crashes or missing codes #1802 #1353 #1201
- State changes prematurely during speech or playback, interrupting active output #1652 #1114 #1014
- New versions fail to build or run with SSL linker and I2S channel errors #991
- Microphone pickup is too weak or only recognizes wake words without processing speech #668 #2262
- The screen intermittently freezes, stopping visual updates and interaction #478
Parts
- Body: ESP32‑S3‑WROOM‑1‑N16R8, OV2640 camera, 1.54-inch screen, 4Ω 3W 3020 speaker, φ4.0 electret microphone, 3.7V polymer cell (1.25 connector)
- Three PCBs joined by 1.27 mm headers plus a touch FPC; V1.2 adds an SS‑12D00G4 slide switch
- 4-pin pogo magnetic connector (5V/GPIO48/GPIO38/GND)
- Tracked chassis: two N20 gear motors, ESP32‑C2 controller, front and rear RGB boards, battery, rubber tracks (four PCBs joined with jumper wires)
- 3D prints: body shell, tracked chassis, charging dock and ear add-ons
Tools
- PCBs ordered at 1 mm thickness; panels must be cut apart and sanded
- Soldering tools (mind the orientation of the two head boards; reversing them can burn the board)
- A 3D printer or JLC 3D printing
Skills
- ESP‑IDF (C) builds and flashing
- Fine-pitch header soldering and FPC assembly
- Configuring LLM platform APIs
Software
- Gitee examples: factory_demo_v1, openai-realtime-demo, volc_rtc_sparkbot, usb_extend_screen_s3, tank (ESP32‑C2 chassis), face recognition, YOLO and more
- ESP‑SR offline speech recognition and ESP‑WHO vision models
- The esp-sparkbot board in xiaozhi-esp32; BSP espressif2022/esp_sparkbot 1.0.1 on the ESP Component Registry