Connect a Generic Modbus TCP Device

🧾 Overview

This guide walks you through the steps to connect any generic Modbus TCP device to MachineMetrics using a custom adapter script. You’ll define register mappings in YAML, apply Modbus address conventions, and upload your configuration via the MachineMetrics platform.

✅ Requirements

• A Modbus TCP-compatible device.
• Ethernet connection from device to MachineMetrics Edge (direct or via switch).
• Device IP address and port (typically 502).
• Modbus register map (with addresses, types, and signal descriptions).
• MachineMetrics Edge installed and online.
• Admin access to the MachineMetrics platform.

🔌 Step 1: Physical Connection

1. Connect an Ethernet cable from the Modbus device to the local network or switch.
2. Ensure the MachineMetrics Edge is on the same subnet as the device.
3. Verify connectivity (e.g., ping the device from the Edge).

🌐 Step 2: Network Configuration

1. Access the Modbus device configuration (via its control panel or web interface).
2. Set or confirm:
   • Static IP address.
   • Subnet mask and gateway (must match Edge’s network).
   • Modbus TCP port (default: 502).
3. Save and apply network settings.

📟 Step 3: Enable Data Collection

Create a YAML adapter script with the following components:

Example Structure

version: 2
unit-id: 1
byte-order: big
word-order: big
address-space: mixed

registers:
  machine-status:
    address: 40001
    type: uint16
    func: 3

coils:
  cycle-complete:
    address: 1
    func: 1

variables:
  execution:
    - source: machine-status > 0
    - state:
        - ACTIVE: this
        - READY: true
  part-count:
    - source: cycle-complete
    - rising-edge
    - count

data-items:
  - execution
  - part-count
  - machine-status

Key Rules

• Use func: to specify Modbus function:
  • 1: Coils
  • 2: Discrete Inputs
  • 3: Holding Registers
  • 4: Input Registers
• Address Conversion:
  • 6-digit addresses (e.g., 400010): Drop the leading digit and subtract 1 → 9
  • 5-digit addresses (e.g., 40001): Use as-is
• Data Types: Use one of int16, uint16, int32, uint32, float32, or string (with size).
• Required Variables:
  • execution: for machine state
  • part-count: for counting parts

🔥 Step 4: Configure Firewalls

Ensure the following are open between the Edge and the Modbus device:

• TCP port 502 (default for Modbus TCP)
• Any custom port used by the device

Also confirm that local network security policies allow Modbus TCP traffic.

🧩 Step 5: Add Machine to MachineMetrics

1. Log in to MachineMetrics.
2. Navigate to Dashboard > Machine List
3. Click Add Machine.
4. Select Modbus TCP as the machine type.
5. Enter the device’s IP address and port.
6. Upload your adapter YAML script.
7. Click Save & Activate.

MachineMetrics will start polling the device using the script.

🛠️ Troubleshooting

🆘 Support

If issues persist:

1. Take a screenshot of your YAML script.
2. Collect device register map and confirm IP/port details.
3. Contact MachineMetrics Support via the chat or email:
   • Mention the machine name and YAML script used

🔍 Modbus Configuration Settings Explained

1. byte-order: big | little

What it means:

• This controls how the two bytes of a 16-bit Modbus register are interpreted.
• A 16-bit register is made up of two 8-bit bytes. The order in which these bytes are transmitted and interpreted can vary by device.

Options:

• big (Big-endian): The most significant byte comes first.
• little (Little-endian): The least significant byte comes first.

When to change it:

• If your data (e.g. integer values) is showing up scrambled or off by a factor, this might be set incorrectly.
• Most devices default to big, but you should validate this using a Modbus test client like Simply Modbus.

2. word-order: big | little

What it means:

• This determines the order of two consecutive 16-bit registers when used together to represent a 32-bit value (e.g., float32, uint32).
• Just like with bytes in a register, the order of registers can vary.

Options:

• big: The higher address register contains the most significant bits.
• little: The lower address register contains the most significant bits.

When to change it:

• If you're reading a 32-bit float or integer and the number is wildly off or non-sensical (e.g., negative where it shouldn’t be), try switching this setting.
• This is especially important for temperature, power, and pressure sensors.

3. address-space: mixed | function3

What it means:

• Modbus has four function types, each with its own address space. Some devices use mixed addressing where the address itself tells you which function it belongs to.

Options:

• mixed: The address encodes both the value and its function type. For example:
  • 40001–49999 → Holding Registers (Function 3)
  • 30001–39999 → Input Registers (Function 4)
  • 10001–19999 → Discrete Inputs (Function 2)
  • 1–9999 → Coils (Function 1)
• function3 (or flat): All registers are assumed to be Holding Registers using Function 3, and only the numeric part of the address matters.

Extended Mode

Enables full 16-bit range using 6-digit addresses:

• 000001–065536: Coils (func: 1)
• 100001–165536: Discrete Inputs (func: 2)
• 300001–365536: Input Registers (func: 4)
• 400001–465536: Holding Registers (func: 3)

Note: If any address exceeds 65535, extended is applied automatically unless specified otherwise.

When to use:

• If your Modbus map uses addresses like 40001, 30001, etc., you’re likely in mixed mode.
• If your addresses are just numeric (e.g. 1, 2, 3) and you’re told everything is accessed using Function 3, use function3.
• If you modbus map uses 6 digits you can use extended mode. If if you require mixed, convert to 5 digit by dropping the leading digit and subtracting 1. 400020 = 19

✅ How to Include This in Your Guide Template

Include a dedicated section in your Modbus onboarding guide, like this:

🔧 Modbus Configuration Parameters (Example)

unit-id: 1
byte-order: big       # Most significant byte first
word-order: big       # Most significant register first
address-space: mixed  # Uses 40001, 30001, etc.

Note:
If you see incorrect values when reading integers or floats, try switching byte-order or word-order. Always test with a Modbus client before onboarding to MachineMetrics.

Let me know if you want a reusable YAML block or onboarding template that auto-generates this based on Modbus maps or vendor specs. I can also help write a troubleshooting section for this.