RemoteCommand¶

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

Bases: lsst.ts.salobj.topics.write_topic.WriteTopic

Issue a specific command topic and wait for acknowldgement.

Parameters

salinfoSalInfo: SAL component information
namestr: 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 acknowledgement for the command.
`put`([data])	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:

RemoteCommand.set_start to start a command.
CommandEvent.set_put to write an event.
CommandTelemetry.set_put to write a telemetry message.

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() → 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: lsst.ts.salobj.type_hints.AckCmdDataType, timeout: float = 3600, wait_done: bool = True) → lsst.ts.salobj.type_hints.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

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: Optional[lsst.ts.salobj.type_hints.BaseDdsDataType] = None) → None¶

Output this topic.

Parameters

dataself.DataType or None: New message data to replace self.data, if any.

Raises

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

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) → lsst.ts.salobj.type_hints.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 (typically CMD_ACK). 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

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.

async start(data: Optional[lsst.ts.salobj.type_hints.BaseDdsDataType] = None, timeout: float = 3600, wait_done: bool = True) → lsst.ts.salobj.type_hints.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 (typically CMD_ACK). 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

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.

Navigation

RemoteCommand¶