Step by step
Run it yourself
About ten minutes from nothing to a live panel.
Just want to try it? Open DeskDot in your browser, nothing to install. Run it yourself for the features that need your computer (now playing, screen mirror, system stats, phone multiplayer, MCP) and to keep the panel going 24/7.
-
Get the prerequisites
- uv, the Python manager. It installs Python 3.13 for you; your system Python is untouched.
- Git, and Node.js 20+ to build the studio once (and for studio development).
- A computer with Bluetooth LE within a few metres of the panel. No panel yet? You can still do everything up to step 5.
- Close the iDotMatrix phone app. The panel accepts one Bluetooth connection at a time.
install uv (PowerShell)PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"install uv$ curl -LsSf https://astral.sh/uv/install.sh | sh -
Clone the repo
$ git clone https://github.com/shivpatel2468/idotmatrix.git deskdot $ cd deskdot
-
Install the engine and the MCP server
One command installs Python 3.13 and every dependency into a local
.venv.$ uv sync --extra mcp -
Build the studio once
The engine serves the built studio from
web/dist. You only need Node again if you work on the studio itself.$ cd web $ npm ci $ npm run build $ cd ..
Hacking on the UI?
npm run devinweb/gives hot reload on:5173, proxied to the engine. -
Try it on the simulator
Everything runs against a simulated panel: every app, every game, the studio and the MCP server.
$ uv run deskdot serve --simThen open
http://127.0.0.1:8765. Pick an app, change a setting, press ▶ Play on a game. -
Find your panel and save its address
Stop the simulator (Ctrl+C), switch the panel on, then scan. It shows up as
IDM-xxxxxx.$ uv run deskdot scanCopy
deskdot.example.tomltodeskdot.tomland put the MAC in. The file is git-ignored, so it never leaves your machine. Leaveaddressempty to use the firstIDM-*panel found.deskdot.tomladdress = "AA:BB:CC:DD:EE:FF" # from `deskdot scan` device = "ble" # "sim" = simulator lan_studio = false # true = full studio for other devices on your Wi-Fi
-
Check the link
Connects and draws a test pattern on the real panel. If you see it, Bluetooth is good.
$ uv run deskdot doctor -
Run it for real
$ uv run deskdot serve # → http://127.0.0.1:8765
Run the colour wizard once (Settings → Display & colour) so photos and album art match your LEDs. Want an app as a PNG without hardware?
uv run deskdot preview clock --out clock.png. -
Connect an AI agent (optional)
With the engine running, register the MCP server and your agent can see the panel, run apps, draw pixel art and notify you.
$ claude mcp add deskdot -- uv run --project /path/to/deskdot deskdot-mcpOther agents: see the AI setup page.
-
Keep it on 24/7 (optional)
Raspberry Pi
Zero 2 W / 3 / 4 / 5: built-in BLE, 1–3 W. Build the studio on your computer, copy the folder over, run the installer (uv + a systemd service). Then open
http://raspberrypi.local:8765.$ scp -r . pi@raspberrypi.local:~/deskdot pi$ cd ~/deskdot && bash scripts/install-pi.sh
Android phone Beta
The whole engine runs on a spare Android 8+ (64-bit) phone as a foreground service and restarts after a reboot. It builds and its Bluetooth bridge is unit-tested, but it hasn't been run on a real phone yet.
Only one device can hold the panel's link: stop DeskDot on the laptop when the Pi or phone runs it.