You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by cd...@apache.org on 2020/02/27 17:07:25 UTC

[plc4x] branch develop updated: - Fixed the `loop` feature - Added site documentation - Fixed broken links and duplicates in the tools section of the site

This is an automated email from the ASF dual-hosted git repository.

cdutz pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git


The following commit(s) were added to refs/heads/develop by this push:
     new 5403b89  - Fixed the `loop` feature - Added site documentation - Fixed broken links and duplicates in the tools section of the site
5403b89 is described below

commit 5403b893b3d8ca02c6d857f88b300625b3c2c996
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Thu Feb 27 18:07:18 2020 +0100

    - Fixed the `loop` feature
    - Added site documentation
    - Fixed broken links and duplicates in the tools section of the site
---
 plc4j/tools/capture-replay/pom.xml                 |  11 ++
 .../java/utils/capturereplay/CaptureReplay.java    |  74 ++++-----
 .../plc4x/java/utils/capturereplay/CliOptions.java |  24 ++-
 .../capture-replay/src/main/resources/logback.xml  |  36 +++++
 .../utils/pcapsockets/netty/PcapSocketChannel.java |   8 -
 src/site/asciidoc/users/opm.adoc                   |  73 ---------
 src/site/asciidoc/users/testing.adoc               | 165 ---------------------
 src/site/asciidoc/users/tools/capture-replay.adoc  |  59 ++++++++
 src/site/site.xml                                  |   9 +-
 9 files changed, 168 insertions(+), 291 deletions(-)

diff --git a/plc4j/tools/capture-replay/pom.xml b/plc4j/tools/capture-replay/pom.xml
index 3c8410c..70cff9a 100644
--- a/plc4j/tools/capture-replay/pom.xml
+++ b/plc4j/tools/capture-replay/pom.xml
@@ -74,6 +74,17 @@
     </dependency>
 
     <dependency>
+      <groupId>ch.qos.logback</groupId>
+      <artifactId>logback-classic</artifactId>
+      <scope>compile</scope>
+    </dependency>
+    <dependency>
+      <groupId>ch.qos.logback</groupId>
+      <artifactId>logback-core</artifactId>
+      <scope>compile</scope>
+    </dependency>
+
+    <dependency>
       <groupId>org.pcap4j</groupId>
       <artifactId>pcap4j-core</artifactId>
     </dependency>
