1512 lines
42 KiB
YAML
1512 lines
42 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: SPORE Embedded System API
|
|
description: |
|
|
RESTful API for monitoring and controlling the SPORE embedded system.
|
|
|
|
The SPORE system provides comprehensive task management, system monitoring,
|
|
and cluster management capabilities for ESP8266-based embedded devices.
|
|
|
|
## Features
|
|
- **Task Management**: Monitor and control background tasks
|
|
- **System Monitoring**: Real-time system resource tracking
|
|
- **Cluster Management**: Multi-node cluster coordination
|
|
- **OTA Updates**: Over-the-air firmware updates
|
|
- **Health Monitoring**: System and task health metrics
|
|
|
|
## Authentication
|
|
Currently, no authentication is required. All endpoints are accessible
|
|
from the local network.
|
|
|
|
## Rate Limiting
|
|
No rate limiting is currently implemented. Use responsibly.
|
|
|
|
## Base URL
|
|
The API is accessible at `http://{device-ip}/` where `{device-ip}` is
|
|
the IP address of your SPORE device on the local network.
|
|
|
|
version: 1.0.0
|
|
contact:
|
|
name: SPORE Development Team
|
|
url: https://git.dcentral.systems/iot/spore
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
|
|
servers:
|
|
- url: http://{device-ip}
|
|
description: Local SPORE device
|
|
variables:
|
|
device-ip:
|
|
description: IP address of your SPORE device
|
|
default: "10.0.1.60"
|
|
|
|
paths:
|
|
/api/tasks/status:
|
|
get:
|
|
summary: Get comprehensive task status
|
|
description: |
|
|
Returns detailed status information for all registered tasks,
|
|
including system resource metrics and task execution details.
|
|
|
|
This endpoint provides a complete overview of the system's
|
|
task management status and can be used for monitoring and
|
|
debugging purposes.
|
|
|
|
tags:
|
|
- Task Management
|
|
|
|
responses:
|
|
'200':
|
|
description: Task status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TaskStatusResponse'
|
|
examples:
|
|
default:
|
|
summary: Default response
|
|
value:
|
|
summary:
|
|
totalTasks: 6
|
|
activeTasks: 5
|
|
tasks:
|
|
- name: "discovery_send"
|
|
interval: 1000
|
|
enabled: true
|
|
running: true
|
|
autoStart: true
|
|
- name: "heartbeat"
|
|
interval: 2000
|
|
enabled: true
|
|
running: true
|
|
autoStart: true
|
|
- name: "status_update"
|
|
interval: 1000
|
|
enabled: true
|
|
running: true
|
|
autoStart: true
|
|
system:
|
|
freeHeap: 48748
|
|
uptime: 12345
|
|
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
/api/tasks/control:
|
|
post:
|
|
summary: Control individual task operations
|
|
description: |
|
|
Controls the execution state of individual tasks. Supports
|
|
enabling, disabling, starting, stopping, and getting detailed
|
|
status for specific tasks.
|
|
|
|
This endpoint is useful for dynamic task management without
|
|
requiring system restarts.
|
|
|
|
tags:
|
|
- Task Management
|
|
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- task
|
|
- action
|
|
properties:
|
|
task:
|
|
type: string
|
|
description: Name of the task to control
|
|
example: "heartbeat"
|
|
action:
|
|
type: string
|
|
description: Action to perform on the task
|
|
enum: [enable, disable, start, stop, status]
|
|
example: "disable"
|
|
|
|
responses:
|
|
'200':
|
|
description: Task operation completed successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/TaskControlResponse'
|
|
- $ref: '#/components/schemas/TaskStatusDetailResponse'
|
|
examples:
|
|
enable:
|
|
summary: Task enabled
|
|
value:
|
|
success: true
|
|
message: "Task enabled"
|
|
task: "heartbeat"
|
|
action: "enable"
|
|
status:
|
|
summary: Task status retrieved
|
|
value:
|
|
success: true
|
|
message: "Task status retrieved"
|
|
task: "discovery_send"
|
|
action: "status"
|
|
taskDetails:
|
|
name: "discovery_send"
|
|
enabled: true
|
|
running: true
|
|
interval: 1000
|
|
system:
|
|
freeHeap: 48748
|
|
uptime: 12345
|
|
|
|
'400':
|
|
description: Bad request - invalid parameters or action
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
examples:
|
|
missing_params:
|
|
summary: Missing required parameters
|
|
value:
|
|
success: false
|
|
message: "Missing parameters. Required: task, action"
|
|
example: "{\"task\": \"discovery_send\", \"action\": \"status\"}"
|
|
invalid_action:
|
|
summary: Invalid action specified
|
|
value:
|
|
success: false
|
|
message: "Invalid action. Use: enable, disable, start, stop, or status"
|
|
task: "heartbeat"
|
|
action: "invalid_action"
|
|
|
|
/api/node/status:
|
|
get:
|
|
summary: Get system status and API information
|
|
description: |
|
|
Returns comprehensive system resource information including
|
|
memory usage, chip details, and a registry of all available
|
|
API endpoints.
|
|
|
|
tags:
|
|
- System Status
|
|
|
|
responses:
|
|
'200':
|
|
description: System status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemStatusResponse'
|
|
examples:
|
|
default:
|
|
summary: Default response
|
|
value:
|
|
freeHeap: 48748
|
|
chipId: 12345678
|
|
sdkVersion: "3.1.2"
|
|
cpuFreqMHz: 80
|
|
flashChipSize: 1048576
|
|
labels:
|
|
location: "kitchen"
|
|
type: "sensor"
|
|
api:
|
|
- uri: "/api/node/status"
|
|
method: 1
|
|
- uri: "/api/tasks/status"
|
|
method: 1
|
|
- uri: "/api/tasks/control"
|
|
method: 3
|
|
|
|
/api/node/endpoints:
|
|
get:
|
|
summary: Get API endpoints
|
|
description: |
|
|
Returns detailed information about all available API endpoints,
|
|
including their parameters, types, and validation rules.
|
|
|
|
tags:
|
|
- System Status
|
|
|
|
responses:
|
|
'200':
|
|
description: Endpoints retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EndpointsResponse'
|
|
examples:
|
|
default:
|
|
summary: Default response
|
|
value:
|
|
endpoints:
|
|
- uri: "/api/tasks/control"
|
|
method: "POST"
|
|
params:
|
|
- name: "task"
|
|
location: "body"
|
|
required: true
|
|
type: "string"
|
|
- name: "action"
|
|
location: "body"
|
|
required: true
|
|
type: "string"
|
|
values: ["enable", "disable", "start", "stop", "status"]
|
|
|
|
/api/cluster/members:
|
|
get:
|
|
summary: Get cluster membership information
|
|
description: |
|
|
Returns information about all nodes in the cluster,
|
|
including their health status, resources, and API endpoints.
|
|
|
|
tags:
|
|
- Cluster Management
|
|
|
|
responses:
|
|
'200':
|
|
description: Cluster information retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ClusterMembersResponse'
|
|
examples:
|
|
default:
|
|
summary: Default response
|
|
value:
|
|
members:
|
|
- hostname: "spore-node-1"
|
|
ip: "192.168.1.100"
|
|
lastSeen: 1234567890
|
|
latency: 5
|
|
status: "ACTIVE"
|
|
resources:
|
|
freeHeap: 48748
|
|
chipId: 12345678
|
|
sdkVersion: "3.1.2"
|
|
cpuFreqMHz: 80
|
|
flashChipSize: 1048576
|
|
api:
|
|
- uri: "/api/node/status"
|
|
method: "GET"
|
|
- uri: "/api/tasks/status"
|
|
method: "GET"
|
|
|
|
/api/node/update:
|
|
post:
|
|
summary: Handle firmware update via OTA
|
|
description: |
|
|
Initiates an over-the-air firmware update. The firmware
|
|
file should be uploaded as multipart/form-data.
|
|
|
|
tags:
|
|
- System Management
|
|
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
firmware:
|
|
type: string
|
|
format: binary
|
|
description: Firmware binary file (.bin)
|
|
|
|
responses:
|
|
'200':
|
|
description: Firmware update initiated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateResponse'
|
|
examples:
|
|
default:
|
|
summary: Update initiated
|
|
value:
|
|
status: "updating"
|
|
message: "Firmware update in progress"
|
|
|
|
'400':
|
|
description: Invalid firmware file or update failed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
/api/node/restart:
|
|
post:
|
|
summary: Restart the system
|
|
description: |
|
|
Triggers a system restart. The response will be sent
|
|
before the restart occurs.
|
|
|
|
tags:
|
|
- System Management
|
|
|
|
responses:
|
|
'200':
|
|
description: System restart initiated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RestartResponse'
|
|
examples:
|
|
default:
|
|
summary: Restart initiated
|
|
value:
|
|
status: "restarting"
|
|
|
|
/api/network/status:
|
|
get:
|
|
summary: Get network status information
|
|
description: |
|
|
Returns comprehensive WiFi and network status information
|
|
including connection details, signal strength, and mode.
|
|
|
|
tags:
|
|
- Network Management
|
|
|
|
responses:
|
|
'200':
|
|
description: Network status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NetworkStatusResponse'
|
|
examples:
|
|
default:
|
|
summary: Default response
|
|
value:
|
|
wifi:
|
|
connected: true
|
|
mode: "STA"
|
|
ssid: "MyNetwork"
|
|
ip: "192.168.1.100"
|
|
mac: "AA:BB:CC:DD:EE:FF"
|
|
hostname: "spore-node-1"
|
|
rssi: -45
|
|
|
|
/api/network/wifi/scan:
|
|
get:
|
|
summary: Get available WiFi networks
|
|
description: |
|
|
Returns a list of available WiFi networks discovered
|
|
during the last scan.
|
|
|
|
tags:
|
|
- Network Management
|
|
|
|
responses:
|
|
'200':
|
|
description: WiFi networks retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WifiScanResponse'
|
|
examples:
|
|
default:
|
|
summary: Default response
|
|
value:
|
|
access_points:
|
|
- ssid: "MyNetwork"
|
|
rssi: -45
|
|
channel: 6
|
|
encryption_type: 4
|
|
hidden: false
|
|
bssid: "AA:BB:CC:DD:EE:FF"
|
|
|
|
post:
|
|
summary: Trigger WiFi network scan
|
|
description: |
|
|
Initiates a new WiFi network scan to discover
|
|
available networks.
|
|
|
|
tags:
|
|
- Network Management
|
|
|
|
responses:
|
|
'200':
|
|
description: WiFi scan initiated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WifiScanInitResponse'
|
|
examples:
|
|
default:
|
|
summary: Scan initiated
|
|
value:
|
|
status: "scanning"
|
|
message: "WiFi scan started"
|
|
|
|
/api/network/wifi/config:
|
|
post:
|
|
summary: Configure WiFi connection
|
|
description: |
|
|
Configures WiFi connection with new credentials and
|
|
attempts to connect to the specified network.
|
|
|
|
tags:
|
|
- Network Management
|
|
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- ssid
|
|
- password
|
|
properties:
|
|
ssid:
|
|
type: string
|
|
description: Network SSID
|
|
example: "MyNetwork"
|
|
password:
|
|
type: string
|
|
description: Network password
|
|
example: "mypassword"
|
|
connect_timeout_ms:
|
|
type: integer
|
|
description: Connection timeout in milliseconds
|
|
default: 10000
|
|
example: 10000
|
|
retry_delay_ms:
|
|
type: integer
|
|
description: Retry delay in milliseconds
|
|
default: 500
|
|
example: 500
|
|
|
|
responses:
|
|
'200':
|
|
description: WiFi configuration updated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WifiConfigResponse'
|
|
examples:
|
|
default:
|
|
summary: Configuration updated
|
|
value:
|
|
status: "success"
|
|
message: "WiFi configuration updated"
|
|
connected: true
|
|
ip: "192.168.1.100"
|
|
|
|
'400':
|
|
description: Invalid parameters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
/api/neopixel/status:
|
|
get:
|
|
summary: Get NeoPixel LED strip status
|
|
description: |
|
|
Returns current NeoPixel LED strip status and configuration
|
|
including pin, count, brightness, and current pattern.
|
|
|
|
tags:
|
|
- Hardware Services
|
|
|
|
responses:
|
|
'200':
|
|
description: NeoPixel status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NeoPixelStatusResponse'
|
|
|
|
/api/neopixel/patterns:
|
|
get:
|
|
summary: Get available LED patterns
|
|
description: |
|
|
Returns a list of available LED patterns for NeoPixel strips.
|
|
|
|
tags:
|
|
- Hardware Services
|
|
|
|
responses:
|
|
'200':
|
|
description: Patterns retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["off", "color_wipe", "rainbow", "rainbow_cycle", "theater_chase", "theater_chase_rainbow"]
|
|
|
|
/api/neopixel:
|
|
post:
|
|
summary: Control NeoPixel LED strip
|
|
description: |
|
|
Controls NeoPixel LED strip patterns, colors, and brightness.
|
|
|
|
tags:
|
|
- Hardware Services
|
|
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
pattern:
|
|
type: string
|
|
description: Pattern name
|
|
example: "rainbow"
|
|
interval_ms:
|
|
type: integer
|
|
description: Update interval in milliseconds
|
|
example: 100
|
|
brightness:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Brightness level
|
|
example: 50
|
|
color:
|
|
type: string
|
|
description: Primary color (hex value)
|
|
example: "0xFF0000"
|
|
r:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Red component
|
|
g:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Green component
|
|
b:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Blue component
|
|
|
|
responses:
|
|
'200':
|
|
description: NeoPixel control successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NeoPixelControlResponse'
|
|
|
|
/api/relay/status:
|
|
get:
|
|
summary: Get relay status
|
|
description: |
|
|
Returns current relay status and configuration.
|
|
|
|
tags:
|
|
- Hardware Services
|
|
|
|
responses:
|
|
'200':
|
|
description: Relay status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RelayStatusResponse'
|
|
|
|
/api/relay:
|
|
post:
|
|
summary: Control relay
|
|
description: |
|
|
Controls relay state (on/off/toggle).
|
|
|
|
tags:
|
|
- Hardware Services
|
|
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- state
|
|
properties:
|
|
state:
|
|
type: string
|
|
enum: [on, off, toggle]
|
|
description: Desired relay state
|
|
example: "on"
|
|
|
|
responses:
|
|
'200':
|
|
description: Relay control successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RelayControlResponse'
|
|
|
|
'400':
|
|
description: Invalid state parameter
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
/api/neopattern/status:
|
|
get:
|
|
summary: Get NeoPattern service status
|
|
description: |
|
|
Returns NeoPattern service status and configuration.
|
|
|
|
tags:
|
|
- Hardware Services
|
|
|
|
responses:
|
|
'200':
|
|
description: NeoPattern status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NeoPatternStatusResponse'
|
|
|
|
/api/neopattern/patterns:
|
|
get:
|
|
summary: Get available pattern types
|
|
description: |
|
|
Returns a list of available pattern types for NeoPattern service.
|
|
|
|
tags:
|
|
- Hardware Services
|
|
|
|
responses:
|
|
'200':
|
|
description: Patterns retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["off", "rainbow_cycle", "theater_chase", "color_wipe", "scanner", "fade", "fire"]
|
|
|
|
/api/neopattern:
|
|
post:
|
|
summary: Control NeoPattern service
|
|
description: |
|
|
Controls advanced LED patterns with multiple parameters.
|
|
|
|
tags:
|
|
- Hardware Services
|
|
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
pattern:
|
|
type: string
|
|
description: Pattern name
|
|
example: "rainbow_cycle"
|
|
interval_ms:
|
|
type: integer
|
|
description: Update interval in milliseconds
|
|
example: 100
|
|
brightness:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Brightness level
|
|
example: 50
|
|
color:
|
|
type: string
|
|
description: Primary color (hex value)
|
|
example: "0xFF0000"
|
|
color2:
|
|
type: string
|
|
description: Secondary color (hex value)
|
|
example: "0x0000FF"
|
|
r:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Red component
|
|
g:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Green component
|
|
b:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Blue component
|
|
r2:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Secondary red component
|
|
g2:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Secondary green component
|
|
b2:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Secondary blue component
|
|
total_steps:
|
|
type: integer
|
|
description: Pattern step count
|
|
example: 32
|
|
direction:
|
|
type: string
|
|
enum: [forward, reverse]
|
|
description: Pattern direction
|
|
example: "forward"
|
|
|
|
responses:
|
|
'200':
|
|
description: NeoPattern control successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NeoPatternControlResponse'
|
|
|
|
components:
|
|
schemas:
|
|
TaskStatusResponse:
|
|
type: object
|
|
required:
|
|
- summary
|
|
- tasks
|
|
- system
|
|
properties:
|
|
summary:
|
|
$ref: '#/components/schemas/TaskSummary'
|
|
tasks:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TaskInfo'
|
|
system:
|
|
$ref: '#/components/schemas/SystemInfo'
|
|
|
|
TaskSummary:
|
|
type: object
|
|
required:
|
|
- totalTasks
|
|
- activeTasks
|
|
properties:
|
|
totalTasks:
|
|
type: integer
|
|
minimum: 0
|
|
description: Total number of registered tasks
|
|
example: 6
|
|
activeTasks:
|
|
type: integer
|
|
minimum: 0
|
|
description: Number of currently enabled tasks
|
|
example: 5
|
|
|
|
TaskInfo:
|
|
type: object
|
|
required:
|
|
- name
|
|
- interval
|
|
- enabled
|
|
- running
|
|
- autoStart
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Unique task identifier
|
|
example: "discovery_send"
|
|
interval:
|
|
type: integer
|
|
minimum: 1
|
|
description: Execution frequency in milliseconds
|
|
example: 1000
|
|
enabled:
|
|
type: boolean
|
|
description: Whether task is currently enabled
|
|
example: true
|
|
running:
|
|
type: boolean
|
|
description: Whether task is actively executing
|
|
example: true
|
|
autoStart:
|
|
type: boolean
|
|
description: Whether task starts automatically
|
|
example: true
|
|
|
|
SystemInfo:
|
|
type: object
|
|
required:
|
|
- freeHeap
|
|
- uptime
|
|
properties:
|
|
freeHeap:
|
|
type: integer
|
|
minimum: 0
|
|
description: Available RAM in bytes
|
|
example: 48748
|
|
uptime:
|
|
type: integer
|
|
minimum: 0
|
|
description: System uptime in milliseconds
|
|
example: 12345
|
|
|
|
TaskControlResponse:
|
|
type: object
|
|
required:
|
|
- success
|
|
- message
|
|
- task
|
|
- action
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
description: Whether the operation was successful
|
|
example: true
|
|
message:
|
|
type: string
|
|
description: Human-readable operation result
|
|
example: "Task enabled"
|
|
task:
|
|
type: string
|
|
description: Name of the task that was operated on
|
|
example: "heartbeat"
|
|
action:
|
|
type: string
|
|
description: Action that was performed
|
|
example: "enable"
|
|
|
|
TaskStatusDetailResponse:
|
|
allOf:
|
|
- $ref: '#/components/schemas/TaskControlResponse'
|
|
- type: object
|
|
required:
|
|
- taskDetails
|
|
properties:
|
|
taskDetails:
|
|
$ref: '#/components/schemas/TaskDetailInfo'
|
|
|
|
TaskDetailInfo:
|
|
type: object
|
|
required:
|
|
- name
|
|
- enabled
|
|
- running
|
|
- interval
|
|
- system
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Task name
|
|
example: "discovery_send"
|
|
enabled:
|
|
type: boolean
|
|
description: Whether task is enabled
|
|
example: true
|
|
running:
|
|
type: boolean
|
|
description: Whether task is running
|
|
example: true
|
|
interval:
|
|
type: integer
|
|
description: Task execution interval
|
|
example: 1000
|
|
system:
|
|
$ref: '#/components/schemas/SystemInfo'
|
|
|
|
SystemStatusResponse:
|
|
type: object
|
|
required:
|
|
- freeHeap
|
|
- chipId
|
|
- sdkVersion
|
|
- cpuFreqMHz
|
|
- flashChipSize
|
|
- api
|
|
properties:
|
|
freeHeap:
|
|
type: integer
|
|
description: Available RAM in bytes
|
|
example: 48748
|
|
chipId:
|
|
type: integer
|
|
description: ESP8266 chip ID
|
|
example: 12345678
|
|
sdkVersion:
|
|
type: string
|
|
description: ESP8266 SDK version
|
|
example: "3.1.2"
|
|
cpuFreqMHz:
|
|
type: integer
|
|
description: CPU frequency in MHz
|
|
example: 80
|
|
flashChipSize:
|
|
type: integer
|
|
description: Flash chip size in bytes
|
|
example: 1048576
|
|
labels:
|
|
type: object
|
|
description: Node labels and metadata
|
|
additionalProperties:
|
|
type: string
|
|
example:
|
|
location: "kitchen"
|
|
type: "sensor"
|
|
api:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ApiEndpoint'
|
|
|
|
EndpointsResponse:
|
|
type: object
|
|
required:
|
|
- endpoints
|
|
properties:
|
|
endpoints:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/EndpointCapability'
|
|
|
|
EndpointCapability:
|
|
type: object
|
|
required:
|
|
- uri
|
|
- method
|
|
properties:
|
|
uri:
|
|
type: string
|
|
description: Endpoint URI path
|
|
example: "/api/tasks/control"
|
|
method:
|
|
type: string
|
|
description: HTTP method
|
|
example: "POST"
|
|
params:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ParameterSpec'
|
|
|
|
ParameterSpec:
|
|
type: object
|
|
required:
|
|
- name
|
|
- location
|
|
- required
|
|
- type
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Parameter name
|
|
example: "task"
|
|
location:
|
|
type: string
|
|
description: Parameter location
|
|
example: "body"
|
|
required:
|
|
type: boolean
|
|
description: Whether parameter is required
|
|
example: true
|
|
type:
|
|
type: string
|
|
description: Parameter data type
|
|
example: "string"
|
|
values:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Allowed values for enum types
|
|
example: ["enable", "disable", "start", "stop", "status"]
|
|
default:
|
|
type: string
|
|
description: Default value
|
|
example: "10000"
|
|
|
|
NetworkStatusResponse:
|
|
type: object
|
|
required:
|
|
- wifi
|
|
properties:
|
|
wifi:
|
|
type: object
|
|
required:
|
|
- connected
|
|
- mode
|
|
properties:
|
|
connected:
|
|
type: boolean
|
|
description: Whether WiFi is connected
|
|
example: true
|
|
mode:
|
|
type: string
|
|
enum: [STA, AP]
|
|
description: WiFi mode
|
|
example: "STA"
|
|
ssid:
|
|
type: string
|
|
description: Connected network SSID
|
|
example: "MyNetwork"
|
|
ip:
|
|
type: string
|
|
format: ipv4
|
|
description: Local IP address
|
|
example: "192.168.1.100"
|
|
mac:
|
|
type: string
|
|
description: MAC address
|
|
example: "AA:BB:CC:DD:EE:FF"
|
|
hostname:
|
|
type: string
|
|
description: Device hostname
|
|
example: "spore-node-1"
|
|
rssi:
|
|
type: integer
|
|
description: Signal strength in dBm
|
|
example: -45
|
|
ap_ip:
|
|
type: string
|
|
format: ipv4
|
|
description: Access point IP (if in AP mode)
|
|
example: "192.168.4.1"
|
|
ap_mac:
|
|
type: string
|
|
description: Access point MAC (if in AP mode)
|
|
example: "AA:BB:CC:DD:EE:FF"
|
|
stations_connected:
|
|
type: integer
|
|
description: Number of connected stations (if in AP mode)
|
|
example: 2
|
|
|
|
WifiScanResponse:
|
|
type: object
|
|
required:
|
|
- access_points
|
|
properties:
|
|
access_points:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/AccessPoint'
|
|
|
|
AccessPoint:
|
|
type: object
|
|
required:
|
|
- ssid
|
|
- rssi
|
|
- channel
|
|
- encryption_type
|
|
- hidden
|
|
- bssid
|
|
properties:
|
|
ssid:
|
|
type: string
|
|
description: Network name
|
|
example: "MyNetwork"
|
|
rssi:
|
|
type: integer
|
|
description: Signal strength in dBm
|
|
example: -45
|
|
channel:
|
|
type: integer
|
|
description: WiFi channel
|
|
example: 6
|
|
encryption_type:
|
|
type: integer
|
|
description: Security type
|
|
example: 4
|
|
hidden:
|
|
type: boolean
|
|
description: Whether network is hidden
|
|
example: false
|
|
bssid:
|
|
type: string
|
|
description: Network MAC address
|
|
example: "AA:BB:CC:DD:EE:FF"
|
|
|
|
WifiScanInitResponse:
|
|
type: object
|
|
required:
|
|
- status
|
|
- message
|
|
properties:
|
|
status:
|
|
type: string
|
|
description: Scan status
|
|
example: "scanning"
|
|
message:
|
|
type: string
|
|
description: Status message
|
|
example: "WiFi scan started"
|
|
|
|
WifiConfigResponse:
|
|
type: object
|
|
required:
|
|
- status
|
|
- message
|
|
- connected
|
|
properties:
|
|
status:
|
|
type: string
|
|
description: Configuration status
|
|
example: "success"
|
|
message:
|
|
type: string
|
|
description: Status message
|
|
example: "WiFi configuration updated"
|
|
connected:
|
|
type: boolean
|
|
description: Whether connection was successful
|
|
example: true
|
|
ip:
|
|
type: string
|
|
format: ipv4
|
|
description: Assigned IP address (if connected)
|
|
example: "192.168.1.100"
|
|
|
|
NeoPixelStatusResponse:
|
|
type: object
|
|
required:
|
|
- pin
|
|
- count
|
|
- interval_ms
|
|
- brightness
|
|
- pattern
|
|
properties:
|
|
pin:
|
|
type: integer
|
|
description: GPIO pin number
|
|
example: 2
|
|
count:
|
|
type: integer
|
|
description: Number of LEDs in strip
|
|
example: 16
|
|
interval_ms:
|
|
type: integer
|
|
description: Update interval in milliseconds
|
|
example: 100
|
|
brightness:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Current brightness level
|
|
example: 50
|
|
pattern:
|
|
type: string
|
|
description: Current pattern name
|
|
example: "rainbow"
|
|
|
|
NeoPixelControlResponse:
|
|
type: object
|
|
required:
|
|
- ok
|
|
- pattern
|
|
- interval_ms
|
|
- brightness
|
|
properties:
|
|
ok:
|
|
type: boolean
|
|
description: Whether control was successful
|
|
example: true
|
|
pattern:
|
|
type: string
|
|
description: Current pattern name
|
|
example: "rainbow"
|
|
interval_ms:
|
|
type: integer
|
|
description: Update interval in milliseconds
|
|
example: 100
|
|
brightness:
|
|
type: integer
|
|
description: Current brightness level
|
|
example: 50
|
|
|
|
RelayStatusResponse:
|
|
type: object
|
|
required:
|
|
- pin
|
|
- state
|
|
- uptime
|
|
properties:
|
|
pin:
|
|
type: integer
|
|
description: GPIO pin number
|
|
example: 5
|
|
state:
|
|
type: string
|
|
enum: [on, off]
|
|
description: Current relay state
|
|
example: "off"
|
|
uptime:
|
|
type: integer
|
|
description: System uptime in milliseconds
|
|
example: 12345
|
|
|
|
RelayControlResponse:
|
|
type: object
|
|
required:
|
|
- success
|
|
- state
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
description: Whether control was successful
|
|
example: true
|
|
state:
|
|
type: string
|
|
enum: [on, off]
|
|
description: Current relay state
|
|
example: "on"
|
|
message:
|
|
type: string
|
|
description: Error message (if unsuccessful)
|
|
example: "Invalid state. Use: on, off, or toggle"
|
|
|
|
NeoPatternStatusResponse:
|
|
type: object
|
|
required:
|
|
- pin
|
|
- count
|
|
- interval_ms
|
|
- brightness
|
|
- pattern
|
|
- total_steps
|
|
- color1
|
|
- color2
|
|
properties:
|
|
pin:
|
|
type: integer
|
|
description: GPIO pin number
|
|
example: 2
|
|
count:
|
|
type: integer
|
|
description: Number of LEDs
|
|
example: 16
|
|
interval_ms:
|
|
type: integer
|
|
description: Update interval in milliseconds
|
|
example: 100
|
|
brightness:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 255
|
|
description: Current brightness level
|
|
example: 50
|
|
pattern:
|
|
type: string
|
|
description: Current pattern name
|
|
example: "rainbow_cycle"
|
|
total_steps:
|
|
type: integer
|
|
description: Pattern step count
|
|
example: 32
|
|
color1:
|
|
type: integer
|
|
description: Primary color value
|
|
example: 16711680
|
|
color2:
|
|
type: integer
|
|
description: Secondary color value
|
|
example: 255
|
|
|
|
NeoPatternControlResponse:
|
|
type: object
|
|
required:
|
|
- ok
|
|
- pattern
|
|
- interval_ms
|
|
- brightness
|
|
properties:
|
|
ok:
|
|
type: boolean
|
|
description: Whether control was successful
|
|
example: true
|
|
pattern:
|
|
type: string
|
|
description: Current pattern name
|
|
example: "rainbow_cycle"
|
|
interval_ms:
|
|
type: integer
|
|
description: Update interval in milliseconds
|
|
example: 100
|
|
brightness:
|
|
type: integer
|
|
description: Current brightness level
|
|
example: 50
|
|
|
|
ApiEndpoint:
|
|
type: object
|
|
required:
|
|
- uri
|
|
- method
|
|
properties:
|
|
uri:
|
|
type: string
|
|
description: API endpoint URI
|
|
example: "/api/node/status"
|
|
method:
|
|
type: integer
|
|
description: HTTP method (1=GET, 3=POST)
|
|
example: 1
|
|
|
|
ClusterMembersResponse:
|
|
type: object
|
|
required:
|
|
- members
|
|
properties:
|
|
members:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ClusterNode'
|
|
|
|
ClusterNode:
|
|
type: object
|
|
required:
|
|
- hostname
|
|
- ip
|
|
- lastSeen
|
|
- latency
|
|
- status
|
|
- resources
|
|
- api
|
|
properties:
|
|
hostname:
|
|
type: string
|
|
description: Node hostname
|
|
example: "spore-node-1"
|
|
ip:
|
|
type: string
|
|
format: ipv4
|
|
description: Node IP address
|
|
example: "192.168.1.100"
|
|
lastSeen:
|
|
type: integer
|
|
description: Timestamp of last communication
|
|
example: 1234567890
|
|
latency:
|
|
type: integer
|
|
description: Network latency in milliseconds
|
|
example: 5
|
|
status:
|
|
type: string
|
|
enum: [ACTIVE, INACTIVE, DEAD]
|
|
description: Node health status
|
|
example: "ACTIVE"
|
|
resources:
|
|
$ref: '#/components/schemas/SystemResources'
|
|
api:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ApiEndpoint'
|
|
|
|
SystemResources:
|
|
type: object
|
|
required:
|
|
- freeHeap
|
|
- chipId
|
|
- sdkVersion
|
|
- cpuFreqMHz
|
|
- flashChipSize
|
|
properties:
|
|
freeHeap:
|
|
type: integer
|
|
description: Available RAM in bytes
|
|
example: 48748
|
|
chipId:
|
|
type: integer
|
|
description: ESP8266 chip ID
|
|
example: 12345678
|
|
sdkVersion:
|
|
type: string
|
|
description: ESP8266 SDK version
|
|
example: "3.1.2"
|
|
cpuFreqMHz:
|
|
type: integer
|
|
description: CPU frequency in MHz
|
|
example: 80
|
|
flashChipSize:
|
|
type: integer
|
|
description: Flash chip size in bytes
|
|
example: 1048576
|
|
|
|
UpdateResponse:
|
|
type: object
|
|
required:
|
|
- status
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [updating, failed]
|
|
description: Update operation status
|
|
example: "updating"
|
|
message:
|
|
type: string
|
|
description: Additional status information
|
|
example: "Firmware update in progress"
|
|
|
|
RestartResponse:
|
|
type: object
|
|
required:
|
|
- status
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [restarting]
|
|
description: Restart operation status
|
|
example: "restarting"
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
required:
|
|
- success
|
|
- message
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
description: Always false for error responses
|
|
example: false
|
|
message:
|
|
type: string
|
|
description: Error description
|
|
example: "Missing parameters. Required: task, action"
|
|
example:
|
|
type: string
|
|
description: Example of correct usage
|
|
example: "{\"task\": \"discovery_send\", \"action\": \"status\"}"
|
|
task:
|
|
type: string
|
|
description: Task name (if applicable)
|
|
example: "heartbeat"
|
|
action:
|
|
type: string
|
|
description: Action attempted (if applicable)
|
|
example: "invalid_action"
|
|
|
|
tags:
|
|
- name: Task Management
|
|
description: Operations for monitoring and controlling background tasks
|
|
- name: System Status
|
|
description: System resource monitoring and API information
|
|
- name: Cluster Management
|
|
description: Multi-node cluster coordination and health monitoring
|
|
- name: System Management
|
|
description: System-level operations like updates and restarts
|
|
- name: Network Management
|
|
description: WiFi and network configuration and monitoring
|
|
- name: Hardware Services
|
|
description: Hardware control services for LEDs, relays, and other peripherals
|
|
|
|
externalDocs:
|
|
description: SPORE Project Documentation
|
|
url: https://github.com/your-org/spore |