One post tagged with "tag-configuration"

If you've ever stared at a spreadsheet of 200 PLC register addresses trying to figure out which ones your SCADA system is actually polling, you know the pain. Traditional tag configuration — hardcoded in ladder logic comments, scattered across HMI screens, buried in proprietary configuration tools — doesn't scale.

The solution that's gaining traction in modern IIoT deployments is declarative, JSON-based tag configuration. Instead of configuring your data collection logic in opaque proprietary formats, you define your device's entire tag map as a structured JSON document. This approach brings version control, template reuse, and automated validation to the industrial data layer.

In this guide, we'll walk through the architecture of a production-grade JSON tag configuration system, drawing from real patterns used in industrial edge gateways connecting to Allen-Bradley Micro800 PLCs via EtherNet/IP and to various devices via Modbus RTU and TCP.

Why JSON for PLC Tag Configuration?​

The traditional approach to configuring PLC data collection involves vendor-specific tools: RSLinx for Allen-Bradley, TIA Portal for Siemens, or proprietary gateway configurators. These tools work, but they create several problems at scale:

• No version control. You can't git diff a proprietary binary config file.
• No templating. When you deploy the same machine type across 50 sites, you're manually recreating the same configuration 50 times.
• No validation. Typos in register addresses don't surface until runtime.
• No automation. You can't script the generation of configurations from a master device database.

JSON solves all of these. A tag configuration becomes a text file that can be:

• Stored in Git with full change history
• Templated per device type (one JSON per machine model)
• Validated against a schema before deployment
• Generated programmatically from engineering databases

Anatomy of a Tag Configuration Document​

A well-structured PLC tag configuration document needs to capture several layers of information:

Device-Level Metadata​

Every configuration file should identify the device type it applies to, carry a version string for change tracking, and specify the protocol:

{
  "device_type": 1010,
  "version": "a3f7b2c",
  "name": "Continuous Blender Model X",
  "protocol": "ethernet-ip",
  "plctags": [ ... ]
}

The device_type field is a numeric identifier that maps to a specific machine model. When an edge gateway auto-detects a PLC (by reading a known register), it uses this type ID to look up the correct configuration file. The version field — ideally a short Git hash — lets you track which configuration version is running on each gateway in the field.

For Modbus devices, you'd also include protocol-specific parameters:

{
  "device_type": 5000,
  "version": "b8e1d4a",
  "name": "Temperature Control Unit",
  "protocol": "modbus-rtu",
  "base_addr": 48,
  "baud": 9600,
  "parity": "even",
  "data_bits": 8,
  "stop_bits": 1,
  "byte_timeout": 4,
  "resp_timeout": 100,
  "plctags": [ ... ]
}

Notice the serial link parameters are part of the same document. This is deliberate — you want a single source of truth for "how to talk to this device and what to read from it."

Tag Definitions: The Core Data Model​

Each tag in the configuration represents a single data point you want to collect from the PLC. A complete tag definition captures:

{
  "name": "barrel_zone1_temp",
  "id": 42,
  "type": "float",
  "ecount": 2,
  "sindex": 0,
  "interval": 5,
  "compare": true,
  "do_not_batch": false
}

Let's break down each field:

name — A human-readable identifier for the tag. For EtherNet/IP (CIP) devices, this is the actual PLC tag name. For Modbus, it's a descriptive label since Modbus uses numeric addresses.

id — A numeric identifier used in the wire protocol when transmitting data to the cloud. Using compact integer IDs instead of string names dramatically reduces payload sizes — critical when you're sending telemetry over cellular connections.

type — The data type of the register value. Common types include:

ecount (element count) — How many consecutive elements to read. For a single register, this is 1. For a 32-bit float stored across two Modbus registers, this is 2. For an array of 10 temperature readings, this is 10.

sindex (start index) — The starting element index for array reads. Combined with ecount, this lets you read slices of PLC arrays without pulling the entire array.

interval — How often (in seconds) to poll this tag. This is where you make intelligent decisions about bandwidth:

• 1 second: Critical alarms, emergency stops, safety interlocks
• 5 seconds: Process temperatures, pressures, flows
• 30 seconds: Setpoints, mode selectors (change infrequently)
• 300 seconds: Configuration parameters, serial numbers

compare — When true, the gateway compares each new reading against the previous value and only transmits if the value changed. This is the single most impactful optimization for reducing bandwidth and cloud ingestion costs.

do_not_batch — When true, the value is transmitted immediately rather than being accumulated into a batch payload. Use this for critical alarms that need sub-second cloud visibility.

Modbus Address Conventions​

