Dune Weaver Touch Interface

A PySide6/QML touch interface for the Dune Weaver sand table. It talks directly to the table's FluidNC firmware over its stateless HTTP/JSON API — there is no separate host (Raspberry Pi FastAPI) service in between.

Connecting to the table

The firmware is headless and advertises itself over mDNS. On launch the app:

Auto-discovers tables via mDNS (_http._tcp advertisements with model=dune-weaver). If exactly one is found it connects automatically; otherwise pick one from the Control page's table list (tap Refresh to re-scan).
Pin a table by setting DUNE_WEAVER_URL in .env (e.g. DUNE_WEAVER_URL=dunetable.local or an IP). This skips discovery.

The chosen table is remembered in touch_settings.json.

How it maps to the firmware API

Status is polled from GET /sand_status (~1 Hz) instead of a WebSocket.
Actions go out as $... commands via /command and the /sand_* routes (run/stop/pause/resume/home/goto/feed/LED).
Patterns come from GET /sand_patterns; previews are rendered locally from the raw .thr files (/sd/patterns/...) and cached under preview_cache/.
Playlists are .txt files on the SD card — listed via GET /sand_playlists, read from /sd/playlists/..., and created/edited by uploading/deleting files.
LEDs use the firmware's named effect/palette catalogue ($LED/* / /sand_led).
Screen / LCD backlight control stays local to the touch host (sysfs + sudo scripts).

See the firmware's API.md for the full contract.

Features

Modern SwipeView Navigation: Swipe between Patterns, Playlists, and Control pages
Pattern Browsing: Beautiful grid view with search and thumbnail previews
Pattern Execution: Touch-optimized controls with pre-execution options
Table Control: Dedicated control page with status monitoring and quick actions
Real-time Status: WebSocket integration for live progress updates
Modern UI: Material Design inspired interface with animations and shadows
Touch Optimized: Large buttons, smooth animations, and intuitive gestures

Architecture

Pattern Browsing: GET /sand_patterns on the table; .thr previews rendered locally
Execution Control: firmware $... commands via /command + /sand_* routes
Status Monitoring: polling GET /sand_status (~1 Hz)
Navigation: StackView-based page navigation

Key modules

firmware_client.py — shared async HTTP client + LED/clear-mode maps (singleton)
discovery.py — mDNS table discovery (zeroconf; degrades gracefully if absent)
thr_preview.py — renders .thr → cached PNG previews
backend.py — QML-facing controller (status poll, actions, LEDs, playlists, local screen)
models/ — PatternModel / PlaylistModel, both firmware-backed

Quick Installation (Auto-Start Setup)

One command to set up everything for kiosk/production use:

sudo ./install.sh

This will:

✅ Create Python virtual environment with dependencies (venv/)
✅ Install system scripts for screen control (/usr/local/bin/screen-on, screen-off, touch-monitor)
✅ Set up systemd service for auto-start on boot
✅ Configure kiosk optimizations (clean boot, auto-login)
✅ Enable automatic startup

Service Management

# Control the service
sudo systemctl start dune-weaver-touch    # Start now
sudo systemctl stop dune-weaver-touch     # Stop service
sudo systemctl status dune-weaver-touch   # Check status
sudo journalctl -u dune-weaver-touch -f   # View logs

# Disable auto-start
sudo systemctl disable dune-weaver-touch

Manual Installation (Development)

Create virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate  # or: . venv/bin/activate
pip install -r requirements.txt

Power on the sand table and make sure it's on the same network (or set DUNE_WEAVER_URL in .env to pin its address).

Run the touch interface:

./run.sh              # Uses virtual environment automatically
# OR manually:
./venv/bin/python main.py

Advanced Setup Options

For custom installations:

sudo ./setup-autostart.sh

Choose from multiple setup options including systemd service, desktop autostart, or kiosk optimizations.

Project Structure

dune-weaver-touch/
├── main.py                     # Application entry point
├── backend.py                  # Backend controller with API/WebSocket integration
├── models/
│   ├── pattern_model.py        # Pattern list model with file system access
│   └── playlist_model.py       # Playlist model reading from JSON
├── qml/
│   ├── main.qml               # Main window with StackView navigation
│   ├── pages/
│   │   ├── PatternListPage.qml    # Grid view of patterns with search
│   │   ├── PatternDetailPage.qml  # Pattern details with execution controls
│   │   ├── PlaylistPage.qml       # Playlist selection and execution
│   │   └── ExecutionPage.qml      # Current execution status display
│   └── components/
│       └── PatternCard.qml        # Pattern thumbnail card
├── requirements.txt
└── README.md

Usage

Navigation

Swipe left/right to navigate between the three main pages:
- Patterns: Browse and search through all available patterns
- Playlists: View and manage pattern playlists
- Control: Monitor table status and quick control actions

Pattern Management

Browse Patterns: Swipe to Patterns page to see grid view with thumbnail previews
Search: Use the search field to filter patterns by name
Select Pattern: Tap a pattern card to view details and execution options
Execute: Choose pre-execution action and tap "Play Pattern"

Table Control

Monitor Status: Swipe to Control page to see current pattern and progress
Control Execution: Use Pause/Resume and Stop buttons
Quick Actions: Use Clear In, Clear Out, or Circle pattern shortcuts
Connection Status: View WebSocket connection status

Notes

The touch interface talks directly to the table firmware; no host service is required
The firmware's HTTP API is multi-client, so the app can run alongside other clients (phone/web app, Home Assistant) at the same time
Pattern previews render locally the first time a pattern is seen, then load from cache
Requires the table to be reachable on the network (mDNS or DUNE_WEAVER_URL)

README.md 6.7 KB تاريخچه خام