doc update: add note about asyncio

1 files changed, 48 insertions, 1 deletions

diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index 36293ad..85dd53a 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -1143,10 +1143,57 @@ Examples:
 - ``hwgrep://0451:f432`` (USB VID:PID)
 - ``spy://COM54?file=log.txt``
 
+
+asyncio
+=======
+
+.. warning:: This implementation is currently in an experimental state. Use
+    at your own risk.
+
+Experimental asyncio support is available for Python 3.4 and newer. The
+:mod:`serial.aio` provides a :class:`asyncio.Transport`:
+``SerialTransport``.
+
+
+A factory function (`asyncio.coroutine`) is provided:
+
+.. function:: create_serial_connection(loop, protocol_factory, \*args, \*\*kwargs)
+
+    :param loop: The event handler
+    :param protocol_factory: Factory function for a :class:`asyncio.Protocol`
+    :param args: Passed to the :class:`serial.Serial` init function
+    :param kwargs: Passed to the :class:`serial.Serial` init function
+    :platform: Posix
+
+    Get a connection making coroutine.
+
+Example::
+
+    class Output(asyncio.Protocol):
+        def connection_made(self, transport):
+            self.transport = transport
+            print('port opened', transport)
+            transport.serial.setRTS(0)
+            transport.write(b'hello world\n')
+
+        def data_received(self, data):
+            print('data received', repr(data))
+            self.transport.close()
+
+        def connection_lost(self, exc):
+            print('port closed')
+            asyncio.get_event_loop().stop()
+
+    loop = asyncio.get_event_loop()
+    coro = create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
+    loop.run_until_complete(coro)
+    loop.run_forever()
+    loop.close()
+
+
 Tools
 =====
 
-
 serial.tools.list_ports
 -----------------------
 .. module:: serial.tools.list_ports