# Beckhoff ADS is a C++ client for TwinCAT devices on non-Windows hosts

> The Beckhoff ADS library lets a Linux, FreeBSD or TC/BSD program talk to a TwinCAT PLC over TCP/IP without TwinCAT installed, built with meson and tested across a wide compiler matrix. The bundled CMake support is community maintained and may lag behind the meson build.

**Beckhoff/ADS** — Beckhoff protocol to communicate with TwinCAT devices.

- Repository: https://github.com/Beckhoff/ADS
- Stars: 658 · Forks: 230
- Language: C++
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/beckhoff-ads

## A client library for a Windows-centric protocol stack

The ADS library exists because TwinCAT devices are usually engineered from Windows, while the clients that talk to them do not have to run there. The README states its purpose plainly: it is intended to provide easy use as an ADS client application running on non-Windows systems, with FreeBSD and Linux given as examples, to communicate with TwinCAT devices via TCP/IP. That is the whole point of the project, because the natural environment for a PLC is a headless Linux box and the natural environment for the official tooling is a Windows engineering station. The library is C++ and requires a recent compiler with C++14 support, and the source tree shows a mature layout with separate directories for the library itself, several test suites including an object oriented interface test and a reference test, a tool directory for the command line utilities, an example directory, a PLC test project used by the test environment, a documentation directory, and packaging directories for Debian and the repository's own package tooling. It is a vendor project with vendor packaging, not a sketch.

## Meson and ninja are the supported build, and the commands are three lines

The build system is meson with ninja, and the README is explicit that this is what the project builds, tests and ships with, and that it is the system the CI covers across Linux, TC/BSD and the cross compiled targets.

```shell
# clone the repository
git clone https://github.com/Beckhoff/ADS.git
# change into root of the cloned repository
cd ADS
# configure meson to build the library into "build" dir
meson setup build
# let ninja build the library
ninja -C build
```

The tree carries several cross files, for amd64 Linux targeting i686, mips and riscv64, for amd64 Linux targeting win32, and for clang-cl on win32, plus native files for win32, for TC/BSD and for Beckhoff RT Linux. The Makefile at the top of the repository is a thin convenience wrapper around the same tools rather than a second build system: it drives meson setup and ninja, installs the library, the two command line binaries and the man page, and it passes the TwinCAT ADS API include and library paths as meson options. Two separate tools are produced, one that links the ADS API directly and one that uses the TwinCAT router, and the documentation explains that the binaries which use the router have a different naming scheme.

## Two binary families, one for standalone clients and one for router clients

The naming table in the README is short and clarifying. The library, the tool and the example each exist in two builds: AdsLib, adstool and example for the standalone variant, and TcAdsLib, tcadstool and tcexample for the variant that uses the TwinCAT router. The distinction is not cosmetic. A standalone client carries its own ADS implementation and talks to the target directly, which is what you want on a Linux server with no TwinCAT installation. A router client goes through a local AMS router, which is what you want on a machine that has TwinCAT installed and already has routes configured. Building the wrong one for your environment produces a client that cannot find its target, and the fact that the project names them differently is a deliberate guard against that confusion. The example program itself is built in both flavours, with meson native files selecting the router build for TC/BSD and for Beckhoff RT Linux.

## Authorisation means adding an AMS route on the target

Before any client can talk to a controller, it has to be authorised, and the README describes that as adding an AMS route on the TwinCAT target with the relevant tools depending on your environment: TwinCAT Engineering through the SYSTEM tree item, the TwinCAT systray context menu on Windows CE aside, TC2 through the AMS Router remote computers properties followed by a restart, TC3 through the router edit routes screen, the TcAmsRemoteMgr tool for Windows CE devices, and the web interface provided by Beckhoff IPC devices for diagnosis and configuration. A sample route is given, and the fields are worth reading closely because two of them are commonly wrong.

```yaml
  Name:           MyAdsClient
  AMS Net Id:     192.168.0.1.1.1 # NetId of your ADS client, derived from its IP address or set by bhf::ads:SetLocalAdress().
  Address:        192.168.0.1     # Use the IP of the ADS client, which is connected to your TwinCAT target
  Transport Type: TCP/IP
  Remote Route:   None / Server
  Unidirectional: false
  Secure ADS:     false
```

The net id is derived from the client address or set explicitly through the library, the address is the client machine as seen from the target, and the route is a server route so the target can answer. Secure ADS is off in the sample, which is the setting to notice if you are reviewing this for a production network.

