Allen-Bradley Ethernet/IP

Description

ezvpn-fld-ethernetip is a service (provided as Docker container image) acting as a broker between multiple Ethernet/IP PLC and one MQTT broker, which:

  • read data from Ethernet/IP PLCs and publish to MQTT topics
  • subscribe to MQTT topics and write incoming messages to Ethernet/IP PLCs

This service is certified only on the Rockwell / Allen-Bradley CompactLogix and ControlLogix PLCs series.

Ethernet/IP Field Schema

Using ezvpn-fld-ethernetip allows you to:

  • write to your Ethernet/IP PLC by sending text messages to MQTT.
  • read from your devices by subscribing to MQTT topics.

How to use it

ezvpn-fld-ethernetip is a Docker container image pre-configured for communication with ezvpn-mqtt. In case you need to use it with your MQTT broker, see the section regarding customization below.

If used with ezvpn-mqtt, only one environment variable must be provided: FLD_CFG.

FLD_CFG is a string representing a JSON object, describing the PLC configuration, addresses, polling, subscription, and writable addresses.

This below is a working example representing an oversimplified case with:

  • two machines (extruder and pelletizer)
  • two thermocouples (one on the extruder tempextruder, one on the pelletizer tempdie), read-only
  • one pressure sensor (pressure), read-only
  • one temperature setpoint (tempSP), read-write
{
    "plcs": [
        {
            "name": "extruder",
            "host": "192.168.150.40",
            "slot": 0
        },
        {
            "name": "pelletizer",
            "hosts": "192.168.150.41",
            "slot": 1
        }    ],
    "addresses": [
        {
            "name": "tempextruder",
            "target": "extruder",
            "address": "TEMP[12]"
        },
        {
            "name": "tempdie",
            "target": "pelletizer",
            "address": "TEMP[13]"
        },
        {
            "name": "pressure",
            "target": "pelletizer",
            "address": "PRESSURE[18]"
        },
        {
            "name": "tempSP",
            "target": "extruder",
            "address": "PRESSURE[9]"
        },
        {
            "name": "statusOK",
            "target": "extruder",
            "address": "STATUS[3]",
            "isBitArray": true
        }
    ],
    "pollings": [
        {
            "cron": "0 */10 * * * *",
            "plcs": ["extruder"],
            "sendAlways": true
        },
        {
            "every": "500ms",
            "plcs": ["pelletizer"],
            "sendAlways": false
        }
    ],
    "writables": ["tempSP"]
}

Mapping configuration (FLD_CFG)

The JSON object has 4 array fields:

{
    "plcs": [],
    "addresses": [],
    "pollings": [],
    "writables": []
}

plcs (required): contains the list of the available Ethernet/IP PLC.

addresses (required): contains the list of the available addresses.

pollings (required): contains the list of the polling cycles.

writables (optional): contains the list of the available addresses (each address must be defined in the addresses section).

plcs

plcs is an array of objects, representing the available Ethernet/IP devices. The plcs array cannot be empty.

Each PLC is represented by the following object:

{
    "name": "<plc name>",
    "host": "<plc address or hostname>",
    "slot": <slot>
}

name, host and slot are required.

On CompactLogix, slot is always 0

addresses

addresses is an array of objects, representing the available Ethernet/IP variables. The addresses array cannot be empty.

Each address, if not in the writables array (see below), is treated as read-only. Every attempt to send values to read-only addresses will silently fail.

Each address is represented by the following object:

{
    "name": "<symbolic address name>",
    "target": "<a PLC defined in the plcs section>",
    "address": <Ethernet/IP format>,
    "isBitArray": true|false
}

isBitArray must be set to true if the address is from a bit array. Defaults to false.

For more information, please refer to the Allen-Bradley documentation.

pollings

pollings represents a list of polling cycles on the Ethernet/IP PLCs. At least one polling must be defined.

Each polling has its independent polling frequency and it can span over different PLCs.

This is the structure of a polling object:

