{"id":16122798,"url":"https://github.com/zanzythebar/easynetworkmanager","last_synced_at":"2025-03-18T11:30:57.361Z","repository":{"id":65325758,"uuid":"525073286","full_name":"ZanzyTHEbar/EasyNetworkManager","owner":"ZanzyTHEbar","description":"An easy network manager for the ESP32","archived":false,"fork":false,"pushed_at":"2024-11-05T11:58:21.000Z","size":701,"stargazers_count":14,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-28T09:17:49.425Z","etag":null,"topics":["arduino","esp32","esp8266","mdns","mdns-sd","networkmanager","ota","platformio","restful-api","wifi","wifimanager"],"latest_commit_sha":null,"homepage":"https://zanzythebar.github.io/EasyNetworkManager-Docs/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZanzyTHEbar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2022-08-15T17:14:38.000Z","updated_at":"2025-01-21T10:14:11.000Z","dependencies_parsed_at":"2023-09-26T20:50:52.461Z","dependency_job_id":"e4941390-0a6b-4dd7-a9ac-2144461f51e3","html_url":"https://github.com/ZanzyTHEbar/EasyNetworkManager","commit_stats":null,"previous_names":[],"tags_count":114,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZanzyTHEbar%2FEasyNetworkManager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZanzyTHEbar%2FEasyNetworkManager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZanzyTHEbar%2FEasyNetworkManager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZanzyTHEbar%2FEasyNetworkManager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZanzyTHEbar","download_url":"https://codeload.github.com/ZanzyTHEbar/EasyNetworkManager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243925562,"owners_count":20369907,"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","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","esp32","esp8266","mdns","mdns-sd","networkmanager","ota","platformio","restful-api","wifi","wifimanager"],"created_at":"2024-10-09T21:13:41.621Z","updated_at":"2025-03-18T11:30:57.355Z","avatar_url":"https://github.com/ZanzyTHEbar.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EasyNetworkManager Library\r\n\r\n\u003e [!NOTE]\\\r\n\u003e A documentation website is being built for this library, you canfind it here [Documentation](https://zanzythebar.github.io/EasyNetworkManager-Docs).\\\r\n\u003e Please feel free to ask me any questions in the [repo discussion forum](https://github.com/ZanzyTHEbar/EasyNetworkManager/discussions).\\\r\n\u003e To see an example `Platformio` project that uses this library: \u003chttps://github.com/ZanzyTHEbar/WaterChamber\u003e\\\r\n\u003e To see an example of a widly-used production project that uses this library: \u003chttps://github.com/EyeTrackVR/OpenIris\u003e\r\n\r\nThis is an in-progress library for easy network management.\r\n\r\n\u003e [!IMPORTANT]\\\r\n\u003e This library requires c++17\r\n\u003e see [extras](#extras)\r\n\r\nThis project supports the following boards:\r\n\r\n- ESP8266\r\n- ESP32\r\n  \r\n\u003e [!NOTE]\\\r\n\u003e Full ESP32C3 support is still in development, please report any bugs in the issues section.\r\n\u003e Of note, this has been successfully tested on all boards except for the ESP32C3.\r\n\u003e This library fully supports M5Stack devices.\r\n\r\nThis library provides a WiFi Manager front-end on a customisable URL endpoint using a provided HTML file.\r\n\r\n![WiFi Manager](/assets/images/wifimanager.png)\r\n\r\nIt also provides numerous key features such as:\r\n\r\n- autodiscovery of saved networks\r\n- saving networks to memory\r\n- automatically creating an Access Point if connecting to a wifi network fails\r\n- mDNS\r\n- Async OTA\r\n- OTA\r\n- customisable REST API\r\n- WebSockets\r\n\r\nAnd much more :smile: See the classes below.\r\n\r\nThis library implements the following classes:\r\n\r\n- APIServer - A server that can be used to manage asynchronous REST API methods.\r\n  - has a `handleJSON` method for handling `POST` and `GET` requests. Can send and receive JSON.\r\n  - has a built-in async-ota endpoint that is disabled by default\r\n  \r\n\u003e [!NOTE]\\\r\n\u003e `POST` requests for `JSON` are still in development.\r\n\r\n- WiFiHandler - A class that can be used to manage WiFi connections.\r\n- OTA - A basic OTA handler.\r\n- MDNSHandler - A class that can be used to manage mDNS services.\r\n- Config - A class that can be used to manage configuration files.\r\n- StateManager - A class that can be used to manage the state of your project (very easy to extend).\r\n- Utilities - A folder that has various template files that can be used to manage various utilities.\r\n\r\n## Installation\r\n\r\n### Platformio (recommended)\r\n\r\nYou can install via the `Platformio Registry` by navigating to the `Libraries` section of `Platformio`.\r\nThe library is called `EasyNetworkManager` by `ZanzyTHEbar`.\r\n\r\nif you like to install the bleading edge, in your `platformio.ini` file add the following:\r\n\r\n```ini\r\nlib_deps = \r\n    https://github.com/ZanzyTHEbar/EasyNetworkManager.git\r\n```\r\n\r\n#### Arduino IDE\r\n\r\nTo install this library in your Arduino IDE, you must add all dependencies (sorry) and then download this repository as a zip file and it as any other library :smile:.\r\n\r\n## Dependencies\r\n\r\nAll dependencies _should_ be installed automatically. If not, please make a new issue and I will fix it.\r\n\r\n\u003e [!NOTE]\\\r\n\u003e `ESP8266` support is still in beta, for now you manually have to install the dependancies listed below.\r\n\u003e `ESPAsyncTCP`\r\n\u003e You _may_ need to install `ESP8266WiFi` if the compiler complains about it, but you shouldn't need to.\r\n\r\n### Dependencies used in this project\r\n\r\n- [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer.git)\r\n\r\n`ESP32`\r\n\r\n- [AsyncTCP](https://github.com/me-no-dev/AsyncTCP.git)\r\n\r\n`ESP8266`\r\n\r\n- [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP)\r\n\r\n## Usage\r\n\r\nFor basic usage please see the [examples](/NetworkManager/examples) folder.\r\n\r\nTo use the provided [wifi manager html](/NetworkManager/ui/wifimanager.html) page you don't need to do anything except for set a `define` before you include the library header (for `pio` users see the [Extras](#extras) section)\r\n\r\nThen, build and flash the SPIFFS image as normal.\r\n\r\nFor the ArduinoIDE you will need to follow a tutorial on `SPIFFS` and flash any custom html files using `SPIFFS`.\r\n\r\n\u003e [!WARNING]\\\r\n\u003e SPIFFS tools **do not** work yet in the ArduinoIDE 2.0. Support is coming soon.\r\n\r\n## Configuration\r\n\r\n\u003e [!WARNING]\\\r\n\u003e It is **required** to add a build flag to your setup for the code to function properly.\r\n\r\nFor `platformio`\r\n\r\n```ini\r\nbuild_flags = \r\n  -DASYNCWEBSERVER_REGEX ; add regex support to AsyncWebServer\r\n```\r\n\r\nOptionally you can enable the wifi manager and the async ota here as well:\r\n\r\n```ini\r\nbuild_flags = \r\n  -DASYNCWEBSERVER_REGEX ; add regex support to AsyncWebServer\r\n  -DUSE_WEBMANAGER ; enable wifimanager\r\n  -DUSE_ASYNCOTA ; enable async ota support\r\n```\r\n\r\nFor `ArduinoIDE`:\r\n\r\nCreate, if missing, or update the `platform.local.txt` file.\r\n\r\nThe paths are:\r\n\r\n\u003e Windows\r\n\r\n```bash\r\nWindows: C:\\Users\\(username)\\AppData\\Local\\Arduino15\\packages\\espxxxx\\hardware\\espxxxx\\{version}\\platform.local.txt\r\n```\r\n\r\n\u003e Linux\r\n\r\n```bash\r\nLinux: ~/.arduino15/packages/espxxxx/hardware/espxxxx/{version}/platform.local.txt\r\n```\r\n\r\nThe text to add is:\r\n\r\n```txt\r\ncompiler.cpp.extra_flags=-DASYNCWEBSERVER_REGEX=1\r\n```\r\n\r\nOptionally you can enable the wifi manager here as well:\r\n\r\n```txt\r\ncompiler.cpp.extra_flags=-DASYNCWEBSERVER_REGEX=1 -DUSE_WEBMANAGER=1\r\n```\r\n\r\n\u003e [!WARNING]\\\r\n\u003e This library is still in development, if there are any bugs please report them in the issues section.\r\n\r\n## Modification\r\n\r\nThis library is intended to be modified and extended. If you find any bugs, please make a new issue and I will fix it.\r\n\r\nIf you have any questions, please ask in the [discussions](https://github.com/ZanzyTHEbar/EasyNetworkManager/discussions).\r\n\r\nTo extend any of the enums please use the `data/utilities/enuminheritance.hpp` file.\r\n\r\nTo use your own custom config, simply inherit from the `CustomConfigInterface`, override the `save` and `load` methods,and then register your config.\r\n\r\n```cpp\r\nConfigHandler configHandler(\"baseConf\", MDNS_HOSTNAME);\r\n\r\nclass CustomConfig : public CustomConfigInterface {\r\n    void save() override {\r\n        this-\u003elog(\"Saving custom config\");\r\n    }\r\n\r\n    void load() override {\r\n        otherStuff();\r\n        this-\u003elog(\"Loading custom config\");\r\n    }\r\n    void otherStuff() {\r\n      // do stuff\r\n    }\r\n};\r\n\r\nCustomConfig customConfig;\r\n\r\n// pass our custom config to the base config so that it can use it.\r\nconfigHandler.config.registerUserConfig(\u0026customConfig);\r\n```\r\n\r\n## Extras\r\n\r\nTo see any of the `log` statements used in this library - you need to add this to your `platformio.ini`:\r\n\r\n```ini\r\nbuild_flags = \r\n  -DASYNCWEBSERVER_REGEX # add regex support to AsyncWebServer\r\n  -DUSE_WEBMANAGER # enable wifimanager\r\n  -DCORE_DEBUG_LEVEL=4 # add debug logging in serial monitor\r\n  -std=gnu++17\r\nbuild_unflags = -std=gnu++11\r\n\r\n; other build parameters\r\nmonitor_filters = \r\n esp32_exception_decoder\r\nbuild_type = debug\r\nlib_ldf_mode = deep\r\n```\r\n\r\nIf you want to build in debug mode add this (it's not a build flag):\r\n\r\n```ini\r\nbuild_type = debug\r\n```\r\n\r\n## License\r\n\r\nThis library is licensed under the MIT License.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzanzythebar%2Feasynetworkmanager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzanzythebar%2Feasynetworkmanager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzanzythebar%2Feasynetworkmanager/lists"}