WebPlatform Library

A comprehensive web development platform for ESP32 that provides a unified framework for building web-enabled embedded applications.

🚀 Quick Start

New to WebPlatform? Get your ESP32 web application running in minutes:

👉 Quick Start Guide - 5-minute setup with code examples
⚙️ Configuration Template - Copy-paste PlatformIO config
📋 Working Examples - Complete code samples

Documentation

User Guide - Detailed usage instructions and examples
API Reference - Complete API documentation
Authentication Guide - Detailed authentication system documentation
Examples - Example applications and modules

Overview

WebPlatform is a complete web development framework that transforms ESP32 devices into sophisticated web-enabled applications. It combines multiple components into a single, easy-to-use library:

Modular Architecture: Build reusable web modules using the IWebModule interface
Unified HTTP/HTTPS Server: Single server instance with automatic HTTPS detection
WiFi Management: Captive portal for configuration and automatic connection handling
Advanced Authentication: Session-based and token-based authentication with CSRF protection
Dual Storage System: JSON driver for fast access + LittleFS driver for large data
Route Management: Advanced route handling with override and disable capabilities
Asset Management: Static asset serving with built-in CSS/JS framework

Target Audiences

Application Developers

Build complete embedded web applications by leveraging the WebPlatform and optional web modules. The platform handles WiFi setup, authentication, HTTPS, and provides a solid foundation for your device's web interface.

Module Developers

Create reusable web modules using the IWebModule interface that can be shared across projects. Modules can define their own routes, authentication requirements, and UI components while integrating seamlessly with any WebPlatform application.

Quick Start

For Application Developers

#include <web_platform.h>
// #include <some_module.h>  // Include your web modules

void setup() {
    Serial.begin(115200);
    // Set up navigation menu with authentication-aware items
    std::vector<NavigationItem> navItems = {
        NavigationItem("Home", "/"),
        NavigationItem("Settings", "/settings/"),
        NavigationItem("About", "/about"),
        Authenticated(NavigationItem("Account", "/account")),
        Authenticated(NavigationItem("Logout", "/logout")),
        Unauthenticated(NavigationItem("Login", "/login"))
    };
    webPlatform.setNavigationMenu(navItems);

    // Initialize WebPlatform (auto-detects HTTPS capability)
    webPlatform.begin("MyDevice");
    
    if (webPlatform.isConnected()) {
        // Register web modules
        // webPlatform.registerModule("/device", &deviceModule);
        
        // Add custom application routes
        webPlatform.registerWebRoute("/about", [](WebRequest& req, WebResponse& res) {
            String html = "<h1>About My Device</h1><p>Built with WebPlatform</p>";
            res.setContent(html, "text/html");
        }, {AuthType::SESSION});  // Protect with login
        
        // Override module routes if needed
        webPlatform.overrideRoute("/", customHomeHandler, {AuthType::SESSION});
    }
}

void loop() {
    webPlatform.handle();
    
    if (webPlatform.isConnected()) {
        // Handle registered modules
        // deviceModule.handle();
    }
}

For Module Developers

#include <web_platform.h>

class MyModule : public IWebModule {
public:
    std::vector<RouteVariant> getHttpRoutes() override {
        return {
            WebRoute("/", WebModule::WM_GET, 
                [this](WebRequest& req, WebResponse& res) {
                    res.setContent(getMainPage(), "text/html");
                }),
            ApiRoute("/data", WebModule::WM_GET, 
                [this](WebRequest& req, WebResponse& res) {
                    res.setContent(getDataJSON(), "application/json");
                }, {AuthType::TOKEN})  // API requires token authentication
        };
    }
    
    std::vector<RouteVariant> getHttpsRoutes() override {
        return getHttpRoutes(); // Same routes for HTTP and HTTPS
    }
    
    String getModuleName() const override { 
        return "My Custom Module"; 
    }
    
private:
    String getMainPage() { /* return HTML content */ }
    String getDataJSON() { /* return JSON data */ }
};

Build Configuration

To use WebPlatform in your project, add the following to your platformio.ini:

HTTP-only Mode (default)

