docs/library: Document the network.PPP class.

Signed-off-by: Damien George <damien@micropython.org>

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.

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
 =================