# 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.
- HTTPS support for devices with self-signed or otherwise invalid certificates.
- 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

You can use the latest pre-built image from the registry:

```sh
docker pull gitea.lostak.dev/lostakj/shelly-exporter:latest
```

Or build it locally:

```sh
docker build --rm -t shelly-exporter:latest .
```

Run the container:

```sh
docker run --rm -p 9090:9090 \
  -v "$PWD/config.yaml:/opt/shelly-exporter/config.yaml:ro" \
  gitea.lostak.dev/lostakj/shelly-exporter:latest
```

Example with docker-compose:

```yaml
version: '3.8'

services:
  shelly-exporter:
    image: gitea.lostak.dev/lostakj/shelly-exporter:latest
    ports:
      - "9090:9090"
    volumes:
      - ./config.yaml:/opt/shelly-exporter/config.yaml:ro
    restart: unless-stopped
```

## 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/).