HAMeter/DEPLOYMENT.md

# HAMeter Deployment Guide — Unraid

## Prerequisites

- Unraid server (Dell R730) with Community Applications plugin installed
- Nooelec RTL-SDR v5 dongle
- Home Assistant running as Docker container on Unraid (spaceinvaderone/ha_inabox)

---

## Step 1: Install Mosquitto MQTT Broker

1. In Unraid web UI, go to **Apps** tab
2. Search for **"mosquitto"**
3. Install **eclipse-mosquitto** (the official image)
4. Default settings are fine for initial setup:
   - Port: **1883** (MQTT) and **9001** (WebSocket, optional)
   - Config path: `/mnt/user/appdata/mosquitto`
5. Start the container
6. Your Unraid server IP (`192.168.1.74`) is the MQTT broker address

### Verify Mosquitto is Running

From Unraid terminal or SSH:
```bash
docker logs mosquitto
```
You should see a line like: `mosquitto version X.X.X running`

---

## Step 2: Connect MQTT to Home Assistant

1. In Home Assistant, go to **Settings → Devices & Services**
2. Click **+ Add Integration** (bottom right), search for **MQTT**
3. Enter:
   - **Broker**: `192.168.1.74`
   - **Port**: `1883`
   - **Username/Password**: Leave blank (unless you configured auth on Mosquitto)
4. Click **Submit**
5. Verify connection succeeds

---

## Step 3: Connect SDR Dongle to R730

1. Plug the Nooelec RTL-SDR into a **USB 2.0 port** on the R730 (avoid USB 3.0 — causes I2C errors)
2. Attach the telescopic whip antenna collapsed to ~8 cm (quarter-wave for 900 MHz)
3. Verify Unraid sees the device — from Unraid terminal:
   ```bash
   lsusb | grep -i rtl
   ```
   You should see: `Realtek Semiconductor Corp. RTL2838 DVB-T` or similar

### Blacklist the Kernel DVB Driver

The Linux DVB driver will claim the dongle and prevent rtl_tcp from using it:

1. SSH into Unraid
2. Create the blacklist file (persists across reboots):
   ```bash
   mkdir -p /boot/config/modprobe.d
   echo "blacklist dvb_usb_rtl28xxu" >> /boot/config/modprobe.d/rtlsdr.conf
   ```
3. If the module is currently loaded, unload it:
   ```bash
   rmmod dvb_usb_rtl28xxu 2>/dev/null
   ```

---

## Step 4: Build the HAMeter Docker Image

On the Unraid server (or any machine with Docker), clone the project and build:

```bash
# Copy project files to Unraid (e.g., via SMB share or scp)
# Then on Unraid terminal:
cd /mnt/user/appdata/hameter
docker build -t hameter:latest .
```

---

## Step 5: Deploy HAMeter Container

### Option A: Via Unraid Docker UI

1. Go to **Docker → Add Container**
2. Configure:

| Setting | Value |
|---------|-------|
| **Name** | `hameter` |
| **Repository** | `hameter:latest` |
| **Network** | Host |
| **Extra Parameters** | `--device=/dev/bus/usb` |
| **Restart Policy** | Unless Stopped |

3. Add path mapping:

| Container Path | Host Path | Mode |
|----------------|-----------|------|
| `/config/hameter.yaml` | `/mnt/user/appdata/hameter/config/hameter.yaml` | Read Only |

### Option B: Via Command Line

```bash
docker run -d \
  --name hameter \
  --restart unless-stopped \
  --network host \
  --device=/dev/bus/usb \
  -v /mnt/user/appdata/hameter/config/hameter.yaml:/config/hameter.yaml:ro \
  -e TZ=America/New_York \
  hameter:latest
```

---

## Step 6: Deploy Configuration

1. Copy the config file to the appdata path:
   ```bash
   mkdir -p /mnt/user/appdata/hameter/config
   cp config/hameter.yaml /mnt/user/appdata/hameter/config/hameter.yaml
   ```
2. The config is pre-set with your Unraid IP (`192.168.1.74`) and electric meter ID (`23040293`)
3. Start the container

---

## Step 7: Verify It's Working

1. Check HAMeter logs:
   ```bash
   docker logs -f hameter
   ```
   You should see:
   - `Connected to MQTT broker`
   - `Published HA discovery for meter 23040293`
   - `Published: meter=23040293 raw=XXXXX calibrated=XX.XXXX kWh`

2. In Home Assistant, go to **Settings → Devices & Services → MQTT**
   - A new device **"Electric Meter"** should appear with 3 entities:
     - **Electric Meter Reading** — calibrated kWh value
     - **Electric Meter Raw Reading** — raw register value (diagnostic)
     - **Electric Meter Last Seen** — timestamp of last transmission

3. Check **Developer Tools → States** and filter for `sensor.electric_meter`

---

## Step 8: Add to Energy Dashboard

1. Go to **HA → Settings → Dashboards → Energy**
2. Under **Electricity Grid**, click **Add Consumption**
3. Select `sensor.electric_meter_reading`
4. Optionally set a **cost per kWh** for cost tracking

---

## Calibration

The raw SCM consumption value (e.g., 516,030) does not directly equal kWh.
HAMeter has a built-in `multiplier` per meter in the config.

### How to Calibrate

1. Read your physical meter display (e.g., 59,669 kWh)
2. Check the raw reading in HA: **Developer Tools → States → `sensor.electric_meter_raw_reading`**
3. Calculate: `multiplier = meter_display_kWh / raw_value`
   - Example: `59,669 / 516,030 ≈ 0.1156`
4. Update `multiplier: 0.1156` in `config/hameter.yaml`
5. Restart the container: `docker restart hameter`

The calibrated reading sensor will now show actual kWh.
The raw reading sensor (diagnostic) always shows the unconverted value
for recalibration later.

---

## Discovering Gas and Water Meter IDs

HAMeter has a built-in discovery mode:

```bash
docker run --rm \
  --device=/dev/bus/usb \
  -v /mnt/user/appdata/hameter/config/hameter.yaml:/config/hameter.yaml:ro \
  hameter:latest --discover --discover-duration 120
```

This will:
1. Listen for all nearby meter transmissions for 120 seconds
2. Log each new meter ID, protocol, and consumption value as they appear
3. Print a summary table of all meters found

Match the IDs to your physical meters, then add them to the config file.

---

## Troubleshooting

### "usb_open error -3"
The DVB kernel driver is claiming the device:
```bash
rmmod dvb_usb_rtl28xxu
```

### "rtl_tcp binary not found"
The Docker image didn't build correctly. Rebuild:
```bash
docker build --no-cache -t hameter:latest .
```

### No meter readings appearing
- Check antenna is attached and collapsed to ~8 cm
- Verify SDR is on USB 2.0 port (not 3.0)
- Check container has USB device access: `docker exec hameter ls /dev/bus/usb/`
- Try discovery mode to confirm the SDR is receiving signals
- Check logs: `docker logs hameter`

### MQTT connection refused
- Verify Mosquitto container is running: `docker ps | grep mosquitto`
- Check IP/port in `hameter.yaml` matches Mosquitto
- Test connectivity: `docker exec hameter python -c "import socket; s=socket.socket(); s.connect(('192.168.1.74',1883)); print('OK')"`

### Sensors not appearing in HA
- Verify MQTT integration is configured in HA
- Check MQTT messages are arriving: In HA, go to **Developer Tools → MQTT → Listen** and subscribe to `hameter/#`
- Restart HA after first discovery publish

### Container keeps restarting
- Check logs for the specific error: `docker logs --tail 50 hameter`
- Common cause: USB device not passed through or kernel driver conflict