Base Interface

Base interfaces for SKA Tango devices.

class ska_tango_base.base.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.base.base_interface.CommandedStateSignal[source]

Bases: Signal[DevState | None]

Special signal for the Commanded State.

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

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

class ska_tango_base.base.base_interface.ControlLevel[source]

Bases: Enum

How much control the Tango device should exert on the system under control.

This enumeration should not be consider exhaustive as, in the future, we may add MONITORING_ONLY to this enumeration.

NO_CONTACT = 1: The Tango device should make no contact with the system under control.

FULL_CONTROL = 2: The Tango device should attempt to control the system under control fully.

class ska_tango_base.base.base_interface.BaseInterface[source]

Bases: SignalBusMixin, SKADevice

Provides the Tango interface for an 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 to drive the Operational State Model 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 and should instead change the state by performing the appropriate action on the OpStateModel, which will additionally ensure that change and archive events are sent.

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

INIT: The device is initialising
DISABLE: The device is not currently monitoring or controlling the system
UNKNOWN: The device cannot determine the state of the system
OFF: The system under control is powered off
STANDBY: The system under control is in low-power standby mode
ON: The system under control is powered on
ALARM: The system under control is powered on and some attribute is raising an alarm. This is typically automatically handled by Tango.
FAULT: The system under control is in fault

The _op_state signal object will raise a ValueError if set to a DevState value other than those above.

BaseInterface similarly provides a _status signal which will update the built-in Tango status attribute with set_status() and push change and archive events whenever set.

In addition to providing the _op_state and _status signals BaseInterface also provides the signals _admin_mode, _commanded_state and _health_state as well as the corresponding Tango attributes adminMode, commandedState and healthState.

The adminMode Tango attribute is writable and should not be set by subclasses of this interface. Subclasses will be notified when a client has requested the device to stop/start controlling the system under control via the change_control_level() method, which they are expected to override.

The commandedState and healthState should be set by subclasses as appropriate, using the corresponding signals.

This interface also provides optional state transition commands Off(), Standby(), On() as well as implementations of the is_Off_allowed(), is_Standby_allowed() and is_On_allowed() methods which respect the Operational State machine.

Subclasses can provide an implementation for these commands by overriding the execute_Off(), execute_Standby() and execute_On() methods.

Additionally, the Reset() command is required and the corresponding execute_Reset() method must be overridden by all subclasses.

_admin_mode: Signal[ska_control_model.AdminMode]

Signal for the admin mode of the device.

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

Typically, subclasses will not need to listen to this signal and should instead override change_control_level().

admin_mode_model: ska_control_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_model: ska_control_model.OpStateModel: State model used to ensure that operational state transitions are allowed.

_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.

_commanded_state: CommandedStateSignal

Signal for the commanded Operational State of the device.

Write to this signal whenever a command is executed which will result in a state transition.

commandedState: attribute_from_signal

Attribute for the last commanded Operating State of the device.

This should be set by subclasses of this interface by writing to _commanded_state.

_health_state

Signal for the health state of the device.

Writing to this signal sets the reported health state of the Tango device.

Writing to this signal directly is deprecated. 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()

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

_init_state_model() → None[source]

Initialise the state model for the device.

init_invoked() → None[source]: Perform ‘init_invoked’ action on the OpStateModel.

init_completed() → None[source]

Notify the state machine 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()

component_disconnected() → None[source]: Perform disconnected action on the OpStateModel.

component_unknown() → None[source]: Perform unknown state action on the OpStateModel.

component_off() → None[source]: Perform off action on the OpStateModel.

component_standby() → None[source]: Perform cstandby action on the OpStateModel.

component_on() → None[source]: Perform on action on the OpStateModel.

component_fault() → None[source]: Perform fault action on the OpStateModel.

component_no_fault() → None[source]: Perform fault stopped action on the OpStateModel.

_update_state(state: DevState, status: str | None = None) → None[source]

Perform Tango operations in response to a change in op state.

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

Parameters:

state – the new state value
status – an optional new status string

_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:

value – Admin Mode of the device.

Raises:

ValueError – for unknown adminMode
StateModelError – for a disallowed transition

change_control_level(control_level: ControlLevel) → None[source]

Change how the device is interacting with the system under control.

Subclasses must override this method to do the following:

Stop all communication with the system under control when passed ControlLevel.NO_CONTACT. Once the Tango device has stopped communicating with the system under control, the operational state must transition to DISABLE.
Start controlling the system under control when passed ControlLevel.FULL_CONTROL. Once the Tango device has started trying to communicating with the system under control, it must transition to a state other than DISABLE. If the Tango device is trying to communicate with the system under control, but unable to, it should transition to operational state UNKNOWN.

