Subsystem JSON updaters

This section documents the Subsystem JSON Updaters framework.

The updaters provide a registry-driven mechanism for applying interface-version specific JSON transformations per:

  • telescope (mid/low)

  • command (configure/assign/scan/…)

  • subsystem (csp/sdp/dish/mccs/…)

Package

Subsystem JSON updaters used by SubarrayNode commands.

The updaters package provides a (telescope, command, subsystem, interface_version) registry of pluggable transformation steps so that interface-version-specific logic does not live inside command classes.

See README.md in this directory for contributor guidance.

class ska_tmc_subarraynode.commands.updaters.SubsystemUpdater

Bases: ABC

Pure transformation step for a subsystem JSON.

Subclasses must:

  • set the class attribute key: UpdaterKey

  • implement update()

key
abstract update(payload, context)

Return (result_code, updated_payload, message).

Return type

Tuple[ResultCode, Dict[str, Any], str]

class ska_tmc_subarraynode.commands.updaters.UpdaterContext(snapshot=<factory>, extras=<factory>)

Bases: object

Runtime context passed to every updater.

This context should contain data only (no Tango proxies and no component manager object). The command layer should construct a snapshot of the required values and pass it to the pipeline.

snapshot

Dictionary-like structure with context values required by updaters (e.g. subarray_id, delay_model_subscription_point, array_centre_coord).

extras

Optional free-form dict for one-off values.

extras
snapshot
class ska_tmc_subarraynode.commands.updaters.UpdaterKey(telescope, command, subsystem, iface_major=0, iface_minor=0)

Bases: object

Identity of an updater rule.

iface_major / iface_minor represent the minimum interface version the rule applies to. The registry activates every rule whose minimum is <= the actual interface version of the incoming payload.

command
iface_major = 0
iface_minor = 0
subsystem
telescope
class ska_tmc_subarraynode.commands.updaters.UpdaterRegistry

Bases: object

Stores updater instances and resolves the ordered list applicable to a given (telescope, command, subsystem, interface_version).

register(updater)

Register an updater instance under its key triple.

Return type

None

resolve(telescope, command, subsystem, iface_major, iface_minor)

Return updaters applicable to the given interface version.

Updaters are ordered by ascending version so newer rules apply last.

Parameters

  • telescope (str) – Telescope identifier used to select updater rules.

  • command (str) – Command name used to select updater rules.

  • subsystem (str) – Subsystem identifier used to select updater rules.

  • iface_major (int) – Target interface major version.

  • iface_minor (int) – Target interface minor version.

Return type

List[SubsystemUpdater]

Returns

Updaters applicable to the given interface version, ordered by ascending version so newer rules apply last.

ska_tmc_subarraynode.commands.updaters.apply_updaters(telescope, command, subsystem, payload, context)

Run all matching updaters in version order. Stops on first FAILED.

The interface version is read from payload["interface"] if available, otherwise (0, 0) is assumed which matches always-applicable rules only.

Parameters

  • telescope (str) – Telescope identifier used to select updater rules.

  • command (str) – Command name used to select updater rules.

  • subsystem (str) – Subsystem identifier used to select updater rules.

  • payload (Dict[str, Any]) – Input payload to be updated in-place/returned updated.

  • context (UpdaterContext) – Updater execution context (e.g., logging, config).

Return type

Tuple[ResultCode, Dict[str, Any], str]

Returns

A tuple of (result_code, payload, message). The payload may be modified by updaters. The message is non-empty on failure.

Core modules

Base classes for subsystem updaters.

class ska_tmc_subarraynode.commands.updaters.base.SubsystemUpdater

Bases: ABC

Pure transformation step for a subsystem JSON.

Subclasses must:

  • set the class attribute key: UpdaterKey

  • implement update()

key
abstract update(payload, context)

Return (result_code, updated_payload, message).

Return type

Tuple[ResultCode, Dict[str, Any], str]

class ska_tmc_subarraynode.commands.updaters.base.UpdaterContext(snapshot=<factory>, extras=<factory>)

Bases: object

Runtime context passed to every updater.

This context should contain data only (no Tango proxies and no component manager object). The command layer should construct a snapshot of the required values and pass it to the pipeline.

snapshot

Dictionary-like structure with context values required by updaters (e.g. subarray_id, delay_model_subscription_point, array_centre_coord).

extras

Optional free-form dict for one-off values.

extras
snapshot
class ska_tmc_subarraynode.commands.updaters.base.UpdaterKey(telescope, command, subsystem, iface_major=0, iface_minor=0)

Bases: object

Identity of an updater rule.

iface_major / iface_minor represent the minimum interface version the rule applies to. The registry activates every rule whose minimum is <= the actual interface version of the incoming payload.

command
iface_major = 0
iface_minor = 0
subsystem
telescope

