Connecting to sources…

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

Documents