dune-weaver

Dune Weaver

An open-source kinetic sand art table that creates mesmerizing patterns using a ball controlled by precision motors.

Features

• Modern React UI — A responsive, touch-friendly web interface that installs as a PWA on any device
• Pattern Library — Browse, upload, and manage hundreds of sand patterns with auto-generated previews
• Live Preview — Watch your pattern come to life in real time with progress tracking
• Playlists — Queue up multiple patterns with configurable pause times and automatic clearing between drawings
• LED Integration — The table's built-in LED ring (firmware-driven effects with a live in-app preview) or WLED, with separate idle, playing, and scheduled modes
• Still Sands Scheduling — Set quiet hours so the table pauses automatically on your schedule
• Multi-Table Support — Tables and boards are discovered automatically on your network (mDNS); control several from a single interface
• Home Assistant Integration — Connect to Home Assistant or other home automation systems using MQTT
• Auto-Updates — One-click software and board firmware updates right from the settings page
• Add-Ons — Optional Desert Compass for auto-homing and DW Touch for dedicated touchscreen control

How It Works

The system is split across two devices that talk over your network — no USB cable:

┌─────────────────┐     Wi-Fi (HTTP)     ┌─────────────────┐
│  Raspberry Pi   │ ◄──────────────────► │  DLC32 / ESP32  │
│  (Dune Weaver   │                      │  (Dune Weaver   │
│   Backend)      │                      │   firmware)     │
└─────────────────┘                      └─────────────────┘
        │                                        │
        │ Wi-Fi                                  │ Motor signals
        ▼                                        ▼
   Web Browser                            Stepper Motors
   (Control UI)                           (Theta & Rho)

The DLC32/ESP32 runs the Dune Weaver firmware (a FluidNC fork) and executes everything on-board — theta-rho kinematics, pattern playback from its SD card, playlists, clears, quiet hours, and homing — so the table keeps drawing even if the Pi is off. The Raspberry Pi backend layers on everything a headless controller can't do: the web UI, pattern management with previews, play history, MQTT/Home Assistant, WLED, multi-table discovery, and one-click software and firmware updates. The backend finds boards automatically via mDNS and drives them over plain HTTP.

Hardware

Dune Weaver comes in three premium models:

	DW Pro	DW Mini Pro	DW Gold
Size	75 cm (29.5")	25 cm (10")	45 cm (17")
Enclosure	IKEA VITTSJÖ table	IKEA BLANDA bowl	IKEA TORSJÖ side table
Motors	2 × NEMA 17	2 × NEMA 17	2 × NEMA 17
Controller	DLC32	DLC32	DLC32
Best for	Living rooms	Desktops	Side-table accent piece

All models run the same software with the Dune Weaver firmware — only the mechanical parts differ.

Free 3D-printable models on MakerWorld: DW OG · DW Mini

Build guides, BOMs, and wiring diagrams are in the Dune Weaver Docs.

Quick Start

The fastest way to get running on a Raspberry Pi:

curl -fsSL https://raw.githubusercontent.com/tuanchris/dune-weaver/main/setup-pi.sh -o setup-pi.sh
bash setup-pi.sh

This installs Docker, clones the repo, and starts the application. Once it finishes, open http://<hostname>.local in your browser.

For full deployment options (Docker, manual install, development setup, Windows, and more), see the Deploying Backend guide.

Polar coordinates

The sand table uses polar coordinates instead of the typical X-Y grid:

• Theta (θ) — the angle in radians (2π = one full revolution)
• Rho (ρ) — the distance from the center (0.0 = center, 1.0 = edge)

Patterns are stored as .thr text files — one coordinate pair per line:

# A simple four-point star
0.000 0.5
1.571 0.7
3.142 0.5
4.712 0.7

The same pattern file works on any table size thanks to the normalized coordinate system. You can create patterns by hand, generate them with code, or browse the built-in library.

Documentation

Full setup instructions, hardware assembly, firmware flashing, and advanced configuration:

Dune Weaver Docs

Contributing

We welcome contributions! See the Contributing Guide for how to get started.

License

Dune Weaver is available under a dual license:

Open Source License (GPL-3.0)

For open-source projects and personal use, Dune Weaver is licensed under the GNU General Public License v3.0.

You are free to use, modify, and distribute this software under GPL-3.0 terms, provided that derivative works are also licensed under GPL-3.0 and source code is made available.

Commercial License

For commercial use, proprietary applications, OEM/embedded deployments, or if you cannot comply with GPL-3.0 requirements, a commercial license is available.

Contact: hello@duneweaver.com

See the LICENSE file for full details.

---

Happy sand drawing!