How kemgong/cola_os works
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_sensor.c Sensors · cola_device.c Device API · app_uart.c UART · bsp.c STM32F0
Components 24
Application
Boot entry and product-specific logic.
- Main · Application boot and startup entry point.
app/main.c - App Core · Top-level application coordination.
app/user/app.c - Sensors · Application-level sensor handling.
app/user/app_sensor.c - UART · Application-level serial communication.
app/user/app_uart.c - Water Detect · Water-detection product logic.
app/user/app_water_detection.c
OS Layer
Cooperative task framework and device abstraction.
- Init · Framework initialization for tasks and devices.
os/cola_init.c - Device API · Device-facing abstraction layer for the scheduler.
os/cola_device.c - Scheduler · Lightweight polling-based task manager.
os/cola_os.c
Reusable Modules
Board-agnostic sensors, buffering, and helpers.
Board Support
MCU-family-specific hardware integration layers.
- STM32F0 · Board port for STM32F0 targets.
bsp/STM32F0xx/drivers/bsp.c - F0 UART · STM32F0 serial wrapper.
bsp/STM32F0xx/drivers/stm32_usart.c - F0 I/O · STM32F0 LED and output wrappers.
bsp/STM32F0xx/drivers/stm32_output.c - STM32L0 · Board port for STM32L0 targets.
bsp/STM32L0xx/drivers/bsp.c - L0 UART · STM32L0 serial wrapper.
bsp/STM32L0xx/drivers/stm32_usart.c - L0 Sleep · STM32L0 low-power/sleep wrapper.
bsp/STM32L0xx/drivers/stm32_sleep.c - GD32E230 · Board port for GD32E230 targets.
bsp/GD32E230xx/drivers/bsp.c - GD32 UART · GD32 serial wrapper.
bsp/GD32E230xx/drivers/gd32_usart.c - GD32 I/O · GD32 output and ADC wrappers.
bsp/GD32E230xx/drivers/gd32_output.c - SWM181 · Board port for SWM181 targets.
bsp/SWM181xx/drivers/bsp.c - SWM I2C · SWM181 I2C wrapper.
bsp/SWM181xx/drivers/swm181x_i2c.c - SWM UART · SWM181 serial wrapper.
bsp/SWM181xx/drivers/swm181x_usart.c
Connections 32
- 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.