Commit 78ccb44a authored by Radomir Dopieralski's avatar Radomir Dopieralski Committed by Damien George
Browse files

docs: Document esp module for ESP8266.

I document as much as I could guess from experiments and reading the
code for the ``esp`` module for the ESP8266 port of Micropython.

For now the tag has to be set manually with -t option when building,
when we have properly split documentation, there will be a separate
config file for esp8266 with that the tag "port_esp8266" set.

To build use:

make SPHINXOPTS="-t port_esp8266" html
parent 278d22ce
:mod:`esp` --- functions related to the ESP8266
===============================================
.. module:: esp
:synopsis: functions related to the ESP8266
The ``esp`` module contains specific functions related to the ESP8266 module.
Functions
---------
.. function:: connect(ssid, password)
Connect to the specified wireless network, using the specified password.
.. function:: disconnect()
Disconnect from the currently connected wireless network.
.. function:: scan(cb)
Initiate scanning for the available wireless networks.
Once the scanning is complete, the provided callback function ``cb`` will
be called once for each network found, and passed a tuple with information
about that network.
.. function:: status()
Return the current status of the wireless connection.
The possible statuses are defined as constants:
* ``STAT_IDLE`` -- no connection and no activity,
* ``STAT_CONNECTING`` -- connecting in progress,
* ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password,
* ``STAT_NO_AP_FOUND`` -- failed because no access point replied,
* ``STAT_CONNECT_FAIL`` -- failed due to other problems,
* ``STAT_GOT_IP`` -- connection susccessful.
.. function:: getaddrinfo((hostname, port, lambda))
Initiate resolving of the given hostname.
When the hostname is resolved, the provided ``lambda`` callback will be
called with two arguments, first being the hostname being resolved,
second a tuple with information about that hostname.
Classes
-------
.. toctree::
:maxdepth: 1
esp.socket.rst
class socket -- network socket
==============================
``socket`` is an object that represents a network socket. Example usage::
socket = esp.socket()
socket.onrecv(print)
socket.connect(('207.58.139.247', 80))
socket.send('GET /testwifi/index.html HTTP/1.0\r\n\r\n')
Constructors
------------
.. class:: esp.socket()
Create and return a socket object.
TCP Methods
-----------
.. method:: socket.connect(addr)
Connect to the adress and port specified in the ``addr`` tuple.
.. method:: socket.close()
Close the connection.
.. method:: socket.accept()
Accept a single connection from the connection queue.
.. method:: socket.listen(backlog)
Start listening for incoming connections.
Note: Only one socket can be listening for connections at a time.
.. method:: socket.bind(addr)
Bind the socket to the address and port specified by the ``addr`` tuple.
.. method:: socket.send(buf)
Send the bytes from ``buf``.
.. method:: socket.recv()
Receive and return bytes from the socket.
UDP Methods
-----------
.. method:: socket.sendto(data, addr)
Placeholder for UDP support, not implemented yet.
.. method:: socket.recvfrom(addr)
Placeholder for UDP support, not implemented yet.
Callback Setter Methods
-----------------------
.. method:: onconnect(lambda)::
When connection is established, call the callback ``lambda``.
.. method:: onrecv(lambda)::
When data is received, call the callback ``lambda``.
.. method:: onsent(lamda)::
What data is finished sending, call the callback ``lambda``.
.. method:: ondisconnect(lambda)::
Call the callback ``lambda`` when the connection is closed.
......@@ -65,3 +65,15 @@ The following libraries are specific to the pyboard.
pyb.rst
network.rst
.. only:: port_esp8266
Libraries specific to the ESP8266
---------------------------------
The following libraries are specific to the ESP8266.
.. toctree::
:maxdepth: 2
esp.rst
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment