egse.device

cgse-common

This code is part of the cgse-common package.

egse.device

This module defines the generic interfaces to connect devices.

Classes:

Name	Description
AsyncDeviceTransport	Base class for the asynchronous device transport layer.
DeviceConnectionError	A generic error for all connection type of problems.
DeviceConnectionInterface	Generic connection interface for all Device classes and Controllers.
DeviceConnectionObservable	An observable for the connection state of a device. An observer can be added with the
DeviceConnectionObserver	An observer for the connection state of a device. Add the subclass of this class to
DeviceConnectionState	Defines connection states for device connections.
DeviceControllerError	Any error that is returned by the device controller.
DeviceError	Generic device error.
DeviceFactoryInterface	Base class for creating a device factory class to access devices.
DeviceInterface	Generic interface for all device classes.
DeviceInterfaceError	Any error that is returned or raised by the higher level interface to the device.
DeviceTimeoutError	A timeout on a device that we could not handle.
DeviceTransport	Base class for the device transport layer.

AsyncDeviceTransport

Base class for the asynchronous device transport layer.

Methods:

Name	Description
query	Send a query to the device and wait for the response.
read	Reads a bytes object back from the instrument and returns it unaltered.
trans	Send a single command to the device controller and block until a response from the
write	Sends a complete command to the device, handle line termination, and write timeouts.

query async

query(command)

Send a query to the device and wait for the response.

This query method is an alias for the trans command. For some commands it might be more intuitive to use the query instead of the transaction. No need to override this method as it delegates to trans.

Parameters:

Name	Type	Description	Default
command	str	the query command.	required

Returns:

Type	Description
bytes	The response to the query.

read async

read()

Reads a bytes object back from the instrument and returns it unaltered.

trans async

trans(command)

Send a single command to the device controller and block until a response from the controller.

Parameters:

Name	Type	Description	Default
command	str	is the command to be sent to the instrument	required

Returns:

Type	Description
bytes	Either a string returned by the controller (on success), or an error message (on failure).

Raises:

Type	Description
DeviceConnectionError	when there was an I/O problem during communication with the controller.
DeviceTimeoutError	when there was a timeout in either sending the command or receiving the response.

write async

write(command)

Sends a complete command to the device, handle line termination, and write timeouts.

Parameters:

Name	Type	Description	Default
command	str	the command to be sent to the instrument.	required

DeviceConnectionError

DeviceConnectionError(device_name, message)

Bases: DeviceError

A generic error for all connection type of problems.

Parameters:

Name	Type	Description	Default
device_name	str	The name of the device	required
message	str	a clear and brief description of the problem	required

DeviceConnectionInterface

DeviceConnectionInterface()

Bases: DeviceConnectionObservable

Generic connection interface for all Device classes and Controllers.

This interface shall be implemented in the Controllers that directly connect to the hardware, but also in the simulators to guarantee an identical interface as the controllers.

This interface will be implemented in the Proxy classes through the YAML definitions. Therefore, the YAML files shall define at least the following commands: connect, disconnect, reconnect, is_connected.

Methods:

Name	Description
add_observer	Add an observer.
connect	Connect to the device controller.
disconnect	Disconnect from the device controller.
is_connected	Check if the device is connected.
notify_observers	Notify the observers of a possible state change.
reconnect	Reconnect the device controller.

add_observer

add_observer(observer)

Add an observer.

connect

connect()

Connect to the device controller.

Raises:

Type	Description
ConnectionError	when the connection can not be opened.

disconnect

disconnect()

Disconnect from the device controller.

Raises:

Type	Description
ConnectionError	when the connection can not be closed.

is_connected

is_connected()

Check if the device is connected.

Returns:

Type	Description
bool	True if the device is connected and responds to a command, False otherwise.

notify_observers

notify_observers(state)

Notify the observers of a possible state change.

reconnect

reconnect()

Reconnect the device controller.

Raises:

Type	Description
ConnectionError	when the device can not be reconnected for some reason.

DeviceConnectionObservable

DeviceConnectionObservable()

An observable for the connection state of a device. An observer can be added with the add_observer() method. Whenever the connection state of the device changes, the subclass is responsible for notifying the observers by calling the notify_observers() method with the correct state.

Methods:

Name	Description
add_observer	Add an observer.
notify_observers	Notify the observers of a possible state change.

add_observer

add_observer(observer)

Add an observer.

notify_observers

notify_observers(state)

Notify the observers of a possible state change.

DeviceConnectionObserver

DeviceConnectionObserver()

An observer for the connection state of a device. Add the subclass of this class to the class that inherits from DeviceConnectionObservable. The observable will notify an update of its state by calling the update_connection_state() method.

Methods:

Name	Description
update_connection_state	Updates the connection state with the given state.

Attributes:

Name	Type	Description
state		Returns the current connection state of the device.

state property

state

Returns the current connection state of the device.

update_connection_state

update_connection_state(state)

