Modbus TCP Onboarding
Topics covered in this article:
- Determine Modbus support
- Connectivity Test
- Modbus Parameters
- Modbus Map
- MachineMetrics Device Configuration
Determine Modbus support
Some machine controls support running a Modbus server to provide internal data, but may not be configured to do so by default. Some examples of why Modbus may not be readily useable on a control:
- It may be an optional component not supported by your machine control or under certain configurations
- It may need to be loaded as an additional program in the control
- It may need to be programmed to provide data
- It may need to be enabled
If you have any uncertainty about the Modbus capabilities of your machine control, please reach out to your vendor to see what options are available to you.
Once you’ve established that Modbus should be available on your control, you should test communication with it before trying to do any Modbus configuration in MachineMetrics. Collect the following information:
- The IP address of your control
- The TCP port being used by Modbus (usually 502)
Make sure the TCP port is open on the machine’s firewall if there is one. Connect a computer to the same network that the machine control is on, and use a Modbus client to try and open a connection to the Modbus server on the machine. If you do not have a Modbus client already, you can download one such as the “Simply Modbus TCP Client”, which will run in a trial mode and allow you to perform basic testing.
To properly communicate with the Modbus server, you’ll need to identify additional parameters:
- The Modbus unit/device/slave ID for the device (usually 1)
- The server’s byte order
- The server’s word order
- The layout of register address space
- Whether one or multiple function types are used
The unit/device/slave ID is the address of a Modbus device in a chain of serial devices, and will not necessarily be relevant for Modbus-TCP communication. If you know the unit ID is not used in your setup, you can assume the value to be 1.
The server byte and word ordering refer to how a server returns data values. Each Modbus register is a 16-bit integer, composed of two bytes, and the server may return these bytes in either “little-endian” (low byte first) or “big-endian” (high byte first) order. If you see incorrect values when reading 16-bit numbers, this setting might be wrong. Similarly, to emulate 32-bit integers and floating-point values, Modbus needs to return data in two consecutive registers. It may return the registers in either order. If you see incorrect values when reading 32-bit numbers, this setting might be wrong.
Register address space and functions are related concepts. Modbus supports 4 different read functions: discrete output coils (1), discrete input contacts (2), analog output holding registers (3), and analog input registers (4). Each of these functions has its own address space from 0 - 65535. A common convention in Modbus addressing, which we refer to as “mixed”, uses part of the address itself to determine which function should be read. This convention is as follows:
- Address 1 - 9999: discrete output coils (1)
- Address 10001 - 19999: discrete input contacts (2)
- Address 30001 - 39999: analog input registers (4)
- Address 40001 - 49999: analog output holding registers (3)
This scheme limits each function to a range of 10,000 values. It’s common for Modbus devices to operate in either mixed mode, or to utilize only function 3 over its full address space.
A Modbus map is a table of data values provided by the Modbus server, where each row lists the address and type of the value. An example Modbus map would be:
|program||40021||string (64)||Program name, up to 64 characters|
|reg80||40053||uint16||Raw register value|
Types are interpreted by the client, and MachineMetrics supports the following types:
- int16: 16-bit signed integer
- uint16: 16-bit unsigned integer
- int32: 32-bit signed integer
- uint32: 32-bit unsigned integer
- float32: 32-bit floating-point number
- string: A sequence of characters making up a string of text. A length must be provided with string types.
If you do not know what your Modbus map looks like, consult with your machine tool vendor. Your control may support a standard map, or it may require all data to be custom programmed.
Use a Modbus client to test reading some of the items in the Modbus map. This will verify that Modbus is programmed correctly, that data is coming through, and that parameters such as byte order are correctly known.
MachineMetrics Device Configuration
Once a Modbus configuration has been validated in the above steps, it’s time to configure a machine with a Modbus data source in MachineMetrics.
In the Integration Data Sources section of the Add Machine form (or in the Integration Data Sources section of the edit form for existing machines), select Modbus as the integration type. Enter the IP of the machine control in the Address field. If it’s not using the standard Modbus port 502, append the port to the IP with a colon (e.g. 10.20.30.40:8000).
In the Config box, you’ll need to specify Modbus parameters, register and coil definitions, data item mappings, and possibly data transformations. For a complete description of config options, refer to the following documents:
- Modbus TCP Adapter Device
- IO Configuration - Data Items
- IO Configuration - Variables
Here’s what a sample Modbus configuration reading both coils (function 1) and registers (function 3) looks like:
The name given to each data item will influence how the item maps to a name and type in MachineMetrics. There are several reserved names that can be used to definitively map the item to a correct type. A partial list of these reserved name mapping is:
- Execution: execution
- Current: current, current1 - current4
- Flow: flow, flow1 - flow4
- Pressure: pressure, pressure1 - pressure4
- Temperature: temperature, temperature1 - temperature4
- Voltage: voltage, voltage1 - voltage4
- Alarms: actuator_alarm, angle_alarm, hardware_alarm, level_alarm, load_alarm, position_alarm, pressure_alarm, system_alarm, temperature_alarm
- Generic: sensor1 - sensor3
Contact MachineMetrics support at firstname.lastname@example.org for the most up-to-date list of reserved names. Data item names not chosen from this set may not automatically map within our system. Contact MachineMetrics support when adding data not represented by the items in the reserved name list.