feat(pi5): RP1 backend UI, gpio slowdown guidance, and hardware init error banner (#337)

* feat(pi5): expose RP1 backend selector, fix gpio defaults, surface init failures in web UI

- Add rp1_rio select (PIO/RIO) to Display Settings hardware config section;
  saved via /api/v3/config/main with 0-or-1 validation — previously the key
  existed in config.json but was not editable from the UI
- Update gpio_slowdown help text with per-model guidance (Pi 3: 3, Pi 4: 4,
  Pi 5: 4–5) and raise max from 5 → 10 to match full library range
- Fix gpio_slowdown Python fallback default from 2 → 3 (only affects edge case
  where the runtime config section is absent; explicit config values are unchanged)
- display_manager writes /tmp/led_matrix_hw_status.json at startup: ok/error;
  Display Settings page fetches it and shows a yellow warning banner when the
  matrix failed to initialize, including Pi 5 remediation steps
- Add GET /api/v3/hardware/status endpoint that reads the status file
- Improve fallback error log to include Pi 5 rebuild hint

Pi 3/4 users: rp1_rio=0 is set in config but silently ignored by the library
on non-RP1 hardware; all other changes are additive or tighten defaults only.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(pi5): correct gpio_slowdown guidance — Pi 5 PIO default is 1, not 4-5

The upstream library defaults gpio_slowdown to 1 for Pi 5 (IsPi4() ? 2 : 1).
In PIO mode the value is a pixel-clock divisor, so 4-5 was unnecessarily
conservative advice. Updated help text and error log to reflect the actual
range (1-3 typical for Pi 5 PIO; inverted effect in RIO mode).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(security): atomic hw-status write, narrow bare excepts, urllib3 CVE floor

- display_manager: replace open()+bare-except with tempfile.mkstemp→fsync→
  chmod(0o600)→os.replace; adds symlink guard and logs errors via logger
  instead of swallowing them silently; pull json/tempfile to module imports
- display_manager cleanup(): narrow broad `except Exception: pass` to
  (OSError, RuntimeError, ValueError, MemoryError) with debug log
- api_v3 get_hardware_status(): catch json.JSONDecodeError and PermissionError
  explicitly; log full traceback server-side; return generic "Unable to read
  hardware status" to client instead of leaking str(e)
- march-madness/requirements.txt: bump urllib3 floor 2.2.2→2.6.3 (CVE fix)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(template): apply |int filter to rp1_rio comparisons in display.html

Without |int, a string-typed value (e.g. from a hand-edited config.json)
causes both selected tests to fail and the select renders with no option
pre-selected. Matches the existing pattern used for multiplexing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

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

.gitmodules

@@ -1,3 +1,4 @@
 [submodule "rpi-rgb-led-matrix-master"]
 	path = rpi-rgb-led-matrix-master
 	url = https://github.com/hzeller/rpi-rgb-led-matrix.git
+	branch = master

config/config.template.json

@@ -112,7 +112,8 @@
             "limit_refresh_rate_hz": 100
         },
         "runtime": {
-            "gpio_slowdown": 3
+            "gpio_slowdown": 3,
+            "rp1_rio": 0
         },
         "display_durations": {},
         "use_short_date_format": true,

first_time_install.sh

@@ -271,7 +271,7 @@ apt_update
 
 # Install required system packages
 echo "Installing Python packages and dependencies..."
-apt_install python3-pip python3-venv python3-dev python3-pil python3-pil.imagetk build-essential python3-setuptools python3-wheel cython3 scons cmake ninja-build
+apt_install python3-pip python3-venv python-dev-is-python3 python3-pil python3-pil.imagetk build-essential python3-setuptools python3-wheel cmake ninja-build
 
 # Install additional system dependencies that might be needed
 echo "Installing additional system dependencies..."
@@ -821,20 +821,13 @@ else
         fi
         
         pushd "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" >/dev/null
