# kemgong/cola_os architecture

> Architecture diagram of the GitHub repository kemgong/cola_os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kemgong/cola_os
- Repository: https://github.com/kemgong/cola_os

## Overview

This repository is a bare-metal embedded C framework for MCU applications, centered on a lightweight polling-based OS rather than a full RTOS.

At a high level, the code is split into four architectural layers:

1. Application layer
2. Small task scheduler / OS layer
3. Reusable modules
4. Board support packages and vendor-specific low-level drivers

The repo is designed to be portable across multiple MCU families, so the BSP layer contains several parallel hardware ports rather than a single target.

Main subsystems

- app/
  - This is the application entry and product logic area.
  - app/main.c is the boot/startup entry for the application side.
  - app/user/ contains feature-level application modules:
    - app.c / app.h
    - app_sensor.c / app_sensor.h
    - app_uart.c / app_uart.h
    - app_water_detection.c / app_water_detection.h
  - This suggests the application is organized around sensor handling, UART communication, and a water-detection use case.

- os/
  - This is the core of the project’s “cola_os” concept.
  - Files:
    - cola_os.c / cola_os.h
    - cola_init.c / cola_init.h
    - cola_device.c / cola_device.h
  - The README describes this as a “300-line” task manager for simple MCU systems.
  - Architecturally, this is not a preemptive RTOS. It is a cooperative/polling scheduler that manages multiple tasks in a simple loop, which makes sense for low-complexity embedded products where RT constraints are moderate.

- modules/
  - These are reusable, board-agnostic functional modules.
  - modules/aht/:
    - aht20.c / aht20.h
    - Likely sensor driver logic for AHT20 environmental sensor.
  - modules/sht/:
    - sht30.c / sht30.h
    - Likely sensor driver logic for SHT30 sensor.
  - modules/fifo/:
    - cola_fifo.c / cola_fifo.h
    - Generic circular buffer / FIFO support.
  - modules/utils/:
    - utils.c / utils.h
    - Shared helper functions used across the application and drivers.
  - These modules sit between application logic and BSP access, especially where sensor data or buffered I/O is needed.

- bsp/
  - This is the hardware abstraction and vendor integration layer.
  - It contains multiple target families:
    - STM32F0xx
    - STM32L0xx
    - GD32E230xx
    - SWM181xx
  - Each family includes:
    - CMSIS/device startup/system files
    - vendor peripheral libraries or HAL/StdPeriph drivers
    - board-specific wrapper drivers
    - IDE project files and example projects

Important BSP boundaries

Each MCU family has its own “platform implementation,” but the architecture is similar:

- CMSIS + startup + system code
  - resets, vector table, clock/system bring-up, startup assembly
- vendor peripheral library
  - STM32F0xx uses STM32F0 Standard Peripheral Library
  - STM32L0xx uses STM32Cube HAL/LL style drivers
  - GD32E230xx uses GD32 standard peripheral library
  - SWM181xx uses SWM181 standard peripheral library
- custom drivers
  - wrappers for LED, UART, output, I2C, ADC, sleep, etc.

Examples of board wrapper files:
- bsp/STM32F0xx/drivers/stm32_led.c
- bsp/STM32F0xx/drivers/stm32_output.c
- bsp/STM32F0xx/drivers/stm32_usart.c
- bsp/STM32L0xx/drivers/stm32_led.c
- bsp/STM32L0xx/drivers/stm32_output.c
- bsp/STM32L0xx/drivers/stm32_sleep.c
- bsp/GD32E230xx/drivers/gd32_adc.c
- bsp/GD32E230xx/drivers/gd32_output.c
- bsp/GD32E230xx/drivers/gd32_usart.c
- bsp/SWM181xx/drivers/swm181x_i2c.c
- bsp/SWM181xx/drivers/swm181x_led.c
- bsp/SWM181xx/drivers/swm181x_usart.c

This is the main portability boundary in the repo: the application and OS are intended to stay relatively stable while the BSP layer changes per MCU family.

Data flow and control flow

Typical runtime flow is:

- MCU reset
- startup/system code initializes runtime and clocks
- bsp-specific initialization configures board peripherals
- app/main.c enters the application
- os/cola_init and os/cola_device set up the task framework and device abstractions
- os/cola_os runs the cooperative scheduler
- application modules in app/user and reusable modules in modules/ perform work
- modules call into BSP drivers for UART, GPIO, I2C, ADC, sleep, etc.
- BSP drivers delegate to vendor peripheral libraries or HAL
- hardware sensors/IO feed data back up the stack