Updates the connection state with the given state.

DeviceConnectionState

Bases: IntEnum

Defines connection states for device connections.

Attributes:

Name	Type	Description
DEVICE_CONNECTED		The device is connected.
DEVICE_NOT_CONNECTED		The device is not connected.

DEVICE_CONNECTED class-attribute instance-attribute

DEVICE_CONNECTED = 1

The device is connected.

DEVICE_NOT_CONNECTED class-attribute instance-attribute

DEVICE_NOT_CONNECTED = 2

The device is not connected.

DeviceControllerError

DeviceControllerError(device_name, message)

Bases: DeviceError

Any error that is returned by the device controller.

When the device controller is connected through an e.g. Ethernet interface, it will usually return error codes as part of the response to a command. When such an error is returned, raise this DeviceControllerError instead of passing the return code (response) to the caller.

Parameters:

Name	Type	Description	Default
device_name	str	The name of the device	required
message	str	a clear and brief description of the problem	required

DeviceError

DeviceError(device_name, message)

Bases: Error

Generic device error.

Parameters:

Name	Type	Description	Default
device_name	str	The name of the device	required
message	str	a clear and brief description of the problem	required

DeviceFactoryInterface

Base class for creating a device factory class to access devices.

This interface defines one interface method that shall be implemented by the Factory:

create(device_name: str, *, device_id: str, **_ignored)

Methods:

Name	Description
create	Create and return a device class that implements the expected device interface.

create

create(device_name, *, device_id, **_ignored)

Create and return a device class that implements the expected device interface. The device_name and device_id can be useful for identifying the specific device.

Additional keyword arguments can be passed to the device factory in order to forward them to the device constructor, but they will usually be ignored.

DeviceInterface

DeviceInterface()

Bases: DeviceConnectionInterface

Generic interface for all device classes.

Methods:

Name	Description
add_observer	Add an observer.
connect	Connect to the device controller.
disconnect	Disconnect from the device controller.
is_connected	Check if the device is connected.
is_simulator	Checks whether the device is a simulator rather than a real hardware controller.
notify_observers	Notify the observers of a possible state change.
reconnect	Reconnect the device controller.

add_observer

add_observer(observer)

Add an observer.

connect

connect()

Connect to the device controller.

Raises:

Type	Description
ConnectionError	when the connection can not be opened.

disconnect

disconnect()

Disconnect from the device controller.

Raises:

Type	Description
ConnectionError	when the connection can not be closed.

is_connected

is_connected()

Check if the device is connected.

Returns:

Type	Description
bool	True if the device is connected and responds to a command, False otherwise.

is_simulator

is_simulator()

Checks whether the device is a simulator rather than a real hardware controller.

This can be useful for testing purposes or when doing actual movement simulations.

Returns:

Type	Description
bool	True if the Device is a Simulator; False if the Device is connected to real hardware.

notify_observers

notify_observers(state)

Notify the observers of a possible state change.

reconnect

reconnect()

Reconnect the device controller.

Raises:

Type	Description
ConnectionError	when the device can not be reconnected for some reason.

DeviceInterfaceError

DeviceInterfaceError(device_name, message)

Bases: DeviceError

Any error that is returned or raised by the higher level interface to the device.

Parameters:

Name	Type	Description	Default
device_name	str	The name of the device	required
message	str	a clear and brief description of the problem	required

DeviceTimeoutError

DeviceTimeoutError(device_name, message)

Bases: DeviceError

A timeout on a device that we could not handle.

Parameters:

Name	Type	Description	Default
device_name	str	The name of the device	required
message	str	a clear and brief description of the problem	required

DeviceTransport

Base class for the device transport layer.

Methods:

Name	Description
query	Send a query to the device and wait for the response.
read	Reads a bytes object back from the instrument and returns it unaltered.
trans	Send a single command to the device controller and block until a response from the
write	Sends a complete command to the device, handle line termination, and write timeouts.

query

query(command)

Send a query to the device and wait for the response.

This query method is an alias for the trans command. For some commands it might be more intuitive to use the query instead of the transaction. No need to override this method as it delegates to trans.

Parameters:

Name	Type	Description	Default
command	str	the query command.	required

Returns:

Type	Description
bytes	The response to the query.

read

read()

Reads a bytes object back from the instrument and returns it unaltered.

trans

trans(command)

Send a single command to the device controller and block until a response from the controller.

Parameters:

Name	Type	Description	Default
command	str	is the command to be sent to the instrument	required

Returns:

Type	Description
bytes	Either a string returned by the controller (on success), or an error message (on failure).

Raises:

Type	Description
DeviceConnectionError	when there was an I/O problem during communication with the controller.
DeviceTimeoutError	when there was a timeout in either sending the command or receiving the response.

write

write(command)

Sends a complete command to the device, handle line termination, and write timeouts.

Parameters:

Name	Type	Description	Default
command	str	the command to be sent to the instrument.	required