feat: refuse matrix settings a Raspberry Pi 5 can't drive

On a Pi 5 the pinned rgbmatrix library drives the panel through the RP1
chip, and that path supports only row address types 0 and 2, parallel 1-3
and the regular / regular-pi1 / classic / adafruit-hat(-pwm) mappings
(Rp1PioConfigSupported in lib/rp1/rp1_pio_backend.cc). For anything else
CreateFromOptions returns NULL; the Python binding doesn't check, so the
display process crashed on its first call into the matrix and systemd
restarted it into the same crash every 10 seconds.

- src/pi5_matrix_support.py: the rule and Pi 5 detection, matching the
  library's /proc/device-tree/model check
- DisplayManager raises before creating the matrix, so it is a logged init
  failure (reported by /api/v3/hardware/status) and fallback mode
- the config API rejects those settings on a Pi 5 when a request sets
  row_address_type, parallel or hardware_mapping
- the Display form offers only row address types 0 and 2 on a Pi 5, and
  warns when a stored value can't be used
- CLAUDE.md: re-check the rule whenever the submodule is bumped

Review feedback on #586.

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

web_interface/blueprints/api_v3/config.py

@@ -12,6 +12,7 @@ from web_interface.blueprints.api_v3 import (
     success_response,
 )
 from src.common.path_safety import resolve_under
+from src.pi5_matrix_support import is_raspberry_pi_5, pi5_unsupported_settings
 import web_interface.blueprints.api_v3 as _pkg
 # Read through the module rather than bound by value: tests patch these
 # as module attributes, and a value binding would not see the patch.
@@ -606,6 +607,18 @@ def save_main_config():
                     if error:
                         return error
 
+            # A Pi 5 can't drive every combination (src/pi5_matrix_support.py),
+            # and one it can't crashes the display service instead of falling
+            # back. Checked only when this request sets one of those fields, so
+            # a combination already stored doesn't block unrelated saves.
+            pi5_fields = ('row_address_type', 'parallel', 'hardware_mapping')
+            if any(k in data for k in pi5_fields) and is_raspberry_pi_5():
+                effective = dict(current_config['display']['hardware'])
+                effective.update({k: data[k] for k in pi5_fields if k in data})
+                unsupported = pi5_unsupported_settings(effective)
+                if unsupported:
+                    return jsonify({'status': 'error', 'message': unsupported}), 400
+
             # Handle hardware settings
             for field in ['rows', 'cols', 'chain_length', 'parallel', 'brightness', 'hardware_mapping', 'scan_mode',
                          'pwm_bits', 'pwm_dither_bits', 'pwm_lsb_nanoseconds', 'limit_refresh_rate_hz',

web_interface/blueprints/pages_v3.py

@@ -14,6 +14,7 @@ _SAFE_WIDGET_NAME_RE = re.compile(r'^[a-zA-Z0-9_-]{1,64}$')
 _SAFE_WIDGET_SCRIPT_RE = re.compile(r'^[a-zA-Z0-9_-]{1,64}\.js$')
 from src.web_interface.secret_helpers import mask_secret_fields
 from src.common.path_safety import resolve_under, safe_path_component
+from src.pi5_matrix_support import is_raspberry_pi_5
 from web_interface import widget_bundle
 
 logger = logging.getLogger(__name__)
@@ -544,7 +545,8 @@ def _load_display_partial():
         if pages_v3.config_manager:
             main_config = pages_v3.config_manager.load_config()
             return render_template('v3/partials/display.html',
-                                 main_config=main_config)
+                                 main_config=main_config,
+                                 is_pi5=is_raspberry_pi_5())
     except Exception as e:
         logger.error("Error loading partial", exc_info=True)
         return "Error loading partial", 500

web_interface/templates/v3/partials/display.html

@@ -196,15 +196,23 @@
                 </div>
 
                 <div class="form-group" id="setting-display-row_address_type" data-setting-key="display.hardware.row_address_type">