Likely interaction patterns

- UART path:
  - app_user app_uart -> bsp UART driver -> vendor USART peripheral -> external serial console/device
- Sensor path:
  - app_sensor / app_water_detection -> modules/aht or modules/sht -> BSP I2C driver -> sensor hardware
- Output/indicator path:
  - application logic -> BSP LED/output driver -> GPIO/peripheral registers
- Buffering path:
  - data streams or messages -> modules/fifo -> application or communication handling

Project organization and tooling

- The repo includes IDE/project artifacts for multiple environments:
  - Keil MDK-ARM project files
  - STM32Cube-generated project structure for STM32L0xx
  - example folders under each BSP
- This indicates the codebase is meant to be built per target MCU family using vendor toolchains and IDE workflows, not via a single unified build system.
- The presence of many CMSIS and vendor library files in-tree means the repo vendors its platform dependencies rather than fetching them externally at build time.

Documentation boundary

- doc/ contains usage and explanatory documents.
- The README points engineers to documentation there for operating the framework.
- The architecture is therefore intentionally split between source code and descriptive usage docs.

How to think about the architecture diagram

A clear diagram for this repo should show:

- Top: application logic in app/
- Middle: lightweight OS/task manager in os/
- Shared functional modules in modules/
- Bottom: BSPs for each MCU family
- Lowest layer: vendor CMSIS/startup/peripheral libraries and hardware

The key architectural idea is portability through a thin abstraction:
- application code depends on the OS and modules,
- modules depend on board services,
- board services are implemented separately for each MCU family.

This is not a distributed system, web app, or service-oriented repo; it is a portable embedded firmware framework for simple MCU products with polling-based task management and reusable peripheral/sensor modules.

