CCYD StudioDocs

CYD Studio › Docs › Known traps

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 imported 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.

Last updated 2026-10-17 · This page as Markdown