# arc1011/kerneluno architecture

> Architecture diagram of the GitHub repository arc1011/kerneluno, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arc1011/kerneluno
- Repository: https://github.com/arc1011/kerneluno

## Overview

1. **Overall shape**
   - KernelUNO is a single Arduino UNO firmware application, centered in `KernelUNO.ino`.
   - It behaves like a tiny Unix-like shell running directly on the microcontroller, with no host-side daemon or external backend.

2. **Primary runtime boundary**
   - The main interaction boundary is the **serial terminal**.
   - All user input arrives over Serial, is buffered, parsed line-by-line, and dispatched as shell commands.
   - All output, including command results and errors, is written back to Serial.

3. **Core subsystems**
   - The repository organizes functionality around three embedded subsystems:
     - **Shell/command interpreter** for parsing and executing commands.
     - **RAM filesystem** for files, directories, and pseudo-devices.
     - **GPIO/sensor control layer** for pin configuration and I/O.
   - These are not separate services; they are tightly coupled inside the firmware.

4. **Filesystem model**
   - The filesystem is entirely in RAM and extremely small by design.
   - Constraints from the README define the architecture: up to 10 total entries, 32 bytes per file, and 12-character names.
   - The filesystem provides Unix-like path navigation and file operations, but all state is volatile and resets on reboot.

5. **Directory and path semantics**
   - The shell maintains a current working directory and supports familiar commands like `ls`, `cd`, `pwd`, `mkdir`, `touch`, `rm`, `find`, and `cat`.
   - On boot, it automatically creates `/home` and `/dev`, which establishes the root-level structure of the virtual tree.
   - This means navigation and command behavior are path-aware even though the storage is memory-backed.

6. **Special device files**
   - `/dev/pin2`, `/dev/pin3`, and `/dev/pin4` are special filesystem entries rather than normal files.
   - They form the boundary between the virtual filesystem and physical hardware control.
   - Reading or writing these entries maps onto Arduino GPIO behavior, allowing the shell to treat hardware pins like device nodes.

7. **Hardware control path**
   - GPIO commands use native Arduino APIs: `pinMode()`, `digitalWrite()`, `digitalRead()`, and `analogWrite()`.
   - Commands such as `pinmode`, `write`, `read`, `gpio`, and `pwm` are the primary interface to this layer.
   - This creates a direct command-to-hardware path with minimal abstraction, appropriate for constrained MCU resources.

8. **Command interpreter behavior**
   - Commands are case-insensitive and include both utility-style and system-style operations such as `info`, `uptime`, `uname`, `dmesg`, `df`, `free`, `whoami`, `clear`, `reboot`, `alias`, and `slots`.
   - `sh` suggests a simple script execution or command chaining capability inside the same interpreter rather than a separate shell process.
   - `alias` implies command-name indirection stored in firmware state, reinforcing the shell-like UX.

9. **State and persistence**
   - The system is deliberately ephemeral: RAM holds filesystem entries, command state, and runtime metadata.
   - There is no persistence layer in the current architecture, so `reboot` effectively clears user data.
   - The README’s planned EEPROM support would be the likely future boundary for persistence, but it is not part of the current design.

10. **Resource constraints as architectural drivers**
    - The MCU environment drives the design: tiny memory footprint, short names, low file count, and small file contents.
    - Commands like `df`, `free`, and `slots` expose internal capacity limits to the user, which is typical for embedded systems where resource visibility matters.

11. **Boot and lifecycle**
    - Startup likely initializes Serial, constructs the in-memory filesystem, seeds default directories, and registers special device nodes.
    - After initialization, the firmware enters a loop that waits for serial input and dispatches commands continuously.

12. **External dependencies and tooling**
    - The only material runtime dependency is the Arduino core libraries and the UNO hardware platform.
    - The repository does not indicate additional libraries, networking, or cloud integration.
    - Screenshots are documentation only; they do not affect runtime architecture.

13. **How to draw the diagram**
    - A good architecture diagram would show:
      - **Serial terminal** on the left as the user entry point.
      - **Command parser / shell** in the center.
      - Two internal targets beneath it: **RAM filesystem** and **GPIO/hardware interface**.
      - A special arrow from filesystem entries like `/dev/pin2` to the GPIO layer.
      - The **Arduino UNO hardware** as the execution platform and final hardware boundary.

14. **Key takeaway**
    - KernelUNO is a compact embedded shell that unifies text commands, a RAM-backed Unix-like filesystem, and direct pin control in one firmware image, with Serial as the sole user interface.

