Source: https://mokxi.com/libraries/asynctcp
Updated: 2026-11-17

Libraries / Network

Arduino library · Network

# AsyncTCP: event-driven TCP sockets on the ESP32

Yes, with limits. You can use the Async TCP library online in Mokxi with nothing to install, and the sketch runs in your browser. Part of it is not simulated, and the notes below say which. The example below, "ESP32 async web server: BME280, slider and relay", runs on the ESP32 DevKit V1.

Run the example in Mokxi See the calls

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

## What Async TCP does

AsyncTCP is the layer under ESPAsyncWebServer, and most people meet it as a dependency they had to install. It can also be used on its own: it gives the ESP32 TCP sockets that call your functions when something happens, rather than a socket you poll. A connection arrives, data comes in, the other side hangs up, an error occurs: each one is a callback.

AsyncServer listens on a port and calls onClient() with a new AsyncClient for each connection. On that client you register onData() for incoming bytes and onDisconnect() for the end, answer with write(), and close() when done. To reach out, an AsyncClient registers onConnect() and onError() and calls connect() with a host and port; connect() returns at once and the callbacks report what happened.

The runnable sketch is a tiny raw HTTP server for the editor’s Web panel plus a client that tries example.com. AsyncServer here gets one Web panel request at a time as raw HTTP bytes, and close() sends the reply. Raw outbound TCP is not simulated, so the client’s connect() ends in onError() and onDisconnect() and the serial monitor explains it.

Library Manager name | Async TCP

Author | ESP32Async

Include | #include <AsyncTCP.h>

Boards | 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

In the simulator | Runs, 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.

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

On a real board, install "Async TCP" by ESP32Async from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add Async TCP to lib_deps in PlatformIO. Mokxi follows the calls of release 3.5.0, so a sketch written here builds there too.

What to know in the simulator: Raw TCP is not simulated, so an outbound connect() ends in onError() and onDisconnect() and says why on Serial. AsyncServer gets one Web panel request at a time, as raw HTTP bytes, and close() sends the reply.

- 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

## The calls you will use

In the order a sketch meets them.

### AsyncServer server(80)

A listening socket on port 80. Nothing is accepted until server.begin().

### server.onClient(handleNewClient, nullptr)

Registers the function called with each new AsyncClient pointer. The second argument is passed back to you as arg.

### c->onData(handleData, nullptr)

Registers the function that gets each chunk of received bytes, with a pointer and a length. The data is not null-terminated.

### c->write("hello")

Queues bytes to send and returns how many were accepted. Large replies may need several writes as space frees up.

### c->close()

Closes the connection once queued data has gone. onDisconnect() then runs.

### client.onError(handleError, nullptr)

Registers the function told about a failed or broken connection, with an error code that AsyncClient::errorToString() turns into words.

### client.connect("example.com", 80)

Starts an outbound connection and returns true if it began. The result arrives later in onConnect() or onError().

### server.begin()

Starts listening for connections.

## Example: ESP32 async web server: BME280, slider and relay

On the ESP32 DevKit V1. It runs in the browser exactly as printed.

sketch.ino · ESP32 DevKit V1

The sketch is cut short here; the editor has every line of it.

Open it in the editor, wired and ready to run · ESP32 async web server: BME280, slider and relay: the project page

## Common errors and how to fix them

### Multiple libraries were found for "AsyncTCP.h"

Two copies are installed, usually me-no-dev’s old one and the ESP32Async one, and the build may pick the wrong one for your ESPAsyncWebServer. Remove the old copy from the libraries folder and keep the pair from the same maintainer.

### The ESP32 resets with a task watchdog message during a request

Callbacks run on the AsyncTCP task, and a delay() or a long loop inside one blocks every other connection and trips the watchdog. Copy what you need, return quickly, and do the slow work in loop().

### Free heap shrinks with every request until the board crashes

Each AsyncClient from onClient() is allocated for you and must be freed. Delete it in its onDisconnect() handler, as the example does with delete c, and never use the pointer after that.

## Questions and answers

### Do I need AsyncTCP if I only use ESPAsyncWebServer?

Yes on the ESP32, because the web server is built on it; you install it but rarely call it. On the ESP8266 the equivalent is ESPAsyncTCP.

## Keep going

### Learn

- Connect a Board to WiFi and Serve a Page
- ESP32-C3 SuperMini Pinout: LED, ADC, I2C, Boot Pins

### More network libraries

- PubSubClient
- MQTT
- Blynk
- ThingSpeak
- WiFiManager
- WiFi, HTTPClient and WebServer (ESP32 core)
- WebSockets
- NTPClient

Every built-in library · Open the editor

## Try Async TCP without installing anything

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

Start building free

Open the editor
