Arduino library 路 Network

ESP32 WiFi, HTTPClient and WebServer: the core libraries for networking

These three come with the ESP32 Arduino core, so there is nothing to install. WiFi.h joins a network in station mode and reports the address it got; HTTPClient.h makes HTTP requests and hands back the status code and body; WebServer.h listens on port 80 and calls your function for each path a browser asks for.

Built in on Mokxi: #include <WiFi.h> and it builds, with nothing to install. Free, and no account needed.

What WiFi, HTTPClient and WebServer (ESP32 core) does

Joining is asynchronous. WiFi.begin() starts the connection and returns at once, so a sketch waits in a loop until WiFi.status() reports WL_CONNECTED, usually printing dots, and only then makes a request or starts the server. WiFi.localIP() is the address to type into a browser.

A web server sketch has one rule for loop(): call server.handleClient() on every pass. Each handler you registered with server.on() runs from inside that call, reads arguments with server.arg() and answers with server.send(). The ESP8266 core has the same calls under ESP8266WiFi.h, ESP8266HTTPClient.h and ESP8266WebServer.h.

Library Manager nameWiFi, HTTPClient and WebServer (ESP32 core)
AuthorEspressif
Include#include <WiFi.h>
#include <HTTPClient.h>
#include <WebServer.h>
#include <WiFiClient.h>
BoardsESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi
In the simulatorRuns, with a gap the note below names.

Install it

It builds on ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi.

In Mokxi it is built in: #include <WiFi.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board it comes with the board package (Espressif), so the Arduino IDE has it as soon as the board is installed: there is nothing to add from the Library Manager.

ESP32-C3 路 ESP32-C6 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32 DevKit 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 ESP32-S3-DevKitC-1 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 ESP8266 NodeMCU 路 Raspberry Pi Pico W 路 Arduino Uno R4 WiFi

The calls you will use

In the order a sketch meets them.

WiFi.begin("Mokxi-Lab", "breadboard")

Starts joining a network with its name and password. It returns before the board is connected.

WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED) {
  delay(500);
  Serial.print(".");
}

WiFi.status()

WL_CONNECTED once joined; WL_DISCONNECTED, WL_NO_SSID_AVAIL or WL_CONNECT_FAILED tell you what is wrong while it is not.

WiFi.localIP()

The board鈥檚 IP address on the network, printable with Serial.println().

http.begin(client, "http://weather.mokxi/")

Sets up a request to a URL through a WiFiClient. Nothing is sent until GET() or POST().

http.GET()

Sends the request and returns the HTTP status (200 for OK), or a negative error code when the request did not get an answer.

int code = http.GET();
if (code > 0) Serial.println(http.getString());
else Serial.println(http.errorToString(code));
http.end();

http.getString()

The response body as a String. Call http.end() afterward to free the connection.

server.on("/", handleRoot)

Registers the function that answers a path. Lambdas work too: server.on("/on", [](){ ... });

server.send(200, "text/html", page)

Answers the current request with a status, a content type and a body.

server.arg("state")

The value of a query or form argument, such as ?state=on, as a String. server.hasArg() checks it is there.

server.handleClient()

Accepts a waiting request and runs its handler. Call it on every pass of loop().

Example: WiFi: a lamp on a web page

On the ESP32-C3-DevKitM-1. It runs in the browser exactly as printed.

sketch.ino 路 ESP32-C3-DevKitM-1
/*
 * WiFi: a lamp on a web page.
 *
 * The server is your code, running on the board's core. The NETWORK under it is
 * SIMULATED: there is no 802.11, no TCP and no listening socket, and the only
 * thing in the world that can reach http://192.168.4.2/ is the Web tab in this
 * page. Nothing outside the browser can, ever.
 *
 * Press Run, open the Web tab, and press On. The LED on GPIO 8 (and any LED
 * you have wired to it) follows the page.
 */
#include <WebServer.h>
#include <WiFi.h>

const char *SSID = "Mokxi-Lab";
const char *PASSWORD = "breadboard";

WebServer server(80);
bool lampOn = false;

void sendPage() {
  String page("<!doctype html><html><head><meta charset=\"utf-8\">");
  page += "<title>Mokxi lamp</title></head><body>";
  page += "<h1>The lamp is ";
  page += lampOn ? "ON" : "OFF";
  page += "</h1><p><a href=\"/on\">On</a> &middot; <a href=\"/off\">Off</a></p>";
  page += "<p><form method=\"post\" action=\"/set\">";
  page += "<button name=\"lamp\" value=\"toggle\">Toggle</button></form></p>";
  page += "<p>Served by the sketch on a simulated network.</p>";
  page += "</body></html>";
  server.send(200, "text/html", page);
}

void applyLamp() {
  digitalWrite(LED_BUILTIN, lampOn ? HIGH : LOW);
  Serial.print("lamp ");
  Serial.println(lampOn ? "on" : "off");
}

void handleRoot() { sendPage(); }

void handleOn() {
  lampOn = true;
  applyLamp();
  sendPage();
}

void handleOff() {
  lampOn = false;
  applyLamp();
  sendPage();
}

void handleSet() {
  if (server.arg("lamp") == "toggle") {
    lampOn = !lampOn;
    applyLamp();
  }
  sendPage();
}

void setup() {
  Serial.begin(115200);
  pinMode(LED_BUILTIN, OUTPUT);
  digitalWrite(LED_BUILTIN, LOW);

  Serial.println("Simulated WiFi: only the Web panel can reach this server.");
  WiFi.begin(SSID, PASSWORD);
  while (WiFi.status() != WL_CONNECTED) {
    Serial.print(".");
    delay(250);
  }
  Serial.println();
  Serial.print("open http://");
  Serial.print(WiFi.localIP());
  Serial.println("/ in the Web tab");

  server.on("/", handleRoot);
  server.on("/on", handleOn);
  server.on("/off", handleOff);
  server.on("/set", handleSet);
  server.begin();
}

void loop() {
  server.handleClient();
  delay(2);
}

Open it in the editor, wired and ready to run 路 WiFi: a lamp on a web page: the project page

Common errors and how to fix them

The dots never stop: stuck waiting for WL_CONNECTED

Wrong network name or password (both are case sensitive), a 5 GHz-only network the ESP32 cannot see, or a router that is out of range. Print WiFi.status() in the loop to see which; WL_NO_SSID_AVAIL means the name was not found.

http.GET() returns -1 (connection refused)

The host did not answer: a wrong address, no internet, or https:// given to a plain client. In Mokxi, only names under .mokxi answer unless real internet mode is switched on, and errorToString() says so.

The web page never loads from the board鈥檚 address

Either server.begin() was not called after server.on(), or loop() does not call server.handleClient(), or it is blocked by a delay(). Keep loop() short so each request is answered at once.

'WiFi' was not declared in this scope on an Arduino Uno

The Uno has no WiFi. WiFi.h here is the ESP32 core鈥檚; use an ESP32, ESP8266, Pico W or Uno R4 WiFi board, each of which has its own WiFi header.

Try WiFi, HTTPClient and WebServer (ESP32 core) without installing anything

Open the example, change the sketch, and keep your version in a free account.