Realtek AmebaZ

Introduction

Realtek AmebaZ is a family of Wi-Fi microcontrollers, primarily consisting of two chips - RTL8710BN and RTL8710BX.

RTL8710BX seems to be the same chip but clocked at 62.5 MHz (instead of 125 MHz for BN). However, it seems that firmware compiled for either of the chips can run on the other with no issues.

Features:

ARM Cortex M4 CPU (up to 125 MHz)
512 KiB ROM
256 KiB SRAM
SPI flash interface with XiP
802.11b/g/n Wi-Fi

Resources:

Finding your board

You need to know which board your device uses. Head to Supported Boards to find it. A good number of popular boards have their dedicated support and documentation pages in LibreTiny. Otherwise, you have to use one of the Generic boards that matches the CPU model of your device.

Flashing

Realtek RTL8710B has two UART ports - UART2 (sometimes called LOG_UART) and UART0. The port used for flashing and viewing logs is UART2.

You need to find which pins correspond to UART2 TX and RX. If your board is supported, you'll find the pinout on its documentation page. Otherwise (and for generic boards), you'll have to find the pinout online.

Tip

You need a good USB<->UART adapter for the process. Some chips may not support 1.5M baud rate, required by the ROM for the initial handshake. Widespread PL2303 is currently known not to work, at least under Windows. FT232RL is verified to work reliably.

Wiring

Connect UART2 of the Realtek chip to the USB-TTL adapter:

PC	RTL8710B
RX	TX2 (Log_TX / PA30)
TX	RX2 (Log_RX / PA29)
GND	GND

Important

Using a good, stable 3.3V power supply is crucial. Most flashing issues are caused by either voltage drops during intensive flash operations, or bad/loose wires. The UART adapter's 3.3V power regulator is usually not enough.

Instead, a regulated bench power supply, or a linear 1117-type regulator is recommended.

In order to flash the chip, you need to enable download mode. This is done by resetting the chip while pulling down the TX2 pin.

Do this, in order:

connect CEN to GND
connect TX2 to GND
release CEN from GND
release TX2 from GND

Note

"CEN" pin is the RESET pin - connecting it to GND will keep the chip in "reset" state. Disconnecting it will allow the chip to start back up.

If you're having issues with using CEN pin (or if it's not accessible on your device) you can toggle the 3.3V power instead. Removing power will keep it in "reset", and applying it back will start it again.

To find out whether download mode is enabled, open a serial terminal (such as PuTTY) on your PC. You should see a few characters printed to the serial console every second (usually some kind of grey blocks, or other non-letter characters).

Note that you will not see any characters before you release TX2 from GND.

Partition layout

When you compile firmware for Realtek with LibreTiny (either ESPHome or other PlatformIO projects), you need to choose a board. Different Realtek boards have different partition layouts - the main difference is the OTA2 firmware address. Choosing a board with wrong address will make it harder to flash OTA updates.

Flashing over UART will update (set) the on-chip OTA address to match the firmware being flashed. OTA flashing will not update the address - so make sure to choose the correct board, and keep using the same board for OTA flashing.

Using incorrect boards may result in OTA updates having no effect, or (worst case) bricking the device completely.

Flashing

The recommended tool to flash (or dump firmware) is ltchiptool.

Read Using ltchiptool to learn the flashing procedure

Tip

Because the UART uploading code is programmed in the ROM of the chip, it can't be software-bricked, even if you damage the bootloader.

Auto-download-reboot

If you have a recent version of LibreTiny already installed on the chip, you don't need to perform any steps to enter download mode. Instead, Auto-download-reboot will reboot the chip automatically, as soon as it notices the flasher program. This is enabled by default, so you don't have to configure anything.

Firmware output files

These files are present in the build directory after successful compilation:

File	Description
firmware.uf2	UF2 package for UART and OTA upload
image_ota1.0x00B000.bin	OTA 1 image, flashable to 0xB000
image_ota2.0x0D0000.bin	OTA 2 image, flashable to 0xD0000 (the address might be different)

Other tools/guides

These tools are not recommended and are kept here for reference only. Don't use them, please.

OTA1/2 files can be flashed using ImageTool_v2.3.1_AmebaZ(8710b). Browse and select one of the files and enter an appropriate address. Select COM port, press Open and then Download.

This method is not recommended, as it requires you to know the currently enabled OTA index (1 or 2). Flashing the wrong file will either not make any changes, or upload firmware which won't run.