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 |
---|---|
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. |
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. |
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. |
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. |
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. |
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. |
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)
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. |
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. |
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 trans
action. 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. |
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. |