For Modbus devices, each tag also carries an addr field that encodes both the register address and the function code:

{
  "name": "process_temp",
  "id": 10,
  "addr": 400100,
  "type": "float",
  "ecount": 2,
  "interval": 5,
  "compare": true
}

The address convention follows a well-established pattern:

So addr: 400100 means "holding register at address 100, read via function code 3." This convention eliminates ambiguity about which Modbus function to use — the address itself encodes it.

Why this matters: A common source of bugs in Modbus deployments is using the wrong function code. Someone configures a tag to read address 100 with FC 03 when the device exposes it as an input register (FC 04). With the address convention above, the function code is implicit and unambiguous.

Advanced Patterns: Calculated and Dependent Tags​

Simple register reads cover 80% of use cases. But industrial devices often pack multiple boolean values into a single 16-bit alarm word, or have tags whose values only matter when a parent tag changes.

Calculated Tags: Extracting Bits from Alarm Words​

Many PLCs pack 16 individual alarm flags into a single uint16 register. Rather than reading 16 separate coils, you read one register and extract the bits:

{
  "name": "alarm_word_1",
  "id": 50,
  "addr": 400200,
  "type": "uint16",
  "ecount": 1,
  "interval": 1,
  "compare": true,
  "calculated": [
    {
      "name": "high_temp_alarm",
      "id": 51,
      "type": "bool",
      "shift": 0,
      "mask": 1
    },
    {
      "name": "low_pressure_alarm",
      "id": 52,
      "type": "bool",
      "shift": 1,
      "mask": 1
    },
    {
      "name": "motor_overload",
      "id": 53,
      "type": "bool",
      "shift": 2,
      "mask": 1
    }
  ]
}

When alarm_word_1 is read, the gateway automatically:

1. Reads the raw uint16 value
2. For each calculated tag, applies the right-shift and mask to extract the bit
3. Compares the extracted boolean against its previous value
4. Only transmits if the bit actually changed

This is vastly more efficient than polling 16 individual coils — one Modbus read instead of 16, with identical semantic output.

Dependent Tags: Event-Driven Secondary Reads​

Some tags only need to be read when a related tag changes. For example, you might have a machine_state register that changes between IDLE, RUNNING, and FAULT. When it changes, you want to immediately read a block of diagnostic registers — but you don't want to poll those diagnostics every cycle when the machine state is stable.

{
  "name": "machine_state",
  "id": 100,
  "addr": 400001,
  "type": "uint16",
  "ecount": 1,
  "interval": 1,
  "compare": true,
  "dependents": [
    {
      "name": "fault_code",
      "id": 101,
      "addr": 400010,
      "type": "uint16",
      "ecount": 1,
      "interval": 60
    },
    {
      "name": "fault_timestamp",
      "id": 102,
      "addr": 400011,
      "type": "uint32",
      "ecount": 2,
      "interval": 60
    }
  ]
}

When machine_state changes, the gateway forces an immediate read of all dependent tags, regardless of their normal polling interval. This gives you:

• Low latency on state transitions — fault diagnostics arrive within 1 second of the fault occurring
• Low bandwidth during steady state — diagnostic registers are only polled every 60 seconds when nothing is happening

Contiguous Register Optimization​

One of the most impactful optimizations in Modbus data collection is contiguous register grouping. Instead of making separate Modbus read requests for each tag, the gateway sorts tags by address and groups adjacent registers into single bulk reads.

Consider these tags:

[
  { "name": "temp_1", "addr": 400100, "ecount": 1 },
  { "name": "temp_2", "addr": 400101, "ecount": 1 },
  { "name": "temp_3", "addr": 400102, "ecount": 1 },
  { "name": "pressure", "addr": 400103, "ecount": 2 }
]

A naive implementation makes four separate Modbus requests. An optimized one makes one request: read 5 registers starting at address 400100. The response contains all four values, which are dispatched to the correct tag definitions.

For this optimization to work, the configuration system must:

1. Sort tags by address at load time, not at runtime
2. Validate that function codes match — you can't group a coil read (FC 01) with a holding register read (FC 03)
3. Respect maximum packet sizes — Modbus TCP allows up to 125 registers per read; some devices are more restrictive
4. Respect polling intervals — only group tags that share the same polling interval

The performance difference is dramatic. A typical PLC with 50 Modbus tags might require 50 individual reads (50 × ~10ms = 500ms per cycle) or 5 grouped reads (5 × ~10ms = 50ms per cycle). That's a 10× improvement in polling speed.

IEEE 754 Float Handling: The Register Order Problem​

