Added UART as a communication interface option.
This commit is contained in:
828
vesper/documentation/API_Reference.md
Normal file
828
vesper/documentation/API_Reference.md
Normal file
@@ -0,0 +1,828 @@
|
||||
# 🔔 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! 🔔*
|
||||
Reference in New Issue
Block a user