Flashing Firmware

This chapter explains how to flash AmebaClaw firmware onto the development board. Two methods are available:

  • Online flashing: Use the browser-based flash tool — no software installation

    required.

  • Manual flashing: For developers who need command-line builds or automated

    workflows.

Note

The online flash tool requires the Web Serial API, which is only supported in the latest versions of Chrome and Edge. Firefox and Safari are not supported.

Online Flashing

Prerequisites

  • A browser that supports the Web Serial API (latest Chrome or Edge recommended)

  • Board connected to your PC via USB data cable

Warning

Use a USB data cable, not a charging cable. Some charging cables lack data pins and the device will not appear as a serial port.

Flashing Steps

  1. Open the online flash page.

  2. In the “Select application” section, choose the platform and

    application firmware from the drop-down menus.

  3. In the “Select device” section, select your board model.

  4. Click “Start flashing”. The browser shows a serial port selection dialog — choose

    the corresponding COM port and confirm. The tool downloads and flashes the firmware automatically. This takes about 1–2 minutes; do not disconnect or close the page.

  5. Once the flash log shows “Flashing complete”, the board is ready for Wi-Fi setup

    (see Wi-Fi Configuration).

Tip

If the expected COM port does not appear in the list, check the USB connection or re-seat the cable. Some systems require a USB-to-serial driver (e.g. CH340 or CP2102).

Manual Flashing (Command Line)

Manual flashing is intended for developers who need custom firmware builds, CI/CD integration, or headless environments. Most users should use the online flash tool.

Prerequisites

  • Python 3.8 or later installed

  • AmebaClaw repository cloned with the build environment configured

  • Board connected to your PC via USB, with the serial device recognized

    (e.g. /dev/ttyUSB0)

Note

Run source env.sh from the repository root before any command to initialize the build environment. Without this, ameba.py cannot locate the toolchain and configuration files.

Flashing Commands

Execute the following commands in order to build and flash:

# 1. Initialize the build environment (required in every new terminal session)
source env.sh

# 2. Specify the target SoC
python ameba.py soc RTL8721F

# 3. Build the firmware (replace /path/to/ameba_claw with the actual path)
python ameba.py build -a /path/to/ameba_claw

# 4. Flash the firmware (replace -p with your actual serial port)
python ameba.py flash -p /dev/ttyUSB0 -b 1500000

# 5. Open the serial monitor to view device output
python ameba.py monitor -p /dev/ttyUSB0 -b 1500000

Parameters:

  • -p /dev/ttyUSB0: Serial port path. On Windows, use COM3, COM4, etc., matching the port shown in Device Manager.

  • -b 1500000: Baud rate. Both flashing and monitoring use 1500000 bps.

Tip

Press Ctrl+C to exit the serial monitor. The monitor itself does not affect the running state of the board.