Param Store Metadata Reference

This document describes the structure of the dictionary returned by ParamResolver.describe_symbol(). The same schema is used by diagnostics (e.g. scripts/tests/test_param_store_flow.py) and by Home Assistant adapters when interpreting dynamic metadata from the BragerOne assets.

The reference below follows Python typing notation and highlights how each field should be interpreted.

Top-level keys

symbol (str)

The original routing token such as "PARAM_66" or "URUCHOMIENIE_KOTLA".

pool (str | None)

Pool identifier extracted from the asset map (for example "P6"). Absent when the asset does not expose a canonical pool.

idx (int | None)

Channel index within the pool. None when no concrete address could be resolved.

chan (str | None)

Preferred channel letter ("v", "s", "u" …) inferred from the mapping. None when detection failed.

label (str | None)

Localised label resolved from the parameters i18n namespace.

unit (str | dict[str, str] | None)

Human-readable unit or enumeration mapping. The formatter first inspects the live value (ParamFamilyModel.unit_code) and falls back to the asset metadata. Enumeration dictionaries always map stringified codes to translated labels.

value (Any)

Latest stored value from REST prime or WebSocket updates. May be None when the device has not yet provided a reading.

unit_code (Any)

Raw unit channel value cached in ParamFamilyModel. Useful for lower-level integrations that need the code before translation.

min / max (Any)

Cached min/max raw channels when present. Integrators should treat these as advisory limits, not strict validation rules.

status (Any)

Raw status channel payload, typically a bitfield integer. Combine with mapping.status_conditions or mapping.status_flags for semantics.

mapping_origin (str | None)

Origin string recorded by the catalog ("asset:<url>" or "inline:index"). Handy for debugging asset regressions.

mapping (dict[str, Any] | None)

Structured metadata extracted from the asset catalog. When None the catalog did not yield a mapping (rare).

Mapping dictionary

component_type (str | None)

Sanitised component identifier (for example "SWITCH"). Prefixes such as "u." or "t." are stripped for readability.

channels (dict[str, list[ChannelDescriptor]])

Cleaned channel descriptors grouped by logical purpose. Keys include "value", "command", "unit", "status", "min" and "max". Each descriptor in the list has the shape described below.

paths (dict[str, list[dict[str, Any]]])

Raw paths exactly as returned by the catalog. These retain all original keys and are mainly useful when debugging parser edge cases.

status_conditions (dict[str, list[ChannelDescriptor]])

Human-readable mapping of status condition names to the channels/bits that drive them. Condition names are unprefixed ("INVISIBLE" instead of "[t.INVISIBLE]"). ChannelDescriptor entries reuse the same schema as channels but always include the bit that triggers the condition.

limits (dict[str, Any] | None)

Optional limit metadata present in some assets (for example structured ranges or validation rules). Contents are asset-defined; treat as a free form dictionary.

status_flags (list[Any])

Sanitised list of auxiliary status definitions. String entries are cleaned from helper prefixes, dictionaries retain unknown keys but have their name field normalised.

command_rules (list[CommandRule])

Normalised automation logic extracted from any/all/when blocks inside the asset. Each rule describes a command that the UI may issue when specific conditions are met. The CommandRule schema is described below.

units_source (str | int | float | None)

Raw unit code stored in the asset map prior to localisation. When the value is a string it is also cleaned from helper prefixes.

origin (str)

Same as mapping_origin for convenience.

raw (dict[str, Any])

Untouched asset payload. Kept for debugging and future i18n enrichment.

ChannelDescriptor schema

channel (str)

Fully qualified address ("P6.v66"). This is the preferred key for downstream logic.

address (str)

Duplicate of channel kept for backwards compatibility.

bit (int | None)

Bit index for boolean/status channels. Absent for value/unit paths.

condition (str | None)

Condition name the entry belongs to (only present when the entry is linked with status_conditions).

CommandRule schema

logic (str)

Source branch within the asset ("any", "all" or "when").

kind (str)

Branch type ("if", "elseif" or "else") mirroring the original control flow.

command (str)

Normalised command identifier without the "o." prefix.

value (Any)

Optional value sent with the command. Logical constants (true/false) are already converted to Python bool.

conditions (list[ConditionDescriptor])

Evaluated guards for the rule. Empty when the branch was an unconditional else.

ConditionDescriptor schema

operation (str | None)

Sanitised operator name (for example "equalTo" or "notEqualTo").

expected (Any)

Value used by the comparison. void 0 and undefined become None; logical negations (!0/!1) map to booleans.

targets (list[ChannelDescriptor]])

Target addresses checked by the condition. Each entry mirrors the ChannelDescriptor schema (sans condition) and is ready to be mapped onto live ParamStore values.

Usage guidelines

• Prefer channel over address when consuming path entries – it already contains the cleaned P?.c? notation.

• Combine status with status_conditions to derive entity states. Each condition describes the bit required to mark the state as active.

• To simulate UI actions (for example resetting the fuel level), locate the relevant entry under command_rules and apply the listed condition checks before issuing the matching command with its value.

• Preserve raw when caching data for offline analysis – upstream asset changes can be re-parsed without fetching everything again.