feat: wifiscan

examples/wifiscan/README.md

@@ -0,0 +1,88 @@
+# WiFi Scanner Example
+
+This example demonstrates how to use the async WiFi scanning functionality in SPORE with periodic scanning via tasks.
+
+## Features
+
+- **Async WiFi Scanning**: Non-blocking WiFi network discovery via NetworkManager
+- **Task-based Periodic Scanning**: Automatically scans for networks every minute using TaskManager
+- **Event-driven**: Uses the event system to handle scan events
+- **REST API**: HTTP endpoints to manually trigger scans and view results
+- **Detailed Results**: Shows SSID, RSSI, channel, and encryption type for each network
+
+## Usage
+
+1. Upload this example to your ESP8266 device
+2. Open the Serial Monitor at 115200 baud
+3. The device will automatically start scanning for WiFi networks every minute
+4. Results will be displayed in the Serial Monitor
+5. Use the REST API to manually trigger scans or view current results
+
+## Event System
+
+The WiFi scanner uses the following events:
+
+- `wifi/scan/start`: Fired when scan starts (both manual and periodic)
+- `wifi/scan/complete`: Fired when scan completes successfully
+- `wifi/scan/error`: Fired when scan fails to start
+- `wifi/scan/timeout`: Fired when scan times out (10 seconds)
+
+## Task Management
+
+The example registers a periodic task:
+- **Task Name**: `wifi_scan_periodic`
+- **Interval**: 60 seconds (60000ms)
+- **Function**: Fires `wifi/scan/start` event and starts WiFi scan
+
+## REST API
+
+### Manual Scan Control
+- **Start Scan**: `POST /api/wifi/scan`
+- **Get Status**: `GET /api/wifi/status`
+
+### Example API Usage
+```bash
+# Start a manual scan
+curl -X POST http://192.168.1.50/api/wifi/scan
+
+# Get current scan status and results
+curl http://192.168.1.50/api/wifi/status
+
+# Check task status
+curl http://192.168.1.50/api/tasks/status
+
+# Disable periodic scanning
+curl -X POST http://192.168.1.50/api/tasks/control \
+  -d task=wifi_scan_periodic -d action=disable
+```
+
+## Architecture
+
+- **WiFiScannerService**: Manages periodic scanning and API endpoints
+- **NetworkManager**: Handles WiFi scanning operations and callbacks
+- **NodeContext**: Stores the WiFi access points data
+- **TaskManager**: Schedules periodic scan tasks
+- **Event System**: Provides communication between components
+
+## WiFiAccessPoint Structure
+
+```cpp
+struct WiFiAccessPoint {
+    String ssid;           // Network name
+    int32_t rssi;          // Signal strength
+    uint8_t encryption;    // Encryption type
+    uint8_t* bssid;        // MAC address
+    int32_t channel;       // WiFi channel
+    bool isHidden;         // Hidden network flag
+};
+```
+
+## Task Configuration
+
+The periodic scanning task can be controlled via the standard TaskManager API:
+- Enable/disable the task
+- Change the scan interval
+- Monitor task status
+- Start/stop the task
+
+This provides flexibility to adjust scanning behavior based on application needs.