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:
| Field | Default | When to change |
|---|---|---|
syncClock | true | Set false only if the board already keeps real time (external RTC, or you call configTime() yourself) |
ntpServer1 / ntpServer2 | pool.ntp.org / time.nist.gov | Point at a LAN NTP server on an isolated network with no public NTP access |
clockSyncTimeoutMs | 8000 | Raise 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#
| Symptom | Likely cause | Fix |
|---|---|---|
state() never leaves Disconnected, mbedTLS -30592 | Wrong relay host or port | Use TOLLAN_RELAY_HOST / TOLLAN_RELAY_PORT from the bundle |
mbedTLS -9984 on every attempt | Clock not synced (board thinks it's 1970) | Ensure syncClock is on and NTP is reachable |
| Stuck before TLS, no NTP reply | No route to pool.ntp.org | Set ntpServer1 to a LAN NTP server |
state() goes straight to Terminal | Protocol-version mismatch | Use the library that ships with your bundle |
Build warning about tollan_config.h | Bundle header not next to the sketch | Drop the console's tollan_config.h into the sketch folder |
| Connects, but forwarded target refused | Target not on the allowlist | Add the host:port to forwardTargets / defaultTarget; keep it in sync with the route |
| Reboots / heap exhaustion under load | Too much buffered traffic | Lower maxFrameBytes; keep fewer forwarded connections open |
Serial debugging#
Both examples print state transitions to serial at 115200. Watch them while the board boots:
wifi... ok, ip=192.168.1.42
tollan agent started
tollan state -> connectedIf you never see connected, work down the common issues table — it's almost always TLS version or clock on the first bring-up.