{"id":29674243,"url":"https://github.com/lennart080/esp8266-captiveportal","last_synced_at":"2025-07-22T23:01:46.634Z","repository":{"id":298551708,"uuid":"1000332160","full_name":"lennart080/ESP8266-CaptivePortal","owner":"lennart080","description":"A lightweight captive portal library for ESP8266.","archived":false,"fork":false,"pushed_at":"2025-07-17T15:01:17.000Z","size":55,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-17T17:36:50.688Z","etag":null,"topics":["arduino","arduino-library","authentication","captive-portal","captiveportal","embedded","esp8266","esp8266-arduino","esp8266-esp-12e","esp8266-library","firmware","hotspot","iot","library","microcontroller","networking","platformio","platformio-library","portal","wifi"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lennart080.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-11T16:01:57.000Z","updated_at":"2025-07-17T14:55:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"c99c020a-36b6-4ab3-9f7a-5f12de81490f","html_url":"https://github.com/lennart080/ESP8266-CaptivePortal","commit_stats":null,"previous_names":["lennart080/esp8266-captiveportal"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/lennart080/ESP8266-CaptivePortal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lennart080%2FESP8266-CaptivePortal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lennart080%2FESP8266-CaptivePortal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lennart080%2FESP8266-CaptivePortal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lennart080%2FESP8266-CaptivePortal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lennart080","download_url":"https://codeload.github.com/lennart080/ESP8266-CaptivePortal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lennart080%2FESP8266-CaptivePortal/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266586839,"owners_count":23952195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","arduino-library","authentication","captive-portal","captiveportal","embedded","esp8266","esp8266-arduino","esp8266-esp-12e","esp8266-library","firmware","hotspot","iot","library","microcontroller","networking","platformio","platformio-library","portal","wifi"],"created_at":"2025-07-22T23:00:36.334Z","updated_at":"2025-07-22T23:01:46.602Z","avatar_url":"https://github.com/lennart080.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CaptivePortal\n[![License](https://img.shields.io/github/license/lennart080/ESP8266-CaptivePortal?color=blue)](https://github.com/lennart080/ESP8266-CaptivePortal/blob/main/LICENSE)\n[![PlatformIO Registry](https://badgen.net/badge/PlatformIO/Available/green?icon=platformio)](https://registry.platformio.org/libraries/lennart080/ESP8266-CaptivePortal)\n[![GitHub Release](https://img.shields.io/github/v/release/lennart080/ESP8266-CaptivePortal)](https://github.com/lennart080/ESP8266-CaptivePortal/releases)\n\nA lightweight captive portal library for ESP8266 (Arduino/PlatformIO).  \nLets users connect to a temporary WiFi access point, open a web portal, and interact with your device (e.g., submit WiFi credentials or other data).\n\n---\n\n## Features\n\n- **Captive portal:** Redirects all DNS and HTTP traffic to the ESP for easy setup.\n- **Static file serving:** Serves files (e.g., `index.html`, CSS, JS) from LittleFS.\n- **Custom API endpoints:** Easily add your own HTTP handlers (e.g., `/api/wifi`).\n- **Captive portal detection:** Handles Android, Windows, and Apple captive portal checks.\n- **Simple API:** Minimal setup, easy to extend.\n\n---\n\n## Example Project\n\nLooking for a ready-to-use example?  \nCheck out the [ESP8266-CaptivePortal-ExampleProject](https://github.com/lennart080/ESP8266-CaptivePortal-ExampleProject).\n\n---\n\n## Getting Started\n\n### Hardware Requirements\n\n- ESP8266-based board (e.g., NodeMCU, Wemos D1 Mini)\n- PlatformIO or Arduino IDE\n\n---\n\n## Installation\n\n### PlatformIO\n\nAdd this library to your `platformio.ini`:\n```\nlib_deps =\n    lennart080/CaptivePortal\n    # Optional: Only add the following if PlatformIO cannot find ESPAsyncWebServer automatically\n    me-no-dev/ESPAsyncWebServer\n```\n\u003e **Note:**  \n\u003e The `me-no-dev/ESPAsyncWebServer` dependency is optional and should only be added if PlatformIO fails to resolve it automatically and you encounter an error about a missing library.\n\nOr install via the PlatformIO Library Manager.\n\n### Arduino IDE\n\n1. Download this repository as a ZIP file.\n2. In Arduino IDE, go to **Sketch \u003e Include Library \u003e Add .ZIP Library...** and select the downloaded ZIP.\n3. Install the required dependencies:\n    - [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer)\n    - [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP)\n    - [LittleFS](https://github.com/earlephilhower/arduino-esp8266littlefs)\n\n### LittleFS Data Upload\n\nTo serve web files (like `index.html`), upload them to the ESP8266's LittleFS filesystem.\n\n- **PlatformIO:**  \n  LittleFS upload is natively supported. Add to your `platformio.ini`:\n  ```\n  board_build.filesystem = littlefs\n  ```\n  Place your web files in the `/data` folder. Then run:\n  ```\n  pio run --target uploadfs\n  ```\n\n- **Arduino IDE:**  \n  Use the [LittleFS Data Upload tool](https://github.com/earlephilhower/arduino-esp8266littlefs#uploading-files-to-filesystem).\n\n---\n\n## Usage\n\n### 1. Include and Create\n\n```cpp\n#include \"CaptivePortal.h\"\nCaptivePortal portal;\n```\n\n### 2. Initialize and Start the Portal\n\nYou can initialize the portal as an open AP (no password):\n\n```cpp\nif (!portal.initializeOpen(\"My-Example-AP\", \"index.html\")) {\n    Serial.println(\"Init failed: \" + portal.getLastErrorString());\n}\n```\n\nOr as a password-protected AP:\n\n```cpp\nif (!portal.initialize(\"My-Example-AP\", \"12345678\", \"index.html\")) {\n    Serial.println(\"Init failed: \" + portal.getLastErrorString());\n}\n```\n- The password must be 8–63 characters for WPA2 AP mode.\n- The third argument is the default file to serve (e.g., `\"index.html\"` from LittleFS).\n\nStart the portal:\n\n```cpp\nif (!portal.startAP()) {\n    Serial.println(\"Start failed: \" + portal.getLastErrorString());\n}\n```\n\n### 3. Main Loop\n\nCall `processDNS()` in your loop to handle DNS redirection:\n\n```cpp\nvoid loop() {\n    portal.processDNS();\n    delay(100);\n}\n```\n\n### 4. Adding Custom API Endpoints\n\nYou can add your own HTTP handlers using the underlying AsyncWebServer:\n\n```cpp\nportal.getServer().on(\"/api\", HTTP_POST, [](AsyncWebServerRequest *request) {\n    if (request-\u003ehasParam(\"text\", true)) {\n        String text = request-\u003egetParam(\"text\", true)-\u003evalue();\n        // Save credentials, connect, etc.\n        request-\u003esend(200, \"text/plain\", \"Text received.\");\n        portal.stopAP();\n    } else {\n        request-\u003esend(400, \"text/plain\", \"Missing Text.\");\n    }\n});\n```\n\n#### Example `script.js` for Sending Data to `/api`\n\nHere’s a simple example of how you could send data from your frontend to the custom API endpoint using JavaScript:\n\n```js\nfunction sendText() {\n    const text = document.getElementById('textInput').value;\n    fetch('/api', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n        body: 'text=' + encodeURIComponent(text)\n    })\n    .then(response =\u003e response.text())\n    .then(data =\u003e {\n        alert('Server response: ' + data);\n    })\n    .catch(error =\u003e {\n        alert('Error: ' + error);\n    });\n}\n```\n\nAnd in your `index.html`:\n\n```html\n\u003cinput id=\"textInput\" type=\"text\" placeholder=\"Enter text\"\u003e\n\u003cbutton onclick=\"sendText()\"\u003eSend\u003c/button\u003e\n\u003cscript src=\"script.js\"\u003e\u003c/script\u003e\n```\n\n- This example sends the value from an input field to your `/api` endpoint using a POST request.\n- Adjust the parameter name and logic as needed for your use case.\n\n### 5. Serving the Web Interface\n\n- Place your `index.html`, `style.css`, and `script.js` in the device's LittleFS filesystem.\n- The portal will serve these files automatically at `/`.\n\n---\n\n## Troubleshooting\n\n- **LittleFS mount failed:** Ensure you have uploaded files to LittleFS and the filesystem is formatted.\n- **File not found:** Make sure your default file (e.g., `index.html`) exists in LittleFS.\n- **Invalid SSID/Password:** SSID must be 1–32 chars; password must be 8–63 chars or empty for open AP.\n- **AP won't start:** Check for conflicting WiFi modes or hardware issues.\n\n---\n\n## API Reference\n\n| Method                                         | Description                                      |\n|------------------------------------------------|--------------------------------------------------|\n| `bool initializeOpen(ssid, defaultFile)`       | Open AP, no password.                            |\n| `bool initialize(ssid, password, defaultFile)`  | WPA2 AP, with password.                          |\n| `bool startAP()`                               | Start the AP and web server.                     |\n| `bool stopAP()`                                | Stop the AP and web server.                      |\n| `void processDNS()`                            | Handle DNS requests (call in loop).              |\n| `AsyncWebServer\u0026 getServer()`                  | Access the underlying AsyncWebServer.            |\n| `CaptivePortalError getLastError() const`      | Get the last error code.                         |\n| `String getLastErrorString() const`            | Get a string describing the last error.          |\n\n---\n\n## License\n\nThis project is licensed under the Apache 2.0 License.\n\nYou may use, share and modify it, as long as you give credit to:\n\n**Lennart Gutjahr (2025)** — Original author  \n**gutjahrlennart@gmail.com** — Email\n\nLicense details: [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)\n\n---\n\n## Credits\n\nBased on [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer) and [LittleFS](https://github.com/earlephilhower/arduino-esp8266littlefs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flennart080%2Fesp8266-captiveportal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flennart080%2Fesp8266-captiveportal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flennart080%2Fesp8266-captiveportal/lists"}