tollan docs Sign up

ESP32 — TLS, clock & troubleshooting#

The two things most likely to stop a first connection are the TLS version and the clock. Both are by-design consequences of running mTLS on a microcontroller, and both have a clean fix.

TLS version#

Most ESP32 cores negotiate TLS 1.2. Tollan's relays accept it, using forward-secret elliptic-curve cipher suites only.

Symptom: the handshake fails with a fatal alert — mbedTLS -30592, "SSL - A fatal alert message was received from our peer."

Fix: make sure cfg.host and cfg.port come from your bundle's tollan_config.h (TOLLAN_RELAY_HOST, TOLLAN_RELAY_PORT). If it persists, contact support with the serial log.

Clock#

mTLS verifies the relay certificate, and X.509 verification checks the certificate's validity window. A board with no RTC boots near 1970, so every 2026-dated cert looks "not yet valid."

Symptom: TLS fails with mbedTLS -9984 ("X509 - Certificate verification failed").

Fix: the agent handles this for you. connect() syncs the clock over SNTP before the first TLS handshake and won't attempt TLS until the clock is real — it backs off and retries instead. Tune or disable via TollanConfig:

FieldDefaultWhen to change
syncClocktrueSet false only if the board already keeps real time (external RTC, or you call configTime() yourself)
ntpServer1 / ntpServer2pool.ntp.org / time.nist.govPoint at a LAN NTP server on an isolated network with no public NTP access
clockSyncTimeoutMs8000Raise on a slow or high-latency link

You can check readiness in code with agent.clockReady().

Protocol version#

A protocol-version mismatch is terminal: the agent enters TollanState::Terminal and stops, rather than reconnect-looping against a relay it can't talk to. Use the library that ships with your bundle.

Common issues#

SymptomLikely causeFix
state() never leaves Disconnected, mbedTLS -30592Wrong relay host or portUse TOLLAN_RELAY_HOST / TOLLAN_RELAY_PORT from the bundle
mbedTLS -9984 on every attemptClock not synced (board thinks it's 1970)Ensure syncClock is on and NTP is reachable
Stuck before TLS, no NTP replyNo route to pool.ntp.orgSet ntpServer1 to a LAN NTP server
state() goes straight to TerminalProtocol-version mismatchUse the library that ships with your bundle
Build warning about tollan_config.hBundle header not next to the sketchDrop the console's tollan_config.h into the sketch folder
Connects, but forwarded target refusedTarget not on the allowlistAdd the host:port to forwardTargets / defaultTarget; keep it in sync with the route
Reboots / heap exhaustion under loadToo much buffered trafficLower maxFrameBytes; keep fewer forwarded connections open

Serial debugging#

Both examples print state transitions to serial at 115200. Watch them while the board boots:

text
wifi... ok, ip=192.168.1.42
tollan agent started
tollan state -> connected

If you never see connected, work down the common issues table — it's almost always TLS version or clock on the first bring-up.