Reading 32-bit floating-point values over Modbus is notoriously tricky because the Modbus specification doesn't define register byte ordering for multi-register values. A float spans two 16-bit registers, and different PLCs may store them in different orders:

• Big-endian (AB CD): Register N contains the high word, N+1 the low word
• Little-endian (CD AB): Register N contains the low word, N+1 the high word
• Mid-endian (BA DC or DC BA): Each word's bytes are swapped

Your tag configuration should support specifying the byte order, or at least document which convention your gateway assumes. Most libraries (libmodbus, for example) provide helper functions like modbus_get_float() that assume big-endian by default — but always verify against your specific PLC.

Pro tip: When commissioning a new device, read a register where you know the expected value (e.g., a temperature setpoint showing 72.0°F on the HMI). If the gateway reads 72.0, your byte order is correct. If it reads 2.388e-38 or 1.23e+12, you have a byte-order mismatch.

Binary vs. JSON Telemetry Encoding​

Once you've collected your tag values, you need to transmit them. Your configuration should support both JSON and binary encoding, with the choice driven by bandwidth constraints:

JSON encoding is human-readable and debuggable:

{
  "groups": [{
    "ts": 1709500800,
    "device_type": 1010,
    "serial_number": 85432,
    "values": [
      { "id": 42, "values": [72.3] },
      { "id": 43, "values": [true] }
    ]
  }]
}

Binary encoding is 3-5× smaller. A typical binary frame packs:

• 1-byte header marker
• 4-byte group count
• Per group: 4-byte timestamp, 2-byte device type, 4-byte serial number, 4-byte value count
• Per value: 2-byte tag ID, 1-byte status, 1-byte value count, 1-byte value size, then raw value bytes

A batch that's 2,000 bytes in JSON might be 400 bytes in binary. Over a cellular connection billed per megabyte, that savings compounds fast.

Putting It All Together: Configuration Lifecycle​

A production deployment follows this lifecycle:

1. Template creation: For each machine model, create a JSON tag configuration. Store it in Git.
2. Deployment: Push configurations to edge gateways via your device management platform. The gateway monitors the config file and reloads automatically when it changes.
3. Auto-detection: When the gateway starts, it queries the PLC for its device type (a known register). It then matches the type to the correct configuration file.
4. Validation: At load time, validate register addresses (no duplicates, valid ranges), data types, and interval values. Reject invalid configs before they cause runtime errors.
5. Runtime: The gateway polls tags according to their configured intervals, applies change detection, groups contiguous registers, and batches values for transmission.

How machineCDN Handles Tag Configuration​

machineCDN's edge gateway uses this exact pattern — JSON-based device templates that are automatically selected based on PLC auto-detection. Each machine type in a plastics manufacturing facility (blenders, dryers, granulators, chillers, TCUs) has its own configuration template with pre-mapped tags, optimized polling intervals, and calculated alarm decomposition.

When a new machine is connected, the gateway detects the PLC type, loads the matching template, and starts collecting data — typically in under 30 seconds with zero manual configuration. For plants running 20+ machines across 5 different models, this eliminates weeks of commissioning time.

Common Pitfalls​

1. Overlapping addresses. Two tags pointing to the same register with different IDs will cause confusion in your data pipeline. Validate for uniqueness at load time.

2. Wrong element count for floats. A 32-bit float on Modbus requires ecount: 2 (two 16-bit registers). Setting ecount: 1 gives you garbage data.

3. Polling too fast on serial links. Modbus RTU over RS-485 at 9600 baud can handle roughly 10-15 register reads per second. If you configure 50 tags at 1-second intervals, you'll never keep up. Budget your polling rate against your link speed.

4. Missing change detection on high-volume tags. Without compare: true, every reading gets transmitted. For a tag polled every second, that's 86,400 data points per day — even if the value never changed.

5. Batch timeout too long. If your batch timeout is 60 seconds but an alarm fires, it won't reach the cloud for up to a minute unless that alarm tag has do_not_batch: true.

Conclusion​

JSON-based tag configuration isn't just a nice-to-have — it's a fundamental enabler for scaling IIoT deployments. It brings software engineering best practices (version control, templating, validation, automation) to a domain that has traditionally relied on manual, vendor-specific tooling.

The key design principles are:

• One file per device type with version tracking
• Rich tag metadata covering data types, intervals, and delivery modes
• Hierarchical relationships for calculated and dependent tags
• Protocol-aware addressing that encodes function codes implicitly
• Contiguous register grouping for optimal Modbus performance

Get this foundation right, and you'll spend your time analyzing machine data instead of debugging data collection.