Jupyter Notebook

OmniPython runs in JupyterLab, Jupyter Notebook, and VS Code / Cursor notebooks through the JNDisplay backend. displaydev.auto.AutoDisplay detects the notebook (get_ipython()) and selects it.

Board config: board_configs/jndisplay/board_config.py. It exports the Jupyter display and host reader; appdev.App(board_config) registers the corresponding host device.

Setup

python3 -m venv .venv
.venv/bin/pip install pillow ipywidgets ipyevents jupyterlab
.venv/bin/jupyter lab --no-browser

Package

Purpose

Pillow

Image buffers for JNDisplay

ipywidgets

The interactive display widget

ipyevents

Mouse / keyboard on that widget

JupyterLab or Jupyter Notebook

Notebook UI

bin/jupyter.py is a CLI runner that generates a demo notebook, exports PYTHONPATH / MICROPYPATH, starts JupyterLab, and opens the demo:

jupyter.py calculator

The generated notebook is written to the current directory, named {script-stem}.ipynb for a file path or run-{slug}.ipynb for -m <module>. Open the URL printed in the terminal, select the .venv kernel (Kernel → Change Kernel), then run cells top to bottom.

Input

After a cell runs, an Image widget appears below the output — click that widget, not the cell chrome. JNDevices captures mouse (motion, buttons), wheel, and keyboard input on it via ipyevents, mapping them to the same event API as hardware. The widget must be focused to receive key events, and the notebook front end may consume some keys. Quit uses JNDisplay.quit_chord (Back / keys.K_AC_BACK); reassign it if the front end intercepts it.

Limitation: a mouse click arrives as MOUSEBUTTONDOWN / MOUSEMOTION / MOUSEBUTTONUP, which the app treats as touch. There is no encoder emulation — for that, use CPython desktop or PyScript.

See Displays → how displays expose input.

Async execution model

The kernel already runs an asyncio loop, so a blocking poll loop would starve it and never receive widget events. multimer uses that loop as its wake source in a notebook (multimer.report() in a cell says source=asyncio), so timers armed in one cell keep firing between cells and nothing is configured.

Subscribe callbacks and the app keeps itself alive — the kernel’s loop is the host loop (app.strategy == "ambient"), so no trailing app.run() is needed. For a custom async main(), use app.run_async(main), not asyncio.run(main()): in a notebook the latter raises RuntimeError: asyncio.run() cannot be called from a running event loop. On Jupyter, run_async schedules main as a background task and returns immediately (the cell finishes while the coroutine continues); on desktop or MCU with no loop running yet it blocks via asyncio.run.

Custom wait-for-touch loops should await multimer.asleep_ms(0) (or the loop’s own sleep) each iteration so the kernel can dispatch widget events between polls. See App and board config and multimer.

Stopping a running example

A task scheduled with run_async / create_task runs in the background on the kernel loop, so the cell returns immediately and the square Stop button will not interrupt it — use Kernel → Restart. An example that blocks in its own loop keeps the cell running, and Stop raises KeyboardInterrupt there; such examples should call multimer.sleep_ms(1) each iteration so Stop can take effect.

VS Code / Cursor

Interactive touch needs the ipywidgets JavaScript loaded in the notebook UI. If the widget area is blank (or VS Code shows an IPyWidget support popup), add to your workspace or user settings:

"jupyter.widgetScriptSources": ["jsdelivr.com", "unpkg.com"]

Reload the window after changing it, then restart the kernel.