Warning

This documentation is actively being updated as the project evolves and may not be complete in all areas.

PySerial driver¶

jumpstarter-driver-pyserial provides functionality for serial port communication.

Installation¶

$ pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple jumpstarter-driver-pyserial

Configuration¶

Example configuration:

export:
  serial:
    type: jumpstarter_driver_pyserial.driver.PySerial
    config:
      url: "/dev/ttyUSB0"
      baudrate: 115200
      cps: 10  # Optional: throttle to 10 characters per second

Config parameters¶

Parameter	Description	Type	Required	Default
url	The serial port to connect to, in pyserial format	str	yes
baudrate	The baudrate to use for the serial connection	int	no	115200
check_present	Check if the serial port exists during exporter initialization, disable if you are connecting to a dynamically created port (i.e. USB from your DUT)	bool	no	True
cps	Characters per second throttling limit. When set, data transmission will be throttled to simulate slow typing. Useful for devices that can’t handle fast input	float	no	None

CLI Commands¶

The pyserial driver provides two CLI commands for interacting with serial ports:

start_console¶

Start an interactive serial console with direct terminal access.

j serial start-console

Exit the console by pressing CTRL+B three times.

pipe¶

Pipe serial port data to stdout or a file. Automatically detects if stdin is piped and enables bidirectional mode.

When stdin is used, commands are sent until EOF, then continues monitoring serial output until Ctrl+C.

# Log serial output to stdout
j serial pipe

# Log serial output to a file
j serial pipe -o serial.log

# Send command to serial, then continue monitoring output
echo "hello" | j serial pipe

# Send commands from file, then continue monitoring output
cat commands.txt | j serial pipe -o serial.log

# Force bidirectional mode (interactive)
j serial pipe -i

# Append to log file instead of overwriting
j serial pipe -o serial.log -a

# Disable stdin input even when piped
cat data.txt | j serial pipe --no-input

Options¶

-o, --output FILE: Write serial output to a file instead of stdout
-i, --input: Force enable stdin to serial port (auto-detected if piped)
--no-input: Disable stdin to serial port, even if stdin is piped
-a, --append: Append to output file instead of overwriting

Exit with Ctrl+C.

API Reference¶

class jumpstarter_driver_pyserial.client.PySerialClient¶

A client for handling serial communication using pexpect.

close()¶: Close the open stream session without a context manager.

open() → fdspawn¶

Open a pexpect session. You can find the pexpect documentation here: https://pexpect.readthedocs.io/en/stable/api/pexpect.html#spawn-class

Returns:: fdspawn: The pexpect session object.

open_stream() → BlockingStream¶

Open a blocking stream session without a context manager.

Returns:: blocking stream session object.
Return type:: BlockingStream

pexpect()¶

Create a pexpect adapter context manager.

Yields:: PexpectAdapter: The pexpect adapter object.

stream(method='connect')¶

Open a blocking stream session with a context manager.

Parameters:: method (str) – method name of streaming driver call
Returns:: blocking stream session object context manager.

Examples¶

Using expect with a context manager

with pyserialclient.pexpect() as session:
    session.sendline("Hello, world!")
    session.expect("Hello, world!")

Using expect without a context manager

session = pyserialclient.open()
session.sendline("Hello, world!")
session.expect("Hello, world!")
pyserialclient.close()

Using a simple BlockingStream with a context manager

with pyserialclient.stream() as stream:
    stream.send(b"Hello, world!")
    data = stream.receive()

Using a simple BlockingStream without a context manager

stream = pyserialclient.open_stream()
stream.send(b"Hello, world!")
data = stream.receive()