Dune Weaver Development Assistant

Expert assistant for working with the Dune Weaver kinetic sand table system codebase. This skill provides comprehensive guidance for development, debugging, and enhancement of both software and hardware components.

Core Capabilities

This skill helps you work with:

**FastAPI backend development** with WebSocket and REST APIs

**Hardware integration** via Serial and WebSocket connections to ESP32/Arduino controllers

**Polar coordinate pattern system** (θ, ρ) for sand table control

**Pattern file management** and image caching

**WLED lighting integration** for synchronized effects

**Real-time state management** and persistent configuration

**CSS/frontend development** with Tailwind

**MQTT integration** for external systems

Architecture Understanding

Coordinate System

The sand table uses **polar coordinates (θ, ρ)** NOT Cartesian:

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

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

Key Components

**Backend**: FastAPI application in `main.py`

**Modules**: Organized in `modules/` directory:

- `connection/` - Serial/WebSocket hardware communication

- `core/` - Patterns, playlists, state, caching

- `led/` - WLED integration

- `mqtt/` - MQTT capabilities

- `update/` - Software update system

**Patterns**: `.thr` files in `patterns/` (theta-rho coordinate pairs)

**Frontend**: HTML templates in `templates/`, CSS/JS in `static/`

Hardware Constraints

Angular and radial axes are **mechanically coupled** (angular movement affects radial position)

Software compensates for coupling automatically

**Crash-homing system** without limit switches for position reference

Development Commands

When working with this codebase, use these commands:

Frontend/CSS Development

```bash

npm run dev # Watch mode for Tailwind CSS development

npm run watch-css # Alias for watch mode

npm run build-css # Build and minify for production

```

Python Application

```bash

python main.py # Start FastAPI server on port 8080 (0.0.0.0:8080)

```

Dependencies

```bash

pip install -r requirements.txt # Install Python dependencies

npm install # Install Node dependencies

```

Step-by-Step Instructions

1. When Reading or Analyzing Code

**Understand the coordinate system**: All pattern-related code uses polar coordinates (θ, ρ)

**Check module organization**: Code is organized by functional area in `modules/`

**Review state management**: Global state in `modules/core/state.py`, persisted to `state.json`

**Identify async operations**: Most I/O operations use asyncio patterns

**Look for hardware communication**: Check `modules/connection/` for Serial/WebSocket handling

2. When Adding or Modifying Features

**Follow FastAPI best practices** from `.cursorrules`:

- Use functional programming patterns

- Implement early returns for error handling

- Use Pydantic models for validation

- Prefer async for I/O operations

- Use proper dependency injection

**For pattern system changes**:

- Pattern files are `.thr` format (space-separated `theta rho` per line)

- Comments in patterns start with `#`

- Cached images stored in `patterns/cached_images/` as WebP

- Custom uploads go in `patterns/custom_patterns/`

**For hardware communication**:

- Support both Serial and WebSocket connection types

- Use thread-safe locks for connection management

- Account for mechanical coupling in motion control

- Remember crash-homing behavior (no limit switches)

**For state management**:

- Update global state via `modules/core/state.py`

- Ensure persistence to `state.json`

- Broadcast changes via WebSocket `/ws/status`

3. When Debugging Issues

**Hardware communication problems**:

- Check connection type (Serial vs WebSocket)

- Verify thread-safe access with locks

- Look for mechanical coupling compensation in motion code

- Check homing sequence completion

**Pattern execution issues**:

- Verify pattern file format (theta-rho pairs, valid ranges)

- Check playlist system state

- Review background task execution

- Validate coordinate transformations

**Frontend/UI issues**:

- Rebuild CSS with `npm run build-css`

- Check WebSocket connection at `/ws/status`

- Verify cached pattern images exist

- Review template rendering in `templates/`

4. When Working with WLED Integration

**WLED effects sync** with pattern execution

Configuration in `modules/led/`

Timing coordinated with pattern playback

Check WLED device connectivity and configuration

5. When Adding Tests

Test pattern parsing with various `.thr` formats

Validate polar coordinate transformations

Mock hardware connections for unit tests

Test state persistence and recovery

Verify WebSocket message handling

Important Constraints and Notes

Hardware-Specific

Angular movement affects radial position (mechanically coupled)

No physical limit switches - software relies on crash-homing

ESP32 or Arduino controllers via Serial or WebSocket

Real-time control requires careful timing

Software Architecture

Asyncio for concurrency

Thread-safe connection management

WebSocket for real-time updates

Pydantic for data validation

Functional programming preferred

File Organization

Patterns: `patterns/` (supports subdirectories)

Static assets: `static/`

Templates: `templates/`

Firmware configs: `firmware/` (version-specific subdirectories)

Root config files: Project root

Usage Examples

**Example 1: Adding a new pattern execution feature**

```

Read modules/core/state.py to understand current state management

Review main.py for existing pattern execution endpoints

Add new FastAPI endpoint with Pydantic validation

Update state management to track new feature

Broadcast state changes via WebSocket

Update frontend to display new feature

```

**Example 2: Debugging pattern preview generation**

```

Check patterns/cached_images/ for WebP files

Review modules/core/caching.py for image generation logic

Verify pattern file format is correct (theta rho pairs)

Test with a simple pattern first

Check file permissions on cached_images directory

```

**Example 3: Modifying hardware communication**

```

Review modules/connection/ for connection types

Ensure thread-safe access with locks

Test with both Serial and WebSocket connections

Account for mechanical coupling in motion commands

Verify crash-homing sequence still works

```

References

Main application: `main.py`

Module documentation: Individual files in `modules/`

Pattern format: Check example `.thr` files in `patterns/`

FastAPI best practices: `.cursorrules`

Hardware firmware: `firmware/` subdirectories

---

This skill provides expert guidance for the Dune Weaver project. Always consider the polar coordinate system, hardware constraints, and async architecture when making changes.

Dune Weaver Development Assistant

Dune Weaver Development Assistant

Core Capabilities

Architecture Understanding

Coordinate System

Key Components

Hardware Constraints

Development Commands

Frontend/CSS Development

Python Application

Dependencies

Step-by-Step Instructions

1. When Reading or Analyzing Code

2. When Adding or Modifying Features

3. When Debugging Issues

4. When Working with WLED Integration

5. When Adding Tests

Important Constraints and Notes

Hardware-Specific

Software Architecture

File Organization

Usage Examples

References

Reviews (0)