{
    "every": "<frequency>",
    "cron": "<frequency time>",
    "timezone": "<timezone>",
    "plcs": [<plcs list>],
    "sendAlways": <polling or subscription>,
    "sendBatch": <batch or single>,
    "disableSingle": <send or not single measurements>
}

The data reading frequency is specified using the alternative every or cron syntax.

every or cron cannot both be defined in the same polling definition, choose which type of polling frequency should be used.

  • every: can be supplied in : human readable time format

  • cron: can be supplied in : cron time format

  • timezone: an optional timezone, see the list, to use for the cron expression. If not defined UTC is used.

  • plcs: is an array of plcs names, in string format

  • sendAlways: is a boolean optional property. If absent or false, only changed values (from previous polling cycles) are sent to MQTT. Otherwise all the values are always sent.

At the first polling cycle, all the values are sent, even if sendAlways is false

sendBatch is a boolean optional property. Defaults to false. If true, all the measurements are sent in aggregated form to the MQTT topic specified on FROM_DEVICE_AGGREGATED_TOPIC_PREFIX environment variable.

The payload is a JSON with 2 properties on default topic aggregate/<protocol>:

{
    "ts": 1612043704952,
    "data": [
        { "address": "tempextruder", "value": 115, "ts": 1612043702457 },
        { "address": "tempdie", "value": 120, "ts": 1612043702457 }
    ]
}
  • ts value is the time at which the payload has been sent.
  • data is an array of all the measures to be sent on each polling cycle. Each array of data is a measurement as sent in single form.

The sendAlways setting affects both the single data and the aggregated data.

disableSingle is a boolean optional property. Defaults to false. If true the measurements are not sent to the MQTT topic specified on TO_DEVICE_TOPIC_PREFIX environment variable.

writables

An array of address names, in string format. Each address on the list can be written.

Environment variables

When you start the ezvpn-fld-ethernetip image, you can adjust the instance's configuration by passing one or more environment variables to the docker run command.

  • FLD_CFG: Ethernet/IP mapping description, as documented above. Required.
  • MQTT_HOST: ip address / host name of the MQTT broker. Defaults to 127.0.0.1 (In IOhubTM the variable is set to ezpn-mqtt value)
  • MQTT_PORT: MQTT broker port. Defaults to 1883.
  • FROM_DEVICE_TOPIC_PREFIX: MQTT topic used to publish values read from devices, defaults to fld/ethernetip/r/.
  • TO_DEVICE_TOPIC_PREFIX: MQTT topic subscribed to get values to write on devices, defaults to fld/ethernetip/w/.
  • FROM_DEVICE_AGGREGATED_TOPIC_PREFIX: MQTT topic use to publish values read from devices, defaults to aggregate/micrologix. Used if sendBatch is set to true.
  • NO_RETAIN: if true values are sent to MQTT_HOST without the retain flag; defaults to false.

With NO_RETAIN set to false, each client that subscribes to a topic pattern receives the retained message immediately after they subscribe.

The broker stores only one retained message per topic.

Examples in EXCH

Read a PLC address

Read an address from the PLC as a 16-bit value and write its value to the key-value DB as Celsius temperature

writeField "db-key-value" "temp" call(f_to_c, ${_v})

Write a value to the PLC

Write a 0-1000 Celsius temperature from the key-value DB to a PLC address, as a 16bit value.

writeField "ethernetip" "setpoint" call(scale, 0, 1000, 0, 65535, db-key-value/temp)

Docker container details

Image: us-central1-docker.pkg.dev/ez-shared/iohub/iohub-fld-ethernetip

Supported architecture: amd64

Changelog

v1.0.6
  • Parallel writes fix
v1.0.5
  • Timezone added in cron expression
v1.0.4
  • Multiple connections fixed
v1.0.3
  • Log fixed
v1.0.2
  • Smaller image
  • Boolean write fix
v1.0.1
  • Cron expression added
v1.0.0
  • First Release