ControllerCommand

class lsst.ts.salobj.topics.ControllerCommand(salinfo, name, queue_len=100)

Bases: ReadTopic

Read a specified command topic.

Parameters:

• salinfo (SalInfo) – SAL component information.

• name (str) – Command name, with no prefix, e.g. “start”.

• queue_len (int, optional) – Number of elements that can be queued for get_oldest.

Notes

Each command must be acknowledged by writing an appropriate ackcmd message. If you use a callback function to process the command then this happens automatically, as follows:

• If the callback function returns None then send a final acknowledgement with ack=SalRetCode.CMD_COMPLETE.

• If the callback function returns an acknowledgement (instance of SalInfo.AckCmdType) instead of None, then send that as the final acknowledgement. This is very unusual, but might be useful if the callback wants to exit early and leave some background task or thread processing the rest of the command.

• If the callback function raises asyncio.TimeoutError then send a final acknowledgement with ack=SalRetCode.CMD_TIMEOUT.

• If the callback function raises asyncio.CancelledError then send a final acknowledgement with ack=SalRetCode.CMD_ABORTED.

• If the callback function raises ExpectedError then send a final acknowledgement with ack=SalRetCode.CMD_FAILED and result=f"Failed: {exception}".

• If the callback function raises any other Exception then do the same as ExpectedError and also log a traceback.

Methods Summary

ack(data, ackcmd)	Acknowledge a command by writing a new state.
ack_in_progress(data, timeout[, result])	Ackowledge this command as "in progress".
next(*[, timeout])	Wait for data, returning old data if found.

Methods Documentation

async ack(data, ackcmd)

Acknowledge a command by writing a new state.

Parameters:

• data (DataType) – Data for the command being acknowledged.

• ackcmd (salobj.AckCmdType) – Command acknowledgement data.

Raises:

RuntimeError – If self.salinfo is not running. This may occur at shutdown. (It is much less likely if the SalInfo as not started, because the SalInfo will not have received any commands.)

Return type:

None

async ack_in_progress(data, timeout, result='')

Ackowledge this command as “in progress”.

Parameters:

• data (DataType) – Data for the command being acknowledged.

• timeout (float) – Estimated command duration (sec).

• result (str, optional) – Reason for acknowledgement. Typically left “”.

Raises:

RuntimeError – If self.salinfo is not running. This may occur at shutdown. (It is much less likely if the SalInfo as not started, because the SalInfo will not have received any commands.)

Return type:

None

async next(*, timeout=None)

Wait for data, returning old data if found.

Unlike RemoteEvent.next and RemoteTelemetry.next, the flush argument is not allowed; the only way to flush old commands is to call flush.

Parameters:

timeout (float, optional) – Time limit, in seconds. If None then no time limit.

Returns:

data – Command data.

Return type:

DataType

Raises:

• asyncio.TimeoutError – If no message is available within the specified time limit.

• RuntimeError – If a callback function is present.

Notes

Do not modify the data or assume that it will be static. If you need a private copy, then copy it yourself.