boWave/MOCK_DATA_EXPLANATION.md

# boWave Mock Data System

## Overview
The mock data system provides realistic NMEA 2000 data for development and testing without requiring real marine hardware or Docker services.

## What is NMEA 2000?
NMEA 2000 is the standard marine networking protocol used on boats to connect various instruments (GPS, depth sounder, wind instruments, engine systems, battery monitors, etc.). SignalK is an open standard that translates NMEA 0183/2000 into a JSON WebSocket interface.

## Mock Data Implementation

### Mock Data Sources (Three Simulators)

#### 1. **SignalK Mock (`src/mock/signalk.mock.js`)**
Simulates real-time boat navigation and systems data with realistic values:

**Navigation Data:**
- Speed Over Ground (SOG): 3.5-8 knots
- Course Over Ground (COG): 200-235°
- Heading: 198-237° (includes drift from wind/current)
- Position: Baltic Sea near Kiel (realistic for testing)
- Rudder Angle: -15° to +15°

**Environmental Data:**
- Depth Below Keel: 6-25 meters
- Water Temperature: 16-20°C
- Air Temperature: ~14°C
- Wind Speed: 8-22 knots
- Wind Angle: 25-70° (apparent wind)

**Engine & Electrical:**
- RPM: 1500-2100 (diesel engine range)
- Starter Battery: 12.2-12.9V (lead-acid)
- House Battery: 24.5-25.6V (dual 12V house system)
- Alternator Output: 30-60 amps
- Fuel Rate: 10-15 L/hour (typical Yanmar diesel)
- Engine Hours: Continuous counter

**Tank Levels:**
- Fuel: 0-100% with realistic consumption
- Fresh Water: 0-200L
- Waste Water: 0-50L
- Bilge/Grey Water monitoring

**Data Format:**
All values are transmitted in SI units (radians for angles, m/s for speed, Kelvin for temperature) to match NMEA 2000 standard. The mock converter shows these in human-readable units on the dashboard.

**Realistic Behavior:**
- Data changes smoothly using "random walk" algorithm (not random jumps)
- Position advances based on heading and speed
- All values respect minimum/maximum realistic bounds
- Battery voltage fluctuates realistically when engine runs
- Wind varies naturally like gusts

#### 2. **Snapcast Mock (`src/mock/snapcast.mock.js`)**
Simulates the multiroom audio server:

**Zones (4 Audio Areas):**
```
- Salon (Main cabin):    Volume 72%, Connected
- Cockpit (Helm):        Volume 58%, Connected
- Bug (Forepeak cabin):  Volume 45%, Muted
- Heck (Aft cabin):      Volume 60%, Disconnected
```

**Streams:**
- Spotify (idle)
- AirPlay (idle)
- Mopidy (playing)

**Behavior:**
- Responds to volume changes in real-time
- Emits status updates every 5 seconds
- Supports zone muting and source switching
- Initial status broadcast on first listener

#### 3. **Mopidy Mock (`src/mock/mopidy.mock.js`)**
Simulates local music playback:

**Mock Tracks:**
- Realistic artist/album/duration metadata
- Cover art URLs (placeholder images)
- Playback position tracking
- Play/pause/next/previous controls

---

## Bug Fixes Applied

### Issue 1: Zones Not Loading
**Problem:** `useZones` hook expected `msg.result.server` but snapcast mock emitted `buildStatus()` directly.

**Fix:** Updated snapcast mock to emit:
```javascript
emit('update', { result: buildStatus() })
```

Added initial status broadcast and periodic updates (5s interval).

### Issue 2: Mock Data Not Working
**Problem:** `VITE_USE_MOCK=false` meant mock data was disabled in dev mode.

**Fix:** Changed docker-compose.dev.yml to:
```yaml
VITE_USE_MOCK=true   # Use mock data for dev testing
```

Now mock data loads automatically in `make dev`.

### Issue 3: NMEA2000 Data Realism
**Enhanced Data Parameters:**
- Added fuel rate monitoring (10-15 L/hr)
- Added alternator output (30-60A)
- Added engine hours counter (continuous)
- Added tank level monitoring (fresh water, waste water)
- Added depth alarm threshold

All values fluctuate realistically using random walk algorithm to simulate actual sensor noise.

---

## How to Use

### Development with Mock Data
```bash
make dev
# Dashboard available at http://localhost:8090
# All data is simulated, no Docker services required
# Perfect for UI development and testing
```

### Testing With Real APIs
To test against real Docker services:
```bash
# In docker-compose.dev.yml, set:
VITE_USE_MOCK=false

# Ensure services are running:
make dev
```

### Understanding the Data Flow
```
Mock SignalK (NMEA2000)
    ↓
React Hook (useNMEA)
    ↓
Dashboard Components (Compass, Gauge, Speed)

Mock Snapcast (Multiroom Audio)
    ↓
React Hook (useZones)
    ↓
Zone Cards (Volume, Mute, Source)

Mock Mopidy (Music Playback)
    ↓
React Hook (usePlayer)
    ↓
Now Playing Card (Track Info)
```

---

## NMEA 2000 Standard Compliance

The mock data follows NMEA 2000 standards:

✓ **Correct SI Units:** Radians (angles), m/s (speed), Kelvin (temperature)
✓ **Realistic Ranges:** Values match typical marine equipment specifications
✓ **Industry Standard Format:** Values transmitted via SignalK WebSocket delta messages
✓ **Proper PGN Mapping:** Engine data follows PGN 127488, battery data follows PGN 127505
✓ **Baltic Sea Coordinates:** Demo position in realistic sailing area (Kiel Fjord)
✓ **Continuous Updates:** Delta stream every 1 second like real NMEA 2000 gateway

---

## Advanced: Custom Mock Data

To modify mock data ranges, edit:
- `src/mock/signalk.mock.js` — Change randomWalk min/max values
- `src/mock/snapcast.mock.js` — Change initial zone volumes/names
- `src/mock/mopidy.mock.js` — Add custom track metadata

Example: Change water temperature range from 16-20°C to 5-25°C:
```javascript
// Line 61:
state.waterTemp = randomWalk(state.waterTemp, 5, 25, 0.05)
```

---

## Testing Checklist

- [x] Zones load on app start (fixed)
- [x] Zone volume/mute controls work
- [x] Source switching works
- [x] NMEA data updates in real-time
- [x] Compass rotates smoothly
- [x] Gauge values change realistically
- [x] Speed/heading/depth display
- [x] Battery voltages realistic
- [x] Engine hours increment continuously
- [x] No console errors
- [x] Dashboard responsive to zone changes