esp32-cf

Cloudflare Tunnel client for ESP32. Connects your microcontroller to the internet through Cloudflare's network without port forwarding or a public IP.

v0.1.0 — Proof of concept. This library has not been thoroughly tested and is not recommended for production use. APIs may change between versions.

Example

See esp32-cf-webserver for a complete working project that serves a status page from an ESP32 through a Cloudflare Tunnel.

What it does

• Establishes an HTTP/2 connection to Cloudflare's edge over TLS
• Registers as a tunnel connector using Cap'n Proto RPC
• Routes incoming HTTP requests to your callback function
• Handles reconnection automatically
• Supports both named tunnels (with token) and TryCloudflare quick tunnels

Requirements

• ESP-IDF >= 5.0
• Any ESP32 variant (ESP32, S2, S3, C3, C6, H2)
• A Cloudflare Tunnel token (from cloudflared tunnel token <NAME>)

Installation

Add to your idf_component.yml:

dependencies:
  esp32-cf:
    git: https://github.com/melvinvoetberg/esp32-cf.git

Usage

#include "esp32_cf.h"

void my_handler(cf_edge_conn_t *conn, int32_t stream_id,
                const char *method, const char *path,
                const char *host, const char *client_ip, void *ud) {
    const char *html = "<h1>Hello from ESP32</h1>";
    cf_tunnel_respond(conn, stream_id, 200, "text/html",
                      (uint8_t *)html, strlen(html));
}

void start(void) {
    cf_tunnel_config_t cfg = CF_TUNNEL_CONFIG_DEFAULT();
    cfg.tunnel_token = "your-token";
    cfg.hostname     = "esp.example.com";
    cfg.on_request   = my_handler;

    cf_tunnel_init(&cfg);
    cf_tunnel_start();
}

How it works

The library implements the same protocol as cloudflared:

1. TCP + TLS 1.3 connection to region1.v2.argotunnel.com:7844
2. HTTP/2 with ALPN negotiation (h2)
3. Cap'n Proto RPC for RegisterConnection on the control stream
4. Incoming HTTP requests arrive as HTTP/2 streams with Cloudflare headers (cf-connecting-ip, cf-ray, etc.)

All protocol handling (HTTP/2 framing, HPACK + Huffman decoding, Cap'n Proto serialization, TLS session resumption) is implemented from scratch — no external dependencies beyond mbedTLS (included in ESP-IDF).

License

MIT