From 323dcb770fd6611009025e6a2af2d80cc771ce82 Mon Sep 17 00:00:00 2001 From: Bitcoin3us <115934595+bitcoin3us@users.noreply.github.com> Date: Wed, 21 Oct 2026 21:36:58 +0100 Subject: [PATCH 1/3] getting-started: add a Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 page 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 --- docs/getting-started/index.md | 1 + docs/getting-started/supported-hardware.md | 4 + .../waveshare-esp32-p4-wifi6-touch-lcd-4-3.md | 126 ++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 132 insertions(+) create mode 100644 docs/getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index d808447..1fcbd1f 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -5,3 +5,4 @@ Get up and running with MicroPythonOS. This section covers installation and supp - [Running](running.md): Step-by-step guide to install and run MicroPythonOS. - [Updating](updating.md): How to update safely (and how not to lose your data). - [Supported Hardware](supported-hardware.md): Compatible devices and platforms. +- [Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3](waveshare-esp32-p4-wifi6-touch-lcd-4-3.md): Installing and using MicroPythonOS on the first ESP32-P4 board, and a note on its ESP32-C6 Wi-Fi firmware. diff --git a/docs/getting-started/supported-hardware.md b/docs/getting-started/supported-hardware.md index 64ac8e0..a988aa8 100644 --- a/docs/getting-started/supported-hardware.md +++ b/docs/getting-started/supported-hardware.md @@ -23,6 +23,10 @@ MicroPythonOS runs on a variety of platforms, from microcontrollers to desktops. - [SQUiXL](https://squixl.io): Fully Supported - [Waveshare ESP32-S3-Touch-LCD-2](https://www.waveshare.com/wiki/ESP32-S3-Touch-LCD-2): Fully Supported +## ESP32-P4 Microcontrollers + +- [Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3](https://docs.waveshare.com/ESP32-P4-WIFI6-Touch-LCD-4.3): Supported on ESP32-P4 chip revisions v0.x and v1.x (tested on v1.3), not v3.x. The microphones, TF card slot, camera, USB host and battery level are not supported. See [its page](waveshare-esp32-p4-wifi6-touch-lcd-4-3.md), including a note on its ESP32-C6 Wi-Fi firmware. + ## WebAssembly (Browser) - **Latest release**: [web.micropythonos.com](https://web.micropythonos.com/) diff --git a/docs/getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md b/docs/getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md new file mode 100644 index 0000000..aaa0305 --- /dev/null +++ b/docs/getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md @@ -0,0 +1,126 @@ +# Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 + +The [Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3](https://docs.waveshare.com/ESP32-P4-WIFI6-Touch-LCD-4.3) is the first ESP32-P4 board that MicroPythonOS supports, starting with release 0.20.0. It has a 4.3" 480x800 touch screen, 32 MB of flash and 32 MB of PSRAM. + +MicroPythonOS runs only on boards whose ESP32-P4 is chip revision v0.x or v1.x. The `esp32p4` image, in 0.20.0 and on the main branch, is built for revisions v0.0 to v1.99, and the board support was developed on has v1.3. The image does not start on a chip of revision v3.0 or later, so boards with such a chip are not supported. Waveshare's [FAQ](https://docs.waveshare.com/ESP32-P4-WIFI6-Touch-LCD-4.3/FAQ) calls v0.x and v1.x chips engineering samples, so newer boards may have a v3.x chip. Step 2 of [Installing](#installing) shows how to check yours. + +The ESP32-P4 has no radio of its own. Wi-Fi and Bluetooth come from a second chip on the board, an ESP32-C6, which runs its own firmware and talks to the ESP32-P4 over SDIO using Espressif's [ESP-Hosted](https://github.com/espressif/esp-hosted-mcu). This page calls it the C6. + +## What works and what doesn't + +| Part | Status | +|---|---| +| ESP32-P4 chip revision | v0.x and v1.x only. MicroPythonOS does not start on a chip of revision v3.0 or later. | +| Display | Works. The panel is portrait (480x800); MicroPythonOS shows its usual landscape UI at 800x480, rotated by the ESP32-P4's pixel processing accelerator (PPA). | +| Brightness | Works, with the brightness slider in the drawer. | +| Touch | Works (GT911). | +| Speaker | Works: ES8311 codec and the on-board amplifier, on the speaker connector. | +| Wi-Fi | Works, through the C6. Read [the C6 firmware](#the-c6-firmware) and [Wi-Fi on channels 6 to 9](#known-issue-wi-fi-on-channels-6-to-9). | +| OS updates | The update server has an entry for this board, so the OSUpdate app checks for new releases. Not tested yet: 0.20.0 is the board's first release, so there has been nothing newer to install. See [Updating](#updating). | +| Microphones | Not supported. They go through a separate ES7210 chip, which MicroPythonOS does not set up on this board. | +| TF (microSD) card slot | Not supported. The slot needs the ESP32-P4's internal LDO channel 4 switched on, which `machine.SDCard` cannot do. | +| Camera (MIPI-CSI) | Not supported. | +| USB host (USB OTG port) | Not supported. MicroPythonOS builds USB host support for the ESP32-S3 only. | +| Battery | The board has a connector for a lithium battery, but MicroPythonOS does not read the battery level on this board. | +| Bluetooth | Not tested with MicroPythonOS on this board. | + +## Installing + +The firmware for this board is the `esp32p4` build: the file `MicroPythonOS_esp32p4_.bin` on the [releases page](https://github.com/MicroPythonOS/MicroPythonOS/releases), first in 0.20.0. It is a full flash image, written at offset 0. + +The [web installer](https://install.micropythonos.com) lists an ESP32-P4 build, but that option currently fails to load. The steps below use [esptool](https://docs.espressif.com/projects/esptool/en/latest/esp32p4/). In the commands, `-b 921600` sets a faster serial speed than esptool's default. + +1. **Connect the board.** Use the USB-C port that Waveshare's documentation calls USB TO UART (power, programming and debugging). The other USB-C port is the USB OTG port. + +2. **Check the chip revision.** esptool prints it when it connects, in a line that ends with `ESP32-P4 (revision v1.3)`: + + python3 -m esptool --chip esp32p4 flash_id + + If the revision is v3.0 or later, stop here. MicroPythonOS will not start on this board, and the next steps would erase its factory firmware. esptool does not check this for you: it writes the full image to any revision. + +3. **Back up the factory firmware (optional).** The board comes with Waveshare's demo firmware. To be able to go back to it, save the whole 32 MB flash first: + + python3 -m esptool --chip esp32p4 -b 921600 read_flash 0 0x2000000 waveshare-p4-factory.bin + + To restore it later, write the file back at offset 0: `python3 -m esptool --chip esp32p4 -b 921600 write_flash 0 waveshare-p4-factory.bin`. + +4. **Write MicroPythonOS:** + + python3 -m esptool --chip esp32p4 -b 921600 write_flash --erase-all 0 MicroPythonOS_esp32p4_0.20.0.bin + + `--erase-all` clears the factory firmware's data, which uses a different partition layout. Leave it out when you reinstall over MicroPythonOS, as it erases your apps and settings. Even without it, reinstalling can cost you data: read [Updating](updating.md) first. + + esptool puts the board into download mode by itself. If it cannot connect, hold the BOOT button, press RESET, release BOOT and try again. + +5. **Start MicroPythonOS.** esptool resets the board when it is done. If the screen stays dark, press RESET. + +## Updating + +Use the OSUpdate app, as on the other boards. See [Updating](updating.md). This has not been tested on this board yet: 0.20.0 is its first release, so there has been no newer release to update to. + +For a manual offline update, also described there, use the `MicroPythonOS_esp32p4_.ota` file from the releases page. The two OTA slots of the `esp32p4` build are at `0x20000` and `0x420000`. + +## The C6 firmware + +The C6 firmware should be updated. On the board MicroPythonOS support was developed on, the C6 came with ESP-Hosted firmware older than version 1.4.7. MicroPythonOS's `esp32p4` build uses ESP-Hosted 2.7.0 on the ESP32-P4 side. + +Why it matters: + +- **Empty scans.** With the original C6 firmware, a Wi-Fi scan made straight after the radio was switched on found nothing, in about 1.2 s. A scan 5 s later found 26 networks. While it is not connected, MicroPythonOS switches the radio off and on before every scan. So after losing Wi-Fi, the board could miss its network and switch Wi-Fi off again ([MicroPythonOS#309](https://github.com/MicroPythonOS/MicroPythonOS/issues/309)). +- **After the update.** On the same board, after its C6 was updated to ESP-Hosted 2.7.0, none of 22 scans made straight after a radio restart came back empty. +- **A fallback, not on 0.20.0.** On the main branch, when the scan after a radio restart finds nothing, MicroPythonOS scans once more 5 s later ([MicroPythonOS#341](https://github.com/MicroPythonOS/MicroPythonOS/pull/341)). Release 0.20.0 does not have this. It could not be tested on the original C6 firmware, as no copy of that firmware was available. +- **Espressif's advice.** ESP-Hosted's own driver recommends upgrading a co-processor whose firmware is older than the host side's, to avoid timeouts in the requests between the two chips. + +### Check the version + +At the MicroPython REPL, for example with [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) on the USB TO UART port. Connect once MicroPythonOS has finished starting: mpremote interrupts a start-up that is still running, which leaves Wi-Fi off. Press RESET if that happens. + +```python +import hosted +hosted.host_version() # ESP-Hosted on the ESP32-P4: (2, 7, 0) +hosted.coprocessor_version() # ESP-Hosted on the C6 +``` + +`coprocessor_version()` returns a version such as `(2, 7, 0)`. It raises `OSError` if the C6 does not answer the version request. The original firmware did not answer it. MicroPythonOS was tested with ESP-Hosted 2.7.0 on both chips. + +### Update it + +MicroPythonOS has no supported way to update the C6 firmware: there is no prebuilt C6 image and no step-by-step guide. Flashing the wrong firmware can leave the board without Wi-Fi. + +What exists today: + +- **The `hosted` module.** It has the low-level calls that send a new firmware image to the C6 over the link between the two chips: `hosted.ota_begin()`, `hosted.ota_write(data)`, `hosted.ota_end()` and `hosted.ota_activate()`. The original firmware switches to the new image at `ota_end()`; `ota_activate()` is for ESP-Hosted 2.x. The C6 on the board MicroPythonOS was developed on was updated to ESP-Hosted 2.7.0 this way, with an image built from Espressif's ESP-Hosted co-processor sources for the ESP32-C6. +- **Espressif's example.** ESP-Hosted's [co-processor OTA example](https://github.com/espressif/esp-hosted-mcu/tree/main/examples/ota/coprocessor_ota) shows the same kind of update, driven from the host chip. +- **Waveshare's FAQ.** The board's [FAQ](https://docs.waveshare.com/ESP32-P4-WIFI6-Touch-LCD-4.3/FAQ) ("How to flash firmware onto the ESP32-C6?") describes flashing the C6 directly through its own UART pins, with both chips in download mode. Waveshare warns that the firmware has to be compatible. + +## Known issue: Wi-Fi on channels 6 to 9 + +On the board MicroPythonOS support was developed on, the C6 joins a network on 2.4 GHz channels 6 to 9 slowly or not at all. With a test access point 1 m away: + +- channels 1 and 11 joined in 3 to 5 s; +- channel 6 joined in 6 of 12 attempts, after 14 to 30 s; +- channels 7 to 9 joined in none of 11 attempts on one day; 7 and 8 had each joined once on another day. + +Results varied between sessions. Channel 6 also fails with Waveshare's own ESP-IDF Wi-Fi example and with plain ESP-IDF, so it is not specific to MicroPythonOS. It failed with the original C6 firmware and still fails with the updated one. Another user reported the same problem on the ESP32-P4-WIFI6-Touch-LCD-3.4C. The cause is not known. It is open as [waveshareteam/ESP32-P4-WIFI6-Touch-LCD-4.3#7](https://github.com/waveshareteam/ESP32-P4-WIFI6-Touch-LCD-4.3/issues/7). + +MicroPythonOS gives this board 30 s to join a network instead of the usual 13 s (`WifiService.CONNECT_TIMEOUT_S`), so a slow join on channel 6 can still succeed. + +If your board does not connect, or keeps losing Wi-Fi, and your router's 2.4 GHz network is on channel 6, 7, 8 or 9, set the router to channel 1 or 11. + +## Building from source + +```bash +./scripts/build_mpos.sh esp32p4 +``` + +This builds MicroPython's `ESP32_GENERIC_P4` board with the `C6_WIFI` variant, for 32 MB of flash with two 4 MiB app partitions. The full flash image is `lvgl_micropython/build/lvgl_micropy_ESP32_GENERIC_P4-C6_WIFI-32.bin`, and the app-only image (for the OTA slots) is `lvgl_micropython/lib/micropython/ports/esp32/build-ESP32_GENERIC_P4-C6_WIFI/micropython.bin`. See [OS Development](../os-development/index.md) for the toolchain. + +## How MicroPythonOS drives the board + +The board file is [`waveshare_esp32_p4_wifi6_touch_lcd_4_3.py`](https://github.com/MicroPythonOS/MicroPythonOS/blob/main/internal_filesystem/lib/mpos/board/waveshare_esp32_p4_wifi6_touch_lcd_4_3.py). MicroPythonOS recognises the board by its GT911 touch controller, at I2C address 0x5D or 0x14 on SDA 7 / SCL 8. + +- **Display:** ST7701 panel over 2-lane MIPI-DSI (`lcd_bus.DSIBus`) at 500 Mbps per lane, RGB565, with the frame buffers in PSRAM. `LCD_ROTATION = 270` shows the landscape UI upright; 90 is upside down and 0 is the panel's native portrait. +- **Backlight:** GPIO 26, PWM, active low. +- **Touch:** GT911 on I2C (SDA 7, SCL 8). It is polled, as its reset and interrupt lines are not connected to the ESP32-P4. +- **Speaker:** ES8311 codec at I2C address 0x18; I2S MCLK 13, BCLK 12, LRCK 10, data out 9; amplifier enable on GPIO 53. The output stays open for 30 s after a clip, so clips played back to back do not click. +- **Wi-Fi:** the C6, over SDIO (ESP-Hosted). The board file sets `WifiService.CONNECT_TIMEOUT_S = 30`. diff --git a/mkdocs.yml b/mkdocs.yml index 710e944..921d4a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,7 @@ nav: - Running: getting-started/running.md - Updating: getting-started/updating.md - Supported Hardware: getting-started/supported-hardware.md + - Waveshare ESP32-P4 4.3-inch: getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md - Apps: - Overview: apps/index.md - Built-in Apps: apps/built-in-apps.md From 05cb487b3538361fdeebb7b1317fc6f85bee67d9 Mon Sep 17 00:00:00 2001 From: Bitcoin3us <115934595+bitcoin3us@users.noreply.github.com> Date: Wed, 21 Oct 2026 21:27:18 +0100 Subject: [PATCH 2/3] wifi-service: document scan_networks()'s empty-scan retry 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/docs#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 --- docs/frameworks/wifi-service.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/frameworks/wifi-service.md b/docs/frameworks/wifi-service.md index 196b2bb..704bce4 100644 --- a/docs/frameworks/wifi-service.md +++ b/docs/frameworks/wifi-service.md @@ -170,6 +170,8 @@ class WifiSettingsActivity(Activity): self.update_status() ``` +`on_scan()` calls `scan_networks()` from a click handler, so the screen doesn't respond until the scan returns. While WiFi is not connected, `scan_networks()` takes at least 5 s longer if the first scan after the radio restart finds nothing (see [Scanning Functions](#scanning-functions)). The same applies to `attempt_connecting()` in `on_network_selected()`, which waits up to `WifiService.CONNECT_TIMEOUT_S` seconds for the connection (13 s by default, 30 s on the Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3). To keep the screen responsive, scan and connect in a background thread and update the screen with [`update_ui_threadsafe_if_foreground()`](../apps/app-lifecycle.md#thread-safe-ui-updates), as the built-in WiFi app does. + ### Background Auto-Connect ```python @@ -237,7 +239,7 @@ ConnectivityManager's periodic reconnect is skipped while the flag is held, so i #### `WifiService.connect(network_module=None, time_module=None)` -Scan for available networks and connect to the first saved network found. +Scan for available networks and connect to the first saved network found. Before it scans, it restarts the radio if WiFi is not connected, and scans once more after 5 s if that scan comes back empty, as [`scan_networks()`](#scanning-functions) does. Unlike `scan_networks()`, it does not take the [busy flag](#busy-flag) itself. `auto_connect()` holds it while it calls `connect()`. **Parameters:** - `network_module` - Network module for dependency injection (testing) @@ -290,9 +292,13 @@ Check if WiFi is currently connected. Returns `True` for hotspot mode when AP is Scan for available WiFi networks. Holds the [busy flag](#busy-flag) while it runs. +When WiFi is not connected, it restarts the radio before scanning. If the scan straight after that restart returns no networks at all, it waits 5 s (`WifiService.SCAN_RETRY_DELAY_S`), scans once more without another restart, and returns that result. So when that scan comes back empty while disconnected, the call takes 5 s longer plus the time of the second scan, and holds the busy flag throughout. There is no second scan while connected, or when the first scan finds networks. The wait was added for the [Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3](../getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md#the-c6-firmware), whose ESP32-C6 still ran its original firmware (older than ESP-Hosted 1.4.7 on the board tested): there, the first scan after a restart found nothing although networks were in range, and a scan 5 s later found them. + +Release 0.20.0 does not have this retry or the `time_module` argument. + **Parameters:** - `network_module` - Network module for dependency injection (testing) -- `time_module` - Time module for dependency injection (testing) +- `time_module` - Time module for dependency injection (testing), used for the 5 s wait **Returns:** - `list` - SSIDs found (empty if none were found) @@ -349,7 +355,7 @@ On desktop (Linux/macOS), WifiService provides simulated behavior for testing: | Method | Desktop Behavior | |--------|------------------| | `is_connected()` | Returns `True` unless WiFi is busy | -| `scan_networks()` | Returns mock SSIDs (ignores the busy flag) | +| `scan_networks()` | Returns mock SSIDs after 1 s (ignores the busy flag and `time_module`) | | `attempt_connecting()` | Simulates 2-second connection delay, succeeds unless WiFi is busy | | `get_current_ssid()` | Returns simulated connected SSID | | `disconnect()` | Prints message, no-op | From 0155e808614c533e4b22b8a9024f330215d05b3e Mon Sep 17 00:00:00 2001 From: Bitcoin3us <115934595+bitcoin3us@users.noreply.github.com> Date: Mon, 26 Oct 2026 15:22:19 +0000 Subject: [PATCH 3/3] getting-started: P4 page: chip revision section, esptool check 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 --- .../waveshare-esp32-p4-wifi6-touch-lcd-4-3.md | 32 +++++++++++++++---- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md b/docs/getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md index aaa0305..fb1c5eb 100644 --- a/docs/getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md +++ b/docs/getting-started/waveshare-esp32-p4-wifi6-touch-lcd-4-3.md @@ -2,15 +2,31 @@ The [Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3](https://docs.waveshare.com/ESP32-P4-WIFI6-Touch-LCD-4.3) is the first ESP32-P4 board that MicroPythonOS supports, starting with release 0.20.0. It has a 4.3" 480x800 touch screen, 32 MB of flash and 32 MB of PSRAM. -MicroPythonOS runs only on boards whose ESP32-P4 is chip revision v0.x or v1.x. The `esp32p4` image, in 0.20.0 and on the main branch, is built for revisions v0.0 to v1.99, and the board support was developed on has v1.3. The image does not start on a chip of revision v3.0 or later, so boards with such a chip are not supported. Waveshare's [FAQ](https://docs.waveshare.com/ESP32-P4-WIFI6-Touch-LCD-4.3/FAQ) calls v0.x and v1.x chips engineering samples, so newer boards may have a v3.x chip. Step 2 of [Installing](#installing) shows how to check yours. +**Check the chip revision before you install.** MicroPythonOS runs only on ESP32-P4 chip revisions v0.x and v1.x. Newer boards can have a v3.x chip, which MicroPythonOS does not support. See [Chip revision](#chip-revision). The ESP32-P4 has no radio of its own. Wi-Fi and Bluetooth come from a second chip on the board, an ESP32-C6, which runs its own firmware and talks to the ESP32-P4 over SDIO using Espressif's [ESP-Hosted](https://github.com/espressif/esp-hosted-mcu). This page calls it the C6. +## Chip revision + +MicroPythonOS 0.20.0 runs only on an ESP32-P4 of chip revision v0.x or v1.x. Its `esp32p4` image is built with ESP-IDF 5.5.1, which supports revisions v0.0 to v1.99. The main branch builds it the same way. The board MicroPythonOS support was developed on has revision v1.3. + +Boards with a v3.x chip are not supported. Waveshare's [FAQ](https://docs.waveshare.com/ESP32-P4-WIFI6-Touch-LCD-4.3/FAQ) calls v0.x and v1.x chips engineering samples, and one user's board of this model has a v3.2 chip. Espressif's [chip revision v3.x guide](https://documentation.espressif.com/esp32-p4-chip-revision-v3.x_user_guide_en.html) says that v1.x and v3.x chips cannot share the same firmware image, and that v3.x needs ESP-IDF 5.5.3 or later. Support for v3.x is tracked in [MicroPythonOS/MicroPythonOS#344](https://github.com/MicroPythonOS/MicroPythonOS/issues/344). + +To check your board, connect it as in step 1 of [Installing](#installing) and run: + +```bash +python3 -m esptool --chip esp32p4 chip_id +``` + +esptool prints the revision when it connects. esptool v4 prints `Chip is ESP32-P4 (revision v1.3)`. esptool v5 prints a `Chip type:` line that ends with `ESP32-P4 (revision v1.3)`. esptool then warns that the ESP32-P4 has no chip ID and prints its MAC address instead. esptool v5 also notes that `chip_id` is deprecated. Both messages are expected. + +If your board has a v3.x chip, keep Waveshare's factory firmware on it. Do not get past the revision limit with esptool's `--force`, or by raising the limit when you build MicroPythonOS. The image is then written, but the board restarts over and over and MicroPythonOS never starts. A v3.2 board flashed this way reset in a loop with `rst:0x10 (CHIP_LP_WDT_RESET)`. Writing Waveshare's factory firmware back made it work again. + ## What works and what doesn't | Part | Status | |---|---| -| ESP32-P4 chip revision | v0.x and v1.x only. MicroPythonOS does not start on a chip of revision v3.0 or later. | +| ESP32-P4 chip revision | v0.x and v1.x only. v3.x is not supported. See [Chip revision](#chip-revision). | | Display | Works. The panel is portrait (480x800); MicroPythonOS shows its usual landscape UI at 800x480, rotated by the ESP32-P4's pixel processing accelerator (PPA). | | Brightness | Works, with the brightness slider in the drawer. | | Touch | Works (GT911). | @@ -32,11 +48,13 @@ The [web installer](https://install.micropythonos.com) lists an ESP32-P4 build, 1. **Connect the board.** Use the USB-C port that Waveshare's documentation calls USB TO UART (power, programming and debugging). The other USB-C port is the USB OTG port. -2. **Check the chip revision.** esptool prints it when it connects, in a line that ends with `ESP32-P4 (revision v1.3)`: +2. **Check the chip revision**, as described in [Chip revision](#chip-revision): + + python3 -m esptool --chip esp32p4 chip_id - python3 -m esptool --chip esp32p4 flash_id + If the revision is v3.0 or later, stop here. MicroPythonOS will not start on this board, and the next steps would erase its factory firmware. - If the revision is v3.0 or later, stop here. MicroPythonOS will not start on this board, and the next steps would erase its factory firmware. esptool does not check this for you: it writes the full image to any revision. + Do not count on esptool to stop you. The release `.bin` starts with padding, not with an image header, so esptool writes it without checking the revision. esptool checks only files that start with an image header, such as the `.ota` file or a bootloader you built yourself. Up to v5.4.0, it refuses any such file built for other revisions. From v5.5.0, it refuses only a bootloader written at offset 0x2000. Either way, `--force` does not help: the image is written, but the board does not start. 3. **Back up the factory firmware (optional).** The board comes with Waveshare's demo firmware. To be able to go back to it, save the whole 32 MB flash first: @@ -66,9 +84,9 @@ The C6 firmware should be updated. On the board MicroPythonOS support was develo Why it matters: -- **Empty scans.** With the original C6 firmware, a Wi-Fi scan made straight after the radio was switched on found nothing, in about 1.2 s. A scan 5 s later found 26 networks. While it is not connected, MicroPythonOS switches the radio off and on before every scan. So after losing Wi-Fi, the board could miss its network and switch Wi-Fi off again ([MicroPythonOS#309](https://github.com/MicroPythonOS/MicroPythonOS/issues/309)). +- **Empty scans.** With the original C6 firmware, a Wi-Fi scan made straight after the radio was switched on found nothing, in about 1.2 s. A scan 5 s later found 26 networks. While it is not connected, MicroPythonOS switches the radio off and on before every scan. So after losing Wi-Fi, the board could miss its network and switch Wi-Fi off again ([MicroPythonOS/MicroPythonOS#309](https://github.com/MicroPythonOS/MicroPythonOS/issues/309)). - **After the update.** On the same board, after its C6 was updated to ESP-Hosted 2.7.0, none of 22 scans made straight after a radio restart came back empty. -- **A fallback, not on 0.20.0.** On the main branch, when the scan after a radio restart finds nothing, MicroPythonOS scans once more 5 s later ([MicroPythonOS#341](https://github.com/MicroPythonOS/MicroPythonOS/pull/341)). Release 0.20.0 does not have this. It could not be tested on the original C6 firmware, as no copy of that firmware was available. +- **A fallback, not on 0.20.0.** On the main branch, when the scan after a radio restart finds nothing, MicroPythonOS scans once more 5 s later ([MicroPythonOS/MicroPythonOS#341](https://github.com/MicroPythonOS/MicroPythonOS/pull/341); see [`WifiService.scan_networks()`](../frameworks/wifi-service.md#scanning-functions)). Release 0.20.0 does not have this. It could not be tested on the original C6 firmware, as no copy of that firmware was available. - **Espressif's advice.** ESP-Hosted's own driver recommends upgrading a co-processor whose firmware is older than the host side's, to avoid timeouts in the requests between the two chips. ### Check the version