toptica.lasersdk.client module

class toptica.lasersdk.client.Client(connection: Connection)

Bases: object

A client for devices that support the Device Control Protocol (DeCoP).

Parameters:

connection (Connection) – A connection that is used to communicate with the device.

change_ul(ul: UserLevel, password: str | None = None) → UserLevel

Changes the user level of the client connection.

Parameters:

• ul (UserLevel) – The requested user level.

• password (str | None) – The password for the requested user level.

Returns:

The new user level or the previous one if the password was incorrect.

Return type:

UserLevel

Raises:

• UnavailableError – If the connection is closed.

• DeviceTimeoutError – If the operation did not complete in time.

close() → None

Closes the connection to the device.

Raises:

DeviceTimeoutError – If the operation did not complete in time.

property command_line_available: bool

True if the command line is available, False otherwise.

Type:

bool

property connection: Connection

The connection of the client to the device.

Type:

Connection

exec(name: str, *args: bool | int | float | str | bytes | bytearray | tuple[Any, ...], input_stream: str | bytes | None = None, output_type: type[str | bytes] | None = None, return_type: type[bool | int | float | str | bytes | bytearray | tuple[Any, ...]] | None = None) → bool | int | float | str | bytes | bytearray | tuple[Any, ...] | None

Execute a DeCoP command.

Parameters:

• name (str) – The name of the command.

• *args – The parameters of the command.

• input_stream (DecopStreamType) – The input stream data of the command.

• output_type (DecopStreamMetaType) – The type of the output stream of the command.

• return_type (DecopMetaType) – The type of the optional return value.

Returns:

Either the output stream, the return value or a tuple of both.

Return type:

DecopType | None

Raises:

• UnavailableError – If the connection is closed or the command line is not available.

• DecopError – If the device returned an error when executing the command.

• DeviceTimeoutError – If the operation did not complete in time.

get(param_name: str, *param_types: type[bool | int | float | str | bytes | bytearray | tuple[Any, ...]]) → bool | int | float | str | bytes | bytearray | tuple[Any, ...]

Returns the current value of a DeCoP parameter.

Parameters:

• param_name (str) – The name of the DeCoP parameter (e.g. ‘laser1:enabled’).

• param_types (DecopMetaType) – Zero or more types of the DeCoP parameter.

Returns:

The current value of the parameter.

Return type:

DecopType

Raises:

• UnavailableError – If the connection is closed or the command line is not available.

• DecopValueError – If the provided types don’t match the result from the device.

• DeviceTimeoutError – If the operation did not complete in time.

get_set_value(param_name: str, *param_types: type[bool | int | float | str | bytes | bytearray | tuple[Any, ...]]) → bool | int | float | str | bytes | bytearray | tuple[Any, ...]

Returns the current ‘set value’ of a DeCoP parameter.

Parameters:

• param_name (str) – The name of the DeCoP parameter (e.g. ‘laser1:enabled’).

• param_types (DecopMetaType) – Zero or more types of the DeCoP parameter.

Returns:

The ‘set value’ of the parameter.

Return type:

DecopType

Raises:

• UnavailableError – If the connection is closed or the command line is not available.

• DecopValueError – If the provided types don’t match the result from the device.

• DeviceTimeoutError – If the operation did not complete in time.

property is_open: bool

True if the client connection is open, False otherwise.

Type:

bool

property monitoring_line_available: bool

True if the monitoring line is available, False otherwise.

Type:

bool

open() → None

Opens a connection to the device.

Raises:

DeviceNotFoundError – If opening the connection to the device has failed.

poll() → None

Invokes the next queued callback.

Raises:

UnavailableError – If the connection is closed or the monitoring line is not available.

run(timeout: float | None = None) → None

Invokes all scheduled callbacks until a timeout occurres.

Parameters:

timeout (float | None) – An optional timeout (in seconds) after this function will return. Without a timeout this function will run indefinitely (or until stop() is called). When timeout=0 this function behaves like poll().

Raises:

UnavailableError – If the connection is closed or the monitoring line is not available.

set(param_name: str, *param_values: bool | int | float | str | bytes | bytearray | tuple[Any, ...]) → int

Sets a new value for a DeCoP parameter.

Parameters:

• param_name (str) – The name of the DeCoP parameter (e.g. ‘laser1:enabled’).

• param_values (DecopType) – One or more parameter values.

Returns:

Zero if successful or a positive integer indicating a warning.

Return type:

int

Raises:

• UnavailableError – If the connection is closed or the command line is not available.

• DecopError – If the device returned an error when setting the new value.

• DeviceTimeoutError – If the operation did not complete in time.

stop() → None

Stops the event loop for the monitoring line.

subscribe(param_name: str, callback: Callable[[Subscription, datetime, SubscriptionValue], None], param_type: type[bool | int | float | str | bytes | bytearray | tuple[Any, ...]] | None = None, interval: int | None = None, threshold: bool | int | float | str | bytes | bytearray | tuple[Any, ...] | None = None) → Subscription

Creates a subscription to the value changes of a parameter.

Parameters:

• param_name (str) – The name of the parameter.

• callback (DecopCallback) – The callback that will be invoked on parameter updates.

• param_type (DecopMetaType | None) – The expected type of the parameter.

• interval (int | None) – The minimum update interval (in milliseconds).

• threshold (DecopType | None) – The minimum change of the value for an update.

Returns:

A subscription to the value changes of the parameter.

Return type:

Subscription

Raises:

• UnavailableError – If the connection is closed or the monitoring line is not available.

• DeviceTimeoutError – If the operation did not complete in time.

unsubscribe(subscription: Subscription) → None

Cancels a subscription to the value changes of a parameter.

Parameters:

subscription (Subscription) – The subscription to cancel.

Raises:

• UnavailableError – If the connection is closed or the monitoring line is not available.

• DeviceTimeoutError – If the operation did not complete in time.

exception toptica.lasersdk.client.DeviceTimeoutError

Bases: DecopError

An exception that is raised when connecting to a device has failed.

class toptica.lasersdk.client.Subscription(client: Client, name: str, callback: Callable[[Subscription, datetime, SubscriptionValue], None])

Bases: object

A subscription to the value changes of a parameter.

Parameters:

• client (Client) – A client that is used to access the parameter.

• name (str) – The fully qualified name of the parameter (e.g. ‘laser1:amp:ontime’).

• callback (DecopCallback) – A callback that will be invoked when the value of the parameter has changed.

cancel() → None

Cancels the subscription for parameter updates.

property client: Client | None

The Client of this subscription (maybe None when it was canceled).

Type:

Client | None

property name: str

The name of the parameter for this subscription.

Type:

str

update(timestamp: datetime, value: SubscriptionValue) → None

Invokes the callback with an updated parameter value.

Parameters:

• timestamp (Timestamp) – The timestamp of the parameter update.

• value (SubscriptionValue) – The new value of the parameter or an error.