CBPComponent#

class lsst.ts.cbp.CBPComponent(log=None)#

Bases: object

This class is for implementing the CBP component.

The component implements a python wrapper over DMC code written by DFM Manufacturing. The following API exposes commands that move the motors of the CBP, sets the focus and selects the mask.

Parameters:: log (None or logging.Logger) – Optional logger used for component diagnostics.

log#

Component logger.

Type:: logging.Logger

client#

TCP client used to communicate with the controller.

Type:: lsst.ts.tcpip.Client

client_lock#

Lock that serializes command traffic.

Type:: asyncio.Lock

timeout#

Short command timeout in seconds.

Type:: int

long_timeout#

Long command timeout in seconds.

Type:: int

host#

Controller host name or IP address.

Type:: str

port#

Controller port.

Type:: int

connected#

True when the TCP client is connected.

Type:: bool

should_be_connected#

True when the TCP client is expected to be connected.

Type:: bool

target#

Latest commanded target snapshot.

Type:: Target

telemetry#

Latest hardware telemetry snapshot.

Type:: TelemetrySnapshot

in_position#

Latest component-owned command-facing in-position snapshot.

Type:: InPosition

monitor_condition#

Condition used to wake command waiters when monitor state changes.

Type:: asyncio.Condition

monitor_failure#

Latest monitor failure reason, if any.

Type:: str or None

masks#

Configured mask metadata keyed by mask ID.

Type:: dict of str to types.SimpleNamespace

error_tolerance#

Allowed azimuth/elevation error before the axis is considered out of position.

Type:: float

rotation_tolerance#

Allowed mask rotation error before the axis is considered out of position.

Type:: float

focus_crosstalk#

Allowed focus error before the axis is considered out of position.

Type:: float

terminator#

Command terminator used by the controller protocol.

Type:: str

Notes

The class uses the python socket module to build TCP/IP connections to the Galil controller for the CBP. The underlying API is built on DMC.

Attributes Summary

`auto_parked`	Return the latest autoparked telemetry value.
`azimuth`	Return the latest azimuth telemetry value.
`connected`	Return whether the controller client is connected.
`elevation`	Return the latest elevation telemetry value.
`focus`	Return the latest focus telemetry value.
`mask`	Return the latest mask telemetry value.
`mask_rotation`	Return the latest mask rotation telemetry value.
`motion_complete`	Return whether all CBP axes are in position.
`parked`	Return the latest parked telemetry value.
`should_be_connected`	Return whether the controller client should be connected.

Methods Summary

`accept_mask_target_update`(mask)	Validate and accept a configured mask target.
`accept_target_update`(**kwargs)	Validate and accept a target update.
`assert_in_range`(name, value, min_value, ...)	Raise ValueError if a value is out of range.
`change_focus`(position)	Change focus.
`check_cbp_status`()	Read hardware status bits from the CBP controller.
`check_park`()	Read the current park and autopark states from hardware.
`clear_monitor_failure`()	Clear the latest monitor failure state.
`configure`(config)	Configure the CBP.
`connect`()	Create a socket and connect to the CBP's static address and designated port.
`disconnect`()	Disconnect from the tcp socket.
`generate_mask_info`()	Generate the initial mask metadata table.
`get_azimuth`()	Read the current azimuth from hardware.
`get_elevation`()	Read and record the mount elevation encoder, in degrees.
`get_focus`()	Read the current focus from hardware.
`get_mask`()	Read the current mask name and mask rotation from hardware.
`get_mask_target`(mask)	Resolve a configured mask into a normalized target record.
`initialize_target_from_telemetry`()	Initialize target from the latest hardware telemetry.
`move_azimuth`(position)	Move the azimuth encoder.
`move_elevation`(position)	Move the elevation encoder.
`notify_monitor_failure`(reason)	Record monitor failure reason and wake command waiters.
`notify_monitor_success`(telemetry)	Record a successful monitor cycle and wake command waiters.
`reconnect_after_reply_failure`(msg)	Reconnect the controller socket after the reply stream stalls.
`send_command`(msg[, log, await_reply, ...])	Send a controller command and optionally read its reply.
`set_mask`(mask)	Set the mask value
`set_mask_rotation`(mask_rotation)	Set the mask rotation
`set_park`()	Send the park command to the controller.
`set_target`(**kwargs)	Update the component target state.
`set_unpark`()	Send the unpark command to the controller.
`update_status`()	Read hardware state and replace the telemetry snapshot.
`validate_target`([azimuth, elevation, focus, ...])	Validate target fields before mutating component state.
`wait_for_motion_complete`(monitor_task)	Wait for all CBP axes to be in position.
`wait_for_park_state`(parked, monitor_task)	Wait for the monitor loop to observe the requested park state.

