baldaquin.serial_ — Serial interface

The module provides basically an abstraction layer over the pyserial package.

The DeviceId class is a simple class grouping the vendor and product IDs of a device into a single data structure. The Port class represents a serial port, and groups the most useful things out of the ListPortInfo class from pyserial.

The most useful bit in the module is probably the list_com_ports(), listing all the COM ports, along wit the device that are attached to them.

>>> ports = serial_.list_com_ports()
>>> [INFO] Scanning serial devices...
>>> [DEBUG] Port(name='/dev/ttyS0', device_id=(vid=None, pid=None), manufacturer=None)
>>> [DEBUG] Port(name='/dev/ttyACM0', device_id=(vid=0x2341, pid=0x43), manufacturer='Arduino (www.arduino.cc)')
>>> [INFO] Done, 2 device(s) found.

The method allows to filter over device IDs (or, equivalently, over vid, pid tuples) which comes handy when one is interested in a particular device or set of devices.

>>> ports = serial_.list_com_ports((0x2341, 0x0043))
>>> [INFO] Scanning serial devices...
>>> [DEBUG] Port(name='/dev/ttyS0', device_id=(vid=None, pid=None), manufacturer=None)
>>> [DEBUG] Port(name='/dev/ttyACM0', device_id=(vid=0x2341, pid=0x43), manufacturer='Arduino (www.arduino.cc)')
>>> [INFO] Done, 2 device(s) found.
>>> [INFO] Filtering port list for specific devices: [(vid=0x2341, pid=0x43)]...
>>> [INFO] Done, 1 device(s) remaining.
>>> [DEBUG] Port(name='/dev/ttyACM0', device_id=(vid=0x2341, pid=0x43), manufacturer='Arduino (www.arduino.cc)')

In addition, the SerialInterface acts like a base class that can be subclassed to implement any specific communication protocol over the serial port.

Module documentation

Serial port interface.

class baldaquin.serial_.DeviceId(vid: int, pid: int)

Data class to hold the device id information.

A device id is basically a tuple of two integers, the vendor id (vid) and the product id (pid), and the class has exactly these two members.

Parameters:

• vid (int) – The vendor id.

• pid (int) – The product id.

vid: int

pid: int

static _hex(value: int) → str

Convenience function to format an integer as a hexadecimal string, gracefully handling the case when the input is not an integer.

class baldaquin.serial_.Port(name: str, device_id: DeviceId, manufacturer: str | None = None)

Small data class holding the informatio about a COM port.

This is a simple wrapper around the serial.tools.list_ports_common.ListPortInfo isolating the basic useful functionalities, for the sake of simplicity.

See https://pyserial.readthedocs.io/en/latest/tools.html#serial.tools.list_ports.ListPortInfo for more information.

Parameters:

• name (str) – The name of the port (e.g., /dev/ttyACM0).

• device_id (DeviceId) – The device id.

• manufacturer (str, optional) – The manufacturer of the device attached to the port.

name: str

device_id: DeviceId

manufacturer: str = None

classmethod from_port_info(port_info: ListPortInfo) → Port

Create a Port object from a ListPortInfo object.

baldaquin.serial_.list_com_ports(*device_ids: DeviceId) → list[Port]

List all the com ports with devices attached, possibly with a filter on the device ids we are interested into.

Parameters:

device_ids (DeviceId or vid, pid tuples, optional) – An arbitrary number of device ids to filter the list of ports returned by pyserial. This is useful when we are searching for a specific device attached to a port; an arduino uno, e.g., might look something like (0x2341, 0x43).

Returns:

The list of COM ports.

Return type:

list of Port objects

class baldaquin.serial_.SerialInterface(port=None, baudrate=9600, bytesize=8, parity='N', stopbits=1, timeout=None, xonxoff=False, rtscts=False, write_timeout=None, dsrdtr=False, inter_byte_timeout=None, exclusive=None, **kwargs)

Small wrapper around the serial.Serial class.

setup(port: str, baudrate: int = 115200, timeout: float | None = None) → None

Setup the serial connection.

Parameters:

• port (str) – The name of the port to connect to (e.g., /dev/ttyACM0).

• baudrate (int) –

  The baud rate.

  Verbatim from the pyserial documentation: the parameter baudrate can be one of the standard values: 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200. These are well supported on all platforms.

  Standard values above 115200, such as: 230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000, 4000000 also work on many platforms and devices.

  Non-standard values are also supported on some platforms (GNU/Linux, MAC OSX >= Tiger, Windows). Though, even on these platforms some serial ports may reject non-standard values.

• timeout (float) –

  The timeout in seconds.

  Verbatim from the pyserial documentation: possible values for the parameter timeout which controls the behavior of read():

  • timeout = None: wait forever / until requested number of bytes are received

  • timeout = 0: non-blocking mode, return immediately in any case, returning zero or more, up to the requested number of bytes

  • timeout = x: set timeout to x seconds (float allowed) returns immediately when the requested number of bytes are available, otherwise wait until the timeout expires and return all bytes that were received until then.

connect(port: str, baudrate: int = 115200, timeout: float | None = None) → None

Connect to the serial port.

Parameters:

• port (str) – The name of the serial port (e.g., /dev/ttyACM0).

• baudrate (int) – The baud rate.

• timeout (float, optional) – The timeout in seconds.

disconnect()

Disconnect from the serial port.

pulse_dtr(pulse_length: float = 0.5) → None

Pulse the DTR line for a given amount of time.

This asserts the DTR line, waits for a specific amount of time, and then deasserts the line.

Parameters:

pulse_length (float) – The duration (in seconds) for the DTR line signal to be asserted.

read_and_unpack(fmt: str) → Any

Read a given number of bytes from the serial port and unpack them.

Note that the number of bytes to be read from the serial port is automatically calculated from the format string. See https://docs.python.org/3/library/struct.html for all the details about format strings and byte ordering.

Parameters:

fmt (str) – The format string for the packet to be read from the seria port.

Returns:

Returns the proper Python object for the format string at hand.

Return type:

any

Example

>>> s = SerialInterface(port)
>>> val = s.read_and_unpack('B') # Single byte (val is int)
>>> val = s.read_and_unpack('>L') # Big-endian unsigned long (val is also int)

pack_and_write(value: Any, fmt: str) → int

Pack a given value into a proper bytes object and write the latter to the serial port.

Parameters:

• value (any) – The value to be written to the serial port.

• fmt (str) – The format string to pack the value with.

Returns:

The number of bytes written to the serial port.

Return type:

int

_abc_impl = <_abc._abc_data object>