Value Mapping Guide

With the Options / Format Field

User Question

"I read a Modbus int value (example '41'), but I want to output text instead. If '41' then 'On', if '43' then 'Off'. Is this possible?"

Solution: Use the options Field

The options field allows you to map raw values to display text.

---

How to Configure

Step 1: Edit Your Entity

In Protocol Wizard options flow:

1. Go to your device settings
2. Edit the entity (the one reading value 41/43)
3. Find the options field

Step 2: Enter JSON Mapping

In the options field, enter a JSON object mapping values to text:

{"41": "On", "43": "Off"}

Important:

• Use strings as keys (even for numbers): "41" not 41
• Use valid JSON syntax (double quotes, no trailing comma)

Step 3: Save

Save the entity. The display will now show:

• Value 41 → "On"
• Value 43 → "Off"

---

Examples

Example 1: Status Codes

{
  "0": "Idle",
  "1": "Running",
  "2": "Error",
  "3": "Maintenance"
}

Example 2: Yes/No

{
  "0": "No",
  "1": "Yes"
}

Example 3: Temperature Ranges

{
  "0": "Cold",
  "1": "Normal", 
  "2": "Hot",
  "3": "Critical"
}

Example 4: Enum Values

{
  "1": "Mode A - Economy",
  "2": "Mode B - Normal",
  "3": "Mode C - Performance"
}

---

How It Works Internally

When the coordinator reads a value:

1. Read raw value from device: 41
2. Check if options exists in entity config
3. Convert value to string: "41"
4. Look up in options dict: {"41": "On", ...}
5. Return mapped value: "On"
6. Display in Home Assistant: Entity shows "On" instead of 41

Advanced: Format String vs Options

When to Use format Field:

format: "{:.1f}°C"

• Formatting numbers (decimals, units)
• Mathematical transformations
• Date/time formatting

When to Use options Field:

options: {"41": "On", "43": "Off"}

• Mapping discrete values to text
• Status codes → readable text
• Enum values → descriptions

Can You Combine Both?

Yes! They're applied in sequence:

1. Scale/offset applied
2. Format string applied
3. Options mapping applied last

Example:

scale: 10
format: "{:.0f}"
options: {"410": "On", "430": "Off"}

Raw value 41 → scaled to 410 → formatted to "410" → mapped to "On"

---

Troubleshooting

"Options not working"

Check 1: Valid JSON?

❌ Wrong: {41: "On"}        # Missing quotes on key
❌ Wrong: {"41": "On",}     # Trailing comma
✅ Correct: {"41": "On"}

Check 2: Key is a string?

❌ Wrong: {41: "On"}        # Number key
✅ Correct: {"41": "On"}    # String key

Check 3: Exact match?

• Value is 41 but options has "41.0" → Won't match!
• Use exact string representation

Check 4: Coordinator implements it?

• Check if _decode_value() has options mapping logic
• See "Coordinator Implementation" section above

"Value shows number sometimes, text other times"

This means:

• Mapped value exists → Shows text ("On")
• Unmapped value received → Shows number (42)

Solution: Add all possible values to options:

{
  "41": "On",
  "42": "Unknown State",
  "43": "Off"
}

"Can I use ranges?"

No, options only supports exact matches. For ranges, use format string or custom logic.

---

UI Configuration

In the Protocol Wizard UI, the options field appears as:

┌─────────────────────────────────────┐
│ Options (JSON mapping)              │
│ ┌─────────────────────────────────┐ │
│ │ {"41": "On", "43": "Off"}       │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

Tips:

• Validate JSON syntax online jsonlint.com before entering
• Start simple with 2-3 mappings, add more later
• Document what each code means in entity name or description

---

Complete Example

Device: Industrial Pump Controller

Address: 40100 Raw Values:

• 0 = Stopped
• 1 = Starting
• 2 = Running
• 3 = Stopping
• 4 = Error
• 5 = Maintenance

Configuration:

Name: Pump Status
Address: 40100
Data Type: uint16
Options: {
  "0": "Stopped",
  "1": "Starting",
  "2": "Running", 
  "3": "Stopping",
  "4": "Error",
  "5": "Maintenance"
}

Result:

Entity displays "Running" instead of 2 ✅

---

Summary

✅ Use options field for value-to-text mapping ✅ JSON format: {"value": "text", "value2": "text2"}
✅ String keys: Always use quotes around keys ✅ Works for all protocols: Modbus, SNMP, MQTT ✅ Applied last: After scale, offset, and format