Files

Jimmy 9e2409430c Add documentation and utility modules

- Add API specification documentation
- Add system specification document
- Add UI mockups and documentation
- Add utility modules (wifi)

2026-01-11 21:34:18 +13:00

62 KiB

Raw Blame History

LED Driver System - Specification Document

Version: 1.0
Date: December 2025
Status: Draft

Overview
System Architecture
User Interface Specifications
Feature Specifications
Preset System
Profile and Scene System
Data Format Specifications
API Specifications
User Flows
Design Guidelines
Technical Requirements
Testing Requirements

Overview

Purpose

The LED Driver system is a MicroPython-based application for controlling LED strips via ESP32-C3 microcontrollers. The system uses a custom firmware image with usqlite and microdot built-in as frozen modules. The system provides:

Real-time LED pattern control
Multi-device management via peer-to-peer communication (ESPNow)
Group-based device control
Web-based configuration interface
Binary message protocol for efficient communication

Target Users

Primary: Hobbyists and makers controlling LED installations
Secondary: Developers building LED-based projects
Tertiary: Commercial installations requiring remote LED control

Key Features

Pattern configuration and control (patterns run on remote devices)
Real-time brightness and speed control
Global brightness setting (system-wide brightness multiplier)
Multi-color support with customizable color palettes
Device grouping for synchronized control
Preset system for saving and loading pattern configurations
Profile and Scene system for complex lighting setups
Preset sequencing within groups for time-based transitions
Peer-to-peer communication via ESPNow
Binary message protocol for bandwidth efficiency
Persistent settings storage (usqlite database)
Web-based configuration interface (Microdot web server)
SQLite database for presets and event logging

System Architecture

Technology Stack

Core Framework:

MicroPython: Python runtime for ESP32-C3
Microdot: Lightweight web framework for HTTP/WebSocket server (built into ESP32-C3 firmware)
usqlite: μSQLite library for MicroPython - SQLite database implementation (built into ESP32-C3 firmware)
ESPNow: Peer-to-peer WiFi communication protocol

Note: The ESP32-C3 firmware image includes usqlite and microdot as frozen modules, meaning they are part of the firmware and available immediately without installation. usqlite is integrated via CMake during firmware build.

Key Libraries:

neopixel: WS2812 LED control
machine: GPIO and hardware control
network: WiFi and ESPNow
json: Settings serialization
struct: Binary message encoding

Components

┌─────────────────────────────────────────────────────────┐
│                    Web Browser                          │
│  (Dashboard, Pattern Selector, Device Management)      │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP/WebSocket
                     ▼
┌─────────────────────────────────────────────────────────┐
│         Master ESP32 Device (MicroPython)                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   Microdot   │  │   Settings   │  │   HTTP/WS    │ │
│  │  Web Server  │  │  Management  │  │  Communication│ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   usqlite    │  │   Settings   │  │  Access      │ │
│  │  Database    │  │  Management  │  │  Point (AP)  │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│  ┌──────────────┐                                     │
│  │  WebSocket   │  Receives BPM from beat detector     │
│  │  BPM Handler │                                     │
│  └──────────────┘                                     │
│  ┌──────────────┐                                     │
│  │  Beat Counter│  Tracks beats, phases, scene queue │
│  │  & Phases    │                                     │
│  └──────────────┘                                     │
└────────────────────┬────────────────────────────────────┘
                     │ ESPNow / Binary Messages
                     │ (Commands to slave devices)
                     │ (BPM sync data)
                     ▼
┌─────────────────────────────────────────────────────────┐
│         Remote LED Devices                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   HTTP/WS    │  │   Settings   │  │   Pattern    │ │
│  │   Client     │  │  Receiver    │  │  Execution   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│  ┌──────────────┐                                     │
│  │  BPM Sync    │  Receives BPM via ESPNow            │
│  └──────────────┘                                     │
│  Note: AP disabled, receives commands from master      │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                  LED Strip (WS2812)                      │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│         Beat Detection Device (Separate Device)         │
│  ┌──────────────┐  ┌──────────────┐                      │
│  │   Audio      │  │  BPM         │                      │
│  │   Input      │  │  Calculator │                      │
│  └──────────────┘  └──────────────┘                      │
│  ┌──────────────┐                                     │
│  │  WebSocket   │  Sends BPM to master device          │
│  │  Client      │                                     │
│  └──────────────┘                                     │
└────────────────────┬────────────────────────────────────┘
                     │ WebSocket Connection
                     │ (BPM data: beats per minute)
                     ▼
              Master Device WebSocket Server

Master/Slave Architecture

The LED Driver system uses a master/slave architecture where one device acts as the central controller and web interface host, while other devices act as pattern executors that receive commands.

Master Device:

Primary Role: Central controller and web interface host
Access Point: Enabled (creates WiFi network, typically 192.168.4.1)
Device Name / SSID / Hostname: All the same value (e.g., "led-device1")
- Single value used for: device name, WiFi SSID, and network hostname
- Changing device name updates SSID and hostname simultaneously
Web Server: Microdot web server running on port 80
Database: usqlite database for presets, settings, and device registry
ESPNow: Sends commands to slave devices
Groups: Master device can be assigned to groups (same as slaves)
Light Control: Master behaves the same as slaves regarding pattern/light control
- Master can receive group-based commands
- Master applies commands to itself when sending to groups it belongs to
- Master checks its own group membership before sending to slaves
Control: Can control itself and all slave devices
Configuration: Full access to all settings and device management
IP Address: Typically 192.168.4.1 (AP mode) or configured IP (STA mode)

Slave Devices:

Primary Role: LED pattern executors
Access Point: Disabled (connects to master's AP or existing WiFi)
Web Server: Optional (can be enabled for direct access, but not required)
Database: Optional (can use for local settings, but master is authoritative)
ESPNow: Receives commands from master device
Control: Only controls itself (receives commands from master)
Configuration: Receives settings via ESPNow messages from master
IP Address: Assigned by master's DHCP (192.168.4.x) or existing network

Communication Flow:

User accesses web interface on master device (via browser at master's IP)
User configures patterns/settings in web UI
User selects target device(s) or group(s)
Master device checks if it belongs to the selected group(s)
If master is in the group, master applies the preset/pattern to itself
Master device sends ESPNow messages to target slave device(s) in the group
Slave devices receive and execute commands
All devices (master + slaves) in the group display synchronized patterns

Group-Based Command Flow:

User selects a group (e.g., "group1") and applies a preset
Master device checks its own group membership
If master belongs to "group1", master applies the preset to itself
Master sends ESPNow messages to all slave devices in "group1"
All devices in the group (including master) update simultaneously

Network Topology:

Master device creates WiFi Access Point (AP mode)
Master SSID = Master Hostname (same value, e.g., "led-device1")
Slave devices connect to master's AP (STA mode) using master's SSID
All devices must be on same WiFi channel for ESPNow communication
Master device IP: Typically 192.168.4.1 (AP mode)
Master device hostname: Same as SSID (accessible via mDNS if supported)
Slave device IPs: Assigned by master's DHCP (192.168.4.x)
Alternative: All devices can connect to existing WiFi network (STA mode)

Communication Protocols

ESPNow (Master-to-Slave):

Direction: Master device sends commands to slave devices
Message Format: Binary (preferred) or JSON (fallback)
Targeting: Device names or groups
Persistence: Settings saved to /settings.json or usqlite database (on master)
Network: Master and slaves must be on same WiFi channel

HTTP/WebSocket (Web Interface - Master Only):

Framework: Microdot web server (master device only)
Protocol: HTTP/1.1 with WebSocket support
Port: 80 (default, configurable)
Access: Direct browser connection to master device IP (typically 192.168.4.1 in AP mode)
Real-time Updates: WebSocket for live status updates
Control: Web interface controls master device and sends commands to slaves via ESPNow
BPM Input: WebSocket receives BPM (beats per minute) from external beat detection device
- Beat detection device connects to master's WebSocket server
- Sends BPM updates in real-time
- Master device uses BPM to sync pattern delays/transitions to music
- Master forwards BPM data to slave devices via ESPNow for synchronized patterns

User Interface Specifications

1. Dashboard (Main Control Panel)

File: dashboard.html

Purpose

Primary interface for real-time LED control and monitoring.

Layout

Header: System title and description
Grid Layout: 4-column responsive grid
- Pattern Selection Card
- Brightness & Speed Card
- Color Selection Card
- Device Status Card
Action Bar: Apply and Save buttons

Components

Pattern Selection

Type: Button grid or dropdown
Patterns: Configurable pattern types (sent to remote devices)
Behavior: Single selection, visual feedback on selected pattern
Visual: Card-based buttons with hover effects

Pattern Mode Selection

Type: Toggle switch or radio buttons
Options: Auto / Single Shot
Default: Auto
Auto Mode: Pattern configuration is sent continuously (default behavior)
Single Shot Mode: Receiving a beat triggers the preset/pattern once (requires beat detection)
Visual Indicator: Shows current mode, disabled state if beat detection unavailable
Tooltip: "Auto: Continuous pattern. Single Shot: Receiving a beat triggers preset/pattern once (requires beat detection)."

Global Brightness Control

Type: Range slider (0-100%)
Display: Real-time value display next to label
Default: 100%
Update: Live preview (if supported)
Description: System-wide brightness that applies to all patterns uniformly

Delay/Speed Control

Type: Range slider (10-1000ms)
Display: Real-time value display in milliseconds
Default: 100ms
Step: 10ms increments

Color Selection

Type: Color picker inputs (HTML5 color input)
Quantity: Multiple colors (minimum 2, expandable)
Format: Hex color codes (e.g., #FF0000)
Display: Large color swatches (60x60px)
Action: "Add Color" button for additional colors

Device Status List

Type: List of connected devices
Information Displayed:
- Device name
- Group assignment
- Online/Offline status (visual indicator)
Visual Indicators:
- Green dot: Online
- Red dot: Offline

Action Buttons

Apply Settings: Apply changes without saving
Save to Device: Persist settings to device storage

Design Specifications

Color Scheme: Purple gradient background (#667eea to #764ba2)
Cards: White background, rounded corners (12px), shadow
Hover Effects: Card lift (translateY -2px), increased shadow
Typography: System font stack, 1.25rem headings

2. Pattern Selector

File: pattern-selector.html

Purpose

Dedicated interface for visual pattern selection with descriptions.

Layout

Header: Title and description
Pattern Grid: Responsive grid (minimum 280px per card)
Action Bar: Cancel and Apply buttons

Pattern Cards

Each pattern card displays:

Icon/Visual: Pattern-specific visual representation
Name: Pattern name (e.g., "Rainbow")
Description: Brief explanation of pattern behavior
Preview: Visual preview dots showing pattern concept

Pattern Types: Patterns are configured and sent to remote devices. The specific pattern types supported depend on the remote device implementation. Common pattern types include:

Static patterns (On, Off)
Animated patterns (Blink, Chase, Pulse, Rainbow, etc.)
Custom patterns defined by device capabilities

Selection Behavior

Single Selection: Only one pattern can be selected at a time
Visual Feedback: Selected card has purple gradient background, white text
Hover Effect: Border highlight, slight lift

Design Specifications

Background: Light gradient (#f5f7fa to #c3cfe2)
Card Size: Minimum 280px width, auto height
Spacing: 24px gap between cards
Selected State: Purple gradient (#667eea to #764ba2), white text

3. Device Management

File: device-management.html

Purpose

Manage connected devices and create/manage device groups.

Layout

Header: Title with "Add Device" button
Tabs: Devices and Groups tabs
Content Area: Tab-specific content

Devices Tab

Device List

Display: List of all known devices
Device Item Information:
- Device name (bold, 1.125rem)
- Status badge (Online/Offline)
- MAC address
- Group assignment
- Current pattern configuration
Status Indicator: Colored dot (green=online, red=offline)
Actions: Edit, Settings, Remove buttons (icon buttons)

Add Device Modal

Fields:
- Device Name (text input)
- MAC Address (text input, format: AA:BB:CC:DD:EE:FF)
- Device Role (dropdown: Master/Slave, default: Slave)
- Group (dropdown, includes "No group" option)
Actions: Cancel, Save
Note: Only one master device per system. Adding a new master will demote existing master to slave.

Groups Tab

Group List

Display: List of all device groups
Group Item Information:
- Group name (bold)
- Pattern settings (pattern, delay)
- Assigned devices (tags showing master and/or slaves)
- Master device indicator if master is in the group
Actions: Edit, Apply, Delete buttons
Note: Master device can be assigned to groups and will apply commands to itself when sending to groups it belongs to

Create Group Modal

Fields:
- Group name (text input)
- Pattern selection
- Brightness (slider)
- Delay (slider)
- Device selection (multi-select)
Actions: Cancel, Create

Design Specifications

Tab Style: Active tab has purple background, white text
List Items: Bordered cards with hover effects
Modal: Centered overlay with white card, shadow
Status Badges: Colored pills (green for online, red for offline)

4. Profile and Scene Management

File: profiles.html (to be created)

Purpose

Create and manage profiles containing scenes, where each scene assigns presets to groups with optional sequencing.

Layout

Header: Title with "Create Profile" button
Profile List: List of all profiles with expandable scenes
Scene Editor: Modal for creating/editing scenes
Group Assignment Panel: Assign groups to presets with sequencing options

Each profile card displays:

Profile Name: Bold, large font
Description: Optional description text
Scene Count: Number of scenes in profile
Actions: Edit, Delete, Activate buttons
Scenes List: Expandable list of scenes within profile

Scene Card

Each scene card displays:

Scene Name: Bold font
Group Assignments: List showing group → preset mappings
Sequencing Indicator: Badge if scene has sequenced groups
Actions: Edit, Activate, Delete buttons

Fields:

Profile Name (text input, required)
Description (textarea, optional)
Scenes List:
- Add Scene button
- List of scenes with edit/delete buttons

Fields:

Scene Name (text input, required)
Description (textarea, optional)
Default Transition Time (slider, 0-5000ms)
Group Assignments:
- Group selector (dropdown)
- Preset selector (single or multiple)
- Sequencing toggle
- If sequencing enabled:
  - Duration per preset (slider, 100-60000ms)
  - Transition time (slider, 0-5000ms)
  - Loop checkbox
  - Repeat count (number input, 0 = infinite)

Activate Scene

Immediate Activation:

User selects profile
User selects scene
User clicks "Activate Scene"
Master device processes scene configuration
All groups in scene receive their assigned presets
Sequencing begins automatically if configured
UI shows active scene indicator and sequence progress

Queue Scene (Phase-Based Activation):

User selects profile
User selects scene
User clicks "Queue Scene" (instead of "Activate Scene")
Scene is queued to activate at the end of the current phase
UI shows queued scene indicator with phase countdown
When phase ends (phase_beat reaches phase_length - 1):
- Queued scene activates automatically
- All groups in scene receive their assigned presets
- Sequencing begins automatically if configured
- Queue is cleared
User can clear queue before phase ends

Design Specifications

Profile Cards: White background, rounded corners, shadow
Scene Cards: Nested within profile cards, slightly indented
Sequence Indicator: Animated badge showing sequence is active
Group Assignment: Visual mapping showing group → preset(s) relationships

5. Settings

File: settings.html

Purpose

Comprehensive device configuration interface.

Layout

Header: Title and description
Sections: Multiple collapsible/expandable sections
Action Bar: Reset and Save buttons

Sections

1. Basic Settings

Device Name (text input)
LED Pin (number input, 0-40)
Number of LEDs (number input, 1-1000)
Color Order (visual selector with 6 options: RGB, RBG, GRB, GBR, BRG, BGR)

2. Pattern Settings

Pattern (dropdown selection)
Pattern Mode (radio buttons or toggle: Auto / Single Shot)
- Auto: Pattern configuration is sent continuously
- Single Shot: Receiving a beat triggers the preset once (requires beat detection)
- Tooltip: "Single Shot mode: Receiving a beat triggers preset once"
Delay (slider, 10-1000ms, with value display)
- Note: Delay is ignored in Single Shot mode (beats trigger preset)

3. Global Brightness

Global Brightness (slider, 0-100%, with value display)
Tooltip: "System-wide brightness that applies to all patterns uniformly."
Default: 100% (full brightness)

3a. Beat Detection (BPM)

Enable BPM Sync (checkbox)
Current BPM Display (read-only, shows current BPM from beat detector)
BPM Multiplier (slider, 0.1x to 10.0x, default: 1.0x)
Manual BPM Override (number input, 0-300, optional)
BPM Source Status (indicator showing beat detector connection status)
Tooltip: "Sync pattern delays and transitions to music beats. BPM is received from external beat detection device via WebSocket."

3b. Beat Counter and Phases

Beat Counter Display (read-only, shows current beat number)
Phase Length (number input, 1-64 beats, default: 4)
Current Phase Display (read-only, shows current phase number)
Phase Beat Position (read-only, shows beat position within phase, 0 to phase_length-1)
Sync Beat Counter (button, resets beat counter to 0)
Queued Scene Display (shows scene queued to activate at end of phase)
Clear Queue (button, clears queued scene)
Tooltip: "Beat counter tracks beats for phase-based scene changes. Scenes can be queued to activate at phase boundaries."

4. Advanced Settings

Pattern Parameters:
- N1-N8 (number inputs, 0-255)
- Tooltip: "Pattern-specific parameters (varies by pattern). N7 and N8 reserved for future enhancements."
Device ID (number input)
Debug Mode (checkbox)

5. Network Settings

Master Device:

Device Name / SSID (text input, required, single field)
- Note: Device name and SSID are the same value
- Changing device name updates both hostname and SSID
Access Point Password (password input, optional)
Enable Access Point (checkbox, checked and locked for master)
Device Role Indicator: "Master Device" badge
Tooltip: "Master device creates WiFi network. Device name is used as both hostname and SSID."

Slave Device:

Device Name (text input, separate from SSID)
Access Point Name (text input, disabled - not applicable for slaves)
Access Point Password (text input, disabled)
Enable Access Point (checkbox, unchecked and disabled for slaves)
Device Role Indicator: "Slave Device" badge
Tooltip: "Slave devices connect to master's network. Device name is separate from SSID."

Form Controls

Input Types:

Text: Standard text input
Number: Number input with min/max validation
Range: Slider with real-time value display
Select: Dropdown menu
Checkbox: Toggle switch
Color: HTML5 color picker

Color Order Selector

Type: Visual button grid
Options: RGB, RBG, GRB, GBR, BRG, BGR
Display: Color boxes showing order (R=red, G=green, B=blue)
Selection: Single selection with visual feedback

Design Specifications

Section Headers: Purple color (#667eea), 1.5rem font, bottom border
Form Groups: 24px spacing between fields
Labels: Bold, 500 weight, dark gray (#333)
Help Text: Small gray text below inputs
Action Buttons: Full-width, Reset (secondary), Save (primary)

5. Preset Management

File: presets.html (to be created)

Purpose

Save, load, and manage preset configurations for quick pattern switching.

Layout

Header: Title with "Create Preset" button and "Sync Presets to All Devices" button
Preset Grid: Responsive grid of preset cards
Action Bar: Quick apply buttons

Preset Card

Each preset card displays:

Name: Preset name (bold, 1.25rem)
Pattern Badge: Current pattern type
Color Preview: Swatches showing preset colors
Quick Info: Delay and brightness values
Actions: Apply, Edit, Delete buttons

Fields:

Preset Name (text input, required)
Pattern (dropdown selection)
Colors (multiple color pickers, minimum 2)
Delay (slider, 10-1000ms)
Step Offset (number input, optional, default: 0)
- Tooltip: "Step offset for group synchronization. Applied per device when preset is used in a group."
Step Increment (number input, optional, default: 1, minimum: 1)
- Tooltip: "Amount step counter increments per cycle. Controls pattern advancement speed."
Pattern Parameters:
- N1 (number input, 0-255)
- N2 (number input, 0-255)
- N3 (number input, 0-255)
- N4 (number input, 0-255)
- N5 (number input, 0-255)
- N6 (number input, 0-255)
- N7 (number input, 0-255)
- N8 (number input, 0-255)

Actions:

Cancel
Save Preset

Preset List View

Display Options:

Grid view (default): Visual cards with previews
List view: Compact list with details

Sorting:

Alphabetical (A-Z)
Recently used
Recently created

Filtering:

By pattern type
By name (search)

Preset Synchronization

Sync Button: "Sync Presets to All Devices" button in header
Behavior:
- Master sends all presets to all devices via ESPNow
- Each device stores presets in local database
- Ensures all devices have same preset definitions
- Shows sync progress and status for each device
Use Case: After creating/editing presets on master, sync to ensure all devices have updated preset definitions

Design Specifications

Card Style: White background, rounded corners, shadow
Pattern Badge: Colored pill with pattern name
Color Swatches: 40x40px squares in card header
Hover Effect: Card lift, border highlight
Selected State: Purple border, subtle background tint

Feature Specifications

Pattern Configuration

Patterns are configured on the controller and sent to remote devices for execution. The controller manages pattern settings including:

Pattern Type: Identifier for the pattern (e.g., "on", "off", "blink", "chase", "pulse", "rainbow", etc.)
Pattern Parameters: Numeric parameters (N1-N8) that configure pattern-specific behavior
Colors: Color palette for the pattern
Timing: Delay and speed settings

Note: Pattern execution happens on the remote devices. The controller sends configuration commands to devices.

Pattern Parameters (N1-N8)

Pattern-specific numeric parameters:

N1-N8: Integer values (0-255)
Usage: Varies by pattern type (sent to remote devices for pattern-specific configuration)
Default: 0 (pattern-specific defaults apply)
Note: N7 and N8 are reserved for future pattern enhancements and preset system

Preset System

Overview

Presets allow users to save complete pattern configurations for quick recall and application. A preset encapsulates all pattern settings including pattern type, colors, timing, and all pattern parameters.

Note: Presets are optional. Devices can be controlled directly without presets.

Preset Structure

A preset contains the following fields:

name (string, required): Unique identifier for the preset
pattern (string, required): Pattern type identifier (sent to remote devices)
colors (array of strings, required): Array of hex color codes (minimum 2 colors)
delay (integer, required): Delay in milliseconds (10-1000)
n1 (integer, optional): Pattern parameter 1 (0-255, default: 0)
n2 (integer, optional): Pattern parameter 2 (0-255, default: 0)
n3 (integer, optional): Pattern parameter 3 (0-255, default: 0)
n4 (integer, optional): Pattern parameter 4 (0-255, default: 0)
n5 (integer, optional): Pattern parameter 5 (0-255, default: 0)
n6 (integer, optional): Pattern parameter 6 (0-255, default: 0)
n7 (integer, optional): Pattern parameter 7 (0-255, default: 0)
n8 (integer, optional): Pattern parameter 8 (0-255, default: 0)

Preset Operations

Create: User configures settings, clicks "Save as Preset", enters name → saved on master device
Load: User selects preset → settings loaded and applied to device/group
Apply: User selects preset, clicks "Apply" → configuration sent to device(s), updates immediately
Edit: User selects preset, clicks "Edit", modifies settings, saves → updated on master device
Delete: User selects preset, clicks "Delete", confirms → removed from master device
Sync: User clicks "Sync Presets to All Devices" → master sends all presets to all devices via ESPNow
- Each device stores presets in local database
- Ensures all devices have same preset definitions
- Useful after creating/editing presets to keep devices in sync

Preset Storage

Primary Storage: usqlite database on device (/presets.db or integrated in main database)
Backup/Export: JSON file format for portability (/presets.json)

Preset Synchronization:

Presets are created/edited on master device
Master can sync all presets to all devices via ESPNow
Each device stores presets in local database
Ensures all devices have same preset definitions available
Sync operation sends all presets to target devices

Preset Synchronization:

Presets are created/edited on master device
Master can sync all presets to all devices via ESPNow
Each device stores presets in local database
Ensures all devices have same preset definitions available
Sync operation sends all presets to target devices

Format:

{
  "presets": [
    {
      "name": "Fast Rainbow",
      "pattern": "rainbow",
      "colors": ["FF0000", "00FF00", "0000FF"],
      "delay": 50,
      "n1": 5,
      "n2": 0,
      "n3": 0,
      "n4": 0,
      "n5": 0,
      "n6": 0,
      "n7": 0,
      "n8": 0
    },
    {
      "name": "Slow Pulse",
      "pattern": "pulse",
      "colors": ["FF0000", "0000FF"],
      "delay": 200,
      "n1": 500,
      "n2": 300,
      "n3": 500,
      "n4": 0,
      "n5": 0,
      "n6": 0,
      "n7": 0,
      "n8": 0
    }
  ]
}

Preset Examples

Example 1: Fast Rainbow

{
  "name": "Fast Rainbow",
  "pattern": "rainbow",
  "colors": ["FF0000", "00FF00", "0000FF"],
  "delay": 30,
  "n1": 10,
  "n2": 0,
  "n3": 0,
  "n4": 0,
  "n5": 0,
  "n6": 0,
  "n7": 0,
  "n8": 0
}

Example 2: Chase Pattern

{
  "name": "Red Blue Chase",
  "pattern": "chase",
  "colors": ["FF0000", "0000FF"],
  "delay": 100,
  "n1": 5,
  "n2": 5,
  "n3": 2,
  "n4": -1,
  "n5": 0,
  "n6": 0,
  "n7": 0,
  "n8": 0
}

Example 3: Circle Loading

{
  "name": "Loading Circle",
  "pattern": "circle",
  "colors": ["00FF00"],
  "delay": 50,
  "n1": 50,
  "n2": 100,
  "n3": 200,
  "n4": 0,
  "n5": 0,
  "n6": 0,
  "n7": 0,
  "n8": 0
}

Example 4: Pulse with Custom Timing

{
  "name": "Smooth Pulse",
  "pattern": "pulse",
  "colors": ["FF00FF"],
  "delay": 100,
  "n1": 500,
  "n2": 200,
  "n3": 500,
  "n4": 0,
  "n5": 0,
  "n6": 0,
  "n7": 0,
  "n8": 0
}

Preset Integration

Dashboard Integration:

Quick preset selector dropdown
"Save Current as Preset" button
Preset preview on hover

Pattern Selector Integration:

"Load Preset" option
Preset suggestions based on selected pattern

Device Management Integration:

Apply preset to group
Preset templates for new groups

Device Management

Device Properties

Name: Unique identifier (string)
MAC Address: Hardware identifier (format: AA:BB:CC:DD:EE:FF)
Group: Optional group assignment
Status: Online/Offline (real-time)
Current Pattern: Active pattern configuration
Step Counter: Device-side counter tracking pattern step/position (integer, 0+, managed by remote device)
Settings: Full settings object

Group Properties

Name: Unique group identifier
Devices: List of device names (can include master and/or slaves)
Settings: Pattern, delay, colors
Step Offset: Per-device step offset sent to devices for synchronized patterns (integer, can be negative)
- Each device in group can receive different step offset
- Creates wave/chase effect across multiple LED strips
- Offset is sent as part of configuration to remote devices
Step Increment: Amount step counter increments per cycle (integer, default: 1, can be > 1)
- Sent to devices to control pattern speed/advancement rate
- Remote devices manage their own step counters
Apply Behavior: Send configuration to all group members
- Controller sends configuration to all devices in the group via HTTP/WebSocket
- All devices in the group receive configuration simultaneously
- Step offsets are sent per device when preset is applied to group
Note: Global brightness is device-specific, not group-specific

Communication

Message Format

Binary Message Structure:

Byte 0: Version (currently 0)
Byte 1: Flags (bit 0: names, bit 1: groups, bit 2: settings, bit 3: save)
[Variable]: Names list (if flag set)
[Variable]: Groups list (if flag set)
[Variable]: Settings dict (if flag set)

JSON Message Structure (Fallback):

{
  "names": ["led-device1"],
  "groups": ["group1"],
  "settings": {
    "pt": "on",
    "pm": "auto",
    "cl": ["000000", "FF0000"],
    "br": 100,
    "dl": 100,
    "n1": 0,
    "n2": 0,
    "n3": 0,
    "n4": 0,
    "n5": 0,
    "n6": 0,
    "n7": 0,
    "n8": 0
  },
  "save": false
}

Message Targeting

By Name: Target specific device(s) by device ID
By Group: Target all devices in group(s)
Broadcast: Send to all devices (empty names/groups)
Controller Role: Controller sends configuration messages to remote devices via HTTP/WebSocket
Device Role: Remote devices receive and process configuration messages from controller

Settings Keys

Key	Type	Description	Range/Values
`pt`	string	Pattern type	on, off, blink, chase, circle, pulse, rainbow, transition
`pm`	string	Pattern mode	auto, single_shot
`cl`	array	Colors (hex strings)	Array of hex color codes
`br`	int	Global brightness	0-100
`dl`	int	Delay (ms)	10-1000
`n1`	int	Parameter 1	0-255
`n2`	int	Parameter 2	0-255
`n3`	int	Parameter 3	0-255
`n4`	int	Parameter 4	0-255
`n5`	int	Parameter 5	0-255
`n6`	int	Parameter 6	0-255
`n7`	int	Parameter 7	0-255
`n8`	int	Parameter 8	0-255
`led_pin`	int	GPIO pin	0-40
`num_leds`	int	LED count	1-1000
`color_order`	string	Color order	rgb, rbg, grb, gbr, brg, bgr
`name`	string	Device name	Any string
`brightness`	int	Global brightness	0-100
`delay`	int	Delay	10-1000
`step_counter`	int	Current step counter value	0+
`step_offset`	int	Step offset for group synchronization	Any integer
`step_increment`	int	Step counter increment per cycle	1+ (default: 1)
`sequence_active`	boolean	Sequence is currently running	true/false
`sequence_index`	int	Current preset index in sequence	0-N
`sequence_start_time`	int	Timestamp when sequence started	milliseconds
`bpm`	int	Current BPM from beat detector	0-300
`bpm_synced`	boolean	Pattern delays synced to BPM	true/false
`bpm_multiplier`	float	BPM multiplier for delay calculation	0.1-10.0

Data Format Specifications

Settings File Format

Location: /settings.json on device

Master Device Structure:

{
  "led_pin": 10,
  "num_leds": 50,
  "pattern": "on",
  "delay": 100,
  "brightness": 100,
  "color_order": "rgb",
  "name": "led-device1",
  "ap_name": "led-device1",  // Must match name (SSID = hostname for master)
  "ap_password": "",
  "ap_enabled": true,
  "groups": ["group1"],  // Master can be in groups (same as slaves)
  "debug": false,
  "n1": 0,
  "n2": 0,
  "n3": 0,
  "n4": 0,
  "n5": 0,
  "n6": 0,
  "n7": 0,
  "n8": 0,
  "step_counter": 0,
  "step_increment": 1
}

Note: For master devices, name and ap_name must always be the same value. The device name serves as both the WiFi SSID (Access Point name) and the network hostname. Changing the device name automatically updates both SSID and hostname.

Step Counter Fields:

step_counter: Current step position in pattern (integer, 0+, managed by remote device)
step_increment: Amount to increment step counter per cycle (integer, 1+, default: 1, sent to device)
step_offset: Sent to device when preset is used in a group (integer, can be negative, default: 0)

Slave Device Structure:

{
  "led_pin": 10,
  "num_leds": 50,
  "pattern": "on",
  "delay": 100,
  "brightness": 100,
  "color_order": "rgb",
  "name": "led-device2",
  "ap_name": "",  // Not used (AP disabled for slaves)
  "ap_password": "",
  "ap_enabled": false,
  "groups": [],
  "debug": false,
  "n1": 0,
  "n2": 0,
  "n3": 0,
  "n4": 0,
  "n5": 0,
  "n6": 0,
  "n7": 0,
  "n8": 0,
  "step_counter": 0,
  "step_increment": 1
}

Group File Format

Location: /groups.json (if implemented)

Structure:

{
  "grps": [
    {
      "n": "group1",
      "pt": "on",
      "cl": ["000000", "FF0000"],
      "br": 100,
      "dl": 100,
      "n1": 0,
      "n2": 0,
      "n3": 0,
      "n4": 0,
      "n5": 0,
      "n6": 0,
      "n7": 0,
      "n8": 0
    }
  ]
}

Profile and Scene Storage Format

Database Storage (usqlite): Profiles and scenes are stored in SQLite database with the following schemas:

Profiles Table:

CREATE TABLE IF NOT EXISTS profiles (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE NOT NULL,
    description TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Scenes Table:

CREATE TABLE IF NOT EXISTS scenes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    profile_id INTEGER NOT NULL,
    name TEXT NOT NULL,
    description TEXT,
    transition_time INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (profile_id) REFERENCES profiles(id) ON DELETE CASCADE,
    UNIQUE(profile_id, name)
);

Scene Group Assignments Table:

CREATE TABLE IF NOT EXISTS scene_groups (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    scene_id INTEGER NOT NULL,
    group_name TEXT NOT NULL,
    presets TEXT NOT NULL,  -- JSON array of preset names
    sequence_duration INTEGER DEFAULT 0,  -- Duration per preset in ms
    sequence_transition INTEGER DEFAULT 0,  -- Transition time in ms
    sequence_loop BOOLEAN DEFAULT 0,
    sequence_repeat_count INTEGER DEFAULT 0,  -- 0 = infinite
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (scene_id) REFERENCES scenes(id) ON DELETE CASCADE
);

JSON Export Format (for backup/portability):

{
  "profiles": [
    {
      "name": "Party Mode",
      "description": "Party lighting profiles",
      "scenes": [
        {
          "name": "Warm Welcome",
          "transition_time": 0,
          "groups": [
            {
              "group_name": "entrance",
              "presets": ["Warm White"],
              "sequence_timing": null
            },
            {
              "group_name": "main",
              "presets": ["Soft Rainbow"],
              "sequence_timing": null
            }
          ]
        },
        {
          "name": "Dance Floor",
          "transition_time": 500,
          "groups": [
            {
              "group_name": "entrance",
              "presets": ["Fast Rainbow"],
              "sequence_timing": null
            },
            {
              "group_name": "accent",
              "presets": ["Pulse Purple", "Pulse Blue"],
              "sequence_timing": {
                "duration": 3000,
                "transition": 500,
                "loop": true,
                "repeat_count": 0
              }
            }
          ]
        }
      ]
    }
  ]
}

Preset Storage Format

Database Storage (usqlite): Presets are stored in SQLite database with the following schema:

CREATE TABLE IF NOT EXISTS presets (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE NOT NULL,
    pattern TEXT NOT NULL,
    pattern_mode TEXT DEFAULT 'auto',  -- 'auto' or 'single_shot'
    colors TEXT NOT NULL,  -- JSON array of hex color strings
    delay INTEGER NOT NULL,
    step_offset INTEGER DEFAULT 0,  -- Step offset for group synchronization
    step_increment INTEGER DEFAULT 1,  -- Step counter increment per cycle
    n1 INTEGER DEFAULT 0,
    n2 INTEGER DEFAULT 0,
    n3 INTEGER DEFAULT 0,
    n4 INTEGER DEFAULT 0,
    n5 INTEGER DEFAULT 0,
    n6 INTEGER DEFAULT 0,
    n7 INTEGER DEFAULT 0,
    n8 INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    usage_count INTEGER DEFAULT 0
);

JSON Export Format (for backup/portability): Location: /presets.json (optional export file)

Structure:

{
  "presets": [
    {
      "name": "Fast Rainbow",
      "pattern": "rainbow",
      "colors": ["FF0000", "00FF00", "0000FF"],
      "delay": 50,
      "n1": 5,
      "n2": 0,
      "n3": 0,
      "n4": 0,
      "n5": 0,
      "n6": 0,
      "n7": 0,
      "n8": 0
    },
    {
      "name": "Slow Pulse",
      "pattern": "pulse",
      "colors": ["FF0000", "0000FF"],
      "delay": 200,
      "n1": 500,
      "n2": 300,
      "n3": 500,
      "n4": 0,
      "n5": 0,
      "n6": 0,
      "n7": 0,
      "n8": 0
    }
  ]
}

Preset Fields:

name (string, required): Unique preset identifier
pattern (string, required): Pattern type
colors (array of strings, required): Hex color codes (minimum 2)
delay (integer, required): Delay in milliseconds (10-1000)
n1 through n8 (integer, optional): Pattern parameters (0-255, default: 0)

API Specifications

Web Interface API (Microdot-based)

Framework: Microdot (lightweight web framework for MicroPython)
Base URL: http://device-ip/ or http://192.168.4.1/ (when in AP mode)
Protocol: HTTP/1.1 with optional WebSocket support for real-time updates

Note: The web interface will be implemented using Microdot, providing a lightweight HTTP server directly on the ESP32 device. This enables direct browser access without requiring a separate host computer.

Endpoints

GET /api/status

Returns device status and current settings
Response: JSON object with device info

POST /api/settings

Update device settings
Body: JSON settings object
Response: Success/error message

GET /api/devices

List all known devices
Response: Array of device objects

POST /api/pattern

Apply pattern immediately
Body: Pattern name and parameters
Response: Success confirmation

GET /api/presets

List all saved presets
Response: Array of preset objects

POST /api/presets

Create a new preset
Body: Preset object (name, pattern, colors, delay, n1-n8)
Response: Created preset object

GET /api/presets/{name}

Get specific preset by name
Response: Preset object

PUT /api/presets/{name}

Update existing preset
Body: Updated preset object
Response: Updated preset object

DELETE /api/presets/{name}

Delete preset
Response: Success confirmation

POST /api/presets/{name}/apply

Apply preset to device(s)
Body: Target device names or groups, optional step_offset overrides per device
Response: Success confirmation
Behavior: Applies preset with step offsets when used in groups (each device gets different offset)

POST /api/presets/sync

Sync all presets from master to all devices
Body: Optional device names array (if empty, syncs to all devices)
Response: Success confirmation with sync status for each device
Behavior: Master sends all presets via ESPNow to target devices, devices store presets in their local database
Use case: Ensure all devices have same preset definitions available

GET /api/profiles

List all profiles
Response: Array of profile objects with scenes

POST /api/profiles

Create a new profile
Body: Profile object (name, description, scenes)
Response: Created profile object

GET /api/profiles/{name}

Get specific profile by name
Response: Profile object with all scenes

PUT /api/profiles/{name}

Update existing profile
Body: Updated profile object
Response: Updated profile object

DELETE /api/profiles/{name}

Delete profile
Response: Success confirmation

POST /api/profiles/{name}/scenes/{scene_name}/activate

Activate a scene within a profile (immediate)
Body: Optional override parameters
Response: Success confirmation
Behavior: Applies presets to all groups in scene, starts sequences if configured

POST /api/profiles/{name}/scenes/{scene_name}/queue

Queue a scene to activate at end of current phase
Body: Optional override parameters
Response: Success confirmation with phase information
Behavior: Scene queued, will activate when phase_beat reaches phase_length - 1

GET /api/beat-counter

Get current beat counter and phase information
Response: JSON object with beat_counter, phase_length, current_phase, phase_beat, queued_scene

POST /api/beat-counter/sync

Sync/reset beat counter
Body: JSON object with beat_number (optional, default: 0) and phase_length (optional)
Response: Success confirmation
Behavior: Resets beat counter and/or updates phase_length on all devices

POST /api/beat-counter/clear-queue

Clear queued scene
Response: Success confirmation
Behavior: Removes queued scene, prevents activation at phase end

GET /api/device/{name}/step-counter

Get current step counter value for device
Response: JSON object with step_counter (integer)

POST /api/device/{name}/step-counter/sync

Sync/reset step counter for device
Body: JSON object with step_counter (optional, default: 0)
Response: Success confirmation

POST /api/group/{name}/step-offsets

Set step offsets for devices in group
Body: JSON object mapping device names to step offsets: {"device1": 0, "device2": 10, "device3": 20}
Response: Success confirmation
Behavior: Sets step offsets for each device in group, creating synchronized wave effect

Direct Device Control: All device control operations support direct value setting without presets or scenes:

Individual device values can be set independently
Multiple devices can be controlled with different values simultaneously
Direct control bypasses preset and scene systems
Presets and scenes are optional organizational features

GET /api/brightness

Get current global brightness setting
Response: JSON object with global_brightness (0-100)

POST /api/brightness

Set global brightness
Body: JSON object with global_brightness (0-100)
Response: Success confirmation

WebSocket /ws

Real-time status updates
Pattern change notifications
Device status changes
Message format: JSON

GET /

Web UI root (serves HTML interface)
Returns: HTML dashboard interface

GET /static/{file}

Static assets (CSS, JS, images)
Returns: Static file content

Microdot Implementation Notes

Built-in Module: Microdot is frozen into the ESP32-C3 firmware image
Server Startup: Microdot server runs on port 80 (default) or configurable port
Concurrent Requests: Microdot handles requests asynchronously
WebSocket Support: Microdot includes WebSocket support for real-time updates
Template Rendering: Can use utemplate (included with Microdot) for server-side rendering
Static Files: Static assets can be served from /static directory or frozen into firmware
No Installation Required: Microdot is available immediately after firmware flash

Database Integration (usqlite)

Database Library: usqlite - μSQLite library module for MicroPython (built into ESP32-C3 firmware)

Repository: https://github.com/spatialdude/usqlite

Database Usage:

Preset storage in SQLite database
Event logging and history
Settings persistence (optional, can use JSON file as fallback)
Pattern usage statistics

Database Schema:

presets table: Stores preset configurations
events table: Logs device events and actions
pattern_history table: Tracks pattern usage
settings table: Optional persistent settings storage

usqlite Features:

API Compatibility: Highly compatible with standard Python sqlite3 library
Memory Management: Uses MicroPython's GC heap by default, optimized for constrained environments
Memory Monitoring: Built-in functions for tracking memory usage (mem_current(), mem_peak(), mem_status())
Row Types: Supports tuple (default), dict, or custom row objects
Parameter Substitution: Supports ?, ?NNN, :name, @name, and $name parameter styles
Built into ESP32-C3 firmware image (frozen module via CMake integration)
No installation required - available immediately after firmware flash
ESP32 Support: Officially supported port (along with Raspberry Pi Pico, Unix, Windows, Pybricks)

usqlite API Usage:

import usqlite

# Connect to database
conn = usqlite.connect('/led_driver.db')

# Set row type to dict for easier access
conn.row_type = 'dict'

# Execute queries
cursor = conn.execute("SELECT * FROM presets WHERE name = ?", ("Fast Rainbow",))
preset = cursor.fetchone()

# Memory monitoring
current_mem = usqlite.mem_current()
peak_mem = usqlite.mem_peak()

User Flows

Flow 1: Change Pattern (Master Controls Slaves)

User opens Dashboard on master device (via web browser)
User clicks pattern button (e.g., "Rainbow")
Pattern button highlights (active state)
User selects target device(s) or group
User adjusts global brightness or speed if needed
User clicks "Apply Settings"
Master device sends ESPNow message to selected slave device(s)
Master device also updates its own pattern
Slave device(s) receive message and update pattern immediately
UI shows confirmation for each device

Flow 1a: Adjust Global Brightness

User adjusts Global Brightness slider on Dashboard
User clicks "Apply Settings" or "Save to Device"
System sends brightness to device(s), all patterns adjust uniformly
UI shows confirmation

Flow 2: Create Device Group

User navigates to Device Management → Groups tab
User clicks "Create Group", enters name, selects pattern/settings
User selects devices to add (can include master), clicks "Create"
Group appears in list
User clicks "Apply" → master applies to itself (if in group), sends ESPNow to slaves
All devices in group update simultaneously

Flow 3: Configure Device Settings

User navigates to Settings page
User modifies settings in sections:
- Basic Settings (pin, LED count, color order)
- Pattern Settings (pattern, delay)
- Global Brightness
- Advanced Settings (N1-N8 parameters)
- Network Settings (AP configuration)
User clicks "Save Settings"
System sends settings with save: true flag
Device persists settings to /settings.json
UI shows success message

Flow 4: Multi-Device Control

User selects multiple devices or a group
User changes pattern/colors/global brightness
User clicks "Apply Settings"
System sends message targeting selected devices/groups
All targeted devices update simultaneously
UI shows status for each device

Flow 5: Create and Use Preset

User configures pattern settings, clicks "Save as Preset"
User enters unique name, clicks "Save" → preset saved on master
User optionally clicks "Sync Presets to All Devices" → master sends all presets to all devices
User selects preset from list, clicks "Apply Preset"
Preset values applied to device(s), UI updates

Flow 6: Apply Preset to Group

User navigates to Device Management or Presets page
User selects a group (e.g., "group1")
User opens preset selector
User selects preset from list
User clicks "Apply to Group"
Master device checks if it belongs to the selected group
If master is in the group, master applies preset configuration to itself
Master device sends preset configuration via ESPNow to all slave devices in the group
All devices in group (including master) update simultaneously
UI shows confirmation for each device (master + slaves)

Flow 7: Create and Activate Profile Scene

User navigates to Profiles page
User clicks "Create Profile"
User enters profile name and description
User clicks "Add Scene"
User enters scene name
User assigns groups to presets:
- Selects group "entrance" → assigns Preset "Warm White"
- Selects group "main" → assigns Preset "Soft Rainbow"
- Selects group "accent" → assigns multiple presets with sequencing
User configures sequencing for groups that need it:
- Sets duration: 3000ms per preset
- Sets transition: 500ms between presets
- Enables loop: true
User saves scene
User saves profile
User clicks "Activate Scene"
Master device processes scene:
- Checks which groups master belongs to
- Applies presets to itself for groups it's in
- Sends ESPNow messages to slave devices in each group
All devices update to scene configuration
Sequencing begins automatically for groups with multiple presets
UI shows active scene and sequence progress

Flow 8: Sequence Between Presets

Scene activated with group having multiple presets
Master applies first preset to itself (if in group), sends to slaves
After duration expires, master transitions to next preset with fade effect
Process repeats for all presets, loops if enabled
Continues until scene changes or manual stop

Design Guidelines

Color Palette

Primary: Purple gradient #667eea to #764ba2, Light gradient #f5f7fa to #c3cfe2
UI: Primary #667eea, Hover #5568d3, Secondary #e0e0e0
Text: Primary #333333, Secondary #666666
Status: Success #4caf50, Error #f44336
Background: White #ffffff

Typography

Font: System stack (-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif)
Sizes: H1 2.5rem, H2 1.5rem, H3 1.25rem, Body 1rem, Small 0.875rem, Tiny 0.75rem

Spacing

Card padding: 24px, Section gap: 24px, Form field gap: 20px
Button padding: 12px vertical, 24px horizontal
Border radius: 8px (buttons), 12px (cards)

Interactive Elements

Buttons:

Hover: Slight lift (translateY -2px), increased shadow
Active: Slight press (translateY 0px)
Disabled: 50% opacity, no pointer events

Inputs:

Focus: Border color changes to primary purple
Hover: Slight border color change
Error: Red border

Cards:

Hover: Lift effect, increased shadow
Selected: Border highlight, background change

Responsive Design

Breakpoints:

Mobile: < 768px (single column)
Tablet: 768px - 1024px (2 columns)
Desktop: > 1024px (3-4 columns)

Grid Behavior:

Auto-fit columns with minimum width
Cards stack vertically on mobile
Maintains readability at all sizes

Technical Requirements

Hardware Requirements

ESP32 Device:

ESP32-C3 microcontroller (recommended)
Custom MicroPython firmware with usqlite and microdot built-in
GPIO pin for LED data line
WiFi capability (for ESPNow and web server)

LED Strip:

WS2812/NeoPixel compatible
Any length (1-1000 LEDs supported)
5V power supply (external)

Host Computer:

Python 3.x
pipenv for dependency management
Network connection (for web interface, if implemented)

Software Requirements

MicroPython Modules:

machine (GPIO, WDT)
network (WiFi, ESPNow)
json (settings storage)
struct (binary encoding)
espnow (peer-to-peer communication)
usqlite (SQLite database support - built into ESP32-C3 firmware)
microdot (web framework for HTTP/WebSocket server - built into ESP32-C3 firmware)

Python Libraries:

mpremote (device communication)
pyserial (serial communication)
esptool (firmware flashing)
playwright (for image generation, optional)

MicroPython Firmware Requirements:

ESP32-C3 MicroPython firmware with usqlite and microdot built-in (frozen modules)
ESPNow support enabled
Network stack configured for AP/STA modes
Note: usqlite and microdot are included in the firmware image, no separate installation required

Performance Requirements

Message Processing:

Binary message decode: < 10ms
Pattern update: < 50ms
Settings save: < 100ms

Pattern Configuration:

Configuration sent to remote devices via HTTP/WebSocket
Remote devices handle pattern execution and LED updates

Communication:

ESPNow message size: < 250 bytes (ESP32 limit)
Binary format: ~70% smaller than JSON
Message delivery: < 100ms latency

Storage Requirements

Device Storage:

Settings file: ~500 bytes (JSON) or SQLite database
Firmware: ~1-2MB (usqlite and microdot are frozen into firmware)
Available space: ESP32-C3 typically has 1-4MB free flash
SQLite database: ~10-100KB (depends on usage)
Note: usqlite and microdot are part of the firmware image, not stored separately

Database Storage (usqlite):

Presets table: ~200-300 bytes per preset
Events table: ~100 bytes per event
Pattern history: ~150 bytes per entry
Recommended limits:
- 50 presets maximum
- 1000 events (with automatic cleanup)
- 500 pattern history entries

Host Storage (Presets - Optional):

Preset file: ~1-10KB (depends on number of presets)
Each preset: ~200-300 bytes
Can sync with device database via API

Testing Requirements

Unit Tests

Pattern Configuration Tests:

Pattern configuration is correctly formatted
Parameters are properly sent to remote devices
Edge cases (invalid patterns, missing parameters, etc.)

Message Encoding/Decoding:

Binary encoding matches JSON structure
Decoding handles all data types
Error handling for malformed messages

Settings Management:

Load/save operations
Default values
Validation

Preset Management:

Preset creation with all fields (name, pattern, colors, delay, n1-n8)
Preset loading and application
Preset editing and deletion
Name uniqueness validation
Preset file format validation

Integration Tests

Device Communication:

ESPNow message delivery
Binary vs JSON fallback
Group targeting
Multi-device synchronization

Pattern Configuration Application:

Pattern configuration is sent to devices correctly
Settings persist after reboot
Configuration parameters are properly formatted

Preset Application:

Preset loads all parameters correctly (pattern, colors, delay, n1-n8)
Preset applies to single device
Preset applies to device group
Preset values match saved configuration

UI Tests

Responsiveness:

All breakpoints render correctly
Touch targets adequate (44x44px minimum)
Forms validate input

Interactivity:

Buttons respond to clicks
Sliders update values
Modals open/close
Tabs switch correctly
Preset selector works
Preset creation form validates input
Preset cards display correctly

Future Enhancements

Planned Features

Web Interface Implementation
- Microdot-based web server on device
- Real-time status updates via WebSocket
- RESTful API endpoints for device control
- OTA (Over-The-Air) updates
Pattern Editor
- Custom pattern creation
- Pattern library sharing
- Visual pattern preview
Advanced Grouping
- Group hierarchies
- Conditional group actions
- Scheduled group changes
Analytics
- Usage statistics
- Pattern popularity
- Device health monitoring
Mobile App
- Native iOS/Android app
- Push notifications
- Offline mode

Appendix

Abbreviations

ESPNow: ESP32 peer-to-peer communication protocol
GPIO: General Purpose Input/Output
LED: Light Emitting Diode
WS2812: Addressable RGB LED chip
WDT: Watchdog Timer
AP: Access Point
OTA: Over-The-Air

References

Core Technologies:

usqlite - μSQLite library for MicroPython - SQLite database implementation
Microdot - Lightweight web framework for MicroPython
ESP32 MicroPython Documentation
WS2812 LED Datasheet
ESPNow Protocol Specification

Project Files:

Mockup files: docs/mockups/*.html
Generated images: docs/mockups/images/*.png

Document Status: This specification is a living document and will be updated as the project evolves.

Last Updated: December 2024

62 KiB Raw Blame History

LED Driver System - Specification Document

Table of Contents

Overview

Purpose

Target Users

Key Features

System Architecture

Technology Stack

Components

Master/Slave Architecture

Communication Protocols

User Interface Specifications

1. Dashboard (Main Control Panel)

Purpose

Layout

Components

Design Specifications

2. Pattern Selector

Purpose

Layout

Pattern Cards

Selection Behavior

Design Specifications

3. Device Management

Purpose

Layout

Devices Tab

Groups Tab

Design Specifications

4. Profile and Scene Management

Purpose

Layout

Profile Card

Scene Card

Create/Edit Profile Modal

Create/Edit Scene Modal

Activate Scene

Design Specifications

5. Settings

Purpose

Layout

Sections

Form Controls

Design Specifications

5. Preset Management

Purpose

Layout

Preset Card

Create/Edit Preset Modal

Preset List View

Preset Synchronization

Design Specifications

Feature Specifications

Pattern Configuration

Pattern Parameters (N1-N8)

Preset System

Overview

Preset Structure

Preset Operations

Preset Storage

Preset Examples

Preset Integration

Device Management

Device Properties

Group Properties

Communication

Message Format

Message Targeting

Settings Keys

Data Format Specifications

Settings File Format

Group File Format

Profile and Scene Storage Format

Preset Storage Format

API Specifications

Web Interface API (Microdot-based)

Endpoints

Microdot Implementation Notes

Database Integration (usqlite)

62 KiB

Raw Blame History