Module Documentation

labnode_async

The Python implementation for the Labnode API. It supports both IPConnection and SerialConnection.

class labnode_async.FeedbackDirection(value)

Bases: Enum

The sign of the feedback action of the PID controller. A positive direction means, that a positive disturbance causes a positive output from the PID. A negative direction causes feedback in the opposing direction. This is the default and should be selected for most systems.

NEGATIVE = False

POSITIVE = True

class labnode_async.IPConnection(hostname: str, port: int = 4223, timeout: float = 2.5)

Bases: Connection

The ip connection is one of the two types of connections supported by the labnodes. See SerialConnection for the other option.

__init__(hostname: str, port: int = 4223, timeout: float = 2.5) → None

Parameters:

• hostname (str) – The hostname or IP of the ethernet endpoint

• port (int) – port of the endpoint

• timeout (float) – the timeout in seconds used when making queries or connection attempts

async connect() → None

Connect to the Labnode using an ip connection and start the connection listener. If the context manager is not used, call this function first. If the connection is already up, it will return immediately.

property endpoint: str

A string representation of the connection properties

property hostname: str

The hostname of the connection

property port: int

The port used by the connection

async send_request(data: dict[FunctionID | int, Any], response_expected: bool = False) → dict[int, Any] | None

Send a request to the Labnode. The data is a dictionary with FunctionID keys and the appropriate parameters as values.

Parameters:

• data (dict) – The dictionary with the requests.

• response_expected (bool) – Must be true if this is a query or if an ACK is requested

Returns:

A dictionary with results and/or ACKs. They dictionary keys are the FunctionIDs of the request.

Return type:

dict

class labnode_async.PidController(connection: Connection, api_version: tuple[int, int, int])

Bases: Labnode

A Labnode PID controller. This is the API to configure and control the Labnode.

__init__(connection: Connection, api_version: tuple[int, int, int]) → None

Create a pid controller. The API version is required to automatically adapt the different api versions.

Parameters:

• connection (Connection) – Either an ethernet or a serial connection

• api_version – The api version as enumerated by the connection

classmethod device_identifier() → DeviceIdentifier

The device identifier used to identify the device type

async get_active_connection_count() → int

Get the number of open sockets. :returns: The number of sockets :rtype: int

Raises:

FunctionNotImplementedError – If the firmware version does not support the request.

async get_auto_resume() → bool

Query the node, whether is automatically resumes after a reset (intentionally or unintentionally). If set, the node will return to the same state. If not, the node will always come up as disabled with default settings.

Returns:

True if the node keeps its enabled state after a reset

Return type:

bool

async get_by_function_id(function_id: PidFunctionID | int) → Any

Query a value by function id, instead of calling the named function.

Parameters:

function_id (PidFunctionID or int) – The function to query

Returns:

The result of the query.

Return type:

Any

Raises:

InvalidCommandError – If the function id was given as an integer and is unknown

async get_device_temperature() → Decimal

Query the temperature of the onboard sensor.

Returns:

The temperature of the onboard sensor in Kelvin

Return type:

Decimal

async get_hardware_version() → tuple[int, int, int]

Get the hardware revision of the device. The response is a tuple of ints, that represents the version number.

Returns:

The revision number

Return type:

Tuple of int

async get_humidity() → Decimal

Returns the humidity as read by the onboard sensor.

Returns:

The humidity in %rH

Return type:

Decimal

async get_kd(config_id: int = 0) → int

Get the PID Kd parameter. The Kp, Ki, Kd parameters are stored in Q16.16 format.

Parameters:

config_id ({0, 1}, default=0) – The id of the parameter set. The controller supports two pid parameter sets. Either 0 or 1.

Raises:

FunctionNotImplementedError – If the firmware version does not support the request.

async get_ki(config_id: int = 0) → int

Get the PID Ki parameter. The Kp, Ki, Kd parameters are stored in Q16.16 format.

Parameters:

config_id ({0, 1}, default=0) – The id of the parameter set. The controller supports two pid parameter sets. Either 0 or 1.

Raises:

FunctionNotImplementedError – If the firmware version does not support the request.

async get_kp(config_id: int = 0) → int

Get the PID Kp parameter. The Kp, Ki, Kd parameters are stored in Q16.16 format.

Parameters:

config_id ({0, 1}, default=0) – The id of the parameter set. The controller supports two pid parameter sets. Either 0 or 1.

Raises:

FunctionNotImplementedError – If the firmware version does not support the request.

async get_lower_output_limit() → int

Get the minimum output value of the DAC.

Returns:

The minimum output in bit

Return type:

int

async get_mac_address() → bytearray

Get the MAC address used by the ethernet port.