-        echo "Building rpi-rgb-led-matrix Python bindings..."
+        echo "Installing rpi-rgb-led-matrix Python package (scikit-build-core + cmake)..."
-        # Build the library first, then Python bindings
+        echo "  Build deps required: python-dev-is-python3 cmake"
-        # The build-python target depends on the library being built
+        echo "  This compiles C++ — may take 2-5 minutes on Pi 4/5..."
-        if ! make build-python; then
-            echo "✗ Failed to build rpi-rgb-led-matrix Python bindings"
-            echo "  Make sure you have the required build tools installed:"
-            echo "  sudo apt install -y build-essential python3-dev cython3 scons"
-            popd >/dev/null
-            exit 1
-        fi
-        cd bindings/python
-        echo "Installing rpi-rgb-led-matrix Python package via pip..."
         if ! python3 -m pip install --break-system-packages .; then
             echo "✗ Failed to install rpi-rgb-led-matrix Python package"
+            echo "  Ensure build tools are installed:"
+            echo "  sudo apt install -y python-dev-is-python3 cmake build-essential"
             popd >/dev/null
             exit 1
         fi

plugin-repos/march-madness/requirements.txt

@@ -1,5 +1,5 @@
 requests>=2.33.0
-urllib3>=1.26.0
+urllib3>=2.6.3
 Pillow>=12.2.0
 pytz>=2022.1
 numpy>=1.24.0

scripts/install/install_web_service.sh

