> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-2/guides/machine-connectivity/robots-sensors-shop-floor-devices/connecting-a-janitza-umg-power-analyzer.md).

# Connecting a Janitza UMG Power Analyzer

This guide shows you how to read power quality and energy measurements from a Janitza UMG power analyzer with the Connectware [Modbus/TCP connector](/2-4-2/connectors/shop-floor-connectors/modbus-tcp.md) and map them into an ISA-95 style MQTT topic hierarchy. The measurements collected here (voltage, current, power, power factor, frequency, and energy counters) are the typical input for energy monitoring dashboards and ISO 50001 energy management reporting. In more detail, the following topics are covered:

* Preparing the Ethernet interface of the UMG device
* Identifying the Modbus addresses of the measured values and energy counters
* Decoding the Float values with the correct `dataType`
* Creating the [service commissioning file](/2-4-2/data-flows/service-commissioning-files.md)
* Mapping the measurements into an ISA-95 style MQTT topic hierarchy
* Verifying data in the [Data Explorer](/2-4-2/monitoring/data-explorer.md)

The register addresses in this guide are verified against the [UMG 96RM-E Modbus address list](https://www.janitza.com/files/download/manuals/current/UMG96RM/E/janitza-mal-umg96rme-en.pdf) (document 1.040.085.8, June 2024). Other Ethernet-capable UMG models, such as the UMG 604-PRO, use different address maps: download the Modbus address list for your model from the [Janitza Modbus address list page](https://www.janitza.com/en/downloads/modbus-address-list) and swap the addresses accordingly. The structure of the service commissioning file stays the same. If you operate Siemens meters as well, the guide [Connecting a Siemens SENTRON PAC3200 Power Meter](/2-4-2/guides/machine-connectivity/robots-sensors-shop-floor-devices/connecting-a-siemens-sentron-pac3200-power-meter.md) follows the same pattern for those devices.

This guide focuses on the Janitza UMG specifics. For a general introduction to the Modbus/TCP connector, including function codes and write operations, see [Connecting & Integrating a Modbus/TCP Server](/2-4-2/guides/machine-connectivity/gateways-generic-protocols/connecting-and-integrating-a-modbus-tcp-server.md).

A complete example file is available at the end of this guide.

## Prerequisites

To follow this guide, you will need the following:

* A running instance of Cybus Connectware.
* A Janitza UMG power analyzer with an Ethernet interface (for example, a UMG 96RM-E) that is reachable over the network from Connectware.
* The Modbus address list for your UMG model, available on the [Janitza Modbus address list page](https://www.janitza.com/en/downloads/modbus-address-list).
* Access to the [Admin UI](/2-4-2/access/admin-ui.md) with sufficient [user permissions](/2-4-2/access/user-management.md).
* Basic knowledge of MQTT and the Connectware [services](/2-4-2/data-flows/services.md) concept (for example, [service commissioning files](/2-4-2/data-flows/service-commissioning-files.md), [connections](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md), and [endpoints](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md)).

## Preparing the Device

Ethernet-capable UMG devices accept Modbus/TCP connections on the standard port 502 without further protocol configuration. You only need a working network setup:

1. Assign the device an IP address that is reachable from Connectware. On the UMG 96RM-E, you set the address mode (fixed IP, BOOTP, or DHCP) and the address directly on the device; see the user manual of your model for the exact menu steps.
2. Verify that port 502 is not blocked by a firewall between the device and Connectware.
3. Check the current and voltage transformer ratios configured on the device. The Float values that this guide reads already include these ratios, so wrong transformer settings produce wrong measurements on every downstream dashboard.

Connectware addresses the analyzer by its IP address; the default unit ID 1 of the Connectware Modbus connection works for a UMG that is connected directly over its Ethernet port. If you reach a meter through a Modbus gateway instead (some UMG devices can act as a gateway for serial Modbus devices), set the `unitId` connection property to the address of the meter behind the gateway.

## Identifying the Modbus Addresses

Janitza documents all measured values of a UMG device in its Modbus address list. The UMG 96RM-E provides the most common measurements as a compact block of 32-bit Float values starting at address 19000, listed in the chapter "Frequently required readings". The device answers read requests with function code 3 (`0x03`) or 4 (`0x04`). The following addresses are used in this guide:

| Address | Number of registers | Name                          | Format | Unit |
| ------: | ------------------: | ----------------------------- | ------ | ---- |
|   19000 |                   2 | Voltage L1-N                  | Float  | V    |
|   19012 |                   2 | Current L1                    | Float  | A    |
|   19026 |                   2 | Real power, sum L1..L3        | Float  | W    |
|   19034 |                   2 | Apparent power, sum L1..L3    | Float  | VA   |
|   19042 |                   2 | Reactive power, sum L1..L3    | Float  | var  |
|   19044 |                   2 | Power factor CosPhi L1        | Float  | -    |
|   19050 |                   2 | Measured frequency            | Float  | Hz   |
|   19068 |                   2 | Real energy L1..L3, consumed  | Float  | Wh   |
|   19076 |                   2 | Real energy L1..L3, delivered | Float  | Wh   |

The remaining phases follow the same pattern in steps of two registers: voltages L2-N and L3-N are at addresses 19002 and 19004, currents L2 and L3 at 19014 and 19016, the per-phase real power values at 19020 to 19024, and CosPhi L2 and L3 at 19046 and 19048. The block also contains apparent energy (19084), reactive energy (19092), and total harmonic distortion values for voltage and current (19110 to 19120). For everything beyond this block, such as mean, minimum, and maximum values, consult the address list of your model.

{% hint style="warning" %}
Start every read at the exact documented address with `length: 2`. A read that is shifted by one register combines the halves of two neighboring Float values and produces implausible numbers instead of an error.
{% endhint %}

### Decoding Float Values

Modbus registers are 16 bits long, so each Float value spans two registers. The Janitza address list states that the documented addresses supply data in big-endian format, which matches the Modbus standard and maps directly to the Connectware [Modbus data types](/2-4-2/connectors/shop-floor-connectors/modbus-tcp.md#supported-data-types): set `length: 2` and `dataType: floatBE`.

With the `dataType` property set, Connectware decodes the registers and publishes a plain JSON number. Without it, you receive a raw buffer that you would have to parse yourself. For all available data types, see [Modbus/TCP Endpoint Properties](/2-4-2/connectors/shop-floor-connectors/modbus-tcp/modbusendpoint.md).

Janitza additionally mirrors every value in little-endian format at the documented address plus 32768. You do not need these mirrored addresses with Connectware, because `floatBE` decodes the standard addresses directly.

## Writing the Service Commissioning File

The service commissioning file contains all connection and mapping details. Do not worry about copying the snippets together into one file, the complete example file is available at the end of this guide.

### Description and Metadata

These sections contain general information about the service commissioning file. Only the metadata name is required.

{% code lineNumbers="true" %}

```yaml
description: >
  Service commissioning file that reads power quality and energy measurements
  from a Janitza UMG 96RM-E power analyzer over Modbus/TCP and maps them into
  an ISA-95 style MQTT topic hierarchy (Example)

metadata:
  name: Janitza UMG 96RM-E Example
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0
```

{% endcode %}

### Parameters and Definitions

We define the network address of the analyzer as parameters, so you can set them when you install the service. The default Modbus/TCP port is 502.

The MQTT topics in this guide follow an ISA-95 style equipment hierarchy with an `energy` branch (`<enterprise>/<site>/<area>/<line>/energy`). We define the prefix once in the `definitions` section and reuse it in every mapping with `!sub`.

{% code lineNumbers="true" %}

```yaml
parameters:
  umgHost:
    description: Hostname or IP address of the Janitza UMG power analyzer
    type: string
    default: 192.168.1.100

  umgPort:
    description: Modbus/TCP port of the Janitza UMG power analyzer
    type: integer
    default: 502

definitions:
  MQTT_TOPIC_PREFIX: enterprise/hamburg/assembly/line-1/energy
```

{% endcode %}

### Cybus::Connection

The connection resource establishes the Modbus/TCP connection to the analyzer. The `connectionStrategy` object controls how Connectware retries failed connection attempts with increasing delays. For all connection properties, including `unitId`, see [Modbus/TCP Connection Properties](/2-4-2/connectors/shop-floor-connectors/modbus-tcp/modbusconnection.md).

{% code lineNumbers="true" %}

```yaml
resources:
  umgConnection:
    type: Cybus::Connection
    properties:
      protocol: Modbus
      targetState: connected
      connection:
        host: !ref umgHost
        port: !ref umgPort
        connectionStrategy:
          initialDelay: 1000
          maxDelay: 30000
          incrementFactor: 2
```

{% endcode %}

### Cybus::Endpoint

Each endpoint polls one measured value. The `address` values come directly from the address list, and every Float value has `length: 2`. The UMG 96RM-E refreshes its Modbus registers every 200 milliseconds, so a poll interval of two seconds captures the instantaneous measurements comfortably.

{% code lineNumbers="true" %}

```yaml
voltageL1:
  type: Cybus::Endpoint
  properties:
    protocol: Modbus
    connection: !ref umgConnection
    subscribe:
      fc: 3
      address: 19000
      length: 2
      dataType: floatBE
      interval: 2000

currentL1:
  type: Cybus::Endpoint
  properties:
    protocol: Modbus
    connection: !ref umgConnection
    subscribe:
      fc: 3
      address: 19012
      length: 2
      dataType: floatBE
      interval: 2000

activePowerTotal:
  type: Cybus::Endpoint
  properties:
    protocol: Modbus
    connection: !ref umgConnection
    subscribe:
      fc: 3
      address: 19026
      length: 2
      dataType: floatBE
      interval: 2000

apparentPowerTotal:
  type: Cybus::Endpoint
  properties:
    protocol: Modbus
    connection: !ref umgConnection
    subscribe:
      fc: 3
      address: 19034
      length: 2
      dataType: floatBE
      interval: 2000

reactivePowerTotal:
  type: Cybus::Endpoint
  properties:
    protocol: Modbus
    connection: !ref umgConnection
    subscribe:
      fc: 3
      address: 19042
      length: 2
      dataType: floatBE
      interval: 2000

cosPhiL1:
  type: Cybus::Endpoint
  properties:
    protocol: Modbus
    connection: !ref umgConnection
    subscribe:
      fc: 3
      address: 19044
      length: 2
      dataType: floatBE
      interval: 2000

frequency:
  type: Cybus::Endpoint
  properties:
    protocol: Modbus
    connection: !ref umgConnection
    subscribe:
      fc: 3
      address: 19050
      length: 2
      dataType: floatBE
      interval: 2000
```

{% endcode %}

The energy counters change slowly. A longer poll interval of ten seconds is sufficient for energy monitoring and reduces the load on the device.

{% code lineNumbers="true" %}

```yaml
activeEnergyConsumed:
  type: Cybus::Endpoint
  properties:
    protocol: Modbus
    connection: !ref umgConnection
    subscribe:
      fc: 3
      address: 19068
      length: 2
      dataType: floatBE
      interval: 10000

activeEnergyDelivered:
  type: Cybus::Endpoint
  properties:
    protocol: Modbus
    connection: !ref umgConnection
    subscribe:
      fc: 3
      address: 19076
      length: 2
      dataType: floatBE
      interval: 10000
```

{% endcode %}

{% hint style="info" %}
If you poll many endpoints, enable [batch read processing](/2-4-2/connectors/shop-floor-connectors/modbus-tcp.md#batch-read-processing) on the connection. Connectware then combines reads of neighboring registers, such as the power values at addresses 19026 to 19050, into a single request.
{% endhint %}

### Cybus::Mapping

The mapping publishes each endpoint on a topic of the ISA-95 hierarchy.

{% code lineNumbers="true" %}

```yaml
mapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          endpoint: !ref voltageL1
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/voltage/l1-n'
      - subscribe:
          endpoint: !ref currentL1
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/current/l1'
      - subscribe:
          endpoint: !ref activePowerTotal
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/power/active'
      - subscribe:
          endpoint: !ref apparentPowerTotal
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/power/apparent'
      - subscribe:
          endpoint: !ref reactivePowerTotal
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/power/reactive'
      - subscribe:
          endpoint: !ref cosPhiL1
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/power-factor/l1'
      - subscribe:
          endpoint: !ref frequency
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/frequency'
      - subscribe:
          endpoint: !ref activeEnergyConsumed
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/energy/active-consumed'
      - subscribe:
          endpoint: !ref activeEnergyDelivered
        publish:
          topic: !sub '${MQTT_TOPIC_PREFIX}/energy/active-delivered'
```

{% endcode %}

With this mapping, the total active power of the line is published on the topic `enterprise/hamburg/assembly/line-1/energy/power/active`, and every other measurement follows the same pattern.

## Installing the Service Commissioning File

1. Install the service commissioning file. See [Installing Services](/2-4-2/data-flows/services/managing/installing.md).
2. Enable the service. See [Enabling Services](/2-4-2/data-flows/services/managing/enabling.md).

**Result:** The service is enabled. Connectware establishes the Modbus/TCP connection to the UMG device and polls the configured addresses.

## Verifying the Data

Open the [Data Explorer](/2-4-2/monitoring/data-explorer.md) and subscribe to `enterprise/hamburg/assembly/line-1/energy/#`. Each topic carries a JSON object with the keys `timestamp` and `value`, where the value is the decoded measurement:

{% code lineNumbers="true" %}

```json
{
  "timestamp": 1784194200354,
  "value": 231.4
}
```

{% endcode %}

A few plausibility checks for the first readings:

* The voltage on `voltage/l1-n` matches your grid, for example around 230 V in Europe.
* The frequency is between 45 and 65 Hz, typically 50 or 60 Hz.
* The power factor on `power-factor/l1` is between -1 and 1.
* The consumed energy counter matches the counter reading on the device display or in GridVis and only increases over time.

If the connection does not reach the **Connected** state, verify that the device is reachable from Connectware and that port 502 is not blocked. If values arrive but look implausible (for example, extremely large or near-zero numbers), the register decoding does not match: check that each `address` is exactly one documented Float address of your UMG model, that `length` is 2, and that `dataType` is `floatBE`. If the values are plausible but off by a constant factor, check the current and voltage transformer ratios configured on the device.

## Service Commissioning File Example

{% file src="/files/N3Lm0qAbBrA4hPvaLkqJ" %}

{% code title="janitza-umg-example.yml" lineNumbers="true" expandable="true" %}

```yaml
---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: support@cybus.io
# ----------------------------------------------------------------------------
# Connecting a Janitza UMG Power Analyzer (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file that reads power quality and energy measurements
  from a Janitza UMG 96RM-E power analyzer over Modbus/TCP and maps them into
  an ISA-95 style MQTT topic hierarchy (Example)

metadata:
  name: Janitza UMG 96RM-E Example
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  umgHost:
    description: Hostname or IP address of the Janitza UMG power analyzer
    type: string
    default: 192.168.1.100

  umgPort:
    description: Modbus/TCP port of the Janitza UMG power analyzer
    type: integer
    default: 502

definitions:
  # ISA-95 style topic prefix: <enterprise>/<site>/<area>/<line>/energy
  MQTT_TOPIC_PREFIX: enterprise/hamburg/assembly/line-1/energy

resources:
  # Connection to the Janitza UMG (Modbus/TCP over the Ethernet port)
  umgConnection:
    type: Cybus::Connection
    properties:
      protocol: Modbus
      targetState: connected
      connection:
        host: !ref umgHost
        port: !ref umgPort
        connectionStrategy:
          initialDelay: 1000
          maxDelay: 30000
          incrementFactor: 2

  # Instantaneous measured values: Float format, two registers each,
  # decoded with floatBE (IEEE 754, big-endian register order).
  # Addresses from the UMG 96RM-E Modbus address list, chapter
  # "Frequently required readings". Other UMG models use different
  # addresses; see the Modbus address list of your model on janitza.com.
  voltageL1:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref umgConnection
      subscribe:
        fc: 3
        address: 19000
        length: 2
        dataType: floatBE
        interval: 2000

  currentL1:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref umgConnection
      subscribe:
        fc: 3
        address: 19012
        length: 2
        dataType: floatBE
        interval: 2000

  activePowerTotal:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref umgConnection
      subscribe:
        fc: 3
        address: 19026
        length: 2
        dataType: floatBE
        interval: 2000

  apparentPowerTotal:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref umgConnection
      subscribe:
        fc: 3
        address: 19034
        length: 2
        dataType: floatBE
        interval: 2000

  reactivePowerTotal:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref umgConnection
      subscribe:
        fc: 3
        address: 19042
        length: 2
        dataType: floatBE
        interval: 2000

  cosPhiL1:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref umgConnection
      subscribe:
        fc: 3
        address: 19044
        length: 2
        dataType: floatBE
        interval: 2000

  frequency:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref umgConnection
      subscribe:
        fc: 3
        address: 19050
        length: 2
        dataType: floatBE
        interval: 2000

  # Energy counters: Float format, two registers each. Counters change
  # slowly, so a longer poll interval is sufficient.
  activeEnergyConsumed:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref umgConnection
      subscribe:
        fc: 3
        address: 19068
        length: 2
        dataType: floatBE
        interval: 10000

  activeEnergyDelivered:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref umgConnection
      subscribe:
        fc: 3
        address: 19076
        length: 2
        dataType: floatBE
        interval: 10000

  mapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref voltageL1
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/voltage/l1-n'
        - subscribe:
            endpoint: !ref currentL1
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/current/l1'
        - subscribe:
            endpoint: !ref activePowerTotal
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/power/active'
        - subscribe:
            endpoint: !ref apparentPowerTotal
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/power/apparent'
        - subscribe:
            endpoint: !ref reactivePowerTotal
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/power/reactive'
        - subscribe:
            endpoint: !ref cosPhiL1
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/power-factor/l1'
        - subscribe:
            endpoint: !ref frequency
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/frequency'
        - subscribe:
            endpoint: !ref activeEnergyConsumed
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/energy/active-consumed'
        - subscribe:
            endpoint: !ref activeEnergyDelivered
          publish:
            topic: !sub '${MQTT_TOPIC_PREFIX}/energy/active-delivered'
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-4-2/guides/machine-connectivity/robots-sensors-shop-floor-devices/connecting-a-janitza-umg-power-analyzer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.