ckoch/HAMeter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
HAMeter/DEPLOYMENT.md
Christopher Koch 4f2556bb42 initial commit
2026-03-06 12:25:27 -05:00

6.8 KiB
Raw Permalink Blame History

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:

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: 
    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): 
    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: 
    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:

# 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
  1. 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

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: 
    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:

    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:

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:

rmmod dvb_usb_rtl28xxu

"rtl_tcp binary not found"

The Docker image didn't build correctly. Rebuild:

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
Reference in New Issue View Git Blame Copy Permalink