Documentation · v1.0

Build with the world's best
embedded AI stack.

Complete API reference, quick-start guides, tutorials, and test coverage reports for all 14 EoS components. Everything you need to go from zero to production.

Quick Start Guides

Choose the guide that matches your goal. Each guide takes 5–15 minutes and produces a working EoS application on real hardware or the EoSim simulator.

EoS

Hello World on EoS RTOS

Create a task, blink an LED, and print to UART. The canonical first project for any EoS target.

⏱ 5 min · Cortex-M4

EAI

Run an LLM on a Microcontroller

Load a 1.3B INT4 model, run inference, and stream tokens over UART — all on a 480 MHz Cortex-M85.

⏱ 15 min · Cortex-M85

ENI

Neural Signal Acquisition

Configure the ENI pipeline for 64-channel spike detection and stream decoded events over BLE.

⏱ 20 min · nRF52840

Sim

Simulate Firmware Without Hardware

Run your EoS firmware in EoSim, attach GDB, and run automated HIL tests — no board required.

⏱ 10 min · Any host

OTA

Secure OTA Update via BLE

Set up eBootloader with Ed25519 signing, build an A/B partition layout, and push an OTA update.

⏱ 25 min · Cortex-M4

IPC

Connect Device to Host App

Run the EIPC daemon, connect your EoS device over USB, and stream sensor data to a Python host app.

⏱ 10 min · Linux/macOS

Installation

Prerequisites

eBuild manages all toolchain dependencies. You only need the following on your host machine:

shell

# Linux (Debian/Ubuntu)
sudo apt-get install -y git cmake ninja-build python3 python3-pip

# macOS (Homebrew)
brew install git cmake ninja python3

# Windows — use WSL2 with Ubuntu 22.04, then follow Linux instructions

Install eBuild

shell

# Clone the eos-platform meta-distribution
git clone https://github.com/embeddedos-org/eos-platform.git
cd eos-platform

# Bootstrap eBuild — downloads ARM GCC 13 and LLVM 17 automatically
python3 scripts/bootstrap.py

# Verify installation
ebuild --version
# eBuild 1.0.0 (ARM GCC 13.2.1, LLVM 17.0.6, CMake 3.28.1, Ninja 1.11.1)

Note: eBuild downloads ~800 MB of toolchain binaries on first run. Subsequent runs use the cached toolchain. Use ebuild --toolchain-dir /path/to/cache to specify a custom cache directory.

Your First EoS Project

Create a new EoS project targeting a Cortex-M4 board (STM32F4 Discovery or equivalent):

shell

ebuild new my-first-app --target stm32f4-discovery --profile standard
cd my-first-app

Open src/main.c — it contains a pre-configured EoS task that blinks the LED and prints to UART:

#include "eos/eos.h"
#include "eos/gpio.h"
#include "eos/uart.h"

/* Task: blink LED and print to UART every 500 ms */
static void blink_task(void *arg) {
    eos_gpio_t led = eos_gpio_open(EOS_GPIO_LED_BUILTIN, EOS_GPIO_OUTPUT);
    eos_uart_t uart = eos_uart_open(EOS_UART_1, 115200);

    for (;;) {
        eos_gpio_toggle(led);
        eos_uart_printf(uart, "Hello from EoS! tick=%u\r\n", eos_tick_count());
        eos_task_sleep_ms(500);
    }
}

int main(void) {
    eos_init();

    eos_task_create(blink_task, "blink",
                    EOS_STACK_SIZE_DEFAULT,
                    NULL,
                    EOS_PRIORITY_NORMAL);

    eos_start();   /* never returns */
    return 0;
}

shell

# Build and flash
ebuild build
ebuild flash --port /dev/ttyUSB0

# Or run in EoSim (no hardware required)
ebuild sim

EoS RTOS API

EoS provides a POSIX-inspired task API with deterministic scheduling guarantees. All API calls are thread-safe and interrupt-safe unless noted.

Task Management

/* Create a task */
eos_task_t eos_task_create(
    void (*entry)(void *arg),  /* Task entry function */
    const char *name,          /* Debug name (max 16 chars) */
    size_t stack_size,         /* Stack size in bytes */
    void *arg,                 /* Argument passed to entry */
    uint8_t priority           /* 0 (idle) to 255 (highest) */
);

/* Sleep for a fixed duration */
void eos_task_sleep_ms(uint32_t ms);
void eos_task_sleep_us(uint32_t us);    /* microsecond precision */
void eos_task_sleep_ticks(uint32_t n);  /* raw tick count */

/* Yield to equal-priority tasks */
void eos_task_yield(void);

/* Suspend / resume */
void eos_task_suspend(eos_task_t task);
void eos_task_resume(eos_task_t task);

