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 access
• Internal Variables: Runtime-injected system metadata and computed values
• Global Variables: Fleet-wide settings (NOT YET IMPLEMENTED)

Variable Precedence

Variables follow a clear precedence hierarchy:

1. User Variables (highest priority) - Override all others when flattened by VariableBundle
2. Internal Variables - System-generated values
3. 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.

Variable	Description	Example Value	Source	Status
{{ .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.

Variable	Description	Example Value	Source	Status
{{ .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.

Variable	Description	Example Value	Source	Status
{{ .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.

Variable	Description	Example Value	Source	Status
{{ .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:

Deprecated Variable	Status	Replacement	Action Required
{{ .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 Bridges
• Location Variables ({{ .location_path }}, {{ .location }}.*): Computed from agent location + bridge location by BuildRuntimeConfig
• Internal Variables ({{ .internal.* }}): Runtime-injected system metadata
• User Variables: Explicitly defined in variables: section
• Global Variables: Fleet-wide settings (NOT YET IMPLEMENTED)

Troubleshooting

Variable Not Found

If a variable is not resolving:

1. Check spelling and case sensitivity
2. Verify the variable is defined in the variables: section (for user variables)
3. Ensure Connection is properly attached (for .IP/.PORT)
4. Check that location path 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.