Returns:

An array of length 6 which contains the MAC

Return type:

bytearray

async get_output() → int

Queries the output value of the DAC.

Returns:

The output of the DAC in bit

Return type:

int

async get_pid_feedback_direction() → FeedbackDirection

Get the sign of the pid output. If set to FeedbackDirection.NEGATIVE, a positive error will result in a negative plant response.

Returns:

The direction of the controller response

Return type:

FeedbackDirection

async get_secondary_config() → int

Set the configuration id used when running in fallback mode.

Returns:

The configuration used, when running in fallback mode. The controller supports two pid parameter sets. Either 0 or 1.

Return type:

int

async get_secondary_pid_update_interval() → float

The update interval, which is used when running in fallback mode. The return value is in seconds.

Returns:

The number of seconds between updates with the backup sensor when running in fallback mode.

Return type:

float

async get_serial() → int

Get the serial number of the device.

Returns:

The serial number of the device

Return type:

int

async get_setpoint(config_id: int = 0) → int

Get the PID setpoint. The value is in Q16.16 format.

Parameters:

config_id ({0, 1}, default=0) – The id of the parameter set. The controller supports two pid parameter sets. Either 0 or 1.

Returns:

The setpoint value for the given config set.

Return type:

int

Raises:

FunctionNotImplementedError – If the firmware version does not support the request.

async get_software_version() → tuple[int, int, int]

Get the firmware version running on the device. The response is a tuple of ints, that represents the version number.

Returns:

The version number

Return type:

Tuple of int

async get_timeout() → float

Get the time, that must pass between updates, before the controller switches to fallback mode.

Returns:

The time in seconds, that the controller waits between updates

Return type:

float

async get_upper_output_limit() → int

Get the maximum output of the DAC in bit values.

Returns:

The upper limit for the output DAC

Return type:

int

async get_uuid() → UUID

Get the universally unique identifier of the node.

Returns:

The universally unique identifier of the node

Return type:

UUID

Raises:

FunctionNotImplementedError – If the firmware version does not support the request.

async is_dac_gain_enabled() → bool

Return True if the DAC output goes from 0-10 V. False if the DAC gain is disabled and the output is 0-5 V.

Returns:

True if the gain is enabled

Return type:

bool

async is_enabled() → bool

Queries the state of the PID controller.

Returns:

True if the controller is enabled

Return type:

bool

async reset() → None

Resets the device. This will trigger a hardware reset.

async reset_settings() → None

Resets the device to default values.

async send_multi_request(data: dict[PidFunctionID | int, Any]) → dict

Send one or more requests to the device.

Parameters:

data

Raises:

ValueError – If an unknown function id was sent and response_expected was set to True

async set_auto_resume(value: bool)

Set the controller to automatically load the previous settings and resume its action.

Parameters:

value (bool) – Set to True to load the node settings on boot

async set_dac_gain(enable: bool) → None

Set the gain of the DAC to x2. This will increase the output voltage range from 0..5V to 0..10V.

Parameters:

enable – True to enable the gain

async set_enabled(enabled: bool) → None

Set the PID controller to enabled/automatic or disabled/manual mode.

Parameters:

enabled (bool) – True to enable the PID controller

async set_input(value: int, return_output: bool = False) → int | None

Set the input, which is fed to the PID controller. The value is in Q16.16 format.

Parameters:

• value (int) – The input value in Q16.16 format

• return_output (bool) – Returns the output of the controller if True

Returns:

Returns the output of the controller if return_output is set

Return type:

int or None

async set_kd(kd: int, config_id: int = 0) → None

Set the PID Kd parameter. The Kp, Ki, Kd parameters are stored in Q16.16 format.

Parameters:

• kd (int) – The parameter value in Q16.16 format (32 bit)

• config_id ({0, 1}, default=0) – The id of the parameter set. The controller supports two pid parameter sets. Either 0 or 1.

async set_ki(ki: int, config_id: int = 0) → None

Set the PID Ki parameter. The Kp, Ki, Kd parameters are stored in Q16.16 format.

Parameters:

• ki (int) – The parameter value in Q16.16 format (32 bit)

• config_id ({0, 1}, default=0) – The id of the parameter set. The controller supports two pid parameter sets. Either 0 or 1.

async set_kp(kp: int, config_id: int = 0) → None

Set the PID Kp parameter. The Kp, Ki, Kd parameters are stored in Q16.16 format.

Parameters:

• kp (int) – The PID k_p parameter in Q16.16 format

• config_id ({0, 1}, default=0) – The id of the parameter set. The controller supports two pid parameter sets. Either 0 or 1.

async set_lower_output_limit(limit: int) → None

