ExtendedSerial¶

class bpod_core.com.ExtendedSerial ¶

Bases: Serial

Enhances serial.Serial with additional functionality.

query(query, size=1) ¶

Query data from the serial port.

This method is a combination of write() and read().

Parameters:

query (Buffer) – Query to be sent to the serial port.
size (int, default: 1) – The number of bytes to receive from the serial port.

Returns:

Data returned by the serial device in response to the query.

Return type:

bytes

Examples

Send a command and read back multiple bytes:

response = serial_port.query(b'\x4A', size=4)

query_struct(query, format_string) ¶

Query structured data from the serial port.

This method queries a specified number of bytes from the serial port and unpacks it into a tuple according to the provided format string.

Parameters:

query (Buffer) – Query to be sent to the serial port.
format_string (str) – A format string that specifies the layout of the data to be read. It should be compatible with the struct module’s format specifications.

Returns:

A tuple containing the unpacked data read from the serial port. The structure of the tuple corresponds to the format specified in format_string.

Return type:

tuple

Examples

Send a command and unpack the response as two unsigned 8-bit integers:

major, minor = serial_port.query_struct(b'\x4a', 'BB')

read_bool() ¶

Read a boolean value from the serial port.

Return type:: bool

read_int16() ¶

Read a 16-bit signed integer from the serial port (little-endian).

Return type:: int

read_int32() ¶

Read a 32-bit signed integer from the serial port (little-endian).

Return type:: int

read_int64() ¶

Read a 64-bit signed integer from the serial port (little-endian).

Return type:: int

read_int8() ¶

Read an 8-bit signed integer from the serial port.

Return type:: int

read_struct(format_string) ¶

Read structured data from the serial port.

This method reads a specified number of bytes from the serial port and unpacks it into a tuple according to the provided format string.

Parameters:: format_string (str) – A format string that specifies the layout of the data to be read. It should be compatible with the struct module’s format specifications.
Returns:: A tuple containing the unpacked data read from the serial port. The structure of the tuple corresponds to the format specified in format_string.
Return type:: tuple

Examples

Read one unsigned 16-bit integer followed by two unsigned 8-bit integers:

major, minor, patch = serial_port.read_struct('<HBB')

read_struct_iter(fmt, n=1, *, flatten=False) ¶

Read structured data from the serial port as an iterator.

Parameters:

fmt (str or struct.Struct) – A pre-compiled struct or a format string compatible with the struct module’s format specifications.
n (int, default: 1) – Number of records to read.
flatten (bool, default: False) – If True, yield individual values instead of tuples.

Yields:

tuple or Any – Each unpacked record as a tuple, or individual values if flatten=True.

Return type:

Iterator[tuple[Any, ...]] | Iterator[Any]

Notes

All bytes are read in a single call before any records are yielded. Use stream_struct() instead if records should be yielded as they arrive.

Examples

Read three records as tuples:

for value, flag in serial_port.read_struct_iter('<HB', 3):
    print(value, flag)

Read two records as individual integers:

v1, f1, v2, f2 = serial_port.read_struct_iter('<HB', 2, flatten=True)

read_uint16() ¶

Read a 16-bit unsigned integer from the serial port (little-endian).

Return type:: int

read_uint32() ¶

Read a 32-bit unsigned integer from the serial port (little-endian).

Return type:: int

read_uint64() ¶

Read a 64-bit unsigned integer from the serial port (little-endian).

Return type:: int

read_uint8() ¶

Read an 8-bit unsigned integer from the serial port.

Return type:: int

stream_struct(fmt, n, *, flatten=True) ¶

Stream structured data from the serial port, yielding one record at a time.

Parameters:

fmt (str or struct.Struct) – A pre-compiled struct or a format string compatible with the struct module’s format specifications.
n (int) – Number of records to read.
flatten (bool, default: True) – If True, yield individual values instead of tuples.

Yields:

Any or tuple – Individual values if flatten=True, otherwise one tuple per record.

Return type:

Iterator[Any] | Iterator[tuple[Any, ...]]

Notes

Each record is read and yielded as soon as its bytes arrive, using one readinto() call per record. Use read_struct_iter() instead if all data is available upfront and a single read call is preferred.

Examples

Stream 100 uint32 samples, yielding each as it arrives:

for sample in serial_port.stream_struct('<I', 100):
    process(sample)

Stream 10 records of 3 floats as tuples:

for x, y, z in serial_port.stream_struct('<3f', 10, flatten=False):
    print(x, y, z)

verify(query=b'', expected_response=b'\\x01') ¶

Verify the response of the serial port.

This method sends a query to the serial port and checks if the response matches the expected response.

Parameters:

query (Buffer, default: b``’’``) – The query to be sent to the serial port.
expected_response (bytes, default: b``’x01’``) – The expected response from the serial port.

Returns:

True if the response matches the expected response, False otherwise.

Return type:

bool

write_bool(value) ¶

Write a boolean value to the serial port.

Return type:: int | None

write_int16(value) ¶

Write a 16-bit signed integer to the serial port (little-endian).

Return type:: int | None

write_int32(value) ¶

Write a 32-bit signed integer to the serial port (little-endian).

Return type:: int | None

write_int64(value) ¶

Write a 64-bit signed integer to the serial port (little-endian).

Return type:: int | None

write_int8(value) ¶

Write an 8-bit signed integer to the serial port.

Return type:: int | None

write_struct(format_string, *data) ¶

Write structured data to the serial port.

This method packs the provided data into a binary format according to the specified format string and writes it to the serial port.

Parameters:

format_string (str) – A format string that specifies the layout of the data. It should be compatible with the struct module’s format specifications.
*data (Any) – Variable-length arguments representing the data to be packed and written, corresponding to the format specifiers in format_string.

Returns:

The number of bytes written to the serial port, or None if the write operation fails.

Return type:

int or None

Raises:

struct.error – Error occurred during packing of the data into binary format.
SerialTimeoutException – In case a write timeout is configured for the port and the time is exceeded.

Examples

Write a command byte followed by a 16-bit unsigned integer:

serial_port.write_struct('<BH', 0x4A, 1000)

write_uint16(value) ¶

Write a 16-bit unsigned integer to the serial port (little-endian).

Return type:: int | None

write_uint32(value) ¶

Write a 32-bit unsigned integer to the serial port (little-endian).

Return type:: int | None

write_uint64(value) ¶

Write a 64-bit unsigned integer to the serial port (little-endian).

Return type:: int | None

write_uint8(value) ¶

Write an 8-bit unsigned integer to the serial port.

Return type:: int | None