Attributes Documentation

auto_parked#

Return the latest autoparked telemetry value.

Returns:: auto_parked – Latest autoparked state from the component telemetry snapshot.
Return type:: bool

azimuth#

Return the latest azimuth telemetry value.

Returns:: azimuth – Latest azimuth value from the component telemetry snapshot.
Return type:: float

connected#

Return whether the controller client is connected.

Returns:: connected – True if the TCP/IP client is connected.
Return type:: bool

elevation#

Return the latest elevation telemetry value.

Returns:: elevation – Latest elevation value from the component telemetry snapshot.
Return type:: float

focus#

Return the latest focus telemetry value.

Returns:: focus – Latest focus value from the component telemetry snapshot.
Return type:: float

mask#

Return the latest mask telemetry value.

Returns:: mask – Latest mask name from the component telemetry snapshot.
Return type:: str

mask_rotation#

Return the latest mask rotation telemetry value.

Returns:: mask_rotation – Latest mask rotation value from the component telemetry snapshot.
Return type:: float

motion_complete#

Return whether all CBP axes are in position.

Returns:: motion_complete – True if all in-position fields are true.
Return type:: bool

parked#

Return the latest parked telemetry value.

Returns:: parked – Latest parked state from the component telemetry snapshot.
Return type:: bool

should_be_connected#

Return whether the controller client should be connected.

Returns:: should_be_connected – True if the TCP/IP client is expected to be connected.
Return type:: bool

Methods Documentation

accept_mask_target_update(mask)#

Validate and accept a configured mask target.

Parameters:: mask (str or int) – Mask identifier accepted by the controller and configuration.
Returns:: target_update – Accepted target data for CSC publication.
Return type:: TargetUpdate

accept_target_update(**kwargs)#

Validate and accept a target update.

The returned update contains the full target snapshot and the component-owned transient in-position state after marking the affected axes out of position.

Parameters:: **kwargs (Any) – Target fields and values to replace in the immutable target snapshot. Each key must name a field on Target.
Returns:: target_update – Accepted target data for CSC publication.
Return type:: TargetUpdate

assert_in_range(name, value, min_value, max_value)#

Raise ValueError if a value is out of range.

Parameters:

name (str) – The name of the parameter.
value (float) – The received value.
min_value (float) – The minimum accepted value.
max_value (float) – The maximum accepted value.

Raises:

ValueError – Raised when a value is outside of the given range.

Return type:

None

async change_focus(position)#

Change focus.

Parameters:: position (int) – The value of the new focus (microns).
Raises:: ValueError – Raised when the new value falls outside the accepted range.
Return type:: None

async check_cbp_status()#

Read hardware status bits from the CBP controller.

Returns:: status – Hardware status bits.
Return type:: Status

async check_park()#

Read the current park and autopark states from hardware.

Return type:

tuple[bool, bool]

Returns:

parked (bool) – True if the CBP is parked.
auto_parked (bool) – True if the CBP is autoparked.

async clear_monitor_failure()#

Clear the latest monitor failure state.

Return type:: None

configure(config)#

Configure the CBP.

Parameters:: config (types.SimpleNamespace) – Configuration namespace produced by the CSC.
Return type:: None

async connect()#

Create a socket and connect to the CBP’s static address and designated port.

Raises:: Exception – Raised when the controller connection cannot be established.
Return type:: None

async disconnect()#

Disconnect from the tcp socket.

Safe to call even if already disconnected.

Return type:: None

generate_mask_info()#

Generate the initial mask metadata table.

Return type:: None

Notes

The mask table is initialized with the controller IDs used by the mock server and configuration loader. configure later replaces the names and rotations with deployment-specific values.

async get_azimuth()#

Read the current azimuth from hardware.

Returns:: azimuth – Current azimuth, in degrees.
Return type:: float

async get_elevation()#

Read and record the mount elevation encoder, in degrees.

Note that the low-level controller calls this axis “altitude”.

Returns:: elevation – Current elevation, in degrees.
Return type:: float

async get_focus()#

Read the current focus from hardware.

Returns:: focus – Current focus, in microns.
Return type:: float

async get_mask()#

Read the current mask name and mask rotation from hardware.

Return type:

tuple[str, float]

Returns:

mask_name (str) – Current mask name.
mask_rotation (float) – Current mask rotation, in degrees.

