navigate.model.devices.pump.tecan.XCaliburPump

class navigate.model.devices.pump.tecan.XCaliburPump(microscope_name: str, device_connection: Any, configuration: Dict[str, Any], device_id: int = 0)

Bases: object

Driver for the Tecan Cavro XCalibur syringe pump. Uses ASCII DT protocol over RS-232 via USB-Serial adapter.

__init__(microscope_name: str, device_connection: Any, configuration: Dict[str, Any], device_id: int = 0) → None

Initialize the XCaliburPump.

Parameters:

• microscope_name (str) – Name of the microscope system using this device.

• device_connection (Serial) – Pre-established serial connection (created via connect() class method).

• configuration (dict) – Device-specific configuration dictionary from YAML.

• device_id (int, optional) – Identifier if multiple pumps of same type are used.

Methods

__init__(microscope_name, device_connection, ...)	Initialize the XCaliburPump.
connect(port[, baudrate, timeout])	Create a new Serial connection to the pump.
disconnect()	Close the serial connection to the pump.
get_max_position()	Return the maximum allowed plunger position based on positioning mode.
get_status()	Send the '?' command to query current pump status.
initialize_pump()	Send the 'ZR' (Zero and Reset) command to initialize the pump state.
move_absolute(position)	Move the syringe plunger to an absolute position.
move_relative(steps)	Move the syringe plunger by a relative number of steps.
parse_response(response)	Parse the response string from the pump and extract the status code.
read_response([expected_bytes])	Read a response from the pump after sending a command.
send_command(command)	Send a command string to the pump, appending carriage return.
set_fine_positioning_mode([enable])	Enable or disable fine positioning mode and update internal state.
set_speed(speed)	Set the pump plunger speed using a predefined speed code.
valve_bypass()	Move valve to bypass position (input connected directly to output).
valve_extra()	Move valve to extra port (3-port distribution valve only).
valve_input()	Move valve to input position (aspiration setup).
valve_output()	Move valve to output position (dispensing setup).

Attributes

ERROR_CODES
device_name	Name of the microscope system using this device.
serial	Pre-established serial connection to the pump.
configuration	Configuration dictionary from YAML.
device_id	Identifier for this pump instance (if multiple pumps are used).
min_speed_code	Minimum speed code for plunger movement.
max_speed_code	Maximum speed code for plunger movement.
fine_positioning	Whether the pump is in fine positioning mode.
port	Serial port name (e.g., '/dev/ttyUSB0').
baudrate	Baudrate for the serial connection (e.g., 9600).
timeout	Timeout for the serial connection (e.g., 0.25 seconds).

classmethod connect(port: str, baudrate: int = 9600, timeout: float = 0.25) → Serial

Create a new Serial connection to the pump.

Parameters:

• port (str) – The serial port to connect to (e.g., ‘/dev/ttyUSB0’).

• baudrate (int, optional) – The baud rate for the serial connection (default is 9600).

• timeout (float, optional) – The timeout for read operations (default is 0.25 seconds).

Returns:

An open Serial object connected to the specified port.

Return type:

Serial

disconnect() → None

Close the serial connection to the pump.

get_max_position() → int

Return the maximum allowed plunger position based on positioning mode.

Returns:

Maximum plunger position in microsteps or encoder units.

Return type:

int

get_status() → str

Send the ‘?’ command to query current pump status.

initialize_pump() → None

Send the ‘ZR’ (Zero and Reset) command to initialize the pump state.

This is typically called at startup to ensure the pump is in a known idle state and the plunger position is zeroed.

It’s not strictly required before all commands, but it’s good practice, especially after power-on or fault conditions.

move_absolute(position: int) → None

Move the syringe plunger to an absolute position.

Sends the ‘A’ (move Absolute) command to the pump, instructing it to move the plunger to the specified absolute position.

Parameters:

position (int) – Target plunger position, in pump-specific units (e.g., microsteps or encoder units). Must be within the valid motion range defined by the pump configuration.

Raises:

UserVisibleException – If the specified position is out of bounds or if the pump returns an error status.

move_relative(steps: int) → None

