Repository navigation
Add a Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 page and document scan_networks()'s empty-scan retry - #13
Merged
ThomasFarstrike merged 3 commits intoOct 28, 2026
Conversation
The first ESP32-P4 board (MicroPythonOS 0.20.0, MicroPythonOS/MicroPythonOS#308) gets its own page: what works and what doesn't, installing with esptool, updating, the ESP32-C6 co-processor firmware, the channel 6-9 Wi-Fi issue and building from source. The page says early that only ESP32-P4 chip revisions v0.x and v1.x are supported. The esp32p4 image (0.20.0 and main) is built with ESP-IDF 5.5.1, whose ESP32-P4 maximum revision is fixed at v1.99, so the image does not start on a v3.x chip. esptool does not check this when it writes the full image, so the install steps check the revision before anything is erased. The C6 section is the note Thomas asked for when closing MicroPythonOS/MicroPythonOS#309: the C6 firmware should be updated. It says why (empty scans straight after a radio restart on the original firmware; the 5 s rescan from MicroPythonOS/MicroPythonOS#341 is on main, not in 0.20.0), how to read both ESP-Hosted versions with the hosted module, and that MicroPythonOS has no supported update path, pointing to Espressif's co-processor OTA example and Waveshare's FAQ instead. The commands inside the numbered install steps are indented code blocks: mkdocs.yml has no superfences, so fenced blocks inside list items would render as inline code. The page is listed in the nav after Supported Hardware, in the Getting Started overview, and in a new ESP32-P4 section of Supported Hardware. That entry says the board runs on chip revisions v0.x and v1.x (tested on v1.3), not v3.x, and lists the parts that are not supported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MicroPythonOS/MicroPythonOS#341 (merged 2026-10-21) gave scan_networks() an optional time_module argument. When WiFi is not connected, _scan_networks_raw() restarts the radio before it scans; if that first scan returns no networks at all, it now waits SCAN_RETRY_DELAY_S (5 s) and scans once more, without another restart. scan_networks() and connect() both go through it. main already lists time_module in scan_networks()'s signature and parameters (61bf2ef, merged with MicroPythonOS#12). This adds what it is used for: a paragraph on the retry, including that scan_networks() holds the busy flag for the extra time, and "used for the 5 s wait" on the time_module parameter. The paragraph names the board the wait was added for, the Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3, whose ESP32-C6 still ran its original firmware, and links to the C6 section of that board's page. A sentence after it says that release 0.20.0 has neither the retry nor the time_module argument. connect() gets two sentences: its scan restarts the radio and retries the same way, but connect() does not take the busy flag itself; auto_connect() holds it around the call. Its arguments did not change. The settings-screen example calls scan_networks() and attempt_connecting() from click handlers. A note under it says the screen doesn't respond until they return. While WiFi is not connected, scan_networks() takes at least 5 s longer if the first scan after the radio restart finds nothing. attempt_connecting() waits up to CONNECT_TIMEOUT_S (13 s by default, 30 s on the Waveshare P4). The note points to a background thread with update_ui_threadsafe_if_foreground(), as the built-in WiFi app does. The Desktop Mode table now says the mock scan takes 1 s and ignores time_module. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 page gets a Chip revision section near the top, and a bold line under the intro that points to it. It says that 0.20.0's esp32p4 image (ESP-IDF 5.5.1) runs only on chip revisions v0.x and v1.x, and that main builds it the same way. Boards with a v3.x chip, such as one user's v3.2 board, are not supported; MicroPythonOS/MicroPythonOS#344 tracks it. The section shows how to read the revision with esptool (the "Chip is" line in esptool v4, "Chip type:" in v5). It says that the warning about the ESP32-P4 having no chip ID, and esptool v5's note that chip_id is deprecated, are expected. It says to keep the factory firmware on a v3.x board, and that forcing the image makes the board reset in a loop. That user's v3.2 board did, with rst:0x10 (CHIP_LP_WDT_RESET), and started again after Waveshare's factory firmware was written back. Install step 2 used to say only that esptool does not check the revision. That holds for the release .bin: it starts with 0x2000 bytes of padding, so esptool cannot read an image header from it, in any version. But esptool does check files that start with a header, such as the .ota file or a separately built bootloader. Up to v5.4.0 it refuses any of them built for other revisions. From v5.5.0 (espressif/esptool d2c62467) it refuses only a bootloader at 0x2000 and prints a note for the others. Step 2 now says which files esptool refuses, and that --force does not help. The step uses chip_id instead of flash_id. The "What works" row links to the new section. The C6 section's #309 and #341 links are written in full, and the #341 bullet links to scan_networks() in the WifiService docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
This PR covers the two docs follow-ups from closing MicroPythonOS/MicroPythonOS#309 (MicroPythonOS/MicroPythonOS#309 (comment)):
time_moduleargument ofWifiService.scan_networks().mainalready lists it in the signature and the parameters (61bf2ef, merged with WifiService: document None return values while WiFi is busy #12). This PR adds what it is for: the 5 s rescan from WifiService: scan again 5 s after an empty scan that follows a radio restart (#309) MicroPythonOS#341.The board page
getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.mdis new. The Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 is the first ESP32-P4 board (MicroPythonOS 0.20.0, MicroPythonOS/MicroPythonOS#308).esp32p4image is built with ESP-IDF 5.5.1, which fixes the maximum at v1.99.mainbuilds it the same way. The board it was developed on has v1.3.esptool chip_idprintsChip is ESP32-P4 (revision v1.3)in esptool v4, and aChip type:line in v5. The page says that the "no chip ID" warning, and v5's note thatchip_idis deprecated, are expected.rst:0x10 (CHIP_LP_WDT_RESET), and started again once Waveshare's factory firmware was written back..binstarts with 0x2000 bytes of padding, so esptool cannot read an image header from it and writes it to any revision. Files that do start with a header, such as the.otafile or a bootloader built separately, are checked. Up to esptool v5.4.0, esptool refuses every such file whose revision range excludes the chip. From v5.5.0 (espressif/esptool d2c62467), it refuses only a bootloader at 0x2000 and prints a note for the others. The step says this, and that--forcedoes not help.--erase-allthe first time.updating.md, it names the.otafile and theesp32p4OTA slot offsets (0x20000, 0x420000).main, not in 0.20.0, and it could not be tested on that firmware.hosted.host_version()andhosted.coprocessor_version()../scripts/build_mpos.sh esp32p4) and a short summary of the board file.WifiService
frameworks/wifi-service.md:scan_networks(): a paragraph on the retry. While WiFi is not connected, the scan restarts the radio first. If that scan finds no networks at all, it waitsSCAN_RETRY_DELAY_S(5 s) and scans once more, without another restart. The busy flag is held for the extra time. There is no second scan while connected, or when the first scan finds networks. The paragraph names the board the wait was added for, whose C6 still ran its original firmware (older than ESP-Hosted 1.4.7 on the board tested). Thetime_moduleparameter now says it is used for that wait.time_moduleargument. On 0.20.0,scan_networks()takes onlynetwork_module.connect(): its scan restarts the radio and retries the same way. It does not take the busy flag itself;auto_connect()holds it around the call.scan_networks()andattempt_connecting()from click handlers. A note under it says the screen does not respond until they return. While WiFi is not connected,scan_networks()takes at least 5 s longer if the first scan after the radio restart finds nothing.attempt_connecting()waits up toCONNECT_TIMEOUT_S. The note points to a background thread withupdate_ui_threadsafe_if_foreground(), as the built-in WiFi app does.time_module.scan_networks().Where the page is linked
mkdocs.yml: Getting Started, after Supported Hardware ("Waveshare ESP32-P4 4.3-inch").getting-started/supported-hardware.md: a new "ESP32-P4 Microcontrollers" section. It says the board is supported on chip revisions v0.x and v1.x (tested on v1.3), not v3.x, and lists the parts that are not supported.getting-started/index.md: one line.Commits
Three commits on
main(28cfda9):time_moduleparameter, the line onmainis kept and extended.Sources
mainat ecfd48ea and the 0.20.0 release: the board file,c_mpos/src/hosted_module.c,wifi_service.py, the WiFi app, OSUpdate,scripts/build_mpos.shand thebuild-esp32p4CI job.esp32p4release image (MicroPythonOS_esp32p4_0.20.0.bin): the padding before 0x2000, the partition table, and the chip revision range (v0.0 to v1.99) in the bootloader and app headers.lvgl_micropythonpins onmain): the ESP32-P4Kconfig.hw_supportand the bootloader's revision check.write_flash's image check, theChip is/Chip type:lines,chip_id's "no chip ID" warning and v5's deprecation note), and commit d2c62467.updatesandinstallrepos.Not tested or observed by me, and worded that way on the page:
chip_id's extra messages. The "no chip ID" warning and v5's deprecation note are taken from esptool's source, not from a run on this board.coprocessor_version()on the original firmware. The page says it raisesOSErrorif the C6 does not answer, and that the original firmware did not answer the version request (Board support: Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 (esp32p4 target, MIPI-DSI display, touch, speaker) MicroPythonOS#308). The call itself was not run on that firmware.Formatting
The esptool commands inside the numbered install steps are indented code blocks, not fenced ones.
mkdocs.ymlhas nopymdownx.superfences, and without it a fenced block inside a list item renders as inline code. The other code blocks on the page are fenced as usual.One thing outside this repo
The web installer's ESP32-P4 option does not load:
/manifests/esp32/MicroPythonOS_esp32p4_0.20.x.json, which returns 404./manifests/esp32p4/MicroPythonOS_esp32p4_0.20.x.json, which returns 200.So the option's manifest path in MicroPythonOS/install's
index.htmllooks wrong. I have only checked the path, not the installer flashing a P4. Until it is fixed, the page says the option fails to load and uses esptool. The chip revision limit applies to the installer too, as its manifest points to the same 0.20.0 image.Not in this PR
Supported Hardware does not list the Waveshare ESP32-S3-Touch-LCD-1.54 or ESP32-S3-Touch-LCD-3.5 either, though both have board files on
main. I left them out to keep this PR to one board.Build
mkdocs build --strictpasses. Its output is the same as onmain(28cfda9): no warnings, and the same INFO lines about pages left out of the nav and old relative links. In the built page, all six code blocks render as blocks, the install steps stay one numbered list, and the in-page links and the links between the two pages resolve.🤖 Generated with Claude Code
With thanks to the scientists and engineers who did the hard, unglamorous work that got us here.