Dune Weaver Development Assistant

An expert AI assistant for working with the Dune Weaver kinetic sand table system - a web-controlled art installation with FastAPI backend, polar coordinate patterns, and hardware integration.

What This Skill Does

Provides comprehensive development support for the Dune Weaver project including:

FastAPI backend development and API design

Polar coordinate pattern system management

Hardware communication (Serial/WebSocket with ESP32/Arduino)

Real-time WebSocket status updates

WLED lighting integration

Pattern caching and preview generation

Playlist and state management

MQTT integration and software updates

Step-by-Step Instructions

1. Project Context Analysis

When starting work on Dune Weaver:

Read `main.py` to understand the FastAPI application structure

Review `modules/core/state.py` for global state management patterns

Check `modules/connection/` for hardware communication protocols

Examine existing `.thr` pattern files to understand the theta-rho coordinate format

Review `.cursorrules` for FastAPI best practices to follow

2. Development Environment Setup

For new features or debugging:

Use `npm run dev` or `npm run watch-css` for Tailwind CSS development

Use `npm run build-css` to build production CSS

Run `python main.py` to start the FastAPI server on port 8080

Verify pattern files exist in `patterns/` directory

Check `state.json` for current application state

3. Understanding the Coordinate System

**Critical**: Dune Weaver uses polar coordinates, NOT Cartesian:

**Theta (θ)**: Angular position in degrees (0-360°)

**Rho (ρ)**: Radial distance (0.0 = center, 1.0 = perimeter)

Pattern files contain `theta rho` pairs, one per line

Comments in pattern files start with `#`

Hardware coupling: angular movement affects radial position (software compensates)

4. Working with Patterns

When creating or modifying pattern features:

Pattern files are `.thr` format stored in `patterns/` directory

Generate WebP preview images in `patterns/cached_images/`

Custom user patterns go in `patterns/custom_patterns/`

Each pattern line: `<theta> <rho>` (space-separated)

Implement caching for performance (see existing cache logic)

5. Hardware Communication

For hardware integration work:

Support both Serial and WebSocket connection types

Use connection modules from `modules/connection/`

Implement thread-safe operations with proper locks

Handle crash-homing (no limit switches - motors crash to find home)

Compensate for mechanical coupling between angular and radial axes

Test with ESP32 or Arduino boards

6. API Development

When adding new endpoints:

Follow FastAPI best practices from `.cursorrules`

Use Pydantic models for request/response validation

Implement proper error handling with early returns

Use async operations for I/O-bound tasks

Follow dependency injection patterns

Add WebSocket endpoints to `/ws/` namespace for real-time updates

7. State Management

For features involving application state:

Use `modules/core/state.py` for global state

Persist state to `state.json`

Broadcast state changes via WebSocket (`/ws/status`)

Implement thread-safe state updates

Handle state recovery on application restart

8. Playlist and Pattern Execution

When working with playback features:

Use background tasks for pattern execution

Implement play, pause, resume, stop, skip controls

Manage playlist sequencing and timing

Coordinate with WLED for synchronized lighting

Update status via WebSocket during execution

9. Integration Features

For WLED, MQTT, or update system work:

WLED integration in `modules/led/`

MQTT capabilities in `modules/mqtt/`

Update management in `modules/update/` (Git-based)

Follow modular design pattern

Maintain separation of concerns

10. Testing and Quality

Before committing changes:

Test with both Serial and WebSocket hardware connections

Verify pattern preview generation works

Check WebSocket real-time updates

Test state persistence across restarts

Validate error handling for hardware disconnections

Ensure CSS builds correctly with `npm run build-css`

Important Constraints

**Coordinate system**: Always use polar coordinates (θ, ρ), never assume Cartesian

**Hardware coupling**: Angular axis affects radial position - software must compensate

**No limit switches**: System uses crash-homing for position reference

**Thread safety**: All hardware communication must be thread-safe with proper locking

**Async patterns**: Use asyncio for I/O operations, background tasks for long-running processes

**Pattern format**: Strict `.thr` format with space-separated theta-rho pairs

Example Usage Scenarios

**Scenario 1: Adding a new pattern API endpoint**

Create Pydantic model for pattern data

Implement async endpoint in `main.py`

Add pattern file validation logic

Generate preview image cache

Update state and broadcast via WebSocket

Handle errors gracefully with early returns

**Scenario 2: Debugging hardware communication**

Check connection type (Serial vs WebSocket)

Review logs for connection errors

Verify thread-safe access to connection objects

Test homing sequence

Validate coordinate compensation for axis coupling

**Scenario 3: Implementing a new playlist feature**

Extend state model in `modules/core/state.py`

Add REST API endpoint for playlist control

Implement background task for execution

Coordinate WLED lighting effects

Broadcast status updates via WebSocket

Persist playlist state to `state.json`

Dune Weaver Development Assistant

Dune Weaver Development Assistant

What This Skill Does

Step-by-Step Instructions

1. Project Context Analysis

2. Development Environment Setup

3. Understanding the Coordinate System

4. Working with Patterns

5. Hardware Communication

6. API Development

7. State Management

8. Playlist and Pattern Execution

9. Integration Features

10. Testing and Quality

Important Constraints

Example Usage Scenarios

Reviews (0)