Initila commit

2026-08-18 00:46:59 +02:00
commit 9db7aa2560
28 changed files with 2823 additions and 0 deletions
@@ -0,0 +1,95 @@
+# Shelly Exporter
+
+Prometheus exporter for Shelly Gen1 Wi-Fi devices that expose monitoring data through the HTTP `/status` endpoint. It supports multiple devices, HTTP Basic Authentication, and dynamically exports only the capabilities present in each device response.
+
+## Features
+
+- Relays, inputs, rollers, lights, power meters, thermostats, and environmental or safety sensors.
+- Correct Prometheus energy counters for both Gen1 `meters` and EM/3EM `emeters`.
+- Concurrent collection from all configured devices.
+- Per-device availability, request duration, and error metrics.
+- Strict YAML validation, graceful shutdown, and a health endpoint.
+- Generic `gen1` product type for compatible devices not explicitly listed.
+
+## Quick start
+
+Copy the example configuration and set the device address and credentials:
+
+```sh
+cp config.example.yaml config.yaml
+```
+
+```yaml
+host: 0.0.0.0
+port: 9090
+logLevel: 4
+
+shelly:
+  timeoutSeconds: 10
+  devices:
+    - name: office-plug
+      product: plug_s
+      url: http://192.168.0.30
+      username: admin
+      password: change-me
+```
+
+Build and start the exporter:
+
+```sh
+go test ./...
+go build -o shelly-exporter .
+./shelly-exporter -config config.yaml
+```
+
+The exporter exposes:
+
+- Prometheus metrics at `http://localhost:9090/metrics`
+- Process health at `http://localhost:9090/-/healthy`
+
+## Supported products
+
+| Family | Product identifiers |
+| --- | --- |
+| Generic Gen1 | `gen1` |
+| Plugs | `plug`, `plug_s` |
+| Relays and inputs | `shelly_1`, `shelly_1pm`, `shelly_1l`, `shelly_2`, `shelly_2_5`, `shelly_4pro`, `shelly_uni`, `shelly_i3`, `shelly_button1` |
+| Energy meters | `shelly_em`, `shelly_3em` |
+| Lights and dimmers | `shelly_bulb`, `shelly_bulb_rgbw`, `shelly_duo`, `shelly_vintage`, `shelly_rgbw2`, `shelly_dimmer` |
+| Sensors and heating | `shelly_ht`, `shelly_flood`, `shelly_smoke`, `shelly_door_window`, `shelly_motion`, `shelly_sense`, `shelly_gas`, `shelly_trv` |
+
+Product identifiers are case-insensitive and punctuation is normalized. For example, `Shelly 2.5` resolves to `shelly_2_5`, and `plug-s` resolves to `plug_s`.
+
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Configuration reference](docs/configuration.md)
+- [Metrics reference](docs/metrics.md)
+- [Operations and troubleshooting](docs/operations.md)
+- [Architecture and adding products](docs/architecture.md)
+
+## Prometheus configuration
+
+```yaml
+scrape_configs:
+  - job_name: shelly
+    static_configs:
+      - targets: [shelly-exporter:9090]
+```
+
+Every device is contacted once during each Prometheus scrape. Choose a scrape interval appropriate for the device and network. Battery-powered Gen1 sensors normally sleep and may be reachable only briefly; push events or MQTT are generally better for continuous monitoring of those devices.
+
+## Docker
+
+```sh
+docker build --rm -t shelly-exporter:latest .
+docker run --rm -p 9090:9090 \
+  -v "$PWD/config.yaml:/opt/shelly-exporter/config.yaml:ro" \
+  shelly-exporter:latest
+```
+
+## Scope
+
+This exporter currently implements the Shelly Gen1 `/status` protocol. Shelly Plus, Pro, Gen2, and Gen3 products use an RPC API and are not currently supported by this client.
+
+Product fields and energy units follow the [official Shelly Gen1 API documentation](https://shelly-api-docs.shelly.cloud/gen1/).