Skip to content
Back to top
View this page
Edit this page

# Core API reference

The API reference is generated with Sphinx autodoc from docstrings in `serialx`.

Platform APIs

- POSIX
- Extended POSIX
- Linux
- macOS
- FreeBSD
- Windows
- Socket
- RFC2217
- ESPHome
- Pyodide (Web Serial)

## Top-level package

serialx serial port implementation.

class serialx.AsyncSerial

  Bases: `object`

  Async serial port with a sync-style API.

  __init__(url, *, transport_cls=None, **kwargs)

    Initialize an unopened serial port.

    Directly creating this class is not recommended; use async_serial_for_url instead.

    Parameters:

      - url (str | None)

      - transport_cls (type[BaseSerialTransport] | None)

      - kwargs (Any)

    Return type:

      None

  async open()

    Open the serial port connection.

    Return type:

      None

  async close()

    Close the connection and wait until the port is fully closed.

    Return type:

      None

  schedule_close()

    Signal a graceful close without waiting for it to finish.

    Return type:

      None

  abort()

    Drop pending writes and close immediately, without waiting.

    Return type:

      None

  async wait_closed()

    Wait until a previously-scheduled close or abort has finished.

    Return type:

      None

  property is_open: bool

    Whether the connection is currently open.

  async read(n=-1)

    Read up to n bytes (or until EOF if n is -1).

    Parameters:

      n (int)

    Return type:

      bytes

  async readexactly(n)

    Read exactly n bytes.

    Parameters:

      n (int)

    Return type:

      bytes

  async readuntil(separator=b'\n')

    Read up to and including separator.

    Parameters:

      separator (bytes)

    Return type:

      bytes

  async readline()

    Read until the next newline.

    Return type:

      bytes

  async write(data)

    Queue data for writing and wait for the application buffer to drain.

    Parameters:

      data (bytes | bytearray | memoryview)

    Return type:

      None

  async writelines(data)

    Queue buffers for writing and wait for the application buffer to drain.

    Parameters:

      data (Iterable[bytes | bytearray | memoryview])

    Return type:

      None

  write_nowait(data)

    Queue data for writing without waiting; pair with drain() to batch.

    Parameters:

      data (bytes | bytearray | memoryview)

    Return type:

      None

  writelines_nowait(data)

    Queue buffers for writing without waiting; pair with drain() to batch.

    Parameters:

      data (Iterable[bytes | bytearray | memoryview])

    Return type:

      None

  async drain()

    Wait until the application-level write buffer can accept more data.

    Return type:

      None

  async flush()

    Drain app-level buffer, then wait for the OS-level buffer to flush.

    Return type:

      None

  property transport: BaseSerialTransport

    Return the underlying serial transport.

  async get_modem_pins()

    Get modem control pins.

    Return type:

      ModemPins

  async set_modem_pins(modem_pins=None, *, le=PinState.UNDEFINED, dtr=PinState.UNDEFINED, rts=PinState.UNDEFINED, st=PinState.UNDEFINED, sr=PinState.UNDEFINED, cts=PinState.UNDEFINED, car=PinState.UNDEFINED, rng=PinState.UNDEFINED, dsr=PinState.UNDEFINED)

    Set modem control pins.

    Parameters:

      - modem_pins (ModemPins | None)

      - le (PinState | bool | None)

      - dtr (PinState | bool | None)

      - rts (PinState | bool | None)

      - st (PinState | bool | None)

      - sr (PinState | bool | None)

      - cts (PinState | bool | None)

      - car (PinState | bool | None)

      - rng (PinState | bool | None)

      - dsr (PinState | bool | None)

    Return type:

      None

  property baudrate: int

    Get the baud rate.

  property parity: Parity

    Get the parity.

  property stopbits: StopBits

    Get the number of stop bits.

  property byte_size: int

    Get the byte size.

  property exclusive: bool

    Get the exclusive setting.

serialx.async_serial_for_url(url, *, transport_cls=None, **kwargs)

  Build an unopened AsyncSerial. Use async with or await serial.open().

  Parameters:

    - url (str | None)

    - transport_cls (type[BaseSerialTransport] | None)

    - kwargs (Any)

  Return type:

    AsyncSerial

async serialx.create_serial_connection(loop, protocol_factory, url, baudrate, parity=Parity.NONE, stopbits=StopBits.ONE, xonxoff=False, rtscts=False, exclusive=True, *, transport_cls=None, **kwargs)

  Create a serial port connection with asyncio.

  Parameters:

    - loop (AbstractEventLoop)

    - protocol_factory (Callable[[], Protocol])

    - url (str | None)

    - baudrate (int)

    - parity (Parity)

    - stopbits (StopBits)

    - xonxoff (bool)

    - rtscts (bool)

    - exclusive (bool)

    - transport_cls (type[BaseSerialTransport] | None)

    - kwargs (Any)

  Return type:

    tuple[BaseSerialTransport, Protocol]

