lockwire 0.2.0__py3-none-any.whl

lockwire/cli_line.py

@@ -0,0 +1,73 @@
+"""One function that turns a command's parts into a shell-safe line.
+
+Every door that prints or returns a paste-able ``lockwire ...`` command
+composes its parts here — the CLI's own ``ran:`` lines, the ``gui``/``start``
+page footer's line, and ``scan.py``'s docker ``bash -lc`` line — so there is
+exactly one place quoting can go wrong, and it uses ``shlex.quote`` (stdlib),
+not hand-rolled or Python (``repr``/``!r``) quoting.
+"""
+
+from __future__ import annotations
+
+import shlex
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import typer
+
+
+def cli_line(*parts: object) -> str:
+    """Shell-quote every part and join with spaces.
+
+    Callers that want a literal ``lockwire ...`` line to paste back in pass
+    ``"lockwire"`` as the first part themselves; this function only quotes
+    and joins.
+    """
+    return " ".join(shlex.quote(str(part)) for part in parts)
+
+
+def argv_from_context(ctx: "typer.Context", exclude: "set[str] | None" = None) -> list[str]:
+    """Rebuild the argv actually typed for this invocation.
+
+    Walks the command's own parameters (``ctx.command.params``) and each
+    one's source (``ctx.get_parameter_source``), including only what the
+    user actually passed on the command line — instead of a hand-written
+    flag list, which is exactly how ``add`` dropped its value flags,
+    how ``scene import`` dropped ``--package-root``, and how ``declare``
+    dropped ``--note``/``--locked-at``.
+
+    Bools carry their own hazard and get their own handling: a true flag
+    emits its option, a false one emits its ``--no-...`` form if it has one
+    and otherwise **nothing**. Both directions matter — a replayed
+    ``apply --dry-run`` line that lost the flag performs a real write, and a
+    line that grew a ``--dry-run`` nobody typed describes a run that wrote
+    nothing when the real one wrote.
+
+    ``exclude`` names parameters the caller renders itself; the only one in
+    the tree is ``gui``'s ``--out``, deliberately printed as ``<this file>``
+    so the page's bytes do not depend on its own filename.
+    """
+    argv: list[str] = []
+    skip = exclude or set()
+    for param in ctx.command.params:
+        if param.name in skip:
+            continue
+        source = ctx.get_parameter_source(param.name)
+        if source is None or source.name != "COMMANDLINE":
+            continue
+        value = ctx.params[param.name]
+        if param.param_type_name == "argument":
+            argv.append(str(value))
+        elif isinstance(value, bool):
+            if value:
+                argv.append(param.opts[0])
+            elif param.secondary_opts:
+                argv.append(param.secondary_opts[0])
+        elif isinstance(value, (list, tuple)):
+            for item in value:
+                argv.append(param.opts[0])
+                argv.append(str(item))
+        else:
+            argv.append(param.opts[0])
+            argv.append(str(value))
+    return argv

lockwire/constraints.py

