Future Base Interface

Base interfaces for SKA Tango devices.

class ska_tango_base.future._base_interface.OpStateEmitMixin[source]

Bases: _BaseOpStateEmitMixin

A mixin class for a SKA base device or its component manager.

It provides helper methods for managing the Operational State of the device.

_update_op_state(**kwargs: Unpack[OpStateInput]) → None[source]

Emit a change in operational state.

This is a helper method for use by subclasses.

Parameters:: kwargs – key/values for state.

class ska_tango_base.future._base_interface.OpStateSignal[source]

Bases: Signal[DevState]

Special signal for Operational State.

Ensures that only valid enumerants from DevState for the SKA Operational State are emitted for the signal.

__init__() → None[source]: Initialise the signal.

class ska_tango_base.future._base_interface.BaseInterface[source]

Bases: OpStateEmitMixin, SignalBusMixin, SKADevice

Provides the Tango interface for a base SKA device with an Operational State.

This class only provides the Tango interface required for SKA Tango devices which support an Operational State. It is up to subclasses to override various abstract methods to provide the appropriate behaviour and set the Operational State as appropriate, except for the initial state that is set in init_device().

The Operational State of an SKA Tango device is exposed as the built-in Tango device state via set_state(). Subclasses are not expected to call set_state() themselves. Instead, the state is driven automatically by calling _update_op_state() with initialising or fault keyword arguments, which will additionally ensure that change and archive events are sent.

The Operational State of the BaseInterface only supports a subset of the DevState enumeration, with the following interpretations:

INIT: The device is initialising. Mandatory initial state for all devices.
ON: The Tango device is communicating with the system under control. Mandatory default state after initialisation has finished.
FAULT: The Tango device encountered a software fault/exception. Optional.

BaseInterface also provides the signals _admin_mode and _health_state as well as the corresponding Tango attributes adminMode and healthState, as well as healthInfo.

The adminMode Tango attribute is writable and should not be set by subclasses of this interface.

The healthState and healthInfo read-only attributes should be set by subclasses by calling report_health(). It is intended to provide information of the overall health of the device, based on the state of the component(s) it is monitoring.

_admin_mode: Signal[AdminMode]

Signal for the admin mode of the device.

Values are emitted for this signal whenever a client successfully changes to the adminMode attribute.

admin_mode_model: AdminModeModel: State model used to ensure that admin mode transitions are allowed.

adminMode: attribute_from_signal: Admin mode attribute of the device.

_op_state: OpStateSignal

Signal for the Operational State of the device.

Write to this signal to set the state of the Tango device.

_status: Signal[str]

Signal for the status of the device.

Write to this signal to set the status of the Tango device.

_health_state

Signal for the health state of the device.

This signal cannot be written to directly. Use the report_health() method instead.

healthState

Health state attribute of the device.

This should be set by subclasses of this interface by calling report_health().

healthInfo

A list of reasons why the device has a particular health state.

Should be an empty list when the healthState is HealthState.OK.

This should be set by subclasses of this interface by calling report_health().

init_device() → None[source]

Initialise the tango device after startup.

Subclasses overriding init_device() must call init_completed() once initialisation has finished.

Example

class MyDevice(BaseInterface):
    def init_device(self) -> None:
        super().init_device()
        ...
        self.init_completed()

init_invoked() → None[source]: Update operational state to reflect that initialisation has started.

init_completed() → None[source]

Update operational state to reflect that initialisation has completed.

Must be called from your init_device() method.

Example

class MyDevice(BaseInterface):
    def init_device(self) -> None:
        super().init_device()
        ...
        self.init_completed()

on_new_shared_bus() → None[source]: Enable manual event pushing for state and status.

dev_state() → DevState[source]: Override the device state method to prevent automatic ALARM state.

dev_status() → DevState[source]: Override the device status method to prevent automatic ALARM state.

_update_admin_mode(admin_mode: AdminMode) → None[source]

Update the admin mode of the device.

This helper method is passed to the admin mode model as a callback, so that the model can trigger actions in the Tango device.

Parameters:: admin_mode – the new admin mode value

read_adminMode() → AdminMode | tuple[AdminMode, float, AttrQuality][source]

