# Known traps

All of these happened, all of them were measured. If something "does not work", look here first.

## Board

- **Display MISO is not wired** (CYD): reading back from the display returns `0xFF`. The controller id and MADCTL cannot be queried; orientation is set by eye (Settings → Display). Verified setting `rotation=0`, `bgr=False`; leave it.
- **SD only on VSPI (slot 3).** Slot 2 is the display's HSPI bus; a failed attempt leaves the host locked and kills the display. With no card `os.statvfs('/sd')` falls back to the root filesystem and gives a false positive.
- **SD cards of 64 GB and above come as exFAT**, and MicroPython only reads FAT. `sd_kontrol.py` diagnoses it and formats as FAT with `BICIMLE = True` (erases everything on the card).
- **Module name must not clash with a folder name.** `projects.py` + `/projects` clashed and MicroPython treated the folder as a package; hence the module is `store.py`.
- **Threads do not isolate.** There is a GIL; a project that never yields the CPU starves the panel. Even `sleep_ms(1)` is enough.
- **Normal mode + a wait inside a `def`:** MicroPython silently accepts `await` in a plain `def` and turns it into a generator; the body never runs. The pre-scan catches this and opens the project as T.
- **The ESP8266 pre-emptor cannot enter a blocking C call** (`uart.write`, big SPI); those are in the millisecond range.
- **`uart.write(512 bytes)` blocks for 44 ms** and trips the watchdog: 64-byte chunks with `sleep_ms(1)` in between.
- **Module cache:** modules a project `import`ed stayed in `sys.modules`; 6 KB never came back and fixes were invisible. `Job._run` now drops the modules the project brought in when it ends.

## PC and serial port

- **`mpremote` leaves the board at the REPL.** `fs cp` interrupts `main.py` with Ctrl-C and never restarts it; after every deploy the panel is down. Pass `--reset`.
- **Clone CH340 driver 3.9.2024.9** (Windows) fails to open the port at 38400 baud or above with `PermissionError(31, 'A device attached to the system is not functioning')`. Opening at 9600 and raising the speed works; patch `serial.Serial.open` through `sitecustomize.py`, or roll the driver back to 3.5 (2019).
- **CH340 wedge:** the port keeps emitting the same garbage byte (`0xE2`) and writes fail with `Write timeout`. It does not recover in software; unplug and replug the USB cable.
- **PowerShell BOM:** `Set-Content -Encoding utf8` adds a BOM and MicroPython says `NameError: name '' isn't defined`. Write with Python or an editor.
- **esptool baud trap:** `--baud 460800` leaves the stub at that speed and the next command cannot connect at 115200. Stay at 115200 for multi-step work.
- **Interrupted flash:** if the port drops the board stays in download mode; no need to hold the button again, just rerun `flash.py --koru`. If a reset still shows `boot:0x3 DOWNLOAD_BOOT`, BOOT is physically pressed.
- **The `txbuf=` parameter** returns `EPERM` on the ESP32 UART; pass only `rxbuf`.
- **First-boot format (ESP8266):** on an erased 4 MB flash the LittleFS format takes a few seconds; `mpremote` resets the board on every connect and restarts the format. Leave it alone ~10 s after flashing.

## Power

- **Unpowered USB hub:** when the display board starts WiFi the hub cannot supply the current and the board drops off USB together with its serial chip (the COM port vanishes within 1.5 s). Use a direct PC port or a powered hub.
- **ESP32 OLED from PC USB:** the 3.3 V rail falls to 1.63 V the moment WiFi starts, brownout loop. 2 × 1000 µF capacitors do not help (~2 ms of buffer). Fix: battery, powered hub or external 3.3 V.
- **Cable resistance:** at 300 mA a thin/long cable drops ~1 V and the regulator goes into dropout. A 3 A adapter does not rescue the cable.

## Network

- **A second HTTP server** drains lwIP buffers and internal DRAM through its second listening socket and freezes the panel. Use `cyd.rota`.
- **HTTPS through `requests` is `ENOMEM` in normal mode**, BLE is `EIO`. Both work in Solo mode.
- **A VPN on the PC** can cut off the local network: the board reports "connected" at its own IP while the PC cannot even ping the router. Turn the VPN off first.
- **A slow client** used to lock the panel while receiving a file: socket timeout 5 s and a heartbeat per chunk; with a client reading 512 B every 0.5 s, 50 s with 0 errors.

## Shadowing

A same-named `.py` on the filesystem overrides the frozen one (priority `.py` > `.mpy` > frozen). Upload a `server.py` and the RAM savings silently disappear. Always run the deploy tools with `--frozen` on frozen boards.