micropython
diff --git a/‎docs/library/espnow.rst
Lines changed: 57 additions & 49 deletions b/‎docs/library/espnow.rst
Lines changed: 57 additions & 49 deletions
@@ -20,7 +20,7 @@ Load this module from the :doc:`esp` module. A simple example would be:
 
         e = espnow.ESPNow()
         e.init()
-        peer = b'0\xae\xa4XC\xd0'   # MAC address of peer's wifi interface
+        peer = b'\xbb\xbb\xbb\xbb\xbb\xbb'   # MAC address of peer's wifi interface
         e.add_peer(peer)
 
         e.send("Starting...")       # Send to all peers
@@ -39,7 +39,7 @@ Load this module from the :doc:`esp` module. A simple example would be:
 
         e = espnow.ESPNow()
         e.init()
-        peer = b'0\xae\xa4XC\xa0'   # MAC address of peer's wifi interface
+        peer = b'\xaa\xaa\xaa\xaa\xaa\xaa'   # MAC address of peer's wifi interface
         e.add_peer(peer)
 
         print(e.irecv())
@@ -70,14 +70,14 @@ Configuration
     protocol, including:
 
     - initialise the ESPNow data structures,
-    - allocate the send and recv data buffers,
+    - allocate the recv data buffer,
     - invoke esp_now_init() and
     - register the send and recv callbacks.
 
 .. method:: ESPNow.deinit()
 
-    De-initialise the Espressif ESPNow software stack (esp_now_deinit()), disable
-    the interrupt callbacks and deallocate the send and recv data buffers.
+    De-initialise the Espressif ESPNow software stack (esp_now_deinit()),
+    disable callbacks and deallocate the recv data buffer.
 
     **Note**: `deinit()` will also deregister all peers which must be
     re-registered after `init()`.
@@ -89,24 +89,18 @@ Configuration
     Get or set configuration values of the ESPNow interface.  To get a value the
     parameter name should be quoted as a string, and just one parameter is
     queried at a time.  To set values use the keyword syntax, and one or more
-    parameters can be set at a time. Invocation with no arguments will return a
-    dict of all parameter names and values.
+    parameters can be set at a time.
 
     Currently supported values are:
 
-    - ``txbuf``: *(default=140)* Get/set the size in bytes of the internal
-      buffer used to store send response data. Increasing this allows better
-      handling of bursty outgoing/incoming data.
-
-    - ``rxbuf``: *(default=514)* Get/set the size in bytes of the internal
+    - ``rxbuf``: *(default=516)* Get/set the size in bytes of the internal
       buffer used to store incoming ESPNow packet data. The default size is
-      selected to fit two
-      max-sized ESPNow packets (250 bytes) with associated mac_address (6 bytes)
-      and a message byte count (1 byte) plus buffer overhead. Increase this if
-      you expect to receive a lot of large packets or expect bursty incoming
-      traffic.
+      selected to fit two max-sized ESPNow packets (250 bytes) with associated
+      mac_address (6 bytes) and a message byte count (1 byte) plus buffer
+      overhead. Increase this if you expect to receive a lot of large packets
+      or expect bursty incoming traffic.
 
-      **Note:** The send and recv buffers are only allocated by `ESPNow.init()`.
+      **Note:** The recv buffer is only allocated by `ESPNow.init()`.
       Changing these values will have no effect until the next call of
       `ESPNow.init()`.
 
@@ -115,7 +109,7 @@ Configuration
 
 .. method:: ESPNow.clear(True)
 
-    Clear out any data in the recv (and send-response) buffers. Use this to clean
+    Clear out any data in the recv buffer. Use this to clean
     up after receiving a ``Buffer error`` (should not happen). All data in the
     buffers will be discarded. An arg of `True` is required to guard against
     inadvertent use.
@@ -131,34 +125,43 @@ Sending and Receiving Data
 --------------------------
 
 A wifi interface (``network.STA_IF`` or ``network.AP_IF``) must be
-`active()<network.WLAN.active>`
-before messages can be sent or received, but it is not necessary to connect or
-configure the WLAN interface. For example::
+`active()<network.WLAN.active>` before messages can be sent or received,
+but it is not necessary to connect or configure the WLAN interface.
+For example::
 
     import network
 
     w0 = network.WLAN(network.STA_IF)
     w0.active(True)
 
-.. method:: ESPNow.send(mac, msg, [sync])
+.. method:: ESPNow.send(mac, msg, [sync=True])
+            ESPNow.send(msg)
 
     Send the data contained in ``msg`` to the peer with given network ``mac``
-    address. ``mac`
629A
` must be a byte string exactly 6 bytes long and ``msg`` must
-    be a string or byte-string such that ``0<len(msg)<=espnow.MAX_DATA_LEN``
-    (250) bytes. If ``mac`` is ``None`` the message will be sent to all
-    registered peers as an ESP-Now broadcast.
+    address. In the second form, ``mac=None`` and ``sync=True``.
+
+    Arguments:
 
