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

fix(display): refuse settings the rgbmatrix library aborts on, on every board

Browse Source 
The library answers several settings with a NULL matrix or abort() rather
than an error, so the display service crash-looped (Restart=on-failure)
instead of reaching fallback mode: rows above 64, chain_length above 255
(uint8_t binding setter, documented as "no upper limit"), a misspelled
hardware_mapping, and parallel 2-3 on a single-output mapping, reachable
from the Display form on the default adafruit-hat(-pwm) mapping. #586 only
guarded the Pi 5 subset.

- src/matrix_support.py holds the rules for every board (Options::Validate
  ranges, binding integer types, mapping names and outputs from
  lib/hardware-mapping.c) plus the Pi 5 ones, and is the one source of the
  API's numeric ranges.
- DisplayManager checks them before building options and raises
  MatrixSettingsRefused, so a hand-edited config falls back with a logged,
  reported reason. Emulator mode only warns.
- The config API refuses them with a 400 naming the setting; combinations
  are checked against stored values but reported only when the request
  sets a field involved.
- The hardware status file gains "cause" (settings/library/forced). The
  fallback log and Display banner give the Pi 5 rebuild hint only for a
  library failure instead of rebuild + gpio_slowdown advice for every
  failure; one Pi 5 slowdown recommendation (1-3, start at 1).
- The Display form offers classic/classic-pi1 and orientation 90/270 and
  renders any other stored mapping selected with a warning, so an
  unrelated save no longer rewrites them; the API accepts 90/270.

