Tag Configuration¶
Tags represent individual data points from your Modbus devices. Configure tags to read values, apply scaling, and publish to MQTT.
Screenshot placeholder: List of configured tags
What is a Tag?¶
A tag is a single data point from a Modbus device, such as: - Temperature reading - Motor speed - Pressure value - Status bit - Alarm state - Counter value
Tag Types¶
The gateway supports 5 tag types:
1. Numeric Tags¶
Standard numeric values with optional scaling.
Supported Data Types: - Int16, Int32, Int64 - UInt16, UInt32, UInt64 - Float32, Float64
Scaling Options: - Scale Factor: Multiply by factor - Offset: Add offset after scaling - Precision: Decimal places for display
Example: Temperature sensor reading 2350 → Scale: 0.1, Offset: -273.15 → Result: -38.15°C
2. State Tags¶
Map numeric values to text labels.
Example: Motor status - 0 = "Stopped" - 1 = "Running" - 2 = "Fault"
Use Cases: - Equipment states - Operating modes - Alarm descriptions
3. Bit Tags¶
Extract individual bits from registers.
Register Types: - Coils (CS) - directly read - Input Status (IS) - directly read - Holding Registers (HR) - extract bit - Input Registers (IR) - extract bit
Example: Extract bit 3 from HR register 100
4. BCD Tags¶
Binary-Coded Decimal conversion.
Use Cases: - Legacy meters - Display values - Certain PLCs
Example: BCD value 0x1234 → 1234
5. String Tags¶
ASCII or UTF-8 text from consecutive registers.
Configuration: - Number of registers - Character encoding (ASCII/UTF-8) - Byte order
Use Cases: - Device names - Status messages - Serial numbers
Adding a Tag¶
Screenshot placeholder: Add tag configuration form
- Navigate to device → Tags → Add Tag
- Fill in configuration:
Basic Settings¶
- Tag Name: Descriptive name (e.g., "Motor Speed")
- Metric Name: Sparkplug metric name
- Tag Group: Select group for polling
- Enabled: Enable/disable this tag
Modbus Settings¶
- Register Type: HR, IR, CS, or IS
- Address: Register address (1-based or 0-based)
- Data Type: Int16, Float32, Boolean, etc.
- Tag Type: Numeric, State, Bit, BCD, or String
Data Processing¶
For Numeric tags: - Scale Factor: Multiply raw value - Offset: Add after scaling - Precision: Decimal places - Engineering Units: Display units
For State tags: - Add value/label mappings
For Bit tags: - Bit Number: 0-15 for 16-bit registers
For String tags: - Register Count: Number of registers - Character Encoding: ASCII or UTF-8
Advanced Options¶
- Is RBE: Report by exception (only publish on change)
- Is Burst: Include in burst polling
- Is Writable: Allow DCMD writes
-
Backfill: Store for offline recovery
-
Click Save
Register Addressing¶
Register Types¶
| Type | Name | Access | Typical Range |
|---|---|---|---|
| HR | Holding Register | Read/Write | 40001-49999 |
| IR | Input Register | Read Only | 30001-39999 |
| CS | Coil | Read/Write | 00001-09999 |
| IS | Input Status | Read Only | 10001-19999 |
Address Modes¶
1-Based (Traditional): - HR address 40001 → PDU address 0 - IR address 30001 → PDU address 0
0-Based (Modern): - HR address 0 → PDU address 0 - IR address 0 → PDU address 0
Set addressing mode per device.
Byte Order (Swap Modes)¶
For multi-register values (Int32, Float32, etc.), configure byte order:
| Mode | Description | Example |
|---|---|---|
| 0 | No swap (ABCD) | Default |
| 1 | Swap bytes (BADC) | Byte swap |
| 2 | Swap words (CDAB) | Word swap |
| 3 | Swap both (DCBA) | Full reverse |
Tag Validation¶
The system validates: - ✅ IR/IS are read-only (writable=false) - ✅ CS/IS must be Boolean data type - ✅ State/BCD/String cannot use CS/IS - ✅ Address ranges are valid - ✅ No overlapping addresses in same group
Testing Tags¶
Poll Once¶
Screenshot placeholder: Poll once result
Test tag configuration: 1. Click Poll Once on device 2. View tag values 3. Verify scaling and formatting
Validate Tags¶
Check all tag configurations: 1. Click Validate Tags 2. System checks for errors 3. Review and fix issues
Bulk Operations¶
Import Tags¶
Screenshot placeholder: Import tags from CSV/JSON
Import many tags at once: 1. Click Import Tags 2. Upload CSV or JSON file 3. Map columns 4. Review and confirm
Export Tags¶
Export tags to backup or share: 1. Select device 2. Click Export Tags 3. Choose format (CSV/JSON) 4. Download file
Best Practices¶
- ✅ Use descriptive tag names
- ✅ Add engineering units
- ✅ Group tags by poll rate
- ✅ Enable RBE for slowly-changing values
- ✅ Test with Poll Once before enabling
- ✅ Document custom scaling
- ✅ Use templates for similar devices