# tencent/tencentos-tiny architecture

> Architecture diagram of the GitHub repository tencent/tencentos-tiny, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tencent/tencentos-tiny
- Repository: https://github.com/tencent/tencentos-tiny

## Overview

##### Project Type and Purpose
- This is a real-time operating system (RTOS) for IoT devices (TobudOS, formerly TencentOS Tiny).
- It provides a small-footprint, modular RTOS kernel plus a set of IoT protocol stacks and peripheral drivers that can be configured, trimmed, and ported to various MCUs (e.g., STM32, LoRa, NB-IoT modules).

##### High-Level Architectural Components
a. Hardware Platform Layer
- Target microcontroller or SoC
- On-chip peripherals (timers, UART, SPI, I²C, ADC, etc.)
b. Hardware Abstraction Layer (HAL) / Board Support Package (BSP)
- MCU startup code (reset, vector table)
- Low-level drivers exposing uniform APIs
- MCU-specific configurations (clock, NVIC)
c. RTOS Kernel Core
- Scheduler (tick or tickless)
- Thread/task management
- Inter-task communication (queues, semaphores, mutexes, event flags)
- Memory management (heap, stack, pool)
- Timers and tick management
- Interrupt dispatcher
d. Kernel Components (configurable modules)
- Dynamic memory allocator (optional)
- Power management hooks
- Hook and trace interfaces
e. Middleware / Protocol Stack Layer
- Networking stacks: CoAP, MQTT, TLS/DTLS, LoRaWAN, NB-IoT
- File systems (if any)
- Device management protocols
f. Application Layer
- User-defined tasks and services
- Sample demos (sensor reading, connectivity examples)
g. Build & Configuration
- Kconfig or menuconfig-style configuration files
- Board / architecture directories
- Makefiles or CMake scripts
h. External Services
- Cloud IoT platforms (MQTT broker, CoAP server)
- OTA update servers

##### Relationships and Data Flow
- Application tasks invoke RTOS APIs (taskCreate, msgQueueSend, etc.).
- RTOS Kernel dispatches tasks based on priority and timing.
- Tasks interact with HAL drivers for peripherals (e.g., SPI_Read).
- Networking middleware uses sockets or driver APIs to send/receive data via the hardware NIC or modem.
- Kernel timers trigger callbacks in middleware or application for scheduled events.
- Interrupts enter the kernel’s ISR entry points, possibly signaling tasks or semaphores.

##### Architectural Patterns and Design Principles
- Layered architecture: clear separation of hardware, kernel core, middleware, and application.
- Modular and configurable components: compile-time inclusion/exclusion of kernel modules and protocol stacks.
- Hardware abstraction for portability: BSP and HAL isolate MCU specifics.
- Event-driven and preemptive scheduling model for real-time responsiveness.
- Hook interfaces for custom tracing, power management, or debug.

##### Essential Elements to Capture
- All RTOS subsystems (scheduler, IPC, memory).
- HAL modules mapped to hardware peripherals.
- Middleware protocols as optional modules.
- Build/configuration layer showing how features are enabled or disabled.
- External cloud or service endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Platform Layer"
        HW["Microcontroller/SoC"]:::hardware
        Peripherals["On-chip Peripherals\n(UART, SPI, I2C, ADC, Timers)"]:::hardware
    end

    subgraph "HAL & BSP Layer"
        HAL["MCU Startup & Vector Table"]:::hal
        Drivers["Low-level Drivers\n(Uniform APIs)"]:::hal
        Configs["MCU Configurations\n(Clock, NVIC)"]:::hal
    end

    subgraph "RTOS Kernel Core"
        Scheduler["Scheduler\n(tick/tickless)"]:::kernel
        TaskMgmt["Task/Thread Management"]:::kernel
        IPC["Inter-task Communication\n(Queues, Semaphores, Mutexes,\nEvent Flags)"]:::kernel
        MemMgmt["Memory Management\n(heap, stack, pool)"]:::kernel
        Timers["Timers & Tick Management"]:::kernel
        ISR["Interrupt Dispatcher"]:::kernel
    end

    subgraph "Kernel Configurable Modules"
        DynMem["Dynamic Memory Allocator"]:::kernelmod
        PowerHook["Power Management Hooks"]:::kernelmod
        HookTrace["Hook & Trace Interfaces"]:::kernelmod
    end

    subgraph "Middleware / Protocol Stacks"
        CoAP["CoAP Stack"]:::middleware
        MQTT["MQTT Stack"]:::middleware
        TLS["TLS/DTLS"]:::middleware
        LoRaWAN["LoRaWAN Stack"]:::middleware
        NBIoT["NB-IoT Stack"]:::middleware
        FS["File Systems"]:::middleware
        DMgmt["Device Management Protocols"]:::middleware
    end

    subgraph "Application Layer"
        UserTasks["User-defined Tasks & Services"]:::app
        Demos["Sample Demos\n(Sensor, Connectivity)"]:::app
    end

    subgraph "Build & Configuration"
        Kconfig["Kconfig/Menuconfig Files"]:::build
        Boards["Board/Arch Directories"]:::build
        BuildScripts["Makefiles/CMake Scripts"]:::build
        README["Project Documentation\n(README.md)"]:::build
    end

    subgraph "External Services"
        Cloud["Cloud IoT Platforms\n(MQTT Broker, CoAP Server)"]:::external
        OTA["OTA Update Server"]:::external
    end

    %% Relationships
    UserTasks -->|"taskCreate(), msgQueueSend()"| Scheduler
    Demos -->|"taskCreate()"| Scheduler
    Scheduler -->|"dispatch()"| UserTasks
    Scheduler -->|"dispatch()"| Demos

    UserTasks -->|"HAL_UART_Transmit()"| Drivers
    Demos -->|"HAL_SPI_Transmit()"| Drivers
    Drivers -->|"direct access"| Peripherals
    Peripherals -->|"hardware interrupt"| ISR
    ISR -->|"ISR entry"| ISR
    ISR -->|"signal()/xSemaphoreGive()"| IPC

    Timers -->|"timer callbacks"| UserTasks

    CoAP -->|"socket API"| Drivers
    MQTT -->|"socket API"| Drivers
    TLS -->|"secure sockets"| Drivers
    LoRaWAN -->|"driver API"| Drivers
    NBIoT -->|"driver API"| Drivers
    FS -->|"block I/O"| Drivers
    DMgmt -->|"protocol API"| Drivers

    MQTT -->|"publish/subscribe"| Cloud
    CoAP -->|"CoAP messages"| Cloud
    OTA -->|"HTTP/CoAP download"| Cloud
    Cloud -->|"network data"| Drivers
    OTA -->|"update retrieval"| Drivers

    HAL -->|"startup hooks"| Scheduler
    HAL -->|"NVIC config"| ISR
    Configs --> HAL
    HW --> HAL
    Drivers --> Peripherals

    %% Click Events
    click README "https://github.com/tencent/tencentos-tiny/blob/main/README.md"

    %% Styles
    classDef hardware fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef hal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef kernel fill:#90EE90,stroke:#333,stroke-width:1px
    classDef kernelmod fill:#98FB98,stroke:#333,stroke-width:1px
    classDef middleware fill:#FFA500,stroke:#333,stroke-width:1px
    classDef app fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef build fill:#F5F5DC,stroke:#333,stroke-width:1px
    classDef external fill:#F08080,stroke:#333,stroke-width:1px
```
