Beckhoff: Read Node

The Beckhoff: Read Node allows you to read the values of one or more symbols from a Beckhoff Automation TwinCAT PLC.

Configuration

Configuration for the Beckhoff: Read Node is broken up into three sections …

Connection Configuration

First, define the properties needed to establish a connection to the Beckhoff PLC. All of the following properties support string templates.

• Local AMS Net ID Template: A six-octet address of the local device (running the GEA) in the TwinCAT network. This is usually the IP address assigned to the GEA device plus .1.1.
• Local ADS Port Template: The port over which the ADS communication protocol of TwinCAT is exposed. Defaults to 37250.
• Target AMS Net ID Template: A six-octet address of the target ADS device, usually defined on the device itself. Usually it is the IP address of the ADS device plus .1.1.
• Target ADS Port Template: The target runtime ADS port. Defaults to 851.
• Router Host Template: The hostname or IP address of the TwinCAT router.
• Router Port Template: The port over which the TwinCAT router is exposed. Defaults to 48898.
• Timeout Template (ms): The length of time, in milliseconds, to wait for a response before timing out the request. Default is 30000 (30 seconds), or the value of the MAX_EXTERNAL_CALL_TIME environment variable, if set.

Note: TwinCAT routers require defining routes that allow a client device (the GEA) to connect to an ADS device. Failure to complete this setup on the router will cause the GEA connection to fail.

Read Instructions

Next, specify one or more instructions for reading Symbols from the PLC and for placing the result on the payload. The instructions may be provided one of two ways …

Array of Template Strings

If selected, you must provide one or more combinations of the following …

• Symbol Name Template: The symbol name to read. This property is required; it supports string templates for referencing a symbol name stored on the payload.
• Key: The path at which to place this symbol’s value within the node’s returned result. If provided, this must be a valid payload path. If not provided, this defaults to the resolved symbol name.

Payload Path

If selected, you must provide a payload path for where to find the node’s read instructions. The value at the path must be an array of objects, each object having the keys …

• name: The symbol name to read. This property is required.
• key: The path at which to place this symbol’s value within the node’s returned result. If provided, this must be a valid payload path. If not provided, this defaults to the name property.

Result

Finally, specify a payload path at which to place the result of the read operations. The value placed at this path will be an object whose properties are the keys / symbol names defined in the read instructions, and whose values are objects containing the symbol’s value and info about the symbol.

If any errors are encountered when invoking the node, an errors property will be placed on the payload describing the errors.

Node Example

Given a symbol name of GVL_Var.TestDint1 whose result is placed at the key test, and a result payload path of working.beckhoffReadResult, the following is an example of what would be added to the payload …

{
  "working": {
    "beckhoffReadResult": {
      "test": {
        "value": 418,
        "symbol": {
          "name": "GVL_Var.TestDint1",
          "comment": "",
          "type": "DINT",
          "size": 4,
          "indexOffset": 384808,
          "indexGroup": 16448
        }
      }
    }
  }
}

Node Errors

If the read operation resulted in any errors, the result will include an errors property whose value is an array of objects. Each object contains a type and message property describing the error, and optionally a key property if the error pertains to a specific instruction.

For example, given a result payload path of working.beckhoffReadResult and a timeout error when attempting to connect, the following would be placed on the payload …

{
  "working": {
    "beckhoffReadResult": {
      "errors": [
        {
          "message": "Connection to 192.168.5.220:48898 failed (timeout) - No response from router in 5000 ms",
          "type": "BECKHOFF_READ_ERROR"
        }
      ]
    }
  }
}

If some read instructions succeeded but others failed - for example, if a requested symbol does not exist on the PLC - then the result will include the successful reads alongside the errors array. Given two read instructions whose results are placed at the keys testdint and testString, where the symbol for testString is not defined on the device, the following would be placed on the payload …

{
  "working": {
    "beckhoffReadResult": {
      "testdint": {
        "value": 296,
        "symbol": {
          "name": "GVL_Var.TestDint1",
          "comment": "",
          "type": "DINT",
          "size": 4,
          "indexOffset": 384808,
          "indexGroup": 16448
        }
      },
      "errors": [
        {
          "type": "BECKHOFF_READ_ERROR",
          "message": "Reading symbol GVL_Var.testString failed: Reading symbol info failed",
          "key": "testString"
        }
      ]
    }
  }
}

Limitations

There are a couple limitations to consider when using the GEA to interact with a Beckhoff PLC …

Single Client Connection

ADS routers only allow a single connection from a host (i.e. a GEA device), and the Target AMS Net ID is ingrained in the connection configuration. If you have multiple Beckhoff: Read or Beckhoff: Write Nodes across your device’s workflows that connect to the same router but interact with different Target AMS Net IDs, the GEA gets around this limitation by closing the open connection to the ADS router and establishing a new connection with the next target.

However, the Beckhoff Trigger requires a persistent connection to the router as it subscribes to changing values. Therefore, the Beckhoff: Read Node will return an error if the device is running any workflows with a Beckhoff Trigger that connects to the same router but a different Target AMS Net ID.

Serial Operations

Read and write operations occur serially (one after the other) and never in parallel. This means that, if the GEA is requesting multiple Beckhoff read or write operations at the same time across all of the device’s workflows, each operation must wait for the operation before it to complete before it can begin. This can lead to performance issues in high-volume scenarios.

Related Nodes

• Beckhoff: Write Node
• Beckhoff Trigger