Network & Display

ESP32 Blackbox

A $5 network probing device compatible with Prometheus blackbox_exporter.

Configure probes via JSON or Web UI; expose metrics in standard Prometheus format. Drop-in replacement for the software blackbox_exporter on a tiny ESP32 board.

GitHub ↗
ESP32-C3/C6 Prometheus MIT

Probe Modules

Module Description Example
http_2xx HTTP health check probe curl http://blackbox/probe?module=http_2xx&target=https://example.com
tcp TCP port connectivity probe curl http://blackbox/probe?module=tcp&target=example.com:80
dns DNS resolution probe curl http://blackbox/probe?module=dns&target=example.com
icmp_ping ICMP ping probe curl http://blackbox/probe?module=icmp_ping&target=1.1.1.1
ws WebSocket connectivity probe curl http://blackbox/probe?module=ws&target=ws://echo.example.com
wss Secure WebSocket connectivity probe curl http://blackbox/probe?module=wss&target=wss://echo.example.com

Supported Hardware

  • ESP32-C3 SuperMini — 802.11 b/g/n, RISC-V core
  • Seeed XIAO ESP32C6 — WiFi 6, upcoming standard

Quick Start

Build and flash

bash 
# Using the build script (recommended)
python build.py esp32c6 build
python build.py esp32c6 flash COM3

# Or using ESP-IDF directly
idf.py set-target esp32c6
idf.py build
idf.py -p COM3 flash monitor

First boot

The device creates an AP named ESP32_Blackbox (password 12345678). Connect and configure at http://192.168.4.1.

Prometheus configuration

Add this to your prometheus.yml:

yaml 
scrape_configs:
  - job_name: 'esp32_blackbox'
    metrics_path: /metrics
    static_configs:
      - targets: ['192.168.1.100']

Tech Stack

  • Framework: ESP-IDF
  • SoC: ESP32-C3 (RISC-V) or ESP32-C6 (WiFi 6)
  • Protocols: HTTP, TCP, DNS, ICMP, WebSocket, Prometheus metrics
  • Configuration: JSON via Web UI or API
  • License: MIT

Documentation

Build scripts, pin mappings, and full API reference are in the GitHub repository.