wifi
====

.. py:module:: wifi

.. autoapi-nested-parse::

   Join a WLAN in station mode.



Attributes
----------

.. autoapisummary::

   wifi.POLL_INTERVAL_S
   wifi.STAT_CONNECTING
   wifi.RADIO_SETTLE_S
   wifi.LAST_NETWORK_FILE
   wifi.SCANNING
   wifi.CONNECTING


Functions
---------

.. autoapisummary::

   wifi.connect
   wifi.known_networks
   wifi.plan
   wifi.connect_any
   wifi.last_network
   wifi.remember_network


Module Contents
---------------

.. py:data:: POLL_INTERVAL_S
   :value: 0.25


.. py:data:: STAT_CONNECTING
   :value: 1001


.. py:data:: RADIO_SETTLE_S
   :value: 0.5


.. py:function:: connect(wlan, ssid, password, timeout_s=6, attempts=3, log=print)

   Connect `wlan` (a network.WLAN STA interface) and return its IP address.

   Each attempt waits up to `timeout_s`; between attempts the radio is
   restarted. On the Feather ESP32-S3 the first attempt after a reset
   occasionally hangs in STAT_CONNECTING, while successful attempts
   finish within 1-3 s; a fresh attempt then usually succeeds.
   Returns None if all attempts fail.


.. py:data:: LAST_NETWORK_FILE
   :value: 'wlan_last.txt'


.. py:data:: SCANNING
   :value: 'scanning'


.. py:data:: CONNECTING
   :value: 'connecting'


.. py:function:: known_networks(config)

   Return the configured networks as [(ssid, password)].

   They come from config.WIFI_NETWORKS, or from the single
   WIFI_SSID/WIFI_PASSWORD pair of older configurations.


.. py:function:: plan(networks, visible)

   Order `networks` for trying after a scan.

   The list order is the priority. Networks in range come first, then
   those the scan did not show (hidden SSIDs do not show up). `visible`
   is a set of SSIDs.


.. py:function:: connect_any(wlan, networks, last=None, timeout_s=6, attempts=2, log=print, progress=None)

   Connect to one of the known `networks`.

   The first network in the list that works wins; the result is
   `(ip, ssid)`, or `(None, None)` if none works.

   If `last` (the network that worked last time) is the first in the list,
   it is tried without a scan, saving 2-3 s per wake in the usual case.
   Otherwise a scan decides, so the board moves back to a higher-priority
   network (like from a travel router to the home WLAN) when it is in range.

   `progress(step, ssid)` is called before each step, with SCANNING (ssid
   None) or CONNECTING, to show what takes the time.


.. py:function:: last_network(path=LAST_NETWORK_FILE)

   Return the SSID that worked last time, or None.


.. py:function:: remember_network(ssid, path=LAST_NETWORK_FILE)

   Store the SSID that worked; writes the flash only when it changes.