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/MICROPYPATHto.:lib:utilsbefore 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)
Confirm the SDL2 system libraries are installed — see Install.
Try
PGDisplay(PyGame) instead of SDL2.Run a minimal draw script; a window should appear immediately.
Wrong colors or garbled pixels on an MCU
Verify the correct board config for your wiring.
Check
requires_byteswap/BusDisplay.disable_auto_byteswap()(defined indisplaydev).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 |
|
|
|---|---|---|
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.