{"id":23140603,"url":"https://github.com/andyrids/micropython-default","last_synced_at":"2026-04-15T14:36:15.351Z","repository":{"id":268465079,"uuid":"904388164","full_name":"andyrids/micropython-default","owner":"andyrids","description":"Micropython project template for the Raspberry Pi Pico W","archived":false,"fork":false,"pushed_at":"2024-12-25T22:58:56.000Z","size":339,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-09T21:13:50.613Z","etag":null,"topics":["asyncio","bootstrap","microdot","micropython","pico","raspberrypi"],"latest_commit_sha":null,"homepage":"https://andyrids.github.io/micropython-default/","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/andyrids.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-12-16T19:43:08.000Z","updated_at":"2025-02-03T20:19:11.000Z","dependencies_parsed_at":"2024-12-16T23:53:12.852Z","dependency_job_id":"070f1f16-035a-494a-9e9a-f83d04fd3625","html_url":"https://github.com/andyrids/micropython-default","commit_stats":null,"previous_names":["andyrids/micropython-default"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyrids%2Fmicropython-default","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyrids%2Fmicropython-default/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyrids%2Fmicropython-default/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andyrids%2Fmicropython-default/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andyrids","download_url":"https://codeload.github.com/andyrids/micropython-default/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247166172,"owners_count":20894654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["asyncio","bootstrap","microdot","micropython","pico","raspberrypi"],"created_at":"2024-12-17T14:10:43.757Z","updated_at":"2026-04-15T14:36:10.308Z","avatar_url":"https://github.com/andyrids.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Micropython Default\n\n\u003e [!NOTE]  \n\u003e This project is a WIP.\n\n## Introduction\n\nThis MicroPython project acts as a template, which forms the basis for creating a Pico W 'thing' in an AWS IoT Core context. It also acts as a template for Micropython projects that need to facilitate access to WiFi through serving a credentials form. The default `main.py` runs an async application function (`async_main`), which carries out the following steps:\n\n1. Attempt WiFi STA connection using env/secrets\n2. Synchronise network time on STA connection\n3. Monitor for connection issues\n4. Wait 15 seconds and check connection again\n5. Start Microdot server on WiFi connection fail\n    1. Serve HTML form to update WiFi credentials\n    2. Update env/secrets if correct\n    3. Shutdown server \u0026 attempt WiFi connection\n    4. Synchronise network time on STA connection\n6. Repeat steps 3 - 5 as necessary\n\nModification of `async_main` should allow extra functionality, such as connection to an AWS IoT Core endpoint via the MicroPython MQTT libraries and the provided template functions in `lib/project/connection.py`.\n\nThis project has the following dependency tree:\n\n```text\nmicropython-default\n├── picoproject                       \u003c-- MicroPython project CLI\n├── bump-my-version (group: dev)\n├── micropython-rp2-rpi-pico-w-stubs  \u003c-- MicroPython Pico W stubs\n├── ruff (group: dev)                 \u003c-- Linting/formatting\n├── sphinx (group: dev)               \u003c-- Documentation\n└── sphinx-rtd-theme (group: dev)     \u003c-- Read the docs theme\n```\n\nI am testing the use of another library, picoproject, which is a CLI (README[repository](https://github.com/andyrids/picoproject)) for managing local installation of MicroPython packages for development, MicroPython binary compilation and exporting of project files.\n\n## Project Layout\n\n```text\nsrc/micropython_default\n├── env\n│   └── secrets.py                  \u003c-- WiFi credentials for STA/AP mode\n├── lib\n│   ├── microdot                    \u003c-- microdot library\n│   │   ├── __init__.py\n│   │   └── microdot.py\n│   ├── project                     \u003c-- project custom modules\n│   │   ├── connection.py\n│   │   ├── telemetry.py\n│   │   └── utility.py\n│   └── umqtt                       \u003c-- MicroPython umqtt library\n│       ├── robust.py\n│       └── simple.py\n└── server                          \u003c-- microdot server files\n    ├── assets\n    │   ├── bootstrap.min.css.gz\n    │   └── favicon.ico.gz\n    └── index.html\n```\n\n`micropython-default/src/micropython_default` is the main project directory.\n\nThe `env/secrets.py` is used to store credentials to connect to a WiFi network and to connect to the Pico, when in AP mode. The default secrets file contents are shown below:\n\n```python\nAP_SSID = None\nAP_PASSWORD = None\nWLAN_SSID = None\nWLAN_PASSWORD = None\n```\n\nExample updated secrets:\n\n```python\nAP_SSID = None\nAP_PASSWORD = None\nWLAN_SSID = \"MY_WIFI_SSID\"\nWLAN_PASSWORD = \"MY_WIFI_PASSWORD\"\n```\n\nThese values are dynamically imported/set using `dynamic_get_secret` and `dynamic_set_secret` in the `lib/project/utility.py` module. This functions facilitate secret variable imports like a python module, even after a secret value change.\n\nThe `lib` directory is used to host MicroPython packages locally to aid in development. This template uses the umqtt MicroPython library and the microdot framework, which is compatible with MicroPython. The `lib/project` directory is meant to store custom modules for your project.\n\nThe `server` directory holds assets and an `index.html` file, which creates a form served by the microdot server. This form is styled using bootstrap, in offline mode. Bootstrap is too big normally, but we demonstrate the realms of the possible using microdot to serve gzip-compressed bootstrap assets - useful for those wanting to know how to achieve this with such minimal resources on a microcontroller.\n\n\u003e [!TIP]  \n\u003e Detailed docstrings are included at the module and function/class level for this project.\n\n## Installation\n\n**uv** is used as the Python package manager. To install **uv** see the installation\nguide @ [uv documentation](https://docs.astral.sh/uv/getting-started/installation/).\n\nThe following command will sync the project dependencies and create a virtual environment:\n\n```bash\ncd \u003cproject directory\u003e\nuv sync\n```\n\nActivate the virtual environment created by uv with the following command:\n\n```bash\nsource .venv/bin/activate\n```\n\n## Build \u0026 distribute the template\n\n\u003e [!WARNING]  \n\u003e Make sure your Pico W device is connected and your virtual environment is activated.\n\nCheck your Pico's current filesystem with the following mpremote command:\n\n```bash\n(micropython-default) mpremote fs ls\n```\n\nOutput of `ls :` will indicate an empty system. The following command will clear the Pico filesystem (use caution):\n\n```bash\n(micropython-default) mpremote exec --no-follow \"import os, machine, rp2; os.umount('/'); bdev = rp2.Flash(); os.VfsLfs2.mkfs(bdev, progsize=256); vfs = os.VfsLfs2(bdev, progsize=256); os.mount(vfs, '/'); machine.reset()\"\n```\n\nWith the recent **picoproject** CLI dependency, you can also th command below, which will use mpreote in the background to format the device.\n\n```bash\n(micropython-default) CLI format\n```\n\n\nFrom the project root directory, the following command will recursively copy all files within the project\ndirectory to the Pico W filesystem:\n\n```bash\n$ (micropython-default) mpremote cp -r ./src/micropython_default/* :\ncp ./src/micropython_default/env :\ncp ./src/micropython_default/lib :\ncp ./src/micropython_default/main.py :  \ncp ./src/micropython_default/server :\n```\n\nYou can verify this with the following command:\n\n```bash\n(micropython-default) mpremote fs ls\n```\n\nA hard reset of the device and a connection to the device REPL, will allow you to view the application running with verbose\ndebug messages (set main.py `_VERBOSE` global variable to False to disable):\n\n```bash\n(micropython-default) mpremote reset\n```\n\nConnect to the device to view the verbose debug messages:\n\n```sh\n(micropython-default) mpremote\n```\n\nIf you have not set credentials in `env/secrets.py`, the application will detect a connection issue and initialise the Pico WLAN in AP mode and start a microdot server. You can connect to the Pico W WLAN, which will have an SSID like PICO-W-\u003cPICO_SERIAL_NUMBER\u003e e.g. 'PICO-W-E66161234567891B'.\n\nThe default password to connect to the Pico W will be the \u003cPICO_SERIAL_NUMBER\u003e in the SSID, unless you have set another value in `env/secrets.py` e.g. `AP_PASSWORD = \"my_password\"`.\n\n![WLAN](./docs/img/PICO_W_WLAN.png)\n\nYou can view the WLAN credentials form by navigating to `http://192.168.4.1:80` or the on the [GitHub page](https://andyrids.github.io/micropython-default/) for this project. On the Github page, the Device \u0026 MicroPython version details are unavailable as these are populated based on your Pico W details.\n\n![WLAN](./docs/img/PICO_W_FORM.png)\n\n\u003e [!WARNING]  \n\u003e Must be HTTP - i.e. `http://192.168.4.1:80/`\n\nExample output:\n\n```bash\n$ (micropython-default) mpremote\nConnected to MicroPython at /dev/ttyACM0\nUse Ctrl-] or Ctrl-x to exit this shell\nNETWORK INTERFACE ACTIVE - AP MODE\n\nWLAN INFO\n---------\nMODE: AP\nSTATUS: 3\nACTIVE: True\nCONNECTED: True\n\nASYNC TASK - GARBAGE COLLECTION\nENTERING MAIN LOOP\nASYNC TASK - GARBAGE COLLECTION\nCONNECTION ISSUE - STATUS: 3\nAFTER MICRODOT SERVER STARTUP:\n1. CONNECT TO PICO W WLAN\n2. NAVIGATE TO http://192.168.4.1:80\n3. ENTER YOUR WLAN SSID \u0026 PASSWORD\nASYNC TASK - MICRODOT SERVER STARTUP\nStarting async server on 0.0.0.0:80...\nASYNC TASK - GARBAGE COLLECTION\nASYNC TASK - GARBAGE COLLECTION\nASYNC TASK - GARBAGE COLLECTION\n```\n\nAfter the WLAN credentials form has been submitted and credentials prove to be correct:\n\n```bash\nPOST /connection 205\nASYNC TASK - MICRODOT SERVER SHUTDOWN\nRESETTING WLAN INTERFACE\nINITIALISE NETWORK WLAN INSTANCE\nSETTING WLAN MODE TO STA\nACTIVATE NETWORK INTERFACE\nACTIVATE NETWORK INTERFACE TIMEOUT - STA MODE\nCONNECTING TO SSID '**********'\nWAITING FOR WLAN CONNECTION\nWLAN STATUS: 1\nWLAN STATUS: 1\nWLAN STATUS: 1\nWLAN STATUS: 1\nWLAN STATUS: 2\nWLAN STATUS: 2\nWLAN STATUS: 3\nWLAN CONNECTION SUCCESSFUL - SSID: '**********'\n\nWLAN INFO\n---------\nMODE: STA\nSTATUS: 3\nACTIVE: True\nCONNECTED: True\n\nCONNECTION ISSUE RESOLVED\nASYNC TASK - GARBAGE COLLECTION\nGET /reset 200\nASYNC TASK - SYNCHRONISE NETWORK TIME\nSET NTPTIME SUCCESS - 2024-12-16 21:26:1\n```\n\nYou can interrupt the main application from the REPL you connected to with the last `mpremote` command, by pressing ctrl + c.\n\n```bash\nASYNC TASK - GARBAGE COLLECTION\nASYNC TASK - GARBAGE COLLECTION\nASYNCIO.RUN KeyboardInterrupt\nASYNCIO.RUN CLEANUP\nASYNCIO.RUN TERMINATE\n```\n\nAs the application is async, commands can still be issued to the device, including a hard reset or filesystem wipe using mpremote.\n\n## Sphinx Documentation\n\nTo build the documentation with sphinx, follow the commands below:\n\n```bash\n(micropython-default) cd docs\n(micropython-default) make html\n```\n\n## Credits\n\n1. Peter Hinch's excellent guide on [asyncio](https://github.com/peterhinch/micropython-async)\n2. [Microdot](https://microdot.readthedocs.io/en/latest/) minimalistic Python web framework inspired by Flask\n3. A detailed guide on [mpremote](https://wellys.com/posts/rp2040_mpremote/)\n4. My MicroPython dev environment using [WSL \u0026 Void Linux](https://github.com/andyrids/void-wsl-dev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyrids%2Fmicropython-default","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandyrids%2Fmicropython-default","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandyrids%2Fmicropython-default/lists"}