828 lines
15 KiB
Markdown
828 lines
15 KiB
Markdown
# 🔔 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! 🔔* |