get_mask_target(mask)#

Resolve a configured mask into a normalized target record.

Parameters:: mask (str or int) – Mask identifier accepted by the controller and configuration.
Returns:: mask_target – Normalized mask target data.
Return type:: MaskTarget

initialize_target_from_telemetry()#

Initialize target from the latest hardware telemetry.

This is used during startup so that the CSC’s initial target matches the current hardware position. Because the target is set equal to the measured state, the resulting telemetry snapshot reports all axes in position.

Raises:: RuntimeError – Raised if no valid hardware telemetry has been read.
Return type:: None

async move_azimuth(position)#

Move the azimuth encoder.

Parameters:: position (float) – The desired azimuth (degrees).
Raises:: ValueError – Raised when the new value falls outside the accepted range.
Return type:: None

async move_elevation(position)#

Move the elevation encoder.

Parameters:: position (float) – The desired elevation (degrees)
Raises:: ValueError – Raised when the new value falls outside the accepted range.
Return type:: None

async notify_monitor_failure(reason)#

Record monitor failure reason and wake command waiters.

Parameters:: reason (str) – Failure reason reported by the monitor task.
Return type:: None

async notify_monitor_success(telemetry)#

Record a successful monitor cycle and wake command waiters.

Parameters:: telemetry (TelemetrySnapshot) – Snapshot read during the successful monitor cycle.
Return type:: None

async reconnect_after_reply_failure(msg)#

Reconnect the controller socket after the reply stream stalls.

This method is called while the command lock is held. That prevents another command from using the socket while it is being reset.

Parameters:: msg (str) – Command that did not receive a usable reply.
Return type:: None

async send_command(msg, log=True, await_reply=True, await_terminator=True)#

Send a controller command and optionally read its reply.

Parameters:

msg (str) – The string command to be sent.
log (bool) – Call with False to suppress log messages. Useful for debugging purposes to limit output.
await_reply (bool) – If false, do not wait for a reply.
await_terminator (bool) – If false, read a fixed-size byte reply; otherwise read a terminator-delimited string reply.

Returns:

reply – The normalized command reply, or None if await_reply is false.

Return type:

str, bytes, or None

Raises:

CommandReplyError – Raised if no usable reply is received after all retry attempts, if reconnecting after a missing reply fails, or if the reply type is unexpected.

async set_mask(mask)#

Set the mask value

Parameters:: mask (str) – Mask identifier or key used to look up the configured mask.
Raises:: KeyError – Raised when new mask is not a key in the dictionary.
Return type:: None

async set_mask_rotation(mask_rotation)#

Set the mask rotation

Parameters:: mask_rotation (float) – The mask_rotation value that will be sent.
Raises:: ValueError – Raised when the new value falls outside the accepted range.
Return type:: None

async set_park()#

Send the park command to the controller.

Return type:: None

set_target(**kwargs)#

Update the component target state.

Parameters:: **kwargs (Any) – Target fields and values to replace in the immutable target snapshot. Each key must name a field on Target.
Return type:: None

async set_unpark()#

Send the unpark command to the controller.

Return type:: None

async update_status()#

Read hardware state and replace the telemetry snapshot.

The new snapshot is built only after all telemetry fields have been read, so callers never observe a partially updated snapshot.

Returns:: telemetry – Captured hardware snapshot.
Return type:: TelemetrySnapshot

validate_target(azimuth=None, elevation=None, focus=None, mask=None, mask_rotation=None)#

Validate target fields before mutating component state.

Parameters:

azimuth (float, optional) – Proposed azimuth target.
elevation (float, optional) – Proposed elevation target.
focus (float, optional) – Proposed focus target.
mask (str, optional) – Proposed mask name.
mask_rotation (float, optional) – Proposed mask rotation target.

Raises:

ValueError – Raised if any provided target value is out of range or not one of the configured masks.

Return type:

None

async wait_for_motion_complete(monitor_task)#

Wait for all CBP axes to be in position.

Parameters:: monitor_task (asyncio.Future) – Monitor task that should continue updating component telemetry.
Raises:: MonitorStoppedError – Raised if the monitor fails or stops before motion completes.
Return type:: None

async wait_for_park_state(parked, monitor_task)#

Wait for the monitor loop to observe the requested park state.

Parameters:

parked (bool) – Desired parked state.
monitor_task (asyncio.Future) – Monitor task that should continue updating component telemetry.

Raises:

MonitorStoppedError – Raised if the monitor fails or stops before the state is observed.

Return type:

None