Shelly Network Scanner

A lightweight, self-contained tool to discover all Shelly smart-home devices on your local network — no cloud account, no installer, no framework. Just java -jar.

Features

• Scans any /24 subnet (e.g. 192.168.1.x) in parallel (50 threads)
• Detects all Shelly generations: Gen1, Gen2/Plus, Gen3, Gen4, and Pro devices
• Supports HTTP Basic Auth (configurable username & password)
• Results table shows: IP, MAC, Firmware, Model name, Device name, API generation
• Direct link to each device's web UI
• Sortable columns
• Last scan settings are saved in a browser cookie
• Runs as a local HTTP server on port 8080 — browser-based UI, no installation needed

Requirements

• Java 21
• Maven (for building)

Build & Run

# Build fat JAR (bundles all dependencies)
mvn package

# Run from the project root
java -jar target/shelly-scanner-1.2-SNAPSHOT.jar

Then open http://localhost:8080 in your browser.

Note: The JAR must be launched from the project root (or any directory containing a static/ folder), because the file handler resolves resources relative to the working directory.

Using the bundled launch scripts

After building, the scripts are copied to target/:

cd target && ./run.sh      # Linux / macOS
cd target && run.cmd       # Windows

Usage

1. Enter your subnet (e.g. 192.168.1) — only the first three octets
2. Enter the admin credentials if your devices are password-protected
3. Adjust the per-device timeout if needed (default: 1500 ms)
4. Click Scan — results appear in the table when the scan completes

Important: The scanner uses a single username/password for the entire subnet. All password-protected Shelly devices must share the same credentials, otherwise they will not be detected.

How It Works

The scanner submits 254 tasks (.1–.254) concurrently to a 50-thread pool. For each IP it:

1. Tries the RPC API first (POST /rpc/Shelly.GetDeviceInfo) — used by Gen2/Gen3/Gen4/Pro devices
2. Falls back to the Gen1 API (GET /shelly + GET /settings) if RPC fails

Results are returned as a JSON array and rendered in the browser table.

Supported Devices

Generation	Examples
Gen1	Shelly 1, 1L, 1PM, 2, 2.5, 4Pro, Dimmer, Plug S, EM, 3EM, RGBW2, H&T, Flood, Smoke, Motion, Door/Window, Button, TRV, …
Gen2 / Plus	Shelly Plus 1, 1PM, 2PM, i4, Plug S (EU/US/UK), PM Mini, H&T, Smoke, UNI, Dimmer, …
Gen3	Shelly 1/1PM/2PM Gen3, PM Mini Gen3, Plug S/M Gen3, i4 Gen3, H&T Gen3, EM Gen3, BLU Gateway Gen3, …
Gen4	Shelly 1/1PM/2PM Gen4, 1 Mini Gen4, Power Strip Gen4, Plug (US) Gen4, EM Mini Gen4, …
Pro	Shelly Pro 1/2/3/4PM, Pro EM-50, Pro 3EM, Pro 3EM-3CT63/400, Pro Circuit Breaker, …

Architecture

ShellyNetworkScannerServlet.main()
├── GET  /        → StaticFileHandler  (serves ./static/)
└── POST /scan    → ScanHandler
                      ├── scanDeviceRPC()   (Gen2+)
                      └── scanDeviceGen1()  (fallback)

• HTTP server: com.sun.net.httpserver (no servlet container)
• Only runtime dependency: org.json
• Frontend: plain HTML/CSS/JS, no build step, no framework

Out of Scope

• HTTPS / TLS
• Device control (switching, configuration changes)
• Persistence / saving scan results
• Scanner UI authentication
• Shelly BLU (Bluetooth-only, not reachable via IP)
• Multi-subnet scanning

License

MIT © 2026 McFcologne — see LICENSE for details.

Third-party components

Component	Version	License
org.json	20240303	JSON License — permissive, with the clause "The Software shall be used for Good, not Evil."
Java SE / OpenJDK (com.sun.net.httpserver)	21	GPL v2 with Classpath Exception — runtime only, not bundled