Skip to content

Commit 81dda10

Browse files
srpatchasrpatcha
committed
EmbeddedOS docs v0.3.0 - Complete API reference for all products
0 parents  commit 81dda10

15 files changed

Lines changed: 2757 additions & 0 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
24+
- name: Validate HTML
25+
run: |
26+
echo "── Checking for required files ──"
27+
test -f index.html || { echo "ERROR: index.html not found"; exit 1; }
28+
echo "✓ index.html exists"
29+
30+
echo "── Checking for broken internal links ──"
31+
MISSING=0
32+
for file in $(grep -oP 'href="(?!https?://|#|mailto:)[^"]+' index.html | sed 's/href="//'); do
33+
if [ ! -f "$file" ]; then
34+
echo "WARNING: linked file not found: $file"
35+
MISSING=$((MISSING + 1))
36+
fi
37+
done
38+
if [ "$MISSING" -eq 0 ]; then
39+
echo "✓ No broken internal links"
40+
fi
41+
42+
echo "── File sizes ──"
43+
for f in $(find . -name '*.html' -o -name '*.css' -o -name '*.js' | grep -v node_modules | grep -v .git); do
44+
SIZE=$(wc -c < "$f")
45+
echo " $f: ${SIZE} bytes"
46+
done
47+
echo "✓ Build validation complete"
48+
49+
- name: Prepare CNAME
50+
run: |
51+
if [ -f CNAME ]; then
52+
DOMAIN=$(grep -v '^#' CNAME | grep -v '^$' | head -1)
53+
if [ -n "$DOMAIN" ]; then
54+
echo "$DOMAIN" > CNAME
55+
echo "✓ Custom domain: $DOMAIN"
56+
else
57+
echo "ℹ CNAME has no active domain — removing from artifact"
58+
rm -f CNAME
59+
fi
60+
else
61+
echo "ℹ No CNAME file — using default github.io domain"
62+
fi
63+
64+
- name: Setup Pages
65+
uses: actions/configure-pages@v5
66+
67+
- name: Upload artifact
68+
uses: actions/upload-pages-artifact@v3
69+
with:
70+
path: .
71+
72+
deploy:
73+
runs-on: ubuntu-latest
74+
needs: build
75+
environment:
76+
name: github-pages
77+
url: ${{ steps.deployment.outputs.page_url }}
78+
steps:
79+
- name: Deploy to GitHub Pages
80+
id: deployment
81+
uses: actions/deploy-pages@v4

‎CNAME‎

Whitespace-only changes.