@@ -0,0 +1,313 @@
+"""the constraints each part participates in, for the app's badges and margin bars.
+
+One row per constraint instance the engine evaluates. Numbers are the checks' own:
+``report_html._budget_rows`` for budgets (itself ``power_rollup``), ``power_rollup`` for rail
+current, the same drivers x bit/s sum for buses, the same torque/thermal arithmetic. A row with
+no used or limit value is ``unset`` rather than a guess. No second scorer, no schema change.
+
+Domain mapping (the graph lens ids stay as they are): lens ``mechanical`` -> "mechanical",
+lens ``power`` -> "electrical", lens ``data`` -> "data", lens ``health`` -> "health";
+thermal has no lens and gets its own "thermal".
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from lockwire.checks import BUS_UTILIZATION_CEILING, _device_worst_draw_w, power_rollup
+from lockwire.scene_view import _bus_consumers, _rail_consumers
+from lockwire.schema import Contract
+
+#: Under this much headroom (percent of the limit) an in-limits constraint is "warn".
+WARN_MARGIN_PCT = 10.0
+
+_HEALTH_STATUS = {
+    "healthy": "ok",
+    "degrading": "warn",
+    "stale": "warn",
+    "faulty": "bad",
+    "watched": "unset",
+    "not_watched": "unset",
+}
+
+
+def _row(
+    id_: str,
+    label: str,
+    domain: str,
+    *,
+    used: float | None,
+    limit: float | None,
+    unit: str,
+    used_kind: str | None,
+    limit_kind: str | None,
+    components: list[str],
+    direction: str = "max",
+    over: bool | None = None,
+    scale: float | None = None,
+) -> dict[str, Any]:
+    """``over`` overrides the used-vs-limit comparison (a budget's own verdict);
+    ``scale`` is the margin's denominator (default: the limit)."""
+    margin: float | None = None
+    if used is not None and limit is not None and (scale or limit) > 0:
+        gap = limit - used if direction == "max" else used - limit
+        margin = round(gap / (scale or limit) * 100.0, 1)
+    if margin is None and over is None:
+        status = "unset"
+    elif over or (over is None and margin is not None and margin < 0):
+        status = "bad"
+    elif margin is not None and margin < WARN_MARGIN_PCT:
+        status = "warn"
+    else:
+        status = "ok" if margin is not None else "unset"
+    return {
+        "id": id_,
+        "label": label,
+        "domain": domain,
+        "used": used,
+        "limit": limit,
+        "unit": unit,
+        "margin_pct": margin,
+        "status": status,
+        "used_kind": used_kind if used is not None else None,
+        "limit_kind": limit_kind if limit is not None else None,
+        "parts": [],
+        "components": list(dict.fromkeys(components)),
+    }
+
+
+def _budget_constraints(contract: Contract, budgets: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    out = []
+    by_id = {b.id: b for b in contract.budgets}
+    for row in budgets:
+        budget = by_id[row["id"]]
+        components: list[str] = []
+        if budget.kind == "rail_power" and budget.rail:
+            components = [budget.rail, *sorted(_rail_consumers(contract, budget.rail))]
+        elif budget.kind == "mass_total":
+            if budget.sources in ("devices", "links+devices"):
+                components += [
+                    d.id
+                    for d in contract.devices
+                    if d.physical is not None and d.physical.mass is not None
+                ]
+            if budget.sources in ("links", "links+devices") and contract.model is not None:
+                components += [ln.name for ln in contract.model.links if ln.mass is not None]
+        label = {"rail_power": "Rail power", "mass_total": "Mass", "endurance": "Endurance"}[
+            budget.kind
+        ]
+        out.append(
+            _row(
+                f"budget.{row['id']}",
+                label,
+                "mechanical" if budget.kind == "mass_total" else "electrical",
+                used=row["value"],
+                limit=row["limit"],
+                unit=row["unit"],
+                used_kind="derived",
+                limit_kind="declared",
+                components=components,
+                direction=row["direction"],
+                over=True if row["state"] == "breach" else None if row["value"] is None else False,
+            )
+        )
+    return out
+
+
+def _rail_current_constraints(contract: Contract) -> list[dict[str, Any]]:
+    if contract.topology is None:
+        return []
+    totals, witnesses, _, _, unknown, _ = power_rollup(contract, "nominal")
+    out = []
+    for rail in contract.topology.rails:
+        if rail.current_limit is None:
+            continue
+        volts = (
+            rail.voltage_range.min.base()
+            if rail.voltage_range is not None
+            else rail.voltage.base()
+            if rail.voltage is not None
+            else None
+        )
+        summable = volts and witnesses.get(rail.id) and not unknown.get(rail.id)
+        out.append(
+            _row(
+                f"rail-current.{rail.id}",
+                "Rail current",
+                "electrical",
+                used=totals.get(rail.id, 0.0) / volts if summable else None,
+                limit=rail.current_limit.base(),
+                unit="A",
+                used_kind="derived",
+                limit_kind="declared",
+                components=[rail.id, *sorted(_rail_consumers(contract, rail.id))],
+            )
+        )
+    return out
+
+
+def _bus_constraints(contract: Contract) -> list[dict[str, Any]]:
+    out = []
+    for bus in contract.topology.buses if contract.topology is not None else []:
+        drivers = [
+            d
+            for d in contract.devices
+            if d.identity is not None
+            and d.identity.bus_ref == bus.id
+            and d.driver is not None
+            and d.driver.nominal_rate_hz is not None
+            and d.driver.payload_bytes is not None
+        ]
+        used = sum(d.driver.nominal_rate_hz * d.driver.payload_bytes * 8 for d in drivers)
+        out.append(
+            _row(
+                f"bus.{bus.id}",
+                "Bus bandwidth",
+                "data",
+                used=used if used > 0 else None,
+                limit=bus.bitrate * BUS_UTILIZATION_CEILING if bus.bitrate else None,
+                unit="bit/s",
+                used_kind="derived",
+                limit_kind="derived",
+                components=[bus.id, *sorted(_bus_consumers(contract, bus.id))],
+            )
+        )
+    return out
+
+
+def _joint_constraints(contract: Contract) -> list[dict[str, Any]]:
+    if contract.model is None:
+        return []
+    out = []
+    driver = {d.drives_joint: d for d in contract.devices if d.drives_joint is not None}
+    for joint in contract.model.joints:
+        lim = joint.limits
+        if lim is None or joint.type == "fixed":
+            continue
+        rot = joint.type in ("revolute", "continuous")
+        dev = driver.get(joint.name)
+        model = contract.device_model(dev.model) if dev is not None else None
+        act = model.actuator if model is not None else None
+        comps = [joint.name, joint.child, *([dev.id] if dev is not None else [])]
+        if lim.effort is not None:  # <= 0 is URDF's "unset": still a row, used=None
+            have = act is not None and act.torque_continuous and act.gear_ratio
+            out.append(
+                _row(
+                    f"joint-torque.{joint.name}",
+                    "Joint torque",
+                    "mechanical",
+                    used=lim.effort_limit,
+                    limit=act.torque_continuous * act.gear_ratio if have else None,
+                    unit="N*m" if rot else "N",
+                    used_kind="declared",
+                    limit_kind="derived",
+                    components=comps,
+                )
+            )
+        if lim.velocity is not None:
+            out.append(
+                _row(
+                    f"joint-speed.{joint.name}",
+                    "Joint speed",
+                    "mechanical",
+                    used=None,
+                    limit=lim.velocity if lim.velocity > 0 else None,  # 0 = unset
+                    unit="rad/s" if rot else "m/s",
+                    used_kind=None,
+                    limit_kind="declared",
+                    components=comps,
+                )
+            )
+        if lim.lower is not None and lim.upper is not None and joint.type != "continuous":
+            out.append(
+                _row(
+                    f"joint-travel.{joint.name}",
+                    "Joint travel",
+                    "mechanical",
+                    used=None,
+                    limit=lim.upper - lim.lower,
+                    unit="rad" if rot else "m",
+                    used_kind=None,
+                    limit_kind="derived",
+                    components=comps,
+                )
+            )
+    return out
+
+
+def _thermal_constraints(contract: Contract) -> list[dict[str, Any]]:
+    out = []
+    for device in contract.devices:
+        model = contract.device_model(device.model)
+        limit = model.thermal_limit if model is not None else None
+        if limit is None:
+            continue
+        t, draw = device.thermal, _device_worst_draw_w(device)
+        used = None
+        if (
+            limit.kind == "throttle"
+            and t is not None
+            and t.resistance is not None
+            and t.ambient is not None
+            and draw is not None
+        ):
+            used = t.ambient.base() + draw[0] * t.resistance.base()
+        limit_c = limit.temperature.base()
+        out.append(
+            _row(
+                f"thermal.{device.id}",
+                "Junction temp",
+                "thermal",
+                used=used,
+                limit=limit_c,
+                unit="C",
+                used_kind="derived",
+                limit_kind="declared",
+                components=[device.id],
+                # the check fires at estimate >= limit, so the cap is "over" at equality
+                over=None if used is None else used >= limit_c,
+                scale=limit_c + 273.15,  # percent of absolute temperature, not of a Celsius figure
+            )
+        )
+    return out
+
+
+def _health_constraints(health_devices: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+    return [
+        {
+            **_row(
+                f"health.{h['id']}",
+                "Health",
+                "health",
+                used=None,
+                limit=None,
+                unit="",
+                used_kind=None,
+                limit_kind=None,
+                components=[h["id"]],
+            ),
+            "status": _HEALTH_STATUS.get(h["state"], "unset"),
+        }
+        for h in health_devices or []
+    ]
+
+
+def constraint_rows(
+    contract: Contract,
+    budgets: list[dict[str, Any]],
+    *,
+    health_devices: list[dict[str, Any]] | None = None,
+    scene_part_ids: set[str] | None = None,
+) -> list[dict[str, Any]]:
+    """``parts`` is ``components`` narrowed to ids that have a scene part."""
+    rows = [
+        *_budget_constraints(contract, budgets),
+        *_rail_current_constraints(contract),
+        *_bus_constraints(contract),
+        *_joint_constraints(contract),
+        *_thermal_constraints(contract),
+        *_health_constraints(health_devices),
+    ]
+    for row in rows:
+        row["parts"] = [c for c in row["components"] if c in (scene_part_ids or ())]
+    return rows

lockwire/copy.py

@@ -0,0 +1,302 @@
+"""The one plain-words map: check labels and human part names.
+
+A label is <= 6 everyday words, no snake_case, no ids. Anything the app shows as a row
+title or chip comes from here (via gui.py), so the app never parses a contract path.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Path segments that only say where a thing lives, never what was checked.
+STRUCTURE = frozenset(
+    {
+        "scene",
+        "devices",
+        "buses",
+        "rails",
+        "hosts",
+        "budgets",
+        "signals",
+        "envelopes",
+        "links",
+        "joints",
+        "cross_signal",
+        "coverage",
+        "stage",
+        "plan",
+        "preflight",
+        "steps",
+        "topology",
+        "wires",
+        "live",
+        "physical",
+        "timestamps",
+        "provenance",
+        "actuator_cases",
+        "device_models",
+        "health",
+        "identity",
+        "driver",
+    }
+)
+
+# Matched against the trailing non-structure segments, longest first.
+CHECK_LABELS: dict[str, str] = {
+    "budgets": "Budget total",
+    "variance": "Signal not frozen",
+    "range": "Reading in range",
+    "nan": "No bad readings",
+    "hard_limit": "Within hard limit",
+    "rate_hz": "Update rate",
+    "recv_gap": "Gaps between messages",
+    "enumeration": "Device seen",
+    "liveness": "Device alive",
+    "liveness/topic": "Topic alive",
+    "sustained_rate_liveness": "Stays alive",
+    "thermal": "Temperature",
+    "rail": "Power rail",
+    "stationary_|g|": "IMU at rest",
+    "redundant_sensors": "Sensors agree",
+    "camera_histogram": "Camera image sane",
+    "flow": "Data flowing",
+    "cross_record": "Records agree",
+    "conditions": "Conditions match",
+    "monotonicity/live_path": "Clock moves forward",
+    "wall_clock_currency": "Clock is current",
+    "recording": "Recording present",
+    "record": "Commands recorded",
+    "channel": "Commands on channel",
+    "in_recording": "Commands in recording",
+    "mass": "Mass declared",
+    "mount_frame": "Mount frame",
+    "mount_xyz": "Mount position",
+    "mount_shape": "Mount shape",
+    "upstream": "Rail source",
+    "voltage": "Rail voltage",
+    "current_limit": "Current limit",
+    "efficiency": "Converter efficiency",
+    "charged_by": "Charged by",
+    "ampacity": "Wire current",
+    "bandwidth": "Bus load",
+    "host": "Host link",
+    "bus_ref": "Bus link",
+    "structure_hash": "CAD file linked",
+    "placement": "Placement",
+    "drives_joint": "Joint driven",
+    "limit": "Budget limit",
+    "cg": "Centre of gravity",
+    "effort": "Joint effort",
+    "origin/xyz": "Joint position",
+    "origin/rpy": "Joint angles",
+    "parent": "Joint parent",
+    "model": "Device model",
+    "owner": "Owner",
+    "unclaimed": "Part not declared",
+    "scored": "Checks compared",
+    "rail_load": "Rail load",
+    "rail_load/rail": "Rail load",
+    "joint_target/effort": "Joint effort",
+    "joint_target": "Joint target",
+    "link_budget": "Radio link",
+    "serial_number": "Serial number",
+    "family": "Device family",
+    "evidence": "Test evidence",
+    "i2c-sysfs": "I2C bus read",
+    "device-tree": "Device tree read",
+    "comm_links_under_representative_load": "Comm links under load",
+    "live_hardware_software_reconciliation": "Hardware matches software",
+    "dds_requested_deadline": "Message deadline",
+    "compared_from": "Compared from",
+    "stationary_g": "IMU at rest",
+}
+
+
+def check_label(quantity: str) -> str:
+    """The plain label of the check behind a contract path, e.g. "Update rate"."""
+    parts = quantity.split("/")
+    if "commands" in parts[:-1]:  # preflight/commands/<record|channel>/<command id>
+        parts = parts[parts.index("commands") + 1 : parts.index("commands") + 2]
+    words = [
+        p
+        for p in parts
+        if p not in STRUCTURE and not p.isdigit() and "." not in p and not p.startswith(("{", "<"))
+    ]
+    for size in (2, 1):
+        key = "/".join(words[-size:])
+        if len(words) >= size and key in CHECK_LABELS:
+            return CHECK_LABELS[key]
+    if not words and parts[0] == "budgets":
+        # "bud.mass-model" -> "mass": the budget's own word, so two totals read differently.
+        kind = re.split(r"[.-]", parts[1].removeprefix("bud."))[0] if len(parts) > 1 else ""
+        return f"{CHECK_LABELS['budgets']} \u00b7 {kind}" if kind else CHECK_LABELS["budgets"]
+    # Unmapped: still readable, still no underscores (the test lists every known path).
+    last = (words[-1] if words else quantity.split("/")[-1]).replace("_", " ").replace("-", " ")
+    text = " ".join(last.replace("|", "").split())
+    return text[:1].upper() + text[1:] or "Check"
+
+
+ACRONYMS = {"imu", "esc", "gnss", "gps", "cpu", "can", "uart", "usb", "spi", "hbc"}
+_PART_NUMBER = re.compile(r"^[a-z]+-\d+-[a-z]", re.I)  # "icm-42688-p": one part number, keep its hyphens
+# ponytail: fixed list of the standard legged-robot convention (ANYmal); extend when another
+# convention shows up. Matched only on the upper-case token, as written in the id.
+LEG_CODES = {
+    "LF": "left front",
+    "RF": "right front",
+    "LH": "left hind",
+    "RH": "right hind",
+    "HAA": "hip abduction",
+    "HFE": "hip flexion",
+    "KFE": "knee",
+}
+
+
+def human_name(identifier: str) -> str:
+    """A person-readable part name from a contract id: "dev.adis_imu" -> "Adis IMU".
+
+    Drops the kind prefix, splits snake/kebab case, drops a word repeated as the last word
+    ("camera ... camera") and a word that opens the next one ("esc esc1" -> "ESC1"). Short
+    codes with a digit and known acronyms are upper-cased ("pm02" -> "PM02"); a long word with
+    a digit is split ("computer1" -> "Computer 1"); other words are title-cased.
+    """
+    for prefix in ("dev.", "rail.", "bus.", "bud.", "host.", "fam.", "mdl."):
+        if identifier.startswith(prefix):
+            identifier = identifier[len(prefix) :]
+    identifier = re.sub(r"(\d)([vV])\b", r"\1 V", identifier)
+    words: list[str] = []
+    for token in identifier.replace(".", " ").replace("_", " ").split():
+        words += [token] if _PART_NUMBER.match(token) else token.split("-")
+    words = [x for w in words for x in LEG_CODES.get(w, w).split() if w]
+    kept = [
+        w
+        for i, w in enumerate(words)
+        if not (w == words[-1] and i + 1 < len(words)) and not (len(w) >= 3 and i + 1 < len(words) and words[i + 1].startswith(w))
+    ]
+
+    def case(w: str) -> str:
+        if w.lower() in ACRONYMS:
+            return w.upper()
+        m = re.match(r"([a-z]{6,})(\d+)$", w, re.I)
+        if m:
+            return f"{m[1].capitalize()} {m[2]}"
+        if len(w) <= 11 and any(c.isdigit() for c in w):
+            return w.upper()
+        return w.capitalize()
+
+    return " ".join(case(w) for w in kept) or identifier
+
+
+_QUOTED = re.compile(r"'([^']+)'")
+
+
+def instead_row(text: str, kind: str) -> dict[str, str]:
+    """One short "Instead" row: a verb, the number, and the kind word. The quoted ids in the
+    engine's sentence become part names, and "derived-by-<check>" becomes "derived"."""
+    m = re.match(r"move the device to rail '([^']+)', which has (.+) free$", text)
+    if m:
+        short = f"Move to {human_name(m[1])} rail, {m[2]} free"
+    else:
+        m = re.match(r"add a (.+) regulator fed from rail '([^']+)'$", text)
+        if m:
+            short = f"Add {m[1]} regulator"
+        elif text.startswith("no other rail has headroom"):
+            short = "No other rail has room"
+        else:
+            short = _QUOTED.sub(lambda q: human_name(q[1]), text)
+            short = short[:1].upper() + short[1:]
+    return {"text": short, "kind": "derived" if kind.startswith("derived-by-") else kind}
+
+
+# Engine fix lines too long or too technical for the app, by their stable start.
+_PLAIN_FIX = (
+    ("declare the traffic each driver", "Declare each device's traffic on this bus"),
+    ("lock a cited bitrate", "Set this bus's speed from its datasheet"),
+    ("lock model provenance", "Re-lock the model file so changes are caught"),
+    ("restore the URDF", "Put the model file back, or fix its path"),
+    ("fill in the link's inertial", "Add this part's mass in the robot model"),
+    (
+        "declare the rail's voltage, or accept upstream",
+        "Declare the rail's voltage, or skip its voltage checks",
+    ),
+    (
+        "add device power witnesses or remove",
+        "Add each device's power use, or remove the empty budget",
+    ),
+    ("add power draws to devices", "Add each device's power use to see battery time"),
+    ("fix the driven-joint reference", "Fix the joint a device drives, or add the missing joint"),
+)
+
+
+def fix_text(action: str) -> str:
+    """The engine's fix line in plain words (Finding.action itself stays engineer text)."""
+    for start, plain in _PLAIN_FIX:
+        if action.startswith(start):
+            return plain
+    m = re.match(r"shed load on rail '([^']+)'", action)
+    if m:
+        return f"Use less power on {human_name(m[1])}, or raise its limit"
+    if action.startswith("remove mass or re-lock"):
+        return "Remove weight, or raise the weight limit"
+    text = _QUOTED.sub(lambda q: human_name(q[1]), action.replace(" with provenance", ""))
+    return text[:1].upper() + text[1:]
+
+
+# Row title for N repeats of one kind of finding, keyed by the trailing path shape.
+GROUP_TITLES: dict[str, str] = {
+    "drives_joint": "{n} drives unmapped",
+    "physical/mass": "{n} parts missing mass",
+    "placement": "{n} positions not declared",
+    "unclaimed": "{n} parts not declared",
+    "rate_hz": "{n} update rates off",
+    "recv_gap": "{n} devices gap out",
+    "enumeration": "{n} devices not seen",
+    "liveness": "{n} devices not alive",
+}
+
+
+def group_title(shape: str) -> str:
+    """The "{n} ..." row title for a repeated finding, or "" (group only identical titles)."""
+    for key, title in GROUP_TITLES.items():
+        if shape.endswith(key):
+            return title
+    return ""
+
+
+def commit_summary(message: str) -> str:
+    """A commit's first line as a sentence: no "docs:" prefix, first letter capital."""
+    line = message.strip().splitlines()[0] if message.strip() else ""
+    line = re.sub(r"^\w+(\([^)]*\))?!?:\s*", "", line)
+    return line[:1].upper() + line[1:]
+
+
+# Declare list: a value's plain name, from the tail of its contract path (longest tail wins).
+_VALUE_NAMES: dict[tuple[str, ...], str] = {
+    ("input_voltage_range", "min"): "Lowest voltage",
+    ("input_voltage_range", "max"): "Highest voltage",
+    ("voltage_range", "min"): "Lowest voltage",
+    ("voltage_range", "max"): "Highest voltage",
+    ("thermal_limit", "temperature"): "Temperature limit",
+    ("radio", "tx_power"): "Radio power",
+    ("radio", "rx_sensitivity"): "Radio sensitivity",
+    ("radio", "air_rate"): "Radio data rate",
+    ("runtime", "max_wall_time"): "Longest run time",
+    ("physical", "mass"): "Device mass",
+    ("mass",): "Model mass",  # a model link's own mass; the device on the same part says "Device mass"
+    ("physical", "mount_xyz"): "Mount position",
+    ("power", "draw"): "Power draw",
+    ("thermal", "resistance"): "Heat resistance",
+    ("thermal", "ambient"): "Surrounding temperature",
+    ("tx_antenna", "gain"): "Transmit antenna gain",
+    ("rx_antenna", "gain"): "Receive antenna gain",
+}
+
+
+def value_name(parts: tuple[str, ...]) -> str:
+    """"input_voltage_range/min" -> "Lowest voltage"; anything unmapped is just capitalised words."""
+    for n in (2, 1):
+        if (hit := _VALUE_NAMES.get(parts[-n:])) is not None and len(parts) >= n:
+            return hit
+    if parts[:1] == ("link_budget",) and len(parts) > 1:
+        parts = parts[1:]  # "link budget required range" -> "Required range"
+    text = " ".join(p.replace("_", " ") for p in parts)
+    return text[:1].upper() + text[1:]