sneak/hdmistat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
hdmistat/DESIGN.md
sneak 402c0797d5 Initial implementation of hdmistat - Linux framebuffer system stats display 
Features:
- Beautiful system statistics display using IBM Plex Mono font
- Direct framebuffer rendering without X11/Wayland
- Multiple screens with automatic carousel rotation
- Real-time system monitoring (CPU, memory, disk, network, processes)
- Systemd service integration with install command
- Clean architecture using uber/fx dependency injection

Architecture:
- Cobra CLI with daemon, install, status, and info commands
- Modular design with separate packages for display, rendering, and stats
- Font embedding for zero runtime dependencies
- Layout API for clean text rendering
- Support for multiple screen types (overview, top CPU, top memory)

Technical details:
- Uses gopsutil for cross-platform system stats collection
- Direct Linux framebuffer access via memory mapping
- Anti-aliased text rendering with freetype
- Configurable screen rotation and update intervals
- Structured logging with slog
- Comprehensive test coverage and linting setup

This initial version provides a solid foundation for displaying rich
system information on resource-constrained devices like Raspberry Pis.
2025-07-23 12:55:42 +02:00

3.2 KiB
Raw Permalink Blame History

hdmistat Design Document

Overview

hdmistat is a golang daemon that displays system statistics on Linux framebuffers using beautiful bitmap graphics rendered with the IBM Plex Mono font in ultralight weight. It's designed for resource-constrained systems like Raspberry Pis that don't run X11 or Wayland.

Architecture

Core Components

  1. Display Package (internal/display)

    • Interfaces with Linux framebuffer devices
    • Handles raw image display
    • Manages framebuffer memory mapping

  2. Layout Package (internal/layout)

    • Provides simple text rendering API
    • Handles font rendering with IBM Plex Mono ultralight
    • Offers drawing primitives for creating clean layouts
    • Abstracts away complex image manipulation

  3. Stat Collector Package (internal/statcollector)

    • Collects system information (CPU, memory, disk, network, processes)
    • Returns structured data for rendering
    • Uses gopsutil for cross-platform system stats

  4. Renderer Package (internal/renderer)

    • Converts system stats to images using the layout API
    • Manages different screen types
    • Handles screen-specific rendering logic

  5. Carousel System (internal/app)

    • Manages multiple screens
    • Handles automatic screen rotation
    • Coordinates between collectors, renderers, and display

Dependency Injection

Uses uber/fx for dependency injection to:

  • Wire together components automatically
  • Manage component lifecycle
  • Enable clean separation of concerns
  • Facilitate testing and modularity

CLI Structure

Uses cobra for command handling:

  • hdmistat daemon - Main daemon that takes over framebuffer
  • hdmistat install - Installs systemd unit files and enables the service
  • hdmistat status - Shows current daemon status
  • hdmistat info - Displays system information in terminal

Screen Types

  1. Overview Screen - Shows:

    • Hostname
    • Memory usage
    • CPU usage
    • Temperatures
    • Disk usage
    • Network interface status (link speeds, IPs, current speeds)

  2. Configurable Detail Screens:

    • Top processes by memory
    • Top processes by CPU
    • Largest files
    • Network traffic details
    • Custom user-defined screens

Configuration

  • YAML-based configuration file
  • Specifies which screens to show
  • Screen rotation timing
  • Custom screen definitions
  • Font size and layout preferences

Logging

  • Uses log/slog for structured logging
  • Different log levels for debugging
  • Logs to systemd journal when running as service

Font Rendering

  • IBM Plex Mono font in ultralight weight
  • Embedded in binary for zero dependencies
  • Anti-aliased rendering for crisp text
  • Configurable sizes

Communication

Components communicate via interfaces:

  • Display - Show images on framebuffer
  • Collector - Gather system information
  • Renderer - Convert data to images
  • Screen - Define what to display
  • Layout - Text and graphics rendering

Implementation Notes

  • All types defined in their respective packages (no separate types package)
  • Graceful shutdown handling
  • Error recovery to prevent framebuffer corruption
  • Efficient memory usage for resource-constrained systems
  • No external font dependencies (embedded assets)