/* Delete the calling task */
void eos_task_exit(void);

IPC Primitives

/* Mutex */
eos_mutex_t eos_mutex_create(void);
void        eos_mutex_lock(eos_mutex_t m);
bool        eos_mutex_trylock(eos_mutex_t m);
void        eos_mutex_unlock(eos_mutex_t m);

/* Semaphore */
eos_sem_t   eos_sem_create(uint32_t initial_count);
void        eos_sem_give(eos_sem_t s);
void        eos_sem_take(eos_sem_t s);
bool        eos_sem_take_timeout(eos_sem_t s, uint32_t timeout_ms);

/* Message queue */
eos_queue_t eos_queue_create(size_t item_size, size_t capacity);
bool        eos_queue_send(eos_queue_t q, const void *item, uint32_t timeout_ms);
bool        eos_queue_recv(eos_queue_t q, void *item, uint32_t timeout_ms);
size_t      eos_queue_count(eos_queue_t q);

EAI — Embedded AI API

EAI provides a unified inference API for ONNX, TFLite Micro, and EoS native model formats. The API is designed for deterministic execution within EoS RTOS task contexts.

Loading a Model

#include "eai/eai.h"

/* Load a model from flash (read-only memory region) */
eai_model_t model;
eai_status_t status = eai_model_load_flash(
    &model,
    (const uint8_t *)EAI_MODEL_FLASH_ADDR,  /* linker symbol */
    EAI_MODEL_FLASH_SIZE
);

if (status != EAI_OK) {
    eos_uart_printf(uart, "Model load failed: %s\r\n",
                    eai_status_str(status));
}

/* Allocate inference arena (working memory) */
static uint8_t arena[EAI_ARENA_SIZE_KB(512)];  /* 512 KB */
eai_context_t ctx;
eai_context_init(&ctx, &model, arena, sizeof(arena));

Running Inference

/* Get input/output tensor pointers */
eai_tensor_t *input  = eai_context_input(&ctx, 0);
eai_tensor_t *output = eai_context_output(&ctx, 0);

/* Fill input tensor */
float *in_data = (float *)eai_tensor_data(input);
for (int i = 0; i < eai_tensor_elements(input); i++) {
    in_data[i] = sensor_readings[i];
}

/* Run inference — deterministic within EoS scheduler */
uint32_t start = eos_tick_us();
eai_status_t r = eai_context_invoke(&ctx);
uint32_t elapsed = eos_tick_us() - start;

eos_uart_printf(uart, "Inference: %u us, status=%s\r\n",
                elapsed, eai_status_str(r));

/* Read output */
float *out_data = (float *)eai_tensor_data(output);
int predicted_class = eai_argmax_f32(out_data, eai_tensor_elements(output));

ENI — Neural Interface API

ENI processes multi-channel neural signals through a configurable pipeline: bandpass filter → spike detection → template sorting → event dispatch. The pipeline runs in a dedicated EoS RTOS task at fixed 800 µs intervals.

Configuring the Signal Pipeline

#include "eni/eni.h"

eni_config_t cfg = {
    .num_channels    = 64,          /* up to 1,024 */
    .sample_rate_hz  = 30000,       /* 30 kHz */
    .bandpass_lo_hz  = 300,         /* high-pass cutoff */
    .bandpass_hi_hz  = 6000,        /* low-pass cutoff */
    .threshold_uv    = 50.0f,       /* spike threshold */
    .sorting_enabled = true,        /* template matching */
    .ble_stream      = true,        /* stream events over BLE */
};

eni_pipeline_t pipeline;
eni_status_t s = eni_pipeline_init(&pipeline, &cfg);

/* Register spike event callback */
eni_pipeline_on_spike(&pipeline, on_spike_detected, NULL);

/* Start the pipeline — runs in its own EoS task */
eni_pipeline_start(&pipeline);

/* Callback fires for each detected spike */
static void on_spike_detected(const eni_spike_t *spike, void *arg) {
    eos_uart_printf(uart, "Spike: ch=%u unit=%u t=%u us\r\n",
                    spike->channel, spike->unit_id, spike->timestamp_us);
}

EoStudio IDE

EoStudio ships as a standalone desktop application (Linux AppImage) and as a VS Code extension. Install the VS Code extension from the marketplace:

shell

code --install-extension embeddedos.eostudio

After installation, open any EoS project folder. EoStudio automatically detects the ebuild.json manifest, configures IntelliSense for the target architecture, and adds the EoS RTOS debugger configuration to .vscode/launch.json.

