# HomeHub 4000 Prometheus Exporter

Prometheus exporter for the [Virgin Plus Vincent](https://www.virginplus.ca/en/support/internet/modem-info-vincent.html) / [Bell HomeHub 4000](https://support.bell.ca/internet/products/home-hub-4000-modem) router. Uses Playwright to scrape the admin UI and expose metrics for Prometheus. Device events are stored in SQLite so other tools can query them independently of Prometheus.

<details>
<summary><strong>Grafana dashboard (included)</strong></summary>

![Grafana Dashboard](docs/grafana-dashboard.png)
</details>

<details>
<summary><strong>Architecture diagram</strong></summary>

```mermaid
flowchart LR
    subgraph exporter.py
        direction TB
        prom[Prometheus Server]
        scraper[router_scraper.py]
        poller[router_log_fetcher.py]
    end

    subgraph Router["HomeHub 4000"]
        mon["/monitoring"]
        stats["/statistics"]
        logs["/logs"]
    end

    scraper --> mon
    scraper --> stats
    poller --> logs
    poller --> db[(SQLite)]
```
</details>

## Quick Start

```bash
# Install
uv sync
uv run playwright install chromium

# Run
ROUTER_PASSWORD="your_password" uv run python src/exporter.py

# Check
curl http://localhost:9100/metrics | grep homehub_
```

## Docker

```bash
cd deploy
echo "ROUTER_PASSWORD=your_password" > .env
docker-compose up -d
```

Services:
- Exporter: http://localhost:9100/metrics
- Prometheus: http://localhost:9090
- Grafana: http://localhost:3000 (pre-configured dashboard included)

Default Grafana credentials are `admin/admin`. Override with `GRAFANA_ADMIN_USER` and `GRAFANA_ADMIN_PASSWORD` in `.env`.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `ROUTER_PASSWORD` | (required) | Router admin password |
| `ROUTER_IP` | 192.168.2.1 | Router IP address |
| `EXPORTER_PORT` | 9100 | Metrics port |
| `SCRAPE_INTERVAL` | 60 | Seconds between scrapes |
| `LOG_POLL_INTERVAL` | 75 | Seconds between log polls |
| `HEADLESS_BROWSER` | true | Run browser headless |

## Metrics

All metrics prefixed with `homehub_`. Covers system health (CPU, memory, load), network interfaces (status, throughput, errors), connected devices, router uptime, and log statistics. See the Grafana dashboard screenshot above or query `curl localhost:9100/metrics | grep homehub_` for the full list.

## Development

```bash
uv sync        # includes dev dependencies
uv run pytest
uv run ruff check src/
```

## Troubleshooting

- Set `HEADLESS_BROWSER=false` to watch the browser and debug scraping issues
- Delete `virgin_monitor.db` to reset device history

Tested on Virgin Plus Vincent (Bell HomeHub 4000), firmware 2.13, UI 7.3.29.