spore/examples/relay/README.md

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:

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

pio run -e esp01_1m_relay -t upload

• D1 Mini:

pio run -e d1_mini_relay -t upload

Monitor serial logs:

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

curl http://192.168.1.50/api/relay/status

• Turn relay ON

curl -X POST http://192.168.1.50/api/relay -d state=on

• Turn relay OFF

curl -X POST http://192.168.1.50/api/relay -d state=off

• Toggle relay

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

curl http://192.168.1.50/api/tasks/status

• Query a specific task status

curl -X POST http://192.168.1.50/api/tasks/control \
  -d task=relay_status_print -d action=status

• Enable / Disable the task

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

curl http://192.168.1.50/api/node/status

• Restart device

curl -X POST http://192.168.1.50/api/node/restart