Configuration

Parsing of the controller's ConfigurationTable (C.O. 24575) and bulk decode of ValuesAll / SetpointsAll blobs. The Controller calls these internally — you only need them directly when working with raw blobs.

Descriptions

pycomap.configuration.ValueDescription `dataclass`

ValueDescription(
    number: int,
    category: ValueCategory,
    data_type: DataType,
    data_length: int,
    decimal_places: int,
    data_index: int,
    state_index: int | None,
    name: str,
    dimension: str,
    group: str | None,
    low_limit: int,
    high_limit: int,
    var_low_limit: bool,
    var_high_limit: bool,
    bit_name_index: int | None,
)

One entry from the controller's ConfigurationTable describing a single value.

pycomap.configuration.SetpointDescription `dataclass`

SetpointDescription(
    number: int,
    category: SetpointCategory,
    data_type: DataType,
    data_length: int,
    decimal_places: int,
    data_index: int,
    name: str,
    dimension: str,
    group: str | None,
    access_level: int,
    low_limit: int,
    high_limit: int,
    var_low_limit: bool,
    var_high_limit: bool,
)

One entry from the controller's ConfigurationTable describing a single setpoint.

needs_password `property`

needs_password: bool

True if writing this setpoint requires a password (access_level > 0).

pycomap.configuration.ValueState `dataclass`

ValueState(
    level1: ProtectionState,
    level2: ProtectionState,
    sensor_fail: ProtectionState,
)

Protection state for one value, decoded from a ValueStatesAll byte.

Each field is a ProtectionState flag combination — check for activity with state.level1 & ProtectionState.ACTIVE. NOT_CONFIRMED is a combinable flag: ACTIVE | NOT_CONFIRMED (value 6) means the alarm is active but not yet acknowledged by the operator pressing Fault Reset.

Source: ComAp.Controller.DataTypes.ValueState in ComAp.Controller.dll::

Level1     = bits 0-2, direct ProtectionState cast
Level2     = bits 3-5, direct ProtectionState cast
SensorFail = bits 6-7, left-shifted by 1 (raw 1 → ACTIVE, raw 2 → NOT_CONFIRMED)

any_alarm `property`

any_alarm: bool

True if any protection level or sensor failure is active.

pycomap.configuration.HistoryFieldDescription `dataclass`

HistoryFieldDescription(
    data_index: int, value: ValueDescription
)

One entry in the controller's history-snapshot field layout.

Describes where a single value's raw bytes sit within a HistoryRecord.data snapshot. This is a separate layout from ValuesAll -- data_index here is the byte offset within the 57-byte history snapshot, unrelated to value.data_index (which is the offset within ValuesAll/ValueStatesAndDataAll). See decode_history_snapshot.

Enums

pycomap.configuration.ValueCategory

Bases: IntEnum

ComAp ValueCategory enum.

FIRST/SECOND/THIRD are refresh-rate tiers (each with its own poll period, read from the table); ONE_TIME values aren't included in ValuesAll/ ValueStatesAndDataAll at all.

pycomap.configuration.SetpointCategory

Bases: IntEnum

ComAp SetpointCategory enum. Unlike values, every setpoint is included in SetpointsAll regardless of category, and setpoints have no associated state.

pycomap.configuration.NamesCategory

Bases: Enum

Subset of ComAp's NamesCategory enum -- only the categories needed to resolve a value's name/dimension/group, alarm reason/prefix, and history reason/prefix are implemented. Values are arbitrary (used only as a dict key into _NAMES_CATEGORY_LAYOUT), not wire values.

Functions

pycomap.configuration.parse_configuration_table

parse_configuration_table(
    data: bytes,
) -> ConfigurationTable

Parse the value-description section of a raw ConfigurationTable blob.

pycomap.configuration.parse_names_heap `cached`

parse_names_heap(
    data: bytes, category: NamesCategory
) -> list[str]

Decode one category of the controller's "unified names heap" (first/default language only). Returned list is indexed directly by a value record's name_index/ dim_index field.

pycomap.configuration.decode_values_all

decode_values_all(
    table: ConfigurationTable, data: bytes
) -> dict[int, RawValue]

Decode a ValuesAll (or the data portion of ValueStatesAndDataAll) blob.

Returns a mapping of value number -> decoded value for every ValueCategory.FIRST/SECOND/THIRD value. ONE_TIME values are excluded — they are not present in ValuesAll and must be read individually.

pycomap.configuration.decode_setpoints_all

decode_setpoints_all(
    table: ConfigurationTable, data: bytes
) -> dict[int, RawValue]

Decode a SetpointsAll blob into a mapping of setpoint number -> decoded value.

Unlike values, every setpoint (both P and R categories) is included.

pycomap.configuration.decode_states_all

decode_states_all(
    table: ConfigurationTable, data: bytes
) -> dict[int, ValueState]

Decode a ValueStatesAll blob (or the state portion of ValueStatesAndDataAll).

Returns a mapping of value number -> ValueState for every value that has a state_index (i.e. ValueDescription.state_index is not None). Values with no state (state_index is None) are omitted.

For ValueStatesAndDataAll (C.O. 24529): the blob is the data region (size = max data_index + data_length across non-OneTime values) followed immediately by the state region — pass only the state suffix to this function, or slice it yourself: data[data_region_size:].

pycomap.configuration.decode_history_snapshot

decode_history_snapshot(
    table: ConfigurationTable, snapshot: bytes
) -> dict[int, RawValue]

Decode the value snapshot from a HistoryRecord.data field.

Alarm/event history records carry a fixed-format snapshot of a specific set of values (RPM, voltages, frequencies, battery voltage, binary I/O, mode, ...), captured at the moment the event occurred. This layout is defined by the controller's own HistoryDescriptionCollection (table.history_fields -- a separate section of the ConfigurationTable, unrelated to ValuesAll's per-value data_index) rather than being a truncated copy of ValuesAll. Verified field-for-field against a live controller's WebSupervisor history view.

Returns {number: decoded_value} for every history field that fits within len(snapshot), using the same type/decimal-places decoding as decode_values_all. Returns an empty dict if snapshot is empty (text records).