serialx.get_serial_classes(url)

  Get the appropriate serial and transport classes based on the URL scheme.

  Parameters:

    url (str)

  Return type:

    tuple[type[BaseSerial], type[BaseSerialTransport]]

serialx.list_serial_ports(platform=Platform.DEVICE, **kwargs)

  List serial ports, defaulting to the system platform.

  Parameters:

    - platform (Platform | str)

    - kwargs (Any)

  Return type:

    list[SerialPortInfo]

async serialx.async_list_serial_ports(platform=Platform.DEVICE, **kwargs)

  List serial ports (async), defaulting to the system platform.

  Parameters:

    - platform (Platform | str)

    - kwargs (Any)

  Return type:

    list[SerialPortInfo]

async serialx.open_serial_connection(*args, **kwargs)

  Open a serial port connection using StreamReader and StreamWriter.

  Parameters:

    - args (Any)

    - kwargs (Any)

  Return type:

    tuple[StreamReader, SerialStreamWriter[BaseSerialTransport]]

serialx.register_uri_handler(*, scheme, unique_scheme, sync_cls, async_transport_cls, list_serial_ports_func=<function empty_port_list>, async_list_serial_ports_func=<function async_empty_port_list>, weight=1, strip_uri_scheme=False)

  Register a URI handler.

  Expose a new backend to `serial_for_url` / `create_serial_connection` / `open_serial_connection`.

  Parameters:

    - scheme (str) – Shared dispatch scheme. URLs with this scheme resolve to the highest-weight handler registered under it.

    - unique_scheme (str) – A scheme that uniquely identifies this handler. Must end with `://` and must not collide with an existing registration. Use this to address the handler directly.

    - sync_cls (type[BaseSerial]) – Synchronous serial class, typically a subclass of `BaseSerial`.

    - async_transport_cls (type[BaseSerialTransport]) – Async transport class, typically a subclass of `BaseSerialTransport`.

    - list_serial_ports_func (Callable[[...], list[SerialPortInfo]]) – Callable returning a list of `SerialPortInfo`.

    - async_list_serial_ports_func (Callable[[...], Awaitable[list[SerialPortInfo]]]) – Async callable returning a list of `SerialPortInfo`.

    - weight (int) – Dispatch priority under `scheme`. Higher wins.

    - strip_uri_scheme (bool) – If `True`, the leading `scheme` / `unique_scheme` is removed before the URL is passed to the sync class. Set this when the underlying class expects a bare device path rather than a URL.

  Returns:

    A callable that unregisters the handler.

  Raises:

    ValueError – if either scheme doesn’t end with `://` or `unique_scheme` is already registered.

  Return type:

    Callable[[], None]

serialx.serial_for_url(url, *args, **kwargs)

  Create the appropriate serial port subclass for the given URL.

  Parameters:

    - url (str)

    - args (Any)

    - kwargs (Any)

  Return type:

    BaseSerial

class serialx.ModemPins

  Bases: `object`

  Modem control bits.

  __init__(le=PinState.UNDEFINED, dtr=PinState.UNDEFINED, rts=PinState.UNDEFINED, st=PinState.UNDEFINED, sr=PinState.UNDEFINED, cts=PinState.UNDEFINED, car=PinState.UNDEFINED, rng=PinState.UNDEFINED, dsr=PinState.UNDEFINED)
    Parameters:

      - le (PinState)

      - dtr (PinState)

      - rts (PinState)

      - st (PinState)

      - sr (PinState)

      - cts (PinState)

      - car (PinState)

      - rng (PinState)

      - dsr (PinState)

    Return type:

      None

class serialx.Parity

  Bases: `str`, `Enum`

  Parity configuration.

  __new__(value)

class serialx.PinState

  Bases: `Enum`

  Pin state.

  classmethod convert(value)

    Create PinState from boolean.

    Parameters:

      value (PinState | bool | None)

    Return type:

      PinState

  to_bool()

    Convert PinState to boolean.

    Return type:

      bool | None

class serialx.Platform

  Bases: `str`, `Enum`

  Built-in platform name.

  __new__(value)