Main entry points: [`app/user/app_sensor.c`](https://github.com/kemgong/cola_os/blob/HEAD/app/user/app_sensor.c) (Sensors), [`os/cola_device.c`](https://github.com/kemgong/cola_os/blob/HEAD/os/cola_device.c) (Device API), [`app/user/app_uart.c`](https://github.com/kemgong/cola_os/blob/HEAD/app/user/app_uart.c) (UART), [`bsp/STM32F0xx/drivers/bsp.c`](https://github.com/kemgong/cola_os/blob/HEAD/bsp/STM32F0xx/drivers/bsp.c) (STM32F0)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Application"
  app_main["Main<br/>app entry<br/>[main.c]"]
  app_core["App Core<br/>feature logic<br/>[app.c]"]
  app_sensor["Sensors<br/>feature module<br/>[app_sensor.c]"]
  app_uart["UART<br/>feature module<br/>[app_uart.c]"]
  app_water["Water Detect<br/>feature module"]
end

subgraph "OS Layer"
  os_init["Init<br/>os setup<br/>[cola_init.c]"]
  os_device["Device API<br/>os abstraction<br/>[cola_device.c]"]
  os_core["Scheduler<br/>cooperative os<br/>[cola_os.c]"]
end

subgraph "Reusable Modules"
  mod_aht["AHT20<br/>sensor module<br/>[aht20.c]"]
  mod_sht["SHT30<br/>sensor module<br/>[sht30.c]"]
  mod_fifo["FIFO<br/>buffer module<br/>[cola_fifo.c]"]
  mod_utils["Utils<br/>shared helpers<br/>[utils.c]"]
end

subgraph "Board Support"
  bsp_f0["STM32F0<br/>bsp family<br/>[bsp.c]"]
  bsp_f0_uart["F0 UART<br/>board driver<br/>[stm32_usart.c]"]
  bsp_f0_io["F0 I/O<br/>board driver<br/>[stm32_output.c]"]
  bsp_l0["STM32L0<br/>bsp family<br/>[bsp.c]"]
  bsp_l0_uart["L0 UART<br/>board driver<br/>[stm32_usart.c]"]
  bsp_l0_sleep["L0 Sleep<br/>board driver<br/>[stm32_sleep.c]"]
  bsp_gd32["GD32E230<br/>bsp family<br/>[bsp.c]"]
  bsp_gd32_uart["GD32 UART<br/>board driver<br/>[gd32_usart.c]"]
  bsp_gd32_io["GD32 I/O<br/>board driver<br/>[gd32_output.c]"]
  bsp_swm["SWM181<br/>bsp family<br/>[bsp.c]"]
  bsp_swm_i2c["SWM I2C<br/>board driver<br/>[swm181x_i2c.c]"]
  bsp_swm_uart["SWM UART<br/>board driver<br/>[swm181x_usart.c]"]
end

app_main -->|"starts"| app_core
app_core -->|"uses"| os_init
app_core -->|"runs on"| os_core
app_sensor -->|"reads"| mod_aht
app_sensor -->|"reads"| mod_sht
app_uart -->|"buffers"| mod_fifo
app_water -->|"depends on"| app_sensor
app_uart -->|"port"| bsp_f0_uart
app_uart -->|"port"| bsp_l0_uart
app_uart -->|"port"| bsp_gd32_uart
app_uart -->|"port"| bsp_swm_uart
app_sensor -->|"uses"| bsp_f0
app_sensor -->|"uses"| bsp_l0
app_sensor -->|"uses"| bsp_gd32
app_sensor -->|"uses"| bsp_swm
mod_aht -->|"calls"| bsp_swm_i2c
mod_sht -->|"calls"| bsp_swm_i2c
mod_fifo -->|"uses"| mod_utils
bsp_f0 -->|"contains"| bsp_f0_io
bsp_f0 -->|"contains"| bsp_f0_uart
bsp_l0 -->|"contains"| bsp_l0_uart
bsp_l0 -->|"contains"| bsp_l0_sleep
bsp_gd32 -->|"contains"| bsp_gd32_io
bsp_gd32 -->|"contains"| bsp_gd32_uart
bsp_swm -->|"contains"| bsp_swm_i2c
bsp_swm -->|"contains"| bsp_swm_uart
os_core -->|"abstracts"| os_device
os_init -->|"configures"| os_device
os_device -->|"backed by"| bsp_f0
os_device -->|"backed by"| bsp_l0
os_device -->|"backed by"| bsp_gd32
os_device -->|"backed by"| bsp_swm

click app_main "https://github.com/kemgong/cola_os/blob/master/app/main.c"
click app_core "https://github.com/kemgong/cola_os/blob/master/app/user/app.c"
click app_sensor "https://github.com/kemgong/cola_os/blob/master/app/user/app_sensor.c"
click app_uart "https://github.com/kemgong/cola_os/blob/master/app/user/app_uart.c"
click app_water "https://github.com/kemgong/cola_os/blob/master/app/user/app_water_detection.c"
click os_init "https://github.com/kemgong/cola_os/blob/master/os/cola_init.c"
click os_device "https://github.com/kemgong/cola_os/blob/master/os/cola_device.c"
click os_core "https://github.com/kemgong/cola_os/blob/master/os/cola_os.c"
click mod_aht "https://github.com/kemgong/cola_os/blob/master/modules/aht/aht20.c"
click mod_sht "https://github.com/kemgong/cola_os/blob/master/modules/sht/sht30.c"
click mod_fifo "https://github.com/kemgong/cola_os/blob/master/modules/fifo/cola_fifo.c"
click mod_utils "https://github.com/kemgong/cola_os/blob/master/modules/utils/utils.c"
click bsp_f0 "https://github.com/kemgong/cola_os/blob/master/bsp/STM32F0xx/drivers/bsp.c"
click bsp_f0_uart "https://github.com/kemgong/cola_os/blob/master/bsp/STM32F0xx/drivers/stm32_usart.c"
click bsp_f0_io "https://github.com/kemgong/cola_os/blob/master/bsp/STM32F0xx/drivers/stm32_output.c"
click bsp_l0 "https://github.com/kemgong/cola_os/blob/master/bsp/STM32L0xx/drivers/bsp.c"
click bsp_l0_uart "https://github.com/kemgong/cola_os/blob/master/bsp/STM32L0xx/drivers/stm32_usart.c"
click bsp_l0_sleep "https://github.com/kemgong/cola_os/blob/master/bsp/STM32L0xx/drivers/stm32_sleep.c"
click bsp_gd32 "https://github.com/kemgong/cola_os/blob/master/bsp/GD32E230xx/drivers/bsp.c"
click bsp_gd32_uart "https://github.com/kemgong/cola_os/blob/master/bsp/GD32E230xx/drivers/gd32_usart.c"
click bsp_gd32_io "https://github.com/kemgong/cola_os/blob/master/bsp/GD32E230xx/drivers/gd32_output.c"
click bsp_swm "https://github.com/kemgong/cola_os/blob/master/bsp/SWM181xx/drivers/bsp.c"
click bsp_swm_i2c "https://github.com/kemgong/cola_os/blob/master/bsp/SWM181xx/drivers/swm181x_i2c.c"
click bsp_swm_uart "https://github.com/kemgong/cola_os/blob/master/bsp/SWM181xx/drivers/swm181x_usart.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class app_main,app_core,app_sensor,app_uart,app_water toneBlue
class os_init,os_device,os_core toneAmber
class mod_aht,mod_sht,mod_fifo,mod_utils toneMint
class bsp_f0,bsp_f0_uart,bsp_f0_io,bsp_l0,bsp_l0_uart,bsp_l0_sleep,bsp_gd32,bsp_gd32_uart,bsp_gd32_io,bsp_swm,bsp_swm_i2c,bsp_swm_uart toneRose
```

## Components

### Application

Boot entry and product-specific logic.

- [Main](https://github.com/kemgong/cola_os/blob/HEAD/app/main.c): app entry · Application boot and startup entry point. · `app/main.c`
- [App Core](https://github.com/kemgong/cola_os/blob/HEAD/app/user/app.c): feature logic · Top-level application coordination. · `app/user/app.c`
- [Sensors](https://github.com/kemgong/cola_os/blob/HEAD/app/user/app_sensor.c): feature module · Application-level sensor handling. · `app/user/app_sensor.c`
- [UART](https://github.com/kemgong/cola_os/blob/HEAD/app/user/app_uart.c): feature module · Application-level serial communication. · `app/user/app_uart.c`
- [Water Detect](https://github.com/kemgong/cola_os/blob/HEAD/app/user/app_water_detection.c): feature module · Water-detection product logic. · `app/user/app_water_detection.c`

### OS Layer

Cooperative task framework and device abstraction.

- [Init](https://github.com/kemgong/cola_os/blob/HEAD/os/cola_init.c): os setup · Framework initialization for tasks and devices. · `os/cola_init.c`
- [Device API](https://github.com/kemgong/cola_os/blob/HEAD/os/cola_device.c): os abstraction · Device-facing abstraction layer for the scheduler. · `os/cola_device.c`
- [Scheduler](https://github.com/kemgong/cola_os/blob/HEAD/os/cola_os.c): cooperative os · Lightweight polling-based task manager. · `os/cola_os.c`

### Reusable Modules

Board-agnostic sensors, buffering, and helpers.

- [AHT20](https://github.com/kemgong/cola_os/blob/HEAD/modules/aht/aht20.c): sensor module · Reusable AHT20 sensor logic. · `modules/aht/aht20.c`
- [SHT30](https://github.com/kemgong/cola_os/blob/HEAD/modules/sht/sht30.c): sensor module · Reusable SHT30 sensor logic. · `modules/sht/sht30.c`
- [FIFO](https://github.com/kemgong/cola_os/blob/HEAD/modules/fifo/cola_fifo.c): buffer module · Generic circular buffering support. · `modules/fifo/cola_fifo.c`
- [Utils](https://github.com/kemgong/cola_os/blob/HEAD/modules/utils/utils.c): shared helpers · Common helper functions used across layers. · `modules/utils/utils.c`

### Board Support

MCU-family-specific hardware integration layers.

- [STM32F0](https://github.com/kemgong/cola_os/blob/HEAD/bsp/STM32F0xx/drivers/bsp.c): bsp family · Board port for STM32F0 targets. · `bsp/STM32F0xx/drivers/bsp.c`
- [F0 UART](https://github.com/kemgong/cola_os/blob/HEAD/bsp/STM32F0xx/drivers/stm32_usart.c): board driver · STM32F0 serial wrapper. · `bsp/STM32F0xx/drivers/stm32_usart.c`
- [F0 I/O](https://github.com/kemgong/cola_os/blob/HEAD/bsp/STM32F0xx/drivers/stm32_output.c): board driver · STM32F0 LED and output wrappers. · `bsp/STM32F0xx/drivers/stm32_output.c`
- [STM32L0](https://github.com/kemgong/cola_os/blob/HEAD/bsp/STM32L0xx/drivers/bsp.c): bsp family · Board port for STM32L0 targets. · `bsp/STM32L0xx/drivers/bsp.c`
- [L0 UART](https://github.com/kemgong/cola_os/blob/HEAD/bsp/STM32L0xx/drivers/stm32_usart.c): board driver · STM32L0 serial wrapper. · `bsp/STM32L0xx/drivers/stm32_usart.c`
- [L0 Sleep](https://github.com/kemgong/cola_os/blob/HEAD/bsp/STM32L0xx/drivers/stm32_sleep.c): board driver · STM32L0 low-power/sleep wrapper. · `bsp/STM32L0xx/drivers/stm32_sleep.c`
- [GD32E230](https://github.com/kemgong/cola_os/blob/HEAD/bsp/GD32E230xx/drivers/bsp.c): bsp family · Board port for GD32E230 targets. · `bsp/GD32E230xx/drivers/bsp.c`
- [GD32 UART](https://github.com/kemgong/cola_os/blob/HEAD/bsp/GD32E230xx/drivers/gd32_usart.c): board driver · GD32 serial wrapper. · `bsp/GD32E230xx/drivers/gd32_usart.c`
- [GD32 I/O](https://github.com/kemgong/cola_os/blob/HEAD/bsp/GD32E230xx/drivers/gd32_output.c): board driver · GD32 output and ADC wrappers. · `bsp/GD32E230xx/drivers/gd32_output.c`
- [SWM181](https://github.com/kemgong/cola_os/blob/HEAD/bsp/SWM181xx/drivers/bsp.c): bsp family · Board port for SWM181 targets. · `bsp/SWM181xx/drivers/bsp.c`
- [SWM I2C](https://github.com/kemgong/cola_os/blob/HEAD/bsp/SWM181xx/drivers/swm181x_i2c.c): board driver · SWM181 I2C wrapper. · `bsp/SWM181xx/drivers/swm181x_i2c.c`
- [SWM UART](https://github.com/kemgong/cola_os/blob/HEAD/bsp/SWM181xx/drivers/swm181x_usart.c): board driver · SWM181 serial wrapper. · `bsp/SWM181xx/drivers/swm181x_usart.c`

## Connections

- Main → App Core: starts · Application entry hands off to product logic.
- App Core → Init: uses · Application is initialized through the OS framework.
- App Core → Scheduler: runs on · Application work is scheduled cooperatively.
- Sensors → AHT20: reads · Sensor feature uses reusable sensor drivers.
- Sensors → SHT30: reads · Sensor feature uses reusable sensor drivers.
- UART → FIFO: buffers · UART feature can rely on FIFO buffering.
- Water Detect → Sensors: depends on · Water-detection logic consumes sensor data.
- UART → F0 UART: port · Serial application paths connect to board UART drivers.
- UART → L0 UART: port · Serial application paths connect to board UART drivers.
- UART → GD32 UART: port · Serial application paths connect to board UART drivers.
- UART → SWM UART: port · Serial application paths connect to board UART drivers.
- Sensors → STM32F0: uses · Sensor workflows rely on the board layer.
- Sensors → STM32L0: uses · Sensor workflows rely on the board layer.
- Sensors → GD32E230: uses · Sensor workflows rely on the board layer.
- Sensors → SWM181: uses · Sensor workflows rely on the board layer.
- AHT20 → SWM I2C: calls · Sensor modules ultimately reach board I2C services.
- SHT30 → SWM I2C: calls · Sensor modules ultimately reach board I2C services.
- FIFO → Utils: uses · Shared helpers support generic modules.
- STM32F0 → F0 I/O: contains · STM32F0 board port provides GPIO and output wrappers.
- STM32F0 → F0 UART: contains · STM32F0 board port provides GPIO and output wrappers.
- STM32L0 → L0 UART: contains · STM32L0 board port provides serial and low-power wrappers.
- STM32L0 → L0 Sleep: contains · STM32L0 board port provides serial and low-power wrappers.
- GD32E230 → GD32 I/O: contains · GD32 port provides output and analog services.
- GD32E230 → GD32 UART: contains · GD32 port provides output and analog services.
- SWM181 → SWM I2C: contains · SWM181 port provides peripheral wrappers.
- SWM181 → SWM UART: contains · SWM181 port provides peripheral wrappers.
- Scheduler → Device API: abstracts · Scheduler uses a device abstraction boundary.
- Init → Device API: configures · Initialization prepares device services for the scheduler.
- Device API → STM32F0: backed by · Device services are implemented by BSP ports.
- Device API → STM32L0: backed by · Device services are implemented by BSP ports.
- Device API → GD32E230: backed by · Device services are implemented by BSP ports.
- Device API → SWM181: backed by · Device services are implemented by BSP ports.
