Proxus connects to Beckhoff TwinCAT controllers using the native ADS (Automation Device Specification) protocol.
Connection Parameters
Basic Settings
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| Host | string | Yes | - | PLC IP Address |
| Port | int | No | 851 | AMS Port (TwinCAT 3 Runtime 1) |
| PollingInterval | int | No | 1000 | Read cycle interval in milliseconds |
| ConnectTimeout | int | No | 3000 | Connection timeout (ms) |
Optimization & Behavior
| Parameter | Type | Default | Description |
|---|---|---|---|
| UseTagCache | bool | true | Caches tag handles to improve read/write performance. Disable only if tags change dynamically at runtime. |
| UseAutoAmsNetid | bool | true | Automatically formats the AMS Net ID as IP.1.1. Set to false if using custom routing. |
Advanced Routing
In complex network topologies (e.g., NAT, Docker containers) or when automatic route discovery fails, you may need to explicitly define the AMS Net IDs.
| Parameter | Example | Description |
|---|---|---|
| SetTargetAMSNetId | 5.12.82.20.1.1:851 | The full AMS Net ID + Port of the PLC runtime. |
| SetSenderAMSNetId | 192.168.1.50.1.1:35000 | The AMS Net ID Proxus should use to identify itself to the PLC. |
The Sender AMS Net ID must match the IP address of the Proxus Gateway + .1.1 suffix (usually) and must be whitelisted in the TwinCAT Static Routes table on the PLC side.
AMS Port Defaults
The Port parameter corresponds to the AMS Port of the target runtime:
| System | Runtime | Default Port |
|---|---|---|
| TwinCAT 3 | Runtime 1 (PLC) | 851 |
| TwinCAT 3 | Runtime 2 (PLC) | 852 |
| TwinCAT 2 | Runtime 1 (PLC) | 801 |
| TwinCAT 2 | Runtime 2 (PLC) | 811 |
| TwinCAT 2 | Runtime 3 (PLC) | 821 |
| TwinCAT 2 | Runtime 4 (PLC) | 831 |
Before connecting, you must add a static route between the Proxus Server and the Beckhoff PLC.
- Open TwinCAT Static Routes on the PLC.
- Add the IP address of the Proxus Server.
- Set the AMS Net ID of the Proxus Server (usually
ProxusIP.1.1).
Address Syntax
Proxus supports multiple addressing methods for ADS.
1. Tag Name (Symbolic) - Recommended
The easiest way to read data is using the full symbolic name of the variable.
Format: {Scope}.{Variable}
| Location | Example | Description |
|---|---|---|
| Global Variable | GVL.MyCount | Variable in a GVL named "GVL" |
| Main Program | MAIN.bStart | Variable in "MAIN" PRG |
| Struct Member | MAIN.stConfig.fSpeed | Nested structure member |
| Array Element | MAIN.arrData[5] | Array index |
2. Index Group / Offset (Direct)
For absolute memory access or special system services.
Format: I:{IndexGroup}:{IndexOffset}
| Address | Description |
|---|---|
I:0xF020:0 | Read from IndexGroup 0xF020, Offset 0 |
I:61472:0 | Same as above (Decimal: 0xF020 = 61472) |
3. Memory Area (TwinCAT 2 Style)
Legacy memory area access.
Format: {Area}:{Offset}
| Area | Prefix | Description | Example |
|---|---|---|---|
| Input | I | Input Image | I:0, I:100 |
| Output | Q | Output Image | Q:0, Q:50 |
| Memory | M | Internal Flag | M:0, M:200 |
Data Types
Beckhoff data types map directly to Proxus types.
| Proxus Type | IEC 61131-3 Type | Size |
|---|---|---|
| Bool | BOOL | 1 bit |
| Short | INT | 16 bit |
| UShort | UINT / WORD | 16 bit |
| Int | DINT | 32 bit |
| UInt | UDINT / DWORD | 32 bit |
| Float | REAL | 32 bit |
| Double | LREAL | 64 bit |
| String | STRING(n) | Variable |
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
| Target Machine Not Found | Missing ADS Route | Add Static Route on PLC side (TwinCAT Router) |
| Target Machine Not Found | Firewall | Allow TCP ports 48898 (ADS) and 8016 |
| Ads Error 1793 | Service not supported | Check if variable name is correct (Case sensitive!) |
| Ads Error 1808 | Symbol not found | Ensure "TPY" file is generated or "Symbol Download" is enabled |
| Connection Refused | Wrong AMS Port | Use 851 for TC3, 801 for TC2 |
Official Resources
- Beckhoff InfoSys: Introduction to ADS (Automation Device Specification)
- Technical Reference: ADS Return Codes / Error List
For data type issues, see Data Type Mismatch. For general connectivity problems, see Gateway Issues.