Reference Index

class serial_singleton.SerialSingleton(port=None, connect=True, **kwargs)

close()

Close port

Return type:: None

open()

Open port with current settings. This may throw a SerialException if the port cannot be opened.

Return type:: None

property port: str | None

Get the serial device’s communication port.

Returns:: str – The serial port (e.g., ‘COM3’, ‘/dev/ttyUSB0’) used by the serial device.

query(query, data_specifier=1)

Query data from the serial device.

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

Parameters:

query (any) – Query to be sent to the serial device.
data_specifier (int or str, default: 1) –
The number of bytes to receive from the serial device, or a format string for unpacking.

When providing an integer, the specified number of bytes will be returned as a bytestring. When providing a format string, the data will be unpacked into a tuple accordingly. Format strings follow the conventions of the struct module.

Returns:

bytes or tuple[Any] – Data returned by the serial device. By default, data is formatted as a bytestring. Alternatively, when provided with a format string, data will be unpacked into a tuple according to the specified format string.

read(data_specifier=1)

Read data from the serial device.

Parameters:

data_specifier (int or str, default: 1) –

The number of bytes to receive from the serial device, or a format string for unpacking.

When providing an integer, the specified number of bytes will be returned as a bytestring. When providing a format string, the data will be unpacked into a tuple accordingly. Format strings follow the conventions of the struct module.

Returns:

bytes or tuple[Any] – Data returned by the serial device. By default, data is formatted as a bytestring. Alternatively, when provided with a format string, data will be unpacked into a tuple according to the specified format string.

static to_bytes(data)

Convert data to bytestring.

This method extends serial.to_bytes() with support for NumPy types, strings (interpreted as utf-8) and lists.

Parameters:: data (any) – Data to be converted to bytestring.
Returns:: bytes – Data converted to bytestring.

write(data)

Write data to the serial device.

Parameters:: data (any) – Data to be written to the serial device. See https://docs.python.org/3/library/struct.html#format-characters
Returns:: int or None – Number of bytes written to the serial device.

exception serial_singleton.SerialSingletonException

serial_singleton.filter_ports(**kwargs)

Filter serial ports based on specified criteria.

Parameters:: **kwargs (keyword arguments) – Filtering criteria for serial ports. Each keyword should correspond to an attribute of the serial port object (ListPortInfo). The values associated with the keywords are used to filter the ports based on various conditions.
Yields:: str – The device name of a filtered serial port that meets all specified criteria.
Return type:: Iterable[str]

Examples

To filter ports by manufacturer and product:

>>> for port in filter_ports(manufacturer="Arduino", product="Uno"):
...     print(port)

Raises:: ValueError – If a specified attribute does not exist for a port.

Notes

The function uses regular expressions for string matching when both actual and expected values are strings.

serial_singleton.get_port_from_serial_number(serial_number)

Retrieve the com port of a USB serial device identified by its serial number.

Parameters:: serial_number (str) – The serial number of the USB device that you want to obtain the communication port of.
Returns:: str or None – The communication port of the USB serial device that matches the serial number provided by the user. The function will return None if no such device was found.

serial_singleton.get_serial_number_from_port(port)

Retrieve the serial number of a USB serial device identified by its com port.

Parameters:: port (str) – The communication port of the USB serial device for which you want to retrieve the serial number.
Returns:: str or None – The serial number of the USB serial device corresponding to the provided communication port. Returns None if no device matches the port.