Beckhoff: Write Node

The Beckhoff: Write Node allows you to write new values to one or more symbols on a Beckhoff Automation TwinCAT PLC.

Configuration

Configuration for the Beckhoff: Write 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.

Write Instructions

Next, specify one or more instructions for writing values to Symbols on 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 write a new value to. This property is required; it supports string templates for referencing a symbol name stored on the payload.

• Data Source Method: One of three methods for defining the new value. Options are …

  • String Template: When selected, you must provide a Data Template, which is the value to write as a string template.
  • JSON Template: When selected, you must provide a JSON Template, which is the value to write as a JSON template.
  • Payload Path: When selected, you must provide a Data Payload Path, which is a payload path pointing to where the value to write can be found on the payload.
• Key: The path at which to place the result of this write operation 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. (If a result path is not provided, this setting has no effect.)

Payload Path

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

• name: The symbol name to write to. This property is required.
• data: The value to write to the symbol. This property is required.
• key: The path at which to place the result of this write operation within the node’s returned result. If provided, this must be a valid payload path. If not provided, this defaults to the name property. (If a result path is not provided, this setting has no effect.)

Result

Finally, optionally specify a payload path at which to place the result of the write operations. The value placed at this path will be an object whose properties are the keys / symbol names defined in the write instructions, and whose values, are objects of the form { "success": true|false }.

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 write result is placed at the key test, and a result payload path of working.beckhoffWriteResult, the following is an example of what would be added to the payload …

{
  "working": {
    "beckhoffWriteResult": {
      "test": {
        "success": true
      }
    }
  }
}

Node Errors

If the write 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.beckhoffWriteResult, the following would be placed on the payload if you attempted to write to a symbol noSuchSymbol that did not exist on the PLC …

{
  "working": {
    "beckhoffWriteResult": {
      "noSuchSymbol": {
        "success": false
      },
      "errors": [
        {
          "key": "noSuchSymbol",
          "message": "Writing symbol noSuchSymbol failed: Reading symbol info failed",
          "type": "BECKHOFF_WRITE_ERROR"
        }
      ]
    }
  }
}

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: Write or Beckhoff: Read 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: Write 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: Read Node
• Beckhoff Trigger