Skip to content

Realtek AmebaZ2

Introduction

Realtek AmebaZ2 is a family of Wi-Fi (or Wi-Fi + BLE) microcontrollers, primarily consisting of RTL8710CF, RTL8720CF and RTL8720CM.

The CF version has built-in 2 MiB flash, whereas the CM version has built-in 4 MiB PSRAM (but no internal flash).

Features:

  • ARM Cortex-M33 (ARMv8-M) CPU (100 MHz)
  • 384 KiB ROM
  • 256 KiB SRAM
  • 2 MiB SPI flash (CF only) with XiP
  • 4 MiB SPI PSRAM (CM only)
  • 802.11b/g/n Wi-Fi
  • BLE 4.2 (8720 only)

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

Read this!

This is probably the most important part of the docs - flashing firmware to the chip.

This is why you're here. Please read this section carefully, and only then start flashing firmware.

Realtek RTL8720C has three UART ports - UART2 (sometimes called LOG_UART), UART1 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.

Wiring

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

PC RTL8720C
RX TX2 (Log_TX / PA16)
TX RX2 (Log_RX / PA15)
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 similar to ESP8266/ESP32, but the strapping pin (GPIO 0 / PA00) has to be pulled to 3.3V, not GND.

Additionally, make sure that pin PA13 (RX0) is NOT pulled to 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.

Do this, in order:

  • connect PA00 to 3.3V
  • apply power to the device OR shortly connect CEN to GND
  • start the flashing process

If you had a serial terminal (such as PuTTY) open at the time, you should see an Open Download Mode on UART message. This means that you've successfully entered download mode and are ready to start flashing.

Partition layout

Important

When you compile firmware with LibreTiny (either ESPHome or other PlatformIO projects), you need to choose a board. Different boards may 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 (with ltchiptool) will adjust the on-chip OTA address to match the firmware being flashed - you can safely change boards this way.

However, OTA flashing will not update the address - 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 either no effect, resulting in errors, or (in worst cases) 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_flash_is.0x000000.bin Complete Flash Image, flashable to 0x0000
image_part_table.0x000000.bin Partition Table, flashable to 0x0000
image_bootloader.0x004000.bin Bootloader Image, flashable to 0x4000
image_firmware_is.0x00C000.bin OTA 1/2, flashable to 0xC000 or OTA 2 address