LibreTiny Documentation

Lightning LN882x is a family of Wi-Fi and BLE microcontrollers designed for indoor short-range IoT applications.

Key features include:

• 32-bit Cortex M4F CPU running at 160 MHz
• 296 KiB SRAM
• Built-in flash memory ranging from 512 KiB to 2 MiB with XiP (Execute In Place) support
• 802.11b/g/n Wi-Fi connectivity
• Bluetooth 5.1 support (available on LN882H models only)

LibreTiny (formerly LibreTuya) is a PlatformIO development platform designed for IoT developers working with BK7231, RTL8710, and LN882H chips.

Its primary purpose is to provide a usable build environment by offering vendor SDKs as PlatformIO cores and, more importantly, developing Arduino-compatible cores for these chip families. These cores are modeled after the Espressif ESP32 core to facilitate porting existing ESP-based applications to these alternative IoT modules.

Supported Chip Families:

• BK7231
• RTL8710 (including RTL8710BN)
• LN882H

Note: This project is a work-in-progress.

PinScan is a TUI (text user interface) tool used to quickly verify the I/O pins of an IoT device. It allows you to map physical pins (like buttons or LEDs) to their logical identifiers by observing real-time voltage changes or by manually toggling pins.

Warning: Manipulating pins can damage hardware. Be extremely careful when writing voltages to digital and PWM pins.

Key Features:

• Digital Pin Testing: Real-time readout, continuous single-pin probing, manual scanning (toggling), and writing HIGH/LOW values.
• Analog Pin Testing: Real-time millivolt readout and single-shot readings.
• Remote Access: By setting USE_WIFI to 1 in main.h, a Telnet server is enabled on port 23, allowing for Over-the-Air (OTA) testing without a physical serial connection.

Realtek AmebaZ is a family of Wi-Fi microcontrollers featuring the RTL8710BN (125 MHz) and RTL8710BX (62.5 MHz) chips. Firmware compiled for one chip is generally compatible with the other.

Key Specifications:

• CPU: ARM Cortex-M4F (ARMv7E-M) up to 125 MHz
• ROM: 512 KiB
• SRAM: 256 KiB
• Flash: SPI flash interface with XiP
• Connectivity: 802.11b/g/n Wi-Fi

LibreTiny implements Over-the-Air (OTA) updates based on Microsoft's UF2 specification. The system uses custom extension tags to support specific OTA schemes (OTA1/OTA2) and target partition selection. All values in the UF2 format are little-endian.

Key features include:

• Multiple Firmware Images: A single UF2 file can contain multiple images (e.g., main firmware, bootloader, and config partitions).
• Dual-OTA Support: Some CPUs allow running firmware from one image while reserving another for updates. A reboot switches the active image.
• Binary Patching: To save space, OTA2 images are often not stored directly. Instead, a LT_BINPATCH tag contains instructions to convert the OTA1 image into the OTA2 image using binary patching (e.g., DIFF32).

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

Key Hardware Differences:

• CF version: Includes 2 MiB of built-in flash.
• CM version: Includes 4 MiB of built-in PSRAM but lacks internal flash.

Core Specifications:

• CPU: ARM Cortex-M33 (ARMv8-M) @ 100 MHz
• Memory: 384 KiB ROM, 256 KiB SRAM
• Connectivity: 802.11b/g/n Wi-Fi; BLE 4.2 (available on 8720 models only)

If you are using the Arduino framework, you can use the C++ API, which provides object-oriented wrappers for core functionality. Available classes include:

• LibreTiny: The main class for core operations.
• LibreTinyOTA: Wrapper for OTA updates.
• LibreTinyWDT: Wrapper for Watchdog Timer operations.
• ESP: A compatibility class for users migrating from ESP-based Arduino cores.

To use these classes, include <Arduino.h>.

The C API provides low-level access to hardware features and is available across all LibreTiny families. It is organized into several functional modules:

• CPU: CPU-specific controls and information.
• Device: Device-level configurations.
• Flash: Flash memory operations.
• Memory: RAM and memory management.
• OTA: Over-the-Air update functionality.
• Utilities: General purpose utility functions and macros.
• Watchdog: Watchdog timer (WDT) management.
• Logger: Logging utilities.
• POSIX compatibility API: A subset of POSIX functions provided for compatibility with other Arduino cores.

To use these functions, include either <libretiny.h> or <Arduino.h> in your source file.

LibreTiny provides specialized APIs for users working within the Arduino ecosystem:

• Arduino custom API: Functions that extend the standard Wiring (Arduino) library to provide additional LibreTiny-specific features.
• Arduino compatibility API: Functions and macros designed to provide compatibility between LibreTiny and other Arduino cores (such as ESP32).

These are accessed via #include <Arduino.h>.

Important: Do not use D# pin numbering

As of LibreTiny release v1.0.0, referencing GPIO pins using D# numbers (e.g., D1, D2) is deprecated and should not be used in new projects.

If you are using Arduino I/O functions, you must use the updated pin referencing method. For instructions on how to update your existing code, see the migration guide.

The LibreTiny C API is organized into three distinct function categories based on their implementation and scope. Understanding these is essential for knowing which functions are available globally and which must be implemented when working with a specific hardware family core:

1. Common functions: Implemented in the base and common core. These are universal and behave identically across all hardware families.
2. Weak functions: Provided in the common core but designed to be overridden by family cores. They may provide a default implementation that can be improved for a specific family, or they may be empty if a particular family does not support that specific feature.
3. Family functions: These are not present in the common core. They must be implemented within the specific family core to be used.