How whinee/whiskerframe works
WhiskerFrame is a Raspberry Pi cyberdeck with an ESP32 display coprocessor. Its principal workflow accepts CardKB input, authenticates a user, runs shell sessions in PTYs, interprets terminal output into a character grid, and sends display commands over UART to the CYD firmware. Supporting branches provide battery monitoring, storage mounting, health checks, and shared display-command utilities. The README establishes the hardware pairing; source-index references and excerpts support the shown module links. Several subsystem internals were not sampled, so their unverified connections are omitted.
Main entry points: bridge.py Terminal Bridge · daemon.py Battery Daemon · login_view.py Login View · grid.py Character Grid
Components 31
Terminal Sessions
- CardKB Input
pi/cardkb/reader.py - Terminal Daemon
pi/terminal/daemon.py - Terminal Bridge
pi/terminal/bridge.py - Login Gate
pi/terminal/login.py - Login View
pi/terminal/login_view.py - Shell Workspaces
pi/terminal/workspaces.py - VT Emulator
pi/terminal/vt.py - Character Grid
pi/terminal/grid.py - Terminal Status Bar
pi/terminal/status_bar.py - Terminal Theme
pi/terminal/theme.py
Display Link
- Serial Transport
whiskerframe/transport.py - Wire Protocol
whiskerframe/protocol.py - CYD Firmware
firmware/cyd_display_link/main.cpp - Frame Decoder
firmware/cyd_display_link/frame.h - Display Renderer
firmware/cyd_display_link/render.h
Power Monitoring
- Battery Daemon
pi/battery_monitor/daemon.py - INA219 Driver
pi/battery_monitor/ina219.py - Power Supply Reader
pi/battery_monitor/power_supply.py - Battery State
pi/battery_monitor/battery.py
Device Services
- Storage Mounting
pi/storage/install_mount.py - Health Check
pi/komodo/healthcheck.py - Configuration
scripts/config.py
Display Utilities
- Command Models
whiskerframe/models.py - Terminal Geometry
whiskerframe/terminal.py - Font Metrics
whiskerframe/metrics.py - Host Preview
whiskerframe/preview.py
Other components
- Cyberdeck User
- Login Shell
- UART Display
- Battery Sensor
- Linux Power Supply
Connections 35
- Cyberdeck User → CardKB Input: enters keys
- Terminal Daemon → CardKB Input: reads input
pi/terminal/daemon.py - Terminal Daemon → Terminal Bridge: starts bridge
pi/terminal/daemon.py - Terminal Bridge → Login Gate: authenticates
pi/terminal/bridge.py - Terminal Bridge → Login View: renders gate
pi/terminal/bridge.py - Terminal Bridge → Shell Workspaces: manages sessions
pi/terminal/bridge.py - Shell Workspaces → Login Shell: spawns PTYs
pi/terminal/workspaces.py - Terminal Bridge → VT Emulator: parses output
pi/terminal/bridge.py - VT Emulator → Character Grid: updates cells
pi/terminal/vt.py - Terminal Bridge → Character Grid: renders grid
pi/terminal/bridge.py - Terminal Bridge → Terminal Status Bar: updates status
pi/terminal/bridge.py - Terminal Bridge → Terminal Theme: uses palette
pi/terminal/bridge.py - Terminal Bridge → Serial Transport: sends frames
pi/terminal/bridge.py - Serial Transport → Wire Protocol: serializes commands
whiskerframe/transport.py - Serial Transport → UART Display: transmits bytes
- UART Display → CYD Firmware: receives frames
- CYD Firmware → Frame Decoder: decodes frames
firmware/cyd_display_link/main.cpp - CYD Firmware → Display Renderer: renders commands
firmware/cyd_display_link/main.cpp - Battery Daemon → INA219 Driver: reads measurements
pi/battery_monitor/daemon.py - Battery Daemon → Power Supply Reader: reads supply
pi/battery_monitor/daemon.py - Battery Daemon → Battery State: derives state
pi/battery_monitor/daemon.py - INA219 Driver → Battery Sensor: samples
- Power Supply Reader → Linux Power Supply: reads kernel data
- Battery Daemon → Configuration: loads settings
pi/battery_monitor/daemon.py - Storage Mounting → Configuration: loads settings
pi/storage/install_mount.py - Login View → Character Grid: draws screen
pi/terminal/login_view.py - Login View → Login Gate: uses login state
pi/terminal/login_view.py - Login View → Terminal Theme: uses palette
pi/terminal/login_view.py - Terminal Status Bar → Character Grid: draws status
pi/terminal/status_bar.py - VT Emulator → Terminal Theme: maps SGR colors
pi/terminal/vt.py - Wire Protocol → Command Models: encodes models
whiskerframe/protocol.py - Terminal Geometry → Font Metrics: uses metrics
whiskerframe/terminal.py - Command Models → Font Metrics: sizes text
whiskerframe/models.py - Host Preview → Command Models: renders commands
whiskerframe/preview.py - Host Preview → Terminal Geometry: renders terminal
whiskerframe/preview.py