LED Matrix Stats Boards

A clean architecture C++ application for Raspberry Pi LED matrix displays. Shows real-time statistics from YouTube and Spotify, plus audio level monitoring.

Features

• dB Meter: Interactive audio level monitoring with visual indicators and real-time input
• YouTube Stats: Channel subscriber count, views, and video count
• Spotify Stats: Artist popularity, albums, and top tracks
• Interactive Input: Real-time numeric input for dB values (0-120)
• Clean Architecture: Modular, testable, and maintainable code

Quick Start

Build and Run

./build.sh -r

Build Only

./build.sh

Run Last Build

./build.sh -rl

Project Structure

Stats Boards/
├── core/                    # Core shared functionality
│   ├── network/            # Network infrastructure
│   ├── arg_parser.*        # Command line argument parsing
│   ├── blink_manager.*     # Blinking animation utilities
│   ├── border_renderer.*   # Border rendering utilities
│   ├── color_utils.*       # Color manipulation utilities
│   ├── config.*            # Application configuration
│   ├── input_handler.*     # Terminal input handling
│   ├── numeric_input_handler.* # Reusable numeric input handler
│   ├── rotating_text.*     # Text rotation utilities
│   ├── main_app.*          # Main application controller
│   └── main.cc             # Application entry point
├── features/              # Feature modules (Clean Architecture)
│   ├── db_meter/          # Audio monitoring feature
│   │   ├── domain/         # Domain layer
│   │   │   └── entities/       # Domain entities (DbColorCalculator)
│   │   └── presentation/   # Presentation layer
│   │       ├── pages/         # App controllers (DbMeterApp)
│   │       └── widgets/       # UI components (DbDisplay)
│   ├── youtube_stats/     # YouTube statistics feature
│   │   ├── data/           # Data layer
│   │   │   ├── datasources/    # API implementations
│   │   │   └── repositories/   # Repository implementations
│   │   ├── domain/         # Domain layer
│   │   │   ├── entities/       # Domain entities
│   │   │   ├── repositories/   # Repository interfaces
│   │   │   └── usecases/       # Business logic
│   │   └── presentation/   # Presentation layer
│   │       ├── pages/         # App controllers
│   │       ├── widgets/       # UI components
│   │       └── providers/     # State management
│   └── spotify_stats/     # Spotify statistics feature
│       ├── data/           # Data layer
│       ├── domain/         # Domain layer
│       └── presentation/   # Presentation layer
├── build/                 # Build artifacts (auto-created)
├── build.sh               # Main build script
├── Makefile               # Make configuration
├── CMakeLists.txt         # CMake configuration
├── API_SETUP.md           # API setup guide
└── README.md              # This file

Usage

Brightness Control

./build/led_matrix_apps -b 8    # 80% brightness
./build/led_matrix_apps -b 1    # 10% brightness (dim)
./build/led_matrix_apps -b 10   # 100% brightness (bright)

Interactive Menu

• db - dB Meter (audio level monitoring with interactive input)
• youtube - YouTube Counter (channel statistics)
• spotify - Spotify Counter (artist statistics)
• back - Return to main menu
• quit - Exit application

dB Meter Interactive Controls

When in dB Meter mode:

• Type numbers (0-120) - Set dB value directly
• Type r - Reset to default value
• Type back - Return to main menu
• Real-time feedback - See border changes as you type

API Setup (Optional)

For detailed API setup instructions, see API_SETUP.md.

Quick Setup

YouTube API:

export YOUTUBE_API_KEY="your_api_key_here"

Spotify API:

export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"

Note: API setup is optional. The dB Meter works without any API configuration.

Requirements

• Raspberry Pi with LED matrix hardware
• RGB Matrix Library
• C++11 compatible compiler
• libcurl (for API features)

Installation

1. Install RGB Matrix Library:

   git clone https://github.com/hzeller/rpi-rgb-led-matrix.git
   cd rpi-rgb-led-matrix
   make

2. Install dependencies:

   sudo apt-get install libcurl4-openssl-dev

3. Build the application:

   ./build.sh

Clean Architecture

This project follows Clean Architecture principles:

• Core: Shared functionality across features (network, input handling, utilities)
• Features: Self-contained modules with layered architecture:
  • Domain: Entities, business logic (DbColorCalculator, etc.)
  • Data: API implementations, data sources (YouTube/Spotify APIs)
  • Presentation: Controllers, UI components (Apps, Displays)
• Reusable Components: NumericInputHandler, BlinkManager, ColorUtils
• Dependency Inversion: Core components are independent and reusable
• Separation of Concerns: Each component has a single responsibility

Development

Adding New Features

1. Create feature directory: features/your_feature/
2. Add domain layer: features/your_feature/domain/
   • Entities: domain/entities/
   • Repository interfaces: domain/repositories/
   • Use cases: domain/usecases/
3. Add data layer: features/your_feature/data/
   • Datasources: data/datasources/
   • Models: data/models/
   • Repository implementations: data/repositories/
4. Add presentation layer: features/your_feature/presentation/
   • Pages (controllers): presentation/pages/
   • Widgets (UI): presentation/widgets/
   • Providers (state): presentation/providers/
5. Update build files: Add new source files to build.sh, Makefile, CMakeLists.txt
6. Update main application: Add feature to main_app.cpp

Building

• Clean build: make clean && ./build.sh
• Fast build: make fast (incremental)
• Debug build: make debug
• Run after build: ./build.sh -r
• Run last build: ./build.sh -rl

License

This project is open source and available under the MIT License.