ESP32 — getting started#
No account yet? Create one first: free forever for one device, no card.
Create a free accountThe TollanAgent library lets an ESP32 (or any Arduino board with WiFiClientSecure) be a Tollan device directly — no gateway box, no Go binary. It opens an outbound, mutually authenticated tunnel to the relay, so the board is reachable at a public Tollan address with no inbound ports.
Internet ──▶ Tollan relay ──(mutual TLS)──▶ ESP32 (TollanAgent)
(public port / answers channels
SNI hostname) in your sketchNote
Read the TLS & clock notes before shipping.
What you'll need#
- An ESP32 board and the Arduino-ESP32 core (Arduino IDE,
arduino-cli, or PlatformIO). - A Tollan device bundle for the board — it includes the library and the board's
tollan_config.h(details below).
1. Install the library#
The TollanAgent library ships inside your device's ESP32 bundle (the TollanAgent/ folder) and inside the demo project. Download either from the device's page in the console. It's licensed for use with the Tollan service only — see its LICENSE file.
It comes precompiled for ESP32, ESP32-S2, ESP32-S3 and ESP32-C3 on the Arduino-ESP32 2.x core.
Arduino IDE / CLI — copy the bundle's TollanAgent folder into your Arduino libraries/ directory, select the board package esp32 by Espressif 2.0.x in the Boards Manager, then open File ▸ Examples ▸ TollanAgent ▸ BasicTunnel.
PlatformIO — copy the TollanAgent folder into your project's lib/ directory (the demo project already has it) and link the archive for your chip (esp32, esp32s2, esp32s3 or esp32c3):
[env:esp32dev]
platform = espressif32@^6.13.0 ; Arduino-ESP32 2.0.x — the precompiled library needs it
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -L lib/TollanAgent/src/esp32 -lTollanAgent2. Provision the board (bundle mode)#
Two ways to get this board's configuration onto the hardware: grab a complete, ready-to-flash project in one click, or wire it into your own sketch by hand. Either way there is no private key in the download: the bundle carries a one-time enrollment token, and on first boot the board makes its own key and enrolls (see First boot).
Note
That's the default, Enrollment. When you add the device you can pick Bundle instead (or use Build bundle on the device page; Enrollment token there gives the default file): then tollan_config.h holds this device's certificate and private key (DEVICE_CERT / DEVICE_KEY) and there is no enrollment step. It's convenient for testing, but anyone with that file can connect as the device, so never commit or share it. The examples accept either kind of file.
Download demo project — ready to flash#
On the device's install step in the console, an ESP32 device shows a Download demo project button next to Download locally. It downloads a complete PlatformIO project built for this device — everything already wired:
platformio.ini— build config (boardesp32dev, Arduino framework);src/main.cpp— the BasicTunnel sketch (the library's own maintained example, so it never drifts);src/tollan_config.h— this device's relay endpoint, CA and one-time enrollment token;src/ca.crt— the relay CA as a raw PEM file;lib/tollan-agent/— theTollanAgentlibrary vendored in, so the project builds offline with no separate library install.
Flash it in three steps:
- Unpack the archive and open the folder in VS Code with the PlatformIO extension (or run
pio run). PlatformIO installs the ESP32 toolchain on the first build. - Edit the two Wi-Fi lines at the top of
src/main.cpp—WIFI_SSID/WIFI_PASS. - Connect the board over USB and Upload (
pio run -t upload), then open the Serial Monitor at 115200 baud.
Because the project is prebuilt for the device, it already contains the library (step 1) and the example sketch (step 3) with its configuration baked in — so you can skip straight to flashing and ignore the manual library install and wiring below.
Important
The link is one-time and expires in 15 minutes. The enrollment token inside works once, within 7 days, and a newer bundle or demo project for the same device voids it: download once and flash a single board. Until the board has enrolled, src/tollan_config.h can enroll a board as this device — keep it off shared drives and version control.
Example projects — both modes#
The Example projects button (on an ESP32 device's page, and next to Download demo project) downloads tollan-esp32-examples.zip with two complete PlatformIO projects:
1-basic-connection/— the board itself is the service (the BasicTunnel sketch, handler mode);2-forward-to-other-devices/— the board forwards to other devices on its network (the LanProxy sketch, forwarding mode, paid plans).
They hold no device configuration: download your device's tollan_config.h with Enrollment token on its page, copy it into the project's src/ folder, set Wi-Fi in src/main.cpp, and upload. platformio.ini lists every supported board; esp32dev is the default.
Or wire it up yourself#
Register the board as a device in the console with the ESP32 architecture and download its bundle. It ships a ready-to-include tollan_config.h:
| Constant | Purpose |
|---|---|
TOLLAN_RELAY_HOST / TOLLAN_RELAY_PORT | the relay to dial (cfg.host / cfg.port) |
CA_CERT | CA that signed the relay's server cert — the board pins it |
TOLLAN_ENROLL_URL / TOLLAN_ENROLL_TOKEN | first-boot enrollment: where, and the one-time token |
TOLLAN_ENROLL_CA | roots the board checks the enrollment server's HTTPS against |
TOLLAN_RENEW_URL | certificate renewal |
Drop it next to your sketch and it's picked up automatically:
#if defined(__has_include) && __has_include("tollan_config.h")
# include "tollan_config.h" // shipped in the bundle — the happy path
#else
# warning "tollan_config.h not found — building with PLACEHOLDERS."
// ...placeholders (see examples/BasicTunnel)...
#endifThe #warning means a forgotten config fails loudly at build time instead of silently shipping placeholders.
Note
With a Bundle (key) file, set cfg.clientCert = DEVICE_CERT and cfg.clientKey = DEVICE_KEY instead of the three cfg.enroll* lines shown below; the examples pick the right ones with #ifdef TOLLAN_ENROLL_TOKEN.
Important
Use the bundle's TOLLAN_RELAY_HOST for cfg.host — it must match the relay's certificate exactly — and TOLLAN_RELAY_PORT (443) for cfg.port, which gets through firewalls that block unusual ports.
3. Handler mode: the board is the service#
In the default handler mode, whatever hits the board's public Tollan address arrives in your sketch as channel DATA, and you reply on the same channel. Here's the minimal shape (see the full BasicTunnel example, which serves a live temperature reading as JSON):
#include <WiFi.h>
#include <TollanAgent.h>
using namespace tollan;
TollanAgent agent;
void setup() {
Serial.begin(115200);
WiFi.mode(WIFI_STA);
WiFi.begin("your-wifi", "your-wifi-password");
while (WiFi.status() != WL_CONNECTED) delay(300);
TollanConfig cfg;
cfg.host = TOLLAN_RELAY_HOST; // from tollan_config.h
cfg.port = TOLLAN_RELAY_PORT; // relay control-channel port (443)
cfg.caCert = CA_CERT;
cfg.enrollUrl = TOLLAN_ENROLL_URL; // first boot: the board makes its key and enrolls
cfg.enrollToken = TOLLAN_ENROLL_TOKEN;
cfg.enrollCaCert = TOLLAN_ENROLL_CA;
cfg.renewUrl = TOLLAN_RENEW_URL;
// Answer whatever the relay forwards on a channel.
agent.onData([](uint32_t ch, const uint8_t* data, size_t len) {
const char* body =
"HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n"
"Content-Length: 3\r\nConnection: close\r\n\r\nhi\n";
agent.send(ch, (const uint8_t*)body, strlen(body));
agent.closeChannel(ch);
});
agent.begin(cfg);
}
void loop() {
agent.loop(); // drives connect, reconnect, keepalive, dispatch — call every iteration
delay(2);
}That's the whole integration: configure, register one callback, and call agent.loop() forever.
4. Add a route and test#
Back in the console, add a route to the device with an internal target of the board itself (handler mode doesn't dial anything, so any placeholder target is fine — the board answers directly). Then hit the public address:
curl https://your-board-username.a.tollan.app/The relay opens a channel to the board, your onData runs, and the reply streams back through the tunnel.
What agent.loop() does#
Calling loop() every iteration drives everything cooperatively:
- connecting to the relay and agreeing the protocol version,
- SNTP clock sync before the first TLS handshake (a fresh ESP32 boots near 1970, which breaks certificate date checks — see clock),
- reconnect with jittered exponential backoff,
tollankeepalivePONGs,- inbound frame dispatch to your callbacks.
- automatic certificate renewal, when
cfg.renewUrlis set (see below).
A protocol-version mismatch is terminal — the agent stops and does not reconnect (TollanState::Terminal). Everything else is retried.
First boot (enrollment)#
On its first start the board makes a P-256 private key on the chip, sends a certificate request with the bundle's one-time token to TOLLAN_ENROLL_URL over HTTPS (checked against TOLLAN_ENROLL_CA), and keeps the issued certificate and key in flash (NVS). The key never leaves the board and Tollan never holds it. From then on the bundle is spent: a copy of it can't enroll another board.
- A board that loses the answer retries with the same key and gets the same certificate back.
- An already-used or expired token stops the agent (
TollanState::Terminal) with a clear log line: download a new bundle. - Flashing a bundle with a different token enrolls afresh. The board it replaces keeps working until the new one connects; then its certificate is revoked.
Health and live log#
While connected, the board checks in every 5 minutes. The device page in the console then shows its Health: free memory (and the lowest it has been), Wi-Fi signal, uptime, the last reset reason (a brownout or panic is worth a look) and the library version.
The Stability tab shows the board's last 72 hours: disconnects, how long each reconnect took, outages, and free memory at every check-in, so a slow leak or a flaky Wi-Fi link shows up at a glance. If the board hears nothing from the relay for 45 seconds it drops the link and reconnects by itself (TollanAgent 0.3.1 and later).
The device page also has a Live log for operators and admins: Open live log streams what the board prints, the last 4 KB first and then new lines as they happen. Print with agent.log() instead of Serial to see your own output there:
agent.log().println("pump on");Certificate renewal#
ESP32 bundles define TOLLAN_RENEW_URL in tollan_config.h, and the examples pass it on, so the board renews its certificate automatically:
cfg.renewUrl = TOLLAN_RENEW_URL; // library 0.2.0+Nothing to do on your side. The renewed identity survives reboots and re-flashing the same bundle; flashing a newer bundle takes over from it. Keep the board online now and then so it can renew; one that has been off for too long needs a new bundle.
Note
Bundles downloaded before renewal shipped have no TOLLAN_RENEW_URL. Download a fresh bundle and update the library to 0.2.0 to turn it on.
Next: proxy other hosts on the board's network with forwarding mode, or see the full API reference.