The ADS (Automation Device Specification) driver communicates with Beckhoff TwinCAT PLCs and controllers using the ADS protocol over TCP/IP. ADS is the transport layer within the TwinCAT system, enabling data exchange between software modules, PLCs, NCs, and external devices.
The Weble universal gateway ADS driver acts as an ADS client that connects to a Beckhoff controller's AMS router to read and write PLC variables. It supports:
- Symbol-based addressing — access PLC variables by their TwinCAT symbol names (e.g.
%ads:MAIN.Temperature). - Raw addressing — access variables by IndexGroup and IndexOffset for low-level control.
- Automatic symbol import — discover and import all PLC symbols directly from the controller.
- TwinCAT XML import — import variable lists from TwinCAT project export files.
- 19 TwinCAT datatypes — BOOL, BYTE, INT, DINT, REAL, LREAL, STRING, TIME, DATE, and more.
- Change-of-value notifications — the controller pushes updates when variable values change.
- Multiple Beckhoff device presets — optimized settings for BK9050, BC9050, CX8090, CX8091, CX9020.
¶ 1. Getting started
¶ 1.1 Gateway configuration
Create a new gateway and select the ADS driver. The key parameters are:
- Host (AMS router): the IP address of the Beckhoff controller.
- Port (AMS router): the ADS TCP port (default:
48898/ 0xBF02). - Source amsNetId: the AMSNetId of the Weble gateway (typically the gateway's IP extended with
.1.1, e.g.192.168.1.2.1.1). - Target amsNetId: the AMSNetId of the Beckhoff controller (typically the controller's IP extended with
.1.1, e.g.192.168.1.1.1.1). - Target device: select a device preset (
custom,BK9050,BC9050,CX8091,CX8090,CX9020) to auto-configure advanced options.
¶ 1.2 Adding an ADS route on the Beckhoff controller
Before the Weble gateway can connect, an ADS route must be configured on the Beckhoff controller to authorize the gateway as a communication partner. Without this route, the connection will be refused.
¶ Using TwinCAT XAE (Engineering)
- Open TwinCAT XAE (Visual Studio integration) on the engineering PC.
- In the Solution Explorer, navigate to SYSTEM > Routes.
- Right-click on Static Routes and select Add New Route.
- Configure the route:
- Route Name: a descriptive name (e.g.
WebleGateway) - AmsNetId: the AMSNetId of the Weble gateway (the value configured as Source amsNetId in the gateway, e.g.
192.168.1.2.1.1) - Transport Type:
TCP/IP - Address Info: the IP address of the Weble gateway (e.g.
192.168.1.2)
- Route Name: a descriptive name (e.g.
- Click Add Route. If prompted for credentials, enter the administrator password of the controller.
¶ Using TwinCAT System Manager (older TwinCAT 2)
- Open the TwinCAT System Manager on the engineering PC or directly on the controller.
- Navigate to SYSTEM - Configuration > Route Settings > Static Routes.
- Click Add and enter the same parameters as above.
¶ From the controller's web interface (if available)
Some Beckhoff controllers (CX series) offer a web-based configuration interface where routes can be added without TwinCAT Engineering.
¶ Troubleshooting
- Connection refused / timeout: verify that the ADS route exists on the controller, the AMSNetId and IP match exactly, and the ADS TCP port (48898) is not blocked by a firewall.
- AMSNetId mismatch: the Source amsNetId configured on the Weble gateway must match exactly the route entry on the Beckhoff controller. A common convention is to use the device's IP address extended with
.1.1(e.g. IP192.168.1.2→ AMSNetId192.168.1.2.1.1), but it can be any unique 6-byte identifier. - Target port: the AMS target port depends on the PLC runtime. Common values are
801(TC2 PLC Runtime 1),811(TC2 Runtime 2),851(TC3 PLC Runtime 1),852(TC3 Runtime 2).
Once the gateway is started and connected, there are three ways to import PLC variables:
¶ Automatic import from controller
Right-click on the gateway and select Import Symbols. Enter an optional filter (e.g. MAIN) to import only symbols whose comment contains the filter text, or leave empty to import all symbols. The driver reads the symbol table directly from the controller.
¶ TwinCAT XML import
Export your TwinCAT project symbols as XML (PlcProjectInfo format) and import them via right-click > Import > Weble import. The XML file contains symbol names, types, IndexGroup, and IndexOffset.
¶ Manual insertion
Addresses can also be created manually by entering the symbol name or raw IndexGroup/IndexOffset.
¶ 1.3 Using with routes
ADS addresses are routable like any other protocol. Typical use cases:
- Route Beckhoff PLC values to BACnet for building management integration.
- Forward PLC data to MQTT / Cloud for remote monitoring dashboards.
- Write setpoints from Modbus sensors into TwinCAT variables.
¶ 2. Gateway parameters
¶ 2.1 Connection parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this ADS gateway instance. |
| Cluster ID | cluster | Cluster identifier. Use 0 for single-gateway setups. |
| Description | description | Optional description. |
| Target device | targetDevice | Device preset: custom, BK9050, BC9050, CX8091, CX8090, or CX9020. Presets adjust advanced options automatically. |
| Host (AMS router) | host | IP address of the Beckhoff controller / AMS router. |
| Port (AMS router) | port | ADS TCP port. Default: 48898 (0xBF02). |
| Source amsNetId | amsNetIdSource | AMSNetId of this gateway. Typically the gateway's local IP extended with .1.1 (e.g. 192.168.1.2.1.1). |
| Source port | amsPortSource | AMS source port. Default: 32905. |
| Target amsNetId | amsNetIdTarget | AMSNetId of the Beckhoff PLC. Typically the PLC's IP extended with .1.1 (e.g. 192.168.1.1.1.1). |
| Target port | amsPortTarget | AMS target port on the PLC. Default: 801. May vary depending on the controller model. |
¶ 2.2 Advanced parameters
These parameters are visible depending on the selected Target device.
| Label | JSON Key | Description |
|---|---|---|
| Import symbols at startup | readAndCacheSymbols | If enabled, all PLC symbols are imported automatically when the gateway starts. Available for custom, CX8090, CX8091, CX9020. |
| Parralels read | parralelsRead | If enabled, multiple read requests are sent in parallel for faster polling. Default: enabled. |
| Idle timeout | idleTimeout | Pause in milliseconds between sequential read requests (only when parallel read is disabled). Default: 1000. |
| Multiple read | multipleRead | If enabled, multiple variables are read in a single ADS request. Available for custom. |
| Allow half open | allowHalfOpen | Allow the TCP connection to remain half-open. Available for custom. |
| Bare client | bareClient | Use a minimal ADS client without AMS router. Available for custom. |
¶ 2.3 Gateway JSON example
{
"host": "192.168.1.1",
"port": 48898,
"amsNetIdSource": "192.168.1.2.1.1",
"amsPortSource": 32905,
"amsNetIdTarget": "192.168.1.1.1.1",
"amsPortTarget": 801,
"targetDevice": "custom",
"readAndCacheSymbols": true,
"parralelsRead": true,
"multipleRead": true,
"allowHalfOpen": false,
"bareClient": false,
"idleTimeout": 1000
}
¶ 3. Addresses
¶ 3.1 Address tabs
The driver organizes addresses into two tabs:
¶ Symbols
Addresses using TwinCAT symbol names. This is the recommended approach.
- Format:
%ads:<symbolName> - Example:
%ads:MAIN.Temperature,%ads:GVL.bRunning
¶ Raw
Addresses using IndexGroup and IndexOffset for direct memory access.
- Format:
%ads-raw:<indexGroup>-<indexOffset> - Example:
%ads-raw:16448-0,%ads-raw:0x4020-100
IndexGroup can be specified in decimal or hexadecimal (0x prefix).
¶ 3.2 Symbol address parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | The address name (%ads:<symbolName>). |
| Symbol name | name (json) | The TwinCAT symbol name (e.g. MAIN.Temperature). |
| Group index | indexGroup | The ADS IndexGroup (auto-filled when importing symbols). |
| Offset index | indexOffset | The ADS IndexOffset (auto-filled when importing symbols). |
| Type | type | The TwinCAT datatype (see section 3.4). |
| CycleTime | cycleTime | Notification cycle time in milliseconds. The PLC checks the variable at this interval and pushes updates when the value changes. Default: 50 ms. Also supports cron expressions. |
| Description | description | Optional description. |
| Log | log | Logging mode: never, on update, always, or a duration in ms. |
¶ 3.3 Raw address parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | The raw address (%ads-raw:<group>-<offset>). |
| Index group | (from name) | The ADS IndexGroup. |
| Index offset | (from name) | The ADS IndexOffset. |
| Type | type | The TwinCAT datatype. |
| CycleTime ms/cron | cycleTime | Notification/polling cycle time. |
| Description | description | Optional description. |
| Log | log | Logging mode. |
¶ 3.4 Datatypes
| Datatype | Size | Description |
|---|---|---|
BOOL |
1 bit | Boolean (TRUE/FALSE) |
BYTE |
8-bit | Unsigned byte (0-255) |
USINT |
8-bit | Unsigned short integer |
SINT |
8-bit | Signed short integer |
UINT |
16-bit | Unsigned integer |
WORD |
16-bit | Unsigned 16-bit word |
INT |
16-bit | Signed integer |
DWORD |
32-bit | Unsigned 32-bit double word |
UDINT |
32-bit | Unsigned double integer |
DINT |
32-bit | Signed double integer |
REAL |
32-bit | Single-precision float (IEEE 754) |
LREAL |
64-bit | Double-precision float (IEEE 754) |
STRING |
variable | Character string |
TIME |
32-bit | Time duration in milliseconds |
TIME_OF_DAY / TOD |
32-bit | Time of day |
DATE |
32-bit | Date |
DATE_AND_TIME / DT |
32-bit | Date and time combined |
¶ 4. Address properties
| Property | Value |
|---|---|
| Readable | Yes |
| Writable | Yes |
| Routable | Yes |
| Loggable | Yes |