terra-os
Fifhdvdy LastnameA super nice OS for my ESP32-C5 supporting a web DE/interface and serial interface, with deuathentication and evil portal functions, and a ton of other nice things.
Comments (0)
Sign in to leave a comment
Build for terra-os
A Python-first SDK built on FastAPI. Define lifecycle hooks, register event listeners, and expose REST endpoints — all from a single class. Ship your plugin, let terra-os handle the rest.
Up and running in 3 steps
The Building Blocks of terra-os Plugins
Master these four foundational concepts to build reliable, secure, and well-integrated plugins for the terra-os ecosystem.
Plugin Manifest
Every terra-os plugin declares its identity, dependencies, and capabilities in a structured manifest.json file. The manifest defines the plugin name, version, required permissions, and entry point — allowing the OS to validate and load plugins safely at runtime.
Learn more→Lifecycle Hooks
Plugins interact with the terra-os runtime through a set of well-defined lifecycle hooks: on_install, on_init, on_start, on_stop, and on_uninstall. Each hook gives your plugin a precise moment to allocate resources, register handlers, or clean up state gracefully.
Learn more→Event Bus
The terra-os Event Bus provides a lightweight publish-subscribe messaging layer between plugins and the core OS. Plugins can emit custom events, subscribe to system events (wifi.connected, serial.data, plugin.loaded), and communicate without tight coupling.
Learn more→Permissions Model
terra-os enforces a capability-based permissions model to keep the device secure. Plugins must declare required permissions (e.g., network.access, serial.read, wifi.scan) in their manifest, and users approve them at install time — mirroring familiar mobile OS security patterns.
Learn more→API Reference
Complete reference for the terra-sdk Python API. Click any row to expand full documentation.
| Name | Signature | Description | Since | |
|---|---|---|---|---|
| register_plugin | register_plugin(manifest: PluginManifest) -> bool | Registers a plugin with the terra-os runtime. Returns True on success. | v1.0.0 | |
| emit_event | emit_event(event: str, payload: dict) -> None | Publishes an event to the terra-os event bus. All subscribed handlers receive the payload. | v1.0.0 | |
| get_config | get_config(key: str, default: Any = None) -> Any | Retrieves a plugin configuration value from persistent NVS storage. | v1.0.0 | |
| set_config | set_config(key: str, value: Any) -> None | Persists a plugin configuration value to NVS storage across reboots. | v1.0.0 | |
| log | log(level: str, message: str) -> None | Writes a structured log entry to the terra-os system log and serial output. | v1.0.0 | |
| expose_endpoint | expose_endpoint(path: str, handler: Callable, method: str = "GET") -> None | Registers a FastAPI route on the terra-os web server under the plugin's namespace. | v1.1.0 |
Plugin Lifecycle Diagram
Every terra-os plugin transitions through six phases. Hover any node to inspect the phase description and its corresponding lifecycle hook.
Plugin SDK
Code Examples
Practical, copy-ready Python examples covering the core terra-os plugin patterns. Click a tab to explore each pattern with annotated callouts.
Annotations
Start building with the terra-os SDK today
The terra-sdk gives you everything you need to build, test, and deploy plugins for the ESP32-C5. Includes FastAPI scaffolding, lifecycle hooks, event bus access, and full API documentation.
You're not building alone
terra-os is built by hobbyists, for hobbyists. Ask questions, share your plugins, and help shape the platform.
GitHub Discussions
Ask questions, share ideas, and get help from the terra-os community and maintainers. Browse open threads or start a new discussion about plugin development, hardware quirks, or OS internals.
Join the discussionDiscord Community
1.2k membersHang out in real-time with other terra-os hobbyists and developers. Get instant help in #plugin-dev, share builds in #showcase, and stay updated with #announcements.
Join Discord serverFile a Bug
Found an issue with the Plugin SDK, lifecycle hooks, or the terra-os runtime? Open a GitHub Issue with reproduction steps, firmware version, and your plugin manifest so maintainers can triage fast.
Open an issueCheck the Wiki and Changelog before filing — your question may already be answered.
No comments yet. Be the first!