# 🔔 VESPER ESP32 Communication API Reference v3.0

> **Complete command reference for Vesper Bell Automation System with Grouped Commands**  
> Version: 3.0 | Updated: 2025-09-15  
> Supports: MQTT + WebSocket protocols with multi-client support and batch processing

---

## 🚀 Getting Started

### Connection Protocols
- **MQTT**: `vesper/{device_id}/control` (commands) → `vesper/{device_id}/data` (responses)
- **WebSocket**: `ws://{esp_ip}/ws` (bidirectional)
- **UDP Discovery**: Broadcast on configured port for device discovery
- **UDP Port**: 32101

### WebSocket Client Identification
**Required for WebSocket clients to receive targeted messages:**

```json
{
  "cmd": "system",
  "contents": {
    "action": "identify",
    "device_type": "master"    // or "secondary"
  }
}
```

**Response:**
```json
{
  "status": "SUCCESS",
  "type": "identify",
  "payload": "Device identified as master"
}
```

---

## 📋 Command Categories (NEW GROUPED ARCHITECTURE)

- [🖥️ System Commands](#️-system-commands)
- [🎵 Playback Control](#-playback-control)
- [📁 File Management](#-file-management)
- [🔧 Relay Setup](#-relay-setup)
- [🕐 Clock Setup](#-clock-setup)
- [📢 Information Messages](#-information-messages)
- [🌐 Network & Discovery](#-network--discovery)
- [🔄 Legacy Command Support](#-legacy-command-support)

---

## 🖥️ System Commands

### 🏓 Ping Test

**Command:**
```json
{
  "cmd": "system",
  "contents": {
    "action": "ping"
  }
}
```

**Response:**
```json
{
  "status": "SUCCESS",
  "type": "pong",
  "payload": ""
}
```

### 📊 System Status

**Command:**
```json
{
  "cmd": "system",
  "contents": {
    "action": "status"
  }
}
```

**Response:**
```json
{
  "status": "SUCCESS",
  "type": "current_status",
  "payload": {
    "player_status": "playing",
    "time_elapsed": 45230,
    "projected_run_time": 34598,
    "timestamp": 1699123456789
  }
}
```

### 👤 Device Identification (WebSocket Only)

**Command:**
```json
{
  "cmd": "system",
  "contents": {
    "action": "identify",
    "device_type": "master"
  }
}
```

### 🔄 Restart Device

**Command:**
```json
{
  "cmd": "system",
  "contents": {
    "action": "restart"
  }
}
```

**Response:**
```json
{
  "status": "SUCCESS",
  "type": "restart",
  "payload": "Device will restart in 2 seconds"
}
```

**Note:** Device will reboot after sending the response.

### 🔄 Force OTA Update

**Command:**
```json
{
  "cmd": "system",
  "contents": {
    "action": "force_update",
    "channel": "stable"  // optional: "stable", "beta", or "emergency" (default: "stable")
  }
}
```

**Response:**
```json
{
  "status": "SUCCESS",
  "type": "force_update",
  "payload": "Starting forced OTA update from channel: stable. Device may reboot."
}
```

**Error Response (if player is active):**
```json
{
  "status": "ERROR",
  "type": "force_update",
  "payload": "Cannot update while playback is active"
}
```

**Note:** If update is successful, device will reboot automatically.

### 🔥 Custom Firmware Update

**Command:**
```json
{
  "cmd": "system",
  "contents": {
    "action": "custom_update",
    "firmware_url": "https://example.com/path/to/firmware.bin",
    "checksum": "a1b2c3d4e5f6...",  // optional: SHA256 checksum for verification
    "file_size": 1234567,           // optional: expected file size in bytes
    "version": 145                  // optional: firmware version number to save in NVS
  }
}
```

**Response:**
```json
{
  "status": "SUCCESS",
  "type": "custom_update",
  "payload": "Starting custom OTA update. Device may reboot."
}
```

**Error Responses:**
```json
{
  "status": "ERROR",
  "type": "custom_update",
  "payload": "Missing firmware_url parameter"
}
```

```json
{
  "status": "ERROR",
  "type": "custom_update",
  "payload": "Cannot update while playback is active"
}
```

**Features:**
- Download firmware from any URL (bypasses configured update servers)
- Optional SHA256 checksum verification
- Optional file size validation
- Optional version number to update NVS (prevents unwanted auto-downgrades)
- Automatically blocks updates during playback
- Device reboots on successful installation

**Version Parameter Behavior:**
- If `version` is provided (> 0): NVS firmware version will be updated to this value
- If `version` is omitted or 0: NVS firmware version remains unchanged
- **Important:** Without version parameter, future OTA checks may detect your custom firmware as "outdated" and trigger auto-updates/downgrades

**Note:** If update is successful, device will reboot automatically. Use with caution!

---

## 🎵 Playback Control

### ▶️ Start Playback

**Command:**
```json
{
  "cmd": "playback",
  "contents": {
    "action": "play",
    "name": "My Melody",
    "uid": "01DegzV9FA8tYbQpkIHR",
    "url": "https://example.com/melody.bin",
    "speed": 500,
    "note_assignments": [1, 2, 3, 4, 5, 6, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    "segment_duration": 15000,
    "pause_duration": 5000,
    "total_duration": 60000,
    "continuous_loop": true
  }
}
```

### ⏹️ Stop Playback

**Command:**
```json
{
  "cmd": "playback",
  "contents": {
    "action": "stop"
  }
}
```

---

## 📁 File Management

### 📋 List Available Melodies

**Command:**
```json
{
  "cmd": "file_manager",
  "contents": {
    "action": "list_melodies"
  }
}
```

**Success Response:**
```json
{
  "status": "SUCCESS",
  "type": "list_melodies",
  "payload": ["melody1.bin", "melody2.bin", "melody3.bin"]
}
```

### 📥 Download Melody

**Command:**
```json
{
  "cmd": "file_manager",
  "contents": {
    "action": "download_melody",
    "download_url": "https://example.com/melody.bin",
    "melodys_uid": "01DegzV9FA8tYbQpkIHR",
    "name": "Optional Display Name"
  }
}
```

### 🗑️ Delete Melody

**Command:**
```json
{
  "cmd": "file_manager",
  "contents": {
    "action": "delete_melody",
    "name": "01DegzV9FA8tYbQpkIHR"
  }
}
```

---

## 🔧 Relay Setup

### ⏱️ Set Relay Timers (Single Bell)

**Command:**
```json
{
  "cmd": "relay_setup",
  "contents": {
    "action": "set_timers",
    "b1": 100,
    "b2": 200,
    "b3": 150
  }
}
```

### ⏱️ Set Relay Timers (Batch Mode)

**Command:**
```json
{
  "cmd": "relay_setup",
  "contents": {
    "action": "set_timers",
    "timers": {
      "b1": 100,
      "b2": 200,
      "b3": 150,
      "b4": 300,
      "b5": 250,
      "b6": 180
    }
  }
}
```

### 🔌 Set Relay Outputs (Single Bell)

**Command:**
```json
{
  "cmd": "relay_setup",
  "contents": {
    "action": "set_outputs",
    "b1": 1,
    "b2": 2,
    "b3": 3
  }
}
```

### 🔌 Set Relay Outputs (Batch Mode)

**Command:**
```json
{
  "cmd": "relay_setup",
  "contents": {
    "action": "set_outputs",
    "outputs": {
      "b1": 1,
      "b2": 2,
      "b3": 3,
      "b4": 4,
      "b5": 5,
      "b6": 6
    }
  }
}
```

---

## 🕐 Clock Setup

### 🔌 Set Clock Outputs

**Command:**
```json
{
  "cmd": "clock_setup",
  "contents": {
    "action": "set_outputs",
    "c1": 1,
    "c2": 2
  }
}
```

### ⏰ Set Clock Timings

**Command:**
```json
{
  "cmd": "clock_setup",
  "contents": {
    "action": "set_timings",
    "pulseDuration": 5000,
    "pauseDuration": 2000
  }
}
```

### 🔔 Set Clock Alerts

**Command:**
```json
{
  "cmd": "clock_setup",
  "contents": {
    "action": "set_alerts",
    "alertType": "HOURS",
    "alertRingInterval": 1000,
    "hourBell": 1,
    "halfBell": 2,
    "quarterBell": 3
  }
}
```

### 💡 Set Clock Backlight

**Command:**
```json
{
  "cmd": "clock_setup",
  "contents": {
    "action": "set_backlight",
    "enabled": true,
    "output": 5,
    "onTime": "18:00",
    "offTime": "06:00"
  }
}
```

### 🔇 Set Clock Silence Periods

**Command:**
```json
{
  "cmd": "clock_setup",
  "contents": {
    "action": "set_silence",
    "daytime": {
      "enabled": true,
      "onTime": "13:00",
      "offTime": "15:00"
    },
    "nighttime": {
      "enabled": true,
      "onTime": "22:00",
      "offTime": "07:00"
    }
  }
}
```

### 🚀 Batch Clock Setup (Multiple Settings at Once)

**Command:**
```json
{
  "cmd": "clock_setup",
  "contents": {
    "action": "batch_setup",
    "outputs": {
      "c1": 1,
      "c2": 2
    },
    "timings": {
      "pulseDuration": 5000,
      "pauseDuration": 2000
    },
    "alerts": {
      "alertType": "HOURS",
      "hourBell": 1,
      "halfBell": 2
    },
    "backlight": {
      "enabled": true,
      "output": 5,
      "onTime": "18:00",
      "offTime": "06:00"
    },
    "silence": {
      "daytime": {
        "enabled": true,
        "onTime": "13:00",
        "offTime": "15:00"
      },
      "nighttime": {
        "enabled": true,
        "onTime": "22:00",
        "offTime": "07:00"
      }
    }
  }
}
```

**Success Response:**
```json
{
  "status": "SUCCESS",
  "type": "clock_setup",
  "payload": "Batch clock setup updated: 5 sections"
}
```

---

## 📢 Information Messages

> **Automatic status broadcasts sent to ALL clients**  
> These messages are initiated by the ESP32 system and broadcast to all connected clients without being requested.

### 🎵 Playback Status Updates

**Sent automatically during playback state changes:**

```json
{
  "status": "INFO",
  "type": "playback",
  "payload": {
    "action": "playing",
    "time_elapsed": 125,
    "projected_run_time": 5158
  }
}
```

### ⚠️ Bell Overload Warnings

**Sent automatically when bell load monitoring detects issues:**

```json
{
  "status": "INFO",
  "type": "bell_overload",
  "payload": {
    "bells": [1, 3, 5],
    "loads": [85, 92, 78],
    "severity": "warning"
  }
}
```

---

## 🌐 Network & Discovery

### 🔍 UDP Discovery

**UDP Broadcast Request:**
```json
{
  "op": "discover",
  "svc": "vesper"
}
```

**UDP Response:**
```json
{
  "op": "discover_reply",
  "svc": "vesper",
  "ver": 1,
  "name": "Proj. Vesper v0.5",
  "id": "ESP32_ABC123",
  "ip": "192.168.1.100",
  "ws": "ws://192.168.1.100/ws",
  "port": 80,
  "fw": "1.2.3",
  "clients": 2
}
```

---

## 🔄 Legacy Command Support

**For backward compatibility, the following legacy commands are still supported:**

### Individual Commands (Legacy)
- `cmd: "ping"` → Use `system` with `action: "ping"`
- `cmd: "report_status"` → Use `system` with `action: "status"`
- `cmd: "identify"` → Use `system` with `action: "identify"`
- `cmd: "list_melodies"` → Use `file_manager` with `action: "list_melodies"`
- `cmd: "download_melody"` → Use `file_manager` with `action: "download_melody"`
- `cmd: "delete_melody"` → Use `file_manager` with `action: "delete_melody"`
- `cmd: "set_relay_timers"` → Use `relay_setup` with `action: "set_timers"`
- `cmd: "set_relay_outputs"` → Use `relay_setup` with `action: "set_outputs"`
- `cmd: "set_clock_outputs"` → Use `clock_setup` with `action: "set_outputs"`
- `cmd: "set_clock_timings"` → Use `clock_setup` with `action: "set_timings"`
- `cmd: "set_clock_alerts"` → Use `clock_setup` with `action: "set_alerts"`
- `cmd: "set_clock_backlight"` → Use `clock_setup` with `action: "set_backlight"`
- `cmd: "set_clock_silence"` → Use `clock_setup` with `action: "set_silence"`

**Legacy commands will continue to work but are deprecated. Please migrate to the new grouped command structure for optimal performance and features.**

---

## 🔧 Key Advantages of Grouped Commands

### 🚀 **Batch Processing**
- Send multiple settings in a single command
- Reduce network overhead and latency
- Atomic operations ensure consistency

### 📊 **Better Organization**
- Logical grouping of related commands
- Cleaner API structure
- Easier to understand and maintain

### ⚡ **Enhanced Performance**
- Fewer round-trips for complex configurations
- Optimized ESP32 processing
- Improved user experience

### 🔄 **Backward Compatibility**
- Legacy commands still supported
- Gradual migration path
- No breaking changes for existing implementations

---

## 🔧 Integration Examples

### Dart/Flutter App Integration

```dart
// New grouped command approach
await ClockSetup.batchClockSetup(
  c1Output: 1,
  c2Output: 2,
  pulseDuration: 5000,
  pauseDuration: 2000,
  alertType: 'HOURS',
  hourBell: 1,
  backlightEnabled: true,
  backlightOutput: 5,
);

// Batch relay setup
await RelaySetup.setBatchRelayOutputs({
  1: 1, 2: 2, 3: 3, 4: 4, 5: 5, 6: 6,
});

// Individual settings still work
await ClockSetup.setOddClockOutput(1);
await ClockSetup.setEvenClockOutput(2);
```

### JavaScript/WebSocket Integration

```javascript
// Batch clock configuration
const clockConfig = {
  cmd: "clock_setup",
  contents: {
    action: "batch_setup",
    outputs: { c1: 1, c2: 2 },
    timings: { pulseDuration: 5000, pauseDuration: 2000 },
    alerts: { alertType: "HOURS", hourBell: 1 },
    backlight: { enabled: true, output: 5 }
  }
};

webSocket.send(JSON.stringify(clockConfig));

// Batch relay configuration
const relayConfig = {
  cmd: "relay_setup",
  contents: {
    action: "set_outputs",
    outputs: {
      b1: 1, b2: 2, b3: 3, b4: 4, b5: 5, b6: 6
    }
  }
};

webSocket.send(JSON.stringify(relayConfig));
```

---

## 🚨 Error Handling

### Common Error Types

**Missing Action Parameter:**
```json
{
  "status": "ERROR",
  "type": "relay_setup",
  "payload": "Missing action parameter"
}
```

**Unknown Action:**
```json
{
  "status": "ERROR",
  "type": "clock_setup",
  "payload": "Unknown action: invalid_action"
}
```

**Batch Processing Errors:**
```json
{
  "status": "ERROR",
  "type": "relay_setup",
  "payload": "No valid relay timers found in batch"
}
```

**Success with Count:**
```json
{
  "status": "SUCCESS",
  "type": "relay_setup",
  "payload": "Batch relay outputs updated: 6 bells"
}
```

---

## 📡 Message Routing

### Response Routing Rules

1. **Command Responses**: Sent only to the originating client/protocol
   - MQTT command → MQTT response
   - WebSocket client #3 → WebSocket client #3 only

2. **Status Broadcasts**: Sent to ALL connected clients
   - All WebSocket clients receive the message
   - MQTT subscribers receive the message
   - Used for system notifications and status updates

3. **Targeted Messages**: Based on device type
   - `broadcastToMasterClients()`: Only master devices
   - `broadcastToSecondaryClients()`: Only secondary devices
   - `broadcastToAllWebSocketClients()`: All WebSocket clients

---

## ⚡ Performance Optimizations

### Batch Command Benefits

**Before (Legacy - 6 separate commands):**
```javascript
// 6 separate network calls
await setRelayOutput(1, 1);
await setRelayOutput(2, 2);
await setRelayOutput(3, 3);
await setRelayOutput(4, 4);
await setRelayOutput(5, 5);
await setRelayOutput(6, 6);
```

**After (Grouped - 1 batch command):**
```javascript
// 1 network call for all settings
await setBatchRelayOutputs({
  1: 1, 2: 2, 3: 3, 4: 4, 5: 5, 6: 6
});
```

### Performance Metrics
- **Network Calls**: Reduced by up to 85%
- **Configuration Time**: 3-5x faster
- **ESP32 Processing**: More efficient batch updates
- **Error Handling**: Atomic operations ensure consistency

---

## 🔧 Quick Reference

### Command Groups
| Group | Purpose | Batch Support |
|-------|---------|---------------|
| `system` | Device management, ping, status | No |
| `playback` | Music playback control | No |
| `file_manager` | Melody file operations | No |
| `relay_setup` | Bell configuration | ✅ Yes |
| `clock_setup` | Clock mechanism setup | ✅ Yes |

### Actions by Group

**System:** `ping`, `status`, `identify`, `restart`, `force_update`, `custom_update`

**Playback:** `play`, `stop`

**File Manager:** `list_melodies`, `download_melody`, `delete_melody`

**Relay Setup:** `set_timers`, `set_outputs`

**Clock Setup:** `set_outputs`, `set_timings`, `set_alerts`, `set_backlight`, `set_silence`, `batch_setup`

---

*Happy Bell Automation with Grouped Commands! 🔔*