class serialx.BaseSerial

  Bases: `RawIOBase`

  Base class for serial port communication.

  __init__(path=None, baudrate=9600, *, parity=Parity.NONE, stopbits=StopBits.ONE, xonxoff=False, rtscts=False, dsrdtr=False, byte_size=8, read_timeout=None, write_timeout=None, rtsdtr_on_open=PinState.HIGH, rtsdtr_on_close=PinState.LOW, exclusive=True, port=None, timeout=None, bytesize=None, do_not_open=None, writeTimeout=None, inter_byte_timeout=None, _wrap_exceptions=False)

    Initialize serial port configuration.

    Parameters:

      - path (str | Path | None)

      - baudrate (int)

      - parity (Parity | str | None)

      - stopbits (StopBits | int | float)

      - xonxoff (bool)

      - rtscts (bool)

      - dsrdtr (bool)

      - byte_size (int)

      - read_timeout (float | None)

      - write_timeout (float | None)

      - rtsdtr_on_open (PinState)

      - rtsdtr_on_close (PinState)

      - exclusive (bool)

      - port (str | None)

      - timeout (float | None)

      - bytesize (int | None)

      - do_not_open (bool | None)

      - writeTimeout (float | None)

      - inter_byte_timeout (int | None)

      - _wrap_exceptions (bool)

    Return type:

      None

  classmethod from_url(url, *args, **kwargs)

    Create the appropriate serial port subclass for the given URL.

    Parameters:

      - url (str)

      - args (Any)

      - kwargs (Any)

    Return type:

      BaseSerial

  open()

    Open the serial port.

    Return type:

      None

  configure_port()

    Configure the serial port settings.

    Return type:

      None

  close()

    Close the serial port.

    Return type:

      None

  property read_timeout: float | None

    Get the read timeout in seconds.

  property write_timeout: float | None

    Get the write timeout in seconds.

  get_modem_pins()

    Get modem control bits.

    Return type:

      ModemPins

  set_modem_pins(modem_pins=None, *, le=PinState.UNDEFINED, dtr=PinState.UNDEFINED, rts=PinState.UNDEFINED, st=PinState.UNDEFINED, sr=PinState.UNDEFINED, cts=PinState.UNDEFINED, car=PinState.UNDEFINED, rng=PinState.UNDEFINED, dsr=PinState.UNDEFINED)

    Set modem control bits.

    Parameters:

      - modem_pins (ModemPins | None)

      - le (PinState | bool | None)

      - dtr (PinState | bool | None)

      - rts (PinState | bool | None)

      - st (PinState | bool | None)

      - sr (PinState | bool | None)

      - cts (PinState | bool | None)

      - car (PinState | bool | None)

      - rng (PinState | bool | None)

      - dsr (PinState | bool | None)

    Return type:

      None

  readinto(b, *, timeout=None)

    Read bytes from serial port into buffer.

    Parameters:

      - b (Buffer)

      - timeout (float | None)

    Return type:

      int

  write(data, *, timeout=None)

    Write bytes to serial port.

    Parameters:

      - data (Buffer)

      - timeout (float | None)

    Return type:

      int

  flush()

    Flush write buffers.

    Return type:

      None

  property path: str | Path | None

    Get the serial port path.

  property baudrate: int

    Get the baud rate.

  property parity: Parity

    Get the parity.

  property byte_size: int

    Get the byte size.

  property stopbits: StopBits

    Get the number of stop bits.

  property rtsdtr_on_open: PinState

    Get the RTS/DTR pin state (on open) setting.

  property rtsdtr_on_close: PinState

    Get the RTS/DTR pin state (on close) setting.

  property exclusive: bool

    Get the exclusive setting.

  readexactly(n, *, timeout=None)

    Read exactly n bytes.

    Parameters:

      - n (int)

      - timeout (float | None)

    Return type:

      bytes

  read_until(expected=b'\n', size=None, *, timeout=None)

    Read until the expected sequence is found.

    Parameters:

      - expected (bytes)

      - size (int | None)

      - timeout (float | None)

    Return type:

      bytes

  abstractmethod num_unread_bytes()

    Return the number of bytes waiting to be read.

    Return type:

      int

  abstractmethod num_unwritten_bytes()

    Return the number of bytes waiting to be written.

    Return type:

      int

  reset_read_buffer()

    Reset the read buffer.

    Return type:

      None

  reset_write_buffer()

    Reset the write buffer.

    Return type:

      None

  abstract property is_open: bool

    Return whether the serial port is open.

  property port: str | None

    Deprecated alias for path.

    Warning

    Deprecated, use path instead.

  property portstr: str | None

    Deprecated alias for path.

    Warning

    Deprecated, use path instead.

  property timeout: float | None

    Deprecated alias for read_timeout.

    Warning

    Deprecated, use read_timeout instead.

  property bytesize: int

    Deprecated alias for byte_size.

    Warning

    Deprecated, use byte_size instead.

  property data_bits: int

    Deprecated alias for byte_size.

    Warning

    Deprecated, use byte_size instead.

  property stop_bits: int | float

    Deprecated alias for stopbits.

    Warning

    Deprecated, use stopbits instead.

  property writeTimeout: float | None

    Deprecated alias for write_timeout.

    Warning

    Deprecated, use write_timeout instead.

  reset_input_buffer()

    Reset the read buffer.

    Warning

    Deprecated, use reset_read_buffer instead.

    Return type:

      None

  reset_output_buffer()

    Reset the write buffer.

    Warning

    Deprecated, use reset_write_buffer instead.

    Return type:

      None

  flushInput()

    Reset the read buffer.

    Warning

    Deprecated, use reset_read_buffer instead.

    Return type:

      None

  flushOutput()

    Reset the write buffer.

    Warning

    Deprecated, use reset_write_buffer instead.

    Return type:

      None

  property in_waiting: int

    Deprecated alias for num_unread_bytes.

    Warning

    Deprecated, use num_unread_bytes instead.

  property out_waiting: int

    Deprecated alias for num_unwritten_bytes.

    Warning

    Deprecated, use num_unwritten_bytes instead.

  property inWaiting: int

    Deprecated alias for num_unread_bytes.

    Warning

    Deprecated, use num_unread_bytes instead.

  isOpen()

    Return whether the serial port is open.

    Warning

    Deprecated, use is_open instead.

    Return type:

      bool

  property dtr: bool | None

    Get DTR modem bit.

  property rts: bool | None

    Get RTS modem bit.

  property cts: bool | None

    Get CTS modem bit.

