Apache PLC4X Documentation

The Generic CAN driver is a general-purpose driver for implementing basic CAN bus listening or writing scenarios. It allows you to model incoming and outgoing communication using the standard Apache PLC4X API.

Data written to the CAN bus is constructed from fields submitted via a write request builder. Incoming data is transformed based on the fields you have subscribed to.

The PLC4X Server is a relay server that implements the PLC4X proxy protocol. It acts as an intermediary between a client (using the plc4x driver) and a PLC.

Use Case: Use the server when your clients are on a different network than the PLCs (e.g., separated by a firewall or on an isolated OT network). The server sits on the reachable network, opens the native connection to the PLC (using protocols like s7, modbus, ads, opcua, etc.), and forwards reads/writes from the client.

Architecture:

• Client $\rightarrow$ PLC4X Server (via plc4x proxy protocol with TLS + auth)
• PLC4X Server $\rightarrow$ PLC (via native protocol like s7 or modbus)

The Mock Driver uses a connection string syntax of mock:{name-of-the-connection}. This allows you to define and use multiple independent mock devices simultaneously.

Instead of communicating with hardware, the driver forwards all requests to a MockDevice. You provide an implementation of the MockDevice interface to control responses (e.g., returning specific values for reads) and monitor incoming requests (e.g., verifying writes) during testing.

ADS is a device-independent and fieldbus-independent interface used for communication between Beckhoff automation devices running TwinCAT and other devices. It allows for interaction between two ADS devices by defining executable operations, necessary parameters, and return values.

Key components include:

• AMS (Automation Message Specification): Specifies the exchange of ADS data.
• AmsNetId: A major component of the AMS specification used to explicitly address ADS devices in the AMS/ADS package for both source and target devices.

SocketCAN is a Linux-specific method for accessing the CAN bus. When using this transport, Apache PLC4X delegates low-level bus access, arbitration, and coordination to the SocketCAN layer and the underlying OS drivers.

Key technical details:

• Frame Representation: You must program your application against the SocketCAN frame representation rather than raw CAN interfaces.
• Frame Length: SocketCAN frames have a fixed length (e.g., CAN 2.0A always takes 16 bytes).
• Identifiers: Standard CAN frames use 11-bit identifiers, whereas SocketCAN uses 29-bit identifiers and appends flags to the remaining 3 bits.
• Compatibility: This transport has been tested with vcan and gs_usb drivers.

In the S7 driver, system-level events (type SYS) can be identified using the S7DiagnosticEventId enum. This enum allows you to determine which internal event of the PLC(AS) generated the event. By interpreting the INFO1 and INFO2 fields associated with the event, you can determine the root cause.

Note: The S7DiagnosticEventId enum is subject to updates as new CPUs or firmware versions are released.

To access specific data points (tags) on a PLC, you use a tag address string. The syntax is generally type:address.

Some protocols support additional tag attributes specified as key-value pairs in braces following the primary address. For example: coil:1{unit-id: 10}

Because address formats are highly dependent on the specific protocol, you must consult the relevant protocol documentation for the correct syntax.

type:address
// Example with attributes:
coil:1{unit-id: 10}

PLC4C uses specific naming suffixes to manage the lifecycle (allocation and deallocation) of structures.

• Creation: All structures must be instantiated using a function ending in the _create suffix.
• Destruction: All structures must be freed, cleared, or deleted using a function ending in the _destroy suffix.