bpod_modules_ibl.RotaryEncoderModule

class bpod_modules_ibl.RotaryEncoderModule

Bases: object

__init__(port, encoder_resolution=1024, reset_to_defaults=True)

Create a RotaryEncoderModule instance and open the connection.

Parameters:

  • port (str) – Serial port name (e.g., '/dev/ttyACM0' or 'COM5').

  • encoder_resolution (int, optional) – The incremental encoder’s resolution in pulses per revolution. Defaults to 1024.

  • reset_to_defaults (bool, optional) – Whether to reset the Rotary Encoder Module to default settings. Defaults to True.

Raises:

  • SerialException – If the port cannot be opened during the probe step.

  • ValueError – If the device on the given port does not appear to be a Rotary Encoder Module.

close() → None

Close serial connection to the Rotary Encoder Module.

Return type:

None

enable_thresholds(value)

Enable or disable thresholds based on the provided value.

Parameters:

value (bool, str or Sequence of int) –

  • If bool: enables all 8 thresholds if True, or disables them if False.

  • If str: must be a binary string of exactly 8 characters (e.g., ‘11010100’). Each character represents whether the corresponding threshold (bit 0 to 7) should be enabled (1) or disabled (0).

  • If Sequence[int]: a sequence of integers (ranging from 0 to 7) specifying which thresholds to enable. All other thresholds will be disabled.

Raises:

ValueError – If value is not a bool, a valid binary string, or a valid sequence of integers.

get_degrees() → float

Get the current encoder position in degrees.

Returns:

The current encoder position in degrees.

Return type:

float

get_logged_data() → ndarray[tuple[int, ...], dtype[void]]

Retrieve logged data from the SD card.

Returns:

Structured NumPy array with one element per logged sample. Each element has the following fields:

Return type:

numpy.ndarray

get_tics() → int

Get the current encoder position in tics.

Returns:

The current encoder position in tics.

Return type:

int

open() → None

Open serial connection to the Rotary Encoder Module.

Return type:

None

static probe(port, raise_value_error=True)

Probe for a Rotary Encoder Module on the specified port.

Parameters:

  • port (str) – The port to probe.

  • raise_value_error (bool, optional) – Whether to raise a ValueError when device does not appear to be a rotary encoder. Defaults to True.

Returns:

The hardware version of the Rotary Encoder Module. Will return None if the device does not appear to be a Rotary Encoder Module and raise_value_error is False.

Return type:

int or None

Raises:

  • SerialException – If the port cannot be opened.

  • ValueError – If the device does not appear to be a Rotary Encoder Module and raise_value_error is True.

reset()

Reset Rotary Encoder Module to default settings.

set_degrees(degrees)

Set the current encoder position in degrees.

Parameters:

degrees (float) – The new encoder position in degrees.

Raises:

  • RuntimeError – When setting of the encoder position fails.

  • ValueError – When the new encoder position is outside the allowed range.

set_event_callback(callback_function) → None
Return type:

None

Parameters:

callback_function (Callable[[int, int, int], None])

set_event_transmission(value)
Parameters:

value (bool)

set_position_callback(callback_function) → None
Return type:

None

Parameters:

callback_function (Callable[[int, float], None])

set_resolution(value) → None

Set the encoder resolution in tics per revolution.

Parameters:

value (int) – The new encoder resolution in tics per revolution. Must be a positive integer.

Raises:

ValueError – If the encoder resolution is not a positive integer.

Return type:

None

set_sd_logging(enable_logging) → None

Enable or disable SD card logging.

Parameters:

enable_logging (bool) – Whether to enable SD card logging. True enables logging, False disables it.

Raises:

RuntimeError – If the hardware does not support SD card logging.

Return type:

None

set_stream_prefix(prefix=b'M') → None

Set the stream prefix.

Parameters:

prefix (str or bytes, optional) – A single character or byte to be used as the stream prefix.

Raises:

  • ValueError – If the prefix is not a single character or byte.

  • RuntimeError – If the hardware version is not 1 or if setting the prefix fails.

Return type:

None

set_thresholds(degrees) → None

Set the thresholds in degrees.

Parameters:

degrees (Sequence of float) – Thresholds in degrees. The sequence must not contain more than 8 values.

Raises:

  • ValueError – If any threshold exceeds the current wrap point or the number of thresholds exceeds 8.

  • RuntimeError – If setting of the thresholds fails.

Return type:

None

set_tics(tics)

Set the current encoder position in tics.

Parameters:

tics (int) – The new encoder position in tics. Value must be an integer between -32768 and 32767.

Raises:

  • RuntimeError – When setting of the encoder position fails.

  • ValueError – When the new encoder position is outside the allowed range.

set_usb_stream(enable) → None
Return type:

None

Parameters:

enable (bool)

set_wrap_mode(mode)
Parameters:

mode (Literal['bipolar', 'unipolar'])

set_wrap_point(degrees) → None

Set the wrap point in degrees.

Parameters:

degrees (float) – The new wrap point in degrees.

Return type:

None

zero() → None

Reset current encoder position to zero.

Return type:

None

property clock_multiplier: int

Clock multiplier of the Rotary Encoder Module.

property event_transmission: bool

The state of event transmission.

property hardware_version: int

Hardware version of the Rotary Encoder Module.

property is_usb_streaming: bool

Whether the USB stream is active or not.

property port: str | None

Port name of the Rotary Encoder Module.

property resolution: int

Resolution of the rotary encoder in pulses per revolution.

property sd_logging: bool

The state of SD card logging.

property thresholds: list[float]

List of thresholds in degrees.

property wrap_mode: Literal['bipolar', 'unipolar']

The wrap mode of the rotary encoder.

property wrap_point: float

The current wrap point in degrees.