From d6473c6eacc9835a6a91d98b7279777e7f5ccf1a Mon Sep 17 00:00:00 2001
From: Patrick Balsiger <frupii@gmail.com>
Date: Fri, 15 Aug 2025 21:32:55 +0200
Subject: [PATCH] docs: add comprehensive README with WiFi network
 documentation

---
 README.md | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 165 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0e76e1f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,165 @@
+# Sprocket WiFi Network
+
+A WiFi networking implementation for the Sprocket framework, providing both station and access point modes with configurable network settings.
+
+## Overview
+
+The WiFi network module extends Sprocket-Core with comprehensive WiFi capabilities, supporting both client (station) and access point modes for flexible network configurations.
+
+## Features
+
+- **Dual Mode Operation**: Station mode (client) and Access Point mode
+- **Configurable Networks**: Support for multiple WiFi networks
+- **Automatic Reconnection**: Built-in connection management
+- **DNS Support**: mDNS hostname resolution
+- **JSON Configuration**: Easy setup through configuration files
+- **Cross-Platform**: Support for both ESP8266 and ESP32
+
+## Configuration
+
+```cpp
+struct WiFiConfig {
+    int stationMode;           // WiFi mode (0=AP, 1=Station, 2=Both)
+    String stationSSID;        // WiFi network SSID
+    String stationPassword;    // WiFi network password
+    String apSSID;            // Access point SSID
+    String apPassword;        // Access point password
+    String hostname;          // Device hostname for mDNS
+    int connectTimeout;       // Connection timeout in seconds
+};
+```
+
+## Operating Modes
+
+### Station Mode (Client)
+- Connect to existing WiFi networks
+- Automatic reconnection on disconnection
+- Configurable connection timeout
+- Support for multiple network credentials
+
+### Access Point Mode
+- Create WiFi hotspot for other devices
+- Configurable SSID and password
+- Built-in DNS server
+- Client device management
+
+### Dual Mode
+- Simultaneous station and AP operation
+- Bridge between WiFi networks
+- Mesh network capabilities
+
+## Usage Example
+
+```cpp
+#include <WiFiNet.h>
+#include <WiFiConfig.h>
+
+// Configure WiFi settings
+WiFiConfig wifiConfig;
+wifiConfig.stationMode = 1;           // Station mode
+wifiConfig.stationSSID = "MyNetwork";
+wifiConfig.stationPassword = "password";
+wifiConfig.hostname = "MySprocket";
+wifiConfig.connectTimeout = 30;
+
+// Create WiFi network instance
+WiFiNet wifiNet(
+    wifiConfig.stationMode,
+    wifiConfig.stationSSID.c_str(),
+    wifiConfig.stationPassword.c_str(),
+    wifiConfig.apSSID.c_str(),
+    wifiConfig.apPassword.c_str(),
+    wifiConfig.hostname.c_str(),
+    wifiConfig.connectTimeout
+);
+
+// Connect to network
+wifiNet.connect();
+```
+
+## Configuration File
+
+WiFi settings can be configured via JSON files:
+
+```json
+{
+    "stationMode": 1,
+    "stationSSID": "MyNetwork",
+    "stationPassword": "password",
+    "apSSID": "SprocketAP",
+    "apPassword": "apassword",
+    "hostname": "MySprocket",
+    "connectTimeout": 30
+}
+```
+
+## Network Functions
+
+### Connection Management
+- `connect()` - Establish WiFi connection
+- `connectStation()` - Connect to configured station
+- `createAccessPoint()` - Start access point mode
+- `isConnected()` - Check connection status
+
+### DNS and Discovery
+- `startDNS()` - Initialize mDNS service
+- Hostname resolution for network discovery
+- Automatic service advertisement
+
+## Installation
+
+1. Include the WiFi network module in your Sprocket project
+2. Configure WiFi credentials and operating mode
+3. Initialize WiFiNet with your configuration
+4. Call connect() to establish network connection
+5. Monitor connection status for network management
+
+## Dependencies
+
+- Sprocket-Core framework
+- Arduino framework
+- ESP8266WiFi or WiFi library (ESP32)
+- ESP8266mDNS or ESPmDNS library
+- ArduinoJson library
+
+## Platform Support
+
+- ESP8266
+- ESP32
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+- `basic/` - Basic WiFi connection and configuration
+
+## Network Security
+
+- WPA2 encryption support
+- Configurable access point security
+- Network isolation options
+- Client device management
+
+## Power Management
+
+- WiFi sleep modes for power saving
+- Configurable connection timeouts
+- Automatic power management
+- Sleep-on-idle support
+
+## Troubleshooting
+
+- **Connection Issues**: Verify SSID and password
+- **Weak Signal**: Check antenna and positioning
+- **AP Mode**: Ensure unique SSID and channel
+- **DNS Issues**: Verify mDNS configuration
+
+## Use Cases
+
+- **IoT Devices**: Connect sensors and actuators to WiFi
+- **Home Automation**: Integrate with home WiFi networks
+- **Mesh Networks**: Create distributed device networks
+- **Remote Access**: Enable remote device management
+
+## License
+
+See LICENSE file for details. 
\ No newline at end of file