Skip to content

LibreTiny API

The LibreTiny API is divided in two parts:

  • the C API, available in all families and frameworks
  • the C++ API, available in the Arduino framework only.

The C++ API is a thin wrapper around the C API (using classes with inline functions). It's provided for less-experienced users, who are used to Arduino IDE's classes like ESP (and for backwards compatibility). It's recommended to use the C API wherever possible.

C API

This API is available using:

  • #include <libretiny.h>
  • #include <Arduino.h>

CPU

Type Name
uint8_t lt_cpu_get_core_count ()
Get CPU core count.
const char * lt_cpu_get_core_type ()
Get CPU core type name as string.
uint32_t lt_cpu_get_cycle_count ()
Get CPU cycle count.
lt_cpu_family_t lt_cpu_get_family ()
Get CPU family ID (as lt_cpu_family_t enum member).
const char * lt_cpu_get_family_name ()
Get CPU family name as string.
uint32_t lt_cpu_get_freq ()
Get CPU frequency in Hz.
uint32_t lt_cpu_get_freq_mhz ()
Get CPU frequency in MHz.
uint32_t lt_cpu_get_mac_id ()
Get CPU ID based on the last three octets of MAC address. Note: the number is 24-bit (with the MSB being zero). The 3rd-to-last octet is least-significant, the last octet is most-significant.
lt_cpu_model_t lt_cpu_get_model ()
Get CPU model ID (as lt_cpu_model_t enum member).
const char * lt_cpu_get_model_code ()
Get CPU model name as string (lowercase).
const char * lt_cpu_get_model_name ()
Get CPU model name as string (uppercase).
uint32_t lt_cpu_get_unique_id ()
Get CPU unique ID. This may be based on MAC, eFuse, etc. (family-specific). Note: the number is 24-bit (with the MSB being zero).

Device

Type Name
const char * lt_get_board_code ()
Get board code.
void lt_get_device_mac (uint8_t * mac)
Read device's default MAC address into 'mac' array. This can be used even without Wi-Fi enabled, and will ignore user-changed Wi-Fi MAC (if changing is possible).
const char * lt_get_device_name ()
Get device friendly name in format "LT-<chip model>-<MAC ID>". Can be used as hostname.
lt_reboot_reason_t lt_get_reboot_reason ()
Get the reason of last chip reboot.
const char * lt_get_reboot_reason_name (lt_reboot_reason_t reason)
Get a textual representation of a reboot reason.
const char * lt_get_version ()
Get LibreTiny version string.
void lt_gpio_recover ()
Reconfigure GPIO pins used for debugging (SWD/JTAG), so that they can be used as normal I/O.
void lt_reboot ()
Reboot the CPU.
bool lt_reboot_download_mode ()
Reboot the CPU and stay in download mode (if possible).
bool lt_reboot_wdt ()
Reboot the CPU with a watchdog timeout (if possible).
bool lt_set_debug_mode (lt_debug_mode_t mode)
Set debugger mode (JTAG, SWD or OFF).

Macros

Type Name
define REBOOT_REASON_SLEEP REBOOT_REASON_SLEEP_GPIO
define RESET_REASON_BROWNOUT REBOOT_REASON_BROWNOUT
define RESET_REASON_CRASH REBOOT_REASON_CRASH
define RESET_REASON_HARDWARE REBOOT_REASON_HARDWARE
define RESET_REASON_MAX REBOOT_REASON_MAX
define RESET_REASON_POWER REBOOT_REASON_POWER
define RESET_REASON_SLEEP REBOOT_REASON_SLEEP_GPIO
define RESET_REASON_SLEEP_GPIO REBOOT_REASON_SLEEP_GPIO
define RESET_REASON_SLEEP_RTC REBOOT_REASON_SLEEP_RTC
define RESET_REASON_SLEEP_USB REBOOT_REASON_SLEEP_USB
define RESET_REASON_SOFTWARE REBOOT_REASON_SOFTWARE
define RESET_REASON_UNKNOWN REBOOT_REASON_UNKNOWN
define RESET_REASON_WATCHDOG REBOOT_REASON_WATCHDOG

Public Types Documentation

enum lt_debug_mode_t

