IO-Link Onboarding

Overview

IO-Link is a device protocol that standardizes the exchange of data between a wide array of smart sensors and a gateway device they are connected to, called a master block. As a standard it allows sensors from different manufacturers to be cross-compatible with any IO-Link master block.

What IO-Link is NOT is a data contextualization standard like MTConnect. IO-Link also does not standardize how a master block communicates data to external applications, like the MachineMetrics edges services. Because of this, our IO-Link support is limited to a collection of master blocks that we explicitly support.

Supported Devices

The IO-Link integration should support all conforming IO-Link sensors, but our support for master blocks is currently limited to:

• ifm blocks with an IoT data port

Additional blocks could be supported in the future and will be marked by different entries in the integration type list.

Be aware, not all ifm blocks have an IoT port. EtherNet/IP-based blocks cannot be supported via our EtherNet/IP integration type. Modbus-based blocks can be supported as a Modbus integration, but data will need to be unpacked by hand.

Device Setup

ifm IoT

ifm master blocks come in different flavors and those that support IoT usually support one other major protocol such as EtherNet/IP or Modbus. These protocols are exposed on different physical ports on the device. Make sure that the IoT port is used to attach the master block to the network.

After the device is physically connected, the device must be configured to assign the IoT port a static IP address on the network. This can be done via ifm’s LR Device software.

The remaining default configuration of the master block should be sufficient. Of note, it’s possible to change the operating modes of the individual sensor ports, and the ports must be in IO-Link mode to function with this integration.

Automatic Configuration

In most cases, an IO-Link integration should be able to fully configure itself, so only an endpoint needs to be supplied. It’s possible to extend or override parts of the configuration, which are covered below under Manual Configuration.

IO-Link is able to configure itself by making use of IO Device Description (IODD) files, which the adapter will automatically try to get from the MachineMetrics API after determining which sensors are connected. If the adapter is unable to find or parse the IODD files, then data items for the affected sensors will not appear, and they will need to be manually configured.

Data items

Automatically-configured sensors will produce data items that follow a very specific naming convention:

iolink_p<n>_<vendorid>_<deviceid>_<subindex>_<shortname>

Where:

• <n> is the number of the port the sensor is plugged into (ports start at 1)

• <vendorid> is the vendor id of the sensor

• <deviceid> is the device id of the sensor

• <subindex> is the index of the particular data item within the sensor's process data block (indexes starts at 1)

• <shortname> is a processed, truncated version of the data item's display name, to help identify the data item for mapping

As an example, ifm’s humidity air sensor, which has vendor ID 310 and device ID 1337, would expose the following data values when plugged into the second port on the master block:

• iolink_p2_310_1337_1_humidity

• iolink_p2_310_1337_2_temperature

• iolink_p2_310_1337_3_devicestatus

Scale and unit

Many data items that come through in the process data block require a scale or offset to be properly presented in their normal unit. IODD definitions refer to these factors as gradient and offset. These are not intrinsic properties of the process data itself, but are part of the display definition of the data, which is carried in a different part of the IODD.

One consequence of this setup is that there may be multiple display definitions for the same data item. For example, a device that reports temperature may have two separate definitions to scale the raw temperature value into both Celcius (C) and Fahrenheit (F), with separate UI definition to allow the viewer to pick which one they want to see.

If there are multiple definitions, the adapter will pick the first one.

It’s not currently possible for the adapter to also report the unit of the data, so it is up to the customer or integrator to include the unit in the data item’s display name if needed. This may be made more automatic in the future.

Manual Configuration

IO-Link integrations can be configured with the same information that would normally be fetched automatically through IODD files. An example configuration for the humidity air sensor looks like this:

version: 2
iolink:
  port2:
    process-data:
      humidity:
        bit-offset: 48
        bit-length: 16
        type: int
        gradient: 0.1
      temperature: 
        bit-offset: 16
        bit-length: 16
        type: int
        gradient: 0.1
      status:
        bit-offset: 4
        bit-length: 4
        type: uint
data-items:
  - humidity
  - temperature
  - status

Note that the data items are reported using the names provided in the configuration, not the auto-generated names that come from auto configuration.

Override IODD configuration

Even when a manual configuration is provided, the adapter will attempt to resolve the IODD configuration for the connected sensors. The adapter will try to match any manual definitions with their IODD counterparts by comparing the bit-offset and bit-length values. When a match is found, any data in the manual definition will override the IODD. This will also suppress the auto-generated data item name, and the adapter will export the manually defined name if it’s included in the data-items block, as shown above.

Overriding IODD data items can be useful to exclude them from output, or to replace them with variable definitions that further manipulate their values than what is possible with just gradient and offset.