poulet_py.hardware.stimulator.qst module

Thermal Control System (TCS) interface module.

This module provides a Python interface for communicating with a TCS thermal stimulator via serial connection. It includes command definitions, stimulus configuration, and data reading capabilities.

Examples

>>> with TCS(port="/dev/ttyUSB0") as tcs:
...     tcs.init()
...     stimulus = TCSStimulus(surface=1, target=35.0)
...     tcs.stimulus = stimulus
...     tcs.trigger()
...     readings = tcs.get_readings()
...     print(readings)

class TCSCommand(*values)

Bases: bytes, Enum

Enumeration of all available TCS commands with their byte representations.

Each command includes formatting capability for parameterized commands.

Examples

>>> TCSCommand.READ_TEMPERATURES
<TCSCommand.READ_TEMPERATURES: b'E'>
>>> TCSCommand.BASELINE_TEMPERATURE.format(300)
b'N300'

READ_INFO = b'H'

READ_TEMPERATURES = b'E'

READ_STIMULATION_VALUES = b'P'

READ_BUTTON_STATUS = b'K'

READ_BATTERY = b'B'

READ_ERRORS = b'Q'

DISPLAY_TEMPERATURES_BETWEEN_STIMULATION = b'Oa'

DISPLAY_TEMPERATURES_DURING_STIMULATION = b'Ob'

RESET = b'Oc'

SET_MAX_TEMPERATURE = b'Om%03d'

AUTOMATIC_CALIBRATION = b'G'

DEACTIVATE_DISPLAY = b'F'

TRIGGER_STIMULATION = b'L'

HALT_STIMULATION = b'A'

BASELINE_TEMPERATURE = b'N%03d'

SURFACE_SELECTION = b'S%05d'

TARGET_TEMPERATURE = b'C%d%03d'

STIMULATION_RATE = b'V%d%04d'

RETURN_SPEED = b'R%d%04d'

STIMULATION_DURATION = b'D%d%05d'

TRIGGER_CHANNEL_DURATION = b'T%03d%03d'

BUZZER = b'Z%03d%03d'

format(*args)

Format the command with the given arguments.

Parameters:

*args (int, float) – Arguments to format into the command string

Returns:

Formatted command string

Return type:

bytes

Raises:

ValueError – If arguments don’t match the command’s format requirements

Examples

>>> TCSCommand.TARGET_TEMPERATURE.format(1, 350)
b'C1350'

class TCSStimulus(**data)

Bases: BaseModel

Configuration for thermal stimulation parameters.

surface: int

baseline: float

target: float

rise_rate: float

return_speed: float

duration: int

commands()

Generate the sequence of commands needed to configure this stimulus.

Returns:

Sequence of formatted command strings

Return type:

Tuple[bytes, …]

Examples

>>> stimulus = TCSStimulus(surface=1)
>>> stimulus.commands()
[b'S10000', b'N300', b'C1000', b'V10010', b'D100100', b'R10010']

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class TCS(port, *, maximum_temperature=40, beep=False, trigger_out_channel=255, read_timeout=2, response_timeout=2)

Bases: object

Interface for communicating with a TCS thermal stimulator.

__init__(port, *, maximum_temperature=40, beep=False, trigger_out_channel=255, read_timeout=2, response_timeout=2)

Initialize TCS interface with validation.

Args:

port: Serial port device path (e.g. ‘/dev/ttyUSB0’ or ‘COM3’) maximum_temperature: Safety limit for maximum allowed temperature (0-60°C) beep: Whether to enable audible beep during stimulation trigger_out_channel: Output channel of trigger signal (1-255) read_timeout: Serial read timeout in seconds response_timeout: Timeout for command responses in seconds

property stimulus: TCSStimulus

write(command)

Write a command to the TCS device.

Parameters:

command (bytes) – The command to send

Returns:

Number of bytes written

Return type:

int

Raises:

RuntimeError – If the write operation fails

execute_command(command, *args, expected_pattern=None)

Execute a command and optionally wait for a response.

Parameters:

• command (TCSCommand) – The command to execute

• *args – Arguments to format into the command

• expected_pattern (Pattern | None) – Regex pattern to match against the response

Returns:

If expected_pattern provided, returns (timestamp, match) tuple

Return type:

tuple[int, Match[str]]] | None

Examples

>>> tcs.execute_command(TCSCommand.READ_INFO, expected_pattern=compile(r"Firmware:(.*)"))

init()

Initialize the TCS connection and verify communication.

Raises:

RuntimeError – If initialization fails

close()

Close the connection and clean up resources.

info()

Get device information including firmware version and probe details.

Returns:

Device information string

Return type:

str

Raises:

RuntimeError – If the info command fails or times out

reset()

Reset the TCS device to its default state.

trigger()

Execute the configured stimulation.

Raises:

RuntimeError – If stimulation fails to trigger

get_readings()

Get current temperature readings from all sensors.

Returns:

Dictionary containing temperatures for neutral and all surfaces, plus a timestamp key.

Return type:

Dict[str, float]

Raises:

RuntimeError – If reading temperatures fails