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/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
      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'
    
    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:
        - 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