Step by step

Run it yourself

About ten minutes from nothing to a live panel. Every command here is the one the README uses; each step links to the file that explains it.

Just want to try it? Open DeskDot in your browser: the same engine and studio run in the tab and connect to the panel over Web Bluetooth, nothing to install (Chrome, Edge or Opera; on iPhone, the Bluefy browser). Run it yourself, below, for the features that need your computer (now playing, screen mirror, system stats, phone multiplayer, MCP) and to keep the panel going 24/7.

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

   Windows macOS / Linux

   install uv (PowerShell)

   PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

   uv install docsREADME: Quick StartREADME: Compatibility

2. Clone the repo

   $ git clone https://github.com/shivpatel2468/idotmatrix.git deskdot
   $ cd deskdot

   github.com/shivpatel2468/idotmatrixdocs/ARCHITECTURE.md

3. Install the engine and the MCP server

   One command installs Python 3.13 and every dependency into a local .venv.

   $ uv sync --extra mcp

   pyproject.tomlADR 0002: Python, uv, FastAPI

4. 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 dev in web/ gives hot reload on :5173, proxied to the engine.

   web/docs/STUDIO_UI.md

5. 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 --sim

   Then open http://127.0.0.1:8765. Pick an app, change a setting, press ▶ Play on a game.

   README: The First Five Minutesdocs/API.md

6. 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 scan

   Copy deskdot.example.toml to deskdot.toml and put the MAC in. The file is git-ignored, so it never leaves your machine. Leave address empty to use the first IDM-* panel found.

   deskdot.toml

   address = "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

   deskdot.example.tomldocs/HARDWARE_PROTOCOL.md

7. Check the link

   Connects and draws a test pattern on the real panel. If you see it, Bluetooth is good.

   $ uv run deskdot doctor

   src/deskdot/cli.pyADR 0009: paced writes

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

   README: The StudioREADME: Games & Multiplayer

9. 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-mcp

   Other agents: see the AI setup page.

   docs/MCP.mdsrc/deskdot/mcp_server.py

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

    scripts/install-pi.shdocs/DEPLOY.md

    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.

    android/README.mdADR 0011

    Only one device can hold the panel's link: stop DeskDot on the laptop when the Pi or phone runs it.