diff --git a/plc4j/tools/capture-replay/src/main/java/org/apache/plc4x/java/utils/capturereplay/CaptureReplay.java b/plc4j/tools/capture-replay/src/main/java/org/apache/plc4x/java/utils/capturereplay/CaptureReplay.java
index ffe1371..ac7959f 100644
--- a/plc4j/tools/capture-replay/src/main/java/org/apache/plc4x/java/utils/capturereplay/CaptureReplay.java
+++ b/plc4j/tools/capture-replay/src/main/java/org/apache/plc4x/java/utils/capturereplay/CaptureReplay.java
@@ -52,42 +52,42 @@ public class CaptureReplay {
 
         // Start a thread that processes the callbacks from the raw socket and simply
         // forwards the bytes read to the buffer.
-        Thread loopThread = new Thread(() -> {
-            try {
-                readHandle.loop(-1, new PacketListener() {
-                    private Timestamp lastPacketTime = null;
-
-                    @Override
-                    public void gotPacket(Packet packet) {
-                        Timestamp curPacketTime = readHandle.getTimestamp();
-
-                        // Only enable the throttling if it is not disabled.
-                        // If last-time is not null, wait for the given number of nano-seconds.
-                        if((replaySpeed <= 0) && (lastPacketTime != null)) {
-                            int numMicrosecondsSleep = (int)
-                                ((curPacketTime.getNanos() - lastPacketTime.getNanos()) * replaySpeed);
-                            nanoSecondSleep(numMicrosecondsSleep);
-                        }
-
-                        // Send the packet to the output device ...
-                        try {
-                            sendHandle.sendPacket(packet);
-                        } catch (PcapNativeException | NotOpenException e) {
-                            LOGGER.error("Error sending packet", e);
-                        }
-
-                        // Remember the timestamp of the current packet.
-                        lastPacketTime = curPacketTime;
+        try {
+            readHandle.loop(-1, new PacketListener() {
+                private Timestamp lastPacketTime = null;
+
+                @Override
+                public void gotPacket(Packet packet) {
+                    Timestamp curPacketTime = readHandle.getTimestamp();
+
+                    // Only enable the throttling if it is not disabled.
+                    // If last-time is not null, wait for the given number of nano-seconds.
+                    if ((replaySpeed > 0) && (lastPacketTime != null)) {
+                        int numMicrosecondsSleep = (int)
+                            ((curPacketTime.getNanos() - lastPacketTime.getNanos()) * replaySpeed);
+                        nanoSecondSleep(numMicrosecondsSleep);
+                    }
+
+                    // Send the packet to the output device ...
+                    try {
+                        sendHandle.sendPacket(packet);
+                    } catch (PcapNativeException | NotOpenException e) {
+                        LOGGER.error("Error sending packet", e);
                     }
-                });
-            } catch (PcapNativeException | NotOpenException e) {
-                LOGGER.error("PCAP sending loop thread died!", e);
-            } catch (InterruptedException e) {
-                LOGGER.warn("PCAP sending loop thread was interrupted (hopefully intentionally)", e);
-                Thread.currentThread().interrupt();
-            }
-        });
-        loopThread.start();
+
+                    // Remember the timestamp of the current packet.
+                    lastPacketTime = curPacketTime;
+                }
+            });
+        } catch (PcapNativeException | NotOpenException e) {
+            LOGGER.error("PCAP sending loop thread died!", e);
+        } catch (InterruptedException e) {
+            LOGGER.warn("PCAP sending loop thread was interrupted (hopefully intentionally)", e);
+            Thread.currentThread().interrupt();
+        } finally {
+            readHandle.close();
+            sendHandle.close();
+        }
     }
 
     private void nanoSecondSleep(long numNanos) {
@@ -107,7 +107,9 @@ public class CaptureReplay {
         }
 
         CaptureReplay replay = new CaptureReplay(options);
-        replay.run();
+        do {
+            replay.run();
+        } while (options.isLoop());
     }
 
 }
