In PLC4X the URL philosophy is used as the data source for the connection for the specification of the driver and its connection parameters, this is almost a standard in network applications (pointing to the best practices). It is also possible to create an instance of the driver directly and assign its parameters with the typical "set" methods.

The specified URL has the structure

The SCHEMA and DOMAINE NAME are almost standard for any URL and do not require further explanation. The PARAMETERS that define the behavior of the driver are defined in the following table.

After defining the URL, the connection is made. Driver selection from the URL is done via PLC4X’s SPI support, so driver instantiation and mapping originating from the URL is done transparently by the Java SPI services.

Any inconsistency in the URL definition will generate an exception that must be handled by the user program.

In (2.1) the driver instance is created, you only have to ensure that the required driver is in the CLASSPATH of your Java environment. Already in (2.2) it defines the type of service required (read/write or a subscription), here a read request is indicated.

No problems? Then we are ready to configure and request the data that we require from the PLC. Let’s go to step "three".

By having the connection we can start building and executing our requests.

In (3.1) the request for a PLCTag is constructed, in this particular case a list of controller system status. In step (3.2) we build the request and in (3.3) we execute the request using the futures pattern in Java. We verify in (3.4) that everything is fine and that our data was acquired.

These steps are shown separately for ease of analysis, but can be simplified into one statement to avoid excessive code.

A detailed explanation of the format for addressing PLCTags in the S7 driver will be given in the following sections.

In general all S7 addresses have this format:

If the array-part is omitted, the size-default of 1 is assumed.

Generally there are two types of addresses:

Bit addresses are only used if the datatype: BOOL is used.

The array notation of these can be omitted. In this case a Count of 1 is used per default.

Start-Byte-Address and Bit-Offset in above list both represent unsigned integer values.

In case of accessing data in the data block memory area, the syntax is quite a bit more complex:

When reading a STRING datatype, currently 254 characters would automatically be fetched from the PLC.

In order to limit the amount of data, we extended the STRING type declaration syntax to allow limiting this.

With the following format less than 254 characters can be read:

These addresses can usually be copied directly out of TIA portal. However we also implemented a shorter version, as above version does have some unnecesary boilerplate parts (The .DB in the middle as well as the Short-Data-Type-Code)

The shorter syntax looks like this:

The S7 driver will handle both types of notation equally.

The S7 driver currently allows access to the following memory areas.

The Code column represents the code that is used in above general address syntax:

Not all S7 device types support the same full set of memory areas, so the last column gives more information on which types a given memory area is supported on.

The S7 driver allows the subscription to asynchronous events generated in the PLC.

This type of event is generated by S7-300, S7-400, G120C-PN, S120-PN controllers and VIPA devices. Unfortunately for the S7-1200 and S7-1500 series this functionality has been superseded.

These services have the following advantages:

The messages are classified into two groups depending on how they are generated:

The data associated with the events is represented in a HashMap in order to facilitate its transfer to other applications based on a standard such as JMS, MQTT or other messaging technology.

The handling of the TimeStamp of the SCAN type events is generated in the computer. In ALARM type messages the TimeStamps are generated in the PLC. It is extremely important that the date and time synchronization is done between both computers and PLC.

The values associated with the events can have different types of representation, so their interpretation must be agreed upon during the programming of the application in the PLC and your application.

For each type of event, the particular fields of type <String, T> will be arranged within the Map. These will be documented for each type of event.

To maximize the use of the data fields associated with the events, the use of the intra-area pointer system and the ANY type pointer is recommended in the PLC, As well as the recommendations for the management of the time stamp [2].

At the user application level App, you can use the PLC4X API to subscribe SCAN or ALARM type events by selecting any of the following fields according to the requirement:

In the following sections we will describe in more detail the functionalities of each field.

By subscribing to controller status changes or MODE events, the PLC status changes can be tracked.

Depending on the CPU model, these state changes are followed in the user application (PLC program), OB100 and OB101, allowing these applications to be brought to a safe state.

Now, how do these state changes affect external applications, for example HMI or custom user applications?