Set the minimum output of the DAC in bit values.

Parameters:

limit (int) – The minimum output value of the DAC

Raises:

ValueError – If the limit was out of bounds.

async set_mac_address(mac: tuple[int, int, int, int, int, int] | list[int] | bytearray) → None

Set the MAC address used by the ethernet port.

Parameters:

mac (bytearray or tuple of int) – The MAC address as a bytearray of length 6

async set_output(value: int) → None

Set the output value of the DAC. This function only works, when the controller mode is set to disabled (manual). Use set_enabled(false).

Parameters:

value (int) – The output in bit

async set_pid_feedback_direction(feedback: FeedbackDirection) → None

Set the sign of the pid output. This needs to be adjusted according to the actuator used to control the plant. Typically, it is assumed, that the feedback is negative. For example, when dealing with e.g. temperature control, this means, that if the temperature is too high, an increase in the feedback will increase the cooling action. In short: If set to FeedbackDirection.NEGATIVE, a positive error will result in a negative plant response.

Parameters:

feedback (FeedbackDirection) – The direction of the controller response

async set_secondary_config(config_id: int) → None

Set the configuration used when running in fallback mode.

Parameters:

config_id ({0, 1}) – The configuration to be used. The controller supports two pid parameter sets. Either 0 or 1.

Raises:

• FunctionNotImplementedError – If the firmware version does not support the request.

• InvalidFormatError – If the config_id is not in {0, 1}.

async set_secondary_pid_update_interval(value: float)

Set the update interval, when running in fallback mode using the secondary PID settings. The Controller will feed a value from the internal sensor to the secondary PID controller every {value} s.

Parameters:

value (int) – The update interval in seconds

async set_serial(serial: int) → None

Set the serial number of the device :param serial: The serial number. Maximum: 4294967295 (32 bit) :type serial: int

Raises:

ValueError – If the serial number is not valid.

async set_setpoint(value: int, config_id: int = 0) → None

Set the PID setpoint. The value is in Q16.16 format.

Parameters:

• value (int) – The setpoint of the PID controller in Q16.16 format.

• config_id ({0, 1}, default=0) – The id of the parameter set. The controller supports two pid parameter sets. Either 0 or 1.

Raises:

FunctionNotImplementedError – If the firmware version does not support the request.

async set_timeout(timeout: float) → None

Set the timeout, that defines when the controller switches to fallback mode. The time is measured in s.

Parameters:

timeout – The timeout in seconds

async set_upper_output_limit(limit: int) → None

Set the maximum output of the DAC in bit values.

Parameters:

limit (int) – The maximum output value of the DAC

Raises:

ValueError – If the limit was out of bounds.

async set_uuid(uuid: UUID) → None

Set the universally unique identifier of the node.

Parameters:

uuid (UUID) – The universally unique identifier of the node

Raises:

FunctionNotImplementedError – If the firmware version does not support the request.

class labnode_async.SerialConnection(url: str, *, baudrate: int = 115200, timeout: float = 2.5, **kwargs: Any)

Bases: Connection

The serial connection is one of the two types of connections supported by the labnodes. See IPConnection for the other option.

__init__(url: str, *, baudrate: int = 115200, timeout: float = 2.5, **kwargs: Any) → None

Parameters:

• url (str) – The serial tty like /dev/ttyUSB0 or COM3 or an integer port number

• baudrate (int, default=115200) – The baud rate of the serial port

• timeout (float) – the timeout in seconds used when making queries or connection attempts

• * (tuple, optional) – arguments will be ignored

• **kwargs (dict, optional) – keyword arguments will be passed on to Serial(). See https://pyserial.readthedocs.io/en/latest/pyserial_api.html for more information.

property baudrate: int

The baudrate of the serial connection

async connect() → None

Connect to the Labnode using a serial connection and start the connection listener.

property endpoint: str

A string representation of the connection endpoint

async send_request(data: dict[FunctionID | int, Any], response_expected: bool = False) → dict[int, Any] | None

Send a request to the Labnode :param data: The dictionary with the requests. :type data: dict :param response_expected: Must be true if this is a query or if an ACK is requested :type response_expected: bool

Returns:

A dictionary with results and/or ACKs. They dictionary keys are the FunctionIDs of the request.

Return type:

dict

property tty: str

The serial endpoint of the connection

class labnode_async.connection.Connection(timeout: float = 2.5)

The base connection used for all Labnode connections.

__init__(timeout: float = 2.5) → None

Parameters:

timeout (float) – the timeout in seconds used when making queries or connection attempts

async connect() → None

Connect to the Labnode and start the connection listener.

async disconnect() → None

Closes the connection. Returns early if the connection is not up.

property endpoint: str