diff --git a/plc4j/tools/capture-replay/src/main/java/org/apache/plc4x/java/utils/capturereplay/CliOptions.java b/plc4j/tools/capture-replay/src/main/java/org/apache/plc4x/java/utils/capturereplay/CliOptions.java
index 2267051..97aa308 100644
--- a/plc4j/tools/capture-replay/src/main/java/org/apache/plc4x/java/utils/capturereplay/CliOptions.java
+++ b/plc4j/tools/capture-replay/src/main/java/org/apache/plc4x/java/utils/capturereplay/CliOptions.java
@@ -28,12 +28,14 @@ public class CliOptions {
     private static final String OPTION_INPUT_FILE = "input-file";
     private static final String OPTION_OUTPUT_DEVICE = "output-device";
     private static final String OPTION_REPLAY_SPEED = "replay-speed";
+    private static final String OPTION_LOOP = "loop";
 
     private static Options options;
 
     private final File inputFile;
     private final String outputDevice;
     private final float replaySpeed;
+    private final boolean loop;
 
     public static CliOptions fromArgs(String[] args) {
         options = new Options();
@@ -56,11 +58,18 @@ public class CliOptions {
                 .build());
         options.addOption(
             Option.builder()
-                .type(String.class)
+                .type(Float.class)
                 .longOpt(OPTION_REPLAY_SPEED)
                 .hasArgs()
                 .desc("Replay speed (1 = real time, 0 = as fast as possible, 0.5 = half speed, 2 = double speed")
                 .build());
+        options.addOption(
+            Option.builder()
+                .type(Boolean.class)
+                .longOpt(OPTION_LOOP)
+                .hasArgs()
+                .desc("If set to TRUE it will start sending the packets as soon as it reaches the end")
+                .build());
 
         CommandLineParser parser = new DefaultParser();
         CommandLine commandLine;
@@ -69,10 +78,10 @@ public class CliOptions {
 
             File inputFile = new File(commandLine.getOptionValue(OPTION_INPUT_FILE));
             String outputDevice = commandLine.getOptionValue(OPTION_OUTPUT_DEVICE);
-            float replaySpeed = Float.parseFloat(
-                commandLine.hasOption(OPTION_REPLAY_SPEED) ? commandLine.getOptionValue(OPTION_REPLAY_SPEED) : "1");
+            float replaySpeed = Float.parseFloat(commandLine.getOptionValue(OPTION_REPLAY_SPEED, "1"));
+            boolean loop = Boolean.parseBoolean(commandLine.getOptionValue(OPTION_LOOP, "false"));
 
-            return new CliOptions(inputFile, outputDevice, replaySpeed);
+            return new CliOptions(inputFile, outputDevice, replaySpeed, loop);
         } catch (ParseException e) {
             System.err.println(e.getMessage());
             return null;
@@ -84,10 +93,11 @@ public class CliOptions {
         formatter.printHelp("CaptureReplay", options);
     }
 
-    public CliOptions(File inputFile, String outputDevice, float replaySpeed) {
+    public CliOptions(File inputFile, String outputDevice, float replaySpeed, boolean loop) {
         this.inputFile = inputFile;
         this.outputDevice = outputDevice;
         this.replaySpeed = replaySpeed;
+        this.loop = loop;
     }
 
     public File getInputFile() {
@@ -102,4 +112,8 @@ public class CliOptions {
         return replaySpeed;
     }
 
+    public boolean isLoop() {
+        return loop;
+    }
+
 }
diff --git a/plc4j/tools/capture-replay/src/main/resources/logback.xml b/plc4j/tools/capture-replay/src/main/resources/logback.xml
new file mode 100644
index 0000000..a8ddebb
--- /dev/null
+++ b/plc4j/tools/capture-replay/src/main/resources/logback.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+-->
+<configuration xmlns="http://ch.qos.logback/xml/ns/logback"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:schemaLocation="http://ch.qos.logback/xml/ns/logback https://raw.githubusercontent.com/enricopulatzo/logback-XSD/master/src/main/xsd/logback.xsd">
+
+  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+    <!-- encoders are assigned the type
+         ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
+    <encoder>
+      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+    </encoder>
+  </appender>
+
+  <root level="trace">
+    <appender-ref ref="STDOUT" />
+  </root>
+
+</configuration>
\ No newline at end of file
diff --git a/plc4j/utils/pcap-sockets/src/main/java/org/apache/plc4x/java/utils/pcapsockets/netty/PcapSocketChannel.java b/plc4j/utils/pcap-sockets/src/main/java/org/apache/plc4x/java/utils/pcapsockets/netty/PcapSocketChannel.java
index 2391575..fcb8daa 100644
--- a/plc4j/utils/pcap-sockets/src/main/java/org/apache/plc4x/java/utils/pcapsockets/netty/PcapSocketChannel.java
+++ b/plc4j/utils/pcap-sockets/src/main/java/org/apache/plc4x/java/utils/pcapsockets/netty/PcapSocketChannel.java
@@ -204,14 +204,6 @@ public class PcapSocketChannel extends OioByteStreamChannel {
         return new RawSocketUnsafe();
     }
 
-    /**
-     * Use a busy wait loop for waiting. This should never be used in a
-     * production environment as it consumes 100% of one CPU core time to
-     * achieve, however it's the only accurate way to sleep for less than
-     * a millisecond.
-     *
-     * @param numNanos number of nano-seconds to wait.
-     */
     private void nanoSecondSleep(long numNanos) {
         try {
             TimeUnit.NANOSECONDS.sleep(numNanos);
diff --git a/src/site/asciidoc/users/opm.adoc b/src/site/asciidoc/users/opm.adoc
deleted file mode 100644
index e41c3c3..0000000
--- a/src/site/asciidoc/users/opm.adoc
+++ /dev/null
@@ -1,73 +0,0 @@
-//
-//  Licensed to the Apache Software Foundation (ASF) under one or more
-//  contributor license agreements.  See the NOTICE file distributed with
-//  this work for additional information regarding copyright ownership.
-//  The ASF licenses this file to You under the Apache License, Version 2.0
-//  (the "License"); you may not use this file except in compliance with
-//  the License.  You may obtain a copy of the License at
-//
-//      http://www.apache.org/licenses/LICENSE-2.0
-//
-//  Unless required by applicable law or agreed to in writing, software
-//  distributed under the License is distributed on an "AS IS" BASIS,
-//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-//  See the License for the specific language governing permissions and
-//  limitations under the License.
-//
-
-== Object PLC Mapping
-
-
-=== What is Object PLC Mapping
-
-Object PLC Mapping (OPM) is heavily inspired by the Java Persistence API (JPA) [1].
-One of the main goal of the PLC4X Project is to make it easy to communicate with PLC devices to enable the development
-of applications that interact with PLCs.
-As many (or even most) of the application programmers are no experts in PLC Communication and protocols it should be as
-easy as possible to interact with PLCs without too much domain knowledge.
-This is exactly the reason why JPA was initialized many years ago to allow the interaction with a Database by simply
-calling methods on POJOs (Plain old Java Object).
-This is exactly what the OPM Module is for, to enable PLC communication by simply interacting with a POJO.
-
-=== Simple Example
-
-The following short code snippet shows how to read one value from a PLC via OPM.
-First, a _PlcEntityManager_ is instantiated, then a *connected* entity is fetched for a given PLC connection address.
-Connected means that all method calls of the entity are intersected and replaced by PLC calls.
-This is then used to print one value to the console.
-In the second snippet one can see how the Entity class looks. The address where to read the variable _pressure_ from is given
-in the _@PlcField_ annotation.
-[source,java]
-----
-public static void main(String[] args) {
-    PlcEntityManager em = new PlcEntityManager();
-    MyEntity entity = em.connect(MyEntity.class, "s7://...");
-    System.out.println(entity.getPressure());
-}
-----
-The class _MyEntity_ is given by
-[source,java]
-----
-@PlcEntity
-public class MyEntity {
-
-    @PlcField("DB01:DW01:LONG")
-    private double pressure;
-
-    public void MyEntity() {
-        // For OPM
-    }
-
-    public double getPressure() {
-        return pressure;
-    }
-}
-----
-
-=== Annotations
-
-=== More details
-
-=== References
-
-[1] https://www.oracle.com/technetwork/java/javaee/tech/persistence-jsp-140049.html
\ No newline at end of file
diff --git a/src/site/asciidoc/users/testing.adoc b/src/site/asciidoc/users/testing.adoc
deleted file mode 100644
index 55dde26..0000000
--- a/src/site/asciidoc/users/testing.adoc
+++ /dev/null
@@ -1,165 +0,0 @@
-//
-//  Licensed to the Apache Software Foundation (ASF) under one or more
-//  contributor license agreements.  See the NOTICE file distributed with
-//  this work for additional information regarding copyright ownership.
-//  The ASF licenses this file to You under the Apache License, Version 2.0
-//  (the "License"); you may not use this file except in compliance with
-//  the License.  You may obtain a copy of the License at
-//
-//      http://www.apache.org/licenses/LICENSE-2.0
-//
-//  Unless required by applicable law or agreed to in writing, software
-//  distributed under the License is distributed on an "AS IS" BASIS,
-//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-//  See the License for the specific language governing permissions and
-//  limitations under the License.
-//
-
-== Testing (or using PLC4X without a PLC)
-
-=== The Mock Driver
-
-PLC4X has a _Mock Driver_ which was initially implemented to be used for Unit Tests and this still is its main purpose.
-But this driver is also very suitable to play around a bit with the PLC4X API if no _Hardware_ PLC is available.
-The driver can be found in the Maven module
-
-```
-<dependency>
-  <groupId>org.apache.plc4x</groupId>
-  <artifactId>plc4j-transport-test</artifactId>
-  <version>${current.version}</version>
-  <scope>test</scope>
-</dependency>
-```
-
-The connection string Syntax for the mock driver is `mock:{name-of-the-connection}`. So you can use multiple Mock Devices at the same time.
-
-The Mock Driver does nothing else than forwarding all Requests to a _Virtual Device_ which we can provide to control all responses and also Monitor them, e.g. for unit tests.
-The Interface for the Mock Device is
-
-```
-public interface MockDevice {
-
-    Pair<PlcResponseCode, PlcValue> read(String fieldQuery);
-
-    PlcResponseCode write(String fieldQuery, Object value);
-
-    Pair<PlcResponseCode, PlcSubscriptionHandle> subscribe(String fieldQuery);
-
-    void unsubscribe();
-
-    // ...
-
-}
-```
-
-=== Simple Example
-
-Imagine we have some Code which we cannot control or whose functionality we want to test.
-This can be done with the Mock Driver in the following way.
-
-First, a new Mock Connection is established (like any other connection also would be):
-```
-PlcDriverManager driverManager = new PlcDriverManager();
-PlcMockConnection connection = (PlcMockConnection) driverManager.getConnection("mock:my-mock-connection");
-```
-You see, that we directly cast the Connection to a `PlcMockConnection`. This is done, because we need to _connect_ a Device to this Mock Connection.
-
-This is done in the following Snippet
-```
-connection.setDevice(mockDevice);
-```
-Here, we pass it an instance of `MockDevice` which could be a simple Implementation of the interface like
-```
-MockDevice mockDevice = new MockDevice() {
-
-    Pair<PlcResponseCode, PlcValue> read(String fieldQuery) {
-        System.out.println("I got a read to " + fieldQuery);
-        return Pair.of(PlcResponseCode.OK, new PlcString("hello"));
-    }
-
-    PlcResponseCode write(String fieldQuery, Object value) {
-        System.out.println("I got a write to " + fieldQuery + " with the value " + value);
-        return PlcResponseCode.OK;
-    }
-
-    // ...
-
-}
-```
-This would just return a String Value `hello` for every request and print all read and write requests to the Console.
-
-=== Unit Testing with the Mock Driver
-
-To use the Mock driver in Unit Tests the easiest way is to generate the `MockDriver` instance as Mockito (or any other Framework) Mock.
-Like in the following Example
-
-```
-MockDevice mockDevice = Mockito.mock(MockDevice.class);
-
-PlcDriverManager driverManager = new PlcDriverManager();
-PlcMockConnection connection = (PlcMockConnection) driverManager.getConnection("mock:my-mock-connection");
-connection.setDevice(mockDevice);
-
-// Populate the Mock to avoid a NPE
-when(mockDevice).read(anyString()).thenReturn(Pair.of(PlcResponseCode.OK, new PlcString("hello")));
-
-// Some Demo code that uses the same Driver Manager and either the connection from above
-// or at least mock:my-mock-connection as connection string
-// Here: send a request to the field "MyAdress"
-connection
-    .readRequestBuilder
-    .addItem("station", "MyAdress")
-    .build()
-    .execute()
-    .get();
-
-// Check that the we really issued a Read request to the Field "MyAdress"
-verify(mockDevice).read(eq("MyAdress"));
-```
-
-But as the _MockDriver_ uses a static Mock Connection registry the following Code works also
-
-```
-MockDevice mockDevice = Mockito.mock(MockDevice.class);
-
-// Setup
-PlcDriverManager driverManager = new PlcDriverManager();
-PlcMockConnection connection = (PlcMockConnection) driverManager.getConnection("mock:my-mock-connection");
-connection.setDevice(mockDevice);
-// Populate the Mock to avoid a NPE
-when(mockDevice).read(anyString()).thenReturn(Pair.of(PlcResponseCode.OK, new PlcString("hello")));
-
-// Some Demo code that uses the same Driver Manager and either the connection from above
-// or at least mock:my-mock-connection as connection string
-// Here: send a request to the field "MyAdress"
-// and we build up a new Connection
-try (PlcConnection conn = driverManager.getConnection("mock:my-mock-connection")) {
-    conn
-        .readRequestBuilder
-        .addItem("station", "MyAdress")
-        .build()
-        .execute()
-        .get();
-} catch (Exception e) {
-    // do nothing
-}
-
-// Check that the we really issued a Read request to the Field "MyAdress"
-verify(mockDevice).read(eq("MyAdress"));
-```
-
-The Snippet above shows that the part under test really has to share nothing with the test code except for the connection string.
-
-=== Conclusion
-
-The above examples show that the `MockDriver` driver can not only be used to play around with the API but is also a powerful tool to
-do unit testing of Code which uses the PLC4X API.
-All that needs to be done is to either pass an instance of the Mocked Connection or just use the same Connection string (e.g. from a test configuration) that was used to Prepare a Mock Device.
-Some Examples of futher (more Complex) use cases can be found in the PLC4X Codebases, e.g. in the following classes
-
-* `org.apache.plc4x.java.opm.PlcEntityManagerTest`
-* `org.apache.plc4x.java.opm.PlcEntityManagerComplexTest`
-* `org.apache.plc4x.java.scraper.ScraperTest`
-
-and many more Test classes, especially in the OPM and the Scraper Module.
\ No newline at end of file
diff --git a/src/site/asciidoc/users/tools/capture-replay.adoc b/src/site/asciidoc/users/tools/capture-replay.adoc
new file mode 100644
index 0000000..a99b1a9
--- /dev/null
+++ b/src/site/asciidoc/users/tools/capture-replay.adoc
@@ -0,0 +1,59 @@
+//
+//  Licensed to the Apache Software Foundation (ASF) under one or more
+//  contributor license agreements.  See the NOTICE file distributed with
+//  this work for additional information regarding copyright ownership.
+//  The ASF licenses this file to You under the Apache License, Version 2.0
+//  (the "License"); you may not use this file except in compliance with
+//  the License.  You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+== Capture Replay
+
+Some times the problem with industry protocols is, that the most interesting protocols live in places that are not very welcoming to IT folks.
+
+Either too hot or too cold and usually no good coffee around.
+
+The `Capture Replay` tool is a little helper, that can possibly help with this.
+
+Especially when it comes to developing passive mode drivers this tool can come in very handy.
+
+It allows to replay recorded network traffic and to directly intercept this traffic in any passive mode drivers.
+
+Possibly it could also work with non passive drivers, but I expect synchronization to be tricky.
+
+=== Getting a Capture
+
+In order to create a capture I usually connect a device running `WireShark` to the network.
+
+Ideally to the replication port of a network switch so I can record all the traffic.
+
+An alternative would be to run `WireShark` on one of the PCs/Servers having access to the traffic I'm interested in.
+So if for example I wanted to work on a driver for control system `X`, capturing the traffic on one of the `X` servers is probably the simplest way to do it.
+If complicance rules prevent ths a third option would be to use a network tap to record the capture.
+
+=== Replaying the Capture
+
+Now you need to copy the `pcapng` file ideally to your development system.
+
+The capture can be replayed by the tool you find in `plc4j/tools/capture-replay`.
+
+Here simply look for the `target/plc4j-capture-replay-{current-last-released-version}-uber-jar.jar` and run:
+
+   java -jar target/plc4j-capture-replay-{current-last-released-version}-uber-jar.jar --input-file {path to capture} --output-device {name of the network device} --replay-speed 1 --loop true
+
+The options `input-file` and `output-device` are mandatory, the rest is optional:
+
+- `input-file` specifies the path to the capture file (pcapng)
+- `output-device` name of the network device that will be used for output (name listed when running `ifconfig` on Linux and Mac or `ipconfig` on Windows)
+- `replay-speed` Speed the replay will be played back. 1 is real time, 0 or less is `as fast as possible`, 0.5 is 50% slower than the original and 2 is twice as fast
+- `loop` if set to true it will automatically start replaying the capture from the start as soon as the end is reached
+
+TIP: The replay-speed is ideal to see how your driver can cope with different volumes of traffic. So even if your driver is currently working fine, consider using this tool in order to find out if your system could cope with 50% more nodes or increased polling intervals etc.
\ No newline at end of file
diff --git a/src/site/site.xml b/src/site/site.xml
index 7645b08..8923b49 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -78,10 +78,11 @@
         <item name="Elastic Logstash " href="users/integrations/elastic-logstash.html"/>
       </item>
       <item name="Tools" href="users/tools/index.html">
-        <item name="Connection Pool" href="users/connection-pool.html"/>
-        <item name="Object PLC Mapping (OPM)" href="users/opm.html"/>
-        <item name="Scraper" href="users/scraper.html"/>
-        <item name="PLC4X without a PLC and Unit Testing" href="users/testing.html"/>
+        <item name="Capture Replay" href="users/tools/capture-replay.html"/>
+        <item name="Connection Pool" href="users/tools/onnection-pool.html"/>
+        <item name="Object PLC Mapping (OPM)" href="users/tools/opm.html"/>
+        <item name="Scraper" href="users/tools/scraper.html"/>
+        <item name="PLC4X without a PLC and Unit Testing" href="users/tools/testing.html"/>
       </item>
       <item name="Industry 4.0 with Apache" href="users/industry40.html"/>
       <item name="Security" href="users/security.html"/>