Registry of SubsystemUpdater rules.

Keyed by (telescope, command, subsystem).

class ska_tmc_subarraynode.commands.updaters.registry.UpdaterRegistry

Bases: object

Stores updater instances and resolves the ordered list applicable to a given (telescope, command, subsystem, interface_version).

register(updater)

Register an updater instance under its key triple.

Return type

None

resolve(telescope, command, subsystem, iface_major, iface_minor)

Return updaters applicable to the given interface version.

Updaters are ordered by ascending version so newer rules apply last.

Parameters

  • telescope (str) – Telescope identifier used to select updater rules.

  • command (str) – Command name used to select updater rules.

  • subsystem (str) – Subsystem identifier used to select updater rules.

  • iface_major (int) – Target interface major version.

  • iface_minor (int) – Target interface minor version.

Return type

List[SubsystemUpdater]

Returns

Updaters applicable to the given interface version, ordered by ascending version so newer rules apply last.

Helper to apply matching updaters for (telescope, command, subsystem).

ska_tmc_subarraynode.commands.updaters.pipeline.apply_updaters(telescope, command, subsystem, payload, context)

Run all matching updaters in version order. Stops on first FAILED.

The interface version is read from payload["interface"] if available, otherwise (0, 0) is assumed which matches always-applicable rules only.

Parameters

  • telescope (str) – Telescope identifier used to select updater rules.

  • command (str) – Command name used to select updater rules.

  • subsystem (str) – Subsystem identifier used to select updater rules.

  • payload (Dict[str, Any]) – Input payload to be updated in-place/returned updated.

  • context (UpdaterContext) – Updater execution context (e.g., logging, config).

Return type

Tuple[ResultCode, Dict[str, Any], str]

Returns

A tuple of (result_code, payload, message). The payload may be modified by updaters. The message is non-empty on failure.

MID / Configure / CSP rules

MID Configure CSP updater rules.

Each rule maps a version-dependent block that used to live in ConfigureMid._configure_csp.

class ska_tmc_subarraynode.commands.updaters.mid.configure.csp.CspMidConfigureBand5DC

Bases: SubsystemUpdater

Lift band-5 downconversion subband from Dish to CSP common.

key = UpdaterKey(telescope='mid', command='configure', subsystem='csp', iface_major=0, iface_minor=0)
update(payload, context)

Copy Dish band5_downconversion_subband into csp.common.

Args:

payload: Configure payload to update in-place. context: Updater context (unused).

Return type

Tuple[ResultCode, Dict[str, Any], str]

Returns

A tuple of (ResultCode, updated payload, message).

class ska_tmc_subarraynode.commands.updaters.mid.configure.csp.CspMidConfigureLegacy

Bases: SubsystemUpdater

Legacy TMC (<4.0): inject delay model subscription into csp.cbf.

key = UpdaterKey(telescope='mid', command='configure', subsystem='csp', iface_major=0, iface_minor=0)
update(payload, context)

For TMC<4.0, set csp.cbf.delay_model_subscription_point.

Parameters

  • payload (Dict[str, Any]) – Configure payload to update in-place.

  • context (UpdaterContext) – Updater context providing snapshot values.

Return type

Tuple[ResultCode, Dict[str, Any], str]

Returns

A tuple of (ResultCode, updated payload, message).

class ska_tmc_subarraynode.commands.updaters.mid.configure.csp.CspMidConfigureV4

Bases: SubsystemUpdater

ADR-99 for TMC>=4.0 and CSP>=0.4.

Injects subarray_id and delay model subscription. Updates correlation output_link_map.

key = UpdaterKey(telescope='mid', command='configure', subsystem='csp', iface_major=4, iface_minor=0)
update(payload, context)

Apply ADR-99 shaping to the CSP configure payload.

Parameters

  • payload (Dict[str, Any]) – CSP configure payload to update.

  • context (UpdaterContext) – Updater context providing snapshot values.

Return type

Tuple[ResultCode, Dict[str, Any], str]

Returns

(ResultCode, payload, message).

class ska_tmc_subarraynode.commands.updaters.mid.configure.csp.CspMidConfigureV6Pst

Bases: SubsystemUpdater

For TMC>=6.0: inject PST delay_centre and apply PST BF defaults.

key = UpdaterKey(telescope='mid', command='configure', subsystem='csp', iface_major=6, iface_minor=0)
update(payload, context)

Inject PST delay_centre and hardcode temporary PST BF keys.

Parameters

  • payload (Dict[str, Any]) – CSP configure JSON to update in-place.

  • context (UpdaterContext) – Updater context with snapshot data.

Return type

Tuple[ResultCode, Dict[str, Any], str]

Returns

(ResultCode, payload, message). Returns FAILED if PST config exists but array_centre_coord is missing.