-                    <label for="row_address_type" class="block text-sm font-medium text-gray-700">Row Address Type{{ ui.help_tip('Row addressing scheme used by the panel.\nLeave at 0 (Default) unless your panel needs AB/ABC addressing — a wrong value shows a garbled or shifted image.\nABC panels (no E line, common on 128x64 FM6124 boards): try 3. Panels with SM5368 row drivers, such as the Waveshare 96x48 V2 (back silkscreen 24S-A1), need 5 with RGB sequence BGR. If rows then jump up and down, or the bottom row shows a copy of other rows, raise GPIO Slowdown (6–8 on a Pi 4). On a Raspberry Pi 5 the rgbmatrix library supports only 0 and 2.', 'Row Address Type') }}</label>
+                    <label for="row_address_type" class="block text-sm font-medium text-gray-700">Row Address Type{{ ui.help_tip('Row addressing scheme used by the panel.\nLeave at 0 (Default) unless your panel needs AB/ABC addressing — a wrong value shows a garbled or shifted image.\nABC panels (no E line, common on 128x64 FM6124 boards): try 3. Panels with SM5368 row drivers, such as the Waveshare 96x48 V2 (back silkscreen 24S-A1), need 5 with RGB sequence BGR. If rows then jump up and down, or the bottom row shows a copy of other rows, raise GPIO Slowdown (6–8 on a Pi 4). On a Raspberry Pi 5 the rgbmatrix library supports only 0 and 2, so only those are offered there.', 'Row Address Type') }}</label>
+                    {% set stored_row_address_type = main_config.display.hardware.get('row_address_type', 0)|int %}
                     <select id="row_address_type" name="row_address_type" class="form-control">
-                        <option value="0" {% if main_config.display.hardware.get('row_address_type', 0)|int == 0 %}selected{% endif %}>0 - Default</option>
-                        <option value="1" {% if main_config.display.hardware.get('row_address_type', 0)|int == 1 %}selected{% endif %}>1 - AB-addressed panels</option>
-                        <option value="2" {% if main_config.display.hardware.get('row_address_type', 0)|int == 2 %}selected{% endif %}>2 - Row direct</option>
-                        <option value="3" {% if main_config.display.hardware.get('row_address_type', 0)|int == 3 %}selected{% endif %}>3 - ABC-addressed panels</option>
-                        <option value="4" {% if main_config.display.hardware.get('row_address_type', 0)|int == 4 %}selected{% endif %}>4 - ABC Shift + DE direct</option>
-                        <option value="5" {% if main_config.display.hardware.get('row_address_type', 0)|int == 5 %}selected{% endif %}>5 - SM5368 / B707 row shift register</option>
+                        <option value="0" {% if stored_row_address_type == 0 %}selected{% endif %}>0 - Default</option>
+                        {% if not is_pi5 %}
+                        <option value="1" {% if stored_row_address_type == 1 %}selected{% endif %}>1 - AB-addressed panels</option>
+                        {% endif %}
+                        <option value="2" {% if stored_row_address_type == 2 %}selected{% endif %}>2 - Row direct</option>
+                        {% if not is_pi5 %}
+                        <option value="3" {% if stored_row_address_type == 3 %}selected{% endif %}>3 - ABC-addressed panels</option>
+                        <option value="4" {% if stored_row_address_type == 4 %}selected{% endif %}>4 - ABC Shift + DE direct</option>
+                        <option value="5" {% if stored_row_address_type == 5 %}selected{% endif %}>5 - SM5368 / B707 row shift register</option>
+                        {% endif %}
                     </select>
+                    {% if is_pi5 and stored_row_address_type not in (0, 2) %}
+                    <p class="text-sm text-red-600 mt-1">Your saved row address type ({{ stored_row_address_type }}) can't be used on this Raspberry Pi 5, so the display won't start with it. Saving this form sets it to 0.</p>
+                    {% endif %}
                 </div>
             </div>