SyntropicOS Documentation¶

High-Performance Bare-Metal Application Framework & Cooperative OS

SyntropicOS is a zero-overhead, production-grade C99 framework designed for deeply embedded systems. It provides stackless multitasking, non-blocking drivers, industrial fieldbuses, and display graphics for targets ranging from 8-bit microcontrollers to 32-bit Cortex-M and RISC-V targets.

Technical Specifications At-a-Glance¶

Feature	Design Specification
Concurrency	Cooperative protothreads (`syn_pt`). Continuation state costs 2 bytes RAM per thread.
Task Scheduler	Cooperative task runner (`syn_sched`). Task descriptors cost ~16–28 bytes RAM per task.
Memory Allocation	100% Zero-Heap / Static Allocation. No `malloc()` or dynamic pool fragmentation over long runtimes.
Execution Model	All 70+ drivers & protocol stacks are written as non-blocking state machines.
Compatibility	Standard C99. Compiles with GCC, Clang, IAR, Keil, STM32CubeIDE, and Arduino IDE.

Module Documentation Index¶

Quick-jump to specific feature guides and API references:

⚡ Core & Multitasking (Read Core Docs →)¶

Protothreads (syn_pt): Stackless coroutines for non-blocking task execution.
Task Scheduler (syn_sched): Cooperative task runner with priority & delay timers.
Active Objects (syn_ao): FSM state machine + SPSC queue + task runner actor model.
Event Flags & Mailboxes: Thread-safe inter-task messaging and synchronization.

🎛️ Input / Output Drivers (Read I/O Docs →)¶

Buttons (syn_button): Debounced buttons, multi-click tap gestures, long-press, auto-repeat, and combos.
Rotary Encoder (syn_encoder): Quadrature rotary decoding and velocity tracking.
LED Controller (syn_led): Pattern blinking, flash sequences, and Morse sequences.
Software PWM (syn_soft_pwm): Timerless PWM generation on arbitrary GPIO pins.

📡 Communications & Protocol Stacks (Read Comm Docs →)¶

COBS Framing (syn_cobs): Zero-overhead 0x00-delimited packet framing.
Packet Router (syn_router): Addressed packet dispatch (Master/Slave Node IDs) with ACKs.
Industrial Modbus (syn_modbus): Modbus RTU & Modbus TCP Master/Slave stacks.
M-Bus Metering (syn_mbus): EN 13757 European utility meter bus decoder.
Automotive ISO-TP & J1939: CAN bus multi-frame transport and heavy vehicle PGN/SPN decoder.

💾 Storage & Filesystems (Read Storage Docs →)¶

Persistent Settings (syn_settings): Wear-leveled flash configuration with load-or-default & CRC-16.
Virtual File System (syn_vfs): POSIX-like VFS abstraction for LittleFS and FAT.

🖥️ Display & Embedded UI (Read Display Docs →)¶

Display Canvas (syn_canvas): Hardware-independent 1bpp/16bpp framebuffer & 2D graphics.
Immediate-Mode GUI (syn_imgui): Zero-heap UI widgets (buttons, sliders, gauges, graphs).

🔬 Diagnostics & System Services (Read Debug Docs →)¶

Lightweight Event Tracer (syn_trace): Timestamped circular event recorder for ISRs & tasks.
Task CPU Profiler (syn_profiler): Task CPU percentage, peak execution time, and run metrics.
Serial CLI (syn_cli): Zero-allocation interactive shell with command auto-help.
Software Watchdog (syn_watchdog): Multi-task heartbeat monitor and deadlock prevention.

Getting Started & Platform Guides¶

Getting Started Guide — Step-by-step setup for C99 CMake & Makefile projects.
Arduino Compatibility Guide — Installing via Library Manager and working with Multi-Tab sketch examples.
Porting & System Integration — Implementing custom GPIO, UART, and timer tick ports.