Gateway Lab

Read in another language: English (this document) · Français.

Autonomous network inventory and discovery appliance powered by ESP32-S3.

Gateway Lab is an autonomous network gateway that discovers, identifies and keeps the history of the devices present on a home local network.

Built around an ESP32-S3, the project favours simplicity of deployment, autonomy, low power consumption and local data retention.

---

Key features

• Multi-protocol discovery (ARP, ICMP, mDNS, SSDP, DNS-SD, NetBIOS...)
• Persistent inventory of detected devices
• Automatic classification (manufacturer, category, type)
• History of connections, disconnections and changes
• Favourites and user notes
• Continuous network monitoring and a per-device stability score
• CSV and JSON export, backup and restore
• Responsive web interface, OTA updates
• Fully local operation, no cloud

Exhaustive feature list: see docs/FEATURES.md.

---

Interface preview

Home

Network information, connection state, system diagnostics and quick access to the main functions.

Devices

Inventory of detected devices with filters, favourites, notes, confidence level and administration tools.

History

Chronological log of new devices, reconnections, disconnections and detected changes.

Topology

Simplified view of the gateway, the detected access points and the attached devices.

System

WiFi configuration, automatic monitoring, status NeoPixel, backup/restore, OTA and system state.

---

Securing the board (optional token)

By default the board accepts firmware updates and Wi-Fi changes from anyone on the local network. To protect them, add this line to include/secrets.h (never committed):

#define GATEWAYLAB_AUTH_TOKEN "a-long-random-string"

With the token defined:

• the web firmware update (/update), Wi-Fi network changes, settings restore, inventory restore and device restart require the X-Auth-Token header (the web interface asks for the token once per tab);
• ArduinoOTA uses the same string as its password (add --auth=a-long-random-string to the upload_flags of the PlatformIO environment for wireless uploads); a separate GATEWAYLAB_OTA_PASSWORD can override it for ArduinoOTA only;
• the settings backup contains Wi-Fi passwords only when asked with ?full=1 and a valid token.

Without the token the previous behaviour is kept, a warning is written to the log at every boot, the settings backup lists SSIDs only (no passwords) and a settings restore ignores Wi-Fi networks. Whatever the configuration, every write request (POST, PUT, PATCH, DELETE) whose Origin header differs from the Host header is refused with 403 cross_origin_forbidden, so a web page visited from the LAN cannot act on the board. Scripts and tools that send no Origin header are not affected.

---

Quick start

1. Clone the repository and build with PlatformIO (pio run --target upload)
2. Connect to the GatewayLab-Setup WiFi network
3. Configure WiFi from the browser
4. Reach Gateway Lab at http://gatewaylab.local

Detailed guide: INSTALLATION.md · Developer guide: docs/DEVELOPMENT.md

---

Target hardware

ESP32-S3 DevKitC-1 N16R8 - 16 MB Flash, 8 MB PSRAM, dual-core 240 MHz.

---

Documentation

File	Description
INSTALLATION.md	Installation and first configuration
docs/DEVELOPMENT.md	Build, flash and development
docs/ARCHITECTURE.md	Internal architecture, project structure, web pipeline
docs/API.md	Full REST API reference
docs/FEATURES.md	Exhaustive feature list
docs/PROTOCOLS.md	Network protocols and identification sources
docs/WIFI_SETUP.md	Detailed WiFi portal operation
docs/WARNINGS.md	Architecture decisions and known limitations
CHANGELOG.md	Version history
ROADMAP.md	Planned evolutions

---

Development constraints

• include/board_config.h - do not modify
• include/secrets.h - never commit
• CSS only in web_src/styles.css
• HTML only in web_src/*.html (never an inline <style> or <script>)
• JavaScript only in web_src/*.js
• Versioning only in platformio.ini via PROJECT_VERSION
• After any change to web_src/ or data/oui.json → just build: pio run regenerates the (git-ignored) headers

Full web pipeline and project structure: docs/ARCHITECTURE.md.

---

License

Open-source personal project published for learning, experimentation and knowledge sharing around the ESP32, networking and embedded systems.