# pySerial-asyncio API

The following high-level functions are provided for initiating a serial connection:

async `serial_asyncio.``create_serial_connection`(loop, protocol_factory, *args, **kwargs)

  Open a streaming connection to the specified serial port.

  Parameters

    - loop – The asyncio event loop

    - protocol_factory – A callable which when invoked without arguments and which should return a `asyncio.Protocol` subclass. Most commonly the protocol class (e.g. `MyProtocol`) can be passed as this argument. If it is required to use an existing protocol instance, pass a zero-argument lambda which evaluates to the instance, such as `lambda: my_protocol`

    - args – Forwarded to the `serial.Serial` constructor

    - kwargs – Forwarded to the `serial.Serial` constructor

  Returns

    A coroutine for managing a serial port connection, which when awaited returns transport and protocol instances.

  Platform

    Posix

  Use this function to associate an asynchronous call-back based protocol with an new `serial.Serial` instance that will be created on your behalf.

  The chronological order of the operation is:

  1. `protocol_factory` is called without arguments and must return a `asyncio.Protocol` subclass instance.

  2. The protocol instance is tied to a `SerialTransport`.

  3. This coroutine returns successfully with a `(transport, protocol)` pair.

  4. The `connection_made()` method of the protocol will be called at some point by the event loop.

async `serial_asyncio.``connection_for_serial`(loop, protocol_factory, serial_instance)

  Open a streaming connection to an existing serial port instance.

  Parameters

    - loop – The asyncio event loop

    - protocol_factory – A callable which when invoked without arguments and which should return a `asyncio.Protocol` subclass. Most commonly the protocol class (e.g. `MyProtocol`) can be passed as this argument. If it is required to use an existing protocol instance, pass a zero-argument lambda which evaluates to the instance, such as `lambda: my_protocol`

    - serial_instance – A `serial.Serial` instance.

  Returns

    A coroutine for managing a serial port connection, which when awaited returns transport and protocol instances.

  Platform

    Posix

  Use this function to associate an asynchronous call-back based protocol with an existing `serial.Serial` instance.

  The chronological order of the operation is:

  1. `protocol_factory` is called without arguments and must return a `asyncio.Protocol` subclass instance.

  2. The protocol instance is tied to a `SerialTransport`.

  3. This coroutine returns successfully with a `(transport, protocol)` pair.

  4. The `connection_made()` method of the protocol will be called at some point by the event loop.

async `serial_asyncio.``open_serial_connection`(*, loop=None, limit=None, **kwargs)

  Open a streaming connection to an existing serial port instance.

  Parameters

    - loop – The asyncio event loop

    - limit – A optional buffer limit in bytes for the `asyncio.StreamReader`

    - kwargs – Forwarded to the `serial.Serial` constructor

  Returns

    A coroutine for managing a serial port connection, which when awaited returns an `asyncio.StreamReader` and a `asyncio.StreamWriter`.

  Platform

    Posix

  Use this function to open connections where serial traffic is handled by an asynchronous coroutine interacting with `asyncio.StreamReader` and a `asyncio.StreamWriter` objects.