Variables
Overview
UMH Core uses a three-tier variable system for protocol converter templates that enables flexible configuration and runtime customization:
User Variables: Defined in the
variables:
section of your YAML configuration, flattened to top-level accessInternal Variables: Runtime-injected system metadata and computed values
Global Variables: Fleet-wide settings (NOT YET IMPLEMENTED)
Variable Precedence
Variables follow a clear precedence hierarchy:
User Variables (highest priority) - Override all others when flattened by VariableBundle
Internal Variables - System-generated values
Global Variables - Fleet-wide defaults (NOT YET IMPLEMENTED)
Available Variables
Connection Variables
These variables provide device connection information, typically auto-injected from Connection configurations or defined by users.
{{ .IP }}
Device IP address or hostname
192.168.1.100
User/Connection
Current
{{ .PORT }}
Device communication port
4840
User/Connection
Current
Usage Example:
protocolConverter:
config: |
input:
opcua:
endpoint: "opc.tcp://{{ .IP }}:{{ .PORT }}/OPCUA/SimulationServer"
Location Variables
These variables provide hierarchical location information for data organization and topic routing.
{{ .location_path }}
Dot-separated hierarchical path
factory.line1.machine1
Internal
Current
{{ .location }}
Location as numbered map
{"0":"factory","1":"line1","2":"machine1"}
Internal
Current
{{ .location.0 }}
Enterprise level (first location)
factory
Internal
Current
{{ .location.1 }}
Site level (second location)
line1
Internal
Current
{{ .location.2 }}
Area level (third location)
machine1
Internal
Current
Usage Example:
protocolConverter:
config: |
output:
mqtt:
topic: "umh/v1/{{ .location_path }}/data"
# Or access individual levels:
# topic: "umh/v1/{{ .location.0 }}/{{ .location.1 }}/data"
Internal System Variables
These variables provide runtime metadata and system integration information.
{{ .internal.bridged_by }}
Bridge identifier that created this config
protocol-converter-node1-pc123
Internal
Current
{{ .internal.id }}
Protocol converter instance ID
pc-123
Internal
Current
{{ .internal.umh_topic }}
UMH topic for write flows
umh/v1/factory/line1/_historian
Internal
Current (write flows only)
Usage Example:
protocolConverter:
config: |
output:
mqtt:
topic: "{{ .internal.umh_topic }}"
metadata:
bridged_by: "{{ .internal.bridged_by }}"
Global Variables (Not Yet Implemented)
These variables will provide fleet-wide configuration when implemented.
{{ .global.cluster_id }}
Multi-cluster identifier
cluster-west-1
Global
NOT IMPLEMENTED
{{ .global.* }}
Other fleet-wide variables
varies
Global
NOT IMPLEMENTED
Deprecated Variables
The following variables should be replaced in your configurations:
{{ .HOST }}
Deprecated
{{ .IP }}
Replace in all configurations
{{ .DEVICE_IP }}
Inconsistent
{{ .IP }}
Standardize usage
{{ .DEVICE_PORT }}
Inconsistent
{{ .PORT }}
Standardize usage
User-Defined Variables
You can define custom variables in the variables:
section of your configuration. These are flattened to top-level access and override any internal variables with the same name.
Common patterns:
{{ .SCAN_RATE }}
- Polling intervals{{ .TAG_PREFIX }}
- Tag naming prefixes{{ .USERNAME }}
- Authentication credentials{{ .PASSWORD }}
- Authentication credentials
Example:
protocolConverter:
variables:
SCAN_RATE: "1000ms"
TAG_PREFIX: "PLC1_"
config: |
input:
opcua:
endpoint: "opc.tcp://{{ .IP }}:{{ .PORT }}/OPCUA/SimulationServer"
poll_interval: "{{ .SCAN_RATE }}"
tag_prefix: "{{ .TAG_PREFIX }}"
Variable Sources
Understanding where variables come from helps with troubleshooting:
Connection Variables (
{{ .IP }}
,{{ .PORT }}
): Auto-injected from Connection configurations attached to BridgesLocation Variables (
{{ .location_path }}
,{{ .location }}.*
): Computed from agent location + bridge location by BuildRuntimeConfigInternal Variables (
{{ .internal.* }}
): Runtime-injected system metadataUser Variables: Explicitly defined in
variables:
sectionGlobal Variables: Fleet-wide settings (NOT YET IMPLEMENTED)
Troubleshooting
Variable Not Found
If a variable is not resolving:
Check spelling and case sensitivity
Verify the variable is defined in the
variables:
section (for user variables)Ensure Connection is properly attached (for
.IP
/.PORT
)Check that location hierarchy is configured (for location variables)
Deprecated Variable Warnings
Replace deprecated variables with their current equivalents:
{{ .HOST }}
→{{ .IP }}
{{ .DEVICE_IP }}
→{{ .IP }}
{{ .DEVICE_PORT }}
→{{ .PORT }}
For questions about variables not listed here, check the configuration reference or consult the UMH Core documentation.
Last updated