uoakinci / espWebAdmin

Web admin tools for esp32 and esp8266 micro devices.

EspWebAdmin

Table of Contents

• About
• Getting Started
• Usage
• Contributing

About

Web based administrator tools for ESP32 and ESP8266 micro devices.

Getting Started

Prerequisites

• EspWebAdmin serves on ESPAsyncWebServer from me-no-dev.
  
• Which requires;
  • ESPAsyncTCP on ESP8266 devices.
  • AsyncTCP on ESP32 devices.
• Web index file ewa.min.htm.gz must stay in a filesystem like an instance of LittleFS, SPIFFS or any other filesystem(publicly inheriting FS class).

Installing

• Arduino

  • Download repository as ZIP file.
  • Use Arduino Library Manager -> Add From zip archive or extract contents to your Arduino library directory.
  • Find more information on arduino docs.

• Platformio

  • Add dependency to your platformio.ini file.

    -lib_deps =
        https://github.com/uoakinci/espWebAdmin.git
    

  • Or download globally in pio command line interface with git capabilities. (Not recommended by the community)

      pio pkg install -g --library https://github.com/uoakinci/espWebAdmin.git
    

Usage

• Server, Filesystem handler and Logger (espWebAdminServer)

  • Include header file espWebAdmin.h and create an instance of espWebAdminHTTPServer with desired filesystem object.

  • Include ewa.min.html.gz file to either "/ewa", "/www" or root directory of filesystem.

    #include <espWebAdmin.h>
    #include <LittleFS.h> ///EspWebAdmin needs a filesystem
    espWebAdminServer server;
    void start()
    {
        ...
        //Construct or begin web admin server with variables
        server.begin( LittleFS ,80 ,"/admin" , "username" , "password" );
        ...
        //ewaServer object can be used as ESPAsyncWebServer pointer
        server->on("/",[](AsyncWebServerRequest *request)
        {
            return request->send(200, "text/plain", "Server Index Page Handler");
        });
        ....
        //Logger object can be obtained from server
        espWebAdminLogger logger=server->getLogger();
        ....
        //logger object can be used as any Print class pointer (eg. Serial pointer)
        logger->println("Start completed.");
    }
    void loop{} //Full Async
    

    • Additional note on lifetime of espWebAdminServer object. This object inherits a reference counted pointer (shared_ptr) of espWebAdminHTTPServer_impl class which holds its own reference in ESPWebAsyncServer's "not found" handler. Resetting or changing "not found" handler with onNotFound() member function will release ownership to the outside espWebAdminServer class again. So if "not found" handlers would be set by the user, managing lifetime of espWebAdminServer instance is required. Otherwise, it is acceptable to construct and destruct espWebAdminServer instance.

        void start()
        {
            ...
            espWebAdminServer srv( LittleFS ,80 ,"/admin" , "username" , "password" );
            somePrintPointerUsingFunction(srv->getLogger());
            ...
        }
      

    • Or even just calling constructor is enough.

        void start()
        {
            ...
            espWebAdminServer( LittleFS ,80 ,"/admin" , "username" , "password" );
            ...
        }
      

  
  
  

• Filesystem Handler (espWebFsHandler)

  • Include header file espWebAdmin.h and construct espWebFsHandler with your own ESPAsyncWebServer instance and desired filesystem object.

  • Include ewa.min.html.gz file to either "/ewa", "/www" or root directory of filesystem.

  • Other functions of EspWebAdmin(currently only Logging) will not work when using Filesystem Handler.

    #include <espWebAdmin.h>
    #include <LittleFS.h> ///EspWebAdmin needs a filesystem
    
    ESPAsyncWebServer server(80);
    espWebFsHandler webAdminHandler;
    void start()
    {
        ...
        server.on("/",[](AsyncWebServerRequest *request)
        {
            return request->send(200, "text/plain", "Server Index Page Handler");
        });
    
        //Construct web admin handler
        webAdminHandler.begin( LittleFS, "/admin", "username", "password" );
        server.addHandler(webAdminHandler);
        ...
    
    }
    void loop{} //Full Async
    

Web Interface

Web interface consists of unified and minified versions of following files in directory web

• index.html
• script.js
• style.css
• codeflask.js (minified)
• Icons comes from icon8 website

Known Bugs

• Sketch and Filesystem binary updates on ESP8266 chip doesn't work currently. I have worked on the subject for a long time searching on web and in arduino framework libraries, but unable to solve the problem. Yet it work perfectly on ESP32 chips.

TODO

• EEPROM Manager interface
• SDCARD Manager interface

License

MIT License