[pull] main from adafruit:main

.pre-commit-config.yaml

@@ -18,13 +18,13 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/pycqa/pylint
-    rev: v2.17.4
+    rev: v3.3.1
     hooks:
       - id: pylint
         name: pylint (library code)
         types: [python]
         args:
-          - --disable=consider-using-f-string
+          - --disable=consider-using-f-string,too-many-arguments,too-many-positional-arguments
         exclude: "^(docs/|examples/|tests/|setup.py$)"
       - id: pylint
         name: pylint (example code)

.readthedocs.yaml

@@ -8,6 +8,9 @@
 # Required
 version: 2
 
+sphinx:
+  configuration: docs/conf.py
+
 build:
   os: ubuntu-20.04
   tools:

README.rst

@@ -28,7 +28,9 @@ Dependencies
 This driver depends on:
 
 * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
-* `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
+* `Adafruit Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
+* `Adafruit CircuitPython ConnectionManager <https://github.com/adafruit/Adafruit_CircuitPython_ConnectionManager/>`_
+* `Adafruit CircuitPython Requests <https://github.com/adafruit/Adafruit_CircuitPython_Requests/>`_
 
 Please ensure all dependencies are available on the CircuitPython filesystem.
 This is easily achieved by downloading

adafruit_esp32spi/adafruit_esp32spi.py

@@ -28,6 +28,7 @@
 
 import struct
 import time
+import warnings
 from micropython import const
 from adafruit_bus_device.spi_device import SPIDevice
 from digitalio import Direction
@@ -131,6 +132,95 @@
 # pylint: disable=too-many-lines
 
 
+class Network:
+    """A wifi network provided by a nearby access point."""
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        esp_spi_control=None,
+        raw_ssid=None,
+        raw_bssid=None,
+        raw_rssi=None,
+        raw_channel=None,
+        raw_country=None,
+        raw_authmode=None,
+    ):
+        self._esp_spi_control = esp_spi_control
+        self._raw_ssid = raw_ssid
+        self._raw_bssid = raw_bssid
+        self._raw_rssi = raw_rssi
+        self._raw_channel = raw_channel
+        self._raw_country = raw_country
+        self._raw_authmode = raw_authmode
+
+    def _get_response(self, cmd):
+        respose = self._esp_spi_control._send_command_get_response(  # pylint: disable=protected-access
+            cmd, [b"\xFF"]
+        )
+        return respose[0]
+
+    @property
+    def ssid(self):
+        """String id of the network"""
+        if self._raw_ssid:
+            response = self._raw_ssid
+        else:
+            response = self._get_response(_GET_CURR_SSID_CMD)
+        return response.decode("utf-8")
+
+    @property
+    def bssid(self):
+        """BSSID of the network (usually the AP’s MAC address)"""
+        if self._raw_bssid:
+            response = self._raw_bssid
+        else:
+            response = self._get_response(_GET_CURR_BSSID_CMD)
+        return bytes(response)
+
+    @property
+    def rssi(self):
+        """Signal strength of the network"""
+        if self._raw_bssid:
+            response = self._raw_rssi
+        else:
+            response = self._get_response(_GET_CURR_RSSI_CMD)
+        return struct.unpack("<i", response)[0]
+
+    @property
+    def channel(self):
+        """Channel number the network is operating on"""
+        if self._raw_channel:
+            return self._raw_channel[0]
+        return None
+
+    @property
+    def country(self):
+        """String id of the country code"""
+        return self._raw_country
+
+    @property
+    def authmode(self):
+        """String id of the authmode
+
+        derived from Nina code:
+        https://github.com/adafruit/nina-fw/blob/master/arduino/libraries/WiFi/src/WiFi.cpp#L385
+        """
+        if self._raw_authmode:
+            response = self._raw_authmode[0]
+        else:
+            response = self._get_response(_GET_CURR_ENCT_CMD)[0]
+
+        if response == 7:
+            return "OPEN"
+        if response == 5:
+            return "WEP"
+        if response == 2:
+            return "PSK"
+        if response == 4:
+            return "WPA2"
+        return "UNKNOWN"
+
+
 class ESP_SPIcontrol:  # pylint: disable=too-many-public-methods, too-many-instance-attributes
     """A class that will talk to an ESP32 module programmed with special firmware
     that lets it act as a fast an efficient WiFi co-processor"""