enum lt_debug_mode_t {
    DEBUG_MODE_OFF = 0,
    DEBUG_MODE_JTAG = 1,
    DEBUG_MODE_SWD = 2
};

enum lt_reboot_reason_t

enum lt_reboot_reason_t {
    REBOOT_REASON_UNKNOWN = 1,
    REBOOT_REASON_POWER = 2,
    REBOOT_REASON_BROWNOUT = 3,
    REBOOT_REASON_HARDWARE = 4,
    REBOOT_REASON_SOFTWARE = 5,
    REBOOT_REASON_WATCHDOG = 6,
    REBOOT_REASON_CRASH = 7,
    REBOOT_REASON_SLEEP_GPIO = 8,
    REBOOT_REASON_SLEEP_RTC = 9,
    REBOOT_REASON_SLEEP_USB = 10,
    REBOOT_REASON_DEBUGGER = 11,
    REBOOT_REASON_MAX = 12
};

Flash

Type Name
bool lt_flash_erase (uint32_t offset, size_t length)
Erase flash area. Flash can only be erased in blocks (usually 4 KiB).
bool lt_flash_erase_block (uint32_t offset)
Erase a single block of flash (usually 4 KiB).
lt_flash_id_t lt_flash_get_id ()
Read flash chip ID and return a lt_flash_id_t struct.
uint32_t lt_flash_get_size ()
Get flash chip total size.
uint32_t lt_flash_read (uint32_t offset, uint8_t * data, size_t length)
Read data from the flash.
uint32_t lt_flash_write (uint32_t offset, const uint8_t * data, size_t length)
Write data to the flash.

Memory

Type Name
uint32_t lt_heap_get_free ()
Get free heap size.
uint32_t lt_heap_get_max_alloc ()
Get largest block of heap that can be allocated at once.
uint32_t lt_heap_get_min_free ()
Get lowest level of free heap memory.
uint32_t lt_heap_get_size ()
Get total heap size.
uint32_t lt_ram_get_size ()
Get total RAM size.

OTA

Type Name
void lt_ota_begin (lt_ota_ctx_t * ctx, size_t size)
Initialize the update context to begin OTA process.
bool lt_ota_can_rollback ()
Check if OTA rollback is possible (switching the stored index to another partition).
uint8_t lt_ota_dual_get_current ()
Get the currently running firmware's OTA index.
uint8_t lt_ota_dual_get_stored ()
Read the currently active OTA index, i.e. the one that will boot upon restart.
bool lt_ota_end (lt_ota_ctx_t * ctx)
Finish the update process. If the update has been written completely, try to activate the target image. Free allocated internal structures, regardless of the activation result.
lt_ota_type_t lt_ota_get_type ()
Get OTA type of the device's chip.
uf2_ota_scheme_t lt_ota_get_uf2_scheme ()
Check which UF2 OTA scheme should be used for applying firmware updates.
bool lt_ota_is_valid (uint8_t index)
Check if the specified OTA image is valid.
void lt_ota_set_write_protect (uf2_ota_t * uf2)
Set family-specific, write-protected flash areas in the OTA update context. This shouldn't be called manually, as it's done by lt_ota_begin().
bool lt_ota_switch (bool revert)
Try to switch OTA index to the other image. For single-OTA chips, only check if the upgrade image is valid.
size_t lt_ota_write (lt_ota_ctx_t * ctx, const uint8_t * data, size_t len)
Process a chunk of data.
bool lt_ota_write_block (lt_ota_ctx_t * ctx, uf2_block_t * block)
Try to write the block. In case of UF2 errors, error code is set in the context. Note: use lt_ota_write() instead. This is for internal usage only.

Public Types Documentation

enum lt_ota_type_t

enum lt_ota_type_t {
    OTA_TYPE_SINGLE = 0,
    OTA_TYPE_DUAL = 1,
    OTA_TYPE_FILE = 2
};

Utilities

