Embedded Web Server API: HttpServerCopy Anchor Link

The HttpServer (or System.httpServer) object allows JavaScript applications to host a multi-client HTTP server on the ESP32. It can serve static web pages from flash or SD card and process dynamic REST API requests.

Embedded server source code is available in the KryonOS GitHub Repository.

1. Server LifecycleCopy Anchor Link

HttpServer.begin(port)Copy Anchor Link

Starts listening for incoming HTTP connections on the designated TCP port.

• Parameters: port (Integer, optional, default 80).
• Returns: Boolean (true if server listening).

HttpServer.stop()Copy Anchor Link

Stops the server and closes all active client connections.

• Parameters: None
• Returns: Boolean

2. Route HandlingCopy Anchor Link

HttpServer.on(method, path, handler)Copy Anchor Link

Registers an endpoint callback for a specific HTTP method and path.

• Parameters:
  • method (String): "GET", "POST", "PUT", or "DELETE".
  • path (String): Route URL path (e.g. "/api/status").
  • handler (Function): Callback function function(req, res).

Request Object (req)Copy Anchor Link

Response Object (res)Copy Anchor Link

• res.status(code): Sets HTTP response status code (default 200). Returns res for chaining.
• res.setHeader(name, value): Sets a response header.
• res.send(content): Sends raw text or HTML body.
• res.json(object): Serializes an object to JSON and sets Content-Type: application/json.

3. Static File ServingCopy Anchor Link

HttpServer.serveStatic(urlPrefix, fsPath)Copy Anchor Link

Maps an entire folder on /local/ or /sd/ to a URL route prefix. Automatically sets appropriate MIME types (.html, .css, .js, .png, .svg).

• Parameters:
  • urlPrefix (String): e.g. "/" or "/assets"
  • fsPath (String): e.g. "/sd/www/" or "/local/dashboard/"
• Returns: Boolean

Complete Example: Web-Controlled Device DashboardCopy Anchor Link

// Start HTTP server on port 80
HttpServer.begin(80);

// 1. Serve static HTML/CSS web frontend from SD card
HttpServer.serveStatic("/", "/sd/www/");

// 2. REST API: Device telemetry endpoint
HttpServer.on("GET", "/api/status", function(req, res) {
  var info = System.getInfo();
  res.json({
    os: "KryonOS",
    uptimeSeconds: Math.floor(System.millis() / 1000),
    freeHeap: info.freeRAM,
    temperature: System.getTemperature()
  });
});

// 3. REST API: Control GPIO pin
HttpServer.on("POST", "/api/gpio", function(req, res) {
  try {
    var data = JSON.parse(req.body);
    var pin = data.pin;
    var state = data.state === 1 ? System.gpio.HIGH : System.gpio.LOW;
    
    System.gpio.pinMode(pin, System.gpio.OUTPUT);
    System.gpio.digitalWrite(pin, state);
    
    res.json({ success: true, pin: pin, state: data.state });
  } catch(e) {
    res.status(400).json({ error: "Invalid JSON body" });
  }
});

System.print("HTTP Server running on http://" + System.getIPAddress());