RemoteCommand

class lsst.ts.salobj.topics.RemoteCommand(salinfo: SalInfo, name: str)

Bases: WriteTopic

Issue a specific command topic and wait for acknowldgement.

Parameters:

salinfoSalInfo

SAL component information.

namestr

Command name, with no prefix, e.g. “start”.

Attributes Summary

DataType	The type (class) for a message of this topic.
data	Internally cached message.
has_data	Has data ever been set?
metadata	Get topic metadata as a TopicMetadata, if available,else None.
volatile	Does this topic have volatile durability?

Methods Summary

basic_close()	A synchronous and possibly less thorough version of close.
close()	Shut down and release resources.
next_ackcmd(ackcmd[, timeout, wait_done])	Wait for the next acknowledgement for the command.
set(**kwargs)	Create a new self.data and set one or more fields.
set_start([timeout, wait_done])	Create a new self.data, set zero or more fields, and start the command.
set_write(*[, force_output])	An override of WriteTopic.set_write that is disabled.
start([data, timeout, wait_done])	Start a command.
write(**kwargs)	An override of WriteTopic.write that is disabled.

Attributes Documentation

DataType

The type (class) for a message of this topic.

When you read or write a message for this topic you are reading or writing an instance of DataType.

Notes

The preferred way to write a message for a topic is:

• RemoteCommand.start to start a command.

• CommandEvent.write to write an event.

• CommandTelemetry.write to write a telemetry message.

data

Internally cached message.

Raises:

TypeError

If data is not an instance of DataType

Notes

Do not assume the data will be constant. You can make a copy using copy.copy(data).

has_data

Has data ever been set?

A value of true simply means that set or set_write has been called at least once since the topic was constructed. All public fields will have their default value until they are set to something else. (Private fields are automatically set when the message is written.)

metadata

Get topic metadata as a TopicMetadata, if available,else None.

volatile

Does this topic have volatile durability?

Methods Documentation

basic_close() → None

A synchronous and possibly less thorough version of close.

Intended for exit handlers and constructor error handlers.

async close() → None

Shut down and release resources.

Intended to be called by SalInfo.close(), since that tracks all topics.

async next_ackcmd(ackcmd: AckCmdDataType, timeout: float = 3600, wait_done: bool = True) → AckCmdDataType

Wait for the next acknowledgement for the command.

Parameters:

ackcmdSalInfo.AckCmdType

Command acknowledgement returned by the previous call to set_start, start or next_ackcmd.

timeoutfloat, optional

Time limit, in seconds. If None then use DEFAULT_TIMEOUT. This time limit is for the entire command if wait_done is true, else it is for the next command acknowledgement. If wait_done is true and the command is acknowledged with CMD_INPROGRESS then the timeout is extended by the timeout value in the acknowledgement. Thus a slow command will not need a long timeout, so long as the command issues a CMD_INPROGRESS acknowledgement with a reasonable timeout value.

wait_donebool, optional

If true then wait for final command acknowledgement. If false then wait only for the next command acknowledgement If that acknowledgement is not final (the ack code is not in self.done_ack_codes), then you will almost certainly want to await next_ackcmd again.

Returns:

ackcmdSalInfo.AckCmdType

Command acknowledgement.

Raises:

lsst.ts.salobj.AckError

If the command fails.

lsst.ts.salobj.AckTimeoutError

If the command acknowledgement does not arrive in time.

RuntimeError

If the command specified by seq_num is unknown or has already finished.

set(**kwargs: Any) → bool

Create a new self.data and set one or more fields.

Parameters:

**kwargsdict [str, any]

Dict of field name: new value for that field:

• Any key whose value is None is checked for existence, but the value of the field is not changed.

• If the field being set is an array then the value must either be an array of the same length or a scalar (which replaces every element of the array).

Returns:

did_changebool

True if self.data was changed, or if this was the first call to set.

Raises:

AttributeError

If the topic does not have the specified field.

ValueError

If the field cannot be set to the specified value.

Notes

If one or more fields cannot be set, the data may be partially updated.

async set_start(timeout: float = 3600, wait_done: bool = True, **kwargs: Any) → AckCmdDataType

Create a new self.data, set zero or more fields, and start the command.

Parameters:

timeoutfloat, optional

Time limit, in seconds. If None then use DEFAULT_TIMEOUT. This time limit is for the entire command if wait_done is true, else it is for the first command acknowledgement. If wait_done is true and the command is acknowledged with CMD_INPROGRESS then the timeout is extended by the timeout value in the acknowledgement. Thus a slow command will not need a long timeout, so long as the command issues a CMD_INPROGRESS acknowledgement with a reasonable timeout value.

wait_donebool, optional

If true then wait for final command acknowledgement. If false then wait only for the first command acknowledgement If that acknowledgement is not final (the ack code is not in self.done_ack_codes), then you will almost certainly want to await next_ackcmd.

**kwargsdict [str, any]

The remaining keyword arguments are field name = new value for that field. See set for more information about values.

Returns:

ackcmdSalInfo.AckCmdType

Command acknowledgement.

Raises:

lsst.ts.salobj.AckError

If the command fails.

lsst.ts.salobj.AckTimeoutError

If the command times out.

TypeError

If data is not None and not an instance of DataType.

async set_write(*, force_output: bool | None = None, **kwargs: Any) → SetWriteResult

An override of WriteTopic.set_write that is disabled.

async start(data: lsst.ts.salobj.type_hints.BaseMsgType | None = None, timeout: float = 3600, wait_done: bool = True) → AckCmdDataType

Start a command.

Parameters:

dataself.DataType, optional

Command message. If None then send the current self.data.

timeoutfloat, optional

Time limit, in seconds. If None then use DEFAULT_TIMEOUT. This time limit is for the entire command if wait_done is true, else it is for the first acknowledgement. If wait_done is true and the command is acknowledged with CMD_INPROGRESS then the timeout is extended by the timeout value in the acknowledgement. Thus a slow command will not need a long timeout, so long as the command issues a CMD_INPROGRESS acknowledgement with a reasonable timeout value.

wait_donebool, optional

If true then wait for final command acknowledgement. If false then wait only for the first command acknowledgement. If that acknowledgement is not final (the ack code is not in self.done_ack_codes), then you will almost certainly want to await next_ackcmd.

Returns:

ackcmdSalInfo.AckCmdType

Command acknowledgement.

Raises:

lsst.ts.salobj.AckError

If the command fails.

lsst.ts.salobj.AckTimeoutError

If the command times out.

RuntimeError

If the salinfo has not started reading.

TypeError

If data is not None and not an instance of DataType.

async write(**kwargs: Any) → BaseMsgType

An override of WriteTopic.write that is disabled.