Type Name
void hexdump (const uint8_t * buf, size_t len, uint32_t offset=0, uint8_t width=16)
Print data pointed to by buf in hexdump-like format (hex+ASCII).
char * lt_btox (const uint8_t * src, int len, char * dest)
Convert a byte array to hexadecimal string.
void lt_rand_bytes (uint8_t * buf, size_t len)
Generate random bytes using rand().
uint8_t * lt_xtob (const char * src, int len, uint8_t * dest)
Convert a hexadecimal string to byte array.

Watchdog

Type Name
void lt_wdt_disable ()
Disable the hardware watchdog.
bool lt_wdt_enable (uint32_t timeout)
Enable the hardware watchdog.
void lt_wdt_feed ()
Feed/reset the hardware watchdog timer.

Logger

Type Name
void lt_log (const uint8_t level, const char * format, ...)
void lt_log_disable ()
Disable LT logger. Enable it back using lt_log_set_port(LT_UART_DEFAULT_LOGGER).
void void lt_log_set_port (uint8_t port)
Change log output port.

POSIX compatibility API

A small subset of POSIX functions, commonly present in other Arduino cores, is provided for compatibility.

Type Name
int strcasecmp (const char * s1, const char * s2)
char * strdup (const char *)
int strncasecmp (const char * s1, const char * s2, size_t n)
char * strptime (const char * buf, const char * fmt, struct tm * tm)

C++ API

This API is available using:

  • #include <Arduino.h>

LibreTiny

Since v1.0.0, this class only consists of inline functions, which wrap the LibreTiny C API (lt_api.h). Refer to the docs of the C API for more information.

The class is accessible using the LT global object.

Type Name
const char * getBoard ()
Get board code.
const char * getChipCoreType ()
Get CPU core type name as string.
uint8_t getChipCores ()
Get CPU core count.
ChipFamily getChipFamily ()
Get CPU family ID (as lt_cpu_family_t enum member).
const char * getChipFamilyName ()
Get CPU family name as string.
uint32_t getChipId ()
Get CPU ID based on the last three octets of MAC address. Note: the number is 24-bit (with the MSB being zero). The 3rd-to-last octet is least-significant, the last octet is most-significant.
const char * getChipModel ()
Get CPU model name as string (uppercase).
ChipType getChipType ()
Get CPU model ID (as lt_cpu_model_t enum member).
uint32_t getCpuFreq ()
Get CPU frequency in Hz.
uint32_t getCpuFreqMHz ()
Get CPU frequency in MHz.
uint32_t getCycleCount ()
Get CPU cycle count.
const char * getDeviceName ()
Get device friendly name in format "LT-<chip model>-<MAC ID>". Can be used as hostname.
FlashId getFlashChipId ()
Read flash chip ID and return a lt_flash_id_t struct.
uint32_t getFlashChipSize ()
Get flash chip total size.
uint32_t getFreeHeap ()
Get free heap size.
uint32_t getHeapSize ()
Get total heap size.
uint32_t getMaxAllocHeap ()
Get largest block of heap that can be allocated at once.
uint32_t getMaxFreeBlockSize ()
Get largest block of heap that can be allocated at once.
uint32_t getMinFreeHeap ()
Get lowest level of free heap memory.
uint32_t getRamSize ()
Get total RAM size.
ResetReason getResetReason ()
Get the reason of last chip reboot.
const char * getResetReasonName (ResetReason reason=lt_get_reboot_reason())
Get a textual representation of a reboot reason.
const char * getVersion ()
Reset reason enumeration.
void gpioRecover ()
Reconfigure GPIO pins used for debugging (SWD/JTAG), so that they can be used as normal I/O.
void restart ()
Reboot the CPU.
void restartDownloadMode ()
Reboot the CPU and stay in download mode (if possible).

LibreTinyOTA

This class only consists of inline functions, which wrap the LibreTiny C API (lt_api.h). Refer to the docs of the C API for more information.

The class is accessible using the OTA global object.

Type Name
bool canRollback ()
Check if OTA rollback is possible (switching the stored index to another partition).
uint8_t getCurrentIndex ()
Get the currently running firmware's OTA index.
uint8_t getStoredIndex ()
Read the currently active OTA index, i.e. the one that will boot upon restart.
lt_ota_type_t getType ()
Get OTA type of the device's chip.
uf2_ota_scheme_t getUF2Scheme ()
Check which UF2 OTA scheme should be used for applying firmware updates.
bool isValid (uint8_t index)
Check if the specified OTA image is valid.
bool switchImage (bool revert=false)
Try to switch OTA index to the other image. For single-OTA chips, only check if the upgrade image is valid.