class serialx.BaseSerialTransport

  Bases: `Transport`

  Base class for serial port asyncio transport.

  __init__(loop, protocol)

    Initialize serial transport.

    Parameters:

      - loop (AbstractEventLoop)

      - protocol (Protocol)

    Return type:

      None

  is_closing()

    Return whether the transport is closing.

    Return type:

      bool

  get_protocol()

    Get the protocol used by this transport.

    Return type:

      Protocol

  set_protocol(protocol)

    Set the protocol to use with this transport.

    Parameters:

      protocol (Protocol)

    Return type:

      None

  property serial: BaseSerial

    Get the serial port instance.

  property baudrate: int

    Get the baud rate.

  property parity: Parity

    Get the parity.

  property stopbits: StopBits

    Get the number of stop bits.

  property byte_size: int

    Get the byte size.

  property exclusive: bool

    Get the exclusive setting.

  async connect(*, path, **kwargs)

    Connect to serial port.

    Parameters:

      - path (str | None)

      - kwargs (Unpack[ConnectKwargs])

    Return type:

      None

  async get_modem_pins()

    Get modem control bits.

    Return type:

      ModemPins

  async set_modem_pins(modem_pins=None, *, le=PinState.UNDEFINED, dtr=PinState.UNDEFINED, rts=PinState.UNDEFINED, st=PinState.UNDEFINED, sr=PinState.UNDEFINED, cts=PinState.UNDEFINED, car=PinState.UNDEFINED, rng=PinState.UNDEFINED, dsr=PinState.UNDEFINED)

    Set modem control bits.

    Parameters:

      - modem_pins (ModemPins | None)

      - le (PinState | bool | None)

      - dtr (PinState | bool | None)

      - rts (PinState | bool | None)

      - st (PinState | bool | None)

      - sr (PinState | bool | None)

      - cts (PinState | bool | None)

      - car (PinState | bool | None)

      - rng (PinState | bool | None)

      - dsr (PinState | bool | None)

    Return type:

      None

  async flush()

    Flush write buffers, waiting until all data is written.

    Return type:

      None

  async wait_closed()

    Wait until transport is fully closed.

    Return type:

      None

serialx.Serial

  alias of `LinuxSerial`

exception serialx.SerialException

  Bases: `Exception`

  Base serial exception.

exception serialx.UnsupportedSetting

  Bases: `SerialException`

  Raised when an unsupported serial port setting is used.

class serialx.SerialPortInfo

  Bases: `object`

  A serial port.

  __init__(device, resolved_device, vid, pid, serial_number, manufacturer, product, bcd_device, interface_description, interface_num)
    Parameters:

      - device (str)

      - resolved_device (str)

      - vid (int | None)

      - pid (int | None)

      - serial_number (str | None)

      - manufacturer (str | None)

      - product (str | None)

      - bcd_device (int | None)

      - interface_description (str | None)

      - interface_num (int | None)

    Return type:

      None

  property description: str

    Description of the device.

    Warning

    Deprecated, this description is unstable and will change in the future.

class serialx.SerialStreamWriter

  Bases: `StreamWriter`, `Generic`[`_T`]

  StreamWriter with properly typed transport.

  property transport: _T

    Return the underlying transport.

serialx.SerialTransport

  alias of `LinuxSerialTransport`

class serialx.StopBits

  Bases: `float`, `Enum`

  Stop bits configuration.

  __new__(value)

serialx.SerialTimeoutException

  alias of `TimeoutError`

## Core modules

### `serialx.common`

Serial port communication utilities.

class serialx.common.Platform

  Bases: `str`, `Enum`

  Built-in platform name.

  __new__(value)

class serialx.common.RegisteredUriHandler

  Bases: `object`

  A URI handler registration entry.

  __init__(scheme, unique_scheme, weight, sync_cls, async_transport_cls, list_serial_ports_func, async_list_serial_ports_func, strip_uri_scheme)
    Parameters:

      - scheme (str)

      - unique_scheme (str)

      - weight (int)

      - sync_cls (type[BaseSerial])

      - async_transport_cls (type[BaseSerialTransport])

      - list_serial_ports_func (Callable[[...], list[SerialPortInfo]])

      - async_list_serial_ports_func (Callable[[...], Awaitable[list[SerialPortInfo]]])

      - strip_uri_scheme (bool)

    Return type:

      None