A string representation of the connection endpoint.

async get_device_id() → tuple[DeviceIdentifier, tuple[int, int, int]]

Query the Labnode for its device id and the version of its API implementation.

Returns:

The Device id and the api version

Return type:

Tuple of DeviceIdentifier and tuple of int

property is_connected: bool

True if the connection is established.

async send_request(data: dict[FunctionID | int, Any], response_expected: bool = False) → dict[int, Any] | None

Send a request to the Labnode.

Parameters:

• data (dict) – The dictionary with the requests.

• response_expected (bool) – Must be true if this is a query or if an ACK is requested

Returns:

A dictionary with results and/or ACKs. They dictionary keys are the FunctionIDs of the request.

Return type:

dict

property timeout: float

The timeout in seconds for async operations.

Constants

All device and command specific constants are found here. All setters are positive integers, while getters are negative.

class labnode_async.devices.DeviceIdentifier(value)

The device codes used by all Labnodes to identify themselves.

PID = 0

class labnode_async.devices.FunctionID(value)

These are the function calls supported by all Labnodes.

GET_ACTIVE_CONNECTION_COUNT = -28

GET_API_VERSION = -32

GET_DEVICE_TYPE = -29

GET_HARDWARE_VERSION = -31

GET_SOFTWARE_VERSION = -30

INVALID_FORMAT = 251

REQUEST_ID = 0

RESET = 30

RESET_SETTINGS = 31

SET_SERIAL_NUMBER = 12

class labnode_async.devices.PidFunctionID(value)

These are the function calls supported by the Labnode PID controllers.

CALLBACK_UPDATE_VALUE = -27

GET_ACTIVE_CONNECTION_COUNT = -28

GET_API_VERSION = -32

GET_AUTO_RESUME = -16

GET_BOARD_TEMPERATURE = -25

GET_DEVICE_TYPE = -29

GET_DIRECTION = -9

GET_ENABLED = -7

GET_FALLBACK_UPDATE_INTERVAL = -17

GET_GAIN = -13

GET_HARDWARE_VERSION = -31

GET_HUMIDITY = -26

GET_INPUT = -1

GET_KD = -4

GET_KI = -3

GET_KP = -2

GET_LOWER_OUTPUT_LIMIT = -5

GET_MAC_ADDRESS = -15

GET_OUTPUT = -11

GET_SECONDARY_KD = -20

GET_SECONDARY_KI = -19

GET_SECONDARY_KP = -18

GET_SECONDARY_PID_PARAMETER_SET = -21

GET_SECONDARY_SETPOINT = -14

GET_SERIAL_NUMBER = -12

GET_SETPOINT = -10

GET_SOFTWARE_VERSION = -30

GET_TIMEOUT = -8

GET_UPPER_OUTPUT_LIMIT = -6

GET_UUID = -24

INVALID_FORMAT = 251

REQUEST_ID = 0

RESET = 30

RESET_SETTINGS = 31

SET_AUTO_RESUME = 16

SET_DIRECTION = 9

SET_ENABLED = 7

SET_FALLBACK_UPDATE_INTERVAL = 17

SET_GAIN = 13

SET_INPUT = 1

SET_KD = 4

SET_KI = 3

SET_KP = 2

SET_LOWER_OUTPUT_LIMIT = 5

SET_MAC_ADDRESS = 15

SET_OUTPUT = 11

SET_SECONDARY_KD = 20

SET_SECONDARY_KI = 19

SET_SECONDARY_KP = 18

SET_SECONDARY_PID_PARAMETER_SET = 21

SET_SECONDARY_SETPOINT = 14

SET_SERIAL_NUMBER = 12

SET_SETPOINT = 10

SET_TIMEOUT = 8

SET_UPPER_OUTPUT_LIMIT = 6

SET_UUID = 24

Errors

Custom errors raised by Labnodes.

exception labnode_async.errors.FunctionNotImplementedError

Raised if the Labnode recognises the command, but the function is not supported in this firmware.

exception labnode_async.errors.InvalidCommandError

Raised if the Labnode does not recognise the command.

exception labnode_async.errors.InvalidFormatError

Raised if the request does not have the correct formatting. Typically, the wrong datatype.

exception labnode_async.errors.InvalidModeError

Raised if the labnode cannot execute the command, because it is not set to the right operating mode.

exception labnode_async.errors.InvalidReplyError

Raised if the Reply from the Labnode matched our request id, yet did not contain a reply to the request made.

exception labnode_async.errors.LabnodeException

The base exception class for all errors thrown by labnode_async.

exception labnode_async.errors.PidNotInitializedError

Raised by the controller if the PID parameters have not been initialized, yet the controller was turned on