In the use of a unified Siemens architecture, the operator panels (HMI) and WinCC (Scada) detect the status of the CPU and pass the quality of the points in the database in real time to poor quality.

In the case of an application developed with PLC4X, the use of MODE events will allow your application to indicate to users the quality of the points used, and that by design the quality is not updated in the controller.

From image 2, we can describe the sequence of actions that can be followed for subscription. In the first place, the subscription process occurs from the App of the user (1)(2)(3)(4), having a positive response the application is ready to receive the events asynchronously from the PLC (AS).

Suppose that the manager for a reason passes the controller to STOP (06) through the front switch or from the engineering station, then OS proceeds to send a notification (07)(08) to all consoles that are registered to receive this event.

Subsequently, the manager decides to switch the controller to execution mode, through the front switch or the engineering console, at this time the OS is in charge of generating the startup events, initially it indicates the hot start WARN_RESTART (09)(10)(11) and if the startup is successful, indicate that the controller is in execution mode or RUN (12)(13)(14).

The information received in (08)(11)(14) is included in the attached table.

With the sequence diagram and the data structures that will be received by the application, we can analyze the Java code for this specific function. We think this should serve as a pseudocode for the other languages.

System events allow to receive asynchronously any event that affects the operation of the controller, or any of its peripheral equipment that is capable of sending events through a PROFIBUS or Profinet fieldbus.

A first example of its use is the change of state of a CP, IM or FM within the architecture of the controller. This will allow the application to indicate that there is an effect on the system that may affect the quality of the signals used, allowing preventive or corrective actions to be taken as required.

In general, system and user events are part of the same group of events, but they are differentiated to facilitate their processing.

From the sequence diagrams after subscribing to the required event type (01)(02)(03)(04), the consumer (05) is registered to start receiving the events either from the SYS system or from the user USR.

When the event is generated, it is sent to the diagnostic buffer (06) and an image of it is sent to all consoles registered to receive this type of event (07) distributed by the OS (08).

Since at the protocol level the events are not differentiated, the PLC4X driver (08) is in charge of classifying the events in SYS or USR and transferring them to the registered consumer (09).

The following table shows the fields available for each message.

For SYS events, the EVENT_ID is generated automatically by the OS, and basically they are constant in the different families of controllers.

For the USER or User-defined events follow the same pattern as system events. They have the particularity that the value of EVENT_ID must be between the values 0xAXXX and 0xBYYY.

This programming of the user-defined events is carried out at the level of the PLC(AS) controller, so we recommend the technical note [3] of the Siemens portal.

In the previous table we can see how the event classes are coded, and how they are classified. If you require detailed information on each event, the user’s App must interpret the indicated bits.

In the INFO1 and INFO2 fields, specific diagnostic information associated with the event is generally attached, or some information that needs to be recorded in the case of user events.

The INFO1 field contains information that can be stored in a word, namely, WORD, INT of ARRAY [0..1] OF CHAR.

The INFO2 field contains information that can be stored in a double word, namely, DWORD, DINT, REAL, TIME, ARRAY [0..3] OF CHAR.

Below is an example code for the subscription of events type SYS.

And below is an example code for the subscription of events type USR.

The Java code shows how to detect the type of event in an event type SYS. In the S7 driver, there is an enum object S7DiagnosticEventId(10) that allows us to identify which internal event of the PLC(AS) generated it and thus, through the interpretation of the INFO1 and INFO2 fields, determine the root cause of the event.

Unlike SYS events, USR events must be interpreted directly by the App application, so they are generally scheduled during the development phase of the S7App application.

By having INFO1 and INFO2 in the S7App program, the user can transfer data associated with events, such as transitions between phases, events of diagnostic routines such as firts-out or the start or end of a batch process, all asynchronously.

The registration sequence for subscription is the typical one carried out so far (01)(02)(03)(04)(05). From that moment on, you can start receiving alarm events asynchronously.

Depending on your application, you can make a request for the currently active alarms in the alarm buffer of the PLC(AS), in this way you can prepare a reception buffer or establish the correct state of a state machine that depends on the Active events in the controller.