@@ -327,7 +417,7 @@ def _wait_response_cmd(self, cmd, num_responses=None, *, param_len_16=False):
             print("Read %d: " % len(responses[0]), responses)
         return responses
 
-    def _send_command_get_response(
+    def _send_command_get_response(  # pylint: disable=too-many-arguments
         self,
         cmd,
         params=None,
@@ -359,7 +449,7 @@ def firmware_version(self):
         if self._debug:
             print("Firmware version")
         resp = self._send_command_get_response(_GET_FW_VERSION_CMD)
-        return resp[0]
+        return resp[0].decode("utf-8").replace("\x00", "")
 
     @property
     def MAC_address(self):  # pylint: disable=invalid-name
@@ -372,12 +462,12 @@ def MAC_address(self):  # pylint: disable=invalid-name
     @property
     def MAC_address_actual(self):  # pylint: disable=invalid-name
         """A bytearray containing the actual MAC address of the ESP32"""
-        if self._debug:
-            print("MAC address")
-        resp = self._send_command_get_response(_GET_MACADDR_CMD, [b"\xFF"])
-        new_resp = bytearray(resp[0])
-        new_resp = reversed(new_resp)
-        return new_resp
+        return bytearray(reversed(self.MAC_address))
+
+    @property
+    def mac_address(self):
+        """A bytes containing the actual MAC address of the ESP32"""
+        return bytes(self.MAC_address_actual)
 
     def start_scan_networks(self):
         """Begin a scan of visible access points. Follow up with a call
@@ -397,16 +487,19 @@ def get_scan_networks(self):
         # print("SSID names:", names)
         APs = []  # pylint: disable=invalid-name
         for i, name in enumerate(names):
-            a_p = {"ssid": name}
-            rssi = self._send_command_get_response(_GET_IDX_RSSI_CMD, ((i,),))[0]
-            a_p["rssi"] = struct.unpack("<i", rssi)[0]
-            encr = self._send_command_get_response(_GET_IDX_ENCT_CMD, ((i,),))[0]
-            a_p["encryption"] = encr[0]
             bssid = self._send_command_get_response(_GET_IDX_BSSID_CMD, ((i,),))[0]
-            a_p["bssid"] = bssid
-            chan = self._send_command_get_response(_GET_IDX_CHAN_CMD, ((i,),))[0]
-            a_p["channel"] = chan[0]
-            APs.append(a_p)
+            rssi = self._send_command_get_response(_GET_IDX_RSSI_CMD, ((i,),))[0]
+            channel = self._send_command_get_response(_GET_IDX_CHAN_CMD, ((i,),))[0]
+            authmode = self._send_command_get_response(_GET_IDX_ENCT_CMD, ((i,),))[0]
+            APs.append(
+                Network(
+                    raw_ssid=name,
+                    raw_bssid=bssid,
+                    raw_rssi=rssi,
+                    raw_channel=channel,
+                    raw_authmode=authmode,
+                )
+            )
         return APs
 
     def scan_networks(self):
@@ -512,23 +605,12 @@ def _wifi_set_ap_passphrase(self, ssid, passphrase, channel):
             raise OSError("Failed to setup AP password")
 
     @property
-    def ssid(self):
-        """The name of the access point we're connected to"""
-        resp = self._send_command_get_response(_GET_CURR_SSID_CMD, [b"\xFF"])
-        return resp[0]
-
-    @property
-    def bssid(self):
-        """The MAC-formatted service set ID of the access point we're connected to"""
-        resp = self._send_command_get_response(_GET_CURR_BSSID_CMD, [b"\xFF"])
-        return resp[0]
-
-    @property
-    def rssi(self):
-        """The receiving signal strength indicator for the access point we're
-        connected to"""
-        resp = self._send_command_get_response(_GET_CURR_RSSI_CMD, [b"\xFF"])
-        return struct.unpack("<i", resp[0])[0]
+    def ap_info(self):
+        """Network object containing BSSID, SSID, authmode, channel, country and RSSI when
+        connected to an access point. None otherwise."""
+        if self.is_connected:
+            return Network(esp_spi_control=self)
+        return None
 
     @property
     def network_data(self):
@@ -545,14 +627,19 @@ def ip_address(self):
         return self.network_data["ip_addr"]
 
     @property
-    def is_connected(self):
+    def connected(self):
         """Whether the ESP32 is connected to an access point"""
         try:
             return self.status == WL_CONNECTED
         except OSError:
             self.reset()
             return False
 
+    @property
+    def is_connected(self):
+        """Whether the ESP32 is connected to an access point"""
+        return self.connected
+
     @property
     def ap_listening(self):
         """Returns if the ESP32 is in access point mode and is listening for connections"""
@@ -568,10 +655,21 @@ def disconnect(self):
         if resp[0][0] != 1:
             raise OSError("Failed to disconnect")
 
-    def connect(self, secrets):
-        """Connect to an access point using a secrets dictionary
-        that contains a 'ssid' and 'password' entry"""
-        self.connect_AP(secrets["ssid"], secrets["password"])
+    def connect(self, ssid, password=None, timeout=10):
+        """Connect to an access point with given name and password.
+
+        **Deprecated functionality:** If the first argument (``ssid``) is a ``dict``,
+        assume it is a dictionary with entries for keys ``"ssid"`` and, optionally, ``"password"``.
+        This mimics the previous signature for ``connect()``.
+        This upward compatibility will be removed in a future release.
+        """
+        if isinstance(ssid, dict):  # secrets
+            warnings.warn(
+                "The passing in of `secrets`, is deprecated. Use connect() with `ssid` and "
+                "`password` instead and fetch values from settings.toml with `os.getenv()`."
+            )
+            ssid, password = ssid["ssid"], ssid.get("password")
+        self.connect_AP(ssid, password, timeout_s=timeout)
 
     def connect_AP(self, ssid, password, timeout_s=10):  # pylint: disable=invalid-name
         """Connect to an access point with given name and password.
@@ -647,6 +745,11 @@ def create_AP(
             raise ConnectionError("Failed to create AP", ssid)
         raise OSError("Unknown error 0x%02x" % stat)
 
+    @property
+    def ipv4_address(self):
+        """IP address of the station when connected to an access point."""
+        return self.pretty_ip(self.ip_address)
+
     def pretty_ip(self, ip):  # pylint: disable=no-self-use, invalid-name
         """Converts a bytearray IP address to a dotted-quad string for printing"""
         return "%d.%d.%d.%d" % (ip[0], ip[1], ip[2], ip[3])
@@ -701,7 +804,7 @@ def socket_open(self, socket_num, dest, port, conn_mode=TCP_MODE):
         if self._debug:
             print("*** Open socket to", dest, port, conn_mode)
         if conn_mode == ESP_SPIcontrol.TLS_MODE and self._tls_socket is not None:
-            raise OSError(23)  # ENFILE - File table overflow
+            raise OSError(23, "Only one open SSL connection allowed")
         port_param = struct.pack(">H", port)
         if isinstance(dest, str):  # use the 5 arg version
             dest = bytes(dest, "utf-8")
@@ -925,7 +1028,7 @@ def set_digital_read(self, pin):
         :param int pin: ESP32 GPIO pin to read from.
         """
         # Verify nina-fw => 1.5.0
-        fw_semver_maj = bytes(self.firmware_version).decode("utf-8")[2]
+        fw_semver_maj = self.firmware_version[2]
         assert int(fw_semver_maj) >= 5, "Please update nina-fw to 1.5.0 or above."
 
         resp = self._send_command_get_response(_SET_DIGITAL_READ_CMD, ((pin,),))[0]
@@ -944,7 +1047,7 @@ def set_analog_read(self, pin, atten=ADC_ATTEN_DB_11):
         :param int atten: attenuation constant
         """
         # Verify nina-fw => 1.5.0
-        fw_semver_maj = bytes(self.firmware_version).decode("utf-8")[2]
+        fw_semver_maj = self.firmware_version[2]
         assert int(fw_semver_maj) >= 5, "Please update nina-fw to 1.5.0 or above."
 
         resp = self._send_command_get_response(_SET_ANALOG_READ_CMD, ((pin,), (atten,)))