Value Mapping

Value mapping converts raw device values into numeric outputs using an ordered list of match rules. When enabled on a tag, every value read from the device is evaluated against the rules — the first matching rule determines the output.

Common use cases include:

• Converting status strings like "Off" and "On" to numeric values 0 and 1
• Mapping numeric ranges (e.g. values above 100 map to an alarm state)
• Normalizing wildcard-patterned strings (e.g. anything ending in _active maps to 1)
• Providing a catch-all default when no specific rule matches

How It Works

Value mapping rules are evaluated top-to-bottom. The first rule that matches the incoming value wins — its output becomes the tag's numeric value, and the original raw value is preserved as the lookup key.

For example, given these rules:

If the device returns "On", rule 2 matches. The tag's value becomes 1 and the lookup key shows "On". If the device returns something unexpected like "Standby", rules 1 and 2 don't match, but rule 3 (the catch-all) does — the value becomes -1.

Enabling Value Mapping

Value mapping is configured in the Advanced section of a tag's configuration:

1. Open the tag's Configuration tab
2. Scroll to the Advanced section
3. Toggle Use Value Mapping on
4. Add your rules using the rule editor
5. Save your changes

You can also enable value mapping when creating a new tag — the same settings are available in the create form's advanced section.

Match Types

The rule editor supports eight match types:

Exact Match

Matches when the raw value equals the pattern. For numeric values, this uses a tolerance-based comparison to handle floating-point imprecision — so a value of 0.30000000000000004 (the result of 0.1 + 0.2) will correctly match a pattern of 0.3. For string values, it performs a direct string comparison.

Numeric Comparisons

The Greater Than, Greater or Equal, Less Than, Less or Equal, and Between match types work with numeric values only. If the raw value cannot be parsed as a number, these rules are skipped and evaluation continues to the next rule.

Between matches when the value falls within a range (inclusive on both ends). In the editor, you enter the minimum and maximum values separately.

Wildcard Pattern

Uses glob-style matching where:

• * matches any number of characters
• ? matches exactly one character

For example, the pattern Sensor_*_OK would match Sensor_01_OK, Sensor_Temp_OK, etc.

Any (Catch-all)

Always matches. Place this as the last rule to provide a default output when no other rule matches. No pattern is needed.

Additional Options

Case-Insensitive Matching

When enabled, Exact Match and Wildcard Pattern rules ignore letter case. For example, "off", "OFF", and "Off" would all match a pattern of "Off".

This setting has no effect on numeric comparisons (Greater Than, Less Than, Between, etc.) since numbers don't have case.

Reverse Mapping on Write

For output tags, enabling reverse mapping converts the numeric output value back to the original string before writing to the device. This only works with Exact Match rules — it finds the first exact rule whose output matches the value being written and sends the rule's pattern string to the device instead.

For example, if an AI model writes the value 1 to an output tag with the rules above, reverse mapping would convert it back to "On" before sending it to the device.

Viewing the Lookup Key

When value mapping is active, the tag's live data displays both:

• Value — the numeric output from the matched rule
• Lookup Key — the original raw value from the device, shown in brackets next to the value

This appears in the tag list table and on the tag's overview page. It helps you verify which raw value was received and which rule matched.

Examples

String-to-Number Mapping

Map device status strings to numeric values:

Numeric Range Mapping

Classify a temperature reading into zones:

Wildcard Pattern Matching

Map device response codes that follow a naming pattern: