more espnow changes

- improve docs
- use existing list methods
- change `recv` to `read`

Author: microdev1

ports/espressif/bindings/espnow/Communicate.c

@@ -36,17 +36,17 @@
 //|     """Provides methods and statistics related to communication
 //|     with the ESP-NOW peers.
 //|
-//|     Dictionary:
+//|     Terminology:
 //|         * "Send" = "Transmit" = ``TX``
-//|         * "Recv" = "Receive" = ``RX``
+//|         * "Read" = ``RX``
 //|     """
 //|
 //|     def __init__(self) -> None:
 //|         """You cannot create an instance of `Communicate`."""
 //|         ...
 
 //|     job: str
-//|     """Used to decide whether to call `__send` or `__recv`. (read-only)"""
+//|     """Used to decide whether to call `__send` or `__read`. (read-only)"""
 //|
 STATIC mp_obj_t espnow_com_get_job(const mp_obj_t self_in) {
     espnow_com_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -97,9 +97,11 @@ MP_PROPERTY_GETTER(espnow_com_failure_obj,
 //|         self,
 //|         message: ReadableBuffer,
 //|         peer: Peer,
-//|     ) -> bool:
+//|     ) -> None:
 //|         """Send a message to the peer's mac address.
 //|
+//|         This blocks until a timeout of ``2`` seconds if the ESP-NOW internal buffers are full.
+//|
 //|         :param ReadableBuffer message: The message to send (length <= 250 bytes).
 //|         :param Peer peer: Send message to this peer. If `None`, send to all registered peers.
 //|         """
@@ -131,18 +133,20 @@ STATIC mp_obj_t espnow_com___send(size_t n_args, const mp_obj_t *pos_args, mp_ma
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_KW(espnow_com___send_obj, 2, espnow_com___send);
 
-//|     def __recv(self) -> Optional[ESPNowPacket]:
-//|         """Receive a message from the peer(s).
+//|     def __read(self) -> Optional[ESPNowPacket]:
+//|         """Read a packet from the receive buffer.
+//|
+//|         This is non-blocking, the packet is received asynchronously from the peer(s).
 //|
 //|         :returns: An `ESPNowPacket` if available in the buffer, otherwise `None`."""
 //|         ...
-STATIC mp_obj_t espnow_com___recv(mp_obj_t self_in) {
+STATIC mp_obj_t espnow_com___read(mp_obj_t self_in) {
     espnow_obj_t *self = MP_OBJ_TO_PTR(self_in);
     common_hal_espnow_check_for_deinit(self);
 
-    return common_hal_espnow_recv(self);
+    return common_hal_espnow_read(self);
 }
-STATIC MP_DEFINE_CONST_FUN_OBJ_1(espnow_com___recv_obj, espnow_com___recv);
+STATIC MP_DEFINE_CONST_FUN_OBJ_1(espnow_com___read_obj, espnow_com___read);
 
 STATIC const mp_rom_map_elem_t espnow_com_locals_dict_table[] = {
     // Config parameters
@@ -153,14 +157,14 @@ STATIC const mp_rom_map_elem_t espnow_com_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_failure), MP_ROM_PTR(&espnow_com_failure_obj) },
 
     // Communication methods
-    { MP_ROM_QSTR(MP_QSTR___send), MP_ROM_PTR(&espnow_com___send_obj) },
-    { MP_ROM_QSTR(MP_QSTR___recv), MP_ROM_PTR(&espnow_com___recv_obj) },
+    { MP_ROM_QSTR(MP_QSTR___send),  MP_ROM_PTR(&espnow_com___send_obj) },
+    { MP_ROM_QSTR(MP_QSTR___read),  MP_ROM_PTR(&espnow_com___read_obj) },
 };
 STATIC MP_DEFINE_CONST_DICT(espnow_com_locals_dict, espnow_com_locals_dict_table);
 
 //|     def __call__(self, *args: Optional[Any], **kwargs: Optional[Any]) -> Optional[Any]:
-//|         """Calls the private `__send` or `__recv` methods with the supplied ``args`` and ``kwargs``
-//|         based on whether the job parameter is set to ``send`` or ``recv``."""
+//|         """Calls the private `__send` or `__read` methods with the supplied ``args`` and ``kwargs``
+//|         based on whether the job parameter is set to ``send`` or ``read``."""
 //|         ...
 //|
 STATIC mp_obj_t espnow_com_call(mp_obj_t self_in, size_t n_args, size_t n_kw, const mp_obj_t *args) {
@@ -170,8 +174,8 @@ STATIC mp_obj_t espnow_com_call(mp_obj_t self_in, size_t n_args, size_t n_kw, co
         case MP_QSTR_send:
             meth = MP_OBJ_FROM_PTR(&espnow_com___send_obj);
             break;
-        case MP_QSTR_recv:
-            meth = MP_OBJ_FROM_PTR(&espnow_com___recv_obj);
+        case MP_QSTR_read:
+            meth = MP_OBJ_FROM_PTR(&espnow_com___read_obj);
             break;
         default:
             break;

ports/espressif/bindings/espnow/ESPNow.c

@@ -165,20 +165,20 @@ STATIC mp_obj_t espnow_get_send(mp_obj_t self_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(espnow_get_send_obj, espnow_get_send);
 
-MP_PROPERTY_GETTER(espnow_send_call_obj,
+MP_PROPERTY_GETTER(espnow_send_obj,
     (mp_obj_t)&espnow_get_send_obj);
 
-//|     recv: Communicate
-//|     """A `Communicate` object with ``job`` set to ``recv``. (read-only)"""
+//|     read: Communicate
+//|     """A `Communicate` object with ``job`` set to ``read``. (read-only)"""
 //|
-STATIC mp_obj_t espnow_get_recv(mp_obj_t self_in) {
+STATIC mp_obj_t espnow_get_read(mp_obj_t self_in) {
     espnow_obj_t *self = MP_OBJ_TO_PTR(self_in);
-    return MP_OBJ_FROM_PTR(self->recv);
+    return MP_OBJ_FROM_PTR(self->read);
 }
-STATIC MP_DEFINE_CONST_FUN_OBJ_1(espnow_get_recv_obj, espnow_get_recv);
+STATIC MP_DEFINE_CONST_FUN_OBJ_1(espnow_get_read_obj, espnow_get_read);
 
-MP_PROPERTY_GETTER(espnow_recv_call_obj,
-    (mp_obj_t)&espnow_get_recv_obj);
+MP_PROPERTY_GETTER(espnow_read_obj,
+    (mp_obj_t)&espnow_get_read_obj);
 
 // --- Peer Related Properties ---
 
@@ -208,8 +208,8 @@ STATIC const mp_rom_map_elem_t espnow_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_phy_rate),    MP_ROM_PTR(&espnow_phy_rate_obj) },
 
     // Send and receive messages
-    { MP_ROM_QSTR(MP_QSTR_send),        MP_ROM_PTR(&espnow_send_call_obj) },
-    { MP_ROM_QSTR(MP_QSTR_recv),        MP_ROM_PTR(&espnow_recv_call_obj) },
+    { MP_ROM_QSTR(MP_QSTR_send),        MP_ROM_PTR(&espnow_send_obj) },
+    { MP_ROM_QSTR(MP_QSTR_read),        MP_ROM_PTR(&espnow_read_obj) },
 
     // Peer related properties
     { MP_ROM_QSTR(MP_QSTR_peers),       MP_ROM_PTR(&espnow_peers_obj) },

ports/espressif/bindings/espnow/Peers.c

@@ -38,7 +38,7 @@
 // TODO: Check for deinit
 
 //| class Peers:
-//|     """A class that provides peer managment functions. Sequence[Peer]."""
+//|     """Maintains a `list` of `Peer` internally and only exposes a subset of `list` methods."""
 //|
 //|     def __init__(self) -> None:
 //|         """You cannot create an instance of `Peers`."""
@@ -86,22 +86,7 @@ STATIC MP_DEFINE_CONST_DICT(espnow_peers_locals_dict, espnow_peers_locals_dict_t
 STATIC void espnow_peers_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
     espnow_peers_obj_t *self = MP_OBJ_TO_PTR(self_in);
     mp_obj_list_t *list = MP_OBJ_TO_PTR(self->list);
-    const char *item_separator = ", ";
-    if (!(MICROPY_PY_UJSON && kind == PRINT_JSON)) {
-        kind = PRINT_REPR;
-    } else {
-        #if MICROPY_PY_UJSON_SEPARATORS
-        item_separator = MP_PRINT_GET_EXT(print)->item_separator;
-        #endif
-    }
-    mp_print_str(print, "[");
-    for (size_t i = 0; i < list->len; i++) {
-        if (i > 0) {
-            mp_print_str(print, item_separator);
-        }
-        mp_obj_print_helper(print, list->items[i], kind);
-    }
-    mp_print_str(print, "]");
+    return list->base.type->print(print, self->list, kind);
 }
 
 /******************************************************************************/
@@ -110,20 +95,7 @@ STATIC void espnow_peers_print(const mp_print_t *print, mp_obj_t self_in, mp_pri
 STATIC mp_obj_t espnow_peers_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
     espnow_peers_obj_t *self = MP_OBJ_TO_PTR(self_in);
     mp_obj_list_t *list = MP_OBJ_TO_PTR(self->list);
-    switch (op) {
-        case MP_UNARY_OP_BOOL:
-            return mp_obj_new_bool(list->len != 0);
-        case MP_UNARY_OP_LEN:
-            return MP_OBJ_NEW_SMALL_INT(list->len);
-        #if MICROPY_PY_SYS_GETSIZEOF
-        case MP_UNARY_OP_SIZEOF: {
-            size_t sz = sizeof(*list) + sizeof(mp_obj_t) * list->alloc;
-            return MP_OBJ_NEW_SMALL_INT(sz);
-        }
-        #endif
-        default:
-            return MP_OBJ_NULL; // op not supported
-    }
+    return list->base.type->ext->unary_op(op, self->list);
 }
 
 /******************************************************************************/
@@ -133,58 +105,18 @@ STATIC mp_obj_t espnow_peers_subscr(mp_obj_t self_in, mp_obj_t index, mp_obj_t v
     if (value != MP_OBJ_SENTINEL) {
         return MP_OBJ_NULL; // op not supported
     }
-
     espnow_peers_obj_t *self = MP_OBJ_TO_PTR(self_in);
     mp_obj_list_t *list = MP_OBJ_TO_PTR(self->list);
-
-    // load
-    #if MICROPY_PY_BUILTINS_SLICE
-    if (mp_obj_is_type(index, &mp_type_slice)) {
-        mp_bound_slice_t slice;
-        if (!mp_seq_get_fast_slice_indexes(list->len, index, &slice)) {
-            return mp_seq_extract_slice(list->len, list->items, &slice);
-        }
-
-        mp_obj_list_t *res = MP_OBJ_TO_PTR(mp_obj_new_list(slice.stop - slice.start, NULL));
-        mp_seq_copy(res->items, list->items + slice.start, res->len, mp_obj_t);
-        return MP_OBJ_FROM_PTR(res);
-    }
-    #endif
-    size_t index_val = mp_get_index(list->base.type, list->len, index, false);
-    return list->items[index_val];
+    return list->base.type->ext->subscr(self->list, index, value);
 }
 
 /******************************************************************************/
 /* peers iterator                                                             */
 
-typedef struct _espnow_peers_it_t {
-    mp_obj_base_t base;
-    mp_fun_1_t iternext;
-    mp_obj_t peers;
-    size_t cur;
-} espnow_peers_it_t;
-
-STATIC mp_obj_t espnow_peers_it_iternext(mp_obj_t self_in) {
-    espnow_peers_it_t *self = MP_OBJ_TO_PTR(self_in);
-    espnow_peers_obj_t *peers = MP_OBJ_TO_PTR(self->peers);
-    mp_obj_list_t *list = MP_OBJ_TO_PTR(peers->list);
-    if (self->cur < list->len) {
-        mp_obj_t o_out = list->items[self->cur];
-        self->cur += 1;
-        return o_out;
-    } else {
-        return MP_OBJ_STOP_ITERATION;
-    }
-}
-
-STATIC mp_obj_t espnow_peers_getiter(mp_obj_t o_in, mp_obj_iter_buf_t *iter_buf) {
-    assert(sizeof(espnow_peers_it_t) <= sizeof(mp_obj_iter_buf_t));
-    espnow_peers_it_t *o = (espnow_peers_it_t *)iter_buf;
-    o->base.type = &mp_type_polymorph_iter;
-    o->iternext = espnow_peers_it_iternext;
-    o->peers = o_in;
-    o->cur = 0;
-    return MP_OBJ_FROM_PTR(o);
+STATIC mp_obj_t espnow_peers_getiter(mp_obj_t self_in, mp_obj_iter_buf_t *iter_buf) {
+    espnow_peers_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    mp_obj_list_t *list = MP_OBJ_TO_PTR(self->list);
+    return list->base.type->ext->getiter(self->list, iter_buf);
 }
 
 espnow_peers_obj_t *espnow_peers_new(void) {

ports/espressif/bindings/espnow/__init__.c

@@ -64,7 +64,7 @@
 //|
 //|     while True:
 //|         if e:
-//|             packet = e.recv()
+//|             packet = e.read()
 //|             packets.append(packet)
 //|             if packet.msg == b'end':
 //|                 break

ports/espressif/common-hal/espnow/ESPNow.c

@@ -93,7 +93,7 @@ static void recv_cb(const uint8_t *mac, const uint8_t *msg, int msg_len) {
     ringbuf_t *buf = self->recv_buffer;
 
     if (sizeof(espnow_packet_t) + msg_len > ringbuf_num_empty(buf)) {
-        self->recv->failure++;
+        self->read->failure++;
         return;
     }
 
@@ -120,7 +120,7 @@ static void recv_cb(const uint8_t *mac, const uint8_t *msg, int msg_len) {
     ringbuf_put_n(buf, mac, ESP_NOW_ETH_ALEN);
     ringbuf_put_n(buf, msg, msg_len);
 
-    self->recv->success++;
+    self->read->success++;
 }
 
 bool common_hal_espnow_deinited(espnow_obj_t *self) {
@@ -133,7 +133,7 @@ void common_hal_espnow_construct(espnow_obj_t *self, mp_int_t buffer_size, mp_in
     common_hal_espnow_set_phy_rate(self, phy_rate);
 
     self->send = espnow_com_new(MP_QSTR_send);
-    self->recv = espnow_com_new(MP_QSTR_recv);
+    self->read = espnow_com_new(MP_QSTR_read);
 
     self->peers = espnow_peers_new();
 
@@ -166,7 +166,7 @@ void common_hal_espnow_init(espnow_obj_t *self) {
 }
 
 // De-initialize the ESP-NOW software stack,
-// disable callbacks and deallocate the recv data buffers.
+// disable callbacks and deallocate the recv data buffer.
 void common_hal_espnow_deinit(espnow_obj_t *self) {
     if (common_hal_espnow_deinited(self)) {
         return;
@@ -214,7 +214,7 @@ mp_obj_t common_hal_espnow_send(espnow_obj_t *self, const mp_buffer_info_t *mess
     return mp_const_none;
 }
 
-mp_obj_t common_hal_espnow_recv(espnow_obj_t *self) {
+mp_obj_t common_hal_espnow_read(espnow_obj_t *self) {
     if (!ringbuf_num_filled(self->recv_buffer)) {
         return mp_const_none;
     }

ports/espressif/common-hal/espnow/ESPNow.h

@@ -40,8 +40,8 @@ typedef struct _espnow_obj_t {
     ringbuf_t *recv_buffer;     // A buffer for received packets
     size_t recv_buffer_size;    // The size of the recv_buffer
     wifi_phy_rate_t phy_rate;   // The ESP-NOW physical layer rate.
-    espnow_com_obj_t *send;     // The tx packet stats
-    espnow_com_obj_t *recv;     // The rx packet stats
+    espnow_com_obj_t *send;     // For keeping tx stats
+    espnow_com_obj_t *read;     // For keeping rx stats
     espnow_peers_obj_t *peers;  // The sequence of peers
 } espnow_obj_t;
 
@@ -57,4 +57,4 @@ extern void common_hal_espnow_set_phy_rate(espnow_obj_t *self, mp_int_t value);
 extern void common_hal_espnow_set_pmk(espnow_obj_t *self, const uint8_t *key);
 
 extern mp_obj_t common_hal_espnow_send(espnow_obj_t *self, const mp_buffer_info_t *message, const uint8_t *mac);
-extern mp_obj_t common_hal_espnow_recv(espnow_obj_t *self);
+extern mp_obj_t common_hal_espnow_read(espnow_obj_t *self);