‎README.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# EoS — Embedded Operating System
2+
3+
**Website**: [embeddedos-org.github.io](https://embeddedos-org.github.io)
4+
5+
## v0.1.0 Release
6+
7+
All 9 repositories at v0.1.0, 1 commit each.
8+
9+
### Ecosystem
10+
11+
| Repo | Description | Version |
12+
|---|---|---|
13+
| [eos](https://github.com/embeddedos-org/eos) | Core OS — HAL (33 peripherals), kernel, services, GDB stub, core dump, service manager, loadable drivers, device tree parser | v0.1.0 |
14+
| [eboot](https://github.com/embeddedos-org/eboot) | Bootloader — 26 board ports, A/B update, secure boot, crypto | v0.1.0 |
15+
| [ebuild](https://github.com/embeddedos-org/ebuild) | Build system — SDK generator (14 targets), eBoot board generator, deliverable packager, gated release | v0.1.0 |
16+
| [eipc](https://github.com/embeddedos-org/eipc) | Secure IPC — Go + C SDK, HMAC, replay protection | v0.1.0 |
17+
| [eai](https://github.com/embeddedos-org/eai) | AI layer — llama.cpp, agent loop, Ebot server | v0.1.0 |
18+
| [eni](https://github.com/embeddedos-org/eni) | Neural interface — BCI, assistive input | v0.1.0 |
19+
| [EoSuite](https://github.com/embeddedos-org/EoSuite) | Dev tools — Ebot client, 20+ GUI apps | v0.1.0 |
20+
21+
### Supported Hardware (14 targets)
22+
23+
| Target | Arch | CPU | Vendor | Board |
24+
|---|---|---|---|---|
25+
| stm32f4 | ARM | Cortex-M4 | ST | STM32F407 |
26+
| stm32h7 | ARM | Cortex-M7 | ST | STM32H743 |
27+
| nrf52 | ARM | Cortex-M4 | Nordic | nRF52840 |
28+
| rp2040 | ARM | Cortex-M0+ | RPi | RP2040 |
29+
| raspi3 | AArch64 | Cortex-A53 | Broadcom | BCM2837 |
30+
| raspi4 | AArch64 | Cortex-A72 | Broadcom | BCM2711 |
31+
| imx8m | AArch64 | Cortex-A53 | NXP | i.MX8M |
32+
| am64x | AArch64 | Cortex-A53 | TI | AM6442 |
33+
| riscv_virt | RISC-V | rv64gc | QEMU | virt |
34+
| sifive_u | RISC-V | U74 | SiFive | FU740 |
35+
| malta | MIPS | 24Kf | MIPS | Malta |
36+
| x86_64 | x86_64 | generic | Generic | PC/Server |
37+
38+
### Build & Deploy
39+
40+
```bash
41+
# Generate SDK for target
42+
ebuild sdk --target raspi4
43+
44+
# Source environment
45+
source build/eos-sdk-raspi4/environment-setup
46+
47+
# Build
48+
cmake -B build -DCMAKE_TOOLCHAIN_FILE=$CMAKE_TOOLCHAIN_FILE
49+
cmake --build build
50+
51+
# Deploy
52+
scp build/app pi@192.168.1.100:~/
53+
```
54+
55+
### Release Deliverables
56+
57+
Every build produces `eos-{target}-v0.1.0-deliverable.zip`:
58+
- **EoS source code + SDK** for the product
59+
- **eBoot source code** + board config for the target
60+
- **EAI source code** + Ebot server
61+
- **ENI source code**
62+
- **EoSuite binaries** for the product
63+
- Auto-generated `eos_product_config.h`
64+
65+
### CI/CD
66+
67+
- Gated release — all repos must pass before release
68+
- 104 CI jobs across all repos per push
69+
- 11 QEMU board types, 6 architectures
70+
- Cross-repo dispatch — change in any repo validates all

‎docs/eai.html‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>EAI Documentation -- EmbeddedOS</title>
7+
<link rel="stylesheet" href="../style.css">
8+
</head>
9+
<body>
10+
11+
<nav class="site-nav">
12+
<span class="brand">EmbeddedOS</span>
13+
<div class="nav-links">
14+
<a href="../index.html">Home</a>
15+
<a href="index.html" class="active">Docs</a>
16+
<a href="../getting-started.html">Getting Started</a>
17+
<a href="https://github.com/embeddedos-org" target="_blank">GitHub</a>
18+
</div>
19+
</nav>
20+
21+
<div class="doc-layout">
22+
<aside class="doc-sidebar">
23+
<h4>Getting Started</h4>
24+
<a href="../getting-started.html">Quick Start Guide</a>
25+
<h4>Core</h4>
26+
<a href="eos.html">EoS</a>
27+
<a href="eboot.html">eBoot</a>
28+
<a href="ebuild.html">ebuild</a>
29+
<h4>Middleware</h4>
30+
<a href="eipc.html">EIPC</a>
31+
<a href="eai.html" class="active">EAI</a>
32+
<a href="eni.html">ENI</a>
33+
<h4>Tools</h4>
34+
<a href="eosuite.html">EoSuite</a>
35+
<a href="eosim.html">EoSim</a>
36+
</aside>
37+
38+
<main class="doc-main">
39+
<h1>EAI -- Embedded AI Layer</h1>
40+
<p>On-device AI inference engine with agentic tool-use capabilities, persistent memory, and an HTTP server (Ebot). Supports 8 quantized LLM models from 80 MB to 6 GB RAM, with automatic model selection based on hardware constraints.</p>
41+
<p><a href="https://github.com/embeddedos-org/eai" target="_blank">GitHub Repository</a></p>
42+
43+
<h2>Getting Started</h2>
44+
<pre><code>git clone https://github.com/embeddedos-org/eai.git
45+
cd eai
46+
cmake -B build && cmake --build build</code></pre>
47+
48+
<h2>API Reference -- Configuration</h2>
49+
<ul class="api-list">
50+
<li><code>eai_config_parse(path, cfg)</code> -- Parse a YAML/JSON configuration file into an EAI config struct</li>
51+
<li><code>eai_config_free(cfg)</code> -- Free memory allocated for a parsed configuration</li>
52+
</ul>
53+
54+
<h2>API Reference -- Tools</h2>
55+
<ul class="api-list">
56+
<li><code>eai_tool_register(name, fn, desc)</code> -- Register a callable tool with the agent runtime</li>
57+
<li><code>eai_tool_exec(name, args, result)</code> -- Execute a registered tool by name with arguments</li>
58+
<li><code>eai_tool_list(buf, len)</code> -- List all registered tools into a buffer</li>
59+
</ul>
60+
61+
<h2>API Reference -- Agent</h2>
62+
<ul class="api-list">
63+
<li><code>eai_agent_init(cfg)</code> -- Initialize the AI agent with model, tools, and memory configuration</li>
64+
<li><code>eai_agent_step(input, output)</code> -- Run one agent step: process input, optionally call tools, produce output</li>
65+
<li><code>eai_agent_reset()</code> -- Reset the agent state and clear conversation history</li>
66+
</ul>
67+
68+
<h2>API Reference -- Memory</h2>
69+
<ul class="api-list">
70+
<li><code>eai_memory_init(capacity)</code> -- Initialize the persistent memory store with a maximum capacity</li>
71+
<li><code>eai_memory_store(key, value)</code> -- Store a key-value pair in persistent memory</li>
72+
<li><code>eai_memory_recall(key, buf, len)</code> -- Recall a value from persistent memory by key</li>
73+
<li><code>eai_memory_clear()</code> -- Clear all entries from persistent memory</li>
74+
</ul>
75+
76+
<h2>API Reference -- Models</h2>
77+
<ul class="api-list">
78+
<li><code>eai_model_find_best_fit(ram_mb, storage_mb)</code> -- Select the best model that fits within RAM and storage constraints</li>
79+
<li><code>eai_model_get_catalog(buf, count)</code> -- Get the full catalog of available models</li>
80+
</ul>
81+
82+
<h2>API Reference -- Runtime</h2>
83+
<ul class="api-list">
84+
<li><code>eai_runtime_init(model_path)</code> -- Initialize the inference runtime with a GGUF model file</li>
85+
<li><code>eai_runtime_infer(prompt, output, max_tokens)</code> -- Run inference on a prompt and generate up to max_tokens</li>
86+
</ul>
87+
88+
<h2>Supported LLM Models</h2>
89+
<table>
90+
<thead><tr><th>Model</th><th>RAM</th><th>Storage</th><th>Tier</th><th>Hardware</th></tr></thead>
91+
<tbody>
92+
<tr><td>TinyLlama 1.1B Q2_K</td><td>80 MB</td><td>400 MB</td><td>Micro</td><td>STM32H7, ESP32-S3</td></tr>
93+
<tr><td>SmolLM 360M Q5</td><td>100 MB</td><td>250 MB</td><td>Tiny</td><td>RPi3, nRF5340</td></tr>
94+
<tr><td>Qwen2 0.5B Q4</td><td>120 MB</td><td>350 MB</td><td>Tiny</td><td>RPi3, AM64x</td></tr>
95+
<tr><td>Phi-2 Q4</td><td>600 MB</td><td>1.6 GB</td><td>Small</td><td>RPi4, i.MX8M</td></tr>
96+
<tr><td>Phi-3-mini Q4 (default)</td><td>2 GB</td><td>2.3 GB</td><td>Small</td><td>RPi4 8 GB</td></tr>
97+
<tr><td>Llama 3.2 3B Q4</td><td>2.5 GB</td><td>2 GB</td><td>Medium</td><td>RPi5, Jetson</td></tr>
98+
<tr><td>Mistral 7B Q3_K</td><td>3.5 GB</td><td>3 GB</td><td>Medium</td><td>x86 edge</td></tr>
99+
<tr><td>Llama 3.2 8B Q4</td><td>6 GB</td><td>4.7 GB</td><td>Large</td><td>x86, Orin</td></tr>
100+
</tbody>
101+
</table>
102+
103+
<h2>Ebot Server Endpoints</h2>
104+
<p>The Ebot HTTP server exposes a REST API for interacting with the AI agent over the network:</p>
105+
<table>
106+
<thead><tr><th>Method</th><th>Endpoint</th><th>Description</th></tr></thead>
107+
<tbody>
108+
<tr><td>POST</td><td>/v1/chat</td><td>Chat with conversation history</td></tr>
109+
<tr><td>POST</td><td>/v1/complete</td><td>Single-shot text completion</td></tr>
110+
<tr><td>GET</td><td>/v1/tools</td><td>List all registered tools</td></tr>
111+
<tr><td>GET</td><td>/v1/models</td><td>List available models</td></tr>
112+
<tr><td>GET</td><td>/v1/status</td><td>Server statistics and health check</td></tr>
113+
</tbody>
114+
</table>
115+
116+
<h2>Usage Example</h2>
117+
<pre><code>// Initialize EAI with automatic model selection
118+
eai_config cfg;
119+
eai_config_parse("eai.yml", &cfg);
120+
eai_agent_init(&cfg);
121+
122+
// Register a custom tool
123+
eai_tool_register("read_sensor", sensor_read_fn, "Read a sensor value");
124+
125+
// Run an agent step
126+
char output[4096];
127+
eai_agent_step("What is the current temperature?", output);
128+
129+
// Query the Ebot server
130+
// curl -X POST http://localhost:8420/v1/chat \
131+
// -d '{"messages":[{"role":"user","content":"Hello"}]}'</code></pre>
132+
133+
</main>
134+
</div>
135+
136+
</body>
137+
</html>

0 commit comments

Comments
 (0)