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:

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:

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

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:

# 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:

// Line 61:
state.waterTemp = randomWalk(state.waterTemp, 5, 25, 0.05)

---

Testing Checklist

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