Main entry points: [`KernelUNO.ino`](https://github.com/arc1011/kerneluno/blob/main/KernelUNO.ino) (KernelUNO.ino)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Interface"]
  node_n1(("Serial terminal<br/>terminal I/O"))
end

subgraph group_g2["Firmware"]
  node_n2["KernelUNO.ino<br/>firmware entry<br/>[KernelUNO.ino]"]
  node_n3{{"Boot init<br/>startup setup"}}
  node_n4["Input buffer<br/>line buffer"]
  node_n5["Shell parser<br/>command parser"]
  node_n6["Dispatcher<br/>command router"]
  node_n7["Built-ins<br/>shell commands"]
  node_n8[("Runtime state<br/>volatile state")]
end

subgraph group_g3["Storage"]
  node_n9[("RAM filesystem<br/>virtual fs")]
  node_n10["Root tree<br/>dir layout"]
  node_n11["Device nodes<br/>special files"]
  node_n12{{"File limits<br/>capacity rules"}}
end

subgraph group_g4["Hardware"]
  node_n13["GPIO layer<br/>pin control"]
  node_n14["Arduino APIs<br/>core APIs"]
  node_n15{{"UNO hardware<br/>target board"}}
end

node_n1 -->|"serial input"| node_n4
node_n1 -->|"console I/O"| node_n2
node_n2 -->|"start"| node_n3
node_n3 -->|"seed fs"| node_n9
node_n3 -->|"register devices"| node_n11
node_n4 -->|"line ready"| node_n5
node_n5 -->|"parsed cmd"| node_n6
node_n6 -->|"invoke"| node_n7
node_n7 -->|"update"| node_n8
node_n7 -->|"fs ops"| node_n9
node_n9 -->|"contains"| node_n10
node_n9 -->|"enforce"| node_n12
node_n9 -->|"special entries"| node_n11
node_n11 -->|"maps to"| node_n13
node_n6 -->|"gpio cmds"| node_n13
node_n13 -->|"use"| node_n14
node_n14 -->|"runs on"| node_n15
node_n15 -.->|"physical pins"| node_n13

click node_n2 "https://github.com/arc1011/kerneluno/blob/main/KernelUNO.ino"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1 toneBlue
class node_n2,node_n3,node_n4,node_n5,node_n6,node_n7,node_n8 toneAmber
class node_n9,node_n10,node_n11,node_n12 toneMint
class node_n13,node_n14,node_n15 toneRose
```

## Components

### Interface

Serial terminal I/O boundary

- **Serial terminal**: terminal I/O · User entry and output channel over Serial

### Firmware

Core shell and runtime logic

- [KernelUNO.ino](https://github.com/arc1011/kerneluno/blob/main/KernelUNO.ino): firmware entry · Single Arduino sketch containing the firmware · `KernelUNO.ino`
- **Boot init**: startup setup · Initializes Serial, seeds directories, and registers device nodes
- **Input buffer**: line buffer · Collects serial bytes and frames commands line by line
- **Shell parser**: command parser · Parses case-insensitive shell commands and arguments
- **Dispatcher**: command router · Routes parsed commands to filesystem, GPIO, and system actions
- **Built-ins**: shell commands · Info, uptime, ls, cd, mkdir, rm, read/write, reboot, alias, and similar commands
- **Runtime state**: volatile state · Current directory, aliases, and live shell metadata held in RAM

### Storage

In-memory virtual filesystem

- **RAM filesystem**: virtual fs · Small volatile filesystem with path navigation and file operations
- **Root tree**: dir layout · Default /home and /dev structure created on boot
- **Device nodes**: special files · /dev/pin2, /dev/pin3, and /dev/pin4 mapped to hardware control
- **File limits**: capacity rules · Enforces tiny RAM-backed limits for entries, sizes, and names

### Hardware

Arduino UNO and GPIO boundary

- **GPIO layer**: pin control · Implements pinMode, digitalWrite, digitalRead, and analogWrite behavior
- **Arduino APIs**: core APIs · Native Arduino functions used to control pins and timing
- **UNO hardware**: target board · Execution platform and physical MCU boundary

## Connections

- Serial terminal → Input buffer: serial input · Characters arrive from the terminal and are buffered
- Serial terminal → KernelUNO.ino: console I/O · Firmware prints prompts, results, and errors back to Serial
- KernelUNO.ino → Boot init: start · Sketch entry performs one-time startup setup
- Boot init → RAM filesystem: seed fs · Boot creates the in-memory filesystem structure
- Boot init → Device nodes: register devices · Boot adds special /dev nodes for pin access
- Input buffer → Shell parser: line ready · Buffered input is handed to the parser
- Shell parser → Dispatcher: parsed cmd · Parsed commands are dispatched to subsystems
- Dispatcher → Built-ins: invoke · Dispatcher executes shell built-ins and system commands
- Built-ins → Runtime state: update · Commands read and mutate live shell state
- Built-ins → RAM filesystem: fs ops · Commands perform path-aware file and directory actions
- RAM filesystem → Root tree: contains · Filesystem exposes the root directory layout
- RAM filesystem → File limits: enforce · Filesystem applies tiny capacity constraints
- RAM filesystem → Device nodes: special entries · Device files live inside the virtual tree
- Device nodes → GPIO layer: maps to · Reading or writing device nodes controls pins
- Dispatcher → GPIO layer: gpio cmds · Pin and PWM commands route to the GPIO layer
- GPIO layer → Arduino APIs: use · GPIO layer calls native Arduino APIs
- Arduino APIs → UNO hardware: runs on · APIs drive the underlying UNO board
- UNO hardware → GPIO layer: physical pins · Hardware boundary where GPIO effects are realized