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

Step 2: Choose How to Start

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

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:
Name: Unique identifier for your bridge
Instance: Select your UMH instance
Level: Location path (e.g., enterprise → site → area → line → machine)

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:

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.

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:

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:

View Logs
Monitor bridge activity in real-time:

View Metrics
Track performance and throughput:

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_DEBUGenvironment 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
Try the Getting Started guide to connect your first device
Learn about Data Models to structure your data
Explore Metadata and Tracing for debugging
Use Stand-alone Flows for custom processing
Configure Stream Processors to transform data
Last updated

