feat: services (#2)

This commit is contained in:
2025-09-13 13:45:24 +02:00
parent fe045804cb
commit 12caeb0be6
33 changed files with 3293 additions and 785 deletions

View File

@@ -212,6 +212,9 @@ paths:
sdkVersion: "3.1.2"
cpuFreqMHz: 80
flashChipSize: 1048576
labels:
location: "kitchen"
type: "sensor"
api:
- uri: "/api/node/status"
method: 1
@@ -220,6 +223,41 @@ paths:
- uri: "/api/tasks/control"
method: 3
/api/node/capabilities:
get:
summary: Get API endpoint capabilities
description: |
Returns detailed information about all available API endpoints,
including their parameters, types, and validation rules.
tags:
- System Status
responses:
'200':
description: Capabilities retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CapabilitiesResponse'
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
@@ -325,6 +363,425 @@ paths:
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:
@@ -501,11 +958,393 @@ components:
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'
CapabilitiesResponse:
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:
@@ -663,6 +1502,10 @@ tags:
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