Library Utilities

def netcode_to_str(error_code: LinkStatus) -> str:
    """Convert the given wireless network error code to a short string,
    indicating the possible error.

    Note that no validation for sanity of the error code is attempted by
    this function. However the returned values are expected to be
    displayed directly to the user, and so should indicate (at least
    minimally) where further investigation might be helpful.
    """
    if error_code == LinkStatus.CYW43_LINK_DOWN:
        return "The wireless link is unavailable - check the SSID is correct"
    elif error_code == LinkStatus.CYW43_LINK_JOIN:
        return "The SSID or password is incorrect  - check the SSID and password."
    elif error_code == LinkStatus.CYW43_LINK_NOIP:
        return (
            "The join request was successful, but no IP address was returned - check"
            " the DHCP settings for the specified SSID"
        )
    elif error_code == LinkStatus.CYW43_LINK_UP:
        return "Successfully joined, and an IP address was obtained from the network"
    elif error_code == LinkStatus.CYW43_LINK_FAIL:
        return "The link specified by the SSID is unavailable for unknown reasons"
    elif error_code == LinkStatus.CYW43_LINK_NONET:
        return (
            "The authentication likely succeeded: but the subsequent attempts to"
            " complete the connection failed"
        )
    elif error_code == LinkStatus.CYW43_LINK_BADAUTH:
        return (
            "General failure code before authentication - check the supplied password."
        )
    else:
        return "Unknown error"

def wireless_enable(
    ssid: str,
    password: str,
    link_light: Union[int, str] = "WL_GPIO0",
) -> None:
    """Enable the default wireless interface, connecting to the networking
    using the specified `ssid` and `password`. Optionally also supply the name,
    or the pin number, of the GPIO pin to use as the `link_light`, which will
    be 'on' if the network connection succeeds (and 'off' otherwise).

    !!! danger "Clear Text Password"

        As with the default wireless library, the `password` **must** be supplied to
        this function in clear text. This presents a potential exposure risk
        of the `password`, and that risk should be mitigated by appropriate storage and
        handling of the password _before_ calling this function.

    Parameters
    ----------

    ssid: str
        The SSID of the network to connect to.
    password: str
        The plain text of the password needed by the wireless network.
    link_light: int or str, optional
        The name (if a `str`) or number (if an `int`) of the GPIO pin to use as
        the link light. If a connection succeeds, this GPIO Pin will be set 'high':
        otherwise 'low' on failure. Defaults to the on-board (user) LED of the Pico W.

    Raises
    ------

    NameError
        The name (`int` or `str`) for the `link_light` is invalid, and a `Pin` with this name cannot be created.
    WirelessNetworkError
        The network named `ssid` cannot be joined with the specified `password`. See the exact `msg` of the `Exception` to determine whether this is a temporary (and may be retried) or a permanent error.

    """

    # Set-up the link status LED
    try:
        if link_light is not None:
            link_status = Pin(link_light, Pin.OUT)
    except NameError:
        print("Cannot initialise the requested link pin")

    # Set-up the Wireless Driver
    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)
    wlan.connect(ssid, password)

    # Number of connection attempts
    # before a hard fail
    max_wait = 10

    while max_wait > 0:
        if wlan.status() == LinkStatus.CYW43_LINK_UP:
            break

        max_wait -= 1
        print("waiting for connection...")
        time.sleep(1)

    # Handle connection error
    if wlan.status() != LinkStatus.CYW43_LINK_UP:
        msg = f"Network connection attempt failed: { netcode_to_str(wlan.status()) } (Code: {wlan.status()})"
        raise WirelessNetworkError(msg)
    else:
        print("Connected")
        print("IP: " + wlan.ifconfig()[0])

    # Display the link light if connected
    if wlan.status() == LinkStatus.CYW43_LINK_UP:
        link_status.on()
    else:
        link_status.off()