How arc1011/kerneluno works
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 KernelUNO.ino
Components 15
Interface
Serial terminal I/O boundary
- Serial terminal · User entry and output channel over Serial
Firmware
Core shell and runtime logic
- KernelUNO.ino · Single Arduino sketch containing the firmware
KernelUNO.ino - Boot init · Initializes Serial, seeds directories, and registers device nodes
- Input buffer · Collects serial bytes and frames commands line by line
- Shell parser · Parses case-insensitive shell commands and arguments
- Dispatcher · Routes parsed commands to filesystem, GPIO, and system actions
- Built-ins · Info, uptime, ls, cd, mkdir, rm, read/write, reboot, alias, and similar commands
- Runtime state · Current directory, aliases, and live shell metadata held in RAM
Storage
In-memory virtual filesystem
- RAM filesystem · Small volatile filesystem with path navigation and file operations
- Root tree · Default /home and /dev structure created on boot
- Device nodes · /dev/pin2, /dev/pin3, and /dev/pin4 mapped to hardware control
- File limits · Enforces tiny RAM-backed limits for entries, sizes, and names
Hardware
Arduino UNO and GPIO boundary
- GPIO layer · Implements pinMode, digitalWrite, digitalRead, and analogWrite behavior
- Arduino APIs · Native Arduino functions used to control pins and timing
- UNO hardware · Execution platform and physical MCU boundary
Connections 18
- 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