diff --git a/.cursor/rules/cpp.mdc b/.cursor/rules/cpp.mdc new file mode 100644 index 0000000..a480c7e --- /dev/null +++ b/.cursor/rules/cpp.mdc @@ -0,0 +1,68 @@ +--- +description: C++ Development Rules +globs: +alwaysApply: true +--- + +# C++ Development Rules + +You are a senior C++ developer with expertise in modern C++ (C++17/20), STL, and system-level programming. + +## Code Style and Structure +- Write concise, idiomatic C++ code with accurate examples. +- Follow modern C++ conventions and best practices. +- Use object-oriented, procedural, or functional programming patterns as appropriate. +- Leverage STL and standard algorithms for collection operations. +- Use descriptive variable and method names (e.g., 'isUserSignedIn', 'calculateTotal'). +- Structure files into headers (*.hpp) and implementation files (*.cpp) with logical separation of concerns. + +## Naming Conventions +- Use PascalCase for class names. +- Use camelCase for variable names and methods. +- Use SCREAMING_SNAKE_CASE for constants and macros. +- Prefix member variables with an underscore or m_ (e.g., `_userId`, `m_userId`). +- Use namespaces to organize code logically. +## C++ Features Usage + +- Prefer modern C++ features (e.g., auto, range-based loops, smart pointers). +- Use `std::unique_ptr` and `std::shared_ptr` for memory management. +- Prefer `std::optional`, `std::variant`, and `std::any` for type-safe alternatives. +- Use `constexpr` and `const` to optimize compile-time computations. +- Use `std::string_view` for read-only string operations to avoid unnecessary copies. + +## Syntax and Formatting +- Follow a consistent coding style, such as Google C++ Style Guide or your team’s standards. +- Place braces on the same line for control structures and methods. +- Use clear and consistent commenting practices. + +## Error Handling and Validation +- Use exceptions for error handling (e.g., `std::runtime_error`, `std::invalid_argument`). +- Use RAII for resource management to avoid memory leaks. +- Validate inputs at function boundaries. +- Log errors using a logging library (e.g., spdlog, Boost.Log). + +## Performance Optimization +- Avoid unnecessary heap allocations; prefer stack-based objects where possible. +- Use `std::move` to enable move semantics and avoid copies. +- Optimize loops with algorithms from `` (e.g., `std::sort`, `std::for_each`). +- Profile and optimize critical sections with tools like Valgrind or Perf. + +## Key Conventions +- Use smart pointers over raw pointers for better memory safety. +- Avoid global variables; use singletons sparingly. +- Use `enum class` for strongly typed enumerations. +- Separate interface from implementation in classes. +- Use templates and metaprogramming judiciously for generic solutions. + +## Security +- Use secure coding practices to avoid vulnerabilities (e.g., buffer overflows, dangling pointers). +- Prefer `std::array` or `std::vector` over raw arrays. +- Avoid C-style casts; use `static_cast`, `dynamic_cast`, or `reinterpret_cast` when necessary. +- Enforce const-correctness in functions and member variables. + +## Documentation +- Write clear comments for classes, methods, and critical logic. +- Use Doxygen for generating API documentation. +- Document assumptions, constraints, and expected behavior of code. + +Follow the official ISO C++ standards and guidelines for best practices in modern C++ development. diff --git a/README.md b/README.md index 5428fdc..97d3f1c 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ SPORE is a cluster engine for ESP8266 microcontrollers that provides automatic n - **Event System**: Local and cluster-wide event publishing/subscription - **Over-The-Air Updates**: Seamless firmware updates across the cluster - **REST API**: HTTP-based cluster management and monitoring +- **Capability Discovery**: Automatic API endpoint and service capability detection ## Supported Hardware @@ -66,11 +67,15 @@ The system provides a comprehensive RESTful API for monitoring and controlling t | Endpoint | Method | Description | |----------|--------|-------------| | `/api/node/status` | GET | System resources and API endpoint registry | +| `/api/node/capabilities` | GET | API endpoint capabilities and parameters | | `/api/cluster/members` | GET | Cluster membership and health status | | `/api/node/update` | POST | OTA firmware updates | | `/api/node/restart` | POST | System restart | | `/api/tasks/status` | GET | Task management and monitoring | | `/api/tasks/control` | POST | Task control operations | +| `/api/network/status` | GET | WiFi and network status information | +| `/api/network/wifi/scan` | GET/POST | WiFi network scanning and discovery | +| `/api/network/wifi/config` | POST | WiFi configuration management | **Response Format:** All endpoints return JSON with standardized error handling and HTTP status codes. @@ -122,6 +127,7 @@ The project uses PlatformIO with Arduino framework and supports multiple ESP8266 - No persistent storage for configuration - Task monitoring and system health metrics - Task execution history and performance analytics not yet implemented +- No authentication or security features implemented ## Troubleshooting diff --git a/api/openapi.yaml b/api/openapi.yaml index ef3e105..72459eb 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -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 diff --git a/docs/API.md b/docs/API.md index 28fa33c..415c011 100644 --- a/docs/API.md +++ b/docs/API.md @@ -16,10 +16,33 @@ The SPORE system provides a comprehensive RESTful API for monitoring and control | Endpoint | Method | Description | Response | |----------|--------|-------------|----------| | `/api/node/status` | GET | System resource information and API endpoint registry | System metrics and API catalog | +| `/api/node/capabilities` | GET | API endpoint capabilities and parameters | Detailed endpoint specifications | | `/api/cluster/members` | GET | Cluster membership and node health information | Cluster topology and health status | | `/api/node/update` | POST | Handle firmware updates via OTA | Update progress and status | | `/api/node/restart` | POST | Trigger system restart | Restart confirmation | +### Network Management API + +| Endpoint | Method | Description | Response | +|----------|--------|-------------|----------| +| `/api/network/status` | GET | WiFi and network status information | Network configuration and status | +| `/api/network/wifi/scan` | GET | Get available WiFi networks | List of discovered networks | +| `/api/network/wifi/scan` | POST | Trigger WiFi network scan | Scan initiation confirmation | +| `/api/network/wifi/config` | POST | Configure WiFi connection | Connection status and result | + +### Hardware Services API + +| Endpoint | Method | Description | Response | +|----------|--------|-------------|----------| +| `/api/neopixel/status` | GET | NeoPixel LED strip status | LED configuration and state | +| `/api/neopixel` | POST | NeoPixel pattern and color control | Control confirmation | +| `/api/neopixel/patterns` | GET | Available LED patterns | List of supported patterns | +| `/api/relay/status` | GET | Relay state and configuration | Relay pin and state | +| `/api/relay` | POST | Relay control (on/off/toggle) | Control result | +| `/api/neopattern/status` | GET | NeoPattern service status | Pattern configuration | +| `/api/neopattern` | POST | Advanced LED pattern control | Control confirmation | +| `/api/neopattern/patterns` | GET | Available pattern types | List of supported patterns | + ## Detailed API Reference ### Task Management @@ -125,8 +148,67 @@ Returns comprehensive system resource information including memory usage, chip d - `sdkVersion`: ESP8266 SDK version - `cpuFreqMHz`: CPU frequency in MHz - `flashChipSize`: Flash chip size in bytes +- `labels`: Node labels and metadata (if available) - `api`: Array of registered API endpoints +**Example Response:** +```json +{ + "freeHeap": 48748, + "chipId": 12345678, + "sdkVersion": "3.1.2", + "cpuFreqMHz": 80, + "flashChipSize": 1048576, + "labels": { + "location": "kitchen", + "type": "sensor" + } +} +``` + +#### GET /api/node/capabilities + +Returns detailed information about all available API endpoints, including their parameters, types, and validation rules. + +**Response Fields:** +- `endpoints[]`: Array of endpoint capability objects +- `uri`: Endpoint URI path +- `method`: HTTP method (GET, POST, etc.) +- `params[]`: Parameter specifications (if applicable) +- `name`: Parameter name +- `location`: Parameter location (body, query, etc.) +- `required`: Whether parameter is required +- `type`: Parameter data type +- `values[]`: Allowed values (for enums) +- `default`: Default value + +**Example Response:** +```json +{ + "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"] + } + ] + } + ] +} +``` + #### GET /api/cluster/members Returns information about all nodes in the cluster, including their health status, resources, and API endpoints. @@ -154,6 +236,225 @@ Initiates an over-the-air firmware update. The firmware file should be uploaded Triggers a system restart. The response will be sent before the restart occurs. +### Network Management + +#### GET /api/network/status + +Returns comprehensive WiFi and network status information. + +**Response Fields:** +- `wifi.connected`: Whether WiFi is connected +- `wifi.mode`: WiFi mode (STA or AP) +- `wifi.ssid`: Connected network SSID +- `wifi.ip`: Local IP address +- `wifi.mac`: MAC address +- `wifi.hostname`: Device hostname +- `wifi.rssi`: Signal strength +- `wifi.ap_ip`: Access point IP (if in AP mode) +- `wifi.ap_mac`: Access point MAC (if in AP mode) +- `wifi.stations_connected`: Number of connected stations (if in AP mode) + +**Example Response:** +```json +{ + "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 + } +} +``` + +#### GET /api/network/wifi/scan + +Returns a list of available WiFi networks discovered during the last scan. + +**Response Fields:** +- `access_points[]`: Array of discovered networks +- `ssid`: Network name +- `rssi`: Signal strength +- `channel`: WiFi channel +- `encryption_type`: Security type +- `hidden`: Whether network is hidden +- `bssid`: Network MAC address + +**Example Response:** +```json +{ + "access_points": [ + { + "ssid": "MyNetwork", + "rssi": -45, + "channel": 6, + "encryption_type": 4, + "hidden": false, + "bssid": "AA:BB:CC:DD:EE:FF" + } + ] +} +``` + +#### POST /api/network/wifi/scan + +Initiates a new WiFi network scan. + +**Response:** +```json +{ + "status": "scanning", + "message": "WiFi scan started" +} +``` + +#### POST /api/network/wifi/config + +Configures WiFi connection with new credentials. + +**Parameters:** +- `ssid` (required): Network SSID +- `password` (required): Network password +- `connect_timeout_ms` (optional): Connection timeout in milliseconds (default: 10000) +- `retry_delay_ms` (optional): Retry delay in milliseconds (default: 500) + +**Response:** +```json +{ + "status": "success", + "message": "WiFi configuration updated", + "connected": true, + "ip": "192.168.1.100" +} +``` + +### Hardware Services + +#### NeoPixel LED Control + +##### GET /api/neopixel/status + +Returns current NeoPixel LED strip status and configuration. + +**Response Fields:** +- `pin`: GPIO pin number +- `count`: Number of LEDs in strip +- `interval_ms`: Update interval in milliseconds +- `brightness`: Current brightness (0-255) +- `pattern`: Current pattern name + +**Example Response:** +```json +{ + "pin": 2, + "count": 16, + "interval_ms": 100, + "brightness": 50, + "pattern": "rainbow" +} +``` + +##### GET /api/neopixel/patterns + +Returns list of available LED patterns. + +**Response:** +```json +["off", "color_wipe", "rainbow", "rainbow_cycle", "theater_chase", "theater_chase_rainbow"] +``` + +##### POST /api/neopixel + +Controls NeoPixel LED strip patterns and colors. + +**Parameters:** +- `pattern` (optional): Pattern name +- `interval_ms` (optional): Update interval in milliseconds +- `brightness` (optional): Brightness level (0-255) +- `color` (optional): Primary color (hex value) +- `r`, `g`, `b` (optional): RGB color values +- `color2` (optional): Secondary color (hex value) +- `r2`, `g2`, `b2` (optional): Secondary RGB values + +**Example Request:** +```bash +curl -X POST http://192.168.1.100/api/neopixel \ + -d "pattern=rainbow&brightness=100&interval_ms=50" +``` + +#### Relay Control + +##### GET /api/relay/status + +Returns current relay status and configuration. + +**Response Fields:** +- `pin`: GPIO pin number +- `state`: Current state (on/off) +- `uptime`: System uptime in milliseconds + +**Example Response:** +```json +{ + "pin": 5, + "state": "off", + "uptime": 12345 +} +``` + +##### POST /api/relay + +Controls relay state. + +**Parameters:** +- `state` (required): Desired state (on, off, toggle) + +**Example Request:** +```bash +curl -X POST http://192.168.1.100/api/relay \ + -d "state=on" +``` + +#### NeoPattern Service + +##### GET /api/neopattern/status + +Returns NeoPattern service status and configuration. + +**Response Fields:** +- `pin`: GPIO pin number +- `count`: Number of LEDs +- `interval_ms`: Update interval +- `brightness`: Current brightness +- `pattern`: Current pattern name +- `total_steps`: Pattern step count +- `color1`: Primary color +- `color2`: Secondary color + +##### GET /api/neopattern/patterns + +Returns available pattern types. + +**Response:** +```json +["off", "rainbow_cycle", "theater_chase", "color_wipe", "scanner", "fade", "fire"] +``` + +##### POST /api/neopattern + +Controls advanced LED patterns. + +**Parameters:** +- `pattern` (optional): Pattern name +- `interval_ms` (optional): Update interval +- `brightness` (optional): Brightness level +- `color`, `color2` (optional): Color values +- `r`, `g`, `b`, `r2`, `g2`, `b2` (optional): RGB values +- `total_steps` (optional): Pattern step count +- `direction` (optional): Pattern direction (forward/reverse) + ## HTTP Status Codes | Code | Description | Use Case |