System Requirements Document (SRD) for terra-os

1. Introduction

The terra-os project is a custom operating system designed specifically for the ESP32-C5 microcontroller. It features a web-based desktop environment (DE), a serial interface, and a modular plugin system to ensure extensibility. The system is targeted at hobbyists who want a lightweight, powerful, and customizable platform for their IoT and networking projects. Key features include a deauthentication package, an evil portal function, and a focus on being flashable and easy to use.

This document outlines the requirements and specifications for the development of terra-os, ensuring it meets the needs of its intended audience while remaining optimized for the ESP32-C5 hardware.

2. System Overview

terra-os is a lightweight, extensible operating system designed to run efficiently on the ESP32-C5 microcontroller. It provides a web-based desktop environment for easy interaction, a serial interface for direct device communication, and a plugin system to allow users to expand its functionality. The system is designed to be flashable and user-friendly, with a focus on modularity and customization.

Key features include:

• A sleek and intuitive web-based desktop environment (DE).
• A serial interface for direct communication and debugging.
• A plugin system for extensibility, allowing users to add new features.
• A deauthentication package and evil portal function for advanced networking experiments.
• Optimized performance for the ESP32-C5 hardware.

3. Functional Requirements

• As a Hobbyist, I should be able to flash the OS easily to my ESP32-C5.
• As a User, I should be able to access a web-based desktop environment (DE) to interact with the system.
• As a User, I should be able to use a serial interface for direct communication with the device.
• As a User, I should be able to install and manage plugins to extend the functionality of the OS.
• As a User, I should be able to use a deauthentication package for network experiments.
• As a User, I should be able to activate an evil portal function for advanced networking use cases.
• As a Developer, I should be able to create plugins using a defined API or framework.

4. User Personas

Hobbyist

• Description: A tech-savvy individual who enjoys experimenting with IoT devices and microcontrollers.
• Goals: To have a customizable and extensible OS for their ESP32-C5 projects.
• Pain Points: Complexity in flashing firmware, lack of extensibility, and limited user interfaces.

Developer

• Description: A programmer or engineer who wants to create plugins or extend the functionality of terra-os.
• Goals: To have a clear API and tools for developing and integrating plugins.
• Pain Points: Poor documentation, lack of modularity, and limited support for development.

5. Visuals Colors and Theme

The visual design of the web-based desktop environment (DE) will follow a modern and minimalistic aesthetic, with the following color scheme:

• Primary Color: Deep Blue (#003366) for headers and navigation.
• Secondary Color: Light Cyan (#00BFFF) for highlights and interactive elements.
• Background Color: Soft Gray (#F5F5F5) for the main background.
• Accent Color: Vibrant Orange (#FF6600) for warnings and critical actions.
• Font: Sans-serif font family (e.g., Roboto or Open Sans) for readability.

The theme will emphasize clarity, simplicity, and ease of use, ensuring that hobbyists and developers can navigate the system effortlessly.

6. Signature Design Concept

The terra-os homepage will feature a dynamic, interactive circuit board design.

• Visuals: The landing page will resemble a glowing, animated circuit board with traces that light up as the user hovers over different sections. Each section of the board represents a feature or module of the OS (e.g., "Web DE," "Serial Interface," "Plugins").
• Animations: Smooth transitions will occur as users interact with the board. For example, clicking on a section will "zoom in" to reveal more details, while the rest of the board fades into the background.
• Micro-interactions: Hover effects will include subtle glowing animations, and clicking on a feature will trigger a ripple effect across the board.
• Color Shifts: The circuit board will shift colors based on the time of day (e.g., cool blues at night, warm oranges during the day).
• User Interaction: Users can drag and pan across the board to explore features, creating an engaging and memorable first impression.

This design will make the system feel futuristic and tech-forward, perfectly aligning with the interests of hobbyists and developers.

7. Non-Functional Requirements

• The system must be lightweight and optimized for the ESP32-C5 hardware.
• The web-based desktop environment must load within 2 seconds on a standard ESP32-C5 setup.
• The plugin system must support at least 10 active plugins without performance degradation.
• The firmware must be flashable using standard ESP32-C5 tools (e.g., esptool).
• The system must be secure, with authentication mechanisms for accessing sensitive features like the deauthentication package and evil portal.

8. Tech Stack

Frontend

• React for the web-based desktop environment.

Backend

• Python with FastAPI for handling plugin management and system APIs.

Database

• MySQL for storing plugin metadata and system configurations.

AI Tools

• GPT 5.2 for user-friendly responses in the web interface.

Local Orchestration

• Docker for development and testing environments.

Server-Side Orchestration

• Kubernetes for managing scalable deployments (if needed for future expansions).

9. Assumptions and Constraints

• The system will be used primarily by hobbyists and developers with basic technical knowledge.
• The ESP32-C5 hardware will have sufficient resources to run the OS and its features.
• Users will have access to standard tools for flashing firmware to the ESP32-C5.
• The plugin system will initially support Python-based plugins, with potential for additional language support in the future.

10. Glossary

• ESP32-C5: A microcontroller with Wi-Fi and Bluetooth capabilities, designed for IoT applications.
• Web DE: A web-based desktop environment for interacting with the OS.
• Serial Interface: A communication interface for direct interaction with the device.
• Deauthentication Package: A tool for performing deauthentication attacks, typically used for network testing and research.
• Evil Portal: A captive portal used for advanced networking experiments.
• Plugin System: A modular framework that allows users to add new features to the OS.

End of Document