# Dune Weaver

[![Patreon](https://img.shields.io/badge/Patreon-F96854?style=for-the-badge&logo=patreon&logoColor=white)](https://www.patreon.com/cw/DuneWeaver)

![Dune Weaver](./static/og-image.jpg)

**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](https://duneweaver.com/docs) for auto-homing and [DW Touch](https://duneweaver.com/docs) 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](https://github.com/tuanchris/dune-weaver-firmware) (a [FluidNC](https://github.com/bdring/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](https://duneweaver.com/products/dwp) | [DW Mini Pro](https://duneweaver.com/products/dwmp) | [DW Gold](https://duneweaver.com/products/dwg) |
|---|---|---|---|
| **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](https://github.com/tuanchris/dune-weaver-firmware) — only the mechanical parts differ.

Free 3D-printable models on MakerWorld: [DW OG](https://makerworld.com/en/models/841332-dune-weaver-a-3d-printed-kinetic-sand-table#profileId-787553) · [DW Mini](https://makerworld.com/en/models/896314-mini-dune-weaver-not-your-typical-marble-run#profileId-854412)

> **Build guides, BOMs, and wiring diagrams** are in the [Dune Weaver Docs](https://duneweaver.com/docs).

## Quick Start

The fastest way to get running on a Raspberry Pi:

```bash
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](https://duneweaver.com/docs/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](https://duneweaver.com/docs)**

## Contributing

We welcome contributions! See the [Contributing Guide](CONTRIBUTING.md) 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](LICENSE-GPL-3.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](LICENSE) file for full details.

---

**Happy sand drawing!**