serialx.common.empty_port_list(*args, **kwargs)

  Return an empty list of serial ports.

  Parameters:

    - args (Any)

    - kwargs (Any)

  Return type:

    list[SerialPortInfo]

async serialx.common.async_empty_port_list(*args, **kwargs)

  Return an empty list of serial ports, async.

  Parameters:

    - args (Any)

    - kwargs (Any)

  Return type:

    list[SerialPortInfo]

serialx.common.register_uri_handler(*, scheme, unique_scheme, sync_cls, async_transport_cls, list_serial_ports_func=<function empty_port_list>, async_list_serial_ports_func=<function async_empty_port_list>, weight=1, strip_uri_scheme=False)

  Register a URI handler.

  Expose a new backend to `serial_for_url` / `create_serial_connection` / `open_serial_connection`.

  Parameters:

    - scheme (str) – Shared dispatch scheme. URLs with this scheme resolve to the highest-weight handler registered under it.

    - unique_scheme (str) – A scheme that uniquely identifies this handler. Must end with `://` and must not collide with an existing registration. Use this to address the handler directly.

    - sync_cls (type[BaseSerial]) – Synchronous serial class, typically a subclass of `BaseSerial`.

    - async_transport_cls (type[BaseSerialTransport]) – Async transport class, typically a subclass of `BaseSerialTransport`.

    - list_serial_ports_func (Callable[[...], list[SerialPortInfo]]) – Callable returning a list of `SerialPortInfo`.

    - async_list_serial_ports_func (Callable[[...], Awaitable[list[SerialPortInfo]]]) – Async callable returning a list of `SerialPortInfo`.

    - weight (int) – Dispatch priority under `scheme`. Higher wins.

    - strip_uri_scheme (bool) – If `True`, the leading `scheme` / `unique_scheme` is removed before the URL is passed to the sync class. Set this when the underlying class expects a bare device path rather than a URL.

  Returns:

    A callable that unregisters the handler.

  Raises:

    ValueError – if either scheme doesn’t end with `://` or `unique_scheme` is already registered.

  Return type:

    Callable[[], None]

serialx.common.get_uri_handler(uri)

  Look up the registered handler for the given URI.

  Parameters:

    uri (str)

  Return type:

    RegisteredUriHandler

exception serialx.common.SerialException

  Bases: `Exception`

  Base serial exception.

exception serialx.common.UnsupportedSetting

  Bases: `SerialException`

  Raised when an unsupported serial port setting is used.

exception serialx.common.UnknownUriScheme

  Bases: `SerialException`

  Raised when a URI scheme has no registered handler.

class serialx.common.StopBits

  Bases: `float`, `Enum`

  Stop bits configuration.

  __new__(value)

class serialx.common.Parity

  Bases: `str`, `Enum`

  Parity configuration.

  __new__(value)

class serialx.common.ConnectKwargs

  Bases: `TypedDict`

  Kwargs forwarded to BaseSerialTransport.connect / _connect.

class serialx.common.PinState

  Bases: `Enum`

  Pin state.

  classmethod convert(value)

    Create PinState from boolean.

    Parameters:

      value (PinState | bool | None)

    Return type:

      PinState

  to_bool()

    Convert PinState to boolean.

    Return type:

      bool | None

class serialx.common.ModemPins

  Bases: `object`

  Modem control bits.

  __init__(le=PinState.UNDEFINED, dtr=PinState.UNDEFINED, rts=PinState.UNDEFINED, st=PinState.UNDEFINED, sr=PinState.UNDEFINED, cts=PinState.UNDEFINED, car=PinState.UNDEFINED, rng=PinState.UNDEFINED, dsr=PinState.UNDEFINED)
    Parameters:

      - le (PinState)

      - dtr (PinState)

      - rts (PinState)

      - st (PinState)

      - sr (PinState)

      - cts (PinState)

      - car (PinState)

      - rng (PinState)

      - dsr (PinState)

    Return type:

      None

serialx.common.measure_time()

  Measure elapsed time in a context.

  Return type:

    Iterator[Callable[[], float]]

serialx.common.maybe_wrap_exceptions(func)

  Re-raise all exceptions as SerialException when the flag is set.

  Parameters:

    func (Callable[[Concatenate[BaseSerial, ~_P]], _R])

  Return type:

    Callable[[Concatenate[BaseSerial, ~_P]], _R]

