TikuOS: Simple. Ubiquitous. Intelligence, Everywhere.

Architecture Overview

TikuOS is organized as a strict layered architecture, engineered from the ground up to run on microcontrollers with kilobytes of memory and microwatts of power budget. Every layer has a single responsibility, a small surface area, and a clear dependency direction: higher layers depend on lower layers, never the other way around.

The goal of this structure is three-fold: keep the kernel small enough to fit alongside application code on 2 KB SRAM parts, make porting to new silicon a matter of filling in one arch layer rather than touching the kernel, and let reusable library code (drivers, math, ML, networking) live outside the kernel without turning into a tangle of cross-cutting dependencies.

Layered Architecture

From top to bottom, the TikuOS stack looks like this. Each layer depends only on the layers beneath it.

Kernel Modules

The kernel is a small set of cooperating modules. None of them own a thread; instead, the scheduler drives the whole system with a single event loop. Every module is independently testable and most can be compiled out of the final image if the application does not need them.

Event-Driven Runtime

TikuOS does not have threads in the traditional sense. It has processes — protothread functions that wait on events, react, and yield. All processes share the main stack, so a 2 KB SRAM part can host half a dozen processes without running out of memory.

The runtime is a single cooperative loop:

1. Check software timers; post TIKU_EVENT_TIMER for any that expired.
2. If the event queue is non-empty, dispatch one event to its target process.
3. If nothing is pending, call the idle hook (usually enters LPM3 or LPM4).
4. Interrupts (clock tick, UART RX, GPIO, radio) wake the CPU and may post
   new events, restarting the loop from step 1.

The effect is that the CPU spends almost all of its time asleep. A typical sensor-logging device might wake up once per second, post a timer event, run a protothread for a few microseconds, and go back to sleep — consuming on average a few hundred microwatts.

How TikuKits Fit In

TikuKits is a separate repository of reusable library code that sits above the kernel but below the application. Kits have no privileged position in the system — they are ordinary C libraries that link against kernel and interface APIs. Splitting them out keeps the core kernel small and lets each library evolve independently.

Kits Overview

Naming and Layering Rules

• Every public identifier in a kit is prefixed tiku_kits_<library>_.
• Each top-level kit has a single common header (e.g. tiku_kits_sensor.h) that defines shared types and return codes. Sub-modules include the parent and reuse those return codes.
• Kits depend on kernel APIs and interfaces, never on other kits — keeping dependencies a tree, not a graph.
• The kernel does not depend on kits. A minimal firmware image can build with zero kits enabled.

Applications

The apps/ directory contains full applications shipped with the repository. Exactly one app, one test suite, or one examples build can be active at a time (selected via the APP= make variable).

User applications do not need to live inside apps/. A typical out-of-tree project adds its own process files, #include "tiku.h", and links against whichever kits it needs.

Hardware Abstraction

The HAL and arch layers are the reason TikuOS can run on several MSP430 variants without touching the kernel. The contract is a one-way interface:

• hal/tiku_*_hal.h declares the functions the kernel uses (tiku_clock_hal_init(), tiku_adc_hal_read(), etc.). These headers are included by kernel and interface code.
• arch/msp430/tiku_*_arch.c implements those functions against MSP430 peripherals. The .c files are device-agnostic: they use macros like TIKU_DEVICE_HAS_LPM45 and TIKU_BOARD_LED1_PORT that are supplied by the device/board headers.
• arch/msp430/devices/ contains one header per supported MCU (FR5969, FR5994, FR6989) with silicon constants.
• arch/msp430/boards/ contains one header per supported board with pin assignments, LED count, and crystal configuration.
• arch/msp430/tiku_device_select.h routes the TIKU_DEVICE_* define in tiku.h to the correct device and board headers at compile time.

Porting to a new MSP430 variant requires adding one device header, one board header, and a single #elif branch in tiku_device_select.h. Porting to a new architecture (Ambiq Apollo, Nordic nRF54L, RISC-V) means adding a new arch/<name>/ tree that fulfills the same HAL contracts.

Boot Sequence

On reset, main() hands control to the boot code, which brings up the system in a deterministic sequence. Each stage is recorded in /sys/boot/stage so a post-mortem shell session can see how far the boot got.

1. init         — earliest CPU setup; capture SYSRSTIV for /sys/boot/reason
2. cpu          — clock tree, watchdog, MPU
3. memory       — tiku_mem_init(): region registry, MPU activation, arenas
4. peripherals  — HAL init for UART, timers, GPIO, ADC, I2C, SPI
5. services     — tiku_clock_init(), tiku_sched_init(), tiku_vfs_tree_init(),
                  tiku_shell_init() (if enabled), tiku_init_run() (if enabled)
6. complete     — tiku_sched_loop() takes over; autostart processes run

From the moment tiku_sched_loop() is entered, the system is event-driven: the CPU only wakes when there is work, and goes back to sleep as soon as the event queue is empty.

The TikuOS Ecosystem

Beyond the kernel and kits, the project ships a few supporting pieces that make development and research on microwatt devices practical:

Design Principles

• Static everything. No heap, no dynamic allocation. Every buffer is sized at compile time; memory use is auditable from a single linker map.
• Event-driven. No preemption, no blocking waits. Processes yield on events and the scheduler sleeps the CPU aggressively between them.
• Layer discipline. Kernel does not depend on kits or apps. Kits do not depend on each other. Arch layer is a one-way contract.
• Small surface area. Each module exposes the minimum needed to use it. Internal helpers stay internal.
• Observable by default. Every kernel subsystem surfaces its state through the VFS, so the shell can inspect a running system without special tooling.
• Configurable at boot. What starts on power-up is edited over the shell and stored in FRAM — one firmware image can run many configurations.
• Power-aware. Every design decision is evaluated against its impact on sleep-mode residency, because the entire reason TikuOS exists is to run on energy budgets that would starve a conventional RTOS.