beckhoff_ads_hardware_interface for ROS 2

Copyright (c) 2025, b-robotized. All rights reserved. Author: Nikola Banovic

This package provides a ros2_control SystemInterface for communicating with Beckhoff TwinCAT PLCs. It acts as a transport layer, allowing ros2_control controllers to read from and write to PLC variables (e.g., joint states, GPIOs, sensor values) over the network.

The core of this hardware interface is in using ADS Sum-Commands. This allows us to read/write multiple PLC variables in a single network transaction, bringing the total network transactions per update loop to only 2 (one read and one write).

This package is built upon the official beckhoff/ADS library, which handles the low-level ADS protocol communication.

Key Features

• ros2_control Integration: Seamlessly integrate your PLC application with the ros2_control framework.
• Efficient Communication: Utilizes ADS Sum-Commands to bundle multiple variable requests, ensuring high-performance communication suitable for real-time control loops.
• URDF-Based Configuration: All hardware connections and variable mappings are configured directly within your robot’s URDF file.

Requirements

• ROS 2 (Jazzy Jalisco or newer recommended)
• ads_vendor package

Configuration

Configuration is managed entirely within the <ros2_control> tag of your robot’s URDF file. You must specify the PLC connection parameters and map each hardware interface (state or command) to a specific variable on the PLC.

1. Hardware Parameters

These parameters define the connection to the target PLC.

2. Interface Parameters

For each <state_interface> and <command_interface>, you must provide parameters that link it to a PLC variable.

Supported PLC Types

The following PLC data types are supported and are automatically converted to and from double values.

• LREAL, REAL
• BOOL
• DINT, UDINT
• INT, UINT
• SINT, USINT
• BYTE

Example Project

[In this accompanying package]is an example of how to configure the hardware interface in a URDF file for a 6-axis robot and a digital output. Here we also provide a sample PLC project with this hardware interface, along with an example URDF

1. Set up the PLC Project

First, load and compile the sample PLC project in your TwinCAT XAE environment. TwinCAT XAE is available for non-commercial use with a trial license

1. Import the PLC Project: Import the from the PLC-TestProject directory.
2. Import the Library: The PLC program requires the tc3_interfaces library provided with the project. In the Solution Explorer, right-click on References, select Add Library, and add the provided .compiled-library file. This will allow the program to compile successfully.

2. Configure TwinCAT Networking

For ADS communication to work, your TwinCAT system needs a static IP and a route to the ROS 2 machine.

1. Set a Static IP: Assign a static IP address to the network adapter on your Windows machine that you’ll use for ADS. This IP must match the plc_ip_address in your URDF.
2. Configure Firewall: Ensure your Windows firewall allows traffic on the ADS port (TCP 851 is the default) or is disabled on the private network for testing. Verify connectivity by pinging the Windows machine from the ROS 2 host.
3. Set Local AMS Net ID: In the TwinCAT systray icon, go to Router -> Change AMS NetID… and set it to match the plc_ams_net_id in your URDF. Restart TwinCAT when prompted. This is the address of your virtual PLC device.
4. Add Static Route: In your project’s SYSTEM -> Routes tab, add a Static route that points to your ROS 2 machine.
   • AMS Net ID: local_ams_net_id from the URDF.
   • IP Address: The IP address of the machine running the ROS 2 hardware interface.

3. Run the PLC Program

1. Activate Configuration: Click the “Activate Configuration” button in the toolbar to download the hardware setup to the runtime.
2. Login and Run: Select the PLC project, click Login to download the program, and then click Start to run it. The TwinCAT icon in the systray should turn green.

4. Run the Hardware Interface

With the PLC running and waiting for a connection, launch the ros2_control system.

A successful connection will produce log output similar to this, showing the interface linking to the PLC symbols and establishing communication:

``` [controller_manager]: Loading hardware ‘beckhoff_bot’ [BeckhoffADSHardwareInterface]: Exporting state interfaces… [BeckhoffADSHardwareInterface]: sensor ‘robot_sensor/currentPos_0’ | hw_states_[2] <– MAIN.currentPos[0] … [BeckhoffADSHardwareInterface]: Exporting command interfaces… [BeckhoffADSHardwareInterface]: gpio ‘robot_io/joggingEnabled’ | hw_commands_[0] –> MAIN.joggingEnabled

File truncated at 100 lines see the full file