## The CMake path exists, and the README tells you not to trust it

The repository ships a CMakeLists.txt, and the README is refreshingly blunt about its status. It says the first suggestion for a project that maintains a CMake build is to move to meson, and that if that is not an option, the CMake file is there for exactly that case. The qualifiers matter: it is described as a community effort rather than a supported second build system, it covers fewer platforms, the CI only exercises it on Linux, and it may lag behind the meson build, with most of its changes coming from outside contributors. The Windows usage is shown with the TwinCAT ADS API location passed in explicitly.

```ps1
# On Windows with TwinCAT installed, from the root of the repository
mkdir build && cd build
# TcAdsDll_ROOT is only needed if the ADS API is installed somewhere
# other than the default location
cmake -DTcAdsDll_ROOT="$env:TWINCAT_ADS_API_ROOT" ..
cmake --build . --config Release --parallel
```

For a team whose tooling is already CMake, this is a workable but unsupported path, and the practical advice is to keep the CMake consumption narrow, to pin a specific commit, and to expect to carry patches when the meson build moves.

## A wide test matrix and vendor packaging, with an MIT licence

The compatibility table in the README is unusually specific, listing the host operating system, the host architecture, the target architecture and the compiler for each configuration tested as of 2026-06-11. The list covers Alpine 3.24 with gcc 15.2.0, Arch Linux with clang 22.1.6 and with gcc 16.1.1, Debian 13 with clang 19.1.7 and with gcc 14.2.0-19 for amd64 targets, Debian 12 with gcc 10.2.1-6 targeting win32, and Debian 13 targeting i686, mips, riscv64 and arm64, plus TC/BSD 14 with clang 19.1.7. The test environment itself is containerised, and the Dockerfile in the repository copies a TwinCAT 3.1 installation and a boot image into the image, which tells you the test suite runs against a real TwinCAT installation rather than a mock. The project also ships Debian packaging, a tcpkg packaging directory, a Makefile, a meson options file and a formatting tool configuration. The licence is MIT, and the releases are versioned with a build suffix, 113.0.33-1 published on 2026-04-27, preceded by 113.0.32-1 in April and 113.0.31-1 in February 2026, with the last push on 2026-09-19.

## Conclusion

Beckhoff ADS is the right choice for a Linux or BSD service that has to read or write PLC data without a Windows host in the loop, and for anyone who needs the same source to build both as a standalone client and as a client that talks through a local TwinCAT router. It is the wrong choice for a project already standardised on CMake, because the README says the first suggestion is to move to meson and describes the CMake path as a community effort that covers fewer platforms and may lag. Verify three things before you build on it: that your compiler provides C++14 support, since the README states a recent compiler with that support is required, that the AMS route you add to the TwinCAT target matches the client address and net id you configure, and that the CI image used for the tests matches the TwinCAT version your target runs, since the test Dockerfile pulls a 3.1 image. The library is MIT licensed, the packages are versioned 113.0.33-1, and the last push was on 2026-09-19.

## FAQ

### What is the Beckhoff ADS library for?

It provides an ADS client implementation for C++ so that applications on non-Windows systems such as Linux and FreeBSD can communicate with TwinCAT devices over TCP/IP. The README notes that a recent compiler with C++14 support is required to build it.

### How do I build the ADS library and the example?

Clone the repository, run meson setup build, and build with ninja -C build. For the example you configure a separate directory with meson example/build example and build it with ninja -C example/build, then run the binary from example/build. Native files are provided for TC/BSD and Beckhoff RT Linux.

### Why does my client fail to connect to the TwinCAT target?

The README requires you to authorise the client by adding an AMS route on the target, with the net id derived from the client address or set explicitly, the address set to the client machine, and the remote route set to None / Server. It also distinguishes the standalone binaries from the ones that use the TwinCAT router.

### Can I use AdsLib from an existing CMake project?

Yes, the repository ships a CMakeLists.txt for that case, but the README describes it as a community effort, not a supported second build system, covering fewer platforms, exercised by CI only on Linux, and liable to lag behind the meson build. The first suggestion given is to move the project to meson.

## Sources

- [Beckhoff/ADS on GitHub](https://github.com/Beckhoff/ADS)
- [Issues](https://github.com/Beckhoff/ADS/issues)
- [License: MIT](https://github.com/Beckhoff/ADS/blob/master/LICENSE)
- [README](https://github.com/Beckhoff/ADS/blob/master/README.md)
- [Releases](https://github.com/Beckhoff/ADS/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/beckhoff-ads