Controller

class lsst.ts.salobj.Controller(name: str, index: Optional[int] = None, *, do_callbacks: bool = False)

Bases: object

A class that receives commands for a SAL component and sends telemetry and events from that component.

This class provides much of the behavior for BaseCsc, basically everything except the standard summary states and associated transition commands.

Parameters
namestr

Name of SAL component.

indexint or None, optional

SAL component index, or 0 or None if the component is not indexed. A value is required if the component is indexed.

do_callbacksbool, optional

Set do_<name> methods as callbacks for commands? If True then there must be exactly one do_<name> method for each command.

Notes

Writing a Controller

(To write a CSC see Writing a CSC, instead)

To write a controller that is not a CSC (one that does not provide the standard summary states and associated state transition commands):

Here is an example that makes a Test controller and displays the topic-related attributes, but has no code to do anything useful with those topics (see TestCsc for that):

include salobj

# the index is arbitrary, but a remote must use the same index
# to talk to this controller
test_controller = salobj.Controller("Test", index=5)
print(dir(test_controller))

You should see the following topic-related attributes:

  • Commands, each an instance of topics.ControllerCommand:

    • cmd_standby

    • cmd_start

    • … and so on for all other standard CSC commands

    • cmd_setArrays

    • cmd_setScalars

  • Events, each an instance of topics.ControllerEvent:

    • evt_authList

    • evt_configurationApplied

    • … and so on for all other standard CSC events

    • evt_arrays

    • evt_scalars

  • Telemetry, each an instance of topics.ControllerTelemetry (note that there are no standard CSC telemetry topics):

    • tel_arrays

    • tel_scalars

Required Logging Attributes

Each Controller must support the following topics, as specified in ts_xml in SALGenerics.xml:

  • setLogLevel command

  • logLevel event

  • logMessage event

Attributes
loglogging.Logger

A logger.

salinfoSalInfo

SAL info.

isopenbool

Is this instance open? True until close is called. The instance is fully closed when done_task is done.

start_calledbool

Has the start method been called? The instance is fully started when start_task is done.

done_taskasyncio.Task

A task which is finished when close or basic_close is done.

start_taskasyncio.Task

A task which is finished when start is done, or to an exception if start fails.

cmd_<command_name>topics.ControllerCommand

Controller command topic. There is one for each command supported by the SAL component.

evt_<event_name>topics.ControllerEvent

Controller event topic. There is one for each event topic supported by the SAL component.

tel_<telemetry_name>topics.ControllerTelemetry

Controller telemetry topic. There is one for each telemetry topic supported by the SAL component.

Attributes Summary

domain

Methods Summary

close([exception, cancel_start])

Shut down, clean up resources and set done_task done.

close_tasks()

Shut down pending tasks.

do_setAuthList(data)

Update the authorization list.

do_setLogLevel(data)

Set logging level.

put_log_level()

Output the logLevel event.

start()

Finish construction.

Attributes Documentation

domain

Methods Documentation

async close(exception: Optional[Exception] = None, cancel_start: bool = True) None

Shut down, clean up resources and set done_task done.

May be called multiple times. The first call closes the Controller; subsequent calls wait until the Controller is closed.

Subclasses should override close_tasks instead of close, unless you have a good reason to do otherwise.

Parameters
exceptionException, optional

The exception that caused stopping, if any, in which case the self.done_task exception is set to this value. Specify None for a normal exit, in which case the self.done_task result is set to None.

cancel_startbool, optional

Cancel the start task? Leave this true unless calling this from the start task.

Notes

Removes the SAL log handler, calls close_tasks to stop all background tasks, pauses briefly to allow final SAL messages to be sent, then closes the dds domain.

async close_tasks() None

Shut down pending tasks. Called by close.

Perform all cleanup other than disabling logging to SAL and closing the dds domain.

async do_setAuthList(data: lsst.ts.salobj.type_hints.BaseMsgType) None

Update the authorization list.

Parameters
datacmd_setAuthList.DataType

Authorization lists.

Notes

Add items if the data string starts with “+”, ignoring duplicates (both with respect to the existing items and within the data string). Remove items if the data string starts with “-”, ignoring missing items (items specified for removal that do not exist). Ignore whitespace after each comma and after the +/- prefix.

async do_setLogLevel(data: lsst.ts.salobj.type_hints.BaseMsgType) None

Set logging level.

Parameters
datacmd_setLogLevel.DataType

Logging level.

async put_log_level() None

Output the logLevel event.

async start() None

Finish construction.