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 — Synchronized lighting via native DW LEDs 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 — Control several sand tables from a single interface
• Home Assistant Integration — Connect to Home Assistant or other home automation systems using MQTT
• Auto-Updates — One-click software 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 connected via USB:

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

The Raspberry Pi runs the web UI, manages pattern files and playlists, and converts patterns into G-code. The DLC32/ESP32 running FluidNC firmware receives that G-code and drives the stepper motors in real time.

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 FluidNC 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!