class serialx.common.BaseSerial

  Bases: `RawIOBase`

  Base class for serial port communication.

  __init__(path=None, baudrate=9600, *, parity=Parity.NONE, stopbits=StopBits.ONE, xonxoff=False, rtscts=False, dsrdtr=False, byte_size=8, read_timeout=None, write_timeout=None, rtsdtr_on_open=PinState.HIGH, rtsdtr_on_close=PinState.LOW, exclusive=True, port=None, timeout=None, bytesize=None, do_not_open=None, writeTimeout=None, inter_byte_timeout=None, _wrap_exceptions=False)

    Initialize serial port configuration.

    Parameters:

      - path (str | Path | None)

      - baudrate (int)

      - parity (Parity | str | None)

      - stopbits (StopBits | int | float)

      - xonxoff (bool)

      - rtscts (bool)

      - dsrdtr (bool)

      - byte_size (int)

      - read_timeout (float | None)

      - write_timeout (float | None)

      - rtsdtr_on_open (PinState)

      - rtsdtr_on_close (PinState)

      - exclusive (bool)

      - port (str | None)

      - timeout (float | None)

      - bytesize (int | None)

      - do_not_open (bool | None)

      - writeTimeout (float | None)

      - inter_byte_timeout (int | None)

      - _wrap_exceptions (bool)

    Return type:

      None

  classmethod from_url(url, *args, **kwargs)

    Create the appropriate serial port subclass for the given URL.

    Parameters:

      - url (str)

      - args (Any)

      - kwargs (Any)

    Return type:

      BaseSerial

  open()

    Open the serial port.

    Return type:

      None

  configure_port()

    Configure the serial port settings.

    Return type:

      None

  close()

    Close the serial port.

    Return type:

      None

  property read_timeout: float | None

    Get the read timeout in seconds.

  property write_timeout: float | None

    Get the write timeout in seconds.

  get_modem_pins()

    Get modem control bits.

    Return type:

      ModemPins

  set_modem_pins(modem_pins=None, *, le=PinState.UNDEFINED, dtr=PinState.UNDEFINED, rts=PinState.UNDEFINED, st=PinState.UNDEFINED, sr=PinState.UNDEFINED, cts=PinState.UNDEFINED, car=PinState.UNDEFINED, rng=PinState.UNDEFINED, dsr=PinState.UNDEFINED)

    Set modem control bits.

    Parameters:

      - modem_pins (ModemPins | None)

      - le (PinState | bool | None)

      - dtr (PinState | bool | None)

      - rts (PinState | bool | None)

      - st (PinState | bool | None)

      - sr (PinState | bool | None)

      - cts (PinState | bool | None)

      - car (PinState | bool | None)

      - rng (PinState | bool | None)

      - dsr (PinState | bool | None)

    Return type:

      None

  readinto(b, *, timeout=None)

    Read bytes from serial port into buffer.

    Parameters:

      - b (Buffer)

      - timeout (float | None)

    Return type:

      int

  write(data, *, timeout=None)

    Write bytes to serial port.

    Parameters:

      - data (Buffer)

      - timeout (float | None)

    Return type:

      int

  flush()

    Flush write buffers.

    Return type:

      None

  property path: str | Path | None

    Get the serial port path.

  property baudrate: int

    Get the baud rate.

  property parity: Parity

    Get the parity.

  property byte_size: int

    Get the byte size.

  property stopbits: StopBits

    Get the number of stop bits.

  property rtsdtr_on_open: PinState

    Get the RTS/DTR pin state (on open) setting.

  property rtsdtr_on_close: PinState

    Get the RTS/DTR pin state (on close) setting.

  property exclusive: bool

    Get the exclusive setting.

  readexactly(n, *, timeout=None)

    Read exactly n bytes.

    Parameters:

      - n (int)

      - timeout (float | None)

    Return type:

      bytes

  read_until(expected=b'\n', size=None, *, timeout=None)

    Read until the expected sequence is found.

    Parameters:

      - expected (bytes)

      - size (int | None)

      - timeout (float | None)

    Return type:

      bytes

  abstractmethod num_unread_bytes()

    Return the number of bytes waiting to be read.

    Return type:

      int

  abstractmethod num_unwritten_bytes()

    Return the number of bytes waiting to be written.

    Return type:

      int

  reset_read_buffer()

    Reset the read buffer.

    Return type:

      None

  reset_write_buffer()

    Reset the write buffer.

    Return type:

      None

  abstract property is_open: bool

    Return whether the serial port is open.

  property port: str | None

    Deprecated alias for path.

    Warning

    Deprecated, use path instead.

  property portstr: str | None

    Deprecated alias for path.

    Warning

    Deprecated, use path instead.

  property timeout: float | None

    Deprecated alias for read_timeout.

    Warning

    Deprecated, use read_timeout instead.

  property bytesize: int

    Deprecated alias for byte_size.

    Warning

    Deprecated, use byte_size instead.

  property data_bits: int

    Deprecated alias for byte_size.

    Warning

    Deprecated, use byte_size instead.

  property stop_bits: int | float

    Deprecated alias for stopbits.

    Warning

    Deprecated, use stopbits instead.

  property writeTimeout: float | None

    Deprecated alias for write_timeout.

    Warning

    Deprecated, use write_timeout instead.

  reset_input_buffer()

    Reset the read buffer.

    Warning

    Deprecated, use reset_read_buffer instead.

    Return type:

      None

  reset_output_buffer()

    Reset the write buffer.

    Warning

    Deprecated, use reset_write_buffer instead.

    Return type:

      None

  flushInput()

    Reset the read buffer.

    Warning

    Deprecated, use reset_read_buffer instead.

    Return type:

      None

  flushOutput()

    Reset the write buffer.

    Warning

    Deprecated, use reset_write_buffer instead.

    Return type:

      None

  property in_waiting: int

    Deprecated alias for num_unread_bytes.

    Warning

    Deprecated, use num_unread_bytes instead.

  property out_waiting: int

    Deprecated alias for num_unwritten_bytes.

    Warning

    Deprecated, use num_unwritten_bytes instead.

  property inWaiting: int

    Deprecated alias for num_unread_bytes.

    Warning

    Deprecated, use num_unread_bytes instead.

  isOpen()

    Return whether the serial port is open.

    Warning

    Deprecated, use is_open instead.

    Return type:

      bool

  property dtr: bool | None

    Get DTR modem bit.

  property rts: bool | None

    Get RTS modem bit.

  property cts: bool | None

    Get CTS modem bit.