LibreTinyWDT

This class only consists of inline functions, which wrap the LibreTiny C API (lt_api.h). Refer to the docs of the C API for more information.

The class is accessible using the WDT global object.

Type Name
void disable ()
Disable the hardware watchdog.
bool enable (uint32_t timeout=10000)
Enable the hardware watchdog.
void feed ()
Feed/reset the hardware watchdog timer.

ESP (compatibility class)

This class only consists of inline functions, which wrap the LibreTiny C API (lt_api.h). Refer to the docs of the C API for more information.

The class is accessible using the ESP global object.

Type Name
bool flashEraseSector (uint32_t sector)
Erase a single block of flash (usually 4 KiB).
bool flashRead (uint32_t address, uint8_t * data, size_t size)
Read data from the flash.
bool flashWrite (uint32_t address, const uint8_t * data, size_t size)
Write data to the flash.
uint8_t getBootMode ()
uint8_t getBootVersion ()
uint32_t getChipId ()
Get CPU ID based on the last three octets of MAC address. Note: the number is 24-bit (with the MSB being zero). The 3rd-to-last octet is least-significant, the last octet is most-significant.
String getCoreVersion ()
uint8_t getCpuFreqMHz ()
Get CPU frequency in MHz.
uint32_t getCycleCount ()
Get CPU cycle count.
uint32_t getFlashChipId ()
Flash chip ID structure.
uint32_t getFlashChipMode ()
uint32_t getFlashChipRealSize ()
Get flash chip total size.
uint32_t getFlashChipSize ()
Get flash chip total size.
uint32_t getFlashChipSizeByChipId ()
Get flash chip total size.
uint8_t getFlashChipVendorId ()
Flash chip ID structure.
uint32_t getFreeHeap ()
Get free heap size.
String getFullVersion ()
uint16_t getMaxFreeBlockSize ()
Get largest block of heap that can be allocated at once.
String getResetInfo ()
Get a textual representation of a reboot reason.
String getResetReason ()
Get a textual representation of a reboot reason.
const char * getSdkVersion ()
uint16_t getVcc ()
uint8_t * random (uint8_t * resultArray, const size_t outputSizeBytes)
Generate random bytes using rand().
uint32_t random ()
Generate random bytes using rand().
void rebootIntoUartDownloadMode ()
Reboot the CPU and stay in download mode (if possible).
void reset ()
Reboot the CPU.
void restart ()
Reboot the CPU.
void wdtDisable ()
Disable the hardware watchdog.
void wdtEnable (uint32_t timeout_ms=0)
Enable the hardware watchdog.
void wdtFeed ()
Feed/reset the hardware watchdog timer.

Arduino custom API

These functions extend the standard Wiring (Arduino) library, to provide additional features.

Type Name
int analogRead (pin_size_t pinNumber)
Read voltage from ADC and return a value between 0 and the current reading resolution.
uint16_t analogReadMaxVoltage (pin_size_t pinNumber)
Get max reading voltage for the specified pin (millivolts).
void analogReadResolution (int res)
Set resolution of values (in bits) returned by analogRead(). Defaults to 10 bit (0-1023).
uint16_t analogReadVoltage (pin_size_t pinNumber)
Read voltage from analog input (in millivolts).
void analogWriteFrequency (int hz)
Set PWM output frequency (in Hz). Defaults to 50 Hz (20,000 uS).
void analogWritePeriod (int us)
Set PWM output frequency (cycle period) in microseconds. Defaults to 20,000 uS (50 Hz).
void analogWriteResolution (int res)
Set resolution of values (in bits) expected by analogWrite(). Defaults to 8 bit (0-255).
void mainTask (const void * arg)
Main setup() and loop() task. Not to be called directly.
PinInfo * pinByGpio (uint32_t gpio)
Find PinInfo struct by GPIO number. Returns NULL if not found.
PinInfo * pinByIndex (uint32_t index)
Get PinInfo struct for the specified index. Returns NULL if pin index is invalid.
bool pinEnabled (PinInfo * pin, uint32_t mask)
Check if pin has all features represented by 'mask' enabled.
uint32_t pinIndex (PinInfo * pin)
Get index of PinInfo in the global pin info table.
PinInfo * pinInfo (pin_size_t pinNumber)
Get PinInfo struct for the specified number. Returns NULL if pin number is invalid.
void pinModeNone (pin_size_t pinNumber)
Deinitialize the pin, by removing all enabled modes.
void pinModeRemove (pin_size_t pinNumber, uint32_t mask)
Disable modes specified by 'mask'.
void pinRemoveMode (PinInfo * pin, uint32_t mask)
bool pinSupported (PinInfo * pin, uint32_t mask)
Check if pin supports all features represented by 'mask'.
void runPeriodicTasks ()
Run periodic tasks, like printing free heap or checking millis() overflow.
bool startMainTask (void)
Run mainTask & start OS kernel (family-defined). Return false if an error occured; else do not return and and keep the OS kernel running.

