ThistleOS — Documentation

Try it now

Launch the browser simulator — ThistleOS running in your browser via WebAssembly. No install needed.

Status

ThistleOS Rust migration complete. 100% Rust kernel (57 modules, 35,000+ LOC, 1,231 tests), 15 Rust hardware drivers, 10 supported boards, multi-arch ESP32 support, and catalog-led provisioning in the Recovery OS.

What is ThistleOS?

ThistleOS is a micro operating system for the ESP32 chip family, initially targeting the LilyGo T-Deck Pro. It brings concepts from mainstream operating systems — loadable apps, a hardware abstraction layer, app permissions, and an app store — down to a device with 512 KB of internal SRAM and 8 MB of PSRAM.

Key design decisions:

Drivers are fully swappable. Swapping a display driver means changing one line in a board definition, not touching the kernel. 15 drivers written in Rust.
Apps are ELF files on an SD card. The kernel's ELF loader resolves symbols against a syscall table at runtime. No recompilation of the OS needed to install an app.
BSD 3-Clause throughout. No GPL components in the ThistleOS core; swap to any commercial use case without license headaches.
Recovery OS provisions from board catalogs. A separate, minimal Rust firmware in ota_0 starts a WiFi captive portal, downloads the selected board profile, verifies catalog hashes, and installs matching drivers and firmware.
Multi-arch. One kernel codebase targets Xtensa (ESP32, S2, S3) and RISC-V (C3, C6). Board configs in JSON — no recompilation for new boards.

Quick Start

Prerequisites: ESP-IDF v5.3+ installed and on your PATH.

# Clone the repo
git clone https://github.com/wan0net/thistle-os
cd esp32-os

# Build for the default board (T-Deck Pro)
idf.py build

# Flash and open serial monitor
idf.py -p /dev/ttyACM0 flash monitor

The SD card layout is documented in sdcard_layout/. Copy the directory contents to a FAT32 SD card and insert it before first boot.

Documentation sections

⚡

Architecture

HAL vtable design, kernel modules, memory layout, boot sequence, driver loading.

🖥

Building Apps

App SDK, syscalls, LVGL UI patterns, packaging as .app.elf, signing, publishing.

🔌

Building Drivers

HAL vtable interfaces, step-by-step display driver, testing, signing.

🏨

App Store

Catalog JSON schema, hosting your own catalog, download and verification flow.

💻

Devices

All 10 supported boards, chip support table, hardware detection flow, and how to add a new board.

🔒

Security

Chain of trust, signing scheme, permissions, OTA verification, key management.

🔄

Recovery OS

Rust-based recovery firmware, captive portal, board catalog provisioning, building from source.

📥

Release Flashing

Release assets, checksums, firmware slot offsets, and recovery update commands.

Repository layout

Path	Purpose
`components/thistle_hal/`	HAL interface headers — pure vtable structs, no implementation
`components/drv_*/`	One component per hardware driver (display, radio, GPS, etc.)
`components/board_*/`	Board definitions — wire drivers to HAL, define pin numbers
`components/kernel/`	App manager, driver manager, ELF loader, IPC, permissions, OTA
`components/ui/`	LVGL window manager, status bar, toast notifications, themes
`components/apps_builtin/`	Built-in apps: Launcher, Messenger, Navigator, Notes, Reader, Settings
`components/shim/`	Compatibility shims for MeshCore and Arduino-style firmware
`app_sdk/`	SDK for third-party app developers — headers + CMake helpers
`recovery/`	Recovery OS — Rust + esp-rs, lives in `ota_0`
`sdcard_layout/`	Template for the SD card — apps/, drivers/, themes/, config/

Supported Hardware

ThistleOS runs on 10 boards across the ESP32 family. The primary board is the LilyGo T-Deck Pro (ESP32-S3, 3.1" e-paper, QWERTY keyboard, LoRa, GPS, IMU, RTC). Other supported boards include the T-Deck (LCD), T-Display-S3, T3-S3 (LoRa), CYD (ESP32), and ESP32-C3 SuperMini.

See Devices for the full hardware breakdown, driver table, and how to add your own board.

License

ThistleOS is released under the BSD 3-Clause License. All source files in components/, app_sdk/, and recovery/ carry the SPDX identifier BSD-3-Clause. Third-party managed components (LVGL, RadioLib, esp-modem) retain their own licenses.