Troubleshooting

Product-level problems when installing, importing, or running PyDevices. Harness- and example-specific issues are covered in pydevices-examples/tools/README.md.

Import errors

ModuleNotFoundError: No module named 'displaydev'

The packages are not on sys.path.

  • Source checkout: set PYTHONPATH / MICROPYPATH to .:lib:utils before running — see Install.

  • Device: install via MIP into /lib.

ModuleNotFoundError: No module named 'board_config'

There is no board_config.py for your hardware. Install a board config package or copy one into lib/:

import mip
mip.install("github:PyDevices/omnipython/board_configs/sdldisplay")  # desktop SDL2

Install failures

mip network or SSL errors on device

Use mpremote mip install from your PC, or copy files with mpremote cp. Check Wi-Fi on the board for OTA installs.

ImportError: No module named 'framebuf' on CircuitPython

CircuitPython has no MicroPython-compatible framebuf. Install the shim from pygraphics (lib/pygraphics/framebuf.py; MIP package pygraphics, PyPI omnipython-pygraphics).

Display issues

Blank window on desktop (CPython)

  1. Confirm the SDL2 system libraries are installed — see Install.

  2. Try PGDisplay (PyGame) instead of SDL2.

  3. Run a minimal draw script; a window should appear immediately.

Wrong colors or garbled pixels on an MCU

  1. Verify the correct board config for your wiring.

  2. Check requires_byteswap / BusDisplay.disable_auto_byteswap() (defined in displaydev).

  3. Confirm the SPI / I80 pins match your schematic.

Touch coordinates wrong or inverted

The touch driver’s rotation must match the display’s. Set display.rotation; it passes the value on to the app’s touch device, so check that your touch_rotation_table suits the panel. See touch-drivers.md.

WSLg: square artifact and drag lag on touchscreens

Symptom: on a touchscreen under Ubuntu/WSLg, a long press shows a small square popup at the touch point, and dragging arrives in bursts rather than smoothly. Mouse clicks and drags never show the square and are not laggy. This reproduces identically under micropython, CircuitPython, and CPython, with either SDLDisplay or PGDisplay.

Cause: not a OmniPython bug. WSLg forwards touch from the Windows host over the RDP Input Extension Protocol (MS-RDPEI), which negotiates CS_READY_FLAGS_SHOW_TOUCH_VISUALS and applies Windows’ legacy “press and hold to right-click” gesture disambiguation. The square is that gesture’s touch-visual feedback; the hold-to-disambiguate delay is the drag lag. This happens before the event reaches X11 or the app. Confirmed environmental by reproducing the identical behavior in mousepad (an unrelated GTK app) in the same WSLg session; disabling Windows’ Settings → Bluetooth & devices → Touch → “Press and hold for right-click” does not remove it, consistent with the gesture being applied at the RDP/WSLg layer.

Fix: none from application code — OmniPython’s SDL2 / PyGame event handling already treats touch and mouse identically. Native Windows builds (micropython.exe, python.exe) are unaffected because they receive touch directly from the Windows touch stack; native (non-WSL) Linux is unaffected too. Prefer mouse input, or native Windows/Linux, for latency-sensitive touch testing.

Slow or uneven replies over Wi-Fi

If a board answers each request late (pictures, REPL lines or pings take hundreds of milliseconds or several seconds), Wi-Fi power saving is the usual cause. Turn it off with wifi.radio.power_management = wifi.PowerManagement.NONE; see Slow replies: turn off power saving. Check the signal strength too: below about -75 dBm, moving the board helps more than any code change.

Slow start or audio dropouts on MicroPython

If a program starts slowly or its sound drops out in a regular rhythm, look for these two habits in code that runs often or reads big files. Both cost little on CPython. On MicroPython they turn into a system call for each byte or each folder, and that gets expensive when the code sits on a slow drive, such as a network share or a WSL folder opened from Windows.

Import struct, time, os and similar modules at the top of the file, not inside a function. MicroPython lets a file replace these built-ins, so every import struct searches each folder on sys.path first, even after the first one. With four folders on a WSL drive, each import took about 9 ms on micropython.exe, and more while audio was playing. A status call that did this four times, twice a second, stalled the audio timer long enough to hear.

import struct


def dropped(status):
    return struct.unpack_from("<Q", status, 80)[0]

Read a whole file at once when you can. for line in file and readline() read one byte per system call. On micropython.exe, a 52 KB file took:

Where the file is

for line in file

file.read()

WSL drive

15.6 s

86 ms

Local disk

223 ms

3 ms

If the file is too big for memory, use file.readinto() with a buffer and split the lines yourself.

Still stuck?

Open an issue on the repository that owns the component, or ask in OmniPython Discussions. Include board / OS, MicroPython or CPython version, the board_config path, and a minimal reproduction script.