homeassistant_espscreen/docs/ELECROW.md

# Elecrow CrowPanel 7.0" — 800 × 480

The **Elecrow CrowPanel ESP32 HMI 7.0-inch** (product code **DIS08070H**, hardware V2.0 and V3.0) has a board file of
its own, next to the CYD's and the Guition's: an 800 × 480 IPS panel on the ESP32-S3's own RGB bus, **GT911
capacitive touch**, an **ESP32-S3-WROOM-1-N4R8** with 4 MB of flash and 8 MB of octal PSRAM, and a backlight on
GPIO 2. It is the Guition's kind of screen, a big RGB panel with capacitive touch, in a wider, landscape form: every
card, the camera images and album covers, the page swipe from the glass edge, the settings on the screen. Two things
differ in kind, and both are below: the **4 MB of flash** (the CYD's budget, not the Guition's 16 MB) and a panel
that is not square, so it **does not turn** (no Rotation entity).

Hardware source: [Elecrow's wiki](https://www.elecrow.com/wiki/esp32-display-702727-intelligent-touch-screen-wi-fi26ble-800480-hmi-display.html)
and the [ESPHome devices page for the CrowPanel 7.0"](https://github.com/esphome/esphome-devices/pull/1494), whose
panel timings, pins and pitfalls this board file follows. The **CrowPanel *Advance* 7.0"** is a different board with
other pins (ESPHome's `CROWPANEL-ADVANCE-7` model); this file is for the plain CrowPanel 7.0".

## Files

- `packages/boards/elecrow-crowpanel7.yaml`: the board file (hardware, the 800 × 480 sizes, the flash measures); the
  interface itself is `packages/core.yaml`, shared with both other boards (docs/PROFILES.md).
- `packages/elecrow.yaml`: what a screen builds from over GitHub; `elecrow-crowpanel7.yaml` in the root is the same for
  a build from a checkout; `installers/elecrow.yaml` the block for a hand-written ESPHome configuration.
- `components/smart_display/elecrow_usb_phy.h`: frees the USB pins for the touch I2C (below).
- `components/smart_display/partitions.py`: the partition table that makes the firmware fit (below).
- `tools/verify_gt911.py`: physical pixel check, as on the Guition; no resistive calibration.

Choose **Elecrow CrowPanel · 7 inch** under **New screen** in ESP Screens (app 0.2.93+). The Guition's own parts (the
Rotation choice) stay off for it; everything the Guition can show, it shows.

## Interface

Six tiles of **378 × 108 pixels** per page in two columns, the Guition's rows and fonts across a wider page: the
vertical sizes are the Guition's to the pixel, the tiles and the cards take the extra width. The top bar, the tile
labels, the alert card (560 wide, its camera picture 532 × 220), the colour and climate titles and the page keys are
sized for 800 px; the cards that are a share of the page (the setpoint card, the mode keys) simply widen. A camera
opens full screen at 800 × 480; ESP Screens serves the picture in that box (`camera_feed.BOXES['elecrow']`).

At 133 pixels an inch the Guition's 42 px icons are a shade larger on this panel than on the 4-inch (170 ppi), which
suits a screen that stands further away.

### Touch

The GT911 is polled every 20 ms over I2C at 400 kHz. The **V3.0** has a PCA9557 I/O expander (I2C 0x18) on the
GT911's reset (IO0) and interrupt (IO1) lines, and a unit tested here kept its GT911 in reset until something drove
them (`touchscreen is marked FAILED: Calibration error` in the log, firmware 0.2.79 to 0.2.81; 0.2.81 tried ESPHome's
own expander support, whose 2 ms reset pulse the chip ignored). `smart_display: elecrow_touch_reset` (firmware 0.2.82,
`components/smart_display/elecrow_touch_reset.h`) runs the sequence of Elecrow's V3.0 ESPHome example before the
driver looks for the chip: every expander pin an output and low (the reset held, the interrupt line low so the chip
takes address 0x5D), 20 ms, the reset released, 100 ms, the interrupt line back to an input. The log says `GT911 reset
through the PCA9557`. A V2.0 board without the expander boots its GT911 by the pull-up as before (the writes fail, the
log says so), and the driver tries 0x14 by itself when 0x5D does not answer, so no address override is ever needed.

The bus is scanned at boot. For a diagnosis, give the screen `logger: level: DEBUG` in its Override YAML (Screen
settings → Override YAML) and read its log: the scan lists 0x18 (the expander; the GT911 is still in reset at that
moment), and the driver logs `Switches ADDR: 0x5D`; a screen without a working bus lists nothing. Two actions of the
screen (firmware 0.2.83; Developer tools → Actions, or over the API) work at any time: `touch_probe` logs the PCA9557's
four registers and whether a GT911 answers at 0x5D or 0x14 (its product id, "911"); `touch_reset` runs Elecrow's
sequence with values of one's own (`config`, `low`, `high`, `hold_ms`, `wait_ms`, `final_config`; Elecrow's are
0, 0, 1, 20, 100, 2) and probes again.

**GPIO 19 and 20, the touch I2C, are the ESP32-S3's USB D- and D+.** The ROM leaves the USB PHY on those pads and
ESP-IDF's I2C driver cannot take them back: the bus reads as `I2C software timeout` and the touch never answers
(esphome/esphome#15356, ESPHome 2026.3+). `elecrow_usb_phy.h` lets the pads go, three times, because three things hand
them back (firmware 0.2.80): a static constructor before any component runs (after the ROM); the board's `BOOT_TOUCH`
hook after Wi-Fi started, because the Wi-Fi PHY library keeps the USB PHY on by default on an ESP32-S3
(`CONFIG_ESP_PHY_ENABLE_USB`, which the board file turns off as well); and a one-second watchdog that reads the pad bit
and releases the pads again when anything took them, logging `USB PHY took GPIO19/20 back; released again` once per
event, so the log says whether it ever had to. The code is behind the build flag `ESP_SCREENS_FREE_USB_PADS`, which
only this board file sets, because ESPHome includes every header of the component in every build and the Guition, an
ESP32-S3 too, keeps its USB. ESPHome's logger keeps the USB-Serial-JTAG secondary console on, so ESP-IDF's own
pad-release at startup (`clk.c`, only without that console) never runs here. The board's USB-C port is a CH340 on UART0, so flashing and the log are unaffected; the
`GPIO19 is used by the USB-Serial-JTAG interface` warnings at build time are expected.

### Rotation

A landscape panel with a layout 800 px wide: it does not turn. `ROTATION_SUPPORTED` is `false`, the settings page
shows no rotation row, and the app offers none for this board.

## Flash

The ESP32-S3-WROOM-1-**N4**R8 has **4 MB** of flash (the N4; 16 MB in the YAML boot-loops with no log). The firmware
is the Guition's, with camera images; with the Guition's fonts it is **2,028 KB**, and ESPHome's own partition table for
4 MB, two update slots of 1,792 KB with 448 KB kept for NVS, does not hold it. Three measures make it fit with room for
updates, all in the board file, measured with ESPHome 2026.9.0 (the add-on's):

| Measure | Saves | Where |
|---|---|---|
| Two update slots of **1,984 KB** and 64 KB of NVS instead of 448 KB (the preferences take a few KB; ESP-IDF's own two-slot example keeps 16 KB) | 192 KB more room a slot | `smart_display: partitions: 4mb_wide_slots`, `components/smart_display/partitions.py` |
| The four icon fonts (the 314 tile icons at 42, 26 and 18 px, the 31 big icons at 64 px) at **2 bits a pixel** instead of 4; the text fonts keep their 4 | 156 KB | `font:` in the board file (`!extend` on the core's fonts) |
| The TLS client only; nothing serves TLS | 7 KB | `sdkconfig_options` in the board file |

That is **1,865,456 bytes, 91.8 %** of a slot: within the CYD's rules (docs/RELEASING.md step 2), in the *tight* band,
and `tools/check.sh --firmware` applies the same budget to this board. Without camera images it is about 1,754 KB,
86 %: drop the `online_image`, `http_request` and `preview_camera` sections, the alert's picture frame and the
`camera_image_seed` image, and empty the camera hooks (`BOOT_CAMERA_HOOKS`, `BOARD_PAINT_FILL`, `CLOSE_CARDS_HOOK`,
`MAY_OPEN_EXTRA`, `TICK_HOOK`, `AWAY_EXTRA`, `ALERT_SHOW_HOOK`) as the CYD's board file has them. The icons at 4 bits
a pixel are the Guition's 156 KB back; they fit only without the camera images, and then at 94 %.

The partition table is part of the firmware and **never changes once a screen is flashed**: an update over Wi-Fi
writes into the other slot of the table the screen has, and only a USB install (ESP Screens' New screen, or ESPHome
Web with the factory image) lays the flash out anew. A screen flashed with this table keeps it through every update.

## Panel

ESPHome's `mipi_rgb` driver with the `RPI` model: the panel takes the pixels straight from the ESP32-S3's LCD
peripheral and needs no initialisation, so the timings are the whole configuration: 15 MHz pixel clock, inverted
(`pclk_inverted: true`, without it the picture tears), horizontal porches 40/48/13 and vertical 1/31/13, the 16 data
pins of Elecrow's schematic. The frame buffer is in PSRAM; LVGL draws in a buffer of 15 % of the screen, the same
number of pixels as the Guition's 25 % of 480 × 480.

## Checks

- `python3 tools/check_packages.py`, `esphome config elecrow-crowpanel7.yaml`, `tools/check.sh --firmware`.
- The touch test page and `tools/verify_gt911.py` for the corners; the ghost-touch filter at (0, 0) of the Guition's
  GT911 applies here too.
- `diagnostics/capture_ui.py` saves the LVGL render at 400 × 240 (half the panel) as a PNG; `ui_self_test` renders
  every card without touching a device.
- A build is not a flash, and a render is not a touch: the owner checks the picture and taps the corners.