[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps = 
  bblanchon/ArduinoJson@^6.20.0
  # Add your web modules here

HTTPS Mode

[env:esp32-https]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps = 
  bblanchon/ArduinoJson@^6.20.0
  # Add your web modules here
  
# HTTPS certificate embedding - certificate files must exist in src/ directory
board_build.embed_txtfiles = 
  src/server_cert.pem
  src/server_key.pem

Generate SSL Certificates

# Generate private key
openssl genrsa -out src/server_key.pem 2048

# Generate certificate signing request
openssl req -new -key src/server_key.pem -out src/server_csr.pem

# Generate self-signed certificate (valid for 365 days)
openssl x509 -req -days 365 -in src/server_csr.pem -signkey src/server_key.pem -out src/server_cert.pem

# Clean up temporary file
rm src/server_csr.pem

Key Features

For more information on WebPlatform features, see the User Guide.

Dual-mode Operation: WiFi configuration portal and application modes
Authentication System: Session-based and token-based authentication
Route Management: Register, override, and disable routes with OpenAPI documentation support
OpenAPI 3.0 Integration: Automatic API documentation generation for registered routes
Template System: HTML templates with automatic bookmark replacement
Dual Storage Drivers: JSON (fast, small data) and LittleFS (scalable, large data) with unified query interface
HTTPS Support: Automatic HTTPS when certificates available
Asset Streaming: Memory-efficient serving of embedded assets using PROGMEM streaming

Learn More

Compatible Modules

The following modules are designed to work with WebPlatform:

Maker API - Interactive API documentation and testing interface specifically for maker-friendly public APIs
USB PD Controller - USB-C Power Delivery voltage and current control with web interface
More modules coming soon...

Dual OpenAPI 3.0 Support

WebPlatform includes built-in support for dual OpenAPI 3.0 specification generation:

Full OpenAPI Specification

Complete API documentation for all registered routes
Intended for internal development and system administration
Available at /openapi.json when enabled

Maker API Specification

Filtered specification containing only routes tagged for public/maker consumption
Routes tagged with "maker" or configured tags
Ideal for external documentation and client SDK generation
Available at /maker/openapi.json when enabled

Build Configuration

Both systems are disabled by default to conserve memory:

# Enable full OpenAPI documentation
build_flags = -DWEB_PLATFORM_OPENAPI=1

# Enable Maker API documentation (filtered subset)
build_flags = -DWEB_PLATFORM_MAKERAPI=1

# Enable both (recommended for development)
build_flags = 
  -DWEB_PLATFORM_OPENAPI=1
  -DWEB_PLATFORM_MAKERAPI=1

Using OpenAPI with Third-Party Tools

Full OpenAPI Specification (/openapi.json):

Internal Development: Complete API reference for system developers
Administrative Tools: Full access to all system endpoints
Swagger UI: Comprehensive interactive documentation

Maker API Specification (/maker/openapi.json):

Public Documentation: Clean, focused API docs for end users
Postman: Generate focused collections for public APIs
Client SDKs: Generate libraries containing only public endpoints
Integration Guides: Simplified API reference for makers

Example with Dual OpenAPI Documentation

// Route appears in both Full API and Maker API (has "maker" tag)
webPlatform.registerApiRoute("/device/status", 
    [](WebRequest& req, WebResponse& res) {
        res.setContent("{\"status\":\"online\",\"uptime\":12345}", "application/json");
    }, 
    {AuthType::TOKEN}, 
    WebModule::WM_GET,
    API_DOC("Get device status", 
            "Returns current device status including uptime and connection info",
            "getDeviceStatus", 
            {"maker", "device"}));

// Route appears only in Full API (no maker tag)
webPlatform.registerApiRoute("/admin/config", 
    [](WebRequest& req, WebResponse& res) {
        res.setContent("{\"config\":\"internal\"}", "application/json");
    }, 
    {AuthType::SESSION}, 
    WebModule::WM_GET,
    API_DOC("Get admin config", 
            "Internal system configuration",
            "getAdminConfig", 
            {"admin"}));

Requirements

ESP32 development board
PlatformIO development environment
Arduino framework for ESP32
ArduinoJson library (automatically installed)

Hardware Compatibility

ESP32 (specific variant compatibility should be verified for your use case)
All testing preformed on ESP32-S3

Performance Considerations

Performance varies based on:

ESP32 variant and clock speed
Available RAM and flash memory
Network conditions
Application complexity
Enabled features (HTTPS, OpenAPI documentation)

Troubleshooting

Common Issues

WiFi Connection Issues

Ensure correct credentials in captive portal
Check WiFi signal strength
Verify network supports ESP32 (2.4GHz only)

Memory Issues

Reduce concurrent connections
Disable unused features (OpenAPI, HTTPS)
Use LittleFS driver for large data instead of JSON driver

HTTPS Certificate Issues

Verify certificate files are in src/ directory
Check certificate format (PEM)
Ensure board_build.embed_txtfiles is correctly configured

Debug Mode

Enable debug output in your platformio.ini:

build_flags = 
  -DCORE_DEBUG_LEVEL=3
  -DWEB_PLATFORM_DEBUG=1

WebPlatform Modules

The WebPlatform ecosystem includes specialized modules for common embedded applications:

Maker API Module: Interactive API documentation interface with OpenAPI 3.0 support, Swagger UI, and maker-friendly filtering
USB PD Controller: USB-C Power Delivery control module supporting 5V-20V output with real-time monitoring and configuration

More modules in development - contributions welcome!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for the ESP32 community

WebPlatform - Transforming ESP32 devices into sophisticated web-enabled applications

Name		Name	Last commit message	Last commit date
Latest commit History 98 Commits
assets		assets
examples		examples
include		include
src		src
.gitignore		.gitignore
API.md		API.md
AUTH.md		AUTH.md
GUIDE.md		GUIDE.md
LICENSE		LICENSE
QUICK_START.md		QUICK_START.md
README.md		README.md
library.json		library.json
platformio.ini.example		platformio.ini.example

License

andrewmherren/web_platform

Folders and files

Latest commit

History

Repository files navigation

WebPlatform Library

🚀 Quick Start

Documentation

Overview

Target Audiences

Application Developers

Module Developers

Quick Start

For Application Developers

For Module Developers

Build Configuration

HTTP-only Mode (default)

HTTPS Mode

Generate SSL Certificates

Key Features

Learn More

Compatible Modules

Dual OpenAPI 3.0 Support

Full OpenAPI Specification

Maker API Specification

Build Configuration

Using OpenAPI with Third-Party Tools

Example with Dual OpenAPI Documentation

Requirements

Hardware Compatibility

Performance Considerations

Troubleshooting

Common Issues

Debug Mode

WebPlatform Modules

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages