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- |
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)