General Concepts

On this page we’ll give a short introduction to the most important concepts that will help you understand Apache PLC4X better.

The most important concepts from a user perspective are in general:

  • Connections — protocols — transports — configuration

  • Addresses

The two parts where we have built abstractions from the real world in PLC4X API are the connection strings and the tag address strings.

Both are pretty dependent on the type of device you are planning to communicate with. However, these can both be easily configured in an external configuration or passed in as arguments.

If you are familiar with JDBC or ODBC, you will easily understand the concepts in PLC4X, as these were a great inspiration for the creation of Apache PLC4X.

Connections

In general a connection is a physical or logical connection between two endpoints.

This connection uses a technical transport mechanism and passes data following a given protocol logic. Therefore, we have modeled both of these aspects separately.

Let’s start with the Transports:

The following transports are currently available, but they will probably be more soon:

  • CAN

  • PCAP replay

  • Raw Socket

  • Serial Port (RS232 and RS485)

  • TCP

  • UDP

  • Test

While TCP, UDP are based on the normal TCP and UDP stack of the operating system, Raw sockets directly provide low-level access to Ethernet Frames. This allows them to not only be used in what we call passive-mode drivers for simply reading all network traffic, it also allows communicating with protocols that are Ethernet based, but don’t use TCP or UDP. This is usually the case with Fieldbus protocols, such as PROFINET or EtherCAT, which usually require lower latency than TCP and UDP can provide.

The Serial Port transport simply reads and writes data to a given serial port.

The probably most special forms of transport are currently the PCAP replay and the Test transport.

The PCAP replay transport allows playing back network traffic packets that were recorded using tools like WireShark. This is really helpful for writing new drivers (especially passive mode drivers) without having to be connected to the real device.

From a driver point of view there is actually no difference between a Raw Socket and a PCAP replay transport.

The Test transport is generally built for being used inside the PLC4X test framework as it allows fine-grained access to the input and output of the drivers. With the test transport we can explicitly control which data is passed into and retrieved from drivers and to validate this in unit- and integration-tests.

Connection Strings

A fully qualified PLC4X connection string would look like this:

{driver code}:{transport code}://{transport config}?{options}

The driver code generally selects the protocol we want to use, the transport code now selects the type of transport that should be used.

Depending on the selected transport mechanism the transport config tells the transport which resource it should use.

For example with a TCP and UDP transport, this will be the IP address or hostname optionally followed by the Port.

For a Serial transport this will be the name of the serial interface. Raw Sockets will require the device name or a MAC address and so on.

For a full description of all transports and their options, please consult the Transport Documentation here.

The last segment - options - can be used to fine tune some protocol or transport options to non-default values. Usually these vary quite a bit from protocol to protocol. For details on these options, please have a look at the Protocol Documentation here. Even if most transports also have common options, their defaults vary quite a bit, depending on the protocol being used. So, instead of having a look at the general Transport Documentation here, wach protocol documentation also contains a list of all supported transports as well as the transport configuration options and their defaults.

The general structure of this part is always the same:

?{option-1-name}={option-1-value}&{option-2-name}={option-2-value}&{option-3-name}={option-3-value}

So the options start with a ? and are then followed by name-value pairs, which are separated by ampersand characters &.

A driver for a given protocol however usually has a default transport, so sometimes it is possible to omit the transport code. Also do most drivers define default values for the various configuration options, so in general you should only require to use configuration options, if you are using non-default settings.

The shortest version of a fully qualified connection string would look something like this:

{driver code}://{transport config}

For more information on the default settings for a given protocol or transport, please check the corresponding drivers documentation.

Individual Resource Addresses (Tags)

Addresses for individual tags on a PLC are extremely dependent on the used protocol. As we usually decided to stick to the address formats that are used in those particular environments, please check the Protocol Documentation on details about these address formats here.

The tag syntax is fairly generic and can be summarized as type:address. Some protocols might support tag attributes which are specified as key-value pairs after primary tag address. For example coil:1{unit-id: 10}. Tag attributes are additional elements which depend on actual protocol.

Tag metadata

Starting from Apache PLC4X release 0.13 an experimental support for result set metadata is provided in plc4j. This metadata is dedicated to provide additional information which might be available at protocol (sample timestamp) or driver level (i.e. packet receive time). Consult again protocol documentation on specifics of this feature.

The common metadata keys currently defined are:

  • timestamp - timestamp for tag value provided by other communication party.

  • timestamp_source - source of timestamp or receive_timestamp field, if any of these is provided.

  • receive_timestamp - timestamp assumed upon receiving of packet with data.