{"id":31710328,"url":"https://github.com/zyltr/wlan-assistant","last_synced_at":"2026-05-15T01:36:27.312Z","repository":{"id":309836912,"uuid":"1036264222","full_name":"zyltr/wlan-assistant","owner":"zyltr","description":"A MicroPython module for managing WLAN connections","archived":false,"fork":false,"pushed_at":"2025-08-14T02:53:30.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-09T00:15:30.046Z","etag":null,"topics":["asynchronous","micropython","network","pico-w","raspberry-pi-pico-w","wlan"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zyltr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-11T20:09:24.000Z","updated_at":"2025-08-14T02:53:20.000Z","dependencies_parsed_at":"2025-08-14T04:32:06.708Z","dependency_job_id":"14a5cbc2-70ae-4697-8078-66eca0183233","html_url":"https://github.com/zyltr/wlan-assistant","commit_stats":null,"previous_names":["zyltr/wlan-assistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zyltr/wlan-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyltr%2Fwlan-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyltr%2Fwlan-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyltr%2Fwlan-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyltr%2Fwlan-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zyltr","download_url":"https://codeload.github.com/zyltr/wlan-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyltr%2Fwlan-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33050359,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asynchronous","micropython","network","pico-w","raspberry-pi-pico-w","wlan"],"created_at":"2025-10-09T00:13:35.557Z","updated_at":"2026-05-15T01:36:27.145Z","avatar_url":"https://github.com/zyltr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WLAN Assistant\n\n## Overview\n\nThe module provides tiny, async-friendly helper methods built around MicroPython's network.WLAN class.\nIt aims to do the following:\n\n- Connect to one or more Wi‑Fi stations using JSON files or hardcoded credentials.\n- Configure an access point as a fallback when no known networks are reachable.\n- Continuously monitor the environment and roam to the best available network.\n- Notifications via async callbacks when connectivity changes, such as connecting or disconnecting from a known network\n  or access point.\n\n## Requirements\n\n- Raspberry Pi Pico W\n    - \u003cins\u003e**Other devices have not been tested.**\u003c/ins\u003e\n- MicroPython 1.25 or later\n    - \u003cins\u003e**Earlier versions may work but are untested.**\u003c/ins\u003e\n- JSON files containing SSID and password for known networks.\n    - \u003cins\u003e**Optional, but recommended for simplicity.**\u003c/ins\u003e\n\n## Installation\n\nFor microcontrollers, copy the **assistant** directory to your microcontroller's root directory,\npreferably in a root subdirectory named **lib**.\n\n### Installing using `mpremote`\n\n*This only installs the core module onto the microcontroller and not the example or tests.*\n\n```shell\nmpremote mip install github:zyltr/wlan-assistant\n```\n\n### Installing using `mip` and `micropython`\n\n*This installs the core module, not the example and the tests, onto a directory on\nyour computer.\nIdeal for local development.*\n\n```shell\nmicropython -m mip install --target ./lib github:zyltr/wlan-assistant\n```\n\n*`--target ./lib` specifies the directory to install the module to.\nIn this case, it will copy the module to the **lib** directory in the current directory, whatever that may be.*\n\n**For this command to work, you must compile `micropython` and then modify your computers PATH variable to include the\ndirectory containing the `micropython` executable.**\n\n[Building `micropython` on Unix](https://github.com/micropython/micropython/blob/master/ports/unix/README.md)\n\n## Basic Usage\n\n### AP (Access Point)\n\nThe AP class is used to configure and start an access point.\nThe only required parameter is the `password` while a `ssid` is optional.\nIf no ssid is provided, the microcontroller, a Pico W in this case, will generate a SSID.\n\nAn optional `timeout` and `verbose` parameter can be passed to the `configure` method.\nWhen `timeout` is specified, the method will have `timeout` seconds to set up and configure the AP.\nIf `verbose` is set to True, the method will print connection state changes to the console.\n\n#### Configuring and starting an AP synchronously\n\n```python\nfrom assistant import AP\n\n# Fill in the placeholders with your own credentials.\nap: AP = AP(password=\"ap-password\", ssid=\"ap-ssid\")\nap.configure()\n```\n\n#### Configuring and starting an AP asynchronously\n\n```python\nfrom asyncio import run\nfrom assistant import AP\n\n# Fill in the placeholders with your own credentials.\nap: AP = AP(password=\"ap-password\", ssid=\"ap-ssid\")\nrun(ap.aconfigure())\n```\n\n\u003cins\u003eThis is not the best way to configure an AP asynchronously and is just for demonstration.\nFor a better example, see the **main.py** in the **example** directory.\n\u003c/ins\u003e\n\n### Station\n\nThe Station class is used to connect to a local network.\nThe required parameters are password and ssid.\nThey are both case-sensitive.\n\nOptional `retries`, `timeout`, and `verbose` parameter can be passed to the `connect` method.\n`Retries` controls how many times the connection will be attempted before giving up.\n`Timeout` controls the amount of time in seconds the method has to connect to the network.\n`Verbose` allows additional information to be printed to the console.\n\n#### Connecting to a local network synchronously.\n\n```python\nfrom assistant import Station\n\n# Fill in the placeholders with your own credentials.\nstation: Station = Station(password=\"network-password\", ssid=\"network-ssid\")\nstation.connect()\n```\n\n#### Connecting to a local network asynchronously.\n\n```python\nfrom asyncio import run\nfrom assistant import Station\n\n# Fill in the placeholders with your own credentials.\nstation: Station = Station(password=\"network-password\", ssid=\"network-ssid\")\nrun(station.aconnect())\n```\n\n\u003cins\u003eThis is not the best way to connect a Station asynchronously and is just for demonstration.\nFor a better example, see the **main.py** in the **example** directory.\n\u003c/ins\u003e\n\n## Monitoring and Watching\n\n#### Monitoring a single network and using an access point for fallback.\n\n```python\nfrom asyncio import run\nfrom assistant import Station, AP, monitor\n\n# Fill in the placeholders with your own credentials.\nap: AP = AP(password=\"ap-password\", ssid=\"ap-ssid\")\nstation: Station = Station(password=\"network-password\", ssid=\"network-ssid\")\n\n\nasync def connectedCallback(interface: AP | Station):\n    print(f\"Connected to {interface.ssid}\")\n\n\nasync def disconnectedCallback(interface: AP | Station):\n    print(f\"Disconnected from {interface.ssid}\")\n\n\nrun(monitor(connectedCallback=connectedCallback, disconnectedCallback=disconnectedCallback, fallback=ap,\n            station=station))\n```\n\n#### Watching a list of networks and using an access point for fallback.\n\n```python\nfrom asyncio import run\nfrom assistant import Station, AP, watch\n\n# Fill in the placeholders with your own credentials.\nap: AP = AP(password=\"ap-password\", ssid=\"ap-ssid\")\nprimary: Station = Station(password=\"network-password\", ssid=\"network-ssid\")\nsecondary: Station = Station(password=\"network-password\", ssid=\"network-ssid\")\n\n\nasync def connectedCallback(interface: AP | Station):\n    print(f\"Connected to {interface.ssid}\")\n\n\nasync def disconnectedCallback(interface: AP | Station):\n    print(f\"Disconnected from {interface.ssid}\")\n\n\nrun(watch(connectedCallback=connectedCallback, disconnectedCallback=disconnectedCallback, fallback=ap,\n          stations=[primary, secondary]))\n```\n\n## Examples\n\nAn in-depth example is available in the **example** directory. It expects a **network.json** file to\nexist at the root directory to function. The **network.json** file should be formatted as follows:\n\n```json\n[\n  {\n    \"ssid\": \"ssid-1\",\n    \"password\": \"password-1\"\n  },\n  {\n    \"ssid\": \"ssid-2\",\n    \"password\": \"password-2\"\n  },\n  {\n    \"ssid\": \"ssid-n\",\n    \"password\": \"password-n\"\n  }\n]\n```\n\nThis example will attempt to connect to the first network in the list, then the second, and so on.\nIf none of the networks are reachable, an access point will be started.\nDepending on what interface is being used (AP or Station),\nthe onboard LED will blink once when configured as an AP and twice when connected to a local network.\n\n## Tests\n\nA few tests are available in the **tests** directory.\nThe tests are meant to isolate any potential bugs and test the functionality of the module.\nUsing them requires a **hotspot.json** and **wlan.json** to exist at the root directory.\n**hotspot.json** ideally should contain the credentials to a hotspot, such as phone that can be\nswitched on and off the test the functionality and switching capability of\nthe `monitor` and `watch` modules.\nThese files should be formatted as follows:\n\n```json\n{\n  \"password\": \"your-password\",\n  \"ssid\": \"your-ssid\"\n}\n```\n\n# Notes and limitations\n\n- SSID matching is case-sensitive.\n- This code focuses on MicroPython.\n\n## Troubleshooting\n\n- Nothing connects:\n    - Confirm SSID and password are correct. Case sensitivity is important.\n    - Try verbose=True to see connection state logs.\n    - Restart the board by hard reset.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyltr%2Fwlan-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzyltr%2Fwlan-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyltr%2Fwlan-assistant/lists"}