# RemoteCommand¶

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

Issue a specific command topic and wait for acknowldgement.

Parameters: salinfo : SalInfo SAL component information name : str Command name

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 acknowledement for the command put([data, priority]) Output this topic. 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. start([data, timeout, wait_done]) Start a command.

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:

However, it is also possible to use DataType to create a message, then write, it as separate operations. For example, assuming we have a Remote for SAL component “Test”:

# The preferred way to issue a command:
await = remote.cmd_wait.set_put(duration=2, timeout=5)

# But an alternative is to first create the command,
# then send it, as two separate operations:
message = remote.cmd_wait.DataType(duration=2)
await remote.cmd_wait.start(message, timeout=5)

# Or, even more verbosely:
message = remote.cmd_wait.DataType()
message.duration = 2
await remote.cmd_wait.start(message, timeout=5)

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?

metadata

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

volatile

Does this topic have volatile durability?

Methods Documentation

basic_close()

A synchronous and possibly less thorough version of close.

Intended for exit handlers and constructor error handlers.

close()

Shut down and release resources.

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

next_ackcmd(ackcmd, timeout=3600, wait_done=True)

Wait for the next acknowledement for the command

Parameters: ackcmd : SalInfo.AckCmdType The command acknowledgement returned by the previous wait (e.g. from start). timeout : float, 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 after the initial “CMD_ACK”. wait_done : bool, optional If True then wait for final command acknowledgement. If False then wait until the next command acknowledgement; if that acknowledgement is not final (the ack code is not in done_ack_codes), then you will almost certainly want to await next_ackcmd again. ackcmd : SalInfo.AckCmdType Command acknowledgement. salobj.AckError If the command fails or times out. RuntimeError If the command specified by seq_num is unknown or has already finished.
put(data=None, priority=0)

Output this topic.

Parameters: data : self.DataType or None New message data to replace self.data, if any. priority : int, optional Priority; used to set the priority field of events. Ignored for commands and telemetry. TypeError If data is not None and not an instance of DataType.
set(**kwargs)

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

Parameters: **kwargs : dict [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). did_change : bool True if self.data was changed, or if this was the first call to set. 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.

set_start(timeout=3600, wait_done=True, **kwargs)

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

Parameters: timeout : float, 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 after the initial CMD_ACK. If 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_done : bool, optional If True then wait for final command acknowledgement. If False then wait for the first acknowledgement after the initial “CMD_ACK”; if that acknowledgement is not final (the ack code is not in done_ack_codes), then you will almost certainly want to await next_ackcmd. **kwargs : dict [str, any] The remaining keyword arguments are field name = new value for that field. See set for more information about values. ackcmd : SalInfo.AckCmdType Command acknowledgement. salobj.AckError If the command fails. salobj.AckTimeoutError If the command times out. TypeError If data is not None and not an instance of DataType.
start(data=None, timeout=3600, wait_done=True)

Start a command.

Parameters: data : self.DataType, optional Command message. If None then send the current self.data. timeout : float, 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 after the initial CMD_ACK. If 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_done : bool, optional If True then wait for final command acknowledgement. If False then wait for the first acknowledgement after the initial “CMD_ACK”; if that acknowledgement is not final (the ack code is not in done_ack_codes), then you will almost certainly want to await next_ackcmd. ackcmd : SalInfo.AckCmdType Command acknowledgement. salobj.AckError If the command fails. 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.