Project files

id: build-guide title: Build Guide sidebar_position: 7 description: Compile and flash the Otto Robot firmware using VS Code and ESP-IDF v6.0.2.

import useBaseUrl from '@docusaurus/useBaseUrl';

export const TutorialImage = ({src, alt, caption}) => (

<figcaption style={{color: 'var(--ifm-color-emphasis-700)', marginTop: '0.5rem'}}>{caption}</figcaption>

Source Code Compilation Tutorial

This tutorial explains how to compile the Otto Robot firmware using ESP-IDF in VS Code and flash the firmware to the ESP32-S3 board via USB.

:::tip

If you only want to use the robot without modifying the source code, you can go directly to the Firmware Flashing page to flash the firmware online without installing the development environment.

:::

Preparation

Before you start, please prepare the following:

• VS Code or Cursor, with the official ESP-IDF extension installed;
• ESP-IDF v6.0.2. The project recommends using v6.0 or a later stable version, with v6.0.2 being the preferred choice;
• Git and a USB Type-C cable capable of data transfer;
• An Otto Robot mainboard with a battery already installed.

Download the source code and open the project directory in your editor:

git clone https://github.com/txp666/xiaozhi-esp32.git
cd xiaozhi-esp32
code .

When using the ESP-IDF extension for the first time, follow the extension's prompts to complete the toolchain installation, and ensure the correct ESP-IDF version is displayed at the bottom of the editor.

1. Select the ESP32-S3 chip

Click the target chip name in the status bar at the bottom of the editor, and select esp32s3 from the pop-up list.

When configuring the project for the first time, ESP-IDF will download dependencies and generate build files, which may take some time. After the configuration is complete, click the gear button at the bottom to open the SDK Configuration Editor (menuconfig).

2. Selecting the Otto Robot Development Board

In the SDK configuration editor, expand Xiaozhi Assistant and locate Target Board.

Open the development board list and select Otto Robot. If this option is not available, first confirm that esp32s3 was chosen in Step 1.

3. Enable WebSocket Service

In the SDK configuration editor, search for websocket at the top, find Component config → HTTP Server → WebSocket server support, and check the box. Some source code versions automatically enable this option; if it is already checked, no further modification is needed.

Click Save in the top-right corner and wait for the configuration to be written.

4. Compiling the Firmware

Click the Build button at the bottom of the editor to start compiling. The first compilation requires downloading components and will take longer than subsequent compilations; wait for the terminal to display a build success message before proceeding to flashing.

The compilation output is located in the project's build/ directory. The VS Code ESP-IDF extension will automatically write the bootloader, partition table, main program, and resource files during flashing—do not flash only the xiaozhi.bin file. If you need to generate a distributable merged firmware, refer to the merged firmware command on the flashing page.

5. Connect the device and select the serial port

Confirm that the battery is installed, then use a USB Type-C cable to connect the Otto Robot to your computer, and select the newly appeared serial port from the ESP-IDF extension.

:::warning

• If it's the first time flashing or the device fails to automatically enter download mode, hold down the BOOT button on the mainboard while powering it on, then retry the flashing process.
• The standard version and the camera version use the same firmware. For the camera version, connect the camera before powering on; the system will detect the camera during startup.

:::

6. Flashing and Viewing Logs

Click the Flash button at the bottom of the editor.

When the flashing method selection appears, choose UART. Wait for the terminal to display flashing completion; if you need to troubleshoot startup issues, you can reopen the ESP-IDF serial monitor to view logs.

FAQ

Otto Robot not found

Confirm that the target chip is esp32s3, then close and reopen the SDK configuration editor.

Compilation keeps getting stuck at downloading components

The first build requires downloading dependencies online. Check your network connection and try again, and make sure the ESP-IDF extension is using a stable version v6.0 or higher.

Cannot find the serial port

Try a USB cable and USB port that are confirmed to support data transfer; when flashing for the first time, hold down BOOT while powering on. Windows users also need to confirm that the serial port driver is installed correctly.

Cannot Start After Flashing

First, power off the device and check whether the camera and other ribbon cables are properly connected. Then power it back on and inspect the serial port logs. If you simply want to restore the official firmware, return to the Firmware Flashing page to reflash the latest version.