@@ -31,7 +31,8 @@ echo "Generating service file with dynamic paths..."
 WEB_SERVICE_FILE_CONTENT=$(cat <<EOF
 [Unit]
 Description=LED Matrix Web Interface Service
-After=network.target
+After=network-online.target
+Wants=network-online.target
 
 [Service]
 Type=simple

src/common/display_helper.py

@@ -235,8 +235,6 @@ class DisplayHelper:
             PIL Image with no data message
         """
         img = self.create_base_image((0, 0, 0))
-        draw = ImageDraw.Draw(img)
-        
         font = ImageFont.load_default()
         self._draw_centered_text(message, font, (0, 0, 0), (150, 150, 150))
         

src/display_controller.py

@@ -823,7 +823,7 @@ class DisplayController:
                 scroll_h = getattr(plugin_instance, 'scroll_helper', None)
                 if scroll_h is not None:
                     follower_frame = scroll_h.get_portion_at(scroll_h.scroll_position + offset)
-            except Exception:
+            except Exception:  # nosec B110 - scroll_helper.get_portion_at is optional; skip on error
                 pass
 
         # 3. Mirror fallback — static plugins (clock, weather) show same frame

src/display_manager.py

@@ -1,4 +1,6 @@
+import json
 import os
+import tempfile
 if os.getenv("EMULATOR", "false") == "true":
     from RGBMatrixEmulator import RGBMatrix, RGBMatrixOptions
 else:
@@ -58,6 +60,7 @@ class DisplayManager:
         
     def _setup_matrix(self):
         """Initialize the RGB matrix with configuration settings."""
+        _init_error_str = None
         try:
             # Allow callers (e.g., web UI) to force non-hardware fallback mode
             if getattr(self, '_force_fallback', False):
@@ -87,7 +90,7 @@ class DisplayManager:
             options.disable_hardware_pulsing = hardware_config.get('disable_hardware_pulsing', False)
             options.show_refresh_rate = hardware_config.get('show_refresh_rate', False)
             options.limit_refresh_rate_hz = hardware_config.get('limit_refresh_rate_hz', 90)
-            options.gpio_slowdown = runtime_config.get('gpio_slowdown', 2)
+            options.gpio_slowdown = runtime_config.get('gpio_slowdown', 3)
             
             # Disable internal privilege dropping - we manage this via systemd or remain root
             # This prevents the library from dropping to 'daemon' user which breaks file permissions
@@ -100,6 +103,17 @@ class DisplayManager:
                 options.pwm_dither_bits = hardware_config.get('pwm_dither_bits')
             if 'inverse_colors' in hardware_config:
                 options.inverse_colors = hardware_config.get('inverse_colors')
+            # Pi 5 only: 0=PIO/RP1 coprocessor (default, less CPU),
+            # 1=RIO/Registered IO (faster; gpio_slowdown effect is inverted in this mode)
+            if 'rp1_rio' in runtime_config:
+                if hasattr(options, 'rp1_rio'):
+                    options.rp1_rio = runtime_config.get('rp1_rio')
+                else:
+                    logger.warning(
+                        "rp1_rio is set in config but the current RGBMatrixOptions "
+                        "implementation does not support it (RGBMatrixEmulator or older "
+                        "library version) — value will be ignored"
+                    )
             
             logger.info(f"Initializing RGB Matrix with settings: rows={options.rows}, cols={options.cols}, chain_length={options.chain_length}, parallel={options.parallel}, hardware_mapping={options.hardware_mapping}")
             
@@ -130,6 +144,7 @@ class DisplayManager:
                 self._draw_test_pattern()
             
         except Exception as e:
+            _init_error_str = str(e)
             logger.error(f"Failed to initialize RGB Matrix: {e}", exc_info=True)
             # Create a fallback image for web preview using configured dimensions when available
             self.matrix = None
@@ -153,9 +168,38 @@ class DisplayManager:
             except Exception:  # nosec B110 - best-effort fallback visualization; drawing errors must not crash startup
                 # Best-effort; ignore drawing errors in fallback
                 pass
-            logger.error(f"Matrix initialization failed, using fallback mode with size {fallback_width}x{fallback_height}. Error: {e}")
+            logger.error(
+                f"Matrix initialization failed — running in fallback/simulation mode "
+                f"(size {fallback_width}x{fallback_height}). Error: {e}. "
+                "On Raspberry Pi 5: ensure rpi-rgb-led-matrix was built from the latest "
+                "submodule (re-run first_time_install.sh). gpio_slowdown of 2–3 is typical for Pi 5 PIO mode."
+            )
             # Do not raise here; allow fallback mode so web preview and non-hardware environments work
 
+        # Write hardware status file so the web UI can surface init failures
+        _hw_status = {"ok": self.matrix is not None, "error": _init_error_str}
+        _status_path = "/tmp/led_matrix_hw_status.json"  # nosec B108
+        try:
+            if os.path.islink(_status_path):
+                logger.warning("Skipping hardware status write: %s is a symlink", _status_path)
+            else:
+                _fd, _tmp_path = tempfile.mkstemp(dir="/tmp", prefix=".led_hw_")  # nosec B108
+                try:
+                    with os.fdopen(_fd, "w") as _f:
+                        json.dump(_hw_status, _f)
+                        _f.flush()
+                        os.fsync(_f.fileno())
+                    os.chmod(_tmp_path, 0o600)
+                    os.replace(_tmp_path, _status_path)
+                except Exception:
+                    try:
+                        os.unlink(_tmp_path)
+                    except OSError:
+                        pass
+                    raise
+        except Exception:
+            logger.error("Failed to write hardware status file", exc_info=True)
+
     @property
     def width(self):
         """Get the display width."""
@@ -736,8 +780,8 @@ class DisplayManager:
             try:
                 self.image = Image.new('RGB', (self.width, self.height))
                 self.draw = ImageDraw.Draw(self.image)
-            except Exception:
+            except (OSError, RuntimeError, ValueError, MemoryError):
-                pass
+                logger.debug("Canvas reset during cleanup failed", exc_info=True)
         # Reset the singleton state when cleaning up
         DisplayManager._instance = None
         DisplayManager._initialized = False

systemd/ledmatrix-web.service

@@ -7,7 +7,8 @@
 
 [Unit]
 Description=LED Matrix Web Interface Service
-After=network.target
+After=network-online.target
+Wants=network-online.target
 
 [Service]
 Type=simple

systemd/ledmatrix.service

@@ -1,6 +1,7 @@
 [Unit]
 Description=LED Matrix Display Service
-After=network.target
+After=network-online.target
+Wants=network-online.target
 
 [Service]
 Type=simple

web_interface/blueprints/api_v3.py

@@ -699,7 +699,7 @@ def save_main_config():
 
         # Handle display settings
         display_fields = ['rows', 'cols', 'chain_length', 'parallel', 'brightness', 'hardware_mapping',
-                         'gpio_slowdown', 'scan_mode', 'disable_hardware_pulsing', 'inverse_colors', 'show_refresh_rate',
+                         'gpio_slowdown', 'rp1_rio', 'scan_mode', 'disable_hardware_pulsing', 'inverse_colors', 'show_refresh_rate',
                          'pwm_bits', 'pwm_dither_bits', 'pwm_lsb_nanoseconds', 'limit_refresh_rate_hz', 'use_short_date_format',
                          'max_dynamic_duration_seconds', 'led_rgb_sequence', 'multiplexing', 'panel_type']
 
@@ -747,6 +747,14 @@ def save_main_config():
             # Handle runtime settings
             if 'gpio_slowdown' in data:
                 current_config['display']['runtime']['gpio_slowdown'] = int(data['gpio_slowdown'])
+            if 'rp1_rio' in data:
+                try:
+                    rp1_val = int(data['rp1_rio'])
+                    if rp1_val not in (0, 1):
+                        return jsonify({'status': 'error', 'message': "rp1_rio must be 0 (PIO) or 1 (RIO)"}), 400
+                    current_config['display']['runtime']['rp1_rio'] = rp1_val
+                except (ValueError, TypeError):
+                    return jsonify({'status': 'error', 'message': "rp1_rio must be 0 or 1"}), 400
 
             # Handle checkboxes - coerce to bool to ensure proper JSON types
             for checkbox in ['disable_hardware_pulsing', 'inverse_colors', 'show_refresh_rate']:
@@ -1527,6 +1535,23 @@ def execute_system_action():
         print(error_details)
         return jsonify({'status': 'error', 'message': str(e), 'details': error_details}), 500
 
+@api_v3.route('/hardware/status', methods=['GET'])
+def get_hardware_status():
+    """Return LED matrix hardware initialization status written by display_manager at startup."""
+    status_path = "/tmp/led_matrix_hw_status.json"  # nosec B108
+    try:
+        with open(status_path) as f:
+            hw_data = json.load(f)
+        return jsonify({"status": "success", "data": hw_data})
+    except FileNotFoundError:
+        return jsonify({"status": "success", "data": {"ok": None, "error": "Display service not yet started"}})
+    except (json.JSONDecodeError, PermissionError):
+        logger.error("Failed to read hardware status file", exc_info=True)
+        return jsonify({"status": "error", "message": "Unable to read hardware status"}), 500
+    except Exception:
+        logger.error("Unexpected error reading hardware status", exc_info=True)
+        return jsonify({"status": "error", "message": "Unable to read hardware status"}), 500
+
 @api_v3.route('/display/current', methods=['GET'])
 def get_display_current():
     """Get current display state"""

web_interface/start.py

@@ -41,7 +41,7 @@ def get_local_ips():
                 ip = ip.strip()
                 if ip and not ip.startswith("127.") and ip != "192.168.4.1":
                     ips.append(ip)
-    except Exception:
+    except Exception:  # nosec B110 - hostname -I output parsing; non-critical startup info
         pass
     
     # Fallback: try socket method

web_interface/static/v3/app.js

@@ -1,4 +1,4 @@
-/* global showNotification, updateSystemStats */
+/* global showNotification, updateSystemStats, htmx */
 // LED Matrix v3 JavaScript
 // Additional helpers for HTMX and Alpine.js integration
 

web_interface/static/v3/js/widgets/custom-feeds.js

@@ -331,7 +331,7 @@
         removeButton.type = 'button';
         removeButton.className = 'text-red-600 hover:text-red-800 px-2 py-1';
         removeButton.addEventListener('click', function() {
-            removeCustomFeedRow(this);
+            window.removeCustomFeedRow(this);
         });
         const removeIcon = document.createElement('i');
         removeIcon.className = 'fas fa-trash';

web_interface/static/v3/js/widgets/timezone-selector.js

@@ -212,7 +212,7 @@
             const parts = formatter.formatToParts(now);
             const offsetPart = parts.find(p => p.type === 'timeZoneName');
             return offsetPart ? offsetPart.value : '';
-        } catch (e) {
+        } catch {
             return '';
         }
     }

web_interface/templates/v3/partials/display.html

@@ -4,6 +4,25 @@
         <p class="mt-1 text-sm text-gray-600">Configure LED matrix hardware settings and display options.</p>
     </div>
 
+    <!-- Hardware status banner: shown when display service is in fallback/simulation mode -->
+    <div x-data="{ show: false, errorMsg: '' }"
+         x-init="fetch('/api/v3/hardware/status').then(r => r.json()).then(d => {
+             const hw = (d && d.data) || {};
+             if (hw.ok === false) { show = true; errorMsg = hw.error || 'Unknown error'; }
+         }).catch(() => {})"
+         x-show="show"
+         style="display:none"
+         class="bg-yellow-50 border border-yellow-300 rounded-lg p-4 mb-6">
+        <p class="font-semibold text-yellow-800"><i class="fas fa-exclamation-triangle mr-2"></i>LED matrix running in simulation mode</p>
+        <p class="text-sm text-yellow-700 mt-1">Hardware initialization failed: <span x-text="errorMsg" class="font-mono text-xs break-all"></span></p>
+        <p class="text-sm text-yellow-700 mt-2">
+            On Raspberry Pi 5: ensure the library was rebuilt from the latest submodule
+            (<code class="bg-yellow-100 px-1 rounded">first_time_install.sh</code>)
+            and try adjusting <strong>GPIO Slowdown</strong> (start at 3, reduce if the display looks dim or choppy).
+            Check the <a href="/v3/logs" class="underline font-medium">Logs tab</a> for the full error.
+        </p>
+    </div>
+
     <form hx-post="/api/v3/config/main"
           hx-ext="json-enc"
           hx-headers='{"Content-Type": "application/json"}'
@@ -149,7 +168,7 @@
                 </div>
             </div>
 
-            <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
                 <div class="form-group">
                     <label for="gpio_slowdown" class="block text-sm font-medium text-gray-700">GPIO Slowdown</label>
                     <input type="number"
@@ -157,9 +176,20 @@
                            name="gpio_slowdown"
                            value="{{ main_config.display.runtime.gpio_slowdown or 3 }}"
                            min="0"
-                           max="5"
+                           max="10"
                            class="form-control">
-                    <p class="mt-1 text-sm text-gray-600">GPIO slowdown factor (0-5)</p>
+                    <p class="mt-1 text-sm text-gray-600">Pi 3: 1&ndash;2 &middot; Pi 4: 2&ndash;4 &middot; Pi 5 PIO: 1&ndash;3. Increase if display shows garbage; in RIO mode higher values may improve performance.</p>
+                </div>
+
+                <div class="form-group">
+                    <label for="rp1_rio" class="block text-sm font-medium text-gray-700">
+                        RP1 Backend <span class="text-xs text-gray-400 font-normal">(Pi 5 only)</span>
+                    </label>
+                    <select id="rp1_rio" name="rp1_rio" class="form-control">
+                        <option value="0" {% if main_config.display.get('runtime', {}).get('rp1_rio', 0)|int == 0 %}selected{% endif %}>0 &mdash; PIO (default, low CPU)</option>
+                        <option value="1" {% if main_config.display.get('runtime', {}).get('rp1_rio', 0)|int == 1 %}selected{% endif %}>1 &mdash; RIO (higher throughput; slowdown inverted)</option>
+                    </select>
+                    <p class="mt-1 text-sm text-gray-600">Pi 5 RP1 coprocessor mode. Ignored on Pi 3/4.</p>
                 </div>
 
                 <div class="form-group">