class serialx.common.BaseSerialTransport

  Bases: `Transport`

  Base class for serial port asyncio transport.

  __init__(loop, protocol)

    Initialize serial transport.

    Parameters:

      - loop (AbstractEventLoop)

      - protocol (Protocol)

    Return type:

      None

  is_closing()

    Return whether the transport is closing.

    Return type:

      bool

  get_protocol()

    Get the protocol used by this transport.

    Return type:

      Protocol

  set_protocol(protocol)

    Set the protocol to use with this transport.

    Parameters:

      protocol (Protocol)

    Return type:

      None

  property serial: BaseSerial

    Get the serial port instance.

  property baudrate: int

    Get the baud rate.

  property parity: Parity

    Get the parity.

  property stopbits: StopBits

    Get the number of stop bits.

  property byte_size: int

    Get the byte size.

  property exclusive: bool

    Get the exclusive setting.

  async connect(*, path, **kwargs)

    Connect to serial port.

    Parameters:

      - path (str | None)

      - kwargs (Unpack[ConnectKwargs])

    Return type:

      None

  async get_modem_pins()

    Get modem control bits.

    Return type:

      ModemPins

  async set_modem_pins(modem_pins=None, *, le=PinState.UNDEFINED, dtr=PinState.UNDEFINED, rts=PinState.UNDEFINED, st=PinState.UNDEFINED, sr=PinState.UNDEFINED, cts=PinState.UNDEFINED, car=PinState.UNDEFINED, rng=PinState.UNDEFINED, dsr=PinState.UNDEFINED)

    Set modem control bits.

    Parameters:

      - modem_pins (ModemPins | None)

      - le (PinState | bool | None)

      - dtr (PinState | bool | None)

      - rts (PinState | bool | None)

      - st (PinState | bool | None)

      - sr (PinState | bool | None)

      - cts (PinState | bool | None)

      - car (PinState | bool | None)

      - rng (PinState | bool | None)

      - dsr (PinState | bool | None)

    Return type:

      None

  async flush()

    Flush write buffers, waiting until all data is written.

    Return type:

      None

  async wait_closed()

    Wait until transport is fully closed.

    Return type:

      None

serialx.common.get_serial_classes(url)

  Get the appropriate serial and transport classes based on the URL scheme.

  Parameters:

    url (str)

  Return type:

    tuple[type[BaseSerial], type[BaseSerialTransport]]

class serialx.common.SerialPortInfo

  Bases: `object`

  A serial port.

  __init__(device, resolved_device, vid, pid, serial_number, manufacturer, product, bcd_device, interface_description, interface_num)
    Parameters:

      - device (str)

      - resolved_device (str)

      - vid (int | None)

      - pid (int | None)

      - serial_number (str | None)

      - manufacturer (str | None)

      - product (str | None)

      - bcd_device (int | None)

      - interface_description (str | None)

      - interface_num (int | None)

    Return type:

      None

  property description: str

    Description of the device.

    Warning

    Deprecated, this description is unstable and will change in the future.

serialx.common.list_serial_ports(platform=Platform.DEVICE, **kwargs)

  List serial ports, defaulting to the system platform.

  Parameters:

    - platform (Platform | str)

    - kwargs (Any)

  Return type:

    list[SerialPortInfo]

async serialx.common.async_list_serial_ports(platform=Platform.DEVICE, **kwargs)

  List serial ports (async), defaulting to the system platform.

  Parameters:

    - platform (Platform | str)

    - kwargs (Any)

  Return type:

    list[SerialPortInfo]

serialx.common.serial_for_url(url, *args, **kwargs)

  Create the appropriate serial port subclass for the given URL.

  Parameters:

    - url (str)

    - args (Any)

    - kwargs (Any)

  Return type:

    BaseSerial

### `serialx.serialutil`

serialx pyserial compatibility module.

exception serialx.serialutil.SerialException

  Bases: `Exception`

  Base serial exception.

### `serialx.async_serial`

Asynchronous serial port support.

