From 35b6a66b0b0ea00ad6b4e83f2dcbeffc349f2b04 Mon Sep 17 00:00:00 2001
From: Damien George <damien@micropython.org>
Date: Wed, 28 Aug 2024 17:28:48 +1000
Subject: [PATCH] docs/library: Document the network.PPP class.

Signed-off-by: Damien George <damien@micropython.org>
---
 docs/library/network.PPP.rst | 98 ++++++++++++++++++++++++++++++++++++
 docs/library/network.rst     |  1 +
 2 files changed, 99 insertions(+)
 create mode 100644 docs/library/network.PPP.rst

diff --git a/docs/library/network.PPP.rst b/docs/library/network.PPP.rst
new file mode 100644
index 000000000000..85f580ce540e
--- /dev/null
+++ b/docs/library/network.PPP.rst
@@ -0,0 +1,98 @@
+.. currentmodule:: network
+.. _network.PPP:
+
+class PPP -- create network connections over serial PPP
+=======================================================
+
+This class allows you to create a network connection over a serial port using
+the PPP protocol.  It is only available on selected ports and boards.
+
+Example usage::
+
+    import network
+
+    ppp = network.PPP(uart)
+    ppp.connect()
+
+    while not ppp.isconnected():
+        pass
+
+    print(ppp.ipconfig("addr4"))
+
+    # use the socket module as usual, etc
+
+    ppp.disconnect()
+
+Constructors
+------------
+
+.. class:: PPP(stream)
+
+   Create a PPP driver object.
+
+   Arguments are:
+
+     - *stream* is any object that supports the stream protocol, but is most commonly a
+       :class:`machine.UART` instance.  This stream object must have an ``irq()`` method
+       and an ``IRQ_RXIDLE`` constant, for use by `PPP.connect`.
+
+Methods
+-------
+
+.. method:: PPP.connect(security=SEC_NONE, user=None, key=None)
+
+   Initiate a PPP connection with the given parameters:
+
+     - *security* is the type of security, either ``PPP.SEC_NONE``, ``PPP.SEC_PAP``,
+       or ``PPP.SEC_CHAP``.
+     - *user* is an optional user name to use with the security mode.
+     - *key* is an optional password to use with the security mode.
+
+   When this method is called the underlying stream has its interrupt configured to call
+   `PPP.poll` via ``stream.irq(ppp.poll, stream.IRQ_RXIDLE)``.  This makes sure the
+   stream is polled, and data passed up the PPP stack, wheverver data becomes available
+   on the stream.
+
+   The connection proceeds asynchronously, in the background.
+
+.. method:: PPP.disconnect()
+
+   Terminate the connection.  This must be called to cleanly close the PPP connection.
+
+.. method:: PPP.isconnected()
+
+   Returns ``True`` if the PPP link is connected and up.
+   Returns ``False`` otherwise.
+
+.. method:: PPP.status()
+
+   Returns the PPP status.
+
+.. method:: PPP.config(config_parameters)
+
+   Sets or gets parameters of the PPP interface. There are currently no parameter that
+   can be set or retrieved.
+
+.. method:: PPP.ipconfig('param')
+            PPP.ipconfig(param=value, ...)
+
+   See `AbstractNIC.ipconfig`.
+
+.. method:: PPP.ifconfig([(ip, subnet, gateway, dns)])
+
+   See `AbstractNIC.ifconfig`.
+
+.. method:: PPP.poll()
+
+   Poll the underlying stream for data, and pass it up the PPP stack.
+   This is called automatically if the stream is a UART with a RXIDLE interrupt,
+   so it's not usually necessary to call it manually.
+
+Constants
+---------
+
+.. data:: PPP.SEC_NONE
+          PPP.SEC_PAP
+          PPP.SEC_CHAP
+
+    The type of connection security.
diff --git a/docs/library/network.rst b/docs/library/network.rst
index 6a436fa85e05..d05d17132dc6 100644
--- a/docs/library/network.rst
+++ b/docs/library/network.rst
@@ -192,6 +192,7 @@ provide a way to control networking interfaces of various kinds.
    network.WLANWiPy.rst
    network.WIZNET5K.rst
    network.LAN.rst
+   network.PPP.rst
 
 Network functions
 =================