Subclasses overriding this method should not assume that the ControlLevel is exhaustive.

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_commandedState_allowed(request_type: AttReqType) → bool[source]

Check if the commandedState can be read currently.

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

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

Read the commanded state of the device.

Subclasses can override this to change the behaviour of the commandedState 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

is_Reset_allowed(request_type: LRCReqType | None = None) → bool[source]

Return whether the Reset() command may be called currently.

This method can be overridden by subclasses to change when this command is allowed.

Returns:: whether the command may be called in the current device state

execute_Reset() → DevVarLongStringArrayType[source]

Execute the standard Reset command.

This method must be overridden by a subclass to enable the Tango command, otherwise the command will not be part of the device interface. The submit_lrc_task() decorator can be used to make Reset a long running command.

For a device that directly monitors and controls hardware, this command should put that hardware into a known state, for example by clearing buffers and loading default values into registers, or if necessary even by power-cycling and re-initialising the hardware.

Logical devices should generally implement this command to perform a sensible reset of that logical device. For example, aborting any current activities and clearing internal state.

Reset() generally should not change the power state of the device or its hardware:

If invoking Reset() from STANDBY state, the device would usually be expected to remain in STANDBY.
If invoking Reset() from ON state, the device would usually be expected to remain in ON.
If invoking Reset() from FAULT state, the device would usually be expected to transition to ON or remain in FAULT, depending on whether the reset was successful in clearing then fault.

Reset() generally should not propagate to subservient devices. For example, a subsystem controller device should implement :py:meth`!Reset()` to reset the subsystem as a whole, but that probably should not result in all of the subsystem’s hardware being power-cycled.

Returns:: A tuple containing a return code and a string message indicating status. The message is for information purpose only.

is_Standby_allowed(request_type: LRCReqType | None = None) → bool[source]

Return whether the Standby() command may be called currently.

This method can be overridden by subclasses to change when this command is allowed.

Returns:: whether the command may be called in the current device state

execute_Standby() → DevVarLongStringArrayType[source]

Execute the standard Standby command.

This method must be overridden by a subclass to enable the Tango command, otherwise the command will not be part of the device interface. The submit_lrc_task() decorator can be used to make Reset a long running command.

If implemented, this command should put the device in standby mode and result in the operational state transitioning to STANDBY. The command should not return until the transition has occurred.

Returns:: A tuple containing a return code and a string message indicating status or a command ID. The message is for information purpose only.

is_Off_allowed(request_type: LRCReqType | None = None) → bool[source]

Return whether the Off() command may be called currently.

This method can be overridden by subclasses to change when this command is allowed.

Returns:: whether the command may be called in the current device state

execute_Off() → DevVarLongStringArrayType[source]

Execute the standard Off command.

This method must be overridden by a subclass to enable the Tango command, otherwise the command will not be part of the device interface. The submit_lrc_task() decorator can be used to make Reset a long running command.

If implemented, this command should turn the device off and result in the operational state transitioning to OFF. The command should not return until the transition has occurred.

Returns:: A tuple containing a return code and a string message indicating status or a command ID. The message is for information purpose only.

is_On_allowed(request_type: LRCReqType | None = None) → bool[source]

Return whether the On() command may be called currently.

This method can be overridden by subclasses to change when this command is allowed.

Returns:: whether the command may be called in the current device state

execute_On() → DevVarLongStringArrayType[source]

Execute the standard On command.

This method must be overridden by a subclass to enable the Tango command, otherwise the command will not be part of the device interface. The submit_lrc_task() decorator can be used to make Reset a long running command.

If implemented, this command should turn the device on and result in the operational state transitioning to ON or ALARM. The command should not return until the transition has occurred.

Returns:: A tuple containing a return code and a string message indicating status or a command ID. The message is for information purpose only.

Reset() → DevVarLongStringArrayType[source]

Reset the device.

Subclasses should override the execute_Reset method to change the behaviour of this command.

Returns:: A tuple containing a return code and a string message indicating status or a command ID. The message is for information purpose only.

On() → DevVarLongStringArrayType[source]

Turn the device on.

Subclasses should override the execute_On method to change the behaviour of this command.

Returns:: A tuple containing a return code and a string message indicating status or a command ID. The message is for information purpose only.

Standby() → DevVarLongStringArrayType[source]

Put the device into standby mode.

Subclasses should override the execute_Standby method to change the behaviour of this command.

Returns:: A tuple containing a return code and a string message indicating status or a command ID. The message is for information purpose only.

Off() → DevVarLongStringArrayType[source]

Turn the device off.

Subclasses should override the execute_Off method to change the behaviour of this command.

Returns:: A tuple containing a return code and a string message indicating status or a command ID. The message is for information purpose only.

ska_tango_base.base.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.base.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.base.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.