Audit findings F03, F16, F19, F21.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Chuck
2026-09-17 08:59:47 -04:00
co-authored by Claude Opus 5
parent c693278d33
commit 94ec74caa5
7 changed files with 680 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/display_manager.py
+58 -32
View File
@@ -37,9 +37,11 @@ from PIL import Image, ImageDraw, ImageFont
from src.common.font_layout import crisp_size, load_truetype, resolve_asset_path
from src.display_geometry import (
DEFAULT_CHAIN_LENGTH, DEFAULT_COLS, DEFAULT_PARALLEL, DEFAULT_ROWS,
physical_size, resolve_double_sided,
ORIENTATION_ROTATE_DEGREES, compose_pixel_mapper_config, physical_size,
resolve_double_sided,
)
from src.pi5_matrix_support import is_raspberry_pi_5, pi5_unsupported_settings
from src.matrix_support import MatrixSettingsRefused, library_refusals, refusal_message
from src.pi5_matrix_support import is_raspberry_pi_5
import threading
import time
from collections import OrderedDict
@@ -247,28 +249,41 @@ class DisplayManager:
# Calendar manager is now initialized by DisplayController
# Orientation setting -> rpi-rgb-led-matrix "Rotate:<deg>" pixel-mapper suffix.
# "normal" needs no suffix since 0 degrees is the identity transform.
_ORIENTATION_ROTATE_DEGREES = {'normal': None, '90': 90, '180': 180, '270': 270}
_ORIENTATION_ROTATE_DEGREES = ORIENTATION_ROTATE_DEGREES
def _build_pixel_mapper_config(self, hardware_config: dict) -> str:
"""Compose the raw pixel_mapper_config string with the orientation setting.
"""Compose pixel_mapper_config with the orientation setting.
`pixel_mapper_config` stays available as a free-form advanced field (e.g.
for "U-mapper" chain layouts); `orientation` is the user-facing dropdown
for physical mounting (e.g. panels mounted upside down) and is appended as
a "Rotate:<deg>" mapper rather than overwriting any existing config.
See :func:`src.display_geometry.compose_pixel_mapper_config`, which the
web preview shares so it sizes the canvas the same way.
"""
base_mapper = (hardware_config.get('pixel_mapper_config') or '').strip()
orientation = hardware_config.get('orientation', 'normal')
degrees = self._ORIENTATION_ROTATE_DEGREES.get(orientation)
if degrees is None:
return base_mapper
rotate_mapper = f'Rotate:{degrees}'
return f'{base_mapper};{rotate_mapper}' if base_mapper else rotate_mapper
return compose_pixel_mapper_config(hardware_config)
@staticmethod
def _fallback_advice(cause: str, error: Exception) -> str:
"""What to do about a failed matrix init, for the log.
Only a library failure gets the rebuild hint: advice about the build
or GPIO timing sends someone whose settings were refused the wrong way.
"""
if cause == "settings":
return (f"{error} Change these in the web interface's Display tab "
"(or display.hardware / display.runtime in config.json) "
"and restart the display service.")
if cause == "forced":
return f"Error: {error}."
advice = (f"Error: {error}. If the rgbmatrix library printed a message "
"just before this, it names the problem.")
if is_raspberry_pi_5():
advice += (" On a Raspberry Pi 5, an mmap error means the library was "
"built without Pi 5 support: sudo RPI_RGB_FORCE_REBUILD=1 "
"./first_time_install.sh")
return advice
def _setup_matrix(self):
"""Initialize the RGB matrix with configuration settings."""
_init_error_str = None
_init_cause = None
try:
# Allow callers (e.g., web UI) to force non-hardware fallback mode
if getattr(self, '_force_fallback', False):
@@ -278,6 +293,18 @@ class DisplayManager:
# Hardware configuration
hardware_config = self.config.get('display', {}).get('hardware', {})
runtime_config = self.config.get('display', {}).get('runtime', {})
# The library has no error path for many settings it can't use:
# it returns no matrix (which the binding doesn't check, so the
# process crashes on its next call) or calls abort(), and systemd
# restarts the service into the same crash. Refuse those first so
# they become a logged, reported fallback (src/matrix_support.py).
refused = refusal_message(library_refusals(
hardware_config, runtime_config, pi5=is_raspberry_pi_5()))
if refused:
if os.getenv("EMULATOR", "false") != "true":
raise MatrixSettingsRefused(refused)
logger.warning("Emulator mode: continuing, but on a real panel the display would not start. %s", refused)
# Basic hardware settings
options.rows = hardware_config.get('rows', DEFAULT_ROWS)
@@ -326,15 +353,6 @@ class DisplayManager:
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}")
# On a Pi 5 the library hands back no matrix for settings its RP1
# path can't drive, and the binding doesn't check -- the process
# would crash on its next call instead of reaching the fallback
# below. Raise first so it is a logged, reported init failure.
if os.getenv("EMULATOR", "false") != "true" and is_raspberry_pi_5():
unsupported = pi5_unsupported_settings(hardware_config)
if unsupported:
raise RuntimeError(unsupported)
# Initialize the matrix
self.matrix = RGBMatrix(options=options)
logger.info("RGB Matrix initialized successfully")
@@ -379,7 +397,12 @@ class DisplayManager:
except Exception as e:
_init_error_str = str(e)
logger.error(f"Failed to initialize RGB Matrix: {e}", exc_info=True)
if isinstance(e, MatrixSettingsRefused):
_init_cause = "settings"
logger.error("Failed to initialize RGB Matrix: %s", e)
else:
_init_cause = "forced" if getattr(self, '_force_fallback', False) else "library"
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
try:
@@ -406,15 +429,18 @@ class DisplayManager:
# Best-effort; ignore drawing errors in fallback
pass
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."
)
"Matrix initialization failed — running in fallback/simulation mode "
"(size %dx%d). %s",
fallback_width, fallback_height, self._fallback_advice(_init_cause, e))
# 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}
# cause: None when ok; "settings" when LEDMatrix refused the config
# (fix the named settings), "library" when the library itself failed,
# "forced" for a caller-requested fallback. The Display tab keys its
# advice on it.
_hw_status = {"ok": self.matrix is not None, "error": _init_error_str,
"cause": None if self.matrix is not None else _init_cause}
_status_path = "/tmp/led_matrix_hw_status.json" # nosec B108
try:
if os.path.islink(_status_path):
src/matrix_support.py
+205
View File
@@ -0,0 +1,205 @@
"""Display settings the pinned rgbmatrix library refuses, on every board.
The library does not raise on a setting it can't use. For most it returns no
matrix -- ``RGBMatrix::CreateFromOptions()`` gives back NULL when
``Options::Validate()`` (``lib/options-initialize.cc``) or its GPIO slowdown
check (``lib/led-matrix.cc``) fails -- and the Python binding stores that
pointer without checking, so the display process crashes on its first call
into the matrix. For two it calls ``abort()``: an unknown hardware mapping
name, and more parallel chains than the mapping has outputs
(``Framebuffer::InitHardwareMapping()`` and the ``Framebuffer`` constructor in
``lib/framebuffer.cc``). Either way systemd restarts the service into the same
crash, and no fallback or hardware status is ever reported.
``DisplayManager`` runs :func:`library_refusals` before creating the matrix,
turning those crashes into a logged error and the usual fallback mode. The
config API uses the same rules to refuse the settings up front, and
:data:`INT_SETTING_LIMITS` is the one place the numeric ranges live.
Pi 5-only limits come from :mod:`src.pi5_matrix_support` and are added when
``pi5=True``.
**Re-check this when the submodule is bumped** (pinned at 1ee4f76): the
ranges in ``Options::Validate()``, the mapping table in
``lib/hardware-mapping.c`` and the setter types in
``bindings/python/rgbmatrix/core.pyx``. A stale rule here blocks settings a
new library accepts; a missing one lets the display service crash-loop.
"""
from typing import Any, Dict, List, Mapping, NamedTuple, Optional, Tuple
from src.pi5_matrix_support import pi5_unsupported_settings
#: The binding's setters for rows, chain_length, parallel and the other small
#: integers are declared ``uint8_t`` (``core.pyx``), cols ``uint32_t``, and
#: limit_refresh_rate_hz lands in a C ``int``; a larger value raises
#: ``OverflowError`` before the library sees it.
UINT8_MAX = 255
UINT32_MAX = 2 ** 32 - 1
INT32_MAX = 2 ** 31 - 1
#: field -> (config section, lowest, highest, must be even). The library's own
#: ranges where it has one, otherwise the binding's integer type.
INT_SETTING_LIMITS: Dict[str, Tuple[str, int, int, bool]] = {
'rows': ('hardware', 8, 64, True),
'cols': ('hardware', 16, UINT32_MAX, False),
'chain_length': ('hardware', 1, UINT8_MAX, False),
# 3 is the most any mapping in the default build has (see MAPPING_OUTPUTS).
'parallel': ('hardware', 1, 3, False),
'brightness': ('hardware', 1, 100, False),
'scan_mode': ('hardware', 0, 1, False),
'pwm_bits': ('hardware', 1, 11, False),
'pwm_dither_bits': ('hardware', 0, 2, False),
'pwm_lsb_nanoseconds': ('hardware', 50, 3000, False),
# 0 = no cap; the library has no upper bound.
'limit_refresh_rate_hz': ('hardware', 0, INT32_MAX, False),
'row_address_type': ('hardware', 0, 5, False),
# 22 registered multiplexers (lib/multiplex-mappers.cc).
'multiplexing': ('hardware', 0, 22, False),
'gpio_slowdown': ('runtime', 0, 10, False),
'rp1_rio': ('runtime', 0, 1, False),
}
#: Hardware mapping name -> parallel chains it has outputs for, as
#: ``lib/hardware-mapping.c`` defines them. ``compute-module`` exists only when
#: the library is built with ENABLE_WIDE_GPIO_COMPUTE_MODULE, which the pinned
#: Makefile leaves commented out and the installer does not set, so the library
#: LEDMatrix installs aborts on it like any other unknown name.
MAPPING_OUTPUTS: Dict[str, int] = {
'regular': 3,
'adafruit-hat': 1,
'adafruit-hat-pwm': 1,
'regular-pi1': 1,
'classic': 3,
'classic-pi1': 1,
}
#: What DisplayManager passes when a key is missing from display.hardware /
#: display.runtime. Config migration normally fills these from
#: config/config.template.json first, so they rarely apply.
DISPLAY_MANAGER_DEFAULTS: Dict[str, Any] = {
'rows': 32, 'cols': 64, 'chain_length': 2, 'parallel': 1,
'hardware_mapping': 'adafruit-hat-pwm', 'brightness': 90, 'pwm_bits': 10,
'pwm_lsb_nanoseconds': 150, 'led_rgb_sequence': 'RGB',
'row_address_type': 0, 'multiplexing': 0, 'limit_refresh_rate_hz': 90,
'gpio_slowdown': 3,
}
class Refusal(NamedTuple):
"""One reason the library can't start with a config.
``fields`` are the settings involved; the config API reports a refusal
only when the request sets one of them, so a problem already stored
doesn't block an unrelated save.
"""
fields: Tuple[str, ...]
message: str
#: A Raspberry Pi 5-only limit, whose message is already a full sentence.
pi5: bool = False
class MatrixSettingsRefused(RuntimeError):
"""Raised by DisplayManager instead of handing the library such a config."""
def _as_int(value: Any) -> Optional[int]:
"""The integer the binding would receive, or None if it isn't one.
A value that isn't a number is left to the binding, which raises a
``TypeError`` DisplayManager already turns into fallback mode.
"""
try:
return int(value)
except (TypeError, ValueError, OverflowError):
return None
def _setting(hardware: Mapping[str, Any], runtime: Mapping[str, Any], field: str) -> Any:
section = runtime if INT_SETTING_LIMITS.get(field, ('hardware',))[0] == 'runtime' else hardware
if field in section:
return section[field]
return DISPLAY_MANAGER_DEFAULTS.get(field)
def describe_range(low: int, high: int, even: bool = False) -> str:
kind = "an even integer" if even else "an integer"
if high >= INT32_MAX:
return f"{kind} of at least {low}"
return f"{kind} from {low} to {high}"
def library_refusals(hardware: Optional[Mapping[str, Any]],
runtime: Optional[Mapping[str, Any]] = None,
pi5: bool = False) -> List[Refusal]:
"""Every reason the pinned library would refuse (NULL, abort or overflow)
to start with this ``display.hardware`` / ``display.runtime`` config.
Missing keys take DisplayManager's defaults. ``pi5`` adds the Raspberry
Pi 5 limits from :func:`pi5_unsupported_settings`.
"""
hardware = hardware if isinstance(hardware, Mapping) else {}
runtime = runtime if isinstance(runtime, Mapping) else {}
refusals: List[Refusal] = []
for field, (section, low, high, even) in INT_SETTING_LIMITS.items():
# DisplayManager sets these only when present, and scan_mode /
# pwm_dither_bits / rp1_rio have no default of its own.
source = runtime if section == 'runtime' else hardware
if field not in source and field not in DISPLAY_MANAGER_DEFAULTS:
continue
value = _as_int(_setting(hardware, runtime, field))
if value is None:
continue
if not low <= value <= high or (even and value % 2):
refusals.append(Refusal(
(field,), f"{field} {value} (must be {describe_range(low, high, even)})"))
mapping = _setting(hardware, runtime, 'hardware_mapping')
outputs = None
if not isinstance(mapping, str):
refusals.append(Refusal(
('hardware_mapping',), f"hardware mapping {mapping!r} (must be a mapping name)"))
else:
# The library matches names case-insensitively and reads an empty
# name as "regular".
outputs = MAPPING_OUTPUTS.get((mapping or 'regular').lower())
if outputs is None:
refusals.append(Refusal(
('hardware_mapping',),
f'hardware mapping "{mapping}" (the installed library has '
+ ", ".join(MAPPING_OUTPUTS) + ")"))
parallel = _as_int(_setting(hardware, runtime, 'parallel'))
if outputs is not None and parallel is not None and 1 <= parallel <= 3 and parallel > outputs:
refusals.append(Refusal(
('parallel', 'hardware_mapping'),
f'parallel {parallel} with hardware mapping "{mapping}", which has '
f'{outputs} output{"s" if outputs != 1 else ""}'))
sequence = _setting(hardware, runtime, 'led_rgb_sequence')
if isinstance(sequence, str) and not (
len(sequence) == 3 and set(sequence.upper()) == {'R', 'G', 'B'}):
refusals.append(Refusal(
('led_rgb_sequence',),
f'LED RGB sequence "{sequence}" (must be R, G and B in some order)'))
if pi5:
unsupported = pi5_unsupported_settings(hardware)
if unsupported:
refusals.append(Refusal(
('row_address_type', 'parallel', 'hardware_mapping'), unsupported, pi5=True))
return refusals
def refusal_message(refusals: List[Refusal]) -> Optional[str]:
"""One sentence naming every refusal, or None when there are none."""
general = [r.message for r in refusals if not r.pi5]
pi5 = [r.message for r in refusals if r.pi5]
parts = []
if general:
parts.append("The installed rgbmatrix library can't start with these "
"display settings: " + "; ".join(general) + ".")
parts.extend(pi5)
return " ".join(parts) or None