https://github.com/ayresnet/ayreswifimanager
AyresWiFiManager (AWM): Wi-Fi manager pro para ESP32/ESP8266. Portal cautivo AP+DNS, credenciales en LittleFS, HTML embebido, escaneo JSON (/scan), botón 2–5s/≥5s, LED por estados, NTP y check de Internet.
https://github.com/ayresnet/ayreswifimanager
arduino-ide arduinojson css3 dns esp32 esp8266 html5 iot javascript json littlefs ntp platformio ux-experience webserver wifi
Last synced: 10 months ago
JSON representation
AyresWiFiManager (AWM): Wi-Fi manager pro para ESP32/ESP8266. Portal cautivo AP+DNS, credenciales en LittleFS, HTML embebido, escaneo JSON (/scan), botón 2–5s/≥5s, LED por estados, NTP y check de Internet.
- Host: GitHub
- URL: https://github.com/ayresnet/ayreswifimanager
- Owner: ayresnet
- License: mit
- Created: 2025-08-23T01:02:37.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-30T00:13:36.000Z (10 months ago)
- Last Synced: 2025-09-30T02:24:22.454Z (10 months ago)
- Topics: arduino-ide, arduinojson, css3, dns, esp32, esp8266, html5, iot, javascript, json, littlefs, ntp, platformio, ux-experience, webserver, wifi
- Language: HTML
- Homepage: https://ayresnet.com
- Size: 168 KB
- Stars: 5
- Watchers: 0
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.es.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# AyresWiFiManager (AWM)
[](https://github.com/ayresnet/AyresWiFiManager/stargazers)
⭐ **Si te resulta útil, considera darle una estrella. Gracias. **
---
---
📢 ¡Disponible en el Arduino IDE!
Instalá AyresWiFiManager directamente desde el Library Manager del IDE de Arduino.
Solo buscá “AyresWiFiManager” y tocá “Instalar”.
---
**AWM - Gestor Wi‑Fi “pro” para ESP32/ESP8266** con portal cautivo real (AP+DNS), UI moderna servida desde **LittleFS**, almacenamiento seguro de credenciales, **políticas de fallback**, botón de provisión, LED de estado, **NTP**, chequeo de Internet y **logging** configurable.
> Proyecto: https://github.com/AyresNet/AyresWiFiManager
> Licencia: MIT — (c) 2025 AyresNet
---
## ⭐ ¿Por qué AyresWiFiManager?
- **Portal cautivo real**: DNS *catch‑all* + rutas de detección (Android/iOS/Windows) para forzar apertura en `http://192.168.4.1`.
- **UI ligera (sin dependencias externas)** servida desde `/data` (LittleFS): búsqueda, reescaneo, barras de señal y opción de borrar credenciales desde el portal.
- **API clara** y multiplataforma (ESP32/ESP8266) con políticas explícitas.
- **Fallbacks inteligentes**: `NO_CREDENTIALS_ONLY` (default), `ON_FAIL`, `SMART_RETRIES`, `BUTTON_ONLY`, `NEVER`.
- **Botón y LED** integrados:
- Botón (LOW): **2–5 s** abre portal · **≥5 s** borra JSON y reinicia.
- LED: `ON` conectado · `BLINK_SLOW` portal · `BLINK_FAST` escaneo · `OFF` idle (+ patrones dobles/triples para feedback).
- **Borrado seguro** de `.json` con **lista blanca** y recursivo en ESP32.
- **Logging profesional** (macros `AWM_LOG*`) con nivel ajustable por `build_flags`.
- **Utilidades**: NTP (pool.ntp.org/time.nist.gov), `hayInternet()` (Google `204`), RSSI, timestamp, reconexión automática.
---
## 🚀 Características
- **Almacenamiento de credenciales** en `/wifi.json` (LittleFS).
- **Rutas del portal**
- `GET /` → `index.html`
- `POST /save` → guarda `{ssid,password}` y reinicia
- `GET /scan` o `/scan.json` → `[{ssid,rssi,secure}]`
- `POST /erase` → borra `.json` (respeta protegidos) y reinicia
- **HTML/JS/CSS** de ejemplo incluidos: `data/index.html`, `data/success.html`, `data/error.html`
- **ESP32**: `esp_wifi_set_ps(WIFI_PS_NONE)`, `LittleFS.begin(true)` (auto‑formateo)
**ESP8266**: `WiFi.setSleepMode(WIFI_NONE_SLEEP)`, iteración LittleFS no recursiva
---
## 📦 Instalación
### PlatformIO (recomendado)
`platformio.ini` mínimo:
```ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
board_build.filesystem = littlefs
; Opcional: logging
build_flags =
-D AWM_ENABLE_LOG=1 ; 0=off, 1=on
-D AWM_LOG_LEVEL=3 ; 1=E, 2=W, 3=I, 4=D, 5=V
```
- Coloca tus archivos del portal en `data/` (por ejemplo `index.html`).
- Sube el FS: `pio run -t uploadfs`.
- Flashea el sketch y abre el monitor serie.
### Arduino IDE
- Añadí las cores ESP32/ESP8266 oficiales.
- Instalá el **uploader de LittleFS** correspondiente (ESP32/ESP8266).
- Subí la carpeta `data/` al FS con la herramienta “Data Upload”.
- Compilá y cargá el sketch.
---
## ✏️ Uso mínimo
```cpp
#include
AyresWiFiManager wifi;
void setup() {
Serial.begin(115200);
wifi.setAPCredentials("ayreswifimanager","123456789");
wifi.setPortalTimeout(300); // 5 min por inactividad
wifi.setAPClientCheck(true); // no cierra si hay clientes
wifi.setWebClientCheck(true); // cada request reinicia el timer
// wifi.setCaptivePortal(false); // desactiva redirecciones, si querés
wifi.begin(); // monta FS, carga /wifi.json si existe
wifi.run(); // intenta STA; si falla aplica la política de fallback
}
void loop() {
wifi.update(); // sirve HTTP/DNS y maneja timeouts/LED
}
```
---
## 🪄 Flujo de arranque recomendado
El ejemplo **`examples/30sVentana/src/main.cpp`** hace:
- Si **hay** credenciales → abre portal con *timeout por inactividad* de **30 s**; si no lo usás, se cierra solo y continúa.
- Si **no hay** credenciales → abre portal “normal” (ej. **5 min** por inactividad).
- En ambos casos, si usás el portal (clientes AP o requests HTTP), **no se cierra** hasta que dejes de usarlo.
---
## 🧩 API principal
```cpp
// Portal / AP
void setHtmlPathPrefix(const String& prefix); // ej: "/wifimanager"
void setHostname(const String& host);
void setAPCredentials(const String& ssid, const String& pass);
void setCaptivePortal(bool enabled); // DNS + rutas captive
void setPortalTimeout(uint32_t seconds); // 0 = sin timeout
void setAPClientCheck(bool enabled); // no cerrar si hay clientes
void setWebClientCheck(bool enabled); // cada request reinicia timer
void openPortal();
void closePortal();
bool isPortalActive() const;
// Fallback
enum class FallbackPolicy { ON_FAIL, NO_CREDENTIALS_ONLY, SMART_RETRIES, BUTTON_ONLY, NEVER };
void setFallbackPolicy(FallbackPolicy p);
void setSmartRetries(uint8_t maxRetries, uint32_t windowMs);
void enableButtonPortal(bool enable);
void setAutoReconnect(bool enabled);
// Estado / utilidades
bool tieneCredenciales() const;
bool connectToWiFi();
bool isConnected();
int getSignalStrength(); // RSSI
uint64_t getTimestamp(); // ms (0 si no hay NTP)
bool hayInternet(); // generate_204
bool scanRedDetectada();
void forzarReconexion();
// LED
enum class LedPattern { OFF, ON, BLINK_SLOW, BLINK_FAST, BLINK_DOUBLE, BLINK_TRIPLE };
void setLedAuto(bool enable);
void setLedPatternManual(LedPattern p);
// Seguridad FS (.json protegidos)
void setProtectedJsons(std::initializer_list names); // ej: {"/wifi.json","licencia.json"}
```
---
## 🔘 Botón y 💡 LED
- **Botón** (pin por defecto **0**, `INPUT_PULLUP`, activo en LOW):
- **2–5 s** → abre portal (si `enableButtonPortal(true)`)
- **≥5 s** → borra `.json` (respeta `setProtectedJsons`) y reinicia
- **LED** (pin por defecto **2**):
- `ON` conectado a Wi‑Fi
- `BLINK_SLOW` portal activo
- `BLINK_FAST` escaneando
- `BLINK_DOUBLE / TRIPLE` feedback al mantener botón
- `OFF` sin enlace/portal
> Podés fijar el patrón manual (`setLedPatternManual`) o dejarlo automático (`setLedAuto(true)`).
---
## 📋 Logging (opcional, recomendado)
Incluye `include/AWM_Logging.h` con macros:
```cpp
AWM_LOGE("error: %d", code); // Error
AWM_LOGW("warning...");
AWM_LOGI("info...");
AWM_LOGD("debug x=%d", x);
AWM_LOGV("verbose...");
```
Activación por **flags de compilación** (PlatformIO):
```ini
build_flags =
-D AWM_ENABLE_LOG=1
-D AWM_LOG_LEVEL=3 ; 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG, 5=VERBOSE
```
- Poné `AWM_ENABLE_LOG=0` para apagar **todos** los logs (macro‑noops).
- Subí/bajá `AWM_LOG_LEVEL` según lo que quieras ver.
---
## 🗂 Archivos del portal (LittleFS)
- `data/index.html` – escaneo, filtro, selección de SSID, formulario de guardado, opciones avanzadas
- `data/success.html` – confirmación de guardado (SVG con pulso; el equipo se reinicia)
- `data/error.html` – error de guardado (SVG con vibración sutil + enlace “Volver”)
> Cambiá la raíz con `setHtmlPathPrefix("/wifimanager")` si preferís otra carpeta.
**Subida del FS**
- PlatformIO: `pio run -t uploadfs`
- Arduino IDE: herramienta “Data Upload”
---
## 🔁 Migrando desde tzapu/WiFiManager
AyresWiFiManager busca ser **simple y explícito**:
- Sin *auto‑magia* de configuración: vos decidís **cuándo** abrir portal y **por cuánto**.
- Portal verdaderamente **cautivo** (DNS + rutas), no solo un AP + webserver.
- UI moderna sin CDNs, pensada para ESPs con poca RAM/flash.
- **Borrado seguro** de `.json` con whitelist y (en ESP32) **recursivo**.
- **Logging** integrable y niveles ajustables.
---
## 📚 Ejemplos
- `examples/AWM_Minimal/AWM_Minimal.ino` – uso mínimo (`begin()`, `update()`, `isConnected()`).
- `examples/AWM_Advanced/AWM_Advanced.ino` – LED de estado, botón de pulsación corta → portal, NTP, reconexión.
- `examples/standard/main.cpp` – flujo simple estándar.
- `examples/30sVentana/main.cpp` – “ventana” de arranque de 30 s si existen credenciales.
- `examples/usedExample/usedExample.ino` – ejemplo de uso legado.
---
## 🗃 Estructura del repo
```text
AyresWiFiManager/
├─ data/ # Captive-portal HTML/CSS/JS (LittleFS examples)
│ ├─ index.html # Main portal page
│ ├─ success.html # Confirmation after saving credentials
│ └─ error.html # Error page
│
├─ examples/ # Example sketches (Arduino IDE & PlatformIO)
│ ├─ AWM_Minimal/
│ │ └─ AWM_Minimal.ino # Minimal usage (begin + update + isConnected)
│ ├─ AWM_Advanced/
│ │ └─ AWM_Advanced.ino # Advanced: LED, button, NTP, reconnect
│ ├─ standard/
│ │ └─ main.cpp # Simple reference flow
│ ├─ 30sVentana/
│ │ └─ main.cpp # 30s "boot window" captive portal
│ └─ usedExample/
│ └─ usedExample.ino # Legacy usage example
│
├─ src/ # Core library sources
│ ├─ AyresWiFiManager.h # Main header (public API)
│ ├─ AyresWiFiManager.cpp # Implementation
│ └─ AWM_Logging.h # Optional lightweight logging macros
│
├─ library.properties # Arduino Library Manager metadata
├─ library.json # PlatformIO metadata
├─ platformio.ini # Example PIO project config
├─ LICENSE # MIT License
├─ README.md # Main documentation (English)
└─ README.es.md # Documentation in Spanish
```
> Si querés mantener librerías locales fuera del repo, añadí rutas a `.gitignore` (ej.: `lib/AyresShell/`).
---
## 📂 Captive portal HTML
Los archivos del portal (`index.html`, `success.html`, `error.html`) deben
subirse al **LittleFS del sketch del usuario**:
1. Copiá los archivos desde `data/` de esta librería al directorio `data/`
de **tu sketch**.
2. Subilos al dispositivo:
- **Arduino IDE**: menú → *ESP32 LittleFS Data Upload*
- **PlatformIO**:
```bash
pio run --target uploadfs
```
> ⚠️ **Nota importante:**
> El `data/` en la raíz de esta librería es **solo de referencia/ejemplo**.
> No se sube automáticamente cuando compilás un sketch.
---
## ✅ Consejos de producción
- **Protegé** archivos críticos:
`wifi.setProtectedJsons({"/wifi.json","licencia.json"});`
- Definí **timeouts por inactividad** coherentes (`setPortalTimeout`) y activá `setAPClientCheck(true)` + `setWebClientCheck(true)` si no querés que se cierre mientras lo usan.
- Para instalaciones remotas, `setFallbackPolicy(SMART_RETRIES)` + `setAutoReconnect(true)` suelen dar buena experiencia.
- Si necesitás ahorrar logs en producción: `-D AWM_ENABLE_LOG=0`.
---
## 🧩 Compatibilidad
- **ESP32** (Arduino core)
- **ESP8266** (Arduino core)
> Requiere **LittleFS**. En ESP32 se auto‑formatea si `begin(true)` falla.
---
## 🤝 Contribuir
¡PRs e issues son bienvenidos!
Ideas: ejemplos adicionales, traducciones, mejoras UI/UX del portal, nuevas políticas de fallback.
---
## 📄 Licencia
MIT — ver archivo `LICENSE` (o cabeceras SPDX en el código).
---
> 📘 [Leer en ingles → README.md](README.md)
¿Dudas o ideas? Abrí un issue en el repo. ¡Gracias por probar **AyresWiFiManager**! 🚀