esp8266/network_wlan: Allow enumerating connected stations in AP mode.

agatti · agatti · commit b9baf4a4452c · 2025-02-27T02:43:13.000+01:00
This commit introduces the ability to obtain a list of stations connected to the device when in soft-AP mode. A new parameter ("stations") to pass to WLAN.status is supported, returning a tuple of (bssid, ipv4) entries, one per connected station. An empty tuple is returned if no stations are connected, and an exception is raised if an error occurred whilst building the python objects to return to the interpreter. Documentation is also updated to cover the new parameter. This fixes #5395. Signed-off-by: Alessandro Gatti <a.gatti@frob.it>
diff --git a/docs/library/network.WLAN.rst b/docs/library/network.WLAN.rst
@@ -85,7 +85,17 @@ Methods
         * ``STAT_GOT_IP`` -- connection successful.
 
     When called with one argument *param* should be a string naming the status
-    parameter to retrieve.  Supported parameters in WiFI STA mode are: ``'rssi'``.
+    parameter to retrieve, and different parameters are supported depending on the
+    mode the WiFi is in.
+
+    In STA mode, passing ``'rssi'`` returns a signal strength indicator value, whose
+    format varies depending on the port (currently supported on ESP32 and ESP8266).
+
+    In AP mode, passing ``'stations'`` returns a list of connected WiFi stations
+    (currently supported on ports/boards that use the CYW43 WiFi driver, and the
+    ESP32 and ESP8266 ports).  The format of the station information entries varies
+    across ports, providing either the raw BSSID of the connected station, the IP
+    address of the connected station, or both.
 
 .. method:: WLAN.isconnected()
 
diff --git a/ports/esp8266/network_wlan.c b/ports/esp8266/network_wlan.c
@@ -170,6 +170,37 @@ static mp_obj_t esp_disconnect(mp_obj_t self_in) {
 }
 static MP_DEFINE_CONST_FUN_OBJ_1(esp_disconnect_obj, esp_disconnect);
 
+static mp_obj_t build_stations_tuple(void) {
+    mp_uint_t count = wifi_softap_get_station_num();
+    if (count == 0) {
+        return mp_const_empty_tuple;
+    }
+    mp_obj_tuple_t *stations = NULL;
+    struct station_info *info = wifi_softap_get_station_info();
+    if (info == NULL) {
+        mp_raise_msg(&mp_type_OSError, MP_ERROR_TEXT("no station info available"));
+    }
+    nlr_buf_t nlr;
+    if (nlr_push(&nlr) == 0) {
+        stations = MP_OBJ_TO_PTR(mp_obj_new_tuple(count, NULL));
+        struct station_info *current = info;
+        size_t station_index = 0;
+        mp_obj_t entry[2] = { 0 };
+        while (current != NULL && station_index < count) {
+            entry[0] = mp_obj_new_bytes(current->bssid, sizeof(current->bssid));
+            entry[1] = netutils_format_ipv4_addr((uint8_t *)&current->ip.addr, NETUTILS_BIG);
+            stations->items[station_index++] = mp_obj_new_tuple(2, entry);
+            current = STAILQ_NEXT(current, next);
+        }
+        nlr_pop();
+    } else {
+        mp_obj_print_exception(&mp_plat_print, MP_OBJ_FROM_PTR(nlr.ret_val));
+        stations = NULL;
+    }
+    wifi_softap_free_station_info();
+    return stations != NULL ? MP_OBJ_FROM_PTR(stations) : MP_OBJ_NULL;
+}
+
 static mp_obj_t esp_status(size_t n_args, const mp_obj_t *args) {
     wlan_if_obj_t *self = MP_OBJ_TO_PTR(args[0]);
     if (n_args == 1) {
@@ -185,6 +216,12 @@ static mp_obj_t esp_status(size_t n_args, const mp_obj_t *args) {
                 if (self->if_id == STATION_IF) {
                     return MP_OBJ_NEW_SMALL_INT(wifi_station_get_rssi());
                 }
+                break;
+            case MP_QSTR_stations:
+                if (self->if_id == SOFTAP_IF) {
+                    return build_stations_tuple();
+                }
+                break;
         }
         mp_raise_ValueError(MP_ERROR_TEXT("unknown status param"));
     }
