CommandTelemetryClient¶

class lsst.ts.hexrotcomm.CommandTelemetryClient(*, log: Logger, ConfigClass: Callable[[], Structure], TelemetryClass: Callable[[], Structure], host: str, port: int, connect_callback: Callable[[BaseClientOrServer], Awaitable[None]], config_callback: Callable[[Self], Coroutine], telemetry_callback: Callable[[Self], Coroutine], connect_timeout: float = 10.0)¶

Bases: Client

TCP/IP Client for a Moog CSC.

This client cannot be reconnected; once closed, you must create a new one.

Parameters

loglogging.Logger: Logger.
ConfigClassctypes.Structure: Class for configuration.
TelemetryClassctypes.Structure: Class for telemetry
hoststr: IP address of CSC server.
portint: Server port.
connect_callbackcoroutine: Coroutine to call when a connection is made or dropped. The function receives one argument: this client.
config_callbackcoroutine: Coroutine to call when configuration is read. The function receives one argument: this client.
telemetry_callbackcoroutine: Coroutine to call when telemetry is read. The function receives one argument: this client.
connect_timeoutfloat, optional: Time limit for a connection to be made (seconds).

Raises

TypeError: If any of the callbacks is not a coroutine.

Notes

To start a client:

client = Client(...)
await client.start_task

To stop the client:

await client.stop()

Attributes

headerHeader: The most recently read header (which may be for config, telemetry, or unrecognized).
configConfigClass: The most recently read configuration. A null-constructed instance before configuration is read.
configured_taskasyncio.Future: A Future that is set to None when configuration is first read and processed, or to the exception if config_callback raises.
telemetryTelemetryClass: The most recently read telemetry. A null-constructed instance before telemetry is read.
config_callbackcoroutine: The config_callback constructor argument.
telemetry_callbackcoroutine: The telemetry_callback constructor argument.
Plus the standard attributes of `lsst.ts.tcpip.Client`.

Attributes Summary

connected

Return True if self._reader and self._writer are connected.

Methods Summary

`basic_close`()	Close the connected client socket, if any, and set done_task done.
`call_connect_callback`()	Call self.__connect_callback.
`close`()	Close the socket connection and cancel all tasks.
`next_telemetry`()	Wait for next telemetry.
`read`(n)	Read up to n bytes.
`read_into`(struct)	Read binary data from a stream reader into a `ctypes.Structure`.
`read_json`()	Read JSON data.
`read_loop`()	Read from the Moog controller.
`read_str`()	Read and decode a terminated str; strip the terminator.
`readexactly`(n)	Read exactly n bytes.
`readline`()	Read a sequence of bytes ending with `\n`.
`readuntil`([separator])	Read one line, where “line” is a sequence of bytes ending with `separator`.
`run_command`(command[, interrupt])	Run a command and wait for acknowledgement.
`start`()	Connect to the low-level controller.
`write`(data)	Write data and call `drain`.
`write_from`(*structs)	Write binary data from one or more `ctypes.Structure`s.
`write_json`(data)	Write data in JSON format.
`write_str`(line)	Encode, terminate, and write a str.
`writelines`(lines)	Write an iterable of bytes and call `drain`.

Attributes Documentation

connected¶

Return True if self._reader and self._writer are connected.

Note: if the other end drops the connection and if you are not trying to read data (e.g. in a background loop), then it takes the operating system awhile to realize the connection is lost. So this can return true for some unknown time after the connection has been dropped.

Methods Documentation

async basic_close() → None¶

Close the connected client socket, if any, and set done_task done.

Like close except does not clear self.should_be_connected, nor cancel self._monitor_connection_task.

async call_connect_callback() → None¶

Call self.__connect_callback.

This is always safe to call. It only calls the callback function if that function is not None and if the connection state has changed since the last time this method was called.

async close() → None¶

Close the socket connection and cancel all tasks.

Always safe to call.

async next_telemetry() → Structure¶: Wait for next telemetry.

async read(n: int) → bytes¶

Read up to n bytes.

Parameters

nint: The number of bytes to read. If -1 then block until the other end closes its writer, then return all data seen.

Raises

ConnectionError: If the connection is lost before, or while, reading.

async read_into(struct: Structure) → None¶

Read binary data from a stream reader into a ctypes.Structure.

Parameters

structctypes.Structure: Structure to set.

Raises

ConnectionError: If the connection is lost before, or while, reading.
asyncio.IncompleteReadError: If EOF is reached before n bytes can be read. Use the IncompleteReadError.partial attribute to get the partially read data.