class serialx.async_serial.SerialStreamWriter

  Bases: `StreamWriter`, `Generic`[`_T`]

  StreamWriter with properly typed transport.

  property transport: _T

    Return the underlying transport.

class serialx.async_serial.AsyncSerial

  Bases: `object`

  Async serial port with a sync-style API.

  __init__(url, *, transport_cls=None, **kwargs)

    Initialize an unopened serial port.

    Directly creating this class is not recommended; use async_serial_for_url instead.

    Parameters:

      - url (str | None)

      - transport_cls (type[BaseSerialTransport] | None)

      - kwargs (Any)

    Return type:

      None

  async open()

    Open the serial port connection.

    Return type:

      None

  async close()

    Close the connection and wait until the port is fully closed.

    Return type:

      None

  schedule_close()

    Signal a graceful close without waiting for it to finish.

    Return type:

      None

  abort()

    Drop pending writes and close immediately, without waiting.

    Return type:

      None

  async wait_closed()

    Wait until a previously-scheduled close or abort has finished.

    Return type:

      None

  property is_open: bool

    Whether the connection is currently open.

  async read(n=-1)

    Read up to n bytes (or until EOF if n is -1).

    Parameters:

      n (int)

    Return type:

      bytes

  async readexactly(n)

    Read exactly n bytes.

    Parameters:

      n (int)

    Return type:

      bytes

  async readuntil(separator=b'\n')

    Read up to and including separator.

    Parameters:

      separator (bytes)

    Return type:

      bytes

  async readline()

    Read until the next newline.

    Return type:

      bytes

  async write(data)

    Queue data for writing and wait for the application buffer to drain.

    Parameters:

      data (bytes | bytearray | memoryview)

    Return type:

      None

  async writelines(data)

    Queue buffers for writing and wait for the application buffer to drain.

    Parameters:

      data (Iterable[bytes | bytearray | memoryview])

    Return type:

      None

  write_nowait(data)

    Queue data for writing without waiting; pair with drain() to batch.

    Parameters:

      data (bytes | bytearray | memoryview)

    Return type:

      None

  writelines_nowait(data)

    Queue buffers for writing without waiting; pair with drain() to batch.

    Parameters:

      data (Iterable[bytes | bytearray | memoryview])

    Return type:

      None

  async drain()

    Wait until the application-level write buffer can accept more data.

    Return type:

      None

  async flush()

    Drain app-level buffer, then wait for the OS-level buffer to flush.

    Return type:

      None

  property transport: BaseSerialTransport

    Return the underlying serial transport.

  async get_modem_pins()

    Get modem control pins.

    Return type:

      ModemPins

  async set_modem_pins(modem_pins=None, *, le=PinState.UNDEFINED, dtr=PinState.UNDEFINED, rts=PinState.UNDEFINED, st=PinState.UNDEFINED, sr=PinState.UNDEFINED, cts=PinState.UNDEFINED, car=PinState.UNDEFINED, rng=PinState.UNDEFINED, dsr=PinState.UNDEFINED)

    Set modem control pins.

    Parameters:

      - modem_pins (ModemPins | None)

      - le (PinState | bool | None)

      - dtr (PinState | bool | None)

      - rts (PinState | bool | None)

      - st (PinState | bool | None)

      - sr (PinState | bool | None)

      - cts (PinState | bool | None)

      - car (PinState | bool | None)

      - rng (PinState | bool | None)

      - dsr (PinState | bool | None)

    Return type:

      None

  property baudrate: int

    Get the baud rate.

  property parity: Parity

    Get the parity.

  property stopbits: StopBits

    Get the number of stop bits.

  property byte_size: int

    Get the byte size.

  property exclusive: bool

    Get the exclusive setting.

async serialx.async_serial.create_serial_connection(loop, protocol_factory, url, baudrate, parity=Parity.NONE, stopbits=StopBits.ONE, xonxoff=False, rtscts=False, exclusive=True, *, transport_cls=None, **kwargs)

  Create a serial port connection with asyncio.

  Parameters:

    - loop (AbstractEventLoop)

    - protocol_factory (Callable[[], Protocol])

    - url (str | None)

    - baudrate (int)

    - parity (Parity)

    - stopbits (StopBits)

    - xonxoff (bool)

    - rtscts (bool)

    - exclusive (bool)

    - transport_cls (type[BaseSerialTransport] | None)

    - kwargs (Any)

  Return type:

    tuple[BaseSerialTransport, Protocol]

async serialx.async_serial.open_serial_connection(*args, **kwargs)

  Open a serial port connection using StreamReader and StreamWriter.

  Parameters:

    - args (Any)

    - kwargs (Any)

  Return type:

    tuple[StreamReader, SerialStreamWriter[BaseSerialTransport]]

serialx.async_serial.async_serial_for_url(url, *, transport_cls=None, **kwargs)

  Build an unopened AsyncSerial. Use async with or await serial.open().

  Parameters:

    - url (str | None)

    - transport_cls (type[BaseSerialTransport] | None)

    - kwargs (Any)

  Return type:

    AsyncSerial