mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 13:02:59 +00:00

Files

Chuck 1833e30c1d Feature/wifi setup improvements (#187 )

* fix: Handle permission errors when removing plugin directories

- Added _safe_remove_directory() method to handle permission errors gracefully
- Fixes permissions on __pycache__ directories before removal
- Updates uninstall_plugin() and install methods to use safe removal
- Resolves [Errno 13] Permission denied errors during plugin install/uninstall

* feat(wifi): Add grace period for AP mode and improve setup documentation

- Add 90-second grace period (3 checks at 30s intervals) before enabling AP mode
- Change AP to open network (no password) for easier initial setup
- Add verification script for WiFi setup
- Update documentation with grace period details and open network info
- Improve WiFi monitor daemon logging and error handling

* feat(wifi): Add Trixie compatibility and dynamic interface discovery

- Add dynamic WiFi interface discovery instead of hardcoded wlan0
  - Supports traditional (wlan0), predictable (wlp2s0), and USB naming
  - Falls back gracefully if detection fails

- Add Raspberry Pi OS Trixie (Debian 13) detection and compatibility
  - Detect Netplan configuration and connection file locations
  - Disable PMF (Protected Management Frames) on Trixie for better
    client compatibility with certain WiFi adapters

- Improve nmcli hotspot setup for Trixie
  - Add explicit IP configuration (192.168.4.1/24)
  - Add channel configuration to hotspot creation
  - Handle Trixie's default 10.42.0.1 IP override

- Add dnsmasq conflict detection
  - Warn if Pi-hole or other DNS services are using dnsmasq
  - Create backup before overwriting config

- Improve error handling
  - Replace bare except clauses with specific exceptions
  - All subprocess calls now have explicit timeouts

- Document sudoers requirements in module docstring
  - List all required NOPASSWD entries for ledpi user

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor(wifi): Use NM_CONNECTIONS_PATHS constant in _detect_trixie

Replace hardcoded Path instances with references to the
NM_CONNECTIONS_PATHS constant for consistency.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(verify): Use ETH_CONNECTED and AP_ACTIVE in summary output

Add connectivity summary section that displays Ethernet and AP mode
status using the previously unused ETH_CONNECTED and AP_ACTIVE flags.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Chuck <chuck@example.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-19 16:43:02 -05:00

README.md

LEDMatrix Documentation

Welcome to the LEDMatrix documentation! This directory contains comprehensive guides, specifications, and reference materials for the LEDMatrix project.

📚 Documentation Overview

This documentation has been consolidated and organized to reduce redundancy while maintaining comprehensive coverage. Recent improvements include complete API references, enhanced plugin development guides, and better organization for both end users and developers.

📖 Quick Start

For New Users

Installation: Follow the main README.md in the project root
First Setup: Run first_time_install.sh for initial configuration
Basic Usage: See TROUBLESHOOTING_QUICK_START.md for common issues

For Developers

Plugin System: Read PLUGIN_QUICK_REFERENCE.md for an overview
Plugin Development: See PLUGIN_DEVELOPMENT_GUIDE.md for development workflow
API Reference: Check PLUGIN_API_REFERENCE.md for available methods
Configuration: Check PLUGIN_CONFIGURATION_GUIDE.md

For API Integration

REST API: See API_REFERENCE.md for all web interface endpoints
Plugin API: See PLUGIN_API_REFERENCE.md for plugin developer APIs
Quick Reference: See DEVELOPER_QUICK_REFERENCE.md for common tasks

📋 Documentation Categories

🚀 Getting Started & Setup

EMULATOR_SETUP_GUIDE.md - Set up development environment with emulator
TRIXIE_UPGRADE_GUIDE.md - Upgrade to Raspbian OS 13 "Trixie"
TROUBLESHOOTING_QUICK_START.md - Common issues and solutions

🏗️ Architecture & Design

PLUGIN_ARCHITECTURE_SPEC.md - Complete plugin system specification
PLUGIN_IMPLEMENTATION_SUMMARY.md - Plugin system implementation details
FEATURE_IMPLEMENTATION_SUMMARY.md - Major feature implementations
NESTED_CONFIG_SCHEMAS.md - Configuration schema design
NESTED_SCHEMA_IMPLEMENTATION.md - Schema implementation details
NESTED_SCHEMA_VISUAL_COMPARISON.md - Schema comparison visuals

⚙️ Configuration & Management

PLUGIN_CONFIGURATION_GUIDE.md - Complete plugin configuration guide
PLUGIN_CONFIGURATION_TABS.md - Configuration tabs feature
PLUGIN_CONFIG_QUICK_START.md - Quick configuration guide

🔌 Plugin Development

PLUGIN_DEVELOPMENT_GUIDE.md - Complete plugin development guide
PLUGIN_QUICK_REFERENCE.md - Plugin development quick reference
PLUGIN_API_REFERENCE.md - Complete API reference for plugin developers
ADVANCED_PLUGIN_DEVELOPMENT.md - Advanced patterns and examples
PLUGIN_REGISTRY_SETUP_GUIDE.md - Setting up plugin registry
PLUGIN_DEPENDENCY_GUIDE.md - Managing plugin dependencies
PLUGIN_DEPENDENCY_TROUBLESHOOTING.md - Dependency troubleshooting

🎮 Plugin Features

ON_DEMAND_DISPLAY_QUICK_START.md - Manual display triggering
PLUGIN_LIVE_PRIORITY_QUICK_START.md - Live content priority
PLUGIN_LIVE_PRIORITY_API.md - Live priority API reference
PLUGIN_CUSTOM_ICONS_FEATURE.md - Custom plugin icons
PLUGIN_DISPATCH_IMPLEMENTATION.md - Plugin dispatch system
PLUGIN_TABS_FEATURE_COMPLETE.md - Plugin tabs feature

📡 API Reference

API_REFERENCE.md - Complete REST API documentation for web interface
PLUGIN_API_REFERENCE.md - Plugin developer API reference (Display Manager, Cache Manager, Plugin Manager)
DEVELOPER_QUICK_REFERENCE.md - Quick reference for common developer tasks
ON_DEMAND_DISPLAY_API.md - On-demand display API reference

🛠️ Development & Tools

BACKGROUND_SERVICE_README.md - Background service architecture
FONT_MANAGER_USAGE.md - Font management system

🔍 Analysis & Compatibility

RASPBIAN_TRIXIE_COMPATIBILITY_ANALYSIS.md - Detailed Trixie compatibility analysis
CONFIGURATION_CLEANUP_SUMMARY.md - Configuration cleanup details
football_plugin_comparison.md - Football plugin analysis

📊 Utility & Scripts

README_broadcast_logo_analyzer.md - Broadcast logo analysis tool
README_soccer_logos.md - Soccer logo management
WEB_INTERFACE_TROUBLESHOOTING.md - Web interface troubleshooting

🔄 Migration & Updates

Recent Consolidations (October 2025)

Implementation Summaries: Consolidated 7 separate implementation summaries into 2 comprehensive guides:
- FEATURE_IMPLEMENTATION_SUMMARY.md (AP Top 25, Plugin System, Configuration, Web Interface, Trixie Compatibility)
- PLUGIN_IMPLEMENTATION_SUMMARY.md (Plugin system technical details)
Trixie Documentation: Merged 4 Trixie-related documents into TRIXIE_UPGRADE_GUIDE.md
Removed Redundancy: Eliminated duplicate documents and outdated debug guides
Total Reduction: 53 → 39 documents (26% reduction)

Migration Notes

Old implementation summary documents have been consolidated
Trixie upgrade information is now centralized in one guide
Deprecated manager documentation has been removed (no longer applicable)
Very specific debug documents have been archived or removed

🎯 Key Resources by Use Case

I'm new to LEDMatrix

Main README - Installation and setup
EMULATOR_SETUP_GUIDE.md - Development environment
PLUGIN_QUICK_REFERENCE.md - Understanding the system

I want to create a plugin

PLUGIN_DEVELOPMENT_GUIDE.md - Complete development guide
PLUGIN_API_REFERENCE.md - Available methods and APIs
ADVANCED_PLUGIN_DEVELOPMENT.md - Advanced patterns and examples
PLUGIN_CONFIGURATION_GUIDE.md - Configuration setup
PLUGIN_ARCHITECTURE_SPEC.md - Complete specification

📝 Contributing to Documentation

Documentation Standards

Use Markdown format with consistent headers
Include code examples where helpful
Provide both quick start and detailed reference sections
Keep implementation summaries focused on what was built, not how to use

Adding New Documentation

Place in appropriate category (see sections above)
Update this README.md with the new document
Follow naming conventions (FEATURE_NAME.md)
Consider if content should be consolidated with existing docs

Consolidation Guidelines

Implementation Summaries: Consolidate into feature-specific summaries
Quick References: Keep if they provide unique value, otherwise merge
Debug Documents: Remove after issues are resolved
Migration Guides: Consolidate when migrations are complete

Main Project README - Installation and basic usage
Web Interface README - Web interface details
LEDMatrix Wiki - Extended documentation and guides
GitHub Issues - Bug reports and feature requests
GitHub Discussions - Community support

📊 Documentation Statistics

Total Documents: ~35 (after consolidation)
Categories: 8 major sections (including new API Reference section)
Primary Languages: English
Format: Markdown (.md)
Last Update: December 2025
Coverage: Installation, development, troubleshooting, architecture, API references

Recent Improvements (December 2025)

✅ Complete REST API documentation (50+ endpoints)
✅ Complete Plugin API reference (Display Manager, Cache Manager, Plugin Manager)
✅ Advanced plugin development guide with examples
✅ Consolidated plugin configuration documentation
✅ Developer quick reference guide
✅ Better organization for end users and developers

This documentation index was last updated: December 2025

For questions or suggestions about the documentation, please open an issue or start a discussion on GitHub.