### Install Git Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/cloudcutter.md Installs the Git version control system if it is not already present on the system. ```bash sudo apt-get install git ``` -------------------------------- ### Install Docker on Ubuntu Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/cloudcutter.md Installs Docker on Ubuntu systems. After installation, add your user to the docker group and reboot. ```bash sudo apt-get install docker.io ``` ```bash sudo adduser docker ``` -------------------------------- ### Install ltchiptool with GUI extras Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/ltchiptool.md Install the ltchiptool package with GUI extras using pip. Python 3.10 or newer is required for the GUI. ```bash pip install ltchiptool[gui] ``` -------------------------------- ### Add 256dpi/MQTT Library Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/dev/libs-3rd-party.md Install the 256dpi/MQTT library, version 2.5.0 or later, for your project. This library has been tested with the `realtek-ambz` platform. ```ini lib_deps = 256dpi/MQTT@^2.5.0 ``` -------------------------------- ### Install LibreTiny Platform Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/getting-started/README.md Use this command to install the LibreTiny platform package within your PlatformIO environment. Ensure PlatformIO is installed first. ```bash pio pkg install --platform libretiny ``` -------------------------------- ### Install ltchiptool CLI Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/ltchiptool.md Install the ltchiptool package from PyPI for CLI usage. This command is used on Linux (Ubuntu) and MacOS. ```bash pip install ltchiptool ``` -------------------------------- ### Add bbx10/DNSServer Library Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/dev/libs-3rd-party.md Install the bbx10/DNSServer library, version 1.1.0 or later. This library is equivalent to the one found in the ESP32 Arduino Core and has been tested with the `beken-72xx` platform. ```ini lib_deps = bbx10/DNSServer@^1.1.0 ``` -------------------------------- ### Run ltchiptool GUI on Linux Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/ltchiptool.md Launch the ltchiptool GUI application on Linux. Ensure wxPython is installed separately if not using pip extras. ```bash ltchiptool gui ``` ```bash python -m ltchiptool gui ``` -------------------------------- ### Start Remote OpenOCD Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/platform/realtek-ambz/debugging.md Command to start OpenOCD on a remote machine with network binding enabled. ```console sudo openocd -f interface/raspberrypi2-native.cfg -f amebaz.cfg -c "bindto 0.0.0.0" ``` -------------------------------- ### Add esphome/AsyncTCP-esphome Library Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/dev/libs-3rd-party.md Install the esphome/AsyncTCP-esphome library, version 2.0.0 or later. This is ESPHome's fork of the original AsyncTCP library and has been tested with `beken-72xx` and `realtek-ambz` platforms. ```ini lib_deps = esphome/AsyncTCP-esphome@^2.0.0 ``` -------------------------------- ### Embed Multiple Files in UF2 Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/ota/uf2ota.md Example of passing multiple input parameters to embed various files into a single UF2 image. ```console "bootloader;boot.bin" "ota1;xip1.bin;ota2;xip2.bin" "config;config1.bin;config;config2.bin" ``` -------------------------------- ### Add esphome/ESPAsyncWebServer-esphome Library Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/dev/libs-3rd-party.md Install the esphome/ESPAsyncWebServer-esphome library, version 3.0.0 or later. This is ESPHome's fork of the original ESPAsyncWebServer library and has been tested with `beken-72xx` and `realtek-ambz` platforms. ```ini lib_deps = esphome/ESPAsyncWebServer-esphome@^3.0.0 ``` -------------------------------- ### OpenOCD Telnet Session Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/platform/realtek-ambz/debugging.md Example interaction with the OpenOCD telnet interface. ```cmd Microsoft Windows [Version 6.1.7601] Kuba@KUBA-PC C:\Users\Kuba # telnet 192.168.0.33 4444 Open On-Chip Debugger > mdw 0x8000000 0x08000000: 96969999 > halt target halted due to debug-request, current mode: Thread xPSR: 0x61000000 pc: 0x0000b462 msp: 0x1003ef5c > reg ===== arm v7m registers (0) r0 (/32): 0x035a9584 (1) r1 (/32): 0x00000015 [...] ===== Cortex-M DWT registers > resume > ``` -------------------------------- ### Expected OpenOCD Output Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/platform/realtek-ambz/debugging.md Example of successful OpenOCD connection output. ```text alpine:~$ sudo openocd -f interface/raspberrypi2-native.cfg -f amebaz.cfg -c "bindto 0.0.0.0" Open On-Chip Debugger 0.11.0 Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html BCM2835 GPIO nums: swclk = 11, swdio = 25 Warn : Interface already configured, ignoring Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections Info : BCM2835 GPIO JTAG/SWD bitbang driver Info : clock speed 1001 kHz Info : SWD DPIDR 0x2ba01477 Info : rtl8711b.cpu: hardware has 6 breakpoints, 4 watchpoints Info : starting gdb server for rtl8711b.cpu on 3333 Info : Listening on port 3333 for gdb connections ``` -------------------------------- ### JLink Debugger Configuration for PlatformIO Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/platform/lightning-ln882x/debugging.md Configure PlatformIO to use JLink as a custom debug server, including server path, connection details, and initialization commands. This setup is for the `ln-02` board. ```ini [env:my_board] board = ln-02 debug_tool = custom debug_server = ../JLink_Linux_V698e_x86_64/JLinkGDBServerExe -singlerun -if SWD -select USB -port 3333 -device Cortex-M4 debug_init_cmds = define pio_reset_halt_target monitor reset end target extended-remote $DEBUG_PORT ;monitor speed auto monitor reset $LOAD_CMDS $INIT_BREAK upload_protocol = custom upload_flags = -auto -startapp -exit upload_command = ../JLink_Linux_V698e_x86_64/JFlashExe -openprj"../JLink_Linux_V698e_x86_64/ln882h.jflash" -open"${BUILD_DIR}/image_firmware.bin",0 $UPLOAD_FLAGS debug_init_break = tbreak Reset_Handler ``` -------------------------------- ### ltchiptool uf2 info - Working with UF2 Files Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/ltchiptool.md Demonstrates how to use the `ltchiptool uf2 info` command to retrieve detailed information about a UF2 firmware file. ```APIDOC ## ltchiptool uf2 info - Working with UF2 Files ### Description This command allows you to inspect UF2 (USB Flashing Format) files and extract metadata about the firmware contained within. ### Example Usage ```console $ ltchiptool uf2 info ./arduinotest_22.08.01_wb2l_BK7231T_lt0.8.0.uf2 Family: BK7231T / Beken 7231T Tags: - BOARD: wb2l - DEVICE_ID: d80e20c2 - LT_VERSION: 0.8.0 - FIRMWARE: arduinotest - VERSION: 22.08.01 - OTA_VERSION: 01 - DEVICE: LibreTiny - BUILD_DATE: 6d08e862 - LT_HAS_OTA1: 01 - LT_HAS_OTA2: 00 - LT_PART_1: app - LT_PART_2: Data chunks: 1871 Total binary size: 478788 ``` ### Output Fields - **Family**: The target microcontroller family (e.g., BK7231T). - **Tags**: Various metadata tags associated with the firmware, such as board name, device ID, LibreTiny version, firmware name, build date, etc. - **Data chunks**: The number of data blocks within the UF2 file. - **Total binary size**: The total size of the firmware binary in bytes. ``` -------------------------------- ### Initialize a New PlatformIO Project Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/getting-started/README.md Command to initialize a new PlatformIO project in your desired directory. Refer to PlatformIO Core documentation for more details on command-line usage. ```bash pio project init ``` -------------------------------- ### Display CLI Help Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/ltchiptool.md View the available commands and global options for the ltchiptool utility. ```console $ ltchiptool --help Usage: ltchiptool [OPTIONS] COMMAND [ARGS]... Tools for working with LT-supported IoT chips Options: -v, --verbose Output debugging messages (repeat to output more) -T, --traceback Print complete exception traceback -t, --timed Prepend log lines with timing info -r, --raw-log Output logging messages with no additional styling -i, --indent INTEGER Indent log messages using graph lines -V, --version Show the version and exit. -h, --help Show this message and exit. Commands: dump Capture or process device dumps elf2bin Generate firmware binaries from ELF file flash Flashing tool - reading/writing link2bin Link code to binary format list List boards, families, etc. soc Run SoC-specific tools uf2 Work with UF2 files ``` -------------------------------- ### Create UF2 Package for OpenBeken Migration Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/esphome.md Command to convert an OpenBeken .RBL file into a UF2 package for ESPHome web server upload. ```bash ltchiptool uf2 write -b generic-bk7231n-qfn32-tuya -o OpenBeken.uf2 "OpenBK7231N_1.17.205.rbl=device:download" ``` -------------------------------- ### ltchiptool - General Usage and Options Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/ltchiptool.md This section details the general usage of the ltchiptool, including available global options and a list of available commands. ```APIDOC ## ltchiptool - General Usage ### Description The `ltchiptool` is a command-line tool designed for working with LibreTiny supported IoT chips. It offers various functionalities for firmware management and device interaction. ### Usage ```console $ ltchiptool --help Usage: ltchiptool [OPTIONS] COMMAND [ARGS]... Tools for working with LT-supported IoT chips Options: -v, --verbose Output debugging messages (repeat to output more) -T, --traceback Print complete exception traceback -t, --timed Prepend log lines with timing info -r, --raw-log Output logging messages with no additional styling -i, --indent INTEGER Indent log messages using graph lines -V, --version Show the version and exit. -h, --help Show this message and exit. Commands: dump Capture or process device dumps elf2bin Generate firmware binaries from ELF file flash Flashing tool - reading/writing link2bin Link code to binary format list List boards, families, etc. soc Run SoC-specific tools uf2 Work with UF2 files ``` ``` -------------------------------- ### Display uf2ota.py Help Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/ota/uf2ota.md View the command-line interface usage and required arguments. ```console $ python uf2ota.py usage: uf2ota [-h] [--output OUTPUT] [--family FAMILY] [--board BOARD] [--version VERSION] [--fw FW] {info,dump,write} inputs [inputs ...] uf2ota: error: the following arguments are required: action, inputs ``` -------------------------------- ### ltchiptool flash - Flashing and Dumping Firmware Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/ltchiptool.md Detailed instructions and commands for flashing firmware to and dumping firmware from supported devices using the `ltchiptool flash` command. ```APIDOC ## ltchiptool flash - Flashing and Dumping Firmware ### Description This section covers the `ltchiptool flash` command, which is used for reading (dumping) and writing (flashing) firmware to connected devices. It's intended for users experienced with terminal operations. ### Commands - `ltchiptool flash file `: Detects the file type based on its contents (e.g., chip from which a dump was acquired), similar to the Linux `file` command. - `ltchiptool flash read `: Makes a full flash dump of the connected device. Specifying the family is required. - `ltchiptool flash write `: Uploads a file to the device. It detects the file type automatically. ### Device Families Supported device families can be checked using the `ltchiptool list families` command. You can use any of the family names (name/code/short name/etc.) in the commands above. ### Overriding UART and Baud Rate - The upload UART port and baud rate are usually detected automatically. - To override the UART port, use `-d COMx` (Windows) or `-d /dev/ttyUSBx` (Linux). - To change the target baud rate, use `-b 460800`. - Note: The baud rate is changed after linking. Linking is performed using the chip-default baud rate. ### Advanced Flashing Options - It's not required to specify the chip family for writing files; `ltchiptool` attempts to recognize the file contents and chooses the best settings automatically. - If you want to flash unrecognized/raw binaries or fine-tune flashing parameters, specify `-f ` and `-s `. ``` -------------------------------- ### Dump UF2 File Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/ota/uf2ota.md Extract firmware binaries from a UF2 file. ```console $ python uf2ota.py dump out.uf2 $ ls -1 out.uf2_dump/ esphome_2022.6.0-dev_lt0.4.0_wr3_1_ota1_0x0.bin esphome_2022.6.0-dev_lt0.4.0_wr3_2_ota2_0x0.bin ``` -------------------------------- ### Configure Project Options in PlatformIO Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/dev/config.md Set custom firmware names, versions, build options, flash layouts, board JSON overrides, and library versions in the platformio.ini file. ```ini [env:my_board] # custom firmware name, present in UF2 output files # - default: project directory name custom_fw_name = my_firmware # custom firmware version # - default: current date in yy.mm.dd format custom_fw_version = 1.2.0 # custom build options (#defines, NOT compiler flags) custom_options.lwip = # make sure to enable LT_DEBUG_LWIP as well NETIF_DEBUG = 0x80 IP_DEBUG = 0x80 TCP_DEBUG = 0x80 custom_options.freertos = configUSE_TICK_HOOK = 1 # partition layout modification (not recommended, unless you know what you're doing) custom_flash.app = 0x12000 # custom board JSON (overrides) # - path relative to the project directory; only values specified # in the JSON will override the defaults # (it's like using board_build.xxx but for more keys) custom_board = myboard.json # custom library versions (not recommended) custom_versions.lwip = 2.1.3 custom_versions.beken_bdk = 2021.06.07 ``` -------------------------------- ### Generate UF2 File Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/ota/uf2ota.md Create a UF2 file from firmware images using the write command. ```console $ python uf2ota.py write --family RTL8710B --board wr3 --version 0.4.0 --fw esphome:2022.6.0-dev "ota1;xip1.bin;ota2;xip2.bin" $ ls -l out.uf2 -rw-r--r-- 1 Kuba None 605696 May 28 14:35 out.uf2 ``` -------------------------------- ### Inspect UF2 Firmware Files Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/ltchiptool.md Retrieve metadata and configuration details from a specific UF2 firmware file. ```console $ ltchiptool uf2 info ./arduinotest_22.08.01_wb2l_BK7231T_lt0.8.0.uf2 Family: BK7231T / Beken 7231T Tags: - BOARD: wb2l - DEVICE_ID: d80e20c2 - LT_VERSION: 0.8.0 - FIRMWARE: arduinotest - VERSION: 22.08.01 - OTA_VERSION: 01 - DEVICE: LibreTiny - BUILD_DATE: 6d08e862 - LT_HAS_OTA1: 01 - LT_HAS_OTA2: 00 - LT_PART_1: app - LT_PART_2: Data chunks: 1871 Total binary size: 478788 ``` -------------------------------- ### Configure COM ports in platformio.ini Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/platformio.md Specify the monitor and upload ports when multiple COM ports are available. ```ini [env:my_board] monitor_port = COM96 upload_port = COM96 ``` -------------------------------- ### Configuration Parameters Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/resources/tuya-pin-config.md This section lists various configuration parameters for LibreTiny, along with their descriptions and allowed values where applicable. ```APIDOC ## Configuration Parameters This section lists various configuration parameters for LibreTiny, along with their descriptions and allowed values where applicable. ### Parameter List - **ch_flagX** (integer) - X in 1..4 - **ch_num** (any) - **clean_t** (any) - **cntdown1** (any) - **ctrl_lv** (any) - **ctrl_pin** (any) - **customcode** (any) - **cyc_dpid** (any) - **dctrl_select** (any) - **dimmod** (any) - **dimt** (any) - **dimval** (any) - **door1_magt_lv** (any) - **door1_magt_pin** (any) - **door_alarm_st1** (any) - **door_mag1** (any) - **ffc_select** (any) - **inch_dp** (any) - **indep_cfgbt** (any) - **init_conf** (any) - **knum** (any) - **ktime** (any) - **leaderr** (any) - **led_dp** (any) - **lfunc** (any) - **light_status_select** (any) - **lock_dp** (any) - **lockt** (any) - **micpin** (any) - **mixway** (any) - **mutex** (any) - **mxcl_led_m** (any) - **netn_led** (any) - **netnc** (any) - **nety_led** (any) - **netyc** (any) - **nightbrig** (any) - **nightcct** (any) - **nightled** (any) - **notdisturb** (boolean) - Do not disturb (DND) mode enabled. Allowed values: 0 or 1. - **on_off_cnt** (any) - **onoff1** (any) - **onoff_clear_t** (any) - **onoff_n** (any) - **onoff_rst_m** (any) - **onoff_rst_type** (any) - **onoff_type** (any) - **onofftime** (any) - **owm** (any) - **preheatt** (any) - **rand_dpid** (any) - **remote_add_dp** (any) - **remote_list_dp** (any) - **remote_select** (any) - **resistor** (any) - **reuse_led_m** (any) - **rsthold** (any) ``` -------------------------------- ### Compile ESPHome via CLI Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/projects/esphome.md Use this command to trigger the compilation process for a specific device configuration file. ```bash python -m esphome compile yourdevice.yml ``` -------------------------------- ### Flash ESPHome via CLI Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/esphome.md Commands to compile and upload firmware using the ESPHome CLI. ```bash python -m esphome run yourdevice.yml ``` ```bash python -m esphome upload yourdevice.yml ``` -------------------------------- ### BOOT ROM Definitions Source: https://github.com/libretiny-eu/libretiny/blob/master/cores/realtek-ambz/misc/export-rom_symbol_v01.txt Definitions for Boot ROM related functions and simulation. ```APIDOC ## BOOT ROM Definitions ### Description Provides definitions for Boot ROM simulation, initialization, and information retrieval functions. ### Function Definitions - **BOOT_ROM_Simulation**: `0x4919` - **BOOT_ROM_ShowBuildInfo**: `0x52ed` - **BOOT_ROM_OTFCheck**: `0x5335` - **BOOT_ROM_InitFlash**: `0x5345` - **BOOT_ROM_FromFlash**: `0x5405` - **BOOT_ROM_InitUsb**: `0x5511` - **BOOT_ROM_Process**: `0x553d` - **BOOT_ROM_InitDebugFlg**: `0x5605` ``` -------------------------------- ### LibreTiny C API Overview Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/dev/lt-api.md The C API provides low-level access to hardware features and system utilities. It is recommended for most use cases and is available across all supported families and frameworks. ```APIDOC ## C API Overview ### Description The C API is the primary interface for LibreTiny, providing direct access to CPU, Flash, Memory, OTA, Watchdog, and Logger functionalities. It is included via `` or ``. ### Modules - **CPU**: Hardware CPU control functions. - **Device**: Device-specific information and control. - **Flash**: Flash memory management. - **Memory**: System memory management. - **OTA**: Over-the-air update capabilities. - **Watchdog**: System watchdog timer management. - **Logger**: System logging utilities. - **POSIX**: Subset of POSIX functions for compatibility. ``` -------------------------------- ### Configure LibreTiny Dedicated Keys Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/projects/esphome.md Set specific framework parameters like log levels and GPIO recovery settings. ```yaml bk72xx: framework: version: latest # verbose/trace/debug/info/warn/error/fatal loglevel: warn # suppress chip's SDK log messages # (same as LT_UART_SILENT_ALL above) sdk_silent: true # disable SWD/JTAG so that all GPIOs can be used # set to false if you want to attach a debugger gpio_recover: true ``` -------------------------------- ### Configure LibreTiny Development Versions Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/projects/esphome.md Point the framework source to a Git repository or a local directory for development purposes. ```yaml bk72xx: framework: version: "0.0.0" source: "https://github.com/libretiny-eu/libretiny" ``` ```yaml bk72xx: framework: version: "0.0.0" source: "/local_path_to_libretiny" ``` -------------------------------- ### Run ltchiptool CLI Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/ltchiptool.md Execute the ltchiptool CLI program. This can be run directly or using the python -m command. ```bash python -m ltchiptool ``` ```bash ltchiptool ``` -------------------------------- ### Perform UF2 OTA Update Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/ota/library.md Initializes the update context, validates blocks, parses headers, and writes data to flash. Requires manual management of memory allocation and block reading. ```c uint8_t target = 1; // target OTA scheme - 1 or 2 uint32_t family = F_RTL8710B; // chip's UF2 family ID uf2_ota_t *ctx = uf2_ctx_init(target, family); uf2_info_t *info = uf2_info_init(); // optional, for getting firmware info uf2_block_t *block = (uf2_block_t *)malloc(UF2_BLOCK_SIZE); uf2_err_t err; // ... // read the first header block (512 bytes) into *block // check the block for validity err = uf2_check_block(ctx, block); if (err > UF2_ERR_IGNORE) // handle the error return; // parse the header block // note: if you don't need info, you can skip this step and call uf2_write() directly err = uf2_parse_header(ctx, block, info); if (err) // handle the error return; while (/* have input data */) { // ... // read the next block into *block // check the block for validity err = uf2_check_block(ctx, block); if (err == UF2_ERR_IGNORE) // skip this block continue; if (err) // handle the error return; // write the block to flash err = uf2_write(ctx, block); if (err > UF2_ERR_IGNORE) // handle the error return; } // finish the update process // ... // activate your new OTA partition // cleanup free(ctx); free(block); uf2_info_free(info); ``` -------------------------------- ### C Standard Library Formatted Input/Output Function Prototypes Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/stdlib.md These formatted input/output functions should be included using GCC's headers and implemented by libc or wrapped and implemented in the SDK. If the printf library is used, all other vendor-defined printf-like functions should be replaced with it. ```cpp int printf(const char *format, ...); int sprintf(char *buffer, const char *format, ...); int snprintf(char *buffer, size_t bufsz, const char *format, ...); int vprintf(const char *format, va_list vlist); int vsprintf(char *buffer, const char *format, va_list vlist); int vsnprintf(char *buffer, size_t bufsz, const char *format, va_list vlist); ``` -------------------------------- ### Run tuya-cloudcutter Script Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/tools/cloudcutter.md Executes the main tuya-cloudcutter script. You will be prompted for firmware file, device vendor, and profile information. ```bash ./tuya-cloudcutter.sh ``` -------------------------------- ### Define ESPHome Device Configuration Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/projects/esphome.md Manual configuration file for LibreTiny devices. Replace the board code with the specific identifier for your hardware. ```yaml esphome: name: yourdevice bk72xx: # adjust accordingly: bk72xx or rtl87xx board: cb2s # THIS IS YOUR BOARD CODE framework: version: latest logger: web_server: captive_portal: api: ota: wifi: ssid: !secret wifi_ssid password: !secret wifi_password ap: ``` -------------------------------- ### Single OTA Scheme Partition Tags Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/ota/README.md Illustrates the UF2 extension tags `LT_PART_1` and `LT_PART_2` used for single OTA schemes. The relevant partition tag is set, while the other is empty. ```text 08 46 59 80 6f 74 61 31 | .FY.ota1 | LT_PART_1 04 d7 e4 a1 | .... | LT_PART_2 ``` -------------------------------- ### Configure Logger and Debugging Options Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/dev/config.md Enable specific logger features like timestamps, caller information, and task display. Also, enable per-module debugging for libraries like WiFi, SSL, and OTA. ```ini [env:my_board] build_flags = -D LT_LOGLEVEL=LT_LEVEL_WARN -D LT_DEBUG_ALL=1 # will print only warnings and errors from all modules ``` -------------------------------- ### Dual-OTA Single-File Scheme Partition Tags Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/ota/README.md Shows the UF2 extension tags `LT_PART_1` and `LT_PART_2` for dual-OTA schemes where a single image is used for both OTA1 and OTA2. Both tags point to the same partition name. ```text 08 46 59 80 6f 74 61 31 | .FY.ota1 | LT_PART_1 08 d7 e4 a1 6f 74 61 32 | ....ota2 | LT_PART_2 ``` -------------------------------- ### Configure ESPHome Docker Compose Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/projects/esphome.md Use this configuration to run the ESPHome dashboard via Docker. Ensure the volume path is set to your desired configuration directory. ```yaml version: "3" services: esphome: container_name: esphome image: ghcr.io/esphome/esphome:latest volumes: - ./configs:/config:rw # (1)! - /etc/localtime:/etc/localtime:ro restart: always privileged: false network_mode: host ``` -------------------------------- ### Inspect UF2 Image Info Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/ota/uf2ota.md Display metadata and parameters of a generated UF2 image. ```console $ python uf2ota.py info out.uf2 Family: RTL8710B Tags: - BOARD: wr3 - DEVICE_ID: 312d5ec5 - LT_VERSION: 0.4.0 - FIRMWARE: esphome - VERSION: 2022.6.0-dev - OTA_VERSION: 01 - DEVICE: LibreTiny - LT_HAS_OTA1: 01 - LT_HAS_OTA2: 01 - LT_PART_1: ota1 - LT_PART_2: ota2 - LT_BINPATCH: fe0900500c009094989ca0 Data chunks: 1182 Total binary size: 302448 ``` -------------------------------- ### C Standard Library Unformatted Input/Output Function Prototypes Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/contrib/stdlib.md These unformatted input/output functions should be included using GCC's headers and implemented by libc or wrapped and implemented in the SDK. ```cpp int putc(int ch, FILE *stream); int putchar(int ch); int puts(const char *str); ``` -------------------------------- ### Configure Remote Debugger in PlatformIO Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/platform/realtek-ambz/debugging.md Settings for platformio.ini to connect to a remote OpenOCD server. ```ini [env:my_board] debug_tool = custom debug_port = 192.168.0.33:3333 debug_server = ``` -------------------------------- ### Array Initialization Function Source: https://github.com/libretiny-eu/libretiny/blob/master/cores/realtek-ambz/misc/export-rom_symbol_v01.txt Function for initializing arrays. ```APIDOC ## Array Initialization Function ### Description Initializes an array with a specified value. ### Function - **ArrayInitialize** (array, size, value) - Initializes an array with a given value. ``` -------------------------------- ### Configure LibreTiny Advanced Options Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/projects/esphome.md Customize low-level LibreTiny settings such as heap logging and UART port assignments within the YAML configuration. ```yaml bk72xx: framework: version: latest lt_config: LT_LOG_HEAP: 1 LT_UART_DEFAULT_PORT: 2 LT_UART_SILENT_ALL: 0 ``` -------------------------------- ### Ambient Light Sensor Configuration Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/resources/tuya-pin-config.md Parameters for configuring ambient light sensor thresholds based on ADC readouts. ```APIDOC ## Ambient Light Sensor Configuration ### Description Defines the ADC value thresholds (0-3300) for various lighting conditions. ### Parameters #### Request Body - **day** (integer) - Optional - ADC value threshold for day - **dusk** (integer) - Optional - ADC value threshold for dusk - **evenfall** (integer) - Optional - ADC value threshold for evenfall - **evening** (integer) - Optional - ADC value threshold for evening - **night** (integer) - Optional - ADC value threshold for night ``` -------------------------------- ### Flash ESPHome via OTA Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/flashing/esphome.md Command to perform an Over-the-Air update using the ESPHome CLI. ```bash python -m esphome upload yourdevice.yml --device yourdevice.local ``` -------------------------------- ### Pairing Configuration Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/resources/tuya-pin-config.md Parameters for managing Wi-Fi pairing modes, reset cycles, and connection visual feedback. ```APIDOC ## Pairing Configuration ### Description Settings related to Wi-Fi pairing, reset behavior, and connection status indicators. ### Parameters #### Request Body - **wfcfg** (string) - Optional - Wi-Fi pairing config (spcl, spcl_auto, prod, old, low) - **remdmode** (integer) - Optional - Light reset pairing mode (0 or 1) - **rstnum** (integer) - Optional - On/off cycles to reset - **rstcor** (string) - Optional - Light color while connecting (c or r) - **rstbr** (integer) - Optional - Light brightness while connecting (10-100) - **rsttemp** (integer) - Optional - Light temperature while connecting (0-100) - **remdtime** (integer) - Optional - Pairing mode timeout in seconds - **wfptime** (integer) - Optional - Light pairing time in minutes ``` -------------------------------- ### Command Line Interface Functions Source: https://github.com/libretiny-eu/libretiny/blob/master/cores/realtek-ambz/misc/export-rom_symbol_v01.txt Functions for handling command line arguments and executing commands. ```APIDOC ## Command Line Interface Functions ### Description Provides functions for accessing command line arguments and executing ROM commands. ### Functions - **CmdRomHelp** () - Displays help for ROM commands. - **CmdDumpWord** (address) - Dumps a word from the specified address. - **CmdWriteWord** (address, value) - Writes a word to the specified address. - **CmdFlash** (address, size, data) - Writes data to flash memory. - **CmdEfuse** (address, size, data) - Writes data to eFuse. - **CmdDumpByte** (address) - Dumps a byte from the specified address. - **CmdDumpHalfWord** (address) - Dumps a half-word from the specified address. - **CmdWriteByte** (address, value) - Writes a byte to the specified address. - **GetRomCmdNum** () - Gets the number of available ROM commands. - **GetArgc** () - Gets the number of command line arguments. - **GetArgv** (index) - Gets the command line argument at the specified index. ``` -------------------------------- ### Access GPIO via Function Macros Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/getting-started/gpio.md Use board-specific labels found in pinout documentation for better portability. These macros work in both Arduino and ESPHome. ```cpp digitalRead(PIN_P6) ``` ```yaml pin: P6 ``` ```cpp digitalRead(PIN_PWM0) ``` ```yaml pin: PWM0 ``` -------------------------------- ### OpenOCD Utility Commands Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/platform/realtek-ambz/debugging.md Various OpenOCD commands for system control and memory operations. ```text mww 0xE000ED0C 0x05FA0007 ``` ```text mww 0x40000138 0x8 mww 0xE000ED0C 0x05FA0007 ``` ```text halt reg pc 0 resume ``` ```text > dump_image rom2.bin 0x0 0x80000 dumped 524288 bytes in 14.041406s (36.464 KiB/s) ``` ```text > dump_image flash.bin 0x8000000 0x200000 dumped 2097152 bytes in 54.447296s (37.614 KiB/s) ``` ```text > dump_image efuse.bin 0x40000000 0x400 dumped 1024 bytes in 0.026813s (37.295 KiB/s) ``` -------------------------------- ### Migrate GPIO Numbering in C++ Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/dev/migration_v1.0.0.md Update `digitalWrite` calls to use `PIN_D#` or `D#` constants instead of raw pin numbers for compatibility with LibreTiny v1.0.0. ```cpp digitalWrite(1, LOW); ``` ```cpp digitalWrite(PIN_D1, LOW); // or digitalWrite(D1, LOW); ``` -------------------------------- ### Enable Debug Logging in PlatformIO Source: https://github.com/libretiny-eu/libretiny/blob/master/docs/dev/config.md Enable LibreTiny logger and set the log level to DEBUG using build flags in platformio.ini. This is useful for detailed debugging. ```ini [env:my_board] build_flags = -D LT_LOGLEVEL=LT_LEVEL_DEBUG ``` -------------------------------- ### System Power Management Functions Source: https://github.com/libretiny-eu/libretiny/blob/master/cores/realtek-ambz/misc/export-rom_symbol_v01.txt Functions for controlling system power states and wake-up events. ```APIDOC ## System Power Management Functions ### Description Provides functions for managing CPU clock during power saving, booting from power save mode, and configuring wake-up events and timers. ### Functions - **SOCPS_BackupCPUClk** () - Backs up the current CPU clock setting. - **SOCPS_RestoreCPUClk** () - Restores the backed-up CPU clock setting. - **SOCPS_BootFromPS** () - Boots the system from a power-saving state. - **SOCPS_TrapPin** (pin) - Configures a pin to trap the system into power save mode. - **SOCPS_ANACKSel** (sel) - Selects the analog acknowledge source. - **SOCPS_CLKCal** () - Performs clock calibration for power saving. - **SOCPS_SetWakeEvent** (event) - Sets a wake-up event. - **SOCPS_ClearWakeEvent** (event) - Clears a wake-up event. - **SOCPS_WakePinsCtrl** (mask) - Controls wake-up pins. - **SOCPS_WakePinCtrl** (pin, enable) - Enables/disables a specific wake-up pin. - **SOCPS_WakePinClear** (pin) - Clears a specific wake-up pin status. - **SOCPS_GetANATimerParam** () - Gets analog timer parameters. - **SOCPS_SetANATimer** (param) - Sets the analog timer. - **SOCPS_SetReguWakepin** (pin) - Configures a regulator wake-up pin. - **SOCPS_SetReguTimer** (timer) - Configures a regulator wake-up timer. - **SOCPS_PWROption** (option) - Sets power management options. ```