Read the admin mode of the device.

Subclasses can override this to change the behaviour of the adminMode attribute.

write_adminMode(mode: AdminMode) → None[source]

Set the Admin Mode of the device.

Subclasses can override this to change the behaviour of the adminMode attribute.

Parameters:

mode – Admin Mode of the device.

Raises:

ValueError – for unknown adminMode
StateModelError – for a disallowed transition

is_adminMode_allowed(request_type: AttReqType) → bool[source]

Check if the adminMode can be read/written currently.

This can be overridden by subclasses to restrict when clients can access the attribute.

is_healthState_allowed(request_type: AttReqType) → bool[source]

Check if the healthState can be read currently.

This can be overridden by subclasses to restrict when clients can access the attribute.

read_healthState() → HealthState | tuple[HealthState, float, AttrQuality][source]

Read the health state of the device.

Subclasses can override this to change the behaviour of the healthState attribute.

is_healthInfo_allowed(request_type: AttReqType) → bool[source]

Check if the healthInfo can be read currently.

This can be overridden by subclasses to restrict when clients can access the attribute.

read_healthInfo() → list[str] | tuple[list[str], float, AttrQuality][source]

Read the health info of the device.

Subclasses can override this to change the behaviour of the healthInfo attribute.

report_health(health_state: HealthState, health_info: list[str]) → None[source]

Report the health of the device.

The health_info should include all the reasons that the current device is reporting a DEGRADED or FAILED health_state. Each element should be a separate reason and should be as brief as possible, while still providing enough information to aid in diagnosis.

If the health_state == OK, then the health_info must be an empty list.

health_state == UNKNOWN is not supported from this interface. Use health_state == FAILED with a descriptive health_info instead, e.g. “component <x> is unreachable”.

Parameters:

health_state – The overall health state of the device
health_info – A list of reasons for the current overall health state

Raises:

ValueError – If health_state==OK and health_info != []
ValueError – If health_state==UNKNOWN

ska_tango_base.future._base_interface.standard_control_mode(doc: str | None = None, **kwargs: Any) → tuple[Signal[ControlMode], attribute_from_signal][source]

Return a signal and attribute pair for the optional controlMode attribute.

When set to ControlMode.LOCAL, the Tango device accepts commands only from a local client and ignores commands and queries received from TM or any other remote clients. The local client must release LOCAL control before remote clients can take control again. The returned tuple should be unpacked into class-level signal and attribute declarations, for example:

_control_mode, controlMode = standard_control_mode()

The attribute is writable and memorized. Override doc to provide a device-specific description.

Parameters:

doc – Optional override for the Tango attribute description.
kwargs – Additional keyword arguments forwarded to attribute_from_signal().

Returns:

A (signal, attribute) tuple.

ska_tango_base.future._base_interface.standard_simulation_mode(doc: str | None = None, **kwargs: Any) → tuple[Signal[SimulationMode], attribute_from_signal][source]

Return a signal and attribute pair for the optional simulationMode attribute.

When SimulationMode.TRUE, the device is using a simulator instead of real hardware. The returned tuple should be unpacked into class-level signal and attribute declarations, for example:

_simulation_mode, simulationMode = standard_simulation_mode()

The attribute is writable and memorized. Override doc to provide a device-specific description.

Parameters:

doc – Optional override for the Tango attribute description.
kwargs – Additional keyword arguments forwarded to attribute_from_signal().

Returns:

A (signal, attribute) tuple.

ska_tango_base.future._base_interface.standard_test_mode(doc: str | None = None, **kwargs: Any) → tuple[Signal[TestMode], attribute_from_signal][source]

Return a signal and attribute pair for the optional testMode attribute.

When TestMode.TEST, the device substitutes its normal operating logic with testing/stub logic, which is useful for integration testing without real hardware. The returned tuple should be unpacked into class-level signal and attribute declarations, for example:

_test_mode, testMode = standard_test_mode()

The attribute is writable and memorized. Override doc to provide a device-specific description.

Parameters:

doc – Optional override for the Tango attribute description.
kwargs – Additional keyword arguments forwarded to attribute_from_signal().

Returns:

A (signal, attribute) tuple.