-    - If ``sync=True`` send ``msg`` to the peer and wait for a response (or not).
-      Returns ``False`` if any peers fail to respond.
+    - ``mac``: byte string exactly 6 bytes long or ``None``
+    - ``msg``: string or byte-string such that
+      ``0<len(msg)<=espnow.MAX_DATA_LEN`` (250) bytes
+    - ``sync``:
 
-    - If ``sync=False`` handover ``msg`` to the esp_now software stack for
-      transmission and return immediately.
-      Responses from the peers will be discarded.
-      Always returns ``True``.
+      - ``True``: (default) send ``msg`` to the peer and wait for a response
+        (or not). Returns ``False`` if any peers fail to respond.
+
+      - ``False`` handover ``msg`` to the esp_now software stack for
+        transmission and return immediately.
+        Responses from the peers will be discarded.
+        Always returns ``True``.
+
+    If ``mac`` is ``None`` the message will be sent to all
+    registered peers as an ESP-Now broadcast.
 
     **Note**: A peer will respond with success if it's wifi interface is
-    active(), regardless of whether it has initialised it's ESP-Now system or
-    is actively listening for ESP-Now traffic (see the Espressif ESP-Now docs).
+    active() and set to the same channel as the sender, regardless of whether
+    it has initialised it's ESP-Now system or is actively listening for ESP-Now
+    traffic (see the Espressif ESP-Now docs).
 
 .. method:: ESPNow.recv([timeout])
 
@@ -169,30 +172,36 @@ configure the WLAN interface. For example::
 
     - ``msg`` is the message/data sent from the peer.
 
-    ``Timeout`` optionally sets a timeout (in milliseconds) for the read. The
+    ``timeout`` optionally sets a timeout (in milliseconds) for the read. The
     default timeout can be set in `ESPNow.config()`.
 
-    **Note**: repeatedly calling `irecv()<ESPNow.send()>` will exercise the
-    micropython garbage collection as new storage is allocated for each new<
F438
/div>
+    **Note**: repeatedly calling `recv()<ESPNow.recv()>` will exercise the
+    micropython memory allocation as new storage is allocated for each new
     message and tuple. Use `irecv()<ESPNow.irecv()>`
     for a more memory-efficient option.
 
 .. method:: ESPNow.irecv([timeout])
 
     As for `recv()<ESPNow.recv()>` except that ``irecv()`` will return a
-    "callee-owned" tuple.
-    That is, memory will be allocated for the tuple and byte strings on the
-    first call and re-used for subsequent calls. You must make copies if you
+    "callee-owned" tuple of bytearrays.
+    That is, memory will be allocated once for the tuple and byte strings on
+    invocation of espnow.ESPNow() and re-used for subsequent calls to
+    `irecv()<ESPNow.irecv()>`. You must make copies if you
     wish to keep the values across calls to ``irecv()``.
 
 .. method:: ESPNow.stats()
 
-    Return a 4-tuple containing the number of packets sent/received/lost:
-    ``(sent_packets, send_responses, recv_packets, lost_rx_packets)``. Packets
-    are *lost* when the recv buffers are full. To reduce packet loss,
-    increase the ``txbuf`` and ``rxbuf`` config parameters and ensure you are
+    Return a 5-tuple containing the number of packets sent/received/lost::
+
+    (sent_packets, sent_responses, sent_failures, recv_packets, lost_rx_packets)
+
+    Incoming packets are *dropped* when the recv buffers are full. To reduce
+    packet loss, increase the ``rxbuf`` config parameters and ensure you are
     in a tight loop calling `irecv()<ESPNow.irecv()>` as quickly as possible.
 
+    **Note**: Dropped packets will still be acknowledged to the sender as
+    received.
+
 Iteration over ESPNow
 ---------------------
 
@@ -209,8 +218,8 @@ for a message.
 Peer Management
 ---------------
 
-The ESP-Now protocol requires that other devices (peers) must be *registered*
-before we can `send()<ESPNow.send()>` them messages.
+The Esspresif ESP-Now software requires that other devices (peers) must be
+*registered* before we can `send()<ESPNow.send()>` them messages.
 
 .. method:: ESPNow.add_peer(mac, [lmk], [channel], [ifidx], [encrypt])
             ESPNow.add_peer(mac, 'param'=value, ...)
@@ -222,8 +231,7 @@ before we can `send()<ESPNow.send()>` them messages.
     - ``lmk``: The Local Master Key (LMK) key used to encrypt data transfers
       with this peer (if the *encrypt* parameter is set to *True*). Must be:
 
-      - a byte-string of length ``<= espnow.KEY_LEN`` (16 bytes) (the key will be
-        padded to the right with zeroes), or
+      - a byte-string of length ``espnow.KEY_LEN`` (16 bytes), or
       - any non-`True` python value (default= ``b''``), signifying an *empty* key
         which will disable encryption.