Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Bridges

Prerequisite: Understand Data Flow concepts and complete the Getting Started guide.

Bridges move data into and out of the Unified Namespace, providing connection monitoring and automatic data organization. While read flows work with any protocol, write flows are not yet implemented - use stand-alone flows for writing to external systems.

New to UMH? This page is the reference for setting up real bridges. If you just want to get mock data flowing and learn the basics first, start with Step 2: Connect Your First Data Source.

UI Capabilities

Action
Available
Notes

Create bridges

✅

Visual protocol configuration

Create from existing bridge

✅

Copy a healthy bridge's configuration

Start from a template

✅

84 pre-configured templates, filtered by vendor and protocol

Select protocols

✅

OPC UA, Modbus, S7, MQTT, 50+ more

Configure location path

✅

ISA-95 levels (0-4)

Map addresses to topics

✅

Dropdown of data model fields for custom data contracts

Monitor connection health

✅

Real-time status

View logs

✅

Live log streaming

View metrics

✅

Throughput monitoring

Edit bridges

✅

Modify and redeploy

Delete bridges

✅

Clean removal

Advanced mode

✅

Direct YAML editing

Creating a Bridge (UI)

Step 1: Navigate to Data Flows

Go to Data Flows and click Add Bridge:

Data Flows Overview

Step 2: Choose How to Start

Create a New Bridge
  • From Scratch: start from a pre-configured protocol template, which is functional out of the box, or customize the template to fit your needs.

  • From Existing Bridge: pick a healthy bridge from any instance and start with a copy of its configuration. Adapt the bridges name, connection, and addresses.

The remaining steps describe the from-scratch path. Starting from an existing bridge skips the template list and lands on the same screens with the fields already filled in.

Step 3: Select a Template

Select a Template

Templates carry a working protocol configuration. Search by name, or narrow the list with the Vendor and Protocol filters.

Behind the templates we support 50+ industrial protocols through Benthos-UMH plus everything from Redpanda Connect:

Common industrial protocols:

  • Modbus: For PLCs and RTUs

  • OPC UA: For industrial servers

  • S7: For Siemens PLCs

  • Ethernet/IP: For Allen-Bradley

  • And many more: See full list at Benthos-UMH Inputs

Step 4: Configure General Settings

Fill in the basic information and proceed with Step 5.

General Information

General Information:

  • Name: Unique identifier for your bridge

  • Instance: Select your UMH instance

  • Level: Location path (e.g., enterprise → site → area → line → machine)

Connection Configuration

Connection:

  • IP Address: Device IP (becomes {{ .IP }} variable)

  • Port: Connection port (becomes {{ .PORT }} variable)

The protocol itself needs no selection here. It comes from the template you picked in Step 3, and the Read tab opens on that protocol's settings.

Step 5: Configure Protocol Settings

Each protocol has specific settings. For example, S7:

Siemens S7 Configuration

Step 6: Map Addresses

Each row in the address mapping table becomes one UNS topic: the protocol address, followed by the data contract, virtual path, and tag name that build the topic.

Address Mapping Table

With _historian or _raw, Virtual Path and Tag Name are free-text fields. Selecting a custom data contract merges both columns into a single dropdown listing every field the contract's data model defines, so you pick a valid path instead of typing one. A value the model rejects, for example after switching contracts, stays in the row, is flagged red, and blocks deploy until you correct it. Contracts whose data model references other models keep free-text input.

Step 7: Deploy

Click Save & Deploy. The bridge will start connecting to your device.

Managing Bridges

View Status

The main view shows all bridges with connection status and throughput:

Bridges Overview
  • Green dot: Connected and running

  • Yellow dot: Starting or warning state

  • Grey dot: Intermediate states (starting, stopping, or stuck in starting state)

Context Menu

Right-click any bridge for quick actions:

Bridge Context Menu

View Logs

Monitor bridge activity in real-time:

Bridge Logs

View Metrics

Track performance and throughput:

Bridge Metrics

Enable Debug Logging

When troubleshooting connection or data issues, enable debug logging in your bridge configuration:

Via YAML:

Debug logging provides:

  • Detailed protocol communication logs

  • Connection state transitions

  • Data parsing details

  • For OPC UA: Sets OPC_DEBUG environment variable for protocol-level debugging

Remember to disable debug logging after troubleshooting - it generates significantly more log data.

To view debug logs, go to the bridge and select Logs.

Important: Data Types from Different Protocols

Industrial protocols (OPC UA, Modbus, S7) only provide time-series data - snapshots of values at points in time. They cannot directly provide relational records.

IT protocols (MQTT, HTTP, Kafka) can provide relational data - when you select "relational" as the data type in the UI, the bridge automatically uses nodered_js processor to handle complex business records like work orders or batch reports.

For converting time-series to relational data, see Stream Processors or use Stand-alone Flows with state management.

Configuration (YAML)

Advanced users can edit the YAML directly:

Key Configuration Elements

Location Path:

Template Variables:

Connection Monitoring:

Metrics

The Management Console shows each bridge's message counts. Open the bridge and select Metrics (see View Metrics). The view shows messages received and sent, errors, connection status and latency for the bridge's input, processors and output. Port 8080, umh-core's Prometheus endpoint, does not carry per-bridge message counts. It carries the bridge's state and error counts. Metrics explains how to read them, which framework runs bridges and what the labels and the state values mean.

Bridges run on FSMv1 and use the standard FSMv1 metrics. For a bridge named mixing-station, the series carry these labels:

Part of the bridge

component

instance

The bridge

protocol_converter_instance

mixing-station

Its connection

connection_instance

protocolconverter-mixing-station

Its read flow

dataflow_component_instance

read-protocolconverter-mixing-station

Its write flow

dataflow_component_instance

write-protocolconverter-mixing-station

The Benthos process of its read flow

benthos_instance

dataflow-read-protocolconverter-mixing-station

The Benthos process of its write flow

benthos_instance

dataflow-write-protocolconverter-mixing-station

To alert when a bridge has not been active for 5 minutes, use this rule with for: 5m. In Prometheus, write exported_instance for instance, or keep instance if the scrape job sets honor_labels: true:

For the bridge itself, umh_core_service_current_state reads 3 when active, 4 when idle and 0 when stopped. The rule does not fire for a bridge that is idle or stopped. A stopped bridge is one you stopped on purpose. When you delete a bridge, umh-core keeps its last state series at -1 until the container restarts, so the rule keeps firing for it. Exclude the deleted name by adding exported_instance!="<deleted bridge>" to the selector, or restart the container. The connection reports errors and reconcile time, but no state. The definitions are in pkg/metrics/metrics.go.

Connection Check

Before umh-core starts a bridge, it checks that the device's host and port answer. This connection check runs on FSMv2. The NMAP_BACKEND environment variable that once switched it to FSMv1 is ignored and can be removed.

When the device stops answering, the bridge's own state changes. It stays in starting_connection if it has not started yet. It moves to degraded_connection if it was already running. To see whether the device answers, read the bridge's state.

The check's series carry a hierarchy_path that ends in connection-protocolconverter-<bridge>-001(nmap).

Next Steps

Last updated