diff --git a/docs/library/esp.rst b/docs/library/esp.rst new file mode 100644 index 0000000000..8dd39f536f --- /dev/null +++ b/docs/library/esp.rst @@ -0,0 +1,56 @@ +: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 diff --git a/docs/library/esp.socket.rst b/docs/library/esp.socket.rst new file mode 100644 index 0000000000..4f5234a154 --- /dev/null +++ b/docs/library/esp.socket.rst @@ -0,0 +1,82 @@ +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. diff --git a/docs/library/index.rst b/docs/library/index.rst index b5a7b3ca9c..9b77271814 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -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