Arduino compatibility API

These functions and macros provide compatibility between LT and other Arduino cores, such as ESP32.

Type Name
String ipToString (const IPAddress & ip)
Type Name
define CONFIG_LWIP_MAX_ACTIVE_TCP 16
define ESP_FAIL -1
define ESP_OK 0
define FPSTR (pstr_pointer) (reinterpret_cast<const __FlashStringHelper *>(pstr_pointer))
define OUTPUT_OPEN_DRAIN OUTPUT_OPENDRAIN
define PGM_VOID_P const void *
define attachInterruptArg attachInterruptParam
define digitalPinToInterrupt (pin) (pin)
define esp_err_t int
define round (x) ((x) >= 0 ? (long)((x) + 0.5) : (long)((x)-0.5))
define voidFuncPtrArg voidFuncPtrParam
define vsnprintf_P vsnprintf
define xTaskCreatePinnedToCore xTaskCreateUniversal
define xTaskCreateUniversal (pxTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask, xCoreID) xTaskCreate(pxTaskCode, pcName, usStackDepth, pvParameters, uxPriority, pxCreatedTask)

Chip & family types

enum lt_cpu_family_t

enum lt_cpu_family_t {
    F_RTL8710A = 0x9FFFD543,
    F_RTL8710B = 0x22E0D6FC,
    F_RTL8720C = 0xE08F7564,
    F_RTL8720D = 0x3379CFE2,
    F_BK7231Q = 0xAFE81D49,
    F_BK7231T = 0x675A40B0,
    F_BK7231N = 0x7B3EF230,
    F_BK7251 = 0x6A82CC42,
    F_BL60X = 0xDE1270B7
};

enum lt_cpu_model_t

enum lt_cpu_model_t {
    RTL8710BL = CPU_MODEL(F_RTL8710B, 0xE0),
    RTL8710BN = CPU_MODEL(F_RTL8710B, 0xFF),
    RTL8710BU = CPU_MODEL(F_RTL8710B, 0xFE),
    RTL8710BX = CPU_MODEL(F_RTL8710B, 0xF6),
    RTL8710L0 = CPU_MODEL(F_RTL8710B, 0xFB),
    RTL8711BN = CPU_MODEL(F_RTL8710B, 0xFD),
    RTL8711BU = CPU_MODEL(F_RTL8710B, 0xFC),
    MX1290 = RTL8710BN,
    MX1290V2 = RTL8710BX,
    W302 = RTL8710BN,
    RTL8720CM = CPU_MODEL(F_RTL8720C, 0xEC),
    RTL8720CF = CPU_MODEL(F_RTL8720C, 0xED),
    RTL8720CX = RTL8720CM,
    BK7231Q = CPU_MODEL(F_BK7231Q, 0x31),
    BK7231T = CPU_MODEL(F_BK7231T, 0x1A),
    BK7231N = CPU_MODEL(F_BK7231N, 0x1C),
    BK7252 = CPU_MODEL(F_BK7251, 0x00),
    BL2028N = BK7231N,
    BK7231S = BK7231T,
    BK7231U = BK7231T
};