You must take into account that when making the request (06), from a few to hundreds of alarms can be stored depending on the complexity of your application and the capacity of the PLC (AS).

In this scenario, the PLC4X driver maintains the dialogue with the OS to receive sequentially (07)(08)(09)(10)(11)(12)(13)(14) the alarms stored on the controller, to later transfer them to the user application App (15).

At the end of the subscription process, it will begin to receive the events generated by the system, such as high precision time signals (16)(17)(18)(19) or events generated by the user application (20)(21)(22).

This simple sequence of events is used by process applications based on PCS7, for the handling of alarms, events and logging of practically all the events of the distributed control system (DCS).

Another important feature of the driver is the ability to recognize the alarms generated from the PLC(AS). In (23)(24)(25) the S7App application generates an alarm/event that is required to be acknowledged by the user to continue with the execution of a specific routine. The user applications App generates the acknowledgment (27)(28) using the corresponding alarm identifier, the OS is responsible for making the confirmation (29)(30) and asynchronously generating an event for the update of the state machine in the App(31)(32).

Within the cyclical execution of the application S7App waits for the confirmation of the alarm (26) to continue with some specific routine.

TODO: Field description

TODO: Example code

The cyclical subscription allows the acquisition of data in passive mode, that is, the data is sent from the PLC in a cyclical and synchronous way.

The data transfer has three time bases:

The system status list gives access to the operating data of the PLC, such as memory space, operating status, status of the control switches, as well as diagnostic data of expansion cards or decentralized peripherals, PROFIBUS or PROFINET .

This is fundamental data to determine the quality of the data supplied by the PLC.

By initiating the connection with the PLC you can determine its operating status, which will allow you to define the quality of the data taken and what the implemented application can do or not, eventually this is the procedure carried out by the Siemens CPs.

Due to the fact that the data structures are so varied, basically one per type of diagnosis, the decision was made to return these as an array of bytes, leaving the developer to implement the parser according to their requirements.

For a first approach to using system state lists a byte array to JSON notation parser is available at "org.apache.plc4x.java.s7.readwrite.utils.StaticHelper.SZL" .

The access to the SZL of the PLC is done as a read request, where the PLCTag is formed by two fields "SZL_ID" and "INDEX".

The request for the SZL lists follows the same pattern of variable readings, for each request a response, unlike the request for process variables where several can be grouped in a single request, the SZL request must correspond to one request to one petition.

Like other requests, the connection URL (01) is established and the request constructor instance (02) is created. The associated PLCTag is added to the diagnostic list (one per request), in this case the SZL_ID=0x0012 and INDEX=0x0000 (03) which allows obtaining the identification and firmware of the PLC.

In (04) and (05), we prepare and execute the request to the PLC. If we have a valid response (06) we can perform the processing of the data stream obtained, which as indicated is an array of bytes which is obtained in (07) and (08).

As we pointed out in the support libraries, we have an "SZL" object (an enum), which allows us to select the appropriate parser based on the numerical index SLZ_ID (09). In (10) we make a wrapper in a ByteBuf type (from the Netty library) in order to pass it to the "szl" instance through the "execute" method (11).

When processing the data buffer we must obtain in (12) a StringBuilder with the JSON representation.

As noted above, the parser performed on the SZL enum is not complete, so the missing information must be obtained from the returned fields. For further details you should consult [].

In case of not being able to process the request, it is detected in (13) to take the necessary measures.

The following diagram represents the information in JSON format.

From the obtained StringBuilder, you can use the JSON processor of your choice to access the different fields.

Especially when it comes to the input- and output addresses for analog channels, the start addresses are configurable and hereby don’t always start at the same address. In order to find out what addresses these ports have, please go to the device setting of your PLC in TIA Portal

Especially pay attention to this part:

In above image you can see that this device has 8 digital inputs (DI 8) and 2 analog inputs (AI 2_1) as well as 6 digital outputs (DQ 6).

The start addresses of the digital inputs and outputs start directly at 0.

The analog inputs however start at address 64.

Each digital input and output can be addresses by a single bit-address (start-address and offset) or can be read in a block by reading a full byte starting at the given start address without providing a bit offset.