[docs] Rewrite flashing guides
This commit is contained in:
Kuba Szczodrzyński
4
docs/platform/SUMMARY.md
Normal file
4
docs/platform/SUMMARY.md
Normal file
@@ -0,0 +1,4 @@
|
||||
# Flashing guides
|
||||
|
||||
* [Beken BK72xx](beken-72xx/README.md)
|
||||
* [Realtek RTL8710Bx](realtek-ambz/README.md)
|
||||
@@ -1,24 +1,123 @@
|
||||
# Beken 72xx
|
||||
|
||||
<div align="center" markdown>
|
||||
## Introduction
|
||||
|
||||
[Read flashing guide](flashing.md){ .md-button }
|
||||
</div>
|
||||
Beken BK7231 is a family of Wi-Fi and BLE microcontrollers, of which most popular are BK7231N and BK7231T.
|
||||
|
||||
## Resources
|
||||
Features:
|
||||
|
||||
Name | Notes
|
||||
------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------
|
||||
[BK7231U Datasheet v0.71](https://cdn.discordapp.com/attachments/983843871320580096/1050461302537064508/BK7231Uv0.71.zh-CN.en.pdf) | Machine-translated to English
|
||||
[BL2028N Datasheet v1.0](https://cdn.discordapp.com/attachments/983843871320580096/1050461346111697028/BL2028N_Datasheet_v1.0.pdf) | BL2028N is a "clone" of BK7231N
|
||||
[BK72XX SDK User Manual 3.0.3](https://cdn.discordapp.com/attachments/983843871320580096/1003661237730672730/BK72XX_SDK_User_Manual-3.0.3.pdf) | Machine-translated to English
|
||||
[BEKEN WiFi SDK API Reference 3.0.27](https://cdn.discordapp.com/attachments/983843871320580096/1003661237349003355/BEKEN_WiFi_SDK_API_Reference-3.0.27_compressed.pdf) | Machine-translated to English
|
||||
[Beken SDK documentation (online)](http://docs.bekencorp.com/backup/v3.0/) | Not much here
|
||||
[`encrypt v0.3` source code](https://github.com/ghsecuritylab/tysdk_for_bk7231/tree/master/toolchain/encrypt_crc) |
|
||||
[`ota_tools` source code](https://github.com/tiancj/rtt_ota_tools) | Encryption routines and FPGA code used on the chip
|
||||
[BK7231 OpenOCD debugging](https://www.elektroda.com/rtvforum/viewtopic.php?p=20028605#20028605) | From Elektroda.pl user `@xabean`
|
||||
- ARM968E-S (ARMv5TE) CPU (120 MHz)
|
||||
- 256 KiB SRAM
|
||||
- built-in 2 MiB SPI flash with XiP
|
||||
- 802.11b/g/n Wi-Fi
|
||||
|
||||
## General info
|
||||
Resources:
|
||||
|
||||
- [BK7231U Datasheet v0.71](https://cdn.discordapp.com/attachments/983843871320580096/1050461302537064508/BK7231Uv0.71.zh-CN.en.pdf) (Machine-translated to English)
|
||||
- [BL2028N Datasheet v1.0](https://cdn.discordapp.com/attachments/983843871320580096/1050461346111697028/BL2028N_Datasheet_v1.0.pdf) (BL2028N is a "clone" of BK7231N)
|
||||
- [BK72XX SDK User Manual 3.0.3](https://cdn.discordapp.com/attachments/983843871320580096/1003661237730672730/BK72XX_SDK_User_Manual-3.0.3.pdf) (Machine-translated to English)
|
||||
- [BEKEN WiFi SDK API Reference 3.0.27](https://cdn.discordapp.com/attachments/983843871320580096/1003661237349003355/BEKEN_WiFi_SDK_API_Reference-3.0.27_compressed.pdf) (Machine-translated to English)
|
||||
- [Beken SDK documentation (online)](http://docs.bekencorp.com/backup/v3.0/)
|
||||
- [`encrypt v0.3` source code](https://github.com/ghsecuritylab/tysdk_for_bk7231/tree/master/toolchain/encrypt_crc) (Encryption routines and FPGA code used on the chip)
|
||||
- [`ota_tools` source code](https://github.com/tiancj/rtt_ota_tools)
|
||||
- [BK7231 OpenOCD debugging](https://www.elektroda.com/rtvforum/viewtopic.php?p=20028605#20028605) (From Elektroda.pl user `@xabean`)
|
||||
|
||||
## Finding your board
|
||||
|
||||
{%
|
||||
include-markdown "../../inc/find-board.md"
|
||||
%}
|
||||
|
||||
## Flashing
|
||||
|
||||
BK7231 has two UART ports - UART2 (sometimes called LOG_UART) and UART1. The UART1 port is used for flashing (and external components, such as TuyaMCU) and has no text output. The UART2 port is used for log viewing only.
|
||||
|
||||
You need to find which pins correspond to UART1 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.
|
||||
|
||||
For best experience, you should have two USB<->UART adapters plugged in:
|
||||
|
||||
- One for flashing, preferably a real FT232RL or a good alternative. This connects to UART1 of the chip.
|
||||
- One for log output - BK72xx outputs messages on a separate port. You can have a terminal session continuously open on this adapter. This connects to UART2 of the chip - but it's not necessary for flashing.
|
||||
|
||||
### Wiring
|
||||
|
||||
Connect UART1 of the BK7231 to the USB-TTL adapter:
|
||||
|
||||
PC | BK7231
|
||||
----|-----------------------
|
||||
RX | TX1 (GPIO11 / P11)
|
||||
TX | RX1 (GPIO10 / P10)
|
||||
GND | GND
|
||||
|
||||
{%
|
||||
include-markdown "../../inc/uart-power.md"
|
||||
%}
|
||||
|
||||
The download mode is entered when the chip communicates with the flasher program. Hence, the first step is running the flasher program (described below). While the program is trying to establish communication, **the chip has to be rebooted**. In order to do that, you need to bridge CEN pin to GND with a wire.
|
||||
|
||||
{%
|
||||
include-markdown "../../inc/uart-cen.md"
|
||||
%}
|
||||
|
||||
Keep in mind that BK7231T (not N) will exit the download mode when it can't communicate with the flasher (or when the flasher finishes its work). It's not possible to forcefully enter download mode without it.
|
||||
|
||||
After linking with the chip, the flasher program will begin writing (or reading) the firmware automatically. If that doesn't happen, try resetting the chip again until it works.
|
||||
|
||||
If you're getting a `No response received` (or similar) error, this means that:
|
||||
|
||||
- the power supply is too weak (read above)
|
||||
- you're resetting the chip too quickly, i.e. you resetted it *after* the program started communicating with it
|
||||
|
||||
### Flashing
|
||||
|
||||
The recommended tool to flash (or dump firmware) is `ltchiptool`.
|
||||
|
||||
**Read [Using ltchiptool](../../flashing/tools/ltchiptool.md) to learn the flashing procedure**
|
||||
|
||||
!!! tip
|
||||
BK7231N can't be software-bricked, because it has a ROM that contains the download mode. **BK7231T doesn't contain it, so be careful with this one**.
|
||||
|
||||
`ltchiptool`'s Beken flashing program is based on [bk7231tools](https://github.com/tuya-cloudcutter/bk7231tools). Refer to the guide for information how to use it, but keep in mind that using the ltchiptool GUI is probably just easier.
|
||||
|
||||
### Auto-download-reboot
|
||||
|
||||
{%
|
||||
include-markdown "../../inc/uart-adr.md"
|
||||
%}
|
||||
|
||||
## Single UART adapter usage
|
||||
|
||||
If you only have a single adapter, or just want to use the UART1 (upload) port only, you can change the logging port of LibreTiny firmware.
|
||||
|
||||
Refer to [Options & config](../../dev/config.md) (`Serial output` section). Set `LT_UART_DEFAULT_PORT` to `1`, which will use UART1 for all output.
|
||||
|
||||
## 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_bk7231t_app.ota.rbl | Beken OTA package (e.g. OpenBeken)
|
||||
image_bk7231t_app.ota.ug.bin | Tuya OTA package (incl. Cloudcutter)
|
||||
image_bk7231t_app.0x011000.rbl | App partition - flashable at 0x11000
|
||||
image_bk7231t_app.0x011000.crc | Encrypted app image - not for flashing
|
||||
image_bk7231t_app.0x129F0A.rblh | RBL header - not for flashing
|
||||
|
||||
## SPI flashing (unbricking BK7231T)
|
||||
|
||||
The [bk7231_spi_flasher.py](https://github.com/openshwprojects/BK7231_SPI_Flasher/blob/main/bk7231_spi_flasher.py) script can be used to put BK7231 in SPI flashing mode. Then, one can use [flashrom](https://www.flashrom.org/Flashrom) to read/write the raw flash chip.
|
||||
|
||||
## Other tools/guides
|
||||
|
||||
These tools are **not recommended** and are kept here for reference only. Don't use them, please.
|
||||
|
||||
- [Flashing (Tuya manual)](https://developer.tuya.com/en/docs/iot/burn-and-authorize-wb-series-modules?id=Ka78f4pttsytd)
|
||||
- [BkWriter v1.6.0](https://images.tuyacn.com/smart/bk_writer1.60/bk_writer1.60.exe)
|
||||
- [hid_download_py](https://github.com/tiancj/hid_download_py)
|
||||
|
||||
|
||||
## Other info
|
||||
|
||||
There are many chip variations in this SoC family:
|
||||
|
||||
@@ -31,7 +130,7 @@ There are many chip variations in this SoC family:
|
||||
The "officially existing" ones are BK7231Q, BK7231N and BK7231U. These are supported by Beken SDKs, such as `bdk_freertos`, although `bk7231s_alios_sdk` also existed at some point.
|
||||
|
||||
- BK7231N is substantially different than the other chips, so running T code on N (and vice versa) is not directly possible.
|
||||
- BK7231Q does not have eFuse.
|
||||
- BK7231Q does not have eFuse **and BLE**
|
||||
- there are some references to U meaning USB support
|
||||
- T seems to be exclusive to Tuya boards (that would explain the name); in the T SDK from Tuya, `CFG_SOC_NAME` is set to `SOC_BK7231U`
|
||||
- T's bootloader greets with `BK7231S_1.0.5` on UART
|
||||
|
||||
@@ -1,75 +0,0 @@
|
||||
# Download mode - Beken 72xx
|
||||
|
||||
<div align="center" markdown>
|
||||
|
||||
[Read chip docs](README.md){ .md-button }
|
||||
</div>
|
||||
|
||||
Downloading is done using UART. For best experience, you should have two USB<->UART adapters plugged in:
|
||||
|
||||
- One for flashing, preferably a real FT232RL or a good alternative. This connects to UART1 of the chip.
|
||||
- One for log output - BK72xx outputs messages on a separate port. You can have a terminal session continuously open on this adapter. This connects to UART2 of the chip - but it's not necessary for flashing.
|
||||
|
||||
**Read [Using ltchiptool](../../flashing/tools/ltchiptool.md) to learn the flashing procedure**
|
||||
|
||||
!!! success "Wiring"
|
||||
Connect UART1 of the BK7231 to the USB-TTL adapter:
|
||||
|
||||
PC | BK7231
|
||||
----|-----------------------
|
||||
RX | TX1 (GPIO11 / P11)
|
||||
TX | RX1 (GPIO10 / P10)
|
||||
RTS | CEN (or RST, optional)
|
||||
GND | GND
|
||||
|
||||
Make sure to use a good 3.3V power supply, otherwise the adapter might
|
||||
lose power during chip reset. Usually, the adapter's power regulator
|
||||
is not enough and an external power supply is needed (like AMS1117).
|
||||
|
||||
If you didn't connect RTS to CEN, after starting the flasher you have
|
||||
around 20 seconds to reset the chip manually. In order to do that,
|
||||
you need to bridge CEN to GND with a wire.
|
||||
|
||||
Note that the download mode can only be activated when the flasher is running (there's no GPIO-strapping like on ESP8266). Additionally, BK7231T (not N) will exit the download mode when the flasher finishes its work.
|
||||
|
||||
!!! tip
|
||||
BK7231N can't be software-bricked, because it has a ROM that contains the download mode. **BK7231T doesn't contain it, so be careful with this one**.
|
||||
|
||||
## bk7231tools
|
||||
|
||||
`ltchiptool`'s Beken flashing program is based on [bk7231tools](https://github.com/tuya-cloudcutter/bk7231tools). Refer to the guide for information how to use it, but keep in mind that using the ltchiptool GUI is probably just easier.
|
||||
|
||||
## Auto-download-reboot
|
||||
|
||||
If you have a recent version of LibreTiny installed on the chip, you can use [Auto-download-reboot](../../flashing/tools/adr.md) to reboot the chip automatically. This is enabled by default, so you don't have to change anything.
|
||||
|
||||
## Single-adapter usage
|
||||
|
||||
If you only have a single adapter, or just want to use the UART1 (upload) port only, you can change the logging port.
|
||||
|
||||
Refer to [Options & config](../../dev/config.md) (`Serial output` section). Set `LT_UART_DEFAULT_PORT` to `1`, which will use UART1 for all output.
|
||||
|
||||
## 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_bk7231t_app.ota.rbl | Beken OTA package (e.g. OpenBeken)
|
||||
image_bk7231t_app.ota.ug.bin | Tuya OTA package (incl. Cloudcutter)
|
||||
image_bk7231t_app.0x011000.rbl | App partition - flashable at 0x11000
|
||||
image_bk7231t_app.0x011000.crc | Encrypted app image - not for flashing
|
||||
image_bk7231t_app.0x129F0A.rblh | RBL header - not for flashing
|
||||
|
||||
## SPI flashing (unbricking BK7231T)
|
||||
|
||||
The [bk7231_spi_flasher.py](https://github.com/openshwprojects/BK7231_SPI_Flasher/blob/main/bk7231_spi_flasher.py) script can be used to put BK7231 in SPI flashing mode. Then, one can use [flashrom](https://www.flashrom.org/Flashrom) to read/write the raw flash chip.
|
||||
|
||||
## Other tools/guides
|
||||
|
||||
These tools are **not recommended** and are kept here for reference only. Don't use them, please.
|
||||
|
||||
- [Flashing (Tuya manual)](https://developer.tuya.com/en/docs/iot/burn-and-authorize-wb-series-modules?id=Ka78f4pttsytd)
|
||||
- [BkWriter v1.6.0](https://images.tuyacn.com/smart/bk_writer1.60/bk_writer1.60.exe)
|
||||
- [hid_download_py](https://github.com/tiancj/hid_download_py)
|
||||
@@ -1,51 +1,115 @@
|
||||
# Realtek AmebaZ
|
||||
|
||||
<div align="center" markdown>
|
||||
## Introduction
|
||||
|
||||
[Read flashing guide](flashing.md){ .md-button }
|
||||
</div>
|
||||
Realtek AmebaZ is a family of Wi-Fi microcontrollers, primarily consisting of two chips - RTL8710BN and RTL8710BX.
|
||||
|
||||
## Resources
|
||||
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.
|
||||
|
||||
Name | Notes
|
||||
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------
|
||||
[Realtek Ameba-Z datasheet v3.4](https://web.archive.org/web/20211203124711if_/https://adelectronicsru.files.wordpress.com/2018/10/um0114-realtek-ameba-z-data-sheet-v3-4.pdf) |
|
||||
[Ameba1/AmebaZ SDK](https://github.com/ambiot/amb1_sdk) |
|
||||
Features:
|
||||
|
||||
## Realtek documents
|
||||
- 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
|
||||
|
||||
Code | Name
|
||||
-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||||
| From **amb1_sdk**
|
||||
AN0004 | [Realtek low power wi-fi mp user guide](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0004%20Realtek%20low%20power%20wi-fi%20mp%20user%20guide.pdf)
|
||||
AN0011 | [Realtek wlan simple configuration](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0011%20Realtek%20wlan%20simple%20configuration.pdf)
|
||||
AN0012 | [Realtek secure socket layer(ssl)](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0012%20Realtek%20secure%20socket%20layer(ssl).pdf)
|
||||
AN0025 | [Realtek at command](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0025%20Realtek%20at%20command.pdf)
|
||||
AN0033 | [Realtek Ameba-1 over the air firmware update](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0033%20Realtek%20Ameba-1%20over%20the%20air%20firmware%20update.pdf)
|
||||
AN0045 | [Realtek Ameba-1 power modes](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0045%20Realtek%20Ameba-1%20power%20modes.pdf)
|
||||
AN0046 | [Realtek Ameba uart adapter](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0046%20Realtek%20Ameba%20uart%20adapter.pdf)
|
||||
AN0060 | [Realtek UART update user manual](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0060%20Realtek%20UART%20update%20user%20manual.pdf)
|
||||
AN0075 | [Realtek Ameba-all at command v2.0](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0075%20Realtek%20Ameba-all%20at%20command%20v2.0.pdf)
|
||||
AN0096 | [Realtek xmodem UART update user manual](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0096%20Realtek%20xmodem%20UART%20update%20user%20manual.pdf)
|
||||
AN0110 | [Realtek Ameba-Z over the air firmware update](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0110%20Realtek%20Ameba-Z%20over%20the%20air%20firmware%20update.pdf)
|
||||
AN0111 | [Realtek Ameba-Z FreeRTOS tickless](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/AN0111%20Realtek%20Ameba-Z%20FreeRTOS%20tickless.pdf)
|
||||
UM0006 | [Realtek wificonf application programming interface](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0006%20Realtek%20wificonf%20application%20programming%20interface.pdf)
|
||||
UM0014 | [Realtek web server user guide](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0014%20Realtek%20web%20server%20user%20guide.pdf)
|
||||
UM0023 | [Realtek Ameba-1 build environment setup - iar](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0023%20Realtek%20Ameba-1%20build%20environment%20setup%20-%20iar.pdf)
|
||||
UM0027 | [Realtek Ameba-1 crypto engine](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0027%20Realtek%20Ameba-1%20crypto%20engine.pdf)
|
||||
UM0034 | [Realtek Ameba-1 memory layout](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0034%20Realtek%20Ameba-1%20memory%20layout.pdf)
|
||||
UM0039 | [Realtek Ameba-1 SDK quick start](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0039%20Realtek%20Ameba-1%20SDK%20quick%20start.pdf)
|
||||
UM0048 | [Realtek Ameba1 DEV 1v0 User Manual_1v8_20160328](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0048%20Realtek%20Ameba1%20DEV%201v0%20User%20Manual_1v8_20160328.pdf)
|
||||
UM0060 | [Realtek Ameba-1 mqtt user guide](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0060%20Realtek%20Ameba-1%20mqtt%20user%20guide.pdf)
|
||||
UM0096 | [Realtek Ameba build environment setup - gcc](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0096%20Realtek%20Ameba%20build%20environment%20setup%20-%20gcc.pdf)
|
||||
UM0096 | [Realtek Ameba-1 build environment setup - gcc](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0096%20Realtek%20Ameba-1%20build%20environment%20setup%20-%20gcc.pdf)
|
||||
UM0101 | [Realtek Ameba-1 peripheral developerment user manual](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0101%20Realtek%20Ameba-1%20peripheral%20developerment%20user%20manual.pdf)
|
||||
UM0110 | [Realtek Ameba-Z build environment setup - iar](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0110%20Realtek%20Ameba-Z%20build%20environment%20setup%20-%20iar.pdf)
|
||||
UM0111 | [Realtek Ameba-Z memory layout](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0111%20Realtek%20Ameba-Z%20memory%20layout.pdf)
|
||||
UM0112 | [Realtek Ameba-Z SDK quick start](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0112%20Realtek%20Ameba-Z%20SDK%20quick%20start.pdf)
|
||||
UM0113 | [Realtek Ameba-Z DEV 1v0 User Manual](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0113%20Realtek%20Ameba-Z%20DEV%201v0%20User%20Manual.pdf)
|
||||
UM0115 | [Realtek Ameba-Z Introduction](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0115%20Realtek%20Ameba-Z%20Introduction.pdf)
|
||||
UM0116 | [Realtek Ameba-Z SDK change](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0116%20Realtek%20Ameba-Z%20SDK%20change.pdf)
|
||||
UM0120 | [Realtek Ameba-Z User Configuration](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0120%20Realtek%20Ameba-Z%20User%20Configuration.pdf)
|
||||
UM0121 | [Realtek Ameba-Z suspend resume api](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0121%20Realtek%20Ameba-Z%20suspend%20resume%20api.pdf)
|
||||
UM0123 | [Realtek Ameba-Z power modes](https://raw.githubusercontent.com/ambiot/amb1_sdk/0c8da639b097f01c60e419405aecfafab1d08e43/doc/UM0123%20Realtek%20Ameba-Z%20power%20modes.pdf)
|
||||
Resources:
|
||||
|
||||
- [Realtek Ameba-Z datasheet v3.4](https://web.archive.org/web/20211203124711if_/https://adelectronicsru.files.wordpress.com/2018/10/um0114-realtek-ameba-z-data-sheet-v3-4.pdf)
|
||||
- [Realtek product page](https://www.realtek.com/en/products/communications-network-ics/item/rtl8710bn)
|
||||
- [Realtek PDFs for Ameba1/AmebaZ](https://github.com/ambiot/amb1_sdk/tree/0c8da639b097f01c60e419405aecfafab1d08e43/doc/)
|
||||
- [Ameba1/AmebaZ SDK](https://github.com/ambiot/amb1_sdk)
|
||||
|
||||
## Finding your board
|
||||
|
||||
{%
|
||||
include-markdown "../../inc/find-board.md"
|
||||
%}
|
||||
|
||||
## 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
|
||||
|
||||
{%
|
||||
include-markdown "../../inc/uart-power.md"
|
||||
%}
|
||||
|
||||
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
|
||||
|
||||
{%
|
||||
include-markdown "../../inc/uart-cen.md"
|
||||
%}
|
||||
|
||||
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](../../flashing/tools/ltchiptool.md) 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
|
||||
|
||||
{%
|
||||
include-markdown "../../inc/uart-adr.md"
|
||||
%}
|
||||
|
||||
## 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.
|
||||
|
||||
- [Flashing (Tuya manual)](https://developer.tuya.com/en/docs/iot/burn-and-authorize-wr-series-modules?id=Ka789pjc581u8)
|
||||
- [ImageTool (AmebaZ/AmebaD)](https://images.tuyacn.com/smart/Image_Tool/Image_Tool.zip)
|
||||
- [rtltool.py](https://github.com/libretiny-eu/ltchiptool/blob/master/ltchiptool/soc/ambz/util/rtltool.py)
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,64 +0,0 @@
|
||||
# Download mode - Realtek AmebaZ
|
||||
|
||||
<div align="center" markdown>
|
||||
|
||||
[Read chip docs](README.md){ .md-button }
|
||||
</div>
|
||||
|
||||
Downloading is done using UART2 (sometimes called Log_UART). Refer to your board documentation to find the correct pins.
|
||||
|
||||
!!! 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.
|
||||
|
||||
**Read [Using ltchiptool](../../flashing/tools/ltchiptool.md) to learn the flashing procedure**
|
||||
|
||||
!!! success "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
|
||||
|
||||
Make sure to use a good 3.3V power supply, otherwise the adapter might
|
||||
lose power during chip reset. Usually, the adapter's power regulator
|
||||
is not enough and an external power supply is needed (like AMS1117).
|
||||
|
||||
You need to put the chip in download mode manually:
|
||||
|
||||
- connect CEN to GND
|
||||
- connect TX2 to GND
|
||||
- release CEN from GND
|
||||
- release TX2 from GND
|
||||
|
||||
If the download mode is enabled, you'll see a few garbage characters
|
||||
printed to the serial console every second.
|
||||
|
||||
|
||||
!!! 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.
|
||||
|
||||
## 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.
|
||||
|
||||
- [Flashing (Tuya manual)](https://developer.tuya.com/en/docs/iot/burn-and-authorize-wr-series-modules?id=Ka789pjc581u8)
|
||||
- [ImageTool (AmebaZ/AmebaD)](https://images.tuyacn.com/smart/Image_Tool/Image_Tool.zip)
|
||||
- [rtltool.py](https://github.com/libretiny-eu/ltchiptool/blob/master/ltchiptool/soc/ambz/util/rtltool.py)
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user