ThingBoot Device Firmware SDK

An enterprise-grade free SDK for developers — ready to use out of the box, zero learning curve, available in both ESP Arduino and ESP-IDF editions

SDK Overview

The ThingBoot Device Firmware SDK is an enterprise-grade, free firmware development framework for developers — ready to use out of the box with zero learning curve. The SDK deeply encapsulates core capabilities such as device connection, state management, command execution, and OTA updates. Developers can complete high-quality product firmware development quickly in their familiar development environment — without implementing communication protocols from scratch or learning a new development paradigm — and connect to the ThingBoot Open Platform and privatized platform. Both the ESP Arduino and ESP-IDF editions of the SDK are open to developers free of charge. Every developer account also enjoys a free device access quota of 100 devices per year, enough to cover nearly a full year of prototypes for a development team; the platform access fee is charged to factories only when a product enters mass production.

Core Features

Device Connection

Connect to the ThingBoot cloud platform or a privatized platform with one click, with stable persistent connections and automatic reconnection.

State Reporting

Standardized interfaces for reporting device state, events, and data, giving the cloud real-time visibility into device operation.

Command Execution

Receive and parse control commands sent from the cloud, with support for both synchronous and asynchronous execution modes.

OTA Updates

Built-in secure and reliable firmware OTA update capability, supporting both differential and full-image update strategies.

SDK Module Overview

Module Access Method Description Notes
Core device.* System initialization and main loop, product information setup, system info / version / ID queries, working modes, time zone and timestamps, reboot, delay and tick, system callbacks (state change / progress / debug log) —
Config device.Config Registration, reading, saving, resetting, and clearing of device configuration items; configuration change callbacks; linked with the "Config" card in the console —
Order device.Order Receive commands issued by the platform (via callback) and reply to them —
Event device.Event Device attribute setting with debounce, attribute change callbacks, and event reporting —
Message device.Message Publish messages to the platform or other devices (topics such as order / event / state / config; supports specifying mid and target device number) —
State device.State State data reporting and periodic reporting (onFetch callback when the platform polls for data) —
Timer device.Timer Software timers: register callbacks by interval in milliseconds and a run count (or infinite loop) —
Peripheral device.Peripheral Peripheral pre-init / init callbacks; device LED and system LED (on / off / toggle / blink); device button and system button (debounce, long-press menu) —
Network device.Network WiFi (multiple configuration groups, add/remove/update/query, connect/disconnect), wired Ethernet (W5500), GSM/4G (ML307), network information queries Ethernet requires TBD_ETHER; GSM requires TBD_GSM; chip selection interfaces are ESP-IDF edition only
BLE (enabled at compile time) BLE provisioning (wifi_provisioning, TBC- hotspot, PoP verification) and BLE control (NimBLE GATT: command write / event notify / config read-write) ESP-IDF edition only; requires TBD_BLE
Bridge device.Bridge UART / SPI byte pipe: raw data send/receive, formatted sending, receive/error callbacks, statistics Can be trimmed with the NO_BRIDGE macro
Utils / JSON Global functions JSONVar / JSON (parse / stringify / typeof), string utilities (concatenation / padding / search / split / hex conversion), md5, random numbers, tb_millis() / mill_elapsed() —

SDK Advantages

Ready to Use, Zero Learning Curve

Builds on the Arduino / ESP-IDF development workflows developers already know — no new framework to learn. It shields low-level protocols and communication details so you can focus on business logic and significantly shorten the R&D cycle.

Proven Code Quality

A firmware framework validated in real mass-production projects, offering greater assurance of stability and compatibility.

Low Migration Cost

A unified interface design keeps the Arduino and ESP-IDF edition APIs consistent, and keeps future migration costs manageable when moving to platforms such as STM32 or Linux.

System Boot Sequence

Stage System Behavior Interface Mechanisms Available at This Point Timing Requirements
Before setup Developer code stage; the system has not yet been initialized ✦ All registration-style interfaces are called here: setProduct() to set product information, onDebug() debug callback, onSystemProgress() progress callback, onSystemStateChange() state callback, onInitPre() / onInit() peripheral callbacks, onOrder() / onConfig() / onFetch() / onAttributeChange() business callbacks, plus network parameter presets (WiFi configuration, setGSMChip() / setEthernetChip() / setGSMSerialPort() / setEthernetPin()) Must be called before device.setup()
0% → 10% Peripheral pre-initialization (scans the system button state) ✦ Triggers the onInitPre() callback: the earliest developer code execution point, where GPIO peripherals can be registered (setDeviceLed() / setDeviceBtn()) Triggered internally by the SDK
10% → 20% System information initialization (NVS/ROM reads, factory configuration imported from SPIFFS) ✦ onSystemProgress() continuously reports progress and stage descriptions; onDebug() outputs internal logs Triggered internally by the SDK
20% → 30% WiFi driver initialization; scans for engineering hotspots (safe / factory / test / debug / config) — (internal stage) —
30% → 40% Peripheral initialization (lights up LEDs per registration info, takes over the system LED/button) ✦ Triggers the onInit() callback: the developer initialization point after peripheral registration takes effect Triggered internally by the SDK
40% → 60% Network connection (tries WiFi / Ethernet / GSM by priority, engineering hotspots first) — (internal stage; the result is reflected through the system state) —
60% → 90% Privatized gateway / privatized Broker initialization (skipped when not enabled) — (internal stage) —
90% → 100% NTP time synchronization initialization — (internal stage) —
100% Complete System startup complete, then automatically performs platform registration (reg), connects to the MQTT Broker, and subscribes to downstream topics ✦ onSystemStateChange() notifies system state transitions (startup / connected / online / offline, etc.) Triggered internally by the SDK
loop runtime device.loop() main loop: MQTT message dispatch, timer scheduling, peripheral polling (10ms), periodic state reporting, OTA, and more ✦ All business interfaces are available: receive commands via onOrder() → reply with replyMessage() / publishMessage(); report with reportEvent() / reportState(); onConfig() configuration changes; onFetch() platform data polling; onAttributeChange() attribute changes; addTimer() scheduled tasks; button callbacks (registered via setDeviceBtn()); Bridge.handle() bridge send/receive (in UART mode it must be called periodically in the loop) Call device.loop() on every iteration

Platform Support Roadmap

ESP Arduino

Fully supported and ready to download, covering mainstream modules such as ESP8266 / ESP32.

More Platforms

Platforms such as STM32 and Linux are in planning — stay tuned.

Get the ThingBoot Device Firmware SDK

Both SDK editions are open and free — visit the GitHub repositories for source code, examples, and documentation

ESP Arduino SDK ESP-IDF SDK (Beta)