143 lines
3.4 KiB
Markdown
143 lines
3.4 KiB
Markdown
# Relay Service Example
|
||
|
||
A minimal example that demonstrates the Spore framework with a custom RelayService and web interface. The Spore framework automatically handles all core functionality (WiFi, clustering, API server, task management) while allowing easy registration of custom services.
|
||
|
||
## Features
|
||
|
||
- **API Control**: RESTful API endpoints for programmatic control
|
||
- **Web Interface**: Beautiful web UI for manual control at `http://<device-ip>/relay.html`
|
||
- **Real-time Status**: Live status updates and visual feedback
|
||
- **Toggle Functionality**: One-click toggle between ON/OFF states
|
||
|
||
- Default relay pin: `GPIO0` (ESP-01). Override with `-DRELAY_PIN=<pin>`.
|
||
- WiFi and API port are configured in `src/Config.cpp`.
|
||
|
||
## Spore Framework Usage
|
||
|
||
This example demonstrates the simplified Spore framework approach:
|
||
|
||
```cpp
|
||
#include <Arduino.h>
|
||
#include "Spore.h"
|
||
#include "RelayService.h"
|
||
|
||
Spore spore({
|
||
{"app", "relay"},
|
||
{"device", "actuator"},
|
||
{"pin", String(RELAY_PIN)}
|
||
});
|
||
|
||
RelayService* relayService = nullptr;
|
||
|
||
void setup() {
|
||
spore.setup();
|
||
|
||
relayService = new RelayService(spore.getContext(), spore.getTaskManager(), RELAY_PIN);
|
||
spore.registerService(relayService);
|
||
|
||
spore.begin();
|
||
}
|
||
|
||
void loop() {
|
||
spore.loop();
|
||
}
|
||
```
|
||
|
||
The Spore framework automatically provides:
|
||
- WiFi connectivity management
|
||
- Cluster discovery and management
|
||
- REST API server with core endpoints
|
||
- Task scheduling and execution
|
||
- Node status monitoring
|
||
- Static file serving for web interfaces (core service)
|
||
|
||
## Build & Upload
|
||
|
||
- ESP‑01S:
|
||
```bash
|
||
pio run -e esp01_1m_relay -t upload
|
||
```
|
||
- D1 Mini:
|
||
```bash
|
||
pio run -e d1_mini_relay -t upload
|
||
```
|
||
|
||
Monitor serial logs:
|
||
```bash
|
||
pio device monitor -b 115200
|
||
```
|
||
|
||
Assume the device IP is 192.168.1.50 below (replace with your device's IP shown in serial output).
|
||
|
||
## Web Interface
|
||
|
||
The web interface is located in the `data/` folder and will be served by the core StaticFileService.
|
||
|
||
Access the web interface at: `http://192.168.1.50/relay.html`
|
||
|
||
The web interface provides:
|
||
- Visual status indicator (red for OFF, green for ON)
|
||
- Turn ON/OFF buttons
|
||
- Toggle button for quick switching
|
||
- Real-time status updates every 2 seconds
|
||
- Uptime display
|
||
- Error handling and user feedback
|
||
|
||
## Relay API
|
||
|
||
- Get relay status
|
||
```bash
|
||
curl http://192.168.1.50/api/relay/status
|
||
```
|
||
|
||
- Turn relay ON
|
||
```bash
|
||
curl -X POST http://192.168.1.50/api/relay -d state=on
|
||
```
|
||
|
||
- Turn relay OFF
|
||
```bash
|
||
curl -X POST http://192.168.1.50/api/relay -d state=off
|
||
```
|
||
|
||
- Toggle relay
|
||
```bash
|
||
curl -X POST http://192.168.1.50/api/relay -d state=toggle
|
||
```
|
||
|
||
Notes:
|
||
- Requests use `application/x-www-form-urlencoded` by default when using `curl -d`.
|
||
|
||
## Task Management (optional)
|
||
The example registers a periodic task `relay_status_print` that logs the current relay state.
|
||
|
||
- Fetch all task statuses
|
||
```bash
|
||
curl http://192.168.1.50/api/tasks/status
|
||
```
|
||
|
||
- Query a specific task status
|
||
```bash
|
||
curl -X POST http://192.168.1.50/api/tasks/control \
|
||
-d task=relay_status_print -d action=status
|
||
```
|
||
|
||
- Enable / Disable the task
|
||
```bash
|
||
curl -X POST http://192.168.1.50/api/tasks/control \
|
||
-d task=relay_status_print -d action=enable
|
||
|
||
curl -X POST http://192.168.1.50/api/tasks/control \
|
||
-d task=relay_status_print -d action=disable
|
||
```
|
||
|
||
## General System Endpoints (optional)
|
||
- Node status
|
||
```bash
|
||
curl http://192.168.1.50/api/node/status
|
||
```
|
||
|
||
- Restart device
|
||
```bash
|
||
curl -X POST http://192.168.1.50/api/node/restart
|
||
``` |