Skip to content

Work in progress

This feature lives on branch feature/remote-meter-through-mqtt (not yet merged to develop) and is tested via an integration branch on real hardware. Config field names may still change.

MQTT Meter Integration

Why

Meters for external/third-party circuits (e.g. vZEV community participants) are read via MQTT instead of Modbus, since we don't have physical/wired access to them. First concrete use case: Shelly Pro EM-50 (Gen2 RPC) energy meter.

Concept

  • io.openems.edge.bridge.mqtt (upstream, untouched) provides the raw broker connection (Bridge.Mqtt component).
  • io.openems.edge.meter.mqtt.api (custom) defines MqttMeterAdapter: one implementation per device family, translating that family's topic/payload layout into a neutral MeterSample.
  • io.openems.edge.meter.mqtt.shelly (custom) is the first adapter + Meter component, for Shelly Gen2 em1:x channels.

To support a new device family later (e.g. WhatWatt Go), copy MeterMqttShellyImpl as a template and implement a new MqttMeterAdapter — no changes needed to the Bridge or the API bundle. See io.openems.edge.meter.mqtt.api/readme.adoc and io.openems.edge.meter.mqtt.shelly/readme.adoc in the openems repo for full details (config tables, live-broker test procedure).

Broker Setup (Mosquitto)

Broker runs as the mosquitto container in openems-docker (eclipse-mosquitto:2, TLS on 8883, reusing the Let's-Encrypt cert for the domain). Auth is username/password + ACL, one MQTT user per physical device, restricted to that device's own topic namespace:

# mosquitto acl file — one block per device
user shelly01
topic readwrite shelly01/#

Create the user with mosquitto_passwd, add the ACL block, restart the mosquitto container.

Shelly Device Config (Web-UI)

On the Shelly Gen2 device itself (Settings → MQTT):

Field Value
Enable MQTT on
Server broker host:port (8883, TLS)
Username / Password the device's own broker user (e.g. shelly01)
Topic prefix defaults to the username — keep it that way, OpenEMS assumes topicPrefix == username
Enable RPC over MQTT on

Verify independently of OpenEMS with mosquitto_sub -h <host> -p 8883 --tls-version tlsv1.2 -u shelly01 -P <pw> -t 'shelly01/#' -v — expect shelly01/online true and periodic shelly01/events/rpc {...NotifyStatus...}.

OpenEMS Component Config

  1. Bridge.Mqtt — one instance per device (matches the broker credentials above): id, host, port=8883, secureConnect=true, username/password = the device's broker user.

  2. Meter.Mqtt.Shelly — one instance per measured channel:

    Field Value
    mqtt_id ID of the Bridge.Mqtt instance from step 1
    topicPrefix device's topic prefix, e.g. shelly01
    channel Shelly em1:x channel, 0 or 1
    phase physical phase this channel represents
    type MeterType (GRID, PRODUCTION, ...)
    invert fixes reversed CT-clamp wiring only — not device sign conventions
    addToSum default false — these Meters represent external/community circuits, not our own grid connection

Adding the Next Sensor

  1. Create the broker user + ACL block for the new device.
  2. Configure MQTT on the device (Web-UI).
  3. mosquitto_sub check that it's publishing.
  4. Add Bridge.Mqtt instance.
  5. Add Meter.Mqtt.Shelly instance (new channel/phase, same or new Bridge.Mqtt per device).
  6. Check MqttCommunicationFailed stays false and values update in the OpenEMS UI.

Troubleshooting

  • MqttCommunicationFailed=true / values UNDEFINED → device offline, or topicPrefix doesn't match the broker username.
  • No data at all → check ACL block matches the username exactly, check Bridge.Mqtt's CONNECTED channel.