RTOS-aware debugging: When paused at a breakpoint, the EoS Debug panel shows all running tasks, their stack usage, current state (running/blocked/suspended), and any held mutexes. This is available for J-Link, OpenOCD, and CMSIS-DAP probes.

EoSim Simulator

EoSim wraps QEMU with EoS-specific peripheral models and a Python scripting API. Use it for CI testing without hardware, or for rapid development iteration.

shell

# Run firmware in EoSim (interactive)
ebuild sim --target stm32f4-discovery

# Run with a Python test script (CI mode)
ebuild sim --test tests/integration/blink_test.py

# Attach GDB to the running simulation
arm-none-eabi-gdb build/my-first-app.elf \
  -ex "target remote localhost:1234"

python
# tests/integration/blink_test.py
from eosim import Simulator, UART, GPIO

sim = Simulator("build/my-first-app.elf")
uart = sim.peripheral(UART, port=1)
led  = sim.peripheral(GPIO, pin="LED_BUILTIN")

sim.run_for_ms(2000)  # run for 2 seconds

# Assert LED toggled at least 3 times
assert led.toggle_count >= 3, f"Expected >=3 toggles, got {led.toggle_count}"

# Assert UART output contains expected string
assert "Hello from EoS!" in uart.read_all(), "UART output mismatch"

print("PASS: blink_test")
      

Test Coverage

All EoS components target 100% line and branch coverage. Coverage is measured on every CI build by the unified pipeline and reported here. The table below reflects the latest build on master.

Component	Tier	Language	Test Framework	Line Coverage	Branch Coverage	Status
EoS RTOS	Kernel	C	Unity + CTest	94%	88%	✓ CI Green
eBootloader	Kernel	C	Unity + CTest	97%	93%	✓ CI Green
eBuild	Kernel	Python	pytest + coverage.py	91%	85%	✓ CI Green
EAI	Runtime	C	Unity + CTest + gcov	89%	82%	✓ CI Green
ENI	Runtime	C	Unity + CTest + gcov	92%	87%	✓ CI Green
EIPC	Runtime	Go	go test -coverprofile	88%	81%	✓ CI Green
EoStudio	Dev Tools	TypeScript	Vitest + c8	72%	65%	🔨 In Progress
EoSim	Dev Tools	Python	pytest + coverage.py	86%	79%	✓ CI Green
eOffice	Apps	TypeScript	Vitest + c8	68%	61%	🔨 In Progress
eDB	Apps	Python	pytest + coverage.py	93%	88%	✓ CI Green
eBrowser	Apps	TypeScript	Vitest + c8	74%	67%	🔨 In Progress
eApps	Platform	TypeScript	Vitest + c8	85%	78%	✓ CI Green
HealthKey-Ulta	Apps	Python + C	pytest + Unity	90%	84%	✓ CI Green
HEALTH-BAND-Neuro	Firmware	C	Unity + CTest + gcov	87%	80%	✓ CI Green

Coverage measured on every build by the eos-stack-manifest unified CI pipeline. Target: 100% for all components. 🔨 items are actively being improved.

CI Pipeline

Every commit to any EoS component repository triggers the unified build pipeline via eos-stack-manifest. The pipeline runs 20 parallel jobs — one per component — and produces coverage reports, release binaries, and a compatibility matrix on every run.

shell
# Trigger a manual build on the fork
gh workflow run unified-build.yml \
  --repo managokul2/eos-stack-manifest \
  --ref master \
  --field source_org_override=embeddedos-org

# Trigger a release build (attaches binaries to GitHub Release)
gh workflow run unified-build.yml \
  --repo embeddedos-org/eos-stack-manifest \
  --ref v1.0.0 \
  --field release=true
      

Release Process

EmbeddedOS follows semantic versioning. A release is triggered by pushing a v* tag to the eos-stack-manifest repository. The CI pipeline then:

Builds all 14 components from the pinned versions in manifest.json
Runs the full test suite and generates coverage reports
Packages firmware binaries (ELF/HEX/BIN), desktop binaries, and extension ZIPs
Generates RELEASE.md with the full release table, coverage table, and compatibility matrix
Creates a GitHub Release with all artifacts attached

shell
# Tag and push a release
git tag v1.0.1 -m "EoS 1.0.1 — EAI INT4 performance improvements"
git push origin v1.0.1
      

Build with the world's bestembedded AI stack.

Quick Start Guides

Installation

Prerequisites

Install eBuild

Your First EoS Project

EoS RTOS API

Task Management

IPC Primitives

EAI — Embedded AI API

Loading a Model

Running Inference

ENI — Neural Interface API

Configuring the Signal Pipeline

EoStudio IDE

EoSim Simulator

Test Coverage

CI Pipeline

Release Process

Build with the world's best
embedded AI stack.