Move the syringe plunger by a relative number of steps.

This sends the ‘M’ (move Relative) command to the pump. The motion will be accepted as long as the resulting absolute position remains within the allowed range (0 to 3000 in standard mode, 0 to 24000 in fine positioning mode).

Notes

This method does not perform bounds checking. If the relative move would result in an invalid plunger position, the pump will reject the command and return an appropriate error status (e.g., plunger overtravel).

Parameters:

steps (int) – Number of increments to move. Positive = forward, negative = backward.

Raises:

UserVisibleException – If the pump rejects the command or serial communication fails.

parse_response(response: str) → str

Parse the response string from the pump and extract the status code.

The status code indicates whether the command was accepted (/0), or rejected due to a specific error (e.g. /1 = invalid command, /3 = not initialized).

Parameters:

response (str) – Full raw response string from the pump (e.g., “/00”).

Returns:

Status code as a string (“0” = success, “1” = error, etc.)

Return type:

str

Raises:

UserVisibleException – If the response is malformed or indicates a hardware error.

read_response(expected_bytes: int = 32) → str

Read a response from the pump after sending a command.

Parameters:

expected_bytes (int) – How many bytes to attempt to read (or until timeout).

Returns:

The decoded response string.

Return type:

str

Raises:

UserVisibleException – If the serial connection is not open, the response is empty, or a decoding error occurs.

send_command(command: str) → bytes

Send a command string to the pump, appending carriage return.

Parameters:

command (str) – The ASCII command to send (without carriage return).

Returns:

The raw command sent, encoded as bytes.

Return type:

bytes

Raises:

UserVisibleException – If the serial connection is not established or the write fails.

set_fine_positioning_mode(enable: bool = True) → None

Enable or disable fine positioning mode and update internal state.

The pump must be initialized and idle before calling this method.

Parameters:

enable (bool) – If True, enables fine positioning mode (N1). If False, disables it (N0 - standard mode).

Raises:

UserVisibleException – If the pump rejects the configuration command or fails to apply it.

set_speed(speed: int) → None

Set the pump plunger speed using a predefined speed code.

Sends the ‘S’ (Speed) command to configure the speed at which the plunger moves during subsequent operations. The speed is specified as an integer code between 0 and 40, which the pump firmware maps to a specific plunger velocity and stroke time.

Speed code 0 corresponds to the fastest movement (6000 pulses/sec), and code 40 to the slowest (10 pulses/sec). These codes are defined by the internal firmware and can be constrained during driver initialization using ‘min_speed_code’ and ‘max_speed_code’.

Parameters:

speed (int) – Speed code to set. Must be within the range defined by ‘self.min_speed_code’ and ‘self.max_speed_code’.

Raises:

UserVisibleException – If the speed code is out of bounds or the command is rejected.

valve_bypass() → None

Move valve to bypass position (input connected directly to output).

Raises:

UserVisibleException – If the valve command fails or the pump returns an error.

valve_extra() → None

Move valve to extra port (3-port distribution valve only).

Raises:

UserVisibleException – If the valve command fails or the pump returns an error.

valve_input() → None

Move valve to input position (aspiration setup).

Raises:

UserVisibleException – If the valve command fails or the pump returns an error.

valve_output() → None

Move valve to output position (dispensing setup).

Raises:

UserVisibleException – If the valve command fails or the pump returns an error.

baudrate

Baudrate for the serial connection (e.g., 9600).

Type:

int

configuration

Configuration dictionary from YAML.

Type:

dict

device_id

Identifier for this pump instance (if multiple pumps are used).

Type:

int

device_name

Name of the microscope system using this device.

Type:

str

fine_positioning

Whether the pump is in fine positioning mode.

Type:

bool

max_speed_code

Maximum speed code for plunger movement. Default is 40.

Type:

int

min_speed_code

Minimum speed code for plunger movement. Default is 0.

Type:

int

port

Serial port name (e.g., ‘/dev/ttyUSB0’).

Type:

str

serial

Pre-established serial connection to the pump.

Type:

Serial

timeout

Timeout for the serial connection (e.g., 0.25 seconds).

Type:

str