|
| 1 | +# Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3 |
| 2 | + |
| 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. |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +## What works and what doesn't |
| 10 | + |
| 11 | +| Part | Status | |
| 12 | +|---|---| |
| 13 | +| ESP32-P4 chip revision | v0.x and v1.x only. MicroPythonOS does not start on a chip of revision v3.0 or later. | |
| 14 | +| 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). | |
| 15 | +| Brightness | Works, with the brightness slider in the drawer. | |
| 16 | +| Touch | Works (GT911). | |
| 17 | +| Speaker | Works: ES8311 codec and the on-board amplifier, on the speaker connector. | |
| 18 | +| 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). | |
| 19 | +| 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). | |
| 20 | +| Microphones | Not supported. They go through a separate ES7210 chip, which MicroPythonOS does not set up on this board. | |
| 21 | +| TF (microSD) card slot | Not supported. The slot needs the ESP32-P4's internal LDO channel 4 switched on, which `machine.SDCard` cannot do. | |
| 22 | +| Camera (MIPI-CSI) | Not supported. | |
| 23 | +| USB host (USB OTG port) | Not supported. MicroPythonOS builds USB host support for the ESP32-S3 only. | |
| 24 | +| Battery | The board has a connector for a lithium battery, but MicroPythonOS does not read the battery level on this board. | |
| 25 | +| Bluetooth | Not tested with MicroPythonOS on this board. | |
| 26 | + |
| 27 | +## Installing |
| 28 | + |
| 29 | +The firmware for this board is the `esp32p4` build: the file `MicroPythonOS_esp32p4_<version>.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. |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +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. |
| 34 | + |
| 35 | +2. **Check the chip revision.** esptool prints it when it connects, in a line that ends with `ESP32-P4 (revision v1.3)`: |
| 36 | + |
| 37 | + python3 -m esptool --chip esp32p4 flash_id |
| 38 | + |
| 39 | + 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. |
| 40 | + |
| 41 | +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: |
| 42 | + |
| 43 | + python3 -m esptool --chip esp32p4 -b 921600 read_flash 0 0x2000000 waveshare-p4-factory.bin |
| 44 | + |
| 45 | + 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`. |
| 46 | + |
| 47 | +4. **Write MicroPythonOS:** |
| 48 | + |
| 49 | + python3 -m esptool --chip esp32p4 -b 921600 write_flash --erase-all 0 MicroPythonOS_esp32p4_0.20.0.bin |
| 50 | + |
| 51 | + `--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. |
| 52 | + |
| 53 | + esptool puts the board into download mode by itself. If it cannot connect, hold the BOOT button, press RESET, release BOOT and try again. |
| 54 | + |
| 55 | +5. **Start MicroPythonOS.** esptool resets the board when it is done. If the screen stays dark, press RESET. |
| 56 | + |
| 57 | +## Updating |
| 58 | + |
| 59 | +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. |
| 60 | + |
| 61 | +For a manual offline update, also described there, use the `MicroPythonOS_esp32p4_<version>.ota` file from the releases page. The two OTA slots of the `esp32p4` build are at `0x20000` and `0x420000`. |
| 62 | + |
| 63 | +## The C6 firmware |
| 64 | + |
| 65 | +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. |
| 66 | + |
| 67 | +Why it matters: |
| 68 | + |
| 69 | +- **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)). |
| 70 | +- **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. |
| 71 | +- **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. |
| 72 | +- **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. |
| 73 | + |
| 74 | +### Check the version |
| 75 | + |
| 76 | +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. |
| 77 | + |
| 78 | +```python |
| 79 | +import hosted |
| 80 | +hosted.host_version() # ESP-Hosted on the ESP32-P4: (2, 7, 0) |
| 81 | +hosted.coprocessor_version() # ESP-Hosted on the C6 |
| 82 | +``` |
| 83 | + |
| 84 | +`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. |
| 85 | + |
| 86 | +### Update it |
| 87 | + |
| 88 | +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. |
| 89 | + |
| 90 | +What exists today: |
| 91 | + |
| 92 | +- **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. |
| 93 | +- **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. |
| 94 | +- **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. |
| 95 | + |
| 96 | +## Known issue: Wi-Fi on channels 6 to 9 |
| 97 | + |
| 98 | +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: |
| 99 | + |
| 100 | +- channels 1 and 11 joined in 3 to 5 s; |
| 101 | +- channel 6 joined in 6 of 12 attempts, after 14 to 30 s; |
| 102 | +- channels 7 to 9 joined in none of 11 attempts on one day; 7 and 8 had each joined once on another day. |
| 103 | + |
| 104 | +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). |
| 105 | + |
| 106 | +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. |
| 107 | + |
| 108 | +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. |
| 109 | + |
| 110 | +## Building from source |
| 111 | + |
| 112 | +```bash |
| 113 | +./scripts/build_mpos.sh esp32p4 |
| 114 | +``` |
| 115 | + |
| 116 | +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. |
| 117 | + |
| 118 | +## How MicroPythonOS drives the board |
| 119 | + |
| 120 | +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. |
| 121 | + |
| 122 | +- **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. |
| 123 | +- **Backlight:** GPIO 26, PWM, active low. |
| 124 | +- **Touch:** GT911 on I2C (SDA 7, SCL 8). It is polled, as its reset and interrupt lines are not connected to the ESP32-P4. |
| 125 | +- **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. |
| 126 | +- **Wi-Fi:** the C6, over SDIO (ESP-Hosted). The board file sets `WifiService.CONNECT_TIMEOUT_S = 30`. |
0 commit comments