rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 13:02:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Feature/soccer scroll support (#186)

Browse Source 
* fix: Use plugin.modes instead of manifest.json for available modes

- Display controller now checks plugin_instance.modes first before falling back to manifest
- This allows plugins to dynamically provide modes based on enabled leagues
- Fixes issue where disabled leagues (WNBA, NCAAW) appeared in available modes
- Plugins can now control their available modes at runtime based on config

* 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

* debug(display): Change FPS check logging from debug to info level

- Change FPS check log from DEBUG to INFO to help diagnose scrolling FPS issues
- Add active_mode to log message for clarity
- Helps identify if plugins are being detected for high-FPS mode

* debug(display): Add logging for display_interval in both FPS loops

- Log display_interval when entering high-FPS and normal loops
- Shows expected FPS for high-FPS mode
- Helps diagnose why news ticker shows 50 FPS despite high-FPS detection

* feat: Update soccer-scoreboard submodule with scroll display support

- Submodule now includes full feature parity with football-scoreboard
- Granular display modes for 8 leagues (24 total modes)
- Scroll display mode with game_renderer.py and scroll_display.py
- League registry system with enabled state filtering
- Modernized config_schema.json with per-league scroll settings
- League-aware logo caching to prevent collisions
- Pillow 8.x compatibility for image resampling

Submodule branch: feature/football-feature-parity
Commit: e22a16d

* style(web): Update plugin button colors and reorganize documentation

- Change update button color to yellow-600 in installed plugins section to match plugin config page
- Change refresh plugins button color to blue-600 to match restart display button
- Move DEVELOPMENT.md and MIGRATION_GUIDE.md from root to docs/ directory
- Remove IMPACT_EXPLANATION.md and MERGE_CONFLICT_RESOLUTION_PLAN.md

---------

Co-authored-by: Chuck <chuck@example.com>
This commit is contained in:
Chuck
2026-01-13 13:33:53 -05:00
committed by GitHub
parent fdf09fabd2
commit 4a63ff87cb
7 changed files with 3 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
docs/DEVELOPMENT.md Normal file
View File

@@ -0,0 +1,159 @@
# Development Guide
This guide provides information for developers and contributors working on the LEDMatrix project.
## Git Submodules
### rpi-rgb-led-matrix-master Submodule
The `rpi-rgb-led-matrix-master` submodule is a foundational dependency located at the repository root (not in `plugins/`). This submodule provides the core hardware abstraction layer for controlling RGB LED matrices via the Raspberry Pi GPIO pins.
#### Architectural Rationale
**Why at the root?**
- **Core Dependency**: Unlike plugins in the `plugins/` directory, `rpi-rgb-led-matrix-master` is a foundational library required by the core LEDMatrix system, not an optional plugin
- **System-Level Integration**: The `rgbmatrix` Python module (built from this submodule) is imported by `src/display_manager.py`, which is part of the core display system
- **Build Requirements**: The submodule must be compiled to create the `rgbmatrix` Python bindings before the system can run
- **Separation of Concerns**: Keeping core dependencies at the root level separates them from user-installable plugins, maintaining a clear architectural distinction
**Why not in `plugins/`?**
- Plugins are optional, user-installable modules that depend on the core system
- `rpi-rgb-led-matrix-master` is a required build dependency, not an optional plugin
- The core system cannot function without this dependency
#### Initializing the Submodule
When cloning the repository, you must initialize the submodule:
**First-time clone (recommended):**
```bash
git clone --recurse-submodules https://github.com/ChuckBuilds/LEDMatrix.git
cd LEDMatrix
```
**If you already cloned without submodules:**
```bash
git submodule update --init --recursive
```
**To initialize only the rpi-rgb-led-matrix-master submodule:**
```bash
git submodule update --init --recursive rpi-rgb-led-matrix-master
```
#### Building the Submodule
After initializing the submodule, you need to build the Python bindings:
```bash
cd rpi-rgb-led-matrix-master
make build-python
cd bindings/python
python3 -m pip install --break-system-packages .
```
**Note:** The `first_time_install.sh` script automates this process during installation.
#### Troubleshooting
**Submodule appears empty:**
If the `rpi-rgb-led-matrix-master` directory exists but is empty or lacks a `Makefile`:
```bash
# Remove the empty directory
rm -rf rpi-rgb-led-matrix-master
# Re-initialize the submodule
git submodule update --init --recursive rpi-rgb-led-matrix-master
```
**Build fails:**
Ensure you have the required build dependencies installed:
```bash
sudo apt install -y build-essential python3-dev cython3 scons
```
**Import error for `rgbmatrix` module:**
- Verify the submodule is initialized: `ls rpi-rgb-led-matrix-master/Makefile`
- Ensure the Python bindings are built and installed (see "Building the Submodule" above)
- Check that the module is installed: `python3 -c "from rgbmatrix import RGBMatrix; print('OK')"`
**Submodule out of sync:**
If the submodule commit doesn't match what the main repository expects:
```bash
git submodule update --remote rpi-rgb-led-matrix-master
```
#### CI/CD Configuration
When setting up CI/CD pipelines, ensure submodules are initialized before building:
**GitHub Actions Example:**
```yaml
- name: Checkout repository
uses: actions/checkout@v3
with:
submodules: recursive
- name: Build rpi-rgb-led-matrix
run: |
cd rpi-rgb-led-matrix-master
make build-python
cd bindings/python
pip install .
```
**GitLab CI Example:**
```yaml
variables:
GIT_SUBMODULE_STRATEGY: recursive
build:
script:
- cd rpi-rgb-led-matrix-master
- make build-python
- cd bindings/python
- pip install .
```
**Jenkins Example:**
```groovy
stage('Checkout') {
checkout([
$class: 'GitSCM',
branches: [[name: '*/main']],
doGenerateSubmoduleConfigurations: false,
extensions: [[$class: 'SubmoduleOption',
disableSubmodules: false,
parentCredentials: true,
recursiveSubmodules: true,
reference: '',
trackingSubmodules: false]],
userRemoteConfigs: [[url: 'https://github.com/ChuckBuilds/LEDMatrix.git']]
])
}
```
**General CI/CD Checklist:**
- ✓ Use `--recurse-submodules` flag when cloning (or equivalent in your CI system)
- ✓ Initialize submodules before any build steps
- ✓ Build the Python bindings if your tests require the `rgbmatrix` module
- ✓ Note: Emulator mode (using `RGBMatrixEmulator`) doesn't require the submodule to be built
---
## Plugin Submodules
Plugin submodules are located in the `plugins/` directory and are managed similarly:
**Initialize all plugin submodules:**
```bash
git submodule update --init --recursive plugins/
```
**Initialize a specific plugin:**
```bash
git submodule update --init --recursive plugins/hockey-scoreboard
```
For more information about plugins, see the [Plugin Development Guide](.cursor/plugins_guide.md) and [Plugin Architecture Specification](docs/PLUGIN_ARCHITECTURE_SPEC.md).

95
docs/MIGRATION_GUIDE.md Normal file
View File

@@ -0,0 +1,95 @@
# Migration Guide
This guide helps you migrate from older versions of LEDMatrix to the latest version.
## Breaking Changes
### Script Path Reorganization
Scripts have been reorganized into subdirectories for better organization. **If you have automation, cron jobs, or custom tooling that references old script paths, you must update them.**
#### Installation Scripts
All installation scripts have been moved from the project root to `scripts/install/`:
| Old Path | New Path |
|----------|----------|
| `install_service.sh` | `scripts/install/install_service.sh` |
| `install_web_service.sh` | `scripts/install/install_web_service.sh` |
| `install_wifi_monitor.sh` | `scripts/install/install_wifi_monitor.sh` |
| `setup_cache.sh` | `scripts/install/setup_cache.sh` |
| `configure_web_sudo.sh` | `scripts/install/configure_web_sudo.sh` |
| `migrate_config.sh` | `scripts/install/migrate_config.sh` |
#### Permission Fix Scripts
All permission fix scripts have been moved to `scripts/fix_perms/`:
| Old Path | New Path |
|----------|----------|
| `fix_assets_permissions.sh` | `scripts/fix_perms/fix_assets_permissions.sh` |
| `fix_cache_permissions.sh` | `scripts/fix_perms/fix_cache_permissions.sh` |
| `fix_plugin_permissions.sh` | `scripts/fix_perms/fix_plugin_permissions.sh` |
| `fix_web_permissions.sh` | `scripts/fix_perms/fix_web_permissions.sh` |
#### Action Required
1. **Update cron jobs**: If you have any cron jobs that call these scripts, update the paths.
2. **Update automation scripts**: Any custom scripts or automation that references the old paths must be updated.
3. **Update documentation**: Update any internal documentation or runbooks that reference these scripts.
#### Example Updates
**Before:**
```bash
# Old cron job or script
0 2 * * * /path/to/LEDMatrix/fix_cache_permissions.sh
sudo ./install_service.sh
```
**After:**
```bash
# Updated paths
0 2 * * * /path/to/LEDMatrix/scripts/fix_perms/fix_cache_permissions.sh
sudo ./scripts/install/install_service.sh
```
#### Verification
After updating your scripts, verify they still work:
```bash
# Test installation scripts (if needed)
ls scripts/install/*.sh
sudo ./scripts/install/install_service.sh --help
# Test permission scripts
ls scripts/fix_perms/*.sh
sudo ./scripts/fix_perms/fix_cache_permissions.sh
```
---
## Other Changes
### Configuration File Location
No changes to configuration file locations. The configuration system remains backward compatible.
### Plugin System
The plugin system has been enhanced but remains backward compatible with existing plugins.
---
## Getting Help
If you encounter issues during migration:
1. Check the [README.md](README.md) for current installation and usage instructions
2. Review script README files:
- `scripts/install/README.md` - Installation scripts documentation
- `scripts/fix_perms/README.md` (if exists) - Permission scripts documentation
3. Check system logs: `journalctl -u ledmatrix -f` or `journalctl -u ledmatrix-web -f`
4. Review the troubleshooting section in the main README