firestarter 3.2.7b2__tar.gz → 3.3.0b1__tar.gz

{firestarter-3.2.7b2/firestarter.egg-info → firestarter-3.3.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firestarter
-Version: 3.2.7b2
+Version: 3.3.0b1
 Summary: EPROM programmer software for the Relatively Universal ROM Programmer
 Author-email: Henrik Olsson <henols@gmail.com>
 Project-URL: Homepage, https://github.com/henols/firestarter_app

{firestarter-3.2.7b2 → firestarter-3.3.0b1}/firestarter/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.2.7b2'
-__version_tuple__ = version_tuple = (3, 2, 7, 'b2')
+__version__ = version = '3.3.0b1'
+__version_tuple__ = version_tuple = (3, 3, 0, 'b1')
 
-__commit_id__ = commit_id = 'g30e9def'
+__commit_id__ = commit_id = 'g927ad2b'

{firestarter-3.2.7b2 → firestarter-3.3.0b1}/firestarter/channel.py

@@ -59,23 +59,16 @@ def is_prerelease_build() -> bool:
     """True when this build came off `beta` (its own version is a pre-release).
 
     Fails **closed**: an unparseable version is treated as stable, so a gated
-    feature stays hidden rather than leaking. This matches
-    `_maybe_auto_route_to_pre`, which also treats `InvalidVersion` as
-    not-a-prerelease. In practice `__version__` is a literal in the package and
-    is always valid PEP 440; dev versions (`2.0.7_dev`) parse as pre-releases and
-    therefore keep gated features enabled while working from a checkout.
+    feature stays hidden rather than leaking. `_maybe_auto_route_to_pre` uses
+    this function, so it treats an unparseable version the same way. In
+    practice `__version__` is a literal in the package and is always valid
+    PEP 440; dev versions (`2.0.7_dev`) parse as pre-releases and therefore
+    keep gated features enabled while working from a checkout.
     """
-    try:
-        from packaging.version import InvalidVersion, Version
+    import firestarter as _pkg
+    from firestarter.fw_release_gate import is_prerelease_version
 
-        import firestarter as _pkg
-
-        try:
-            return bool(Version(_pkg.__version__).is_prerelease)
-        except InvalidVersion:
-            return False
-    except ImportError:  # pragma: no cover — packaging is a hard dependency
-        return False
+    return is_prerelease_version(_pkg.__version__) is True
 
 
 def is_board_available(board: str | None) -> bool:

{firestarter-3.2.7b2 → firestarter-3.3.0b1}/firestarter/chip_resolver.py

@@ -9,7 +9,7 @@ Single chokepoint between CLI dispatch and the EPROM database lookup/conversion.
 
 from typing import Any
 
-from firestarter.database import ROM_CE, ROM_OE, EpromDatabase
+from firestarter.database import ROM_CE, ROM_OE, EpromDatabase, pin_conversions
 from firestarter.exceptions import (
     AmbiguousChipNameError,
     ChipNotFoundError,
@@ -18,6 +18,13 @@ from firestarter.exceptions import (
 
 _NON_ZERO_WIRE_FIELDS = ("memory-size", "pin-count", "vpp_mv")
 
+# The 0x10 (Intel 28F) handler routes 12V to socket pin 1 (CTRL_VPP_P1_ENABLE).
+_INTEL_28F_ALGORITHM = 0x10
+
+# The shield supplies a fixed 5V VCC. Must agree with SHIELD_MIN_VCC_MV in
+# tools/build_db.py.
+_SHIELD_MIN_VCC_MV = 4500
+
 
 def _qualified_choices(name: str, db: EpromDatabase) -> list[str]:
     """The row `name` selects first, then each other row it selects that
@@ -115,13 +122,22 @@ def resolve_chip(name: str, db: EpromDatabase | None = None) -> dict[str, Any]:
             "a chip entry must specify a non-zero 'algorithm' to be programmed"
         )
 
+    # A 3V part runs out of its rating on the shield's 5V supply. A user
+    # override that marks such a row supported is refused here, before any wire.
+    vcc_mv = raw_config.get("electrical", {}).get("vcc_mv")
+    if isinstance(vcc_mv, int) and 0 < vcc_mv < _SHIELD_MIN_VCC_MV:
+        raise ChipNotImplementedError(
+            f"{name}: the chip's operating VCC is {vcc_mv / 1000:g}V, but the "
+            "shield supplies 5V. The programmer refuses the chip."
+        )
+
     full = db.get_eprom(name)
     data = db.convert_to_programmer(full) if full else None
     if not data:
         raise ChipNotFoundError(name)
 
     # The firmware refuses a memory command whose memory-size, pin-count or
-    # vpp_mv is 0, with the same 'Bad JSON' answer that old firmware gives.
+    # vpp_mv is 0 (MSG_ERR_BAD_COMMAND), so the port walk sees no programmer.
     # No shipped row has a 0 here; a user database override can.
     zero_fields = [key for key in _NON_ZERO_WIRE_FIELDS if not data.get(key)]
     if zero_fields:
@@ -148,4 +164,13 @@ def resolve_chip(name: str, db: EpromDatabase | None = None) -> dict[str, Any]:
             f"{1 << len(bus)} of its {data['memory-size']} bytes. The programmer "
             "cannot address the rest of the chip."
         )
+    # The 0x10 handler puts 12V on socket pin 1, so a 0x10 chip whose bus uses
+    # that pin (A18 on the SST28SF040 family) would take 12V on an address
+    # line. Only a 32-pin chip has a pin there: a smaller chip sits
+    # bottom-aligned, and none of its pins converts to the socket pin 1 line.
+    if bus and algorithm == _INTEL_28F_ALGORITHM and pin_conversions[32][1] in bus:
+        raise ChipNotImplementedError(
+            f"{name}: algorithm 0x10 puts 12V on socket pin 1, but the chip's pin "
+            "map uses pin 1 as an address line. The programmer refuses the chip."
+        )
     return data

{firestarter-3.2.7b2 → firestarter-3.3.0b1}/firestarter/cli_handlers.py

@@ -21,6 +21,7 @@ import click.shell_completion
 from rich.console import Console
 
 from firestarter import __version__ as version
+from firestarter import command_frame as cf
 from firestarter import (
     dip24_2816_erase_gate,
     flash4_erase_gate,
@@ -62,6 +63,7 @@ from firestarter.chip_test import (
     sdp_hold_state,
     sdp_oracle_applicable,
 )
+from firestarter.command_codec import CommandEncodeError
 from firestarter.config import ConfigManager, get_config_dir
 from firestarter.constants import (
     CONFIG_R1_MAX,
@@ -85,6 +87,7 @@ from firestarter.exceptions import (
     ChipNotFoundError,
     ChipNotImplementedError,
     EpromOperationError,
+    FirmwareFrameVersionError,
     FirmwareOperationError,
     FirmwareOutdatedError,
     HardwareOperationError,
@@ -98,7 +101,7 @@ from firestarter.exceptions import (
 )
 from firestarter.firmware import FIRMWARE_VERSION_RE, FirmwareManager
 from firestarter.fw_release_gate import require_installable_release
-from firestarter.hardware import HardwareManager
+from firestarter.hardware import HardwareManager, bandgap_from_measured_vcc
 from firestarter.lock_status import (
     classify_protection_response,
     exit_code_for_class,
@@ -238,6 +241,8 @@ def map_typed_errors(f: Callable[..., Any]) -> Callable[..., Any]:
             return f(*args, **kwargs)
         except ChipNotFoundError as e:
             raise click.ClickException(str(e)) from e
+        except FirmwareFrameVersionError as e:
+            raise click.ClickException(f"Command frame version mismatch: {e}") from e
         except FirmwareOutdatedError as e:
             raise click.ClickException(f"Firmware outdated: {e}") from e
         except (SerialError, SerialTimeoutError) as e:
@@ -269,6 +274,11 @@ def map_typed_errors(f: Callable[..., Any]) -> Callable[..., Any]:
             # make this host-voiced refusal (write_blank_guard.py) read as a
             # hardware fault instead of an input-validation refusal.
             raise click.ClickException(str(e)) from e
+        except CommandEncodeError as e:
+            # The host refused the command before any byte reached the port.
+            # Above the EpromOperationError arm: "Programmer error" would read
+            # as a hardware fault for an input the frame cannot carry.
+            raise click.ClickException(f"Refused before sending: {e}") from e
         except EpromOperationError as e:
             raise click.ClickException(f"Programmer error: {e}") from e
         except Pin1HazardRefusedError as e:
@@ -343,29 +353,15 @@ def _maybe_auto_route_to_pre(args: object) -> None:
         or getattr(args, "stable", False)
     ):
         return
-    try:
-        from packaging.version import InvalidVersion, Version
-
-        import firestarter as _pkg
-
-        try:
-            if Version(_pkg.__version__).is_prerelease:
-                args.pre = True  # type: ignore[attr-defined]
-                helper_logger.info(
-                    "Beta app detected — defaulting to --pre. "
-                    "Use --firmware-version X.Y.Z to pin a stable version."
-                )
-        except InvalidVersion:
-            # Deliberate fail-OPEN, and deliberately the opposite polarity to
-            # fw_release_gate, which fails CLOSED on the same unreadable input.
-            # The asymmetry is intended: the worst case here is that the wrong
-            # channel is picked, which the gate then judges on its merits; the
-            # worst case there is a board flashed with firmware this host cannot
-            # drive, recoverable only through the bootloader. Do not "align"
-            # these two without re-reading both worst cases.
-            pass
-    except ImportError:
-        pass
+    # An unreadable version is not a pre-release here: the worst case is the
+    # wrong channel, which fw_release_gate then judges and refuses (it fails
+    # CLOSED on the same input). Do not "align" the two polarities.
+    if is_prerelease_build():
+        args.pre = True  # type: ignore[attr-defined]
+        helper_logger.info(
+            "Beta app detected — defaulting to --pre. "
+            "Use --firmware-version X.Y.Z to pin a stable version."
+        )
 
 
 def _build_op_flags(
@@ -381,6 +377,7 @@ def _build_op_flags(
     # SDP auto-set condition inside write() below -- flipping this default
     # invalidates the removal-safety argument the `dev sdp` removal rests on.
     skip_sdp_unlock: bool = False,
+    skip_final_verify: bool = False,
     input_enable: bool | None = None,
     chip_disable: bool | None = None,
 ) -> int:
@@ -410,6 +407,7 @@ def _build_op_flags(
         verbose,
         skip_erase=skip_erase,
         skip_sdp_unlock=skip_sdp_unlock,
+        skip_final_verify=skip_final_verify,
     )
     if input_enable is not None:
         flags |= 0 if input_enable else FLAG_OUTPUT_ENABLE
@@ -947,6 +945,9 @@ def write(
             vpe_as_vpp=vpe_as_vpp,
             skip_erase=skip_erase,
             skip_sdp_unlock=skip_sdp_unlock,
+            # The read-back below compares every byte, so the board's own
+            # final verify pass would only repeat it.
+            skip_final_verify=verify,
         ),
         # Translate Click's `None` ("--pulse-us not supplied") into
         # write_eprom's own integer sentinel (0 means "use the database
@@ -1062,8 +1063,7 @@ def _address_size_refusal_exit_code(
     """Refuse a negative start address or a size below 1 byte before the
     serial port opens.
 
-    The firmware refuses both at setup, with the same 'Bad JSON' answer that
-    firmware too old for this CLI gives, so without this check the operator
+    The firmware refuses both at setup, so without this check the operator
     sees only "no programmer found". Returns 2 to refuse with, or `None`.
     A malformed string is not refused here: `_setup_operation`'s own parse
     handling still owns that error.
@@ -1606,15 +1606,22 @@ def hw(app: AppContext) -> None:
 
 
 _BANDGAP_NOMINAL_MV = 1100
+# A plausibility bound for a 5 V supply pin, not a wire limit: the host sends
+# the bandgap, not the reading. A reading above it is a typo, refused before
+# any port opens.
+_CAL_VCC_MAX_V = 10.0
 
 
 @cli.command(name="cal")
 @click.option(
     "--vcc",
-    type=click.FloatRange(min=0, min_open=True),
+    type=click.FloatRange(min=0, min_open=True, max=_CAL_VCC_MAX_V),
     default=None,
     metavar="VOLTS",
-    help="Calibrate using a multimeter reading of the 5V pin, e.g. --vcc 5.09",
+    help=(
+        "Calibrate using a multimeter reading of the 5V pin, e.g. --vcc 5.09. "
+        f"At most {_CAL_VCC_MAX_V:g} V."
+    ),
 )
 @click.option(
     "--reset",
@@ -1654,21 +1661,43 @@ def cal(app: AppContext, vcc: float | None, reset: bool) -> None:
     if vcc is not None:
         measured_mv = int(round(vcc * 1000))
         before = app.hardware_manager.read_calibration()
-        if not app.hardware_manager.calibrate_bandgap(measured_mv):
+        if before is None:
+            click.echo(
+                "Could not read the calibration. The firmware may be older than "
+                "this CLI."
+            )
+            sys.exit(1)
+        bandgap_adc = before["bandgap_adc"]
+        if bandgap_adc == 0:
+            click.echo("This board has no bandgap calibration (py32f071).")
+            sys.exit(1)
+        bandgap_mv = bandgap_from_measured_vcc(measured_mv, bandgap_adc)
+        if bandgap_mv is None:
             click.echo(
                 "Calibration refused. The result was outside 1000-1200 mV, which "
                 "means the reading does not match this board. Check that the "
-                "multimeter is on the 5V pin and that the value is in volts. "
-                "A py32f071 board has no bandgap calibration and always "
-                "refuses it."
+                "multimeter is on the 5V pin and that the value is in volts."
             )
             sys.exit(1)
+        if not app.hardware_manager.set_bandgap_mv(bandgap_mv):
+            sys.exit(1)
+        # Read the value back over a new connection, so the report is what the
+        # board stored, not what this host sent.
         after = app.hardware_manager.read_calibration()
-        if before is not None and after is not None:
+        if after is None:
+            click.echo(
+                f"Sent {bandgap_mv} mV, but could not read the calibration back. "
+                "Run 'firestarter cal' to check it."
+            )
+            sys.exit(1)
+        if after["bandgap_mv"] != bandgap_mv:
             click.echo(
-                f"Reference: {before['bandgap_mv']} mV -> {after['bandgap_mv']} mV"
+                f"Calibration not stored: the board reports {after['bandgap_mv']} "
+                f"mV, expected {bandgap_mv} mV."
             )
-            _echo_calibration_effect(after["bandgap_mv"])
+            sys.exit(1)
+        click.echo(f"Reference: {before['bandgap_mv']} mV -> {after['bandgap_mv']} mV")
+        _echo_calibration_effect(after["bandgap_mv"])
         sys.exit(0)
 
     current = app.hardware_manager.read_calibration()
@@ -2285,16 +2314,22 @@ if _DEV_TOOLS_ENABLED:
     @click.option(
         "--read-settling",
         "read_settling_us",
-        type=int,
+        type=click.IntRange(0, cf.READ_TIMING_MAX_US),
         default=0,
-        help="Address-settling delay before /CE assert (µs; 0=firmware default 0µs).",
+        help=(
+            "Address-settling delay before /CE assert "
+            f"(µs, 0..{cf.READ_TIMING_MAX_US}; 0=firmware default 0µs)."
+        ),
     )
     @click.option(
         "--read-strobe",
         "read_strobe_us",
-        type=int,
+        type=click.IntRange(0, cf.READ_TIMING_MAX_US),
         default=0,
-        help="/CE read-strobe pulse width (µs; 0=firmware default 3µs).",
+        help=(
+            "/CE read-strobe pulse width "
+            f"(µs, 0..{cf.READ_TIMING_MAX_US}; 0=firmware default 3µs)."
+        ),
     )
     @click.pass_obj
     @map_typed_errors

{firestarter-3.2.7b2 → firestarter-3.3.0b1}/firestarter/codec.py

@@ -12,6 +12,7 @@ import logging
 import struct
 from typing import Any, List  # noqa: UP035
 
+from firestarter.command_frame import REFUSALS
 from firestarter.constants import (
     COMMAND_NAMES,
     REVISION_0,
@@ -29,22 +30,58 @@ from firestarter.messages import (
     DEBUG_CATALOG,
     MSG_DATA_CHUNK,
     MSG_DEBUG,
+    MSG_ERR_BAD_COMMAND,
+    MSG_ERR_VPP_HIGH_MV,
     MSG_INFO_CMD,
     MSG_INFO_HW,
     MSG_INFO_PHYSICAL_HW,
+    MSG_INFO_REGISTERS,
     MSG_OK_CFG,
     MSG_OK_REV,
+    MSG_WARN_VPP_HIGH_MV,
+    MSG_WARN_VPP_LOW_MV,
     SEVERITY_LABEL,
     MessageDef,
 )
 
 logger = logging.getLogger("Codec")
 
-# Older, shorter forms of fixed-width acks that the host still accepts. The
-# value is the legacy param-region length; the decoder reads only the leading
-# catalog params that fit in it. MSG_OK_CFG gained the trailing u16 bandgap in
-# 3.1.0b4, so the 3.1.0 stable firmware still sends the 9-byte form.
-_LEGACY_PARAM_BYTES = {MSG_OK_CFG: 9}
+# MSG_INFO_REGISTERS views (firmware sync: dev_tools.cpp DT_VIEW_*).
+_REGISTER_VIEW_REG_FIRESTARTER = 1
+_REGISTER_VIEW_ADDR = 2
+
+
+def volts(mv: int) -> str:
+    """`'12.449 V'` for a millivolt value: every millivolt the firmware sent."""
+    return f"{mv / 1000:.3f} V"
+
+
+def _register_table(name: str, value: int, bits: int) -> list[str]:
+    """One register as the three lines `dev reg` / `dev addr` print: the
+    value, the bit header and the bit row, D(bits-1) first."""
+    header = "|D8" if bits == 9 else ""
+    row = "".join(f"| {(value >> i) & 1}" for i in range(bits - 1, -1, -1))
+    return [
+        f"{name}: 0x{value:02X}",
+        f"{header}|D7|D6|D5|D4|D3|D2|D1|D0|",
+        f"{row}|",
+    ]
+
+
+def _render_registers(msb: int, lsb: int, ctrl: int, remapped: int, view: int) -> str:
+    """The bit tables for MSG_INFO_REGISTERS. The firmware sends raw values;
+    the table layout is the one the firmware used to print."""
+    lines = _register_table("MSB", msb, 8) + _register_table("LSB", lsb, 8)
+    if view == _REGISTER_VIEW_ADDR:
+        lines += _register_table("TOP addr", ctrl, 8)
+        lines += _register_table("CTRL remapped", remapped, 8)
+    elif view == _REGISTER_VIEW_REG_FIRESTARTER:
+        lines += _register_table("CTRL", ctrl, 9)
+        lines += _register_table("CTRL remapped", remapped, 8)
+    else:
+        lines += _register_table("CTRL", ctrl & 0xFF, 8)
+    return "\n".join(lines)
+
 
 # REVISION_* byte → silkscreen-string mapping for MSG_OK_REV rendering.
 # Mirrors firmware enum at firestarter/include/rurp_shield.h. Lookup-via-dict.get()
@@ -78,13 +115,10 @@ def format_message(msg_id: int, params: List[Any], entry: MessageDef) -> str | N
       (the override is in effect; the second field is what the board detected)
 
     P-03 MSG_OK_CFG  — params[0]=r1 u32, params[1]=r2 u32, params[2]=override u8,
-                       params[3]=bandgap_mv u16 (absent on firmware before 3.1.0b4)
-      override==0xFF → "R1: {r1}, R2: {r2}, Bandgap: {n} mV"
-      override!=0xFF → "R1: {r1}, R2: {r2}, Override HW: {silkscreen_str}, Bandgap: {n} mV"
-      The Bandgap clause is always present when the ack carries the field:
-      HardwareManager.read_calibration keys on it. The 9-byte form from older
-      firmware has no bandgap, so it renders without the Bandgap clause, and
-      read_calibration reports that firmware as too old.
+                       params[3]=bandgap_mv u16, params[4]=bandgap_adc u16
+      override==0xFF → "R1: {r1}, R2: {r2}, Bandgap: {n} mV, Bandgap count: {c}"
+      override!=0xFF → "R1: {r1}, R2: {r2}, Override HW: {silkscreen_str},
+                        Bandgap: {n} mV, Bandgap count: {c}"
       Override clause now routes through
       _REVISION_SILKSCREEN so the same byte that surfaces as "Rev 2.0-class"
       via MSG_OK_REV no longer surfaces as "Rev2" on the adjacent ack line.
@@ -107,7 +141,7 @@ def format_message(msg_id: int, params: List[Any], entry: MessageDef) -> str | N
         eff_str = _REVISION_SILKSCREEN.get(effective, f"Rev{effective}")
         return f"{eff_str}, Detected HW: {phys_str}"
 
-    if msg_id == MSG_OK_CFG and len(params) in (3, 4):
+    if msg_id == MSG_OK_CFG and len(params) == 5:
         r1, r2, override = params[0], params[1], params[2]
         head = f"R1: {r1}, R2: {r2}"
         if override != 0xFF:
@@ -117,12 +151,7 @@ def format_message(msg_id: int, params: List[Any], entry: MessageDef) -> str | N
             # No-space "Rev{n}" fallback mirrors the MSG_OK_REV branch shape.
             override_str = _REVISION_SILKSCREEN.get(override, f"Rev{override}")
             head += f", Override HW: {override_str}"
-        if len(params) == 3:
-            # Firmware before 3.1.0b4 sends no bandgap field.
-            return head
-        # v1.43 appended the calibrated reference. Rendered last so the
-        # override clause keeps the position every prior release put it in.
-        return f"{head}, Bandgap: {params[3]} mV"
+        return f"{head}, Bandgap: {params[3]} mV, Bandgap count: {params[4]}"
 
     # Silkscreen-aware rendering for the two
     # boot-time INFO surfaces that carry the same revision byte as
@@ -136,6 +165,22 @@ def format_message(msg_id: int, params: List[Any], entry: MessageDef) -> str | N
         byte = params[0]
         return f"Physical HW: {_REVISION_SILKSCREEN.get(byte, f'Rev{byte}')}"
 
+    if msg_id == MSG_ERR_BAD_COMMAND and len(params) == 1:
+        code = params[0]
+        return f"Command refused: {REFUSALS.get(code, f'reason {code}')}"
+
+    if msg_id == MSG_INFO_REGISTERS and len(params) == 5:
+        return _render_registers(*params)
+
+    # The firmware sends millivolts; show volts. The catalog text (mV) is the
+    # fallback for any other shape.
+    if msg_id in (MSG_WARN_VPP_LOW_MV, MSG_WARN_VPP_HIGH_MV, MSG_ERR_VPP_HIGH_MV):
+        if len(params) == 2:
+            measured, expected = params
+            relation = "<" if msg_id == MSG_WARN_VPP_LOW_MV else ">"
+            state = "low" if msg_id == MSG_WARN_VPP_LOW_MV else "high"
+            return f"VPP is {state}: {volts(measured)} {relation} {volts(expected)}"
+
     if msg_id == MSG_INFO_CMD and len(params) == 1:
         cmd = params[0]
         name = COMMAND_NAMES.get(cmd)
@@ -244,27 +289,18 @@ def decode_id_frame(frame_len: int, body: bytes) -> LogMessage | None:
     # entries carry param_bytes == -1 in the catalog; for those we
     # cannot pre-validate, but _decode_param will surface any overrun
     # via IndexError below.
-    legacy_len = _LEGACY_PARAM_BYTES.get(msg_id)
-    is_legacy = legacy_len is not None and len(params_bytes) == legacy_len
-    if (
-        entry.param_bytes >= 0
-        and len(params_bytes) != entry.param_bytes
-        and not is_legacy
-    ):
+    if entry.param_bytes >= 0 and len(params_bytes) != entry.param_bytes:
         logger.warning(
             f"Param shape mismatch for ID 0x{msg_id:02x} ({entry.name}): "
             f"expected {entry.param_bytes} bytes, got {len(params_bytes)}"
         )
         return None
 
-    # Decode each param per the catalog grammar. A legacy short form stops
-    # at the end of its shorter param region.
+    # Decode each param per the catalog grammar.
     values: List[Any] = []  # noqa: UP006
     cursor = 0
     try:
         for ptype, _prender in entry.params:
-            if is_legacy and cursor >= len(params_bytes):
-                break
             value, cursor = _decode_param(ptype, params_bytes, cursor)
             values.append(value)
     except (IndexError, struct.error, ValueError) as exc:
@@ -295,15 +331,19 @@ def decode_id_frame(frame_len: int, body: bytes) -> LogMessage | None:
 
     # Extract raw-bytes payload for MSG_DATA_CHUNK (W-04) so the chip-read
     # loop can obtain the chip data without a second read call.
-    chunk_payload = None
+    payload = None
     if (
         msg_id == MSG_DATA_CHUNK
         and values
         and isinstance(values[0], (bytes, bytearray))
     ):
-        chunk_payload = bytes(values[0])
+        payload = bytes(values[0])
 
     severity_label = SEVERITY_LABEL.get(entry.severity, f"SEV{entry.severity}")
     return LogMessage(
-        severity=severity_label, text=text, id=msg_id, payload=chunk_payload
+        severity=severity_label,
+        text=text,
+        id=msg_id,
+        payload=payload,
+        params=tuple(values),
     )