Itron Go MQTT Bridge

A Go implementation for the Gen5 Riva utility power meter by Itron that communicates with the meter API and bridges that information to MQTT brokers for Home Assistant integration or other integrations based on customizable configuration and MQTT topic prefix.

Features

• IEEE 2030.5 Compliance: Implements the IEEE 2030.5-2023 specification for smart energy communication
• Custom TLS/SSL Support: Uses ECDHE-ECDSA-AES128-CCM8 cipher suite required by Itron meters
• Automatic Discovery: mDNS/Zeroconf discovery of meters on the network
• Home Assistant Integration: Automatic device and sensor discovery via MQTT
• Multiple Endpoints: Configurable endpoint monitoring (power, energy summation, etc.)
• Robust Error Handling: Exponential backoff retry logic for reliable operation
• Continuous Monitoring: Real-time polling and data publishing

Key Components

1. TLS Package: Implements custom SSL context with ECDHE-ECDSA-AES128-CCM8 cipher
2. Discovery Package: Automatic meter discovery using mDNS
3. Parser Package: IEEE 2030.5 XML response parsing
4. MQTT Package: MQTT data publishing
5. Endpoint Package: Meter endpoint management and polling

Supported Meter Endpoints

• Instantaneous Demand: Real-time power consumption (/upt/1/mr/1/r)
• Current Summation Received: Energy received from grid (/upt/1/mr/2/rs/1/r/1)
• Current Summation Delivered: Energy delivered to grid (/upt/1/mr/3/rs/1/r/1)

Home Assistant Integration

The application automatically creates Home Assistant entities via MQTT discovery by default:

• Device information (LFDI, software version, manufacturer)
• Power sensors with proper device classes
• Energy sensors with state classes for long-term statistics
• Proper units of measurement (W, Wh)

Configuration

Environment Variables

Variable	Description	Default
METER_IP	IP address of the Itron meter (disables mDNS discovery when set)	Auto-discovery
METER_PORT	Port of the Itron meter	8081
CERT_PATH	Path to client certificate	/opt/certs/cert.pem
KEY_PATH	Path to client key (or same file as cert)	/opt/certs/key.pem
LOGLEVEL	Log level (DEBUG, INFO, NOTICE, WARN, ERROR, CRIT, EMER)	INFO
MQTT_SERVER	MQTT broker hostname	localhost
MQTT_PORT	MQTT broker port	1883
MQTT_USER	MQTT username	(optional)
MQTT_PASSWORD	MQTT password	(optional)
MQTT_TOPIC_PREFIX	MQTT topic prefix	homeassistant/

Certificate Setup

The application requires a client certificate (and optionally a separate key) to authenticate with the Itron meter. By default the application looks for the certificate and key at /opt/certs/cert.pem and /opt/certs/key.pem respectively. For container usage you can mount your files to /opt/certs:

# Example: mount both cert and key into the container
docker run -v /path/to/certs:/opt/certs:ro ...

For ease-of-use both certificate and key can be combined in a single PEM file; in that case point both CERT_PATH and KEY_PATH to the same file (or only set CERT_PATH and the program will attempt to use the same file for the key).

See the Setup section of Zak Nye's excellent xcel_itron2mqtt project for how to generate a certificate and key that can be used with this project.

Logging Configuration

The application provides comprehensive logging with configurable levels:

Log Levels (in order of verbosity):

• DEBUG - Detailed debugging information, HTTP requests/responses, connection details
• INFO - General informational messages (default)
• NOTICE - Important notices (mapped to INFO level)
• WARN - Warning messages for non-critical issues
• ERROR - Error messages for failures
• CRIT - Critical errors that may cause termination
• EMER - Emergency/panic conditions

Endpoint Configuration

The application uses YAML configuration files to define which meter endpoints to monitor:

• configs/endpoints_default.yaml - Default configuration

The application automatically selects the appropriate configuration based on the meter's software version.

Meter Discovery

The application supports multiple methods for finding the Itron meter on your network:

1. Manual Configuration (Highest Priority)

   • Set METER_IP environment variable to specify the meter's IP address
   • When METER_IP is set, mDNS discovery is completely disabled
   • Optionally set METER_PORT (defaults to 8081)

2. Automatic mDNS Discovery (Default)

   • Only used when METER_IP is not set
   • Searches for _smartenergy._tcp.local services on the network
   • Automatically discovers IP address and port

3. Simple Discovery (Fallback)

   • Tries common IP addresses (192.168.1.100, 192.168.0.100, etc.)
   • Used if mDNS discovery fails

4. Default Fallback

   • Uses localhost:8081 if all discovery methods fail

Usage

Docker images

Pre-built multi-arch images (amd64 and arm64) are published to Docker Hub and GitHub Container Registry by CI.

Docker Hub examples:

# Pull a semver release (e.g. v1.2.3)
docker pull user00265/itron-go-mqtt:v1.2.3

# Pull the latest release (alias of the most recent semver tag)
docker pull user00265/itron-go-mqtt:latest

# Pull the develop image (built from master)
docker pull user00265/itron-go-mqtt:develop

GitHub Container Registry examples (using user00265 as the owner):

# Pull a semver release
docker pull ghcr.io/user00265/itron-go-mqtt:v1.2.3

# Pull the latest release
docker pull ghcr.io/user00265/itron-go-mqtt:latest

# Pull the develop image
docker pull ghcr.io/user00265/itron-go-mqtt:develop

Docker Usage

# Run with environment variables
docker run -d \
  -e METER_IP=192.168.1.100 \
  -e MQTT_SERVER=mqtt.local \
  -v /path/to/cert.pem:/app/itron.pem \
  itron-go-mqtt

Manual IP Configuration (mDNS Disabled)

# Run with specific meter IP (disables mDNS discovery)
export METER_IP=192.168.1.100
export METER_PORT=8081  # Optional, defaults to 8081
export MQTT_SERVER=mqtt.local
./itron-go-mqtt

Automatic mDNS Discovery

# Let the application discover the meter automatically via mDNS
# (Do NOT set METER_IP to enable discovery)
export MQTT_SERVER=mqtt.local
./itron-go-mqtt

Hostname Support

# METER_IP also supports hostnames
export METER_IP=itron-meter.local
export MQTT_SERVER=mqtt.local
./itron-go-mqtt

Troubleshooting

Common Issues

1. SSL Connection Failures

   • Verify certificate file path and permissions
   • Ensure meter is accessible on the network
   • Check that the meter supports the required cipher suite

2. mDNS Discovery Issues

   • Check network connectivity
   • Verify meter broadcasts on _smartenergy._tcp.local
   • Try manual IP configuration

3. MQTT Connection Issues

   • Verify MQTT broker accessibility
   • Check username/password if authentication is required
   • Ensure proper network firewall configuration

Debug Logging

The application provides structured logging with multiple levels. Debug level includes:

• SSL/TLS connection establishment details
• HTTP request/response content
• mDNS discovery attempts
• MQTT topic publishing details
• Endpoint querying progress
• Configuration loading information

Acknowledgments

• This project was inspired by Zak Nye's xcel_itron2mqtt project and uses the default endpoint configuration/mapping from that project.
• IEEE 2030.5-2023 specification
• Itron Riva Gen5 meter documentation