async read_json() → Any¶

Read JSON data.

Read the data with read_str and return the json-decoded result.

Returns

datatyping.Any: Data decoded from JSON.

Raises

ConnectionError: If the connection is lost before, or while, reading.
asyncio.IncompleteReadError: If EOF is reached before the complete separator is found and the internal buffer is reset.
LimitOverrunError: If the amount of data read exceeds the configured stream lmit. The data is left in the internal buffer and can be read again.
TypeError: If the data are of a type that cannot be decoded from JSON.
json.JSONDecodeError: If the data cannot be decoded from JSON.

async read_loop() → None¶: Read from the Moog controller.

async read_str() → str¶

Read and decode a terminated str; strip the terminator.

Read until self.terminator, strip the terminator, and decode the data as self.encoding with strict error handling.

Returns

linestr: Line of data, as a str with the terminator stripped.

Raises

ConnectionError: If the connection is lost before, or while, reading.
asyncio.IncompleteReadError: If EOF is reached before the complete separator is found and the internal buffer is reset.
LimitOverrunError: If the amount of data read exceeds the configured stream lmit. The data is left in the internal buffer and can be read again.
UnicodeError: If decoding fails.

async readexactly(n: int) → bytes¶

Read exactly n bytes.

Parameters

nint: The number of bytes to read.

Raises

ConnectionError: If the connection is lost before, or while, reading.
asyncio.IncompleteReadError: If EOF is reached before n bytes can be read. Use the IncompleteReadError.partial attribute to get the partially read data.

async readline() → bytes¶

Read a sequence of bytes ending with \n.

If EOF is received and \n was not found, the method returns partially read data.

Raises

ConnectionError: If the connection is lost before, or while, reading.

async readuntil(separator: bytes = b'\n') → bytes¶

Read one line, where “line” is a sequence of bytes ending with separator.

Read data from the stream until separator is found.

On success, the data and separator will be removed from the internal buffer (consumed). Returned data will include the separator at the end.

See also read_str, which is more convenient for most use cases.

Parameters

separatorbytes: The desired separator. The default matches the standard library, rather than using terminator.

Raises

ConnectionError: If the connection is lost before, or while, reading.
asyncio.IncompleteReadError: If EOF is reached before the complete separator is found and the internal buffer is reset.
LimitOverrunError: If the amount of data read exceeds the configured stream lmit. The data is left in the internal buffer and can be read again.

async run_command(command: Command, interrupt: bool = False) → float¶

Run a command and wait for acknowledgement.

Parameters

commandCommand: Command to write. Its counter field will be set.
interruptbool, optional: Interrupt the current command, if any? Only use this for the stop command and similar.

Returns

durationfloat: The expected duration of the command (seconds).

Raises

ValueError: If command is not an instance of structs.Command.
ConnectionError: If not connected.
asyncio.TimeoutError: If no acknowledgement is seen in time.
lsst.ts.salobj.ExpectedError: If the command fails.

Notes

Holds the command lock until the reply for this command is seen (or the time limit is exceeded).

async start() → None¶: Connect to the low-level controller.

async write(data: bytes) → None¶

Write data and call drain.

Parameters

databytes: The data to write.

Raises

ConnectionError: If self.connected false before writing begins.

async write_from(*structs: Structure) → None¶

Write binary data from one or more ctypes.Structures.

Parameters

structslist [ctypes.Structure]: Structures to write.

Raises

ConnectionError: If self.connected false before writing begins.

async write_json(data: Any) → None¶

Write data in JSON format.

Encode the data as json and write the result with write_str.

Parameters

dataany: The data to be written. Typically a dict, but any json-encodable data is acceptable.

Raises

ConnectionError: If the connection is lost before, or while, reading.
UnicodeError: If encoding fails.
json.JSONEncodeError: If the data cannot be json-encoded.

async write_str(line: str) → None¶

Encode, terminate, and write a str.

Encode the str as self.encoding with strict error handling, and append self.terminator.

Parameters

linestr: The line of data to be written.

Raises

ConnectionError: If the connection is lost before, or while, reading.
UnicodeError: If encoding fails.

async writelines(lines: Iterable) → None¶

Write an iterable of bytes and call drain.

Parameters

linescollections.abc.Iterable [bytes]: The data to write, as an iterable collection of bytes.

Raises

ConnectionError: If self.connected false before writing begins.

Navigation

CommandTelemetryClient¶