You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by ld...@apache.org on 2024/10/29 17:53:55 UTC
(plc4x) 01/01: chore(site): Reorganize page titles by 1 level.
This is an automated email from the ASF dual-hosted git repository.
ldywicki pushed a commit to branch site-title-updates
in repository https://gitbox.apache.org/repos/asf/plc4x.git
commit 9e3b21c441f28c7b760318f6b9e0d55c27313d10
Author: Łukasz Dywicki <lu...@code-house.org>
AuthorDate: Tue Oct 29 18:53:42 2024 +0100
chore(site): Reorganize page titles by 1 level.
Signed-off-by: Łukasz Dywicki <lu...@code-house.org>
---
src/site/asciidoc/apache/index.adoc | 2 +-
src/site/asciidoc/developers/architecture.adoc | 10 +-
src/site/asciidoc/developers/building.adoc | 20 ++--
src/site/asciidoc/developers/code-gen/index.adoc | 18 ++--
.../developers/code-gen/language/freemarker.adoc | 4 +-
.../asciidoc/developers/code-gen/protocol/df1.adoc | 2 +-
.../developers/code-gen/protocol/mspec.adoc | 50 +++++-----
src/site/asciidoc/developers/conferences.adoc | 2 +-
src/site/asciidoc/developers/contributing.adoc | 14 +--
src/site/asciidoc/developers/decisions.adoc | 12 +--
src/site/asciidoc/developers/index.adoc | 10 +-
.../asciidoc/developers/infrastructure/ci.adoc | 4 +-
.../asciidoc/developers/infrastructure/index.adoc | 2 +-
.../asciidoc/developers/infrastructure/issues.adoc | 2 +-
.../asciidoc/developers/infrastructure/sonar.adoc | 2 +-
.../asciidoc/developers/infrastructure/vm.adoc | 10 +-
.../developers/infrastructure/website.adoc | 10 +-
.../asciidoc/developers/infrastructure/wiki.adoc | 2 +-
src/site/asciidoc/developers/jqassistant.adoc | 8 +-
src/site/asciidoc/developers/maturity.adoc | 6 +-
src/site/asciidoc/developers/preparing/index.adoc | 2 +-
src/site/asciidoc/developers/preparing/linux.adoc | 18 ++--
src/site/asciidoc/developers/preparing/macos.adoc | 16 +--
.../asciidoc/developers/preparing/windows.adoc | 16 +--
.../developers/protocols/ads/protocol.adoc | 2 +-
.../developers/protocols/eip/protocol.adoc | 2 +-
src/site/asciidoc/developers/protocols/index.adoc | 4 +-
.../asciidoc/developers/release/build-tools.adoc | 24 ++---
src/site/asciidoc/developers/release/index.adoc | 2 +-
src/site/asciidoc/developers/release/release.adoc | 40 ++++----
.../asciidoc/developers/release/validation.adoc | 8 +-
src/site/asciidoc/developers/team.adoc | 5 +-
src/site/asciidoc/developers/tools.adoc | 2 +-
src/site/asciidoc/developers/tutorials/index.adoc | 2 +-
.../tutorials/testing-serializers-and-parsers.adoc | 2 +-
.../developers/tutorials/writing-driver.adoc | 2 +-
src/site/asciidoc/protocols/ab-eth/index.adoc | 4 +-
src/site/asciidoc/protocols/ads/index.adoc | 4 +-
src/site/asciidoc/protocols/canopen/index.adoc | 4 +-
src/site/asciidoc/protocols/delta-v/index.adoc | 12 +--
src/site/asciidoc/protocols/delta-v/read-data.adoc | 2 +
.../protocols/delta-v/reverse-engineering.adoc | 22 ++---
src/site/asciidoc/protocols/ehtercat/index.adoc | 4 +-
src/site/asciidoc/protocols/ethernet-ip/index.adoc | 4 +-
src/site/asciidoc/protocols/features.adoc | 2 +-
src/site/asciidoc/protocols/index.adoc | 8 +-
src/site/asciidoc/protocols/modbus/index.adoc | 4 +-
src/site/asciidoc/protocols/opc-ua/index.adoc | 4 +-
src/site/asciidoc/protocols/s7/index.adoc | 14 +--
src/site/asciidoc/protocols/s7/s7comm-plus.adoc | 2 +-
src/site/asciidoc/protocols/s7/s7comm.adoc | 12 +--
src/site/asciidoc/users/adopters.adoc | 2 +-
.../asciidoc/users/blogs-videos-and-slides.adoc | 8 +-
src/site/asciidoc/users/commercial-support.adoc | 6 +-
src/site/asciidoc/users/download.adoc | 70 ++++++-------
.../users/getting-started/general-concepts.adoc | 27 +++++-
src/site/asciidoc/users/getting-started/index.adoc | 6 +-
src/site/asciidoc/users/getting-started/plc4c.adoc | 2 +-
.../asciidoc/users/getting-started/plc4cs.adoc | 2 +-
.../asciidoc/users/getting-started/plc4go.adoc | 8 +-
src/site/asciidoc/users/getting-started/plc4j.adoc | 10 +-
.../asciidoc/users/getting-started/plc4py.adoc | 10 +-
.../users/getting-started/using-snapshots.adoc | 2 +-
.../users/getting-started/virtual-modbus.adoc | 4 +-
src/site/asciidoc/users/index.adoc | 2 +-
src/site/asciidoc/users/industry40.adoc | 16 +--
.../users/integrations/apache-calcite.adoc | 2 +-
.../asciidoc/users/integrations/apache-camel.adoc | 2 +-
.../asciidoc/users/integrations/apache-edgent.adoc | 2 +-
.../asciidoc/users/integrations/apache-iotdb.adoc | 6 +-
.../asciidoc/users/integrations/apache-kafka.adoc | 2 +-
.../asciidoc/users/integrations/apache-nifi.adoc | 10 +-
.../users/integrations/apache-streampipes.adoc | 2 +-
.../asciidoc/users/integrations/eclipse-ditto.adoc | 2 +-
.../asciidoc/users/integrations/eclipse-milo.adoc | 8 +-
src/site/asciidoc/users/integrations/index.adoc | 2 +-
src/site/asciidoc/users/issues.adoc | 2 +-
src/site/asciidoc/users/preparing-issues.adoc | 2 +-
src/site/asciidoc/users/protocols/ab-eth.adoc | 4 +-
src/site/asciidoc/users/protocols/ads.adoc | 8 +-
src/site/asciidoc/users/protocols/bacnet.adoc | 8 +-
src/site/asciidoc/users/protocols/c-bus.adoc | 4 +-
src/site/asciidoc/users/protocols/can.adoc | 4 +-
src/site/asciidoc/users/protocols/canopen.adoc | 10 +-
src/site/asciidoc/users/protocols/ctrlx.adoc | 4 +-
src/site/asciidoc/users/protocols/deltav.adoc | 2 +-
src/site/asciidoc/users/protocols/df1.adoc | 2 +-
src/site/asciidoc/users/protocols/eip.adoc | 8 +-
src/site/asciidoc/users/protocols/firmata.adoc | 10 +-
src/site/asciidoc/users/protocols/genericcan.adoc | 10 +-
src/site/asciidoc/users/protocols/iec-60870.adoc | 4 +-
src/site/asciidoc/users/protocols/index.adoc | 4 +-
src/site/asciidoc/users/protocols/knxnetip.adoc | 6 +-
src/site/asciidoc/users/protocols/logix.adoc | 12 +--
src/site/asciidoc/users/protocols/modbus.adoc | 26 ++---
src/site/asciidoc/users/protocols/opcua.adoc | 22 ++---
.../asciidoc/users/protocols/open-protocol.adoc | 4 +-
src/site/asciidoc/users/protocols/plc4x.adoc | 12 +--
src/site/asciidoc/users/protocols/profinet.adoc | 12 +--
src/site/asciidoc/users/protocols/s7.adoc | 108 ++++++++++-----------
src/site/asciidoc/users/protocols/simulated.adoc | 20 ++--
src/site/asciidoc/users/protocols/umas.adoc | 16 +--
src/site/asciidoc/users/security.adoc | 4 +-
src/site/asciidoc/users/tools/capture-replay.adoc | 6 +-
.../asciidoc/users/tools/connection-cache.adoc | 2 +-
src/site/asciidoc/users/tools/connection-pool.adoc | 6 +-
src/site/asciidoc/users/tools/index.adoc | 2 +-
src/site/asciidoc/users/tools/opm.adoc | 12 +--
src/site/asciidoc/users/tools/scraper.adoc | 14 +--
src/site/asciidoc/users/tools/testing.adoc | 10 +-
src/site/asciidoc/users/transports/can.adoc | 6 +-
src/site/asciidoc/users/transports/index.adoc | 2 +-
.../asciidoc/users/transports/pcap-replay.adoc | 2 +-
src/site/asciidoc/users/transports/raw-socket.adoc | 2 +-
src/site/asciidoc/users/transports/serial.adoc | 2 +-
src/site/asciidoc/users/transports/socketcan.adoc | 2 +-
src/site/asciidoc/users/transports/tcp.adoc | 2 +-
src/site/asciidoc/users/transports/udp.adoc | 2 +-
118 files changed, 537 insertions(+), 515 deletions(-)
diff --git a/src/site/asciidoc/apache/index.adoc b/src/site/asciidoc/apache/index.adoc
index 0f7364ccb1..35e48fafb3 100644
--- a/src/site/asciidoc/apache/index.adoc
+++ b/src/site/asciidoc/apache/index.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../images/
:icons: font
-== Apache
+= Apache
diff --git a/src/site/asciidoc/developers/architecture.adoc b/src/site/asciidoc/developers/architecture.adoc
index 0e95ebf201..784d26a391 100644
--- a/src/site/asciidoc/developers/architecture.adoc
+++ b/src/site/asciidoc/developers/architecture.adoc
@@ -15,9 +15,9 @@
// limitations under the License.
//
-== Architecture of PLC4X Connections
+= Architecture of PLC4X Connections
-=== Simple case
+== Simple case
In this simple case, an application asks the DriverManager to forward a connection creation to the corresponding Driver implementation, which then creates both a Connection and a MessageCodec instance. The Connection is the logical link between the connection state and the MessageCodec.
A MessageCodec uses a TransportInstance to communicate with the target device.
@@ -84,13 +84,13 @@ note top of [Connection] : logical
....
-=== Problems
+== Problems
Serial transports based on RS475 and UDP Transports currently don't allow sharing. That means only one connection instance can have access to one RS485 or one shared local UDP Port (Multiple UDP transport instances with different local ports however are possible). As soon as one connection is established and a second connection would try to access this, this would result in errors.
However, multiple devices could be attached to the same RS458 port (Modbus RTU and Modbus ASCII explicitly supports this, however using different devices using different protocols over the same port is not possible) and in BACnet connecting to multiple remote BACnet devices would require one local UDP port to be used by multiple connections.
-=== Protocols requiring us to use a fixed port on a non-broadcast address
+== Protocols requiring us to use a fixed port on a non-broadcast address
Some protocols, such as BACnet require remotes to send data to a fixed udp port on a non-broadcast address. This causes problems as soon as we want to connect to multiple BACnet devices from the same host as only one instance can get access to that port.
@@ -157,6 +157,6 @@ note top of [Connection] : logical
....
-=== Protocols only allowing one connection at a time
+== Protocols only allowing one connection at a time
diff --git a/src/site/asciidoc/developers/building.adoc b/src/site/asciidoc/developers/building.adoc
index ce5aa78d50..c2989fce7d 100644
--- a/src/site/asciidoc/developers/building.adoc
+++ b/src/site/asciidoc/developers/building.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Building PLC4X
+= Building PLC4X
PLC4X is built with `Apache Maven` and we have tried to make the build as simple as possible.
@@ -27,7 +27,7 @@ More about these later down in this manual.
For your convenience we also have provided a `Maven-Wrapper`, that should allow building of PLC4X with only `Java 11` or greater as requirement.
-=== Requirements
+== Requirements
The only requirements to building PLC4X should be:
@@ -35,7 +35,7 @@ The only requirements to building PLC4X should be:
* Git (Even if you are building the source distribution, the Kafka plugin seems to require a `git` executable being available on the systems `PATH`)
* Apache Maven (3.6.0 or newer) *(Optional)* (See next chapter)
-=== Using the Maven-Wrapper
+== Using the Maven-Wrapper
The so-called `Maven-Wrapper` is used by calling the Maven-Wrapper scripts `mvnw` (Mac & Linux) or `mvnw.cmd` (Windows) instead of the default Maven commands `mvn` and `mvn.cmd`.
@@ -45,7 +45,7 @@ If no suitable version can be found, it is automatically downloaded and installe
After the script has ensured a suitable Maven version is available, this is used and all arguments and parameters are transparently forwarded to this.
So simply adding the additional `w` to each of the Maven commands, there should be no difference to using a pre-installed Maven version.
-=== Using Maven
+== Using Maven
This document can't provide you with all the details needed to get started with `Maven` itself.
But there is a lot of good documentation out there.
@@ -57,7 +57,7 @@ It should handle all the details needed to get a general understanding of Maven
.Recording of a Maven Training for Apache Flex from 2016
https://vimeo.com/167857327
-=== Building PLC4X with Maven
+== Building PLC4X with Maven
As especially building the C++, and C# drivers requires building of some third party artifacts and increases build-time dramatically and requires setting up some additional third party tools, we have excluded these parts form the default Maven build.
@@ -95,7 +95,7 @@ If you want to skip the running of tests (even if this is not encouraged) you ca
This will not skip the compilation of tests, however.
-=== Building the PLC4X Website with Maven
+== Building the PLC4X Website with Maven
The PLC4X Website is also part of the same GIT repository that contains the code and it is built by Maven as well.
@@ -105,13 +105,13 @@ In order to build the website the following command should be sufficient:
This is just a quick-start version of the site generation, for a fully detailed documentation please read the https://plc4x.apache.org/developers/infrastructure/website.html[Website] documentation page.
-=== Some special Maven profiles
+== Some special Maven profiles
Maven supports so-called `profiles` for customizing the build in special cases.
We have tried to keep the number of profiles as low as possible.
So far there is only one profile.
-==== `apache-release` profile
+=== `apache-release` profile
This profile is automatically enabled on a release-build and it automatically creates some additional artifacts:
@@ -123,7 +123,7 @@ This profile is automatically enabled on a release-build and it automatically cr
Generally it is not required to enable ths profile unless you are interested in these Artifacts.
-==== `debug-pom` profile
+=== `debug-pom` profile
Especially for Maven beginners, it might be difficult to understand why a module builds the way it does.
Maven contains a lot of concepts to inherit and override settings.
@@ -141,7 +141,7 @@ Some tests of the PLC4X project do require quite a bit of time to run.
Therefore we decided to disable these for a normal build on developer machines.
If you want to run them locally and not rely on them being run on the CI servers, enable the `enable-all-checks` profile.
-=== Use the compiled library with Gradle
+== Use the compiled library with Gradle
Compiling the library as explained here add the new version in the local Maven repository (i.e. usually under `~/.m2/repository` on linux like systems), if you would like to use Gradle as Build Tool for your project you have just to use a local repository in your Gradle `build.gradle` file.
diff --git a/src/site/asciidoc/developers/code-gen/index.adoc b/src/site/asciidoc/developers/code-gen/index.adoc
index 83019d265f..5c0f3b96e4 100644
--- a/src/site/asciidoc/developers/code-gen/index.adoc
+++ b/src/site/asciidoc/developers/code-gen/index.adoc
@@ -16,7 +16,7 @@
//
:imagesdir: ../../images/
-== Code Generation
+= Code Generation
As hand-writing code for a lot of drivers in multiple languages would be quite a nightmare, we have invested a very large amount of time into finding a way to automate this.
@@ -120,7 +120,7 @@ So for example in case of generating a `Siemens S7` Driver for `Java` this would
The dark blue parts are the ones released externally, the turquoise ones are part of the main PLC4X repo.
-=== Introduction
+== Introduction
The maven plugin is built up very modular.
@@ -141,7 +141,7 @@ The downside was, that the PLC4X community regarded this XML format as pretty co
In the end we came up with our own format which we called `MSpec` and is described in the link:protocol/mspec.html[MSpec Format description].
-=== Configuration
+== Configuration
The `plc4x-maven-plugin` has a very limited set of configuration options.
@@ -295,11 +295,11 @@ and:
The reason for why the dependencies are added as code-dependencies and why the scope is set the way it is, is described in the <<Why are the protocol and language dependencies done so strangely?>> section.
-=== Custom Modules
+== Custom Modules
The plugin uses the https://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html[Java Serviceloader] mechanism to find modules.
-==== Protocol Modules
+=== Protocol Modules
In order to provide a new protocol module, all that is required, it so create a module containing a `META-INF/services/org.apache.plc4x.plugins.codegenerator.protocol.Protocol` file referencing an implementation of the `org.apache.plc4x.plugins.codegenerator.protocol.Protocol` interface.
@@ -346,7 +346,7 @@ As mentioned before, we support multiple versions of a protocol, so if `getVersi
The most important method for the actual code-generation however is the `getTypeContext()` method, which returns a `TypeContext` type which generally contains a list of all parsed types for this given protocol.
-==== Language Modules
+=== Language Modules
Analog to the <<Protocol Modules>> the Language modules are constructed very similar.
@@ -394,9 +394,9 @@ The `name` being used by the plugin to find the language output module defined b
`supportedOptions` provides a list of `options` that the current language module is able to use and which can be passed in to the maven configuration using the `options` settings.
-=== Problems with Maven
+== Problems with Maven
-==== Why are the 4 modules released separately?
+=== Why are the 4 modules released separately?
We mentioned in the introduction, that the first 4 modules are maintained and released from outside the main PLC4X repository.
@@ -417,7 +417,7 @@ For this reason we have stripped down the plugin and its dependencies to an abso
As soon as the tooling is released, the version is updated in the PLC4X build and the release version is used without any complications.
-==== Why are the protocol and language dependencies done so strangely?
+=== Why are the protocol and language dependencies done so strangely?
It would certainly be a lot cleaner, if we provided the dependencies to protocol and language modules as plugin dependencies.
diff --git a/src/site/asciidoc/developers/code-gen/language/freemarker.adoc b/src/site/asciidoc/developers/code-gen/language/freemarker.adoc
index 5c53337b8f..5851fcff0b 100644
--- a/src/site/asciidoc/developers/code-gen/language/freemarker.adoc
+++ b/src/site/asciidoc/developers/code-gen/language/freemarker.adoc
@@ -16,7 +16,7 @@
//
:imagesdir: ../../../images/
-== Apache Freemarker
+= Apache Freemarker
For the Freemarker language output we are using an unmodified version of https://freemarker.apache.org[Apache Freemarker] to generate output.
@@ -48,7 +48,7 @@ It will automatically create all needed intermediate directories and generate th
If this line is empty, the output is skipped for this type.
-=== Example `Java` output
+== Example `Java` output
....
package org.apache.plc4x.language.java;
diff --git a/src/site/asciidoc/developers/code-gen/protocol/df1.adoc b/src/site/asciidoc/developers/code-gen/protocol/df1.adoc
index ca52ae1738..aba6793803 100644
--- a/src/site/asciidoc/developers/code-gen/protocol/df1.adoc
+++ b/src/site/asciidoc/developers/code-gen/protocol/df1.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Example: DF1 MSpec
+= Example: DF1 MSpec
The DF1 protocol has three basic messages: a command message, acknowledge and not acknowledge.
A `0x10` is used as delimiter to differentiate between the messages and parts of the command message.
diff --git a/src/site/asciidoc/developers/code-gen/protocol/mspec.adoc b/src/site/asciidoc/developers/code-gen/protocol/mspec.adoc
index 8d19b56480..c8b20a35e3 100644
--- a/src/site/asciidoc/developers/code-gen/protocol/mspec.adoc
+++ b/src/site/asciidoc/developers/code-gen/protocol/mspec.adoc
@@ -16,7 +16,7 @@
//
:imagesdir: ../../../images/
-== The MSpec format
+= The MSpec format
The `MSpec` format (Message Specification) was a result of a brainstorming session after evaluating a lot of other options.
@@ -109,7 +109,7 @@ In general, we distinguish between two types of types used in field definitions:
- simple types
- complex types
-=== Simple Types
+== Simple Types
Simple types are usually raw data the format is:
@@ -138,7 +138,7 @@ There is currently one special type, reserved for string values, whose length is
- *vstring*: The input is treated as a variable length string and requires an expression tp provide the number of bits to read.
-=== Complex Types
+== Complex Types
In contrast to simple types, complex types reference other complex types (Root elements of the spec document).
@@ -146,9 +146,9 @@ How the parser should interpret them is defined in the referenced types definiti
In the example above, for example the `S7Parameter` is defined in another part of the spec.
-=== Field Types and their Syntax
+== Field Types and their Syntax
-==== array Field
+=== array Field
An `array` field is exactly what you expect.
It generates an field which is not a single-value element but an array or list of elements.
@@ -166,7 +166,7 @@ Possible values are:
- `length`: In this case a given number of bytes are being read. So if an element has been parsed and there are still bytes left, another element is parsed.
- `terminated`: In this case the parser will continue reading elements until it encounters a termination sequence.
-==== assert Field
+=== assert Field
An assert field is pretty much identical to a `const` field.
The main difference however it how the case is handled, if the parsed value does not match the expected value.
@@ -185,7 +185,7 @@ See also:
- validation field: Similar to an `assert` field, however no parsing is done, and instead simply a condition is checked.
- optional field: `optional` fields are aware of the types of parser errors produced by `assert` and `validation` fields
-==== checksum Field
+=== checksum Field
A checksum field can only operate on simple types.
@@ -205,7 +205,7 @@ This field doesn't keep any data in memory.
See also:
- implicit field: A checksum field is similar to an implicit field, however the `checksum-expression` is evaluated are parsing time and throws an exception if the values don't match.
-==== const Field
+=== const Field
A const field simply reads a given simple type and compares to a given reference value.
@@ -222,7 +222,7 @@ This field doesn't keep any data in memory.
See also:
- implicit field: A const field is similar to an implicit field, however it compares the parsed input to the reference value and throws an exception if the values don't match.
-==== discriminator Field
+=== discriminator Field
Discriminator fields are only used in `discriminatedType`s.
@@ -239,7 +239,7 @@ See also:
- implicit field: A discriminator field is similar to an implicit field, however doesn't provide a serialization expression as it uses the discrimination constants of the type it is.
- discriminated types
-==== implicit Field
+=== implicit Field
Implicit types are fields that get their value implicitly from the data they contain.
@@ -255,7 +255,7 @@ This type of field is generally used for fields that handle numbers of elements
This field doesn't keep any data in memory.
-==== manualArray Field
+=== manualArray Field
[manualArray {bit|byte} {name} {count|length|terminated} '{loop-expression}' '{serialization-expression}' '{deserialization-expression}' '{length-expression}']
@@ -263,7 +263,7 @@ This field doesn't keep any data in memory.
[manualArray {complex-type} {name} {count|length|terminated} '{loop-expression}' '{serialization-expression}' '{deserialization-expression}' '{length-expression}']
-==== manual Field
+=== manual Field
[manual {bit|byte} {name} '{serialization-expression}' '{deserialization-expression}' '{length-expression}']
@@ -271,7 +271,7 @@ This field doesn't keep any data in memory.
[manual {complex-type} {name} '{serialization-expression}' '{deserialization-expression}' '{length-expression}']
-==== optional Field
+=== optional Field
An optional field is a type of field that can also be `null`.
@@ -293,7 +293,7 @@ See also:
- `assert`: Assert fields are similar to `const` fields, but can abort parsing of an `optional` filed.
- `validation`: If a validation field in any of the subtypes fails, this aborts parsing of the `optional` field.
-==== padding Field
+=== padding Field
A padding field allows aligning of data blocks.
It outputs additional padding data, given amount of times specified by padding expression.
@@ -309,11 +309,11 @@ When serializing, the `times-padding` defines how often the `padding-value` shou
This field doesn't keep any data in memory.
-===== peek Field
+==== peek Field
// TODO: Implement
-==== reserved Field
+=== reserved Field
Reserved fields are very similar to `const` fields, however they don't throw exceptions, but instead log messages if the values don't match.
@@ -334,7 +334,7 @@ This field doesn't keep any data in memory.
See also:
- `const` field
-==== simple Field
+=== simple Field
Simple fields are the most common types of fields.
@@ -350,7 +350,7 @@ When parsing, the given type is parsed (can't be `null`) and saved in the corres
When serializing it is serialized normally using either a simple type serializer or by delegating serialization to a complex type.
-==== typeSwitch Field
+=== typeSwitch Field
// TODO: Finish this ...
@@ -393,7 +393,7 @@ These arguments are then available for expressions or passing on in the subtypes
See also:
- `discriminatedType`
-===== unknown Field
+==== unknown Field
// TODO: Finish this ...
@@ -402,7 +402,7 @@ It allows parsing any type of information, storing and using it and serializing
In general, it's something similar to a `simple` field, just explicitly states, that we don't yet quite know how to handle the content.
-===== validation Field
+==== validation Field
As mentioned before, a `validation` field is not really a field, it's a check that is added to the type parser.
@@ -414,7 +414,7 @@ If it finds one, it rewinds the parser to the position just before starting to p
If there is no `optional` field up the stack, then parsing fails.
-==== virtual Field
+=== virtual Field
Virtual fields have no impact on the input or output.
They simply result in creating artificial get-methods in the generated model classes.
@@ -427,7 +427,7 @@ They simply result in creating artificial get-methods in the generated model cla
Instead of being bound to a property, the return value of a `virtual` property is created by evaluating the `value-expression`.
-==== Parameters
+=== Parameters
Sometimes it is necessary to pass along additional parameters.
@@ -459,13 +459,13 @@ Here comes an example of this in above snippet:
[field S7Payload 'payload' ['messageType', 'parameter']]
-==== Serializer and Parser-Arguments
+=== Serializer and Parser-Arguments
Arguments influence the way the parser or serializer operates.
Wherever an parser-argument is used, this should also be valid in all subtypes the parser processes.
-===== byteOrder
+==== byteOrder
A `byteOrder` argument can set or change the byte-order used by the parser.
@@ -474,7 +474,7 @@ We currently support two variants:
- BIG_ENDIAN
- LITTLE_ENDIAN
-===== encoding
+==== encoding
Each simple type has a default encoding, which is ok for a very high percentage of cases.
diff --git a/src/site/asciidoc/developers/conferences.adoc b/src/site/asciidoc/developers/conferences.adoc
index cde6fe0936..4be49a499b 100644
--- a/src/site/asciidoc/developers/conferences.adoc
+++ b/src/site/asciidoc/developers/conferences.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Conferences & Events
+= Conferences & Events
On this page we are listing options to attend talks and events around PLC4X.
diff --git a/src/site/asciidoc/developers/contributing.adoc b/src/site/asciidoc/developers/contributing.adoc
index 09fc6a60cf..05f2181421 100644
--- a/src/site/asciidoc/developers/contributing.adoc
+++ b/src/site/asciidoc/developers/contributing.adoc
@@ -16,9 +16,9 @@
//
:imagesdir: ../images/
-== Contributing
+= Contributing
-=== Forms of contribution
+== Forms of contribution
There are multiple forms in which you can become involved with the PLC4X project.
@@ -32,13 +32,13 @@ These usually are, but are not limited to:
We are a very friendly bunch and don't be afraid to step forward.
-=== Commits
+== Commits
We make use of https://www.conventionalcommits.org/en/v1.0.0/[conventional commits].
As plc4x is a monolithic polyglot repository we usually define the scope as `...(plc4[language shortcut here]/subcomponent)`
(e.g. a new feature in Bacnet in the Golang part would have a message of `feat(plc4go/bacnet): cool new feature for...`).
-=== Pull-Requests
+== Pull-Requests
The simplest way to submit code changes, is via a GitHub pull-request.
@@ -67,7 +67,7 @@ image::contributing-github-create-pull-request.png[]
If you click on this, we will receive a notification on your changes and can review them.
We also can discuss your changes and have you perfect your pull request before we accept and merge it into PLC4X.
-==== Keeping your fork up to date
+=== Keeping your fork up to date
As we are continuously working on PLC4X and you created a copy of our repo, this will become out-of-date pretty soon.
@@ -120,14 +120,14 @@ So if you are considering to contribute more than just a one-time-patch, please
If you want to be assigned to an issue because you want to work on it, please request to be added to the JIRA groups on our http://plc4x.apache.org/mailing-lists.html[developers mailing list]
-=== Documentation
+== Documentation
As our documentation and website are generated as a side-product of our build, contributing to this technically the same as contributing to the code.
All our content is written in Asciidoctor and is located in `src/site/asciidoc` directories.
For a reference of the Asciidoctor syntax please have a look at the https://asciidoctor.org/docs/user-manual/#introduction-to-asciidoctor[Asciidoctor documentation].
-=== Branching model
+== Branching model
The PLC4X project uses the following branching model.
diff --git a/src/site/asciidoc/developers/decisions.adoc b/src/site/asciidoc/developers/decisions.adoc
index 61d181e928..f4d43e2e7d 100644
--- a/src/site/asciidoc/developers/decisions.adoc
+++ b/src/site/asciidoc/developers/decisions.adoc
@@ -16,9 +16,9 @@
//
:imagesdir: ../images/
-== Decision Making
+= Decision Making
-=== Introduction
+== Introduction
This document describes the roles and responsibilities of the project, who may vote, how voting works, how conflicts are resolved, etc.
@@ -26,19 +26,19 @@ The https://www.apache.org/foundation/faq[Apache Foundation FAQ] and http://www.
Apache has a http://www.apache.org/foundation/policies/conduct.html[code of conduct] that it expects its members to follow.
-=== Roles and Responsibilities
+== Roles and Responsibilities
Apache projects define a set of https://www.apache.org/foundation/how-it-works.html#roles[roles] with associated rights and responsibilities.
-==== Project Management Committee
+=== Project Management Committee
The http://www.apache.org/dev/pmc.html#what-is-a-pmc[PMC] has many https://www.apache.org/foundation/how-it-works.html#pmc[responsibilities] including complying with http://www.apache.org/dev/pmc.html#policy[ASF policies], https://www.apache.org/foundation/board/reporting[reporting to the board], https://www.apache.org/foundation/voting.html[approving releases] and adding new http://www.apache.org/dev/pmc.html#newcommitter[committers] and http://www.apache.org/dev/pmc.html#newpmc[PMC members].
-==== The Chair
+=== The Chair
The http://www.apache.org/dev/pmc.html#chair[chair] ensures board reports are submitted and that the project's roster is up to date.
-=== Decision Making
+== Decision Making
Different decisions require different forms of approval but community consensus is always the goal. Voting when needed should be open for http://www.apache.org/legal/release-policy.html#release-approval[at least 72 hours].
diff --git a/src/site/asciidoc/developers/index.adoc b/src/site/asciidoc/developers/index.adoc
index 33aea916a2..43540280f4 100644
--- a/src/site/asciidoc/developers/index.adoc
+++ b/src/site/asciidoc/developers/index.adoc
@@ -17,11 +17,11 @@
:imagesdir: ../images/
:icons: font
-== Developer Section
+= Developer Section
This part of the Apache PLC4X dedicated to provide information to people wanting to build PLC4X and hopefully also start contributing to this awesome project.
-=== Getting Started
+== Getting Started
We have tried to make the PLC4X build experience as smooth as possible and have tried to reduce the number of required third party tools to an absolute minimum.
@@ -35,17 +35,17 @@ As part of the build we have an initial build step that will do a `prerequisite
For details please have a look at the link:preparing/index.html[Preparing your Computer] page.
-=== Building PLC4X
+== Building PLC4X
We have a dedicated page on link:building.html[Building PLC4X].
Please read this page on information about how to build Apache PLC4X.
-=== Contributing
+== Contributing
If you want to work on Apache PLC4X in order to `fix things`, `add things` and start `contributing` in general, please have a look at our link:contributing.html[Contributing] page. It should contain all the information you need.
-=== Getting Help
+== Getting Help
The primary source for getting help definitely is our project mailing list dev@plc4x.apache.org.
diff --git a/src/site/asciidoc/developers/infrastructure/ci.adoc b/src/site/asciidoc/developers/infrastructure/ci.adoc
index fcb0558cf6..0c72f6c87b 100644
--- a/src/site/asciidoc/developers/infrastructure/ci.adoc
+++ b/src/site/asciidoc/developers/infrastructure/ci.adoc
@@ -16,7 +16,7 @@
//
:imagesdir: ../images/
-== Continuous Integration
+= Continuous Integration
We are currently using the following CI systems.
@@ -30,7 +30,7 @@ GitHub Actions on the other side responsible for doing the main part of the test
It not only builds and runs the tests on a matrix of operating systems as well as with a number of java versions.
It also is configured to run the tests on pull-requests.
-=== Structure of the Jenkins Pipeline build
+== Structure of the Jenkins Pipeline build
We are using the Jenkins `multi-branch pipeline plugin` to automatically setup build for branches based upon the build definition in the `Jenkinsfile` in the root of the project.
diff --git a/src/site/asciidoc/developers/infrastructure/index.adoc b/src/site/asciidoc/developers/infrastructure/index.adoc
index 7f48619a72..fd9b4a4169 100644
--- a/src/site/asciidoc/developers/infrastructure/index.adoc
+++ b/src/site/asciidoc/developers/infrastructure/index.adoc
@@ -17,6 +17,6 @@
:imagesdir: ../../images/
:icons: font
-== Infrastructure
+= Infrastructure
In this section you can find information on the services the Apache PLC4X project makes use of.
diff --git a/src/site/asciidoc/developers/infrastructure/issues.adoc b/src/site/asciidoc/developers/infrastructure/issues.adoc
index 13b44a1f37..1000e363e3 100644
--- a/src/site/asciidoc/developers/infrastructure/issues.adoc
+++ b/src/site/asciidoc/developers/infrastructure/issues.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Bug & Issue Tracker
+= Bug & Issue Tracker
Our bug & issue tracker is Github-Issues.
diff --git a/src/site/asciidoc/developers/infrastructure/sonar.adoc b/src/site/asciidoc/developers/infrastructure/sonar.adoc
index 663d9199e6..eae01fc9ca 100644
--- a/src/site/asciidoc/developers/infrastructure/sonar.adoc
+++ b/src/site/asciidoc/developers/infrastructure/sonar.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Code Analysis
+= Code Analysis
We are using `SonarCloud` as the service for static code analysis.
diff --git a/src/site/asciidoc/developers/infrastructure/vm.adoc b/src/site/asciidoc/developers/infrastructure/vm.adoc
index a42a8d8b70..4bce1f2358 100644
--- a/src/site/asciidoc/developers/infrastructure/vm.adoc
+++ b/src/site/asciidoc/developers/infrastructure/vm.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== The PLC4X Project VM
+= The PLC4X Project VM
As, especially for the raw socket functionality of PLC4X, our project had higher demands on the infrastructure as other projects.
Apache Infra kindly provided us with a dedicated VM.
@@ -28,7 +28,7 @@ On this machine we can even `sudo` to perform operations only available to `root
Project members can request access to the machine.
-=== Requesting access
+== Requesting access
In order to be able to log in, users need to add their SSH public key to their Apache ID first.
@@ -50,7 +50,7 @@ Here make sure to select the Project `Infrastructure (INFRA)`.
As soon as that's handled by the Infra team, you should be ready to log-in on the machine.
-=== Login to the machine
+== Login to the machine
Using SSH we should now be able to log in to the VM.
@@ -60,7 +60,7 @@ Be sure to use the username matching your Apache ID or the login will fail.
If all went well you should now be able to log in to the machine using your apache user.
-=== Doing things as `root`
+== Doing things as `root`
Apache Infra is great at keeping things safe.
Providing a sudo password directly would increase the danger of having this intercepted, therefore they are using a tool called `opiepasswd`.
@@ -94,7 +94,7 @@ https://selfserve.apache.org/otp-calculator.html
TIP: More help can be found for Apache committers at https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=122916896
-=== Required software
+== Required software
For being able to build the charts and graphics as part of the site generation, we need to add some additional packages:
diff --git a/src/site/asciidoc/developers/infrastructure/website.adoc b/src/site/asciidoc/developers/infrastructure/website.adoc
index 5a390688d9..d53c7b3c89 100644
--- a/src/site/asciidoc/developers/infrastructure/website.adoc
+++ b/src/site/asciidoc/developers/infrastructure/website.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Generating the Website
+= Generating the Website
We are currently using the normal `Maven` build to not only generate the project artifacts, but also the projects website.
@@ -36,7 +36,7 @@ Beyond the basic goodies, the build is also configured to generate images from A
This allows us to generate images like the ones on the http://plc4x.apache.org/protocols/s7/index.html[S7 Protocol Description page]
-=== Providing new content
+== Providing new content
Within the `src/site` directory there is a file `site.xml` which generally controls the menu and the look of the site.
@@ -51,7 +51,7 @@ So if we wanted to add a new page on some (hopefully non existent) `Wombat PLC P
For example with this content:
```
-== Wombat PLC Protocol
+= Wombat PLC Protocol
If you want to waste your money, brains and time, feel free to use a `Wombat PLC`.
@@ -75,7 +75,7 @@ After the build, you would find a file `target/site/protocols/wombat/index.html`
However you can link to this page from any other page, but it is not added ot the navigation menu.
-=== Adding links to menus
+== Adding links to menus
In order to add links to the menus, you have to create or modify the `site.xml` for the module you want to add content to.
@@ -158,7 +158,7 @@ If you want to insert the menu somewhere else, you will have to re-define the en
The `menu ref` items hereby reference standard menus provided by the `Maven` build.
-=== Deploying the Website
+== Deploying the Website
The PLC4X project uses Apache `gitpubsub` system for maintaining the website.
diff --git a/src/site/asciidoc/developers/infrastructure/wiki.adoc b/src/site/asciidoc/developers/infrastructure/wiki.adoc
index 7c72a1c894..6afbb897e1 100644
--- a/src/site/asciidoc/developers/infrastructure/wiki.adoc
+++ b/src/site/asciidoc/developers/infrastructure/wiki.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== WIKI
+= WIKI
We use Apache's Confluence instance as Wiki, however most information is generally managed on this website.
diff --git a/src/site/asciidoc/developers/jqassistant.adoc b/src/site/asciidoc/developers/jqassistant.adoc
index edd69283fa..dd924860ba 100644
--- a/src/site/asciidoc/developers/jqassistant.adoc
+++ b/src/site/asciidoc/developers/jqassistant.adoc
@@ -16,7 +16,7 @@
//
:imagesdir: ../images/
-== Using JQAssistant
+= Using JQAssistant
In PLC4X we are using a tool called `https://jqassistant.org/[JQAssistant]` for enforcing quality assurance rules.
@@ -58,11 +58,11 @@ These rules that are automatically checked during the build are defined in `src/
If defined in a reactor project, the rules apply to all modules of that (sub-)reactor.
So if they are defined in the root module of the project, it applies to all modules.
-=== Defining JQAssistant rules
+== Defining JQAssistant rules
TODO: Finish this "little detail" ...
-=== Using the Web-UI
+== Using the Web-UI
The scan and analysis is automatically performed during a normal Maven build.
In order to do ad-hoc queries against the project or develop new rules, the Web-UI is very helpful.
@@ -93,7 +93,7 @@ So when visiting the anounced url with a browser, you can use the pretty useful
image::neo4j-web-console.png[Neo4j Web Console]
-=== Using IntelliJ Idea
+== Using IntelliJ Idea
IntelliJ comes with some interesting Neo4J support. Unfortunately this only supports `Neo4j 3`.
diff --git a/src/site/asciidoc/developers/maturity.adoc b/src/site/asciidoc/developers/maturity.adoc
index dbefed507a..3cf0bc8750 100644
--- a/src/site/asciidoc/developers/maturity.adoc
+++ b/src/site/asciidoc/developers/maturity.adoc
@@ -17,15 +17,15 @@
:icons: font
-== Apache Maturity Model Assessment for PLC4X
+= Apache Maturity Model Assessment for PLC4X
-=== Overview
+== Overview
This is an assessment of the PLC4X project's maturity, meant to help inform the decision (of the mentors, community, Incubator PMC and ASF Board of Directors) to graduate it as a top-level Apache project.
It is based on the ASF project maturity model at https://community.apache.org/apache-way/apache-project-maturity-model.html
-=== Maturity model assessment
+== Maturity model assessment
Community members are encouraged to contribute to this page and comment on it, the following table summarizes project’s self-assessment against the Apache Maturity Model.
diff --git a/src/site/asciidoc/developers/preparing/index.adoc b/src/site/asciidoc/developers/preparing/index.adoc
index 460f2affa7..98d8475b51 100644
--- a/src/site/asciidoc/developers/preparing/index.adoc
+++ b/src/site/asciidoc/developers/preparing/index.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Preparing your Computer
+= Preparing your Computer
Building a project like Apache PLC4X on multiple target operating-systems is quite a challenge, but I think we managed to make it as simple as possible.
diff --git a/src/site/asciidoc/developers/preparing/linux.adoc b/src/site/asciidoc/developers/preparing/linux.adoc
index 8492571753..fb08eb59a4 100644
--- a/src/site/asciidoc/developers/preparing/linux.adoc
+++ b/src/site/asciidoc/developers/preparing/linux.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Linux
+= Linux
As tracking down issues which result from missing or outdated third party tools such as compilers are always hard do diagnose, we have extended the build of PLC4X with a `prerequisiteCheck` that automatically checks if required tools are installed and if a required minimum version is available.
@@ -26,7 +26,7 @@ So for example the availability and version of the C compiler is only checked if
If the check is reporting any issues, please feel free to follow the corresponding steps in this guide to install the tools.
-=== Git
+== Git
Checking:
@@ -42,7 +42,7 @@ Yum based systems:
sudo yum install git
-=== Java
+== Java
Checking:
@@ -54,11 +54,11 @@ Apt based systems:
sudo apt install openjdk-21-jdk
-=== Optional and other language support
+== Optional and other language support
Git an Java should be all you need for building the Java part of PLC4X.
-==== LibPCAP (For raw-ethernet support)
+=== LibPCAP (For raw-ethernet support)
Apt-based systems:
@@ -81,7 +81,7 @@ Sometimes I had to set the uid to execute the java executable with the permissio
sudo chmod 4755 /path/to/java
-==== gcc (For PLC4C)
+=== gcc (For PLC4C)
NOTE: It seems that when running Linux on `aarch64` (Apple's Silicon Chips), that there are issues ... we're working on that. Feel free to watch https://github.com/apache/plc4x/issues/1582 on updates to this.
@@ -99,7 +99,7 @@ Yum based systems:
sudo yum install gcc
-==== dotnet (For PLC4Net)
+=== dotnet (For PLC4Net)
Checking:
@@ -125,7 +125,7 @@ If, when checking the version again after installing, you are getting an error:
Then please have a look at this Stackoverflow post (the accepted solution) https://stackoverflow.com/questions/73753672/a-fatal-error-occurred-the-folder-usr-share-dotnet-host-fxr-does-not-exist
-==== python (For PLC4Py)
+=== python (For PLC4Py)
Checking:
@@ -141,7 +141,7 @@ Yum based systems:
yum intall python3
-==== Python venv (For PLC4Py)
+=== Python venv (For PLC4Py)
Checking:
diff --git a/src/site/asciidoc/developers/preparing/macos.adoc b/src/site/asciidoc/developers/preparing/macos.adoc
index d61bc26198..289030dced 100644
--- a/src/site/asciidoc/developers/preparing/macos.adoc
+++ b/src/site/asciidoc/developers/preparing/macos.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Mac OS
+= Mac OS
As tracking down issues which result from missing or outdated third party tools such as compilers are always hard do diagnose, we have extended the build of PLC4X with a `prerequisiteCheck` that automatically checks if required tools are installed and if a required minimum version is available.
@@ -30,7 +30,7 @@ Make sure `Homebrew` ist installed in order to install most of these.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-=== Git
+== Git
Checking:
@@ -45,7 +45,7 @@ If you get a response that indicates that git needs to be installed, please exec
brew install git
-=== Java
+== Java
Checking:
@@ -57,11 +57,11 @@ Apt based systems:
brew install openjdk
-=== Optional and other language support
+== Optional and other language support
Git an Java should be all you need for building the Java part of PLC4X.
-==== LibPCAP (For raw-ethernet support)
+=== LibPCAP (For raw-ethernet support)
The libpcap version bundled with macOS is currently 1.9.1.
This version causes exceptions.
@@ -69,7 +69,7 @@ So it's best to update to a newer version using brew:
brew install libpcap
-==== gcc (For PLC4C)
+=== gcc (For PLC4C)
Checking:
@@ -79,7 +79,7 @@ If you get any successful output, you probably don't need to do anything.
It seems macOS comes with a version of gcc which is good enough for our use cases.
-==== dotnet (For PLC4Net)
+=== dotnet (For PLC4Net)
Checking:
@@ -93,7 +93,7 @@ Alternatively you can also install it via homebrew:
brew install --cask dotnet-sdk
-==== python (For PLC4Py)
+=== python (For PLC4Py)
Checking:
diff --git a/src/site/asciidoc/developers/preparing/windows.adoc b/src/site/asciidoc/developers/preparing/windows.adoc
index f602b1cc58..8b1b1164ab 100644
--- a/src/site/asciidoc/developers/preparing/windows.adoc
+++ b/src/site/asciidoc/developers/preparing/windows.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Windows
+= Windows
As tracking down issues which result from missing or outdated third party tools such as compilers are always hard do diagnose, we have extended the build of PLC4X with a `prerequisiteCheck` that automatically checks if required tools are installed and if a required minimum version is available.
@@ -28,7 +28,7 @@ As in the past keeping the documentation up to date has been quite challenging,
So first be sure to install Chocolatey from here: https://community.chocolatey.org/ and follow the most recent instructions on that page in order to install it.
-=== Git
+== Git
Checking:
@@ -40,7 +40,7 @@ If above command is not successful, simply install it via Chocolatey:
choco install git
-=== Java
+== Java
Checking:
@@ -52,11 +52,11 @@ If you need to install or update Java, unfortunately this doesn't seem to be ava
For Oracles OpenJDK 21 this would be from here: https://learn.microsoft.com/de-de/java/openjdk/download
If you are using a Windows VM on `aarch64` (Apple M1 or M2 virtual machine), the download available from Microsoft build seem to be one of the few options you have. When installing make sure to select the option to configure the "JAVA_HOME" environment variable (deactivated per default).
-=== Optional and other language support
+== Optional and other language support
Git an Java should be all you need for building the Java part of PLC4X.
-==== LibPCAP (For raw-ethernet support)
+=== LibPCAP (For raw-ethernet support)
In order to use the raw ethernet transport capabilities of PLC4X, we need to ensure the NPcap library is installed.
@@ -74,7 +74,7 @@ In order to check if NPcap is installed, check the following directories:
If none of these can be found, install it by downloading the installer from https://npcap.com/#download
-==== gcc (For PLC4C)
+=== gcc (For PLC4C)
Checking:
@@ -92,7 +92,7 @@ https://repo.maven.apache.org/maven2/com/googlecode/cmake-maven-project/cmake-bi
Deploy as:
https://repo.maven.apache.org/maven2/com/googlecode/cmake-maven-project/cmake-binaries/3.27.7-b1/cmake-binaries-3.27.7-b1-windows-arm64.jar
-==== dotnet (For PLC4Net)
+=== dotnet (For PLC4Net)
Checking:
@@ -104,7 +104,7 @@ Usually this is already installed on Windows machines.
Download the installer from https://dotnet.microsoft.com/en-us/download[here]
-==== python (For PLC4Py)
+=== python (For PLC4Py)
Checking:
diff --git a/src/site/asciidoc/developers/protocols/ads/protocol.adoc b/src/site/asciidoc/developers/protocols/ads/protocol.adoc
index d71aa79036..79d9e73c1e 100644
--- a/src/site/asciidoc/developers/protocols/ads/protocol.adoc
+++ b/src/site/asciidoc/developers/protocols/ads/protocol.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Beckhoff ADS Protocol
+= Beckhoff ADS Protocol
// https://plantuml.com/de/activity-diagram-legacy
// https://deepu.js.org/svg-seq-diagram/Reference_Guide.pdf
diff --git a/src/site/asciidoc/developers/protocols/eip/protocol.adoc b/src/site/asciidoc/developers/protocols/eip/protocol.adoc
index 1cf6bbbc4c..ddf2120ae3 100644
--- a/src/site/asciidoc/developers/protocols/eip/protocol.adoc
+++ b/src/site/asciidoc/developers/protocols/eip/protocol.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== EIP Protocol
+= EIP Protocol
// https://plantuml.com/de/activity-diagram-legacy
// https://deepu.js.org/svg-seq-diagram/Reference_Guide.pdf
diff --git a/src/site/asciidoc/developers/protocols/index.adoc b/src/site/asciidoc/developers/protocols/index.adoc
index c3aa351f8b..c0b0b010b0 100644
--- a/src/site/asciidoc/developers/protocols/index.adoc
+++ b/src/site/asciidoc/developers/protocols/index.adoc
@@ -15,9 +15,9 @@
// limitations under the License.
//
-== Usage of protocols
+= Usage of protocols
-=== Currently documented are:
+== Currently documented are:
- link:ads/protocol.html[Beckhoff/ ADS]
- link:eip/protocol.html[EIP]
diff --git a/src/site/asciidoc/developers/release/build-tools.adoc b/src/site/asciidoc/developers/release/build-tools.adoc
index 4375c95ca2..f865ee51f6 100644
--- a/src/site/asciidoc/developers/release/build-tools.adoc
+++ b/src/site/asciidoc/developers/release/build-tools.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== Releasing PLC4X Build-Tools
+= Releasing PLC4X Build-Tools
In contrast to the main project, the `plc4x-build-tools` repository contains a loose collection of sub-projects.
@@ -30,7 +30,7 @@ So please check link:release.html[here] (Chapters: `Preparing your system for be
The rest of the steps are a lot simpler than those of the main project as there aren't any profiles involved.
-=== Creating a release branch (For the code-generation module)
+== Creating a release branch (For the code-generation module)
According to SemVer, we have: Major, Minor and Bugfix releases.
@@ -68,7 +68,7 @@ This step now should perform quite quickly as no build and no tests are involved
However in the end the versions of the `develop` branch are updated and a new `releases/code-generation/{code-generation-short-version}` branch is created.
-=== Preparing `develop` for the next iteration
+== Preparing `develop` for the next iteration
Now is a good time to add a new section to the `RELEASE_NOTES` document for the new `SNAPSHOT` version.
@@ -99,7 +99,7 @@ Also be sure to do a quick full-text-search to check if the version was updated
WARNING: If you find anything here, you will need to pay attention during the release.
-=== Release stabilization phase
+== Release stabilization phase
Now usually comes a phase in which last tests and checks should be performed.
@@ -107,7 +107,7 @@ If any problems are found they, have to be fixed in the release branch.
Changes should either be re applied in `develop` or `cherry-picked`, however merging things back can cause a lot of problems, and we no longer have the same versions.
-=== Preparing a release
+== Preparing a release
Before you start preparing the release, it is important to manually make the `RELEASE_NOTES` reflect the version we are planning on releasing.
@@ -180,7 +180,7 @@ And it will change the versions back and commit and push things.
However, it will not delete the tag in GIT (locally and remotely). So you have to do that manually or use a different tag next time.
-=== Performing a release
+== Performing a release
This is done by executing another goal of the `maven-release-plugin`:
@@ -217,7 +217,7 @@ This contains all sources of the project and will be what's actually the release
This file will also be signed and `SHA512` hashes will be created.
-=== Staging a release
+== Staging a release
Each new release and release-candidate has to be staged in the Apache SVN under:
@@ -257,7 +257,7 @@ The three `*-source-release.zip*` artifacts should be located in the directory:
So, after committing these files to SVN, you are ready to start the vote.
-=== Starting a vote on the mailing list
+== Starting a vote on the mailing list
After staging the release candidate in the Apache SVN, it is time to actually call out the vote.
@@ -335,7 +335,7 @@ After the 72-our minimum wait period is over, and we have fulfilled the requirem
Chris
----
-=== Releasing after a successful vote
+== Releasing after a successful vote
As soon as the votes are finished, and the results were in favor of a release, the staged artifacts can be released.
This is done by moving them inside the Apache SVN.
@@ -351,7 +351,7 @@ This will make the release artifacts available and will trigger them being copie
This is also the reason why you should wait at least 24 hours before sending out the release notification emails.
-=== Cleaning up older release versions
+== Cleaning up older release versions
As a lot of mirrors are serving our releases, it is the Apache policy to clean old releases from the repo if newer versions are released.
@@ -361,7 +361,7 @@ This can be done like this:
After this, https://dist.apache.org/repos/dist/release/plc4x should only contain the latest release directory.
-=== Releasing the Maven artifacts
+== Releasing the Maven artifacts
The probably simplest part is releasing the Maven artifacts.
@@ -371,7 +371,7 @@ This will move all artifacts into the Apache release repository and delete the s
All release artifacts released to the Apache release repo, will automatically be synced to Maven central.
-=== Merge back release version to `release` branch
+== Merge back release version to `release` branch
The `release branch should always point to the last released version.
This has to be done with git
diff --git a/src/site/asciidoc/developers/release/index.adoc b/src/site/asciidoc/developers/release/index.adoc
index 473cddb5b6..311fe0ca3a 100644
--- a/src/site/asciidoc/developers/release/index.adoc
+++ b/src/site/asciidoc/developers/release/index.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== Releasing and Validating Releases
+= Releasing and Validating Releases
diff --git a/src/site/asciidoc/developers/release/release.adoc b/src/site/asciidoc/developers/release/release.adoc
index 4e7ae20674..25de5fa27f 100644
--- a/src/site/asciidoc/developers/release/release.adoc
+++ b/src/site/asciidoc/developers/release/release.adoc
@@ -17,9 +17,9 @@
:imagesdir: ../../images/
:icons: font
-== Releasing PLC4X
+= Releasing PLC4X
-=== TL/DR
+== TL/DR
IMPORTANT: Please be sure to execute the release with a Java version 11 or the Karaf feature tests will not run.
@@ -57,7 +57,7 @@ IMPORTANT: Please be sure to execute the release with a Java version 11 or the K
* [ ] Merge back release version to `release` branch
* [ ] Send announce email
-=== Preparing your system for being able to release
+== Preparing your system for being able to release
NOTE: Be sure you are using a JDK and not a JRE, or the release will fail because the release can't execute the `javadoc` executable.
@@ -130,7 +130,7 @@ NOTE: On some systems (mainly Mac) gpg signing can result in errors like:
gpg: signing failed: Inappropriate ioctl for device```
In this case adding the following helps: `export GPG_TTY=$(tty)`
-=== Preparing the codebase for a release
+== Preparing the codebase for a release
Usually you will have to update the RELEASE_NOTES document to the new version.
I would suggest doing this prior to the branch as otherwise you will definitely have to port it back to `develop`.
@@ -139,7 +139,7 @@ So remove the `SNAPSHOT` and `(Unreleased)` markers from the file and add missin
Also, if you are doing the first release in a new year, it is advisable to search for the old year and check if any occurrences are ok the way they are.
Usually the `NOTICE` file has to be adjusted.
-=== Creating a release branch
+== Creating a release branch
According to SemVer, we have: Major, Minor and Bugfix releases.
@@ -180,7 +180,7 @@ This step now should perform quite quickly as no build and no tests are involved
However, in the end the versions of the `develop` branch are updated and a new `rel/{current-short-version}` branch is created.
-=== Preparing `develop` for the next iteration
+== Preparing `develop` for the next iteration
Now is a good time to add a new section to the `RELEASE_NOTES` document for the new `SNAPSHOT` version.
@@ -209,7 +209,7 @@ Also be sure to do a quick full-text-search to check if the version was updated
WARNING: If you find anything here, you will need to pay attention during the release.
-=== Release stabilization phase
+== Release stabilization phase
Now usually comes a phase in which last tests and checks should be performed.
@@ -217,7 +217,7 @@ If any problems are found, they have to be fixed in the release branch.
Changes should either be re applied in `develop` or `cherry-picked`, however merging things back can cause a lot of problems, and we no longer have the same versions.
-=== Preparing a release
+== Preparing a release
Same as with creating the branch it is important to enable all profiles when creating the branch as only this way will all modules versions be updated.
Otherwise, the non-default modules on develop will reference the old version which will cause problems when building.
@@ -287,7 +287,7 @@ Also, should you check if you have any uncommitted changes (as our code-generati
However, it will not delete the tag in GIT (locally and remotely). So you have to do that manually or use a different tag next time.
-=== Performing a release
+== Performing a release
This is done by executing another goal of the `maven-release-plugin`:
@@ -328,7 +328,7 @@ This contains all sources of the project and will be what's actually the release
This file will also be signed and `SHA512` hashes will be created.
-=== Staging a release
+== Staging a release
Each new release and release-candidate has to be staged in the Apache SVN under:
@@ -368,7 +368,7 @@ All three `*-source-relese.zip*` artifacts should be located in the directory: `
After committing these files to SVN you are ready to start the vote.
-=== Starting a vote on the mailing list
+== Starting a vote on the mailing list
After staging the release candidate in the Apache SVN, it is time to actually call out the vote.
@@ -442,7 +442,7 @@ Message:
So, the vote passes with {number of +1 votes} +1 votes by PMC members {number of +1 votes from non-pmc members} +1 vote by a non PMC member.
----
-=== Releasing after a successful vote
+== Releasing after a successful vote
As soon as the votes are finished, and the results were in favor of a release, the staged artifacts can be released.
This is done by moving them inside the Apache SVN.
@@ -458,7 +458,7 @@ This will make the release artifacts available and will trigger them being copie
This is also the reason why you should wait at least 24 hours before sending out the release notification emails.
-=== Going back for a new release candidate
+== Going back for a new release candidate
If however for some reason it is needed to prepare a new RC for the release. Please follow these steps:
@@ -486,7 +486,7 @@ If however for some reason it is needed to prepare a new RC for the release. Ple
After this you should be ready to start a new RC.
-=== Cleaning up older release versions
+== Cleaning up older release versions
As a lot of mirrors are serving our releases, it is the Apache policy to clean old releases from the repo if newer versions are released.
@@ -496,7 +496,7 @@ This can be done like this:
After this https://dist.apache.org/repos/dist/release/plc4x should only contain the latest release directory.
-=== Releasing the Maven artifacts
+== Releasing the Maven artifacts
Probably the simplest part is releasing the Maven artifacts.
@@ -506,7 +506,7 @@ This will move all artifacts into the Apache release repository and delete the s
All release artifacts released to the Apache release repo, will automatically be synced to Maven central.
-=== Add the version to the DOAP file
+== Add the version to the DOAP file
Now that the release is out, in the `develop` branch, update the `DOAP` file for plc4x.
@@ -518,7 +518,7 @@ Please add the just released version to the top of the versions.
This file is needed for Apache's tooling to automatically keep track of project release activity, and we use this internally too to automatically update the documentation to always reference the latest released version automatically.
-=== Merge back release version to `release` branch
+== Merge back release version to `release` branch
The `release` branch should always point to the last released version.
This has to be done with git
@@ -539,12 +539,12 @@ git merge -X theirs v{current-full-version}
Possibly a manual conflict resolution has to be done afterwards. After that, changes need to
be pushed.
-=== Updating Jira
+== Updating Jira
1. Set the released version to "released" and set the "release-date"
2. Add the next version to the versions.
-=== Update the download site
+== Update the download site
The URL http://plc4x.apache.org/users/download.html has to be changed, and the current release has to be listed there.
This is done by changing the `download.adoc` under `src/site/users/` (**in the develop branch, as this is where the site is generated from!**)
@@ -557,7 +557,7 @@ _Note: Please add an anchor for the toc_
_Note: Transfer all to ascii-doc notation to ensure correct rendering of the site_
_Also remove the JIRA TICKET ids in Front_
-=== Notifying the world
+== Notifying the world
Make sure you have given the Apache mirrors time to fetch the release files by waiting at least 24 hours after moving the release candidate to the release part of the SVN.
diff --git a/src/site/asciidoc/developers/release/validation.adoc b/src/site/asciidoc/developers/release/validation.adoc
index e5f572b49a..d16222e368 100644
--- a/src/site/asciidoc/developers/release/validation.adoc
+++ b/src/site/asciidoc/developers/release/validation.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../images/
:icons: font
-== Validating a staged release
+= Validating a staged release
TIP: On MacOS and Linux the first 4 steps can be automated. For details please read the section about tooling after this chapter.
@@ -69,7 +69,7 @@ find . -type f -name 'pom.xml' -exec grep -l "SNAPSHOT" {} \;
* [ ] Build the project according to the information in the README.md file.
* [ ] [RM] Build the project with all `with-xyz` profiles and tests enabled and an empty maven local repo: by appending `-Dmaven.repo.local=../.m2` (On windows use `-D"maven.repo.local"="../.m2"`).
-=== Using RAT
+== Using RAT
Even if we are using RAT to ensure sources have headers in place, still the project can contain exclusions that hide things from the check.
@@ -86,7 +86,7 @@ java -jar apache-rat-0.13.jar apache-plc4x-{current-full-version}-source-release
By piping the result into a text file gives you the chance to investigate the content more easily.
-=== Release Tooling
+== Release Tooling
In the `tools` directory we have a little script that can help with downloading and checking the hashes and signatures automatically.
@@ -103,7 +103,7 @@ After that it will calculate the SHA512 hash and compare it with the staged hash
Last not least it will validate the PGP key and print out some information on it.
-=== Template for the email for voting
+== Template for the email for voting
----
+1/-1 (binding)
diff --git a/src/site/asciidoc/developers/team.adoc b/src/site/asciidoc/developers/team.adoc
index 787754f55b..42a9482e59 100644
--- a/src/site/asciidoc/developers/team.adoc
+++ b/src/site/asciidoc/developers/team.adoc
@@ -17,12 +17,12 @@
:imagesdir: ../images/
:icons: font
-== Team
+= Team
Sorted by first name:
[width="100%",cols="2,4,1,1",options="header"]
-|=========================================================
+|===
|Name |Bio | |
| *Ben Hutcheson*
@@ -88,3 +88,4 @@ Engineer
pragmatic industries GmbH
Nürtingen |Electrical engineer (HW, SW and interface-stuff) from passion and very new to Apache projects. The more he is involved in open-source the more he likes it, focusing on PLC4X at first. | a|image::team/tmitsch.png[tmitsch, 240, 263]
+|===
\ No newline at end of file
diff --git a/src/site/asciidoc/developers/tools.adoc b/src/site/asciidoc/developers/tools.adoc
index 825229d5f7..c4a68cea01 100644
--- a/src/site/asciidoc/developers/tools.adoc
+++ b/src/site/asciidoc/developers/tools.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../images/
:icons: font
-== Tools
+= Tools
In order to be able to work on PLC4X some tools have kindly been made available to Apache PLC4X committers.
diff --git a/src/site/asciidoc/developers/tutorials/index.adoc b/src/site/asciidoc/developers/tutorials/index.adoc
index 21ded0ee2c..2016e68c53 100644
--- a/src/site/asciidoc/developers/tutorials/index.adoc
+++ b/src/site/asciidoc/developers/tutorials/index.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== Tutorials
+= Tutorials
diff --git a/src/site/asciidoc/developers/tutorials/testing-serializers-and-parsers.adoc b/src/site/asciidoc/developers/tutorials/testing-serializers-and-parsers.adoc
index 5b55e17049..4a6e1268b2 100644
--- a/src/site/asciidoc/developers/tutorials/testing-serializers-and-parsers.adoc
+++ b/src/site/asciidoc/developers/tutorials/testing-serializers-and-parsers.adoc
@@ -18,7 +18,7 @@
= Testing Serializers and Parsers
-Currently the build generates the serializers and parsers from a provided `mspec` specification.
+Currently, the build generates the serializers and parsers from a provided `mspec` specification.
A typical full round-trip test for the model, parsers and serializers would look as follows:
diff --git a/src/site/asciidoc/developers/tutorials/writing-driver.adoc b/src/site/asciidoc/developers/tutorials/writing-driver.adoc
index dcf572775b..583187d992 100644
--- a/src/site/asciidoc/developers/tutorials/writing-driver.adoc
+++ b/src/site/asciidoc/developers/tutorials/writing-driver.adoc
@@ -16,7 +16,7 @@
//
:imagesdir: ../../images/
-== Basic Building Blocs of a Driver / Protocol
+= Basic Building Blocs of a Driver / Protocol
The general pipeline for a Protocol looks like the following:
diff --git a/src/site/asciidoc/protocols/ab-eth/index.adoc b/src/site/asciidoc/protocols/ab-eth/index.adoc
index 759a709457..67ba35fcee 100644
--- a/src/site/asciidoc/protocols/ab-eth/index.adoc
+++ b/src/site/asciidoc/protocols/ab-eth/index.adoc
@@ -15,12 +15,12 @@
// limitations under the License.
//
-== Allen-Bradley Ethernet
+= Allen-Bradley Ethernet
The Allen-Bradley Ethernet protocol encapsulates a DF1 protocol body to transfer data. The PLC4X driver currently only
supports the protected typed logical read with a limited number of data types.
-=== Connection
+== Connection
The connection string looks as follows: `ab-eth://<ip-address>/<station>`
diff --git a/src/site/asciidoc/protocols/ads/index.adoc b/src/site/asciidoc/protocols/ads/index.adoc
index f586586a6d..64498ae358 100644
--- a/src/site/asciidoc/protocols/ads/index.adoc
+++ b/src/site/asciidoc/protocols/ads/index.adoc
@@ -15,11 +15,11 @@
// limitations under the License.
//
-== Beckhoff ADS
+= Beckhoff ADS
Introduction
-=== Links
+== Links
diff --git a/src/site/asciidoc/protocols/canopen/index.adoc b/src/site/asciidoc/protocols/canopen/index.adoc
index 7d9d2b2472..5e61e1ccd3 100644
--- a/src/site/asciidoc/protocols/canopen/index.adoc
+++ b/src/site/asciidoc/protocols/canopen/index.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== CANopen
+= CANopen
CANopen is communication protocol built on top of CAN.
CAN is a popular link layer standard which allows exchanging data between nodes and build multi-node applications.
@@ -31,7 +31,7 @@ Please refer the official materials for more details on protocol and its constru
Apache PLC4X is open source project.
It is not a certified product.
-=== Links
+== Links
- https://www.can-cia.org/canopen[CAN in Automation] organization managing specification.
- Public materials published by CAN in Automation: https://www.can-cia.org/en/download/
diff --git a/src/site/asciidoc/protocols/delta-v/index.adoc b/src/site/asciidoc/protocols/delta-v/index.adoc
index 791ece131f..1ffebaf7a1 100644
--- a/src/site/asciidoc/protocols/delta-v/index.adoc
+++ b/src/site/asciidoc/protocols/delta-v/index.adoc
@@ -16,14 +16,14 @@
//
:imagesdir: ../../images/
-== DeltaV Industrial Ethernet Communication
+= DeltaV Industrial Ethernet Communication
The DeltaV protocol is used in the Emerson DeltaV system.
In contrast to most other systems, this is a combination of PLC and Control System.
As Emerson seems to insist on the devices not being PLCs, but controllers, well call them this way in this document.
Same with the Control System, these seem to be called OS (Operator System).
-=== Disclaimer
+== Disclaimer
As we had absolutely no information on the details of the protocol, we started by taking an existing DeltaV training system and replaced the network switch with a hub and used this to take network captures of the entire network traffic of the DeltaV network.
@@ -37,7 +37,7 @@ Due to this uncertainty we are only implementing a `promiscuous mode` driver, wh
Read link:reverse-engineering.html[here] for a document on how we proceeded with reverse engineering this protocol.
-=== The Wrapper Protocol
+== The Wrapper Protocol
All communication seems to be done using the `UDP` protocol on port `18507`.
@@ -98,11 +98,11 @@ However we currently have no idea on how this is calculated and we haven't inves
UDP being connectionless the DeltaV network protocol seems to require acknowledging.
This is done by sending a packet back to the originator, but with a length of `0x0000` and the same `type` and mesasge-id` as the packet that is acknowledged.
-=== High Level View of the Protocol
+== High Level View of the Protocol
In this section we'll describe the general structure of how the communication looks like - which message types are sent when and in which sequence.
-==== Connecting an OS to a Controller
+=== Connecting an OS to a Controller
[seqdiag,deltav-connect]
....
@@ -125,7 +125,7 @@ In this section we'll describe the general structure of how the communication lo
}
....
-==== Regular sync
+=== Regular sync
It seems that every 15 seconds two packets are exchanged.
diff --git a/src/site/asciidoc/protocols/delta-v/read-data.adoc b/src/site/asciidoc/protocols/delta-v/read-data.adoc
index 7793bad8f5..a7b9072f79 100644
--- a/src/site/asciidoc/protocols/delta-v/read-data.adoc
+++ b/src/site/asciidoc/protocols/delta-v/read-data.adoc
@@ -16,6 +16,8 @@
//
:imagesdir: ../../images/
+= Data retrieval
+
== 0x0403 (before registration)
Before a subscription is done, regularly (about once a minute) the following packets come in.
diff --git a/src/site/asciidoc/protocols/delta-v/reverse-engineering.adoc b/src/site/asciidoc/protocols/delta-v/reverse-engineering.adoc
index 271c31b8e3..b38c17f380 100644
--- a/src/site/asciidoc/protocols/delta-v/reverse-engineering.adoc
+++ b/src/site/asciidoc/protocols/delta-v/reverse-engineering.adoc
@@ -16,13 +16,13 @@
//
:imagesdir: ../../images/
-== Reverse Engineering the DeltaV protocol
+= Reverse Engineering the DeltaV protocol
This document should describe what we did in order to reverse-engineer the DeltaV protocol.
The sole purpose of this document, is to write document our path in order to eventually protect ourselves against accusation of using illegal measures in gaining the information we got.
-=== Starting point
+== Starting point
We kindly were provided with access to a DeltaV system used for training.
@@ -42,7 +42,7 @@ With this we let the system run and did a pretty long network capture.
This 29MB WireShark capture was what we started working with.
-=== Identifying the protocol
+== Identifying the protocol
As WireShark didn't have a DeltaV disector, we had to trace it down ourselves.
@@ -50,7 +50,7 @@ When looking at the capture, we very quickly filtered out the usual network prot
Special with all of these was that they all started with a payload of `0xFACE`.
-=== First steps in understanding the protocol
+== First steps in understanding the protocol
Here it appeared that `UDP` packets are sent with some sort of payload, which are obviously responded to by packets with a fixed and very small size (64 bytes).
@@ -68,7 +68,7 @@ When filtering only the `UDP` packets on port `18507` we could scroll though the
In order to prove any assumption we made, we used little programs that used Pcap4J to programmatically check assumptions.
-=== Decoding the wrapper packet header
+== Decoding the wrapper packet header
As mentioned before, it appeared obvious that for almost identical packets the first two short values were very similar too, which led us to the assumption that these are `type` and `sub-type'.
So we wrote a little program, that scanned all the packets and counted how many types we had.
@@ -135,7 +135,7 @@ So we'll just keep that in mind an not worry about interpreting a meaning into t
The last two bytes of the wrapper packet header are simply constantly `0x8000` in every packet.
Here too, we'll just live with knowing that and not wondering what it could mean.
-=== Decoding the internal packet
+== Decoding the internal packet
After having decoded what we think is the wrapper-protocol packet structure, we knew decoding the internal protocol would be a bigger challenge.
@@ -153,7 +153,7 @@ The first two bytes of the payload seem again to relate to a type as similar pac
Especially we did a lot of separate captures for all sorts of different operations.
During this we managed to reverse engineer the connection on the wrapper-protocol layer as well how the communication looks inside the internal protocol.
-==== Connecting
+=== Connecting
When an OS is booted, the following communication could be observed:
@@ -172,7 +172,7 @@ So it seems that In these packets each participant compares it's software state
This does make sense.
When connecting to a remote system, checking the version compatibility is surely an important thing to do.
-==== Normal operation
+=== Normal operation
When just starting the system and not changing anything, we did notice those previously mentioned `0x0006` type messages we think are responsible for keeping the connections in sync.
@@ -183,7 +183,7 @@ It also appears that there is some upper bound for the size of packets.
As when seeing a lot of alarms being sent in 0x0304 messages, sometimes these are split up into multiple messages sent in very short intervals.
The last of these usually being smaller than the rest.
-==== Changing values
+=== Changing values
So now we started changing values.
First we started changing valid values into other valid values.
@@ -197,7 +197,7 @@ Also did we notice the `0x0403` packets seem to contain String constants that re
We assume payload-types starting with `0x04` relate to normal data exchange and ones with `0x03` relating to events and alarms.
-==== Decoding value changes
+=== Decoding value changes
After coming to the conclusion that wrapper-type `0x0002` messages with a payload-type `0x0403` seem to relate to value changes, we started filtering for exactly these packages.
@@ -242,7 +242,7 @@ Right now we are assuming that in one of the other `0x04` packets a subscription
We will hopefully be able to decode this addressing problem in one of our next reverse-engineering sessions.
-==== Decoding Strings
+=== Decoding Strings
As we mentioned before, that we could see content in the packages that were sometimes readable from just looking at the payload, we decided to have another look at these.
diff --git a/src/site/asciidoc/protocols/ehtercat/index.adoc b/src/site/asciidoc/protocols/ehtercat/index.adoc
index 8fecaa9b8a..4f533f54f9 100644
--- a/src/site/asciidoc/protocols/ehtercat/index.adoc
+++ b/src/site/asciidoc/protocols/ehtercat/index.adoc
@@ -15,11 +15,11 @@
// limitations under the License.
//
-== EtherCAT
+= EtherCAT
Introduction
-=== Links
+== Links
https://www.ethercat.org/default.htm
https://www.ethercat.org/download/documents/EtherCAT_EAP_EN.pdf
diff --git a/src/site/asciidoc/protocols/ethernet-ip/index.adoc b/src/site/asciidoc/protocols/ethernet-ip/index.adoc
index f0c705bd97..ca16129867 100644
--- a/src/site/asciidoc/protocols/ethernet-ip/index.adoc
+++ b/src/site/asciidoc/protocols/ethernet-ip/index.adoc
@@ -15,11 +15,11 @@
// limitations under the License.
//
-== EtherNet/IP
+= EtherNet/IP
Introduction
-=== Links
+== Links
As of November 2008, The EtherNet/IP Specification consists of three parts: The Common Industrial
Protocol (Volume 1 of the CIP Networks Library), the EtherNet/IP Adaptation of CIP (Volume 2), and the
diff --git a/src/site/asciidoc/protocols/features.adoc b/src/site/asciidoc/protocols/features.adoc
index 2c20eafe90..8f41b8afb2 100644
--- a/src/site/asciidoc/protocols/features.adoc
+++ b/src/site/asciidoc/protocols/features.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Features
+= Features
:icons: font
The following table contains a list of operations and the protocols that support them:
diff --git a/src/site/asciidoc/protocols/index.adoc b/src/site/asciidoc/protocols/index.adoc
index da8c5308bc..b6314097de 100644
--- a/src/site/asciidoc/protocols/index.adoc
+++ b/src/site/asciidoc/protocols/index.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Protocols
+= Protocols
- link:ab-eth/index.html[AB-Ethernet]
- link:ads/index.html[DeltaV]
@@ -26,14 +26,14 @@
- link:opc-ua/index.html[OPC-UA]
- link:s7/index.html[S7]
-=== Links
+== Links
Apache 2.0 licensed JNI library for accessing raw IPv4 and IPv6 sockets. Might be the ideal starting point for implementing protocols below TCP & UDP.
https://www.savarese.org/software/rocksaw/
Links to different WireShark captures: https://github.com/automayt/ICS-pcap
-==== BACNet
+=== BACNet
Used in the building automation sector.
http://www.bacnet.org/Addenda/Add-135-2008t.pdf
@@ -41,7 +41,7 @@ http://www.bacnet.org/Addenda/Add-135-2008t.pdf
AKA: ISO 16484-5:
The official specification can be purchased here: https://www.iso.org/standard/71935.html
-==== IEC 61850
+=== IEC 61850
Used by the IDS SAS (station automation system)
diff --git a/src/site/asciidoc/protocols/modbus/index.adoc b/src/site/asciidoc/protocols/modbus/index.adoc
index 7a1092eba3..58e2c65e2d 100644
--- a/src/site/asciidoc/protocols/modbus/index.adoc
+++ b/src/site/asciidoc/protocols/modbus/index.adoc
@@ -15,11 +15,11 @@
// limitations under the License.
//
-== Modbus
+= Modbus
Introduction
-=== Links
+== Links
- Main Landing Page: http://www.modbus.org/tech.php
- Modbus Protocol Spec: http://www.modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf
diff --git a/src/site/asciidoc/protocols/opc-ua/index.adoc b/src/site/asciidoc/protocols/opc-ua/index.adoc
index 82973c0edc..0176696587 100644
--- a/src/site/asciidoc/protocols/opc-ua/index.adoc
+++ b/src/site/asciidoc/protocols/opc-ua/index.adoc
@@ -15,11 +15,11 @@
// limitations under the License.
//
-== OPC-UA
+= OPC-UA
Introduction
-=== Links
+== Links
https://opcfoundation.org/developer-tools/specifications-unified-architecture/part-1-overview-and-concepts
diff --git a/src/site/asciidoc/protocols/s7/index.adoc b/src/site/asciidoc/protocols/s7/index.adoc
index bb17ec7a4f..0b734e4b64 100644
--- a/src/site/asciidoc/protocols/s7/index.adoc
+++ b/src/site/asciidoc/protocols/s7/index.adoc
@@ -16,14 +16,14 @@
//
:imagesdir: ../../images/
-== S7 Communication
+= S7 Communication
When communicating with S7 Devices there is a whole family of protocols, that can be used.
In general you can divide them into `Profinet` protocols and `S7 Comm` protocols.
The later are far simpler in structure, but also far less documented.
The `S7 Comm` protocols are generally split up into two flavours: The classic `S7 Comm` and a newer version unofficially called `S7 Comm Plus`.
-=== Overview of the Protocols
+== Overview of the Protocols
[ditaa,protocols-s7-osi]
....
@@ -83,7 +83,7 @@ The `S7 Comm` protocols are generally split up into two flavours: The classic `S
- - - - - - - - - - +-------------------------------------------------------------------------------------------------+ - -
....
-=== Protocol Descriptions
+== Protocol Descriptions
|===
|Name |ISO |RFC |Link
@@ -96,7 +96,7 @@ The `S7 Comm` protocols are generally split up into two flavours: The classic `S
|DCOM |- |- | https://msdn.microsoft.com/library/cc201989.aspx
|===
-=== Interaction with an S7 PLC
+== Interaction with an S7 PLC
Currently we are concentrating on implementing the TCP-based variants of the `S7 Comm` and `S7 Comm Plus` protocols.
Both are transferred using `ISO TP` which is wrapped by `ISO on TCP`.
@@ -140,7 +140,7 @@ Each message is called a `TPDU` (Transport Protocol Data Unit):
Notice: There is no `Disconnect Response` in `ISO TP: Class 0`.
-==== Connection Request TPDU
+=== Connection Request TPDU
// len (length of bits - use instead of explicit byte count - requires "*" as first element)
// label
@@ -198,11 +198,11 @@ Legend:
- [protocolId]#Part of the packet that identifies the type of request#
- [protocolParameter]#Variable Parts of the ISO Transport Protocol Packet Header#
-==== Connection Response TPDU
+=== Connection Response TPDU
The `Connection Response` is identical to the `Connection Request` with the only difference that the `TPDU-Code` has a code of `0xD0`.
-==== Data TPDU
+=== Data TPDU
// len (length of bits - use instead of explicit byte count - requires "*" as first element)
// label
diff --git a/src/site/asciidoc/protocols/s7/s7comm-plus.adoc b/src/site/asciidoc/protocols/s7/s7comm-plus.adoc
index 529500a5f1..2c1f8fa775 100644
--- a/src/site/asciidoc/protocols/s7/s7comm-plus.adoc
+++ b/src/site/asciidoc/protocols/s7/s7comm-plus.adoc
@@ -16,7 +16,7 @@
//
:imagesdir: ../../images/
-== S7 Comm Plus (0x72)
+= S7 Comm Plus (0x72)
The `S7 Comm Plus` protocol is a new version of the original `S7 Comm` protocol.
While a `S7 Comm` packet is identified, by the magic byte `0x32`, the `S7 Comm Plus` packet uses the magic byte `0x72`.
diff --git a/src/site/asciidoc/protocols/s7/s7comm.adoc b/src/site/asciidoc/protocols/s7/s7comm.adoc
index 3b97a43ef3..3d25f6d9aa 100644
--- a/src/site/asciidoc/protocols/s7/s7comm.adoc
+++ b/src/site/asciidoc/protocols/s7/s7comm.adoc
@@ -16,9 +16,9 @@
//
:imagesdir: ../../images/
-== S7 Comm (0x32)
+= S7 Comm (0x32)
-=== General
+== General
While a lot of information was available on the general structure of S7 communication, only little information was available on the constant values this protocol uses.
If information was available, this was mostly provided with a GPL license and therefore was disqualified for being used in this project.
@@ -30,7 +30,7 @@ As soon as a valid value was found the tool then output the detected constant va
The tool for generating this is located in the `plc4j/protocols/s7-utils` project.
-=== Structure of a Setup Communication Request
+== Structure of a Setup Communication Request
[packetdiag,s7-setup-communication-request,svg]
....
@@ -78,7 +78,7 @@ Legend:
- [protocolId]#Part of the packet that identifies the type of request#
- [protocolParameter]#Variable Parts of the ISO Transport Protocol Packet Header#
-=== Structure of a Setup Communication Response
+== Structure of a Setup Communication Response
The `Setup Communication Response` is identical to the `Setup Communication Request` with the only difference that the `Message Type` has an ACK_DATA code of `0x03`.
@@ -88,7 +88,7 @@ The values might be lower than in the request, but never higher.
TIP: One thing about `Setup Communication Responses` which is kind of strange, is that usually S7 response messages have additional `error class` and `error code` fields, which this type of response doesn't seem to have.
-=== Sizes of requests
+== Sizes of requests
During the connection to a S7 PLC the client and PLC agree on 3 important parameters:
@@ -134,7 +134,7 @@ Same should sometimes be possible in the other direction.
So if we wanted to read 300 bytes with a 256 byte TPDU size, the driver would split this up into two smaller byte arrays and internally merge them. However when reading Real (Number) values there could be issues with this.
However in this case the driver has to completely take care of this optimization.
-=== Links
+== Links
Providing some additional information without directly being used:
diff --git a/src/site/asciidoc/users/adopters.adoc b/src/site/asciidoc/users/adopters.adoc
index da17829a85..4b2d61652d 100644
--- a/src/site/asciidoc/users/adopters.adoc
+++ b/src/site/asciidoc/users/adopters.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../images/
:icons: font
-== Companies using Apache PLC4X
+= Companies using Apache PLC4X
image::toddy-loves-apache.png[width=200,float=left]
diff --git a/src/site/asciidoc/users/blogs-videos-and-slides.adoc b/src/site/asciidoc/users/blogs-videos-and-slides.adoc
index bd591e4bfb..dc0f1e524b 100644
--- a/src/site/asciidoc/users/blogs-videos-and-slides.adoc
+++ b/src/site/asciidoc/users/blogs-videos-and-slides.adoc
@@ -15,15 +15,15 @@
// limitations under the License.
//
-== Blogs, Videos and Slides on Apache PLC4X
+= Blogs, Videos and Slides on Apache PLC4X
-=== Blog posts
+== Blog posts
- https://medium.com/@megachucky/apache-kafka-ksql-and-apache-plc4x-for-iiot-data-integration-and-processing-472c2de6700b[Apache Kafka, KSQL and Apache PLC4X for IIoT Data Integration and Processing]
- https://blog.codecentric.de/2018/06/edge-computing-industrial-iot-apache-edgent-apache-plc4x/[Edge Computing und Industrial IoT mit Apache Edgent und Apache PLC4X]
- https://riot.community/examples/http-plc4x.html[Advanced: Exposing a PLC as JSON Web Services (using PLC4X)]
-=== Videos & Webinars
+== Videos & Webinars
- https://youtu.be/1vf3zw7HQws[High Security Iiot Communication With Apache Plc4X, Apache Asia Con, August 2021]
- https://youtu.be/ogsFTnQhtIU[Apache Plc4X For Can Bus And Canopen, Apache Asia Con, August 2021]
@@ -39,7 +39,7 @@
- https://aceu19.apachecon.com/session/idea-apache-tlp[From an idea to an Apache TLP]
- https://mediathek.hhu.de/watch/6014a3fd-aadf-4bcf-adf6-3134162aef1b[Wie wir mit Apache PLC4X die Silos in der Automatisierungsindustrie aufbechen]
-=== Slides
+== Slides
- https://de.slideshare.net/KaiWaehner/iiot-industry-40-with-apache-kafka-connect-ksql-apache-plc4x[Apache Kafka, KSQL and Apache PLC4X for IIoT Data Integration and Processing]
- https://de.slideshare.net/ChristoferDutz/episode-iv-a-new-hope-229731756[Episode iv a new hope - Industry 4.0 done our way]
diff --git a/src/site/asciidoc/users/commercial-support.adoc b/src/site/asciidoc/users/commercial-support.adoc
index ed80b9e0af..f6adaf3e5c 100644
--- a/src/site/asciidoc/users/commercial-support.adoc
+++ b/src/site/asciidoc/users/commercial-support.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../images/
:icons: font
-== Commercial support offerings for Apache PLC4X
+= Commercial support offerings for Apache PLC4X
image::toddy-loves-apache.png[width=200,float=left]
@@ -40,11 +40,11 @@ a|image::users/companies/logo-timecho.png[timecho, 200, 200] |https://www.timec
|===
-=== Who can be added to this list?
+== Who can be added to this list?
Anyone who provides `Apache PLC4X` related services can be added to this list (e.g. training, consulting, custom software development, support, installation or related services).
-=== How can I get added to this list?
+== How can I get added to this list?
Please create a Pull-Request on GitHub as described https://plc4x.apache.org/developers/contributing.html[here]. The resource requiring editing can be found https://github.com/apache/plc4x/blob/develop/src/site/asciidoc/users/commercial-support.adoc[here]
diff --git a/src/site/asciidoc/users/download.adoc b/src/site/asciidoc/users/download.adoc
index cf1edee462..c0436e5b65 100644
--- a/src/site/asciidoc/users/download.adoc
+++ b/src/site/asciidoc/users/download.adoc
@@ -15,11 +15,11 @@
// limitations under the License.
//
-== Download
+= Download
Be sure to verify your downloads by these https://www.apache.org/info/verification[procedures] using these https://downloads.apache.org/plc4x/KEYS[KEYS] for any Apache release.
-=== Current Releases
+== Current Releases
==== 0.12.0 Official https://www.apache.org/dyn/closer.lua/plc4x/0.12.0/apache-plc4x-0.12.0-source-release.zip[source release] [ https://downloads.apache.org/plc4x/0.12.0/apache-plc4x-0.12.0-source-release.zip.sha512[SHA512] ] [ https://downloads.apache.org/plc4x/0.12.0/apache-plc4x-0.12.0-source-release.zip.asc[ASC] ]
@@ -32,7 +32,7 @@ This release was mainly a release containing many bugfixes. We literally halved
- Which of these configuration options are required?
- The same set of information is also available for the transports a driver is using.
-===== New Features
+==== New Features
- API: Made several bits of information available via the API
allowing tools to provide more content assist when dealing
@@ -45,7 +45,7 @@ and Simulated drivers.
- The OPC-UA Java driver now support certificate-based
authentication and encryption.
-===== Incompatible changes
+==== Incompatible changes
- Java 8 is no longer officially supported and Java 11 is the
new base-line.
@@ -60,7 +60,7 @@ new base-line.
config options in the connection-string was updated to be
now prefixed with the transport name the option belongs to.
-===== Bug Fixes
+==== Bug Fixes
- S7: Several bugs and issues regarding supporting various
duration, date and time data-types.
@@ -71,7 +71,7 @@ numbers.
improved.
- Core: Fixed several leaks of open threads.
-=== Previous Releases
+== Previous Releases
==== 0.11.0 Official https://archive.apache.org/dist/plc4x/0.11.0/apache-plc4x-0.11.0-source-release.zip[source release] [ https://downloads.apache.org/plc4x/0.11.0/apache-plc4x-0.11.0-source-release.zip.sha512[SHA512] ] [ https://downloads.apache.org/plc4x/0.11.0/apache-plc4x-0.10.0-source-release.zip.asc[ASC] ]
@@ -79,7 +79,7 @@ The APIs have been streamlined in a preparation for a hopefully soon 1.0.0 relea
Many drivers have been re-implemented with much more features.
Integration modules have been improved.
-===== New Features
+==== New Features
- Implemented a `PLC4X-Server` and `PLC4X-Driver` that allows
using the server as a proxy for communicating with PLCs.
@@ -92,7 +92,7 @@ communication, which however can be tunneled through a
- The KNX driver in Java now supports reading "knxproj" files
exported from the new ETS version 6.
-===== Bug Fixes
+==== Bug Fixes
- The name of the Modbus TCP driver was changed from "modbus"
to "modbus-tcp".
@@ -121,7 +121,7 @@ This is a bugfix release aiming at directly fixing CVE-2021-43083 as well as upd
Please note that CVE-2021-43083 only affects the PLC4C part of PLC4X.
-===== Bug Fixes
+==== Bug Fixes
CVE-2021-43083 Apache PLC4X 0.9.0 Buffer overflow in PLC4C via crafted server response
@@ -132,7 +132,7 @@ This is an ordinary PLC4X release, containing changes that
accumulated over time. It doesn't have an explicit focus on
a particular topic.
-===== New Features
+==== New Features
- The OPC UA driver has been replaced with a native driver. Previously
Eclipse Milo was being used.
@@ -143,9 +143,9 @@ Eclipse Milo was being used.
- Major cleanup of PLC4C
- S7 Driver now supports event and alarm handling on some S7 models
-===== Incompatible changes
+==== Incompatible changes
-===== Bug Fixes
+==== Bug Fixes
PLC4X-200 OPC-UA Driver not connecting if params string is not provided
PLC4X-201 OPC-UA PlcList underlying type not compatible with Eclipse Milo
@@ -168,7 +168,7 @@ This is an ordinary PLC4X release, containing changes that
accumulated over time. It doesn't have an explicit focus on
a particular topic.
-===== New Features
+==== New Features
- The KNXnet/IP Driver now supports writing of values.
- The Modbus driver now supports more common notations of Modbus addresses using a pure-numeric notation.
@@ -177,7 +177,7 @@ a particular topic.
- Integration with the Milo OPC UA Server is now available.
- Kafka Connect workers have been updated source and sink connectors are now included.
-===== Incompatible changes
+==== Incompatible changes
- The syntax of the S7 addresses changed slightly allowing to provide a string length. Without this, a STRING datatype will read 254 characters, by adding the size in round brackets to the type name will use the specified number.
@@ -191,7 +191,7 @@ a particular topic.
- The PLCValue types have been refactored to align with the types defined in IEC 61131-3 (https://en.wikipedia.org/wiki/IEC_61131-3) directly using the older Java types (PlcBoolean) is no longer possible.
-===== Bug Fixes
+==== Bug Fixes
A lot of testing was done regarding the IEC 61131-3 data-types.
This resulted in numerous bugfixes in many protocols.
@@ -226,7 +226,7 @@ core. All previous driver versions are now considered deprecated
and have been replaced by versions using the new driver structure
and generated driver codebase.
-===== New Features
+==== New Features
- Drivers now support structured types using PlcValues
- The EIP (EtherNet/IP) driver no longer requires an external
@@ -242,7 +242,7 @@ significant performance gains when writing multiple vlaues)
to be able to use them in an OSGi container.
- New Firmata protocol driver
-===== Incompatible changes
+==== Incompatible changes
- Due to the refactoring of the driver core there might be issues
running drivers built against older core versions.
@@ -255,7 +255,7 @@ https://plc4x.apache.org/users/protocols/s7.html
- The karaf-feature modules are removed as the drivers now all
provide both a feature.xml as well as a `kar` bundled archive
-===== Bug Fixes
+==== Bug Fixes
- PLC4X-174 UDP Transport does not accept ports containing 0
- PLC4X-134 S7 is terminating the connection during handshake
@@ -271,16 +271,16 @@ most users have switched to 0.7 and above (with generated drivers).
If you are using the S7 Driver you should update to this Version
as the critical (memory leak) bug PLC4X-163 is fixed.
-===== New Features
+==== New Features
- PLC4X-168 A shorter S7 Field Syntax is Introduced.
This release contains no further features and mostly stabilization.
-===== Incompatible changes
+==== Incompatible changes
- Moved the C++, C# and Python drivers into the `sandbox`
-===== Bug Fixes
+==== Bug Fixes
- Fixed Promise Chain for InternalPlcWriteRequest
- PLC4X-45 Add float support to Modbus Protocol
@@ -294,7 +294,7 @@ This release contains no further features and mostly stabilization.
This is the first release containing our new generated drivers (AB-ETH)
-===== New Features
+==== New Features
- Implemented a new Apache Kafka Connect integration module
- Implemented a new Apache NiFi integration module
@@ -307,9 +307,9 @@ Sandbox (Beta-Features)
- Implemented a new BACnet/IP passive mode driver
- Implemented a new Serial DF1 driver
-===== Incompatible changes
+==== Incompatible changes
-===== Bug Fixes
+==== Bug Fixes
- PLC4X-104 S7 Driver Datatype TIME_OF_DAY causes ArrayOutOfBoundException
- PLC4X-134 S7 is terminating the connection during handshake
@@ -322,7 +322,7 @@ Sandbox (Beta-Features)
This is the first release of Apache PLC4X as top-level project.
-===== New Features
+==== New Features
- The PlcConnection now supports a `ping` method to allow checking if an existing connection is still alive.
- Support of the OPC-UA protocol with the `opc-ua-driver`.
@@ -331,25 +331,25 @@ This is the first release of Apache PLC4X as top-level project.
-- Added first versions of a Python PLC4X API (`plc4py`)
- Added an Interop server which allows to relay requests from other languages to a Java Server
-===== Incompatible changes
+==== Incompatible changes
- ElasticSearch example was updated to use ElasticSearch 7.0.1, this might cause problems with older Kibana versions.
-===== Bug Fixes
+==== Bug Fixes
-=== Incubating Releases
+== Incubating Releases
==== 0.3.1 (incubating) Official https://archive.apache.org/dist/incubator/plc4x/0.3.1-incubating/apache-plc4x-incubating-0.3.1-source-release.zip[source release] [ https://archive.apache.org/dist/incubator/plc4x/0.3.1-incubating/apache-plc4x-incubating-0.3.1-source-release.zip.sha512[SHA512] ] [ https://archive.apache.org/dist/incubator/plc4x/0.3.1-incubating/apache-plc4x-incubating-0.3.1-source-release.zip.asc[ASC] ]
-===== New Features
+==== New Features
- No new features
-===== Incompatible changes
+==== Incompatible changes
- No incompatible changes.
-===== Bug Fixes
+==== Bug Fixes
- The S7 driver didn't correctly handle "fill-bytes" in multi-item read-responses and multi-item write-requests
- Fixed NPE when reading odd-length array of one-byte base types
@@ -359,7 +359,7 @@ This is the first release of Apache PLC4X as top-level project.
[#release-0_3_0]
==== 0.3.0 (incubating) Official https://archive.apache.org/dist/incubator/plc4x/0.3.0-incubating/apache-plc4x-incubating-0.3.0-source-release.zip[source release] [ https://archive.apache.org/dist/incubator/plc4x/0.3.0-incubating/apache-plc4x-incubating-0.3.0-source-release.zip.sha512[SHA512] ] [ https://archive.apache.org/dist/incubator/plc4x/0.3.0-incubating/apache-plc4x-incubating-0.3.0-source-release.zip.asc[ASC] ]
-===== New Features
+==== New Features
- Object PLC Mapping (OPM) now has a Alias Registry to allow
variable substitution at runtime and write support
@@ -368,7 +368,7 @@ This is the first release of Apache PLC4X as top-level project.
- New integration `apache-karaf` to enable plc4j in a karaf
runtime environment
-===== Incompatible changes
+==== Incompatible changes
- The 'plc4j-core' module has been merged into 'plc4j-api'.
So there is no 'plc4j-core' module anymore. Just remove that
@@ -377,7 +377,7 @@ This is the first release of Apache PLC4X as top-level project.
a `plc4j-protocol-{name}` you now need to change this to
`plc4j-driver-{name}`
-===== Bug Fixes
+==== Bug Fixes
- Fixing dependency to the wrap url-handler
- When receiving responses with more than 512 byte, the IsoOnTcp protocol doesn't work
@@ -388,7 +388,7 @@ This is the first release of Apache PLC4X as top-level project.
[#release-0_2_0]
==== 0.2.0 (incubating) Official https://archive.apache.org/dist/incubator/plc4x/0.2.0-incubating/apache-plc4x-incubating-0.2.0-source-release.zip[source release] [ https://archive.apache.org/dist/incubator/plc4x/0.2.0-incubating/apache-plc4x-incubating-0.2.0-source-release.zip.sha512[SHA512] ] [ https://archive.apache.org/dist/incubator/plc4x/0.2.0-incubating/apache-plc4x-incubating-0.2.0-source-release.zip.asc[ASC] ]
-===== Changes:
+==== Changes:
* Changed API: instead of passing request object to `read({read-request})`, `write({write-request})` or `subscribe({subscribe-request})` methods now the `execute()` method is called on the request itself
* New Connection Pool component
diff --git a/src/site/asciidoc/users/getting-started/general-concepts.adoc b/src/site/asciidoc/users/getting-started/general-concepts.adoc
index 0df85ea25c..bb5d70e175 100644
--- a/src/site/asciidoc/users/getting-started/general-concepts.adoc
+++ b/src/site/asciidoc/users/getting-started/general-concepts.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== General Concepts
+= General Concepts
On this page we'll give a short introduction to the most important concepts that will help you understand Apache PLC4X better.
@@ -33,7 +33,7 @@ Both are pretty dependent on the type of device you are planning to communicate
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
+== Connections
In general a connection is a physical or logical connection between two endpoints.
@@ -65,7 +65,7 @@ From a driver point of view there is actually no difference between a `Raw Socke
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
+=== Connection Strings
A fully qualified PLC4X connection string would look like this:
@@ -103,7 +103,26 @@ The shortest version of a fully qualified connection string would look something
For more information on the default settings for a given protocol or transport, please check the corresponding drivers documentation.
-=== Individual Resource Addresses (Tags)
+== 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 link:../protocols/index.html[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.
+
+
diff --git a/src/site/asciidoc/users/getting-started/index.adoc b/src/site/asciidoc/users/getting-started/index.adoc
index 41f0a5b72e..c634db80e1 100644
--- a/src/site/asciidoc/users/getting-started/index.adoc
+++ b/src/site/asciidoc/users/getting-started/index.adoc
@@ -15,14 +15,14 @@
// limitations under the License.
//
-== Getting Started
+= Getting Started
Depending on the programming language, the usage will differ, therefore please go to the `Getting Started` version of the language of choice.
-=== Go/Golang
+== Go/Golang
For guides on how to write PLC4X applications with Go, please go to the link:plc4go.html[Go Getting Started]
-=== Java
+== Java
For guides on how to write PLC4X applications with Java, please go to the link:plc4j.html[Java Getting Started]
\ No newline at end of file
diff --git a/src/site/asciidoc/users/getting-started/plc4c.adoc b/src/site/asciidoc/users/getting-started/plc4c.adoc
index 358f781bb2..99327ed3d4 100644
--- a/src/site/asciidoc/users/getting-started/plc4c.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4c.adoc
@@ -15,4 +15,4 @@
// limitations under the License.
//
-== Getting Started with C
\ No newline at end of file
+= Getting Started with C
\ No newline at end of file
diff --git a/src/site/asciidoc/users/getting-started/plc4cs.adoc b/src/site/asciidoc/users/getting-started/plc4cs.adoc
index 465c1a4436..f476a8b89a 100644
--- a/src/site/asciidoc/users/getting-started/plc4cs.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4cs.adoc
@@ -15,4 +15,4 @@
// limitations under the License.
//
-== Getting Started with C#
\ No newline at end of file
+= Getting Started with C#
\ No newline at end of file
diff --git a/src/site/asciidoc/users/getting-started/plc4go.adoc b/src/site/asciidoc/users/getting-started/plc4go.adoc
index 105b2245df..672ae5b48d 100644
--- a/src/site/asciidoc/users/getting-started/plc4go.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4go.adoc
@@ -15,9 +15,9 @@
// limitations under the License.
//
-== Getting Started with Go
+= Getting Started with Go
-=== Initializing a dummy project
+== Initializing a dummy project
Just in case you want to get started with `Go`. In this part we'll setup a new `Go` project.
If you are familiar with this, you can go to the next chapter.
@@ -58,7 +58,7 @@ You will execute your first `Go` progran ... however the output is rather underw
You're now ready to continue.
-=== Using the PLC4Go API directly
+== Using the PLC4Go API directly
In order to write a valid PLC4X Go application, all you need, is to add a dependency to the `plc4go module`.
Now all you need to do, is execute the following command:
@@ -77,7 +77,7 @@ Perhaps we'll change this in the future, but for now all comes in one bundle.
Now you're generally set to start writing your first `PLC4Go` program.
-==== Connecting to a PLC
+=== Connecting to a PLC
In contrast to PLC4J, which uses the service lookup to find the `transports` and the `drivers` automatically, in `PLC4Go` they need to be manually registered at the driver manager.
diff --git a/src/site/asciidoc/users/getting-started/plc4j.adoc b/src/site/asciidoc/users/getting-started/plc4j.adoc
index c98d7feda1..5f4a3eeff7 100644
--- a/src/site/asciidoc/users/getting-started/plc4j.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4j.adoc
@@ -15,9 +15,9 @@
// limitations under the License.
//
-== Getting Started with Java
+= Getting Started with Java
-=== Using the PLC4J API directly
+== Using the PLC4J API directly
In order to write a valid PLC4X Java application, all you need, is to add a dependency to the `api module`.
When using Maven, all you need to do is add this dependency:
@@ -79,7 +79,7 @@ But there are some cases in which we can't simulate or features are simply disab
Therefore, we use metadata to check programmatically, if a given feature is available.
-==== Reading Data
+=== Reading Data
----
// Check if this connection support reading of data.
@@ -185,7 +185,7 @@ PLC4X provides getters and setters for a wide variety of Java types and automati
However, when for example trying to get a long-value as a byte and the long-value exceeds the range supported by the smaller type, a `RuntimeException` of type `PlcIncompatibleDatatypeException`.
In order to avoid causing this exception to be thrown, however there are `isValid{TypeName}` methods that you can use to check if the value is compatible.
-==== Writing Data
+=== Writing Data
In general the structure of code for writing data is extremely similar to that of reading data.
@@ -241,7 +241,7 @@ for (String tagName : response.getTagNames()) {
}
----
-==== Subscribing to Data
+=== Subscribing to Data
Subscribing to data can be considered similar to reading data, at least the subscription itself if very similar to reading of data.
diff --git a/src/site/asciidoc/users/getting-started/plc4py.adoc b/src/site/asciidoc/users/getting-started/plc4py.adoc
index f2e0411e3f..37a2df7070 100644
--- a/src/site/asciidoc/users/getting-started/plc4py.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4py.adoc
@@ -15,9 +15,9 @@
// limitations under the License.
//
-== Getting Started with Python
+= Getting Started with Python
-=== Using the PLC4PY API directly
+== Using the PLC4PY API directly
Currently, you need to install PLC4Py from the GitHub repository instead of pypi.
Once we have decided that PLC4Py is in a position to release we will publish to pypi.
@@ -81,7 +81,7 @@ But there are some cases in which we can't simulate or features are simply disab
Therefore, we use metadata to check programmatically, if a given feature is available.
-==== Reading Data
+=== Reading Data
----
@@ -163,7 +163,7 @@ As all PlcValue items support the len property, the user can check how many item
You can then treat the values in the PlcList as a list using response.tags[tag_name].value.get_list()
-==== Writing Data
+=== Writing Data
In general the structure of code for writing data is extremely similar to that of reading data.
@@ -210,6 +210,6 @@ for tag_name in response.tag_names:
logger.error("Error[" + tag_name + "]: " + response.tags[tag_name].name())
----
-==== Subscribing to Data
+=== Subscribing to Data
Coming Soon
diff --git a/src/site/asciidoc/users/getting-started/using-snapshots.adoc b/src/site/asciidoc/users/getting-started/using-snapshots.adoc
index b6a29a126d..3044ef838b 100644
--- a/src/site/asciidoc/users/getting-started/using-snapshots.adoc
+++ b/src/site/asciidoc/users/getting-started/using-snapshots.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Using SNAPSHOT versions
+= Using SNAPSHOT versions
Especially when it comes to trying to verify if an issue you are facing has already been fixed in the development version, you might want to or be asked to try out the absolute latest version of PLC4X. You can generally do this by adding "-SNAPSHOT" to the version number of PLC4X.
diff --git a/src/site/asciidoc/users/getting-started/virtual-modbus.adoc b/src/site/asciidoc/users/getting-started/virtual-modbus.adoc
index 5da29851b7..8aa9b815e6 100644
--- a/src/site/asciidoc/users/getting-started/virtual-modbus.adoc
+++ b/src/site/asciidoc/users/getting-started/virtual-modbus.adoc
@@ -16,7 +16,7 @@
//
:imagesdir: ../../images/
-== Playing around with Apache PLC4X with a virtual Modbus PLC
+= Playing around with Apache PLC4X with a virtual Modbus PLC
If you want to get started with Apache PLC4X, but don't have any PLC at hand, this tutorial will demonstrate how you can use a virtual `Modbus Slave` software to simulate communication with `Modbus` enabled PLCs.
@@ -24,7 +24,7 @@ Such a fully open-source software is `ModbusPal` which is available from http://
All you need, is to download the file called `ModbusPal.jar`.
-=== Setting up the virtual Modbus Slave
+== Setting up the virtual Modbus Slave
In order to run the software, you just need to execute the following command in the same directory you downloaded the Jar to:
diff --git a/src/site/asciidoc/users/index.adoc b/src/site/asciidoc/users/index.adoc
index 53694a2022..004459b733 100644
--- a/src/site/asciidoc/users/index.adoc
+++ b/src/site/asciidoc/users/index.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../images/
:icons: font
-== Users
+= Users
This part of the PLC4X website is dedicated to people wanting to use Apache PLC4X.
diff --git a/src/site/asciidoc/users/industry40.adoc b/src/site/asciidoc/users/industry40.adoc
index a918c8cbd3..5c6243df45 100644
--- a/src/site/asciidoc/users/industry40.adoc
+++ b/src/site/asciidoc/users/industry40.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Industry 4.0 with Apache
+= Industry 4.0 with Apache
Since the introduction of programmable logic controllers in the production industry in the early 80s, they have been the core of almost every piece of production machinery.
@@ -32,7 +32,7 @@ Most of the biggest changes in how we create modern IT systems is a result of th
Unfortunately the production industry has been missing a lot of this innovation.
Only a small number of companies today use open source software in their production systems.
-=== Benefits of using open source
+== Benefits of using open source
The benefit of using open source could be huge:
@@ -42,21 +42,21 @@ The benefit of using open source could be huge:
* Improved Security
* Great Cost reduction
-==== Increased Flexibility
+=== Increased Flexibility
If a company had decided to use PLCs and control systems of a certain vendor, it is almost impossible to change this decision.
This reduces the options available when adding new machinery or replacing existing ones.
Technologically speaking, also the company can only use the options and solution it's vendor is able to provide.
-==== Increased Stability
+=== Increased Stability
Current control systems are usually based on the concept of "backup systems".
If the main control system fails, all activity is switched to the standby system.
When using modern public- or private cloud systems, there is no need for a backup system, because the cluster is designed in a way that it can live with the failure of most of its hosts before loosing the ability to function.
-==== Increased Extendability
+=== Increased Extendability
From the perspective of designing and scaling the IT infrastructure:
If a control system was designed to handle the current size of plant, for cost reasons the IT infrastructure isn't designed to handle much more than that.
@@ -65,14 +65,14 @@ Now if the plant should be extended in the future, extending it's control-system
By utilizing modern virtualization frameworks, extending the existing cloud solution, would only require adding more compute resources, by adding more systems to the cluster and it should be possible to extend the existing system without problems.
If the company decided to utilize a public cloud provider, it makes things even simpler, as it would only require booking more resources.
-==== Improved Security
+=== Improved Security
This is probably one of the most concerning aspects of modern production control systems.
Right now, in order to run these systems, a lot of the most popular solutions require companies to run not up to date systems.
If applying all updates, the company is risking either loss of commercial support or even loss of functionality.
Therefore an attacker can probably be certain to be able to exploit certain vulnerabilities just by knowing the type and version of the used control system.
-==== Cost Reduction
+=== Cost Reduction
Well the probably biggest and most obvious cost reduction factor is definitely, that if the software you are using is free, you will not have to pay for it.
@@ -80,7 +80,7 @@ Additionally, the ability to get the computing power of one insanely expensive s
Being freed of the requirement to stick to the products of one vendor alone and to be able to choose the technology and the vendor of used systems freely will definitely also reduce costs.
-=== Options to communicating with PLCs
+== Options to communicating with PLCs
In general there are two options for communicating with industrial PLCs:
diff --git a/src/site/asciidoc/users/integrations/apache-calcite.adoc b/src/site/asciidoc/users/integrations/apache-calcite.adoc
index e8a37d02ea..83c0d31c21 100644
--- a/src/site/asciidoc/users/integrations/apache-calcite.adoc
+++ b/src/site/asciidoc/users/integrations/apache-calcite.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== Apache Calcite
+= Apache Calcite
https://calcite.apache.org/[Apache Calcite]
Standard SQL
diff --git a/src/site/asciidoc/users/integrations/apache-camel.adoc b/src/site/asciidoc/users/integrations/apache-camel.adoc
index b65f751ef9..31e0026e70 100644
--- a/src/site/asciidoc/users/integrations/apache-camel.adoc
+++ b/src/site/asciidoc/users/integrations/apache-camel.adoc
@@ -17,6 +17,6 @@
:imagesdir: ../../images/
:icons: font
-== Apache Camel
+= Apache Camel
The Camel Component for PLC4X allows you to create routes using the PLC4X API to read from a PLC device or write to it.
This component is now maintained within the https://camel.apache.org/components/next/plc4x-component.html[Apache Camel] Project.
diff --git a/src/site/asciidoc/users/integrations/apache-edgent.adoc b/src/site/asciidoc/users/integrations/apache-edgent.adoc
index bfc713e1c4..3c90fb4ab4 100644
--- a/src/site/asciidoc/users/integrations/apache-edgent.adoc
+++ b/src/site/asciidoc/users/integrations/apache-edgent.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== Apache Edgent (Retired)
+= Apache Edgent (Retired)
diff --git a/src/site/asciidoc/users/integrations/apache-iotdb.adoc b/src/site/asciidoc/users/integrations/apache-iotdb.adoc
index 8c06996809..5e1a431f63 100644
--- a/src/site/asciidoc/users/integrations/apache-iotdb.adoc
+++ b/src/site/asciidoc/users/integrations/apache-iotdb.adoc
@@ -17,13 +17,13 @@
:imagesdir: ../../images/
:icons: font
-== Apache IotDB
+= Apache IotDB
Apache IoTDB is database for storing time serie data.
Therefore, it can be a good solution for managing the data which is collected by PLC4x.
-=== Data Model (Concept)
+== Data Model (Concept)
Given a PLC address and some fields, we can consider the PLC as a `device` in IoTDB, and each field
as a `measurement` in IoTDB. A couple of PLCs form a `storage group`.
@@ -32,7 +32,7 @@ For example, there is a virtual storage group `mi`, and a PLC `d1`, which has on
Then, in IoTDB, we can get a time series like `root.mi.d1.foo` (or `root.mi.d1.RANDOM_foo_Integer`, as you like).
Then, we can write data into IoTDB using JDBC with SQL or native API called session API.
-=== Example
+== Example
https://github.com/apache/plc4x-extras/tree/develop/plc4j/examples/hello-integration-iotdb shows an example
to collect data using PLC4x and then writing data to IoTDB.
diff --git a/src/site/asciidoc/users/integrations/apache-kafka.adoc b/src/site/asciidoc/users/integrations/apache-kafka.adoc
index 6a0a244573..00469f8882 100644
--- a/src/site/asciidoc/users/integrations/apache-kafka.adoc
+++ b/src/site/asciidoc/users/integrations/apache-kafka.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== https://kafka.apache.org/[Apache Kafka]
+= https://kafka.apache.org/[Apache Kafka]
Apache Kafka is an open-source distributed event streaming platform used by thousands of
companies for high-performance data pipelines, streaming analytics, data integration, and
diff --git a/src/site/asciidoc/users/integrations/apache-nifi.adoc b/src/site/asciidoc/users/integrations/apache-nifi.adoc
index abe7bd365d..97ba370957 100644
--- a/src/site/asciidoc/users/integrations/apache-nifi.adoc
+++ b/src/site/asciidoc/users/integrations/apache-nifi.adoc
@@ -17,13 +17,13 @@
:imagesdir: ../../images/
:icons: font
-== Apache NiFi
+= Apache NiFi
Apache NiFi allows creating systems that process data around the concept of data-streams.
Apache PLC4X provides both `Source` as well as `Sink` processors for accessing data in PLCs or writing data to them.
-=== Setting Up NiFi
+== Setting Up NiFi
Even if the documentation of NiFi states it works with any Java version above 1.8, this is not quite true.
@@ -40,7 +40,7 @@ As soon as you have started NiFi using the `nifi.sh run` or `run-nifi.bat` the W
It might take a few seconds for the Web-UI to show up ... so if you're getting errors in the browser, give it some time to start.
====
-=== Enabling PLC4X Processors in NiFi
+== Enabling PLC4X Processors in NiFi
In order to enable `Apache PLC4X` support in `Apache NiFi` all you need to do, is to copy our `nar` archive into the Nifi installations `lib` directory.
@@ -50,7 +50,7 @@ Or you can download a released version from Maven central: https://search.maven.
image::integrations/nifi/empty-nifi-flow.png[]
-=== Using a PLC4X Source Processor in NiFi
+== Using a PLC4X Source Processor in NiFi
Add a PLC4X Source processor to the canvas, click on the `Add processor` button and drag it into the canvas.
@@ -136,7 +136,7 @@ Now you should see an increasing number at the `Out` of the PLC4X Source and on
image::integrations/nifi/running-flow.png[]
-=== Enabling debugging
+== Enabling debugging
In order to be able to debug the PLC4X, please edit the `bin/nifi.sh` (On Mac & Linux) and comment in the line:
diff --git a/src/site/asciidoc/users/integrations/apache-streampipes.adoc b/src/site/asciidoc/users/integrations/apache-streampipes.adoc
index 7bf1ae05a9..4e85452919 100644
--- a/src/site/asciidoc/users/integrations/apache-streampipes.adoc
+++ b/src/site/asciidoc/users/integrations/apache-streampipes.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== Apache StreamPipes
+= Apache StreamPipes
https://streampipes.apache.org/docs/pe/org.apache.streampipes.connect.iiot.adapters.plc4x.s7[PLC4X S7 Adapter,opts=nofollow]
diff --git a/src/site/asciidoc/users/integrations/eclipse-ditto.adoc b/src/site/asciidoc/users/integrations/eclipse-ditto.adoc
index 4413b81982..e70e744225 100644
--- a/src/site/asciidoc/users/integrations/eclipse-ditto.adoc
+++ b/src/site/asciidoc/users/integrations/eclipse-ditto.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== Eclipse Ditto
+= Eclipse Ditto
… where IoT devices and their digital twins get together
https://www.eclipse.org/ditto/
diff --git a/src/site/asciidoc/users/integrations/eclipse-milo.adoc b/src/site/asciidoc/users/integrations/eclipse-milo.adoc
index 6107c9d82f..33b0b42557 100644
--- a/src/site/asciidoc/users/integrations/eclipse-milo.adoc
+++ b/src/site/asciidoc/users/integrations/eclipse-milo.adoc
@@ -15,12 +15,12 @@
// limitations under the License.
//
-== Introduction
+= Introduction
The PLC4X OPC UA server integration is based around the Eclipse Milo OPC UA server. It uses PLC4X to communicate with
industrial devices effectively acting as a industrial OPC UA gateway.
-== Building the server
+= Building the server
The OPC UA server can be built using maven as part of the PLC4X build.
```
@@ -30,7 +30,7 @@ mvn install
This creates a target directory within plc4x/plc4j/integrations/opcua-server containing a jar file which is the main java
executable.
-== Configuration File
+= Configuration File
The config.yml file is used to configure the server. The following root level settings should be configured.
@@ -93,7 +93,7 @@ tcpPort: 12687
httpPort: 8445
```
-== Running
+= Running
To run the java executable execute:-
```
diff --git a/src/site/asciidoc/users/integrations/index.adoc b/src/site/asciidoc/users/integrations/index.adoc
index f9ac3beba9..6e50951096 100644
--- a/src/site/asciidoc/users/integrations/index.adoc
+++ b/src/site/asciidoc/users/integrations/index.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== Integrations
+= Integrations
diff --git a/src/site/asciidoc/users/issues.adoc b/src/site/asciidoc/users/issues.adoc
index 13b44a1f37..1000e363e3 100644
--- a/src/site/asciidoc/users/issues.adoc
+++ b/src/site/asciidoc/users/issues.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Bug & Issue Tracker
+= Bug & Issue Tracker
Our bug & issue tracker is Github-Issues.
diff --git a/src/site/asciidoc/users/preparing-issues.adoc b/src/site/asciidoc/users/preparing-issues.adoc
index 1a73e204c7..e94365f7f8 100644
--- a/src/site/asciidoc/users/preparing-issues.adoc
+++ b/src/site/asciidoc/users/preparing-issues.adoc
@@ -15,5 +15,5 @@
// limitations under the License.
//
-== Preparing Issues & Bug Reports
+= Preparing Issues & Bug Reports
diff --git a/src/site/asciidoc/users/protocols/ab-eth.adoc b/src/site/asciidoc/users/protocols/ab-eth.adoc
index 391fea2b36..23a8c9583e 100644
--- a/src/site/asciidoc/users/protocols/ab-eth.adoc
+++ b/src/site/asciidoc/users/protocols/ab-eth.adoc
@@ -17,8 +17,8 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== AB-ETH
+= AB-ETH
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/ab-eth.adoc[]
diff --git a/src/site/asciidoc/users/protocols/ads.adoc b/src/site/asciidoc/users/protocols/ads.adoc
index db3aedcc3d..4416257381 100644
--- a/src/site/asciidoc/users/protocols/ads.adoc
+++ b/src/site/asciidoc/users/protocols/ads.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== ADS (Automation Device Specification)
+= ADS (Automation Device Specification)
image::ads_banner.png[banner,512,167]
The ADS (automation device specification) describes a device-independent and fieldbus independent interface for communication between Beckhoff automation devices running TwinCAT and other devices implementing this interface. https://www.home-assistant.io/integrations/ads/ Source (accessed 7 August 2022)
@@ -26,13 +26,13 @@ ADS device concept: https://infosys.beckhoff.com/english.php?content=../content/
Specification for ADS devices: https://infosys.beckhoff.com/english.php?content=../content/1033/ams_nat/4275563275.html&id= Source (accessed 7 August 2022)
-=== Structure AMS/TCP Packet
+== Structure AMS/TCP Packet
ADS (Automation Device Specification) is the TwinCAT communication protocol that specifies the interaction between two ADS devices. For example, it defines what operations can be executed on another ADS device, what parameters are necessary for that and what return value is sent after execution.
AMS (Automation Message Specification) specifies the exchange of the ADS data. A major component of the communication protocol is the AmsNetId. This is specified in the AMS/ADS package for the source and target device. An ADS device can be explicitly addressed using the AmsNetId.
Source https://infosys.beckhoff.com/english.php?content=../content/1033/ams_nat/4275563275.html&id= (accessed 7 August 2022)
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/ads.adoc[]
@@ -56,7 +56,7 @@ include::../../../plc4j/drivers/all/src/site/generated/ads.adoc[]
|===
-=== More details on
+== More details on
For details about the protocol look here: http://www.beckhoff.com/
& (German Handbook: https://download.beckhoff.com/download/Document/automation/twincat3/TwinCAT_3_ADS_INTRO_DE.pdf)
diff --git a/src/site/asciidoc/users/protocols/bacnet.adoc b/src/site/asciidoc/users/protocols/bacnet.adoc
index e49888e3ab..b05a3d87f5 100644
--- a/src/site/asciidoc/users/protocols/bacnet.adoc
+++ b/src/site/asciidoc/users/protocols/bacnet.adoc
@@ -17,13 +17,13 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== BACnet/IP
+= BACnet/IP
image::bacnet_banner.png[banner,512,167]
-=== BACnet (Building Automation and Control Networks)
+== BACnet (Building Automation and Control Networks)
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/bacnet-ip.adoc[]
@@ -47,6 +47,6 @@ include::../../../plc4j/drivers/all/src/site/generated/bacnet-ip.adoc[]
|===
-=== More details on
+== More details on
http://www.bacnet.org/[BACnet - A Data Communication Protocol for Building Automation and Control Networks]
\ No newline at end of file
diff --git a/src/site/asciidoc/users/protocols/c-bus.adoc b/src/site/asciidoc/users/protocols/c-bus.adoc
index a2ddbbd345..478c65c1f1 100644
--- a/src/site/asciidoc/users/protocols/c-bus.adoc
+++ b/src/site/asciidoc/users/protocols/c-bus.adoc
@@ -17,8 +17,8 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== C-Bus
+= C-Bus
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/c-bus.adoc[]
\ No newline at end of file
diff --git a/src/site/asciidoc/users/protocols/can.adoc b/src/site/asciidoc/users/protocols/can.adoc
index 062dbaa2c9..159be9ec10 100644
--- a/src/site/asciidoc/users/protocols/can.adoc
+++ b/src/site/asciidoc/users/protocols/can.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== CAN Bus Driver Adapter
+= CAN Bus Driver Adapter
image::can_banner.png[banner,512,167]
@@ -25,7 +25,7 @@ The CAN Bus driver is a special kind of driver which does not bring any logic.
Its responsibility is to combine link:../transports/can.html[CAN transport facade] and custom application layer protocols.
In this way, the protocol can use its own "root frame" type which is not delivered from CAN bus frame.
-=== More details on the driver
+== More details on the driver
The `CANDriverAdapter` is a full implementation of Apache PLC4X API.
Under the hood adapter will forward all operations to delegate driver.
diff --git a/src/site/asciidoc/users/protocols/canopen.adoc b/src/site/asciidoc/users/protocols/canopen.adoc
index 1f7345f0a7..87e56bb1d9 100644
--- a/src/site/asciidoc/users/protocols/canopen.adoc
+++ b/src/site/asciidoc/users/protocols/canopen.adoc
@@ -17,13 +17,13 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== CANopen
+= CANopen
image::can_banner.png[banner,512,167]
-=== CAN in Automation
+== CAN in Automation
CANopen is a specific protocol built on top of CAN bus.
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/canopen.adoc[]
@@ -46,7 +46,7 @@ include::../../../plc4j/drivers/all/src/site/generated/canopen.adoc[]
- It is possible to subscribe to CANopen NMT messages.
|===
-=== More details on the driver
+== More details on the driver
CAN, despite (or due) to its popularity has ambiguous meaning.
There are multiple articles and sources which attempts to give introduction, yet very few of them is consistent between each other.
@@ -75,7 +75,7 @@ The CANopen specification defines Object Dictionary (OD).
This driver does honor OD structure through usage of index and sub index for addressing fields.
It does not ship Electronic Data Sheet (EDS) parser leaving it for applications who wish to utilize it.
-=== Address Format
+== Address Format
CANopen specification defines several groups of addresses dedicated to certain kind of operations.
Critical services and message exchanges related with them have lower identifiers making them wining eventual bus access.
diff --git a/src/site/asciidoc/users/protocols/ctrlx.adoc b/src/site/asciidoc/users/protocols/ctrlx.adoc
index 872b743a66..e89db5f0ee 100644
--- a/src/site/asciidoc/users/protocols/ctrlx.adoc
+++ b/src/site/asciidoc/users/protocols/ctrlx.adoc
@@ -17,8 +17,8 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== CtlrX
+= CtlrX
-=== Connection String Options
+== Connection String Options
//include::../../../plc4j/drivers/all/src/site/generated/ctrlx.adoc[]
\ No newline at end of file
diff --git a/src/site/asciidoc/users/protocols/deltav.adoc b/src/site/asciidoc/users/protocols/deltav.adoc
index 2d3298de94..456487d70a 100644
--- a/src/site/asciidoc/users/protocols/deltav.adoc
+++ b/src/site/asciidoc/users/protocols/deltav.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== DeltaV
+= DeltaV
diff --git a/src/site/asciidoc/users/protocols/df1.adoc b/src/site/asciidoc/users/protocols/df1.adoc
index c93ff1d90e..19e04d7b84 100644
--- a/src/site/asciidoc/users/protocols/df1.adoc
+++ b/src/site/asciidoc/users/protocols/df1.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== DF1
+= DF1
diff --git a/src/site/asciidoc/users/protocols/eip.adoc b/src/site/asciidoc/users/protocols/eip.adoc
index f7bc997879..0ae30b47d0 100644
--- a/src/site/asciidoc/users/protocols/eip.adoc
+++ b/src/site/asciidoc/users/protocols/eip.adoc
@@ -17,13 +17,13 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== EtherNet/IP
+= EtherNet/IP
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/eip.adoc[]
-=== Address Format
+== Address Format
To read and write data to a PLC4X device, the EtherNet/IP driver uses symbolic segments.
This is used to refer to objects through their symbolic names. This makes reading data a lot easier, as you do not
@@ -44,7 +44,7 @@ To read and write data to a PLC4X device, the EtherNet/IP driver uses symbolic s
|DataType (writing) |Specify the Data-type of the value you want to write (mandatory)
|===
-==== Data Types
+=== Data Types
[cols="2" ,options="header"]
|===
|To store a|Use this data type
diff --git a/src/site/asciidoc/users/protocols/firmata.adoc b/src/site/asciidoc/users/protocols/firmata.adoc
index dea5f9ec21..42ef1c9601 100644
--- a/src/site/asciidoc/users/protocols/firmata.adoc
+++ b/src/site/asciidoc/users/protocols/firmata.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== Firmata
+= Firmata
The Firmata protocol is based on the MIDI protocol used for communicating with musical equipment.
@@ -25,7 +25,7 @@ It is also one of the most widely used protocols for communication with Arduino
This driver is built to be compatible with the `StandardFirmata Arduino Sketch` which can be found https://github.com/firmata/arduino/blob/master/examples/StandardFirmata/StandardFirmata.ino[here] (Version last changed on August 17th, 2017)
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/firmata.adoc[]
@@ -46,13 +46,13 @@ include::../../../plc4j/drivers/all/src/site/generated/firmata.adoc[]
NOTE: When subscribing to pins, these are configured to become read pins. When writing to digital pins, these are configured to become output pins. However, writing to pins for which a subscription exists, an exception will be thrown. In order to write to previously subscribed pins, all subscriptions for this have to be cancelled first.
-=== Individual Resource Address Format
+== Individual Resource Address Format
Similar to the Modbus protocol, the Firmata protocol support Boolean and Short values.
Booleans are used for the digital IO pins and short values for the analog inputs.
-==== Binary Addresses
+=== Binary Addresses
The full format for a digital address has the following format:
@@ -77,7 +77,7 @@ A normal `Arduino Uno` is equipped with 14 digital inputs: 0-13
WARNING: However in case of using the serial port (which will always be the case when using this driver), the pins 0 and 1 are the `RX` and `TX` pins of the serial port and can't be used.
-==== Analog Addresses
+=== Analog Addresses
The full format for an analog address is as follows:
diff --git a/src/site/asciidoc/users/protocols/genericcan.adoc b/src/site/asciidoc/users/protocols/genericcan.adoc
index 5633f2751f..da07b93742 100644
--- a/src/site/asciidoc/users/protocols/genericcan.adoc
+++ b/src/site/asciidoc/users/protocols/genericcan.adoc
@@ -17,16 +17,16 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== Generic CAN
+= Generic CAN
-=== CAN Bus semantics
+== CAN Bus semantics
This driver is a generic purpose driver.
It allows implementing a basic CAN bus listening or writing scenarios.
CAN bus open is a specific protocol built on top of CAN bus.
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/genericcan.adoc[]
@@ -46,7 +46,7 @@ include::../../../plc4j/drivers/all/src/site/generated/genericcan.adoc[]
|===
-=== More details on the driver
+== More details on the driver
Given popularity of CAN in multiple market segments there is variety of protocols which can't be published.
Also, for many cases which are data acquisition oriented it is necessary to tap only parts of communications.
@@ -55,7 +55,7 @@ This driver allows to model incoming and outgoing communication using plain Apac
The written CAN data is constructed from fields submitted via write request builder.
The receiving data is transformed in similar fashion, based on subscribed fields.
-==== Address format
+=== Address format
[cols="1,1a,1a,2a"]
|===
diff --git a/src/site/asciidoc/users/protocols/iec-60870.adoc b/src/site/asciidoc/users/protocols/iec-60870.adoc
index 5a87891f45..747c79cf4a 100644
--- a/src/site/asciidoc/users/protocols/iec-60870.adoc
+++ b/src/site/asciidoc/users/protocols/iec-60870.adoc
@@ -17,8 +17,8 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== IEC-60870
+= IEC-60870
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/iec-60870-5-104.adoc[]
\ No newline at end of file
diff --git a/src/site/asciidoc/users/protocols/index.adoc b/src/site/asciidoc/users/protocols/index.adoc
index 4bb5e16e54..4af0ec637f 100644
--- a/src/site/asciidoc/users/protocols/index.adoc
+++ b/src/site/asciidoc/users/protocols/index.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Current language support for protocols
+= Current language support for protocols
:icons: font
|===
|Protocol | C | C# | Go | Java | Python
@@ -169,7 +169,7 @@ Legend:
- icon:check[role="red"] Not implemented yet
- icon:question[role="red"] Unsure
-== Features
+= Features
:icons: font
The following table contains a list of operations and the protocols that support them:
diff --git a/src/site/asciidoc/users/protocols/knxnetip.adoc b/src/site/asciidoc/users/protocols/knxnetip.adoc
index 84d465031e..4e2522668a 100644
--- a/src/site/asciidoc/users/protocols/knxnetip.adoc
+++ b/src/site/asciidoc/users/protocols/knxnetip.adoc
@@ -17,14 +17,14 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== KNXnet/IP
+= KNXnet/IP
image::knx_banner.png[banner,512,167]
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/knxnet-ip.adoc[]
-=== Individual Resource Address Format
+== Individual Resource Address Format
KNX Addresses usually have one of the following structures:
diff --git a/src/site/asciidoc/users/protocols/logix.adoc b/src/site/asciidoc/users/protocols/logix.adoc
index db60c5f32d..77458b6b63 100644
--- a/src/site/asciidoc/users/protocols/logix.adoc
+++ b/src/site/asciidoc/users/protocols/logix.adoc
@@ -17,15 +17,15 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== Logix
+= Logix
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/logix.adoc[]
-=== Individual Resource Address Format
+== Individual Resource Address Format
-==== Connection String
+=== Connection String
Logix has the following connection string format:-
----
@@ -38,7 +38,7 @@ logix:tcp://127.0.0.1:502?communicationPath=[1,1]
Note the port and option fields are optional.
-==== General Format
+=== General Format
In general all Logix addresses have this format:
@@ -50,7 +50,7 @@ If the array-size part is omitted, the size-default of `1` is assumed.
If the data-type part is omitted, the data type from the controller is used
The address format matches that found in the controller.
-==== Data Types
+=== Data Types
The following data types are supported
diff --git a/src/site/asciidoc/users/protocols/modbus.adoc b/src/site/asciidoc/users/protocols/modbus.adoc
index 5f210f50c6..4c0d2bd46b 100644
--- a/src/site/asciidoc/users/protocols/modbus.adoc
+++ b/src/site/asciidoc/users/protocols/modbus.adoc
@@ -17,23 +17,23 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== Modbus (TCP/UDP/Serial)
+= Modbus (TCP/UDP/Serial)
-=== Connection String Options
+== Connection String Options
-==== Modbus TCP
+=== Modbus TCP
include::../../../plc4j/drivers/all/src/site/generated/modbus-tcp.adoc[]
-==== Modbus RTU
+=== Modbus RTU
include::../../../plc4j/drivers/all/src/site/generated/modbus-rtu.adoc[]
-==== Modbus ASCII
+=== Modbus ASCII
include::../../../plc4j/drivers/all/src/site/generated/modbus-ascii.adoc[]
-=== Supported Operations
+== Supported Operations
[cols="2,2a,5a"]
|===
@@ -48,9 +48,9 @@ include::../../../plc4j/drivers/all/src/site/generated/modbus-ascii.adoc[]
2+| `write`
|===
-=== Individual Resource Address Format
+== Individual Resource Address Format
-==== Connection String
+=== Connection String
Modbus has the following connection string format:-
----
@@ -63,7 +63,7 @@ modbus-tcp:tcp://127.0.0.1:502
Note the transport, port and option fields are optional.
-==== General Format
+=== General Format
In general all Modbus addresses have this format:
@@ -86,7 +86,7 @@ Specifying this value overrides value of `default-unit-id` parameter specified a
----
With this, can the default byte-order be overridden on a per-tag basis. If not provided the default-byte-order from the connection string is used, or BIG_ENDIAN, if this is also not provided.
-==== Memory Areas
+=== Memory Areas
There are a number of memory areas defined in the Modbus specification.
@@ -120,7 +120,7 @@ Address 610000 is then the first address in the second file record and so on. It
Using the extended-register: format you are able to reference all of these, if the shorter format is used then it is limited to 699999.
This memory area starts at address 0.
-==== Data Types
+=== Data Types
The following data types are supported
@@ -142,7 +142,7 @@ The following data types are supported
- CHAR (char)
- WCHAR (2 byte char)
-==== Some useful tips
+=== Some useful tips
Most memory areas start at address 1, except for the extended register area which starts at 0. These are both mapped to 0x0000 when it is sent in the Modbus protocol.
@@ -161,7 +161,7 @@ The following Modbus function codes are supported:-
- 0x14 (Read File Record)(Extended Register Read)
- 0x15 (Write File Record)(Extended Register Write)
-==== Examples
+=== Examples
To read 10 holding registers starting at address 20 and parse as Unsigned Integers the following examples are all valid.
diff --git a/src/site/asciidoc/users/protocols/opcua.adoc b/src/site/asciidoc/users/protocols/opcua.adoc
index 4116697e74..dd5bc8dc46 100644
--- a/src/site/asciidoc/users/protocols/opcua.adoc
+++ b/src/site/asciidoc/users/protocols/opcua.adoc
@@ -17,9 +17,9 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== OPC UA
+= OPC UA
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/opcua.adoc[]
@@ -34,7 +34,7 @@ include::../../../plc4j/drivers/all/src/site/generated/opcua.adoc[]
|===
-=== Connection String
+== Connection String
The OPC UA drivers uses the connection string
@@ -54,7 +54,7 @@ opcua:tcp://127.0.0.1:12686?discovery=true&username=admin&password=password
Note the transport, port and options fields are optional.
-=== Secure communication
+== Secure communication
The secure channel implementation within Apache PLC4X project have been tested against existing open source server implementations.
This includes Eclipse Milo (all modes) as well as OPC Foundation .NET server (except `Basic128Rsa15`).
Manual tests proven that driver is able to communicate with OPC UA server launched on PLCs as well as commercial simulators.
@@ -69,7 +69,7 @@ By default, this option is set to `SIGN_ENCRYPT` which imposes high security set
In case when additional diagnostics is needed payloads has to be traced through TRACE level log entries.
The `SIGN` mode gives possibility o browse packets in tools such wireshark.
-==== Certificate verification
+=== Certificate verification
The OPC UA specification defines its own procedures for certificate validation.
In order to simplify implementation by default server certificate validation is relaxed.
Unless explicitly disabled through configuration of `trustStoreFile` all server certificates will be accepted without validation.
@@ -77,7 +77,7 @@ Unless explicitly disabled through configuration of `trustStoreFile` all server
In case when secure communication is enabled the `trustStoreFile` option might be used to point certificates which client should accept.
The acceptance rely on regular TLS checks (expiry date, certificate path etc.), does not validate OPC UA specific parts such as application URI.
-==== Negotiation procedure
+=== Negotiation procedure
Depending on settings driver might or might not attempt to discover endpoints from remote server.
In case when `discovery` option is set to `true` driver will look up server certificate through connection attempt.
The discovery option also enables checks of server endpoints for matching security settings.
@@ -94,7 +94,7 @@ Usual values of `sendBufferSize` and `receiveBufferSize` PLC devices remain at 8
NOTE: Due to lack of complete implementation of negotiation and chunking logic the OPC UA driver prior Apache PLC4X 0.11 release could supply calls exceeding server limits.
-=== Address Format
+== Address Format
To read, write and subscribe to data, the OPC UA driver uses the variable declaration string of the OPC UA server it is
connecting to.
It includes the namespace(`ns`) of the hierarchy tree followed by the type of identifier string(`s`), numeric(`i`),
@@ -107,7 +107,7 @@ ns={namespace-index};[s|i|g|b]={Identifier};{Data Type}
----
-==== Data Types
+=== Data Types
The following data types are supported
@@ -132,7 +132,7 @@ The following data types are supported
- WSTRING (utf-16)
-==== Example of a valid OPC UA address:
+=== Example of a valid OPC UA address:
The following are examples of valid addresses
@@ -154,12 +154,12 @@ ns=2;g=09087e75-8e5e-499b-954f-f2a8624db28a;REAL
Note the Identifiers `s`,`i`,`b` and `g` specify the format of the address not the data type of the returned value.
-=== Some useful tips
+== Some useful tips
The namespace (e.g. `ns=2`) within the address is specific to the server you are connecting to.
-=== More details on OPC UA
+== More details on OPC UA
https://opcfoundation.org/about/opc-technologies/opc-ua/[OPC UA]
The OPC Unified Architecture (UA), released in 2008, is a platform independent service-oriented architecture that integrates all the functionality of the individual OPC Classic specifications into one extensible framework.
diff --git a/src/site/asciidoc/users/protocols/open-protocol.adoc b/src/site/asciidoc/users/protocols/open-protocol.adoc
index e9d8722579..eec5bbd709 100644
--- a/src/site/asciidoc/users/protocols/open-protocol.adoc
+++ b/src/site/asciidoc/users/protocols/open-protocol.adoc
@@ -17,8 +17,8 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== Open-Protocol (Torque-Tools)
+= Open-Protocol (Torque-Tools)
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/open-protocol.adoc[]
\ No newline at end of file
diff --git a/src/site/asciidoc/users/protocols/plc4x.adoc b/src/site/asciidoc/users/protocols/plc4x.adoc
index 82cda1c070..8a765cbf9e 100644
--- a/src/site/asciidoc/users/protocols/plc4x.adoc
+++ b/src/site/asciidoc/users/protocols/plc4x.adoc
@@ -17,13 +17,13 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== PLC4X (Proxy) (TCP)
+= PLC4X (Proxy) (TCP)
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/plc4x.adoc[]
-=== Connection String Options
+== Connection String Options
[cols="2,2a,5a"]
|===
@@ -39,9 +39,9 @@ include::../../../plc4j/drivers/all/src/site/generated/plc4x.adoc[]
|===
-=== Individual Resource Address Format
+== Individual Resource Address Format
-==== Connection String
+=== Connection String
The `plc4x` protocol connection has the following connection string format:-
----
@@ -55,7 +55,7 @@ plc4x://127.0.0.1?remote-connection-string=simulated%3A%2F%2Flocalhost
Note the transport, port and option fields are optional.
The remote connection string: `simulated://localhost` is encoded as `simulated%3A%2F%2Flocalhost`
-==== General Format
+=== General Format
The address format is simply the address format of the used remote connection.
So if you specify a remote connection as `simulated`, please follow the address format of that driver.
\ No newline at end of file
diff --git a/src/site/asciidoc/users/protocols/profinet.adoc b/src/site/asciidoc/users/protocols/profinet.adoc
index dcecdf256e..0239d2dd3a 100644
--- a/src/site/asciidoc/users/protocols/profinet.adoc
+++ b/src/site/asciidoc/users/protocols/profinet.adoc
@@ -17,12 +17,12 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== Profinet (In Development)
+= Profinet (In Development)
The PROFINET driver implements a class 3 real time controller. Which is able to communicate with multiple devices
on the same network segment.
-=== Connection String Options
+== Connection String Options
On linux as the Java executable won't have permission to capture raw packets, this needs to be enabled via:-
----
@@ -42,7 +42,7 @@ include::../../../plc4j/drivers/all/src/site/generated/profinet.adoc[]
|===
-=== Connection String
+== Connection String
The Profinet driver uses the connection string
@@ -66,7 +66,7 @@ profinet:raw://127.0.0.1?gsddirectory=/Profinet/GSD&devices=[[test-device-1,MOD_
Note the transport, port fields shouldn't have to be changed
-=== Address Format
+== Address Format
The format of address will be in the format.
----
@@ -83,7 +83,7 @@ device-1.1.1.DIGITAL_INPUT.0.1:BOOL
Note:-
-==== Data Types
+=== Data Types
The following data types are supported
@@ -108,7 +108,7 @@ The following data types are supported
- WSTRING (utf-16)
-=== Some useful tips
+== Some useful tips
Although the GSD file contains all the information needed to configure which data will be available from a device.
The easiest approach is to use the browsing function of the Profinet driver to return a list of all available tags.
diff --git a/src/site/asciidoc/users/protocols/s7.adoc b/src/site/asciidoc/users/protocols/s7.adoc
index 2acd668d43..650a07a4b6 100644
--- a/src/site/asciidoc/users/protocols/s7.adoc
+++ b/src/site/asciidoc/users/protocols/s7.adoc
@@ -21,10 +21,10 @@
//:coderay-linenums-mode: inline
//:coderay-css: class
-== S7 (Step7)
+= S7 (Step7)
image::s7_banner.png[banner,512,167]
-=== Executive Summary
+== Executive Summary
This version of the S7 driver is aimed at exploiting the advanced features of the S7-300 and S7-400 controllers, as well as basic reading and writing functions for the S7-1200 and S7-1500 devices (PUT/GET functions). We hope in a short period of time to have the S7-Plus version, which should exploit the asynchronous functions of the S7-1500.
@@ -49,7 +49,7 @@ Although this driver is developed using Siemens Hardware, it should be functiona
NOTE: When trying to connect to a Siemens `LOGO` device, it is important to add one connection option, as Siemens seems to have only partially implemented the protocol, the device simply terminates the connection as soon as our driver tried to read the SZL table in order to find out which type of S7 device it is talking to. This can be disabled by passing in the type of PLC. For a Siemens LOGO device therefore please add `?controller-type=LOGO` to the connection string.
-=== Regarding the Support
+== Regarding the Support
It is typical within the decision-making cycle in an automation project to know who and how much the support of the tools that will be used in the control architecture will cost.
@@ -57,7 +57,7 @@ PLC4X support is on our development list (dev@plc4x.apache.org) where we will gl
If your company requires commercial support, companies that directly or indirectly support the drivers and tools developed in PLC4X are published on our page.
-=== Record of revisions made to the driver
+== Record of revisions made to the driver
[cols="1, 2,2a,5a"]
|===
@@ -67,9 +67,9 @@ If your company requires commercial support, companies that directly or indirect
|===
-=== Connecting as easy as 1-2-3.
+== Connecting as easy as 1-2-3.
-==== ONE
+=== ONE
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.
@@ -89,7 +89,7 @@ image::s7_url.png[s7_url,,,,align="center"]
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.
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/s7.adoc[]
@@ -114,7 +114,7 @@ include::../../../plc4j/drivers/all/src/site/generated/s7.adoc[]
|===
-==== TWO
+=== TWO
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.
@@ -127,8 +127,8 @@ Any inconsistency in the URL definition will generate an exception that must be
.
.
try {
- PlcConnection connection = new DefaultPlcDriverManager().getConnection("s7://10.10.1.33?remote-rack=0&remote-slot=3&controller-type=S7_400"); //(2.1)
- final PlcReadRequest.Builder subscription = connection.readRequestBuilder(); //(2.2)
+ PlcConnection connection new DefaultPlcDriverManager().getConnection("s7://10.10.1.33?remote-rack=0&remote-slot=3&controller-type=S7_400"); //(2.1)
+ final PlcReadRequest.Builder subscription connection.readRequestBuilder(); //(2.2)
.
.
.
@@ -140,7 +140,7 @@ In (2.1) the driver instance is created, you only have to ensure that the requir
No problems? Then we are ready to configure and request the data that we require from the PLC. Let's go to step "three".
-==== THREE
+=== THREE
By having the connection we can start building and executing our requests.
@@ -151,9 +151,9 @@ By having the connection we can start building and executing our requests.
.
readrequest.addTagAddress("MySZL", "SZL_ID=16#0091;INDEX=16#0000"); //(3.1)
- final PlcReadRequest rr = readrequest.build(); //(3.2)
- final PlcReadResponse szlresponse = rr.execute().get(); //(3.3)
- if (szlresponse.getResponseCode("MySZL") == PlcResponseCode.OK) {//(3.4)
+ final PlcReadRequest rr readrequest.build(); //(3.2)
+ final PlcReadResponse szlresponse rr.execute().get(); //(3.3)
+ if (szlresponse.getResponseCode("MySZL") = PlcResponseCode.OK) {//(3.4)
}
.
.
@@ -168,13 +168,13 @@ These steps are shown separately for ease of analysis, but can be simplified int
A detailed explanation of the format for addressing PLCTags in the S7 driver will be given in the following sections.
-=== Individual Resource Address Format
+== Individual Resource Address Format
When programming Siemens PLCs, usually the tool used to do that is called TIA Portal.
The PLC4X S7 Driver is therefore sticking to the address format defined by this tool as it simplifies exchanging address information.
-==== General Format
+=== General Format
In general all S7 addresses have this format:
@@ -227,7 +227,7 @@ The shorter syntax looks like this:
The S7 driver will handle both types of notation equally.
-==== Memory Areas
+=== Memory Areas
The S7 driver currently allows access to the following memory areas.
@@ -286,7 +286,7 @@ Not all S7 device types support the same full set of memory areas, so the last c
|===
-==== Data Types
+=== Data Types
[cols="1,1,2,4,1,1"]
|===
@@ -330,7 +330,7 @@ Not all S7 device types support the same full set of memory areas, so the last c
-=== Actors participating in the communication process
+== Actors participating in the communication process
PLC programming in general is a Pandora's box!
@@ -369,7 +369,7 @@ endbox
. `CP`, the communications CP will depend on your architecture and requirements, for an S7-300 it will be a CP 343-1 or a CP 443-1 for an S7-400.
-==== S7 Read/Write
+=== S7 Read/Write
@@ -408,7 +408,7 @@ OS --> PLC4X
PLC4X --> App : to consumer
....
-==== S7 Event Subscription
+=== S7 Event Subscription
The S7 driver allows the subscription to asynchronous events generated in the PLC.
@@ -449,9 +449,9 @@ At the user application level `App`, you can use the PLC4X API to subscribe SCAN
In the following sections we will describe in more detail the functionalities of each field.
-==== SCAN Events
+=== SCAN Events
-==== Subscription to MODE events (S7ModeEvent).
+=== Subscription to MODE events (S7ModeEvent).
By subscribing to controller status changes or `MODE` events, the PLC status changes can be tracked.
@@ -528,19 +528,19 @@ With the sequence diagram and the data structures that will be received by the a
public class PLCEventModeSubscription {
public static void main(String[] args) throws Exception {
- try (PlcConnection connection = new PlcDriverManager()
+ try (PlcConnection connection new PlcDriverManager()
.getConnection("s7://192.168.1.51?remote-rack=0&remote-slot=3&controller-type=S7_400")) {
- final PlcSubscriptionRequest.Builder subscription = connection.subscriptionRequestBuilder(); // <01>
+ final PlcSubscriptionRequest.Builder subscription connection.subscriptionRequestBuilder(); // <01>
subscription.addEventField("myMODE", "MODE");
- final PlcSubscriptionRequest sub = subscription.build();
+ final PlcSubscriptionRequest sub subscription.build();
System.out.println("Query: " + sub.toString());
- final PlcSubscriptionResponse subresponse = sub.execute().get();
+ final PlcSubscriptionResponse subresponse sub.execute().get();
- if (subresponse.getResponseCode("myMODE") == PlcResponseCode.OK) { //<04>
+ if (subresponse.getResponseCode("myMODE") = PlcResponseCode.OK) { //<04>
PlcConsumerRegistration registerMode =
subresponse
.getSubscriptionHandle("myMODE") //<05>
@@ -566,7 +566,7 @@ public class PLCEventModeSubscription {
----
-==== Subscription to SYS events (S7SysEvent) and USER events (S7UserEvent).
+=== Subscription to SYS events (S7SysEvent) and USER events (S7UserEvent).
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.
@@ -711,17 +711,17 @@ Below is an example code for the subscription of events type *SYS*.
[source,java]
----
public static void main(String[] args) throws Exception {
- try (PlcConnection connection = new PlcDriverManager().
+ try (PlcConnection connection new PlcDriverManager().
getConnection("s7://192.168.1.51?remote-rack=0&remote-slot=3&controller-type=S7_400")) {
- final PlcSubscriptionRequest.Builder subscription = connection.subscriptionRequestBuilder(); //<01>
+ final PlcSubscriptionRequest.Builder subscription connection.subscriptionRequestBuilder(); //<01>
subscription.addEventField("mySYS", "SYS");
- final PlcSubscriptionRequest sub = subscription.build();
+ final PlcSubscriptionRequest sub subscription.build();
System.out.println("Query: " + sub.toString());
- final PlcSubscriptionResponse subresponse = sub.execute().get();
+ final PlcSubscriptionResponse subresponse sub.execute().get();
PlcConsumerRegistration registerSys =
subresponse
@@ -751,17 +751,17 @@ And below is an example code for the subscription of events type *USR*.
[source,java]
----
public static void main(String[] args) throws Exception {
- try (PlcConnection connection = new PlcDriverManager().
+ try (PlcConnection connection new PlcDriverManager().
getConnection("s7://192.168.1.51?remote-rack=0&remote-slot=3&controller-type=S7_400")) {
- final PlcSubscriptionRequest.Builder subscription = connection.subscriptionRequestBuilder();
+ final PlcSubscriptionRequest.Builder subscription connection.subscriptionRequestBuilder();
subscription.addEventField("myUSR", "USR");
- final PlcSubscriptionRequest sub = subscription.build();
+ final PlcSubscriptionRequest sub subscription.build();
System.out.println("Query: " + sub.toString());
- final PlcSubscriptionResponse subresponse = sub.execute().get();
+ final PlcSubscriptionResponse subresponse sub.execute().get();
PlcConsumerRegistration registerUsr =
subresponse
@@ -785,14 +785,14 @@ public static void main(String[] args) throws Exception {
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.
-[NOTE, icon = s7_note.png]
+[NOTE, icon s7_note.png]
To date, the enum object _S7DiagnosticEventId_ contains a considerable amount of diagnostic values, it must be updated according to the new CPUs or firmware versions available.
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.
-==== Subscription to ALM type events (S7AlarmEvent).
+=== Subscription to ALM type events (S7AlarmEvent).
@@ -910,7 +910,7 @@ TODO: Field description
TODO: Example code
-==== TODO: Cyclic subscription (CYC).
+=== TODO: Cyclic subscription (CYC).
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.
@@ -943,7 +943,7 @@ The data transfer has three time bases:
-==== SZL System Status List
+=== SZL System Status List
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 .
@@ -961,7 +961,7 @@ For a first approach to using system state lists a byte array to JSON notation p
[NOTE,icon=s7_tip.png]
Make use of the XXX document for a detailed explanation of each SZL, since as indicated, everything will depend on the hardware you have installed.
-==== Notation for SZL request
+=== Notation for SZL request
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".
@@ -1021,26 +1021,26 @@ public static void main(String[] args) throws Exception {
System.out.println("URL: https://cache.industry.siemens.com/dl/files/604/44240604/att_67003/v1/s7sfc_en-EN.pdf");
System.out.println("******************************************************************************************");
- try (PlcConnection connection = new DefaultPlcDriverManager().getConnection("s7://10.10.1.33?remote-rack=0&remote-slot=3&controller-type=S7_400")) { //(01)
+ try (PlcConnection connection new DefaultPlcDriverManager().getConnection("s7://10.10.1.33?remote-rack=0&remote-slot=3&controller-type=S7_400")) { //(01)
- final PlcReadRequest.Builder readrequest = connection.readRequestBuilder(); //(02)
+ final PlcReadRequest.Builder readrequest connection.readRequestBuilder(); //(02)
readrequest.addTagAddress("MySZL", "SZL_ID=16#0012;INDEX=16#0000"); //(03)
- final PlcReadRequest rr = readrequest.build(); //(04)
- final PlcReadResponse szlresponse = rr.execute().get(); //(05)
+ final PlcReadRequest rr readrequest.build(); //(04)
+ final PlcReadResponse szlresponse rr.execute().get(); //(05)
- if (szlresponse.getResponseCode("MySZL") == PlcResponseCode.OK){ //(06)
+ if (szlresponse.getResponseCode("MySZL") = PlcResponseCode.OK){ //(06)
- Collection<Byte> data = szlresponse.getAllBytes("MySZL"); //(07)
- byte[] dbytes = ArrayUtils.toPrimitive(data.toArray(new Byte[data.size()])); //(08)
+ Collection<Byte> data szlresponse.getAllBytes("MySZL"); //(07)
+ byte[] dbytes ArrayUtils.toPrimitive(data.toArray(new Byte[data.size()])); //(08)
- SZL szl = SZL.valueOf(0x0012); //(09)
- ByteBuf wb = wrappedBuffer(dbytes); //(10)
+ SZL szl SZL.valueOf(0x0012); //(09)
+ ByteBuf wb wrappedBuffer(dbytes); //(10)
StringBuilder sb = szl.execute(wb); //(11)
System.out.println(sb.toString()); //(12)
- } else if (szlresponse.getResponseCode("MySZL") == PlcResponseCode.NOT_FOUND){ //(13)
+ } else if (szlresponse.getResponseCode("MySZL") = PlcResponseCode.NOT_FOUND){ //(13)
System.out.println("SZL is not supported.");
}
@@ -1114,7 +1114,7 @@ From the obtained StringBuilder, you can use the JSON processor of your choice t
-==== Some useful tips
+=== Some useful tips
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`
@@ -1134,7 +1134,7 @@ 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.
-==== Resources
+=== Resources
1. https://snap7.sourceforge.net/
2. https://support.industry.siemens.com/cs/document/13649203/simatic-net-pc-software-s7-programming-interface?dti=0&dl=en&lc=es-ES
1. https://support.industry.siemens.com/cs/document/109797648/simatic-comparison-list-for-s7-300-s7-400-s7-1200-s7-1500?dti=0&lc=en-WW
diff --git a/src/site/asciidoc/users/protocols/simulated.adoc b/src/site/asciidoc/users/protocols/simulated.adoc
index 7f299119f2..51675f03c9 100644
--- a/src/site/asciidoc/users/protocols/simulated.adoc
+++ b/src/site/asciidoc/users/protocols/simulated.adoc
@@ -17,9 +17,9 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== Simulated
+= Simulated
-=== Connection String Options
+== Connection String Options
include::../../../plc4j/drivers/all/src/site/generated/simulated.adoc[]
@@ -39,9 +39,9 @@ include::../../../plc4j/drivers/all/src/site/generated/simulated.adoc[]
|===
-=== Individual Resource Address Format
+== Individual Resource Address Format
-==== Connection String
+=== Connection String
The simulated driver has the following connection string format:-
----
@@ -54,7 +54,7 @@ simulated://127.0.0.1
Note the transport and port fields are optional.
-==== General Format
+=== General Format
The simulated addresses have this format:
@@ -65,7 +65,7 @@ The simulated addresses have this format:
If the array-size part is omitted, the default size of `1` is assumed.
If the data-type part is omitted, it defaults to STRING.
-==== Simulation Types
+=== Simulation Types
The simulation device supports 3 different simulation types
@@ -74,13 +74,13 @@ should only be used in conjunction with a persistent connection. Once the connec
- RANDOM - This provides a new random value for each read. When writing, a log message is recorded and the value is discarded.
- STDOUT - Always returns a null value when reading. When writing, a log message is recorded and the value is discarded.
-==== Alias
+=== Alias
Aliases are used to identify the different field addresses.
They should only contain alpha-numeric and the full stop (.) character.
For readability and language specific technical purposes they should be less than 256 characters.
-==== Data Types
+=== Data Types
The following data types are supported:-
@@ -103,12 +103,12 @@ The following data types are supported:-
- WCHAR (2 byte char)
- STRING (254 bytes)
-==== Some useful tips
+=== Some useful tips
The simulation driver uses a lot of the same logic templates that is used for the other drivers. It is a good way to test PLC4X
functionality without having a device to connect to.
-==== Examples
+=== Examples
All of these address formats are valid:-
diff --git a/src/site/asciidoc/users/protocols/umas.adoc b/src/site/asciidoc/users/protocols/umas.adoc
index 3b188c97ee..4e94f8540d 100644
--- a/src/site/asciidoc/users/protocols/umas.adoc
+++ b/src/site/asciidoc/users/protocols/umas.adoc
@@ -17,11 +17,11 @@
:imagesdir: ../../images/users/protocols
:icons: font
-== UMAS (Schneider Electric PLCs)
+= UMAS (Schneider Electric PLCs)
(Supported by Plc4Py Only)
-=== Connection String Options
+== Connection String Options
[cols="2,2a,2a,2a,4a"]
|===
@@ -37,7 +37,7 @@
+++
|===
-=== Supported Operations
+== Supported Operations
[cols="2,2a,5a"]
|===
@@ -55,9 +55,9 @@
2+| `browse`
|===
-=== Individual Resource Address Format
+== Individual Resource Address Format
-==== Connection String
+=== Connection String
UMAS has the following connection string format:-
----
@@ -70,7 +70,7 @@ umas:tcp://127.0.0.1:502
Note the transport, port and option fields are optional.
-==== General Format
+=== General Format
In general all UMAS addresses have this format:
@@ -86,7 +86,7 @@ If the array-size part is omitted, the size-default of `1` is assumed.
If the data-type part is omitted, it defaults to the data type of the tag read from the PLC.
-==== Memory Areas
+=== Memory Areas
Apart from tags defined in the PLC the driver is also able to access the %S and %SW
system memory areas.
@@ -96,7 +96,7 @@ manual.
An example of the address format of these areas is %SW1 or %S20.
-==== Data Types
+=== Data Types
The following data types are supported
diff --git a/src/site/asciidoc/users/security.adoc b/src/site/asciidoc/users/security.adoc
index d9316052a2..a500de019d 100644
--- a/src/site/asciidoc/users/security.adoc
+++ b/src/site/asciidoc/users/security.adoc
@@ -15,12 +15,12 @@
// limitations under the License.
//
-== Security Vulnerabilities
+= Security Vulnerabilities
Please note that binary patches are not produced for individual vulnerabilities. To obtain the binary fix for a particular vulnerability you should upgrade to an Apache PLC4X version where that vulnerability has been fixed.
For more information about reporting vulnerabilities, see the https://www.apache.org/security/[Apache Security Team] page.
-=== Known Vulnerabilities
+== Known Vulnerabilities
No vulnerabilities have been reported.
\ 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
index adb2ee0ed7..097536aaaf 100644
--- a/src/site/asciidoc/users/tools/capture-replay.adoc
+++ b/src/site/asciidoc/users/tools/capture-replay.adoc
@@ -15,7 +15,7 @@
// limitations under the License.
//
-== Capture Replay
+= 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.
@@ -29,7 +29,7 @@ It allows to replay recorded network traffic and to directly intercept this traf
Possibly it could also work with non passive drivers, but I expect synchronization to be tricky.
-=== Getting a Capture
+== Getting a Capture
In order to create a capture I usually connect a device running `WireShark` to the network.
@@ -39,7 +39,7 @@ An alternative would be to run `WireShark` on one of the PCs/Servers having acce
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
+== Replaying the Capture
Now you need to copy the `pcapng` file ideally to your development system.
diff --git a/src/site/asciidoc/users/tools/connection-cache.adoc b/src/site/asciidoc/users/tools/connection-cache.adoc
index 3d92cf9e52..c717f6b5b4 100644
--- a/src/site/asciidoc/users/tools/connection-cache.adoc
+++ b/src/site/asciidoc/users/tools/connection-cache.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-=== The Connection Cache concept
+== The Connection Cache concept
In some applications there might be multiple parts of the code that require access to a PLC connection.
diff --git a/src/site/asciidoc/users/tools/connection-pool.adoc b/src/site/asciidoc/users/tools/connection-pool.adoc
index 82f4361110..f47ea49755 100644
--- a/src/site/asciidoc/users/tools/connection-pool.adoc
+++ b/src/site/asciidoc/users/tools/connection-pool.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== Connection Pool
+= Connection Pool
NOTE: The plc4j-connection-pool module has been discontinued and has been removed from PLC4X stating with version 0.11.0
@@ -41,7 +41,7 @@ Per default the PLC connection has no means of automatically re-connecting.
The `PooledPlcDriverManager` can help you with both of these scenarios.
-=== The PooledPlcDriverManager
+== The PooledPlcDriverManager
The `PooledPlcDriverManager` is a wrapper around the normal `PlcDriverManager`.
@@ -57,7 +57,7 @@ Another benefit of the `PooledPlcDriverManager` is that it will check a connecti
So if a connection was terminated, it will detect this and create a new connection.
-=== Example
+== Example
Here comes a little example program utilizing the `PooledPlcDriverManager`:
diff --git a/src/site/asciidoc/users/tools/index.adoc b/src/site/asciidoc/users/tools/index.adoc
index 4670d70607..a558327a17 100644
--- a/src/site/asciidoc/users/tools/index.adoc
+++ b/src/site/asciidoc/users/tools/index.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== Tools
+= Tools
diff --git a/src/site/asciidoc/users/tools/opm.adoc b/src/site/asciidoc/users/tools/opm.adoc
index 9192300c4f..06a6018406 100644
--- a/src/site/asciidoc/users/tools/opm.adoc
+++ b/src/site/asciidoc/users/tools/opm.adoc
@@ -15,10 +15,10 @@
// limitations under the License.
//
-== Object PLC Mapping
+= Object PLC Mapping
-=== What is 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
@@ -29,7 +29,7 @@ This is exactly the reason why JPA was initialized many years ago to allow the i
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
+== 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.
@@ -64,10 +64,10 @@ public class MyEntity {
}
----
-=== Annotations
+== Annotations
-=== More details
+== More details
-=== References
+== 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/tools/scraper.adoc b/src/site/asciidoc/users/tools/scraper.adoc
index 857c48f63b..9944d66974 100644
--- a/src/site/asciidoc/users/tools/scraper.adoc
+++ b/src/site/asciidoc/users/tools/scraper.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== Scraper
+= Scraper
While the Apache PLC4X API allows simple access to PLC resources, if you want to continuously monitor some values and have them retrieved in a pre-defined interval, the core PLC4X API method is a little bit uncomfortable.
@@ -29,7 +29,7 @@ As we have encountered exactly the same problem for about every integration modu
This tool automatically handles all of the tasks mentioned above.
-=== Getting started with the `Scraper`
+== Getting started with the `Scraper`
The Scraper can be found in the Maven module:
[subs=attributes+]
@@ -49,13 +49,13 @@ In general, you need 3 parts to work with the `Scraper`:
In the `Scraper` Configuration you define the so-called `jobs`.
-==== Sources
+=== Sources
Sources define connections to PLCs using PLC4X drivers.
Generally you can think of a `Source` as a PLC4X connection string, given an alias name.
-==== Jobs
+=== Jobs
A `Job` defines which resources (PLC Addresses) should be collected from which `Sources` with a given `Trigger`.
@@ -69,7 +69,7 @@ In the near future we're hoping that we will be able to support:
But, as to now, this has not been implemented yet.
-=== Configuration using the Java API
+== Configuration using the Java API
The core of the Scraper configuration is the `ScraperConfigurationTriggeredImplBuilder` class.
Use this to build the configuration objects used to bootstrap the Scraper.
@@ -138,7 +138,7 @@ As soon as we're done configuring jobs, we need to create the `Scraper` configur
ScraperConfigurationTriggeredImpl scraperConfig = builder.build();
----
-=== Running the `Scraper`
+== Running the `Scraper`
In order to run the `Scraper`, the following boilerplate code is needed.
@@ -183,7 +183,7 @@ public interface ResultHandler {
}
----
-=== Configuration using a `JSON` or `YAML` file
+== Configuration using a `JSON` or `YAML` file
As an alternative to using the Java API, the Scraper Configuration can also be read from a `JSON` or `YAML` document.
diff --git a/src/site/asciidoc/users/tools/testing.adoc b/src/site/asciidoc/users/tools/testing.adoc
index e4252c188c..0539675308 100644
--- a/src/site/asciidoc/users/tools/testing.adoc
+++ b/src/site/asciidoc/users/tools/testing.adoc
@@ -15,9 +15,9 @@
// limitations under the License.
//
-== Testing (or using PLC4X without a PLC)
+= Testing (or using PLC4X without a PLC)
-=== The Mock Driver
+== 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.
@@ -54,7 +54,7 @@ public interface MockDevice {
}
```
-=== Simple Example
+== 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.
@@ -89,7 +89,7 @@ MockDevice mockDevice = new MockDevice() {
```
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
+== 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
@@ -149,7 +149,7 @@ 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
+== 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.
diff --git a/src/site/asciidoc/users/transports/can.adoc b/src/site/asciidoc/users/transports/can.adoc
index 6dcdda5b72..ffcbe0591e 100644
--- a/src/site/asciidoc/users/transports/can.adoc
+++ b/src/site/asciidoc/users/transports/can.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== CAN
+= CAN
A CAN transport is a special category of transport which can bring CAN frame data to various drivers.
All of these transports are meant to follow basic CAN frame data semantics.
@@ -67,11 +67,11 @@ The CAN transport responsibility is to bring CAN data to driver implementer.
This API does not enforce, require or promote a low level bus operations.
In this regard, these operations can be made by library available for specific CAN adapter in use.
-=== Developer notes
+== Developer notes
Usage of CAN transport APIs is recommended for portability reasons.
Please have a look on link:../protocols/can.html[CAN] describe usage of CAN driver adapter with CAN transport facade.
-== Compatible CAN transports
+= Compatible CAN transports
- link:socketcan.html[SocketCAN]
\ No newline at end of file
diff --git a/src/site/asciidoc/users/transports/index.adoc b/src/site/asciidoc/users/transports/index.adoc
index 59d0f41168..cbefddf052 100644
--- a/src/site/asciidoc/users/transports/index.adoc
+++ b/src/site/asciidoc/users/transports/index.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== Transports
+= Transports
- link:tcp.html[TCP]
- link:udp.html[UDP]
diff --git a/src/site/asciidoc/users/transports/pcap-replay.adoc b/src/site/asciidoc/users/transports/pcap-replay.adoc
index 96df626959..84163fc6b0 100644
--- a/src/site/asciidoc/users/transports/pcap-replay.adoc
+++ b/src/site/asciidoc/users/transports/pcap-replay.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== PCAP Replay
+= PCAP Replay
[cols="2,2a,5a"]
|===
diff --git a/src/site/asciidoc/users/transports/raw-socket.adoc b/src/site/asciidoc/users/transports/raw-socket.adoc
index 9ca68332f1..53e56bb247 100644
--- a/src/site/asciidoc/users/transports/raw-socket.adoc
+++ b/src/site/asciidoc/users/transports/raw-socket.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== Raw Socket
+= Raw Socket
[cols="2,2a,5a"]
|===
diff --git a/src/site/asciidoc/users/transports/serial.adoc b/src/site/asciidoc/users/transports/serial.adoc
index 61b2886725..524c903236 100644
--- a/src/site/asciidoc/users/transports/serial.adoc
+++ b/src/site/asciidoc/users/transports/serial.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== Serial Port
+= Serial Port
[cols="2,2a,5a"]
|===
diff --git a/src/site/asciidoc/users/transports/socketcan.adoc b/src/site/asciidoc/users/transports/socketcan.adoc
index c0c86a4a60..0cd2c1db88 100644
--- a/src/site/asciidoc/users/transports/socketcan.adoc
+++ b/src/site/asciidoc/users/transports/socketcan.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== SocketCAN
+= SocketCAN
[cols="2,2a,5a"]
|===
diff --git a/src/site/asciidoc/users/transports/tcp.adoc b/src/site/asciidoc/users/transports/tcp.adoc
index a5da3229e7..cf714d7bc8 100644
--- a/src/site/asciidoc/users/transports/tcp.adoc
+++ b/src/site/asciidoc/users/transports/tcp.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== TCP
+= TCP
[cols="2,2a,5a"]
|===
diff --git a/src/site/asciidoc/users/transports/udp.adoc b/src/site/asciidoc/users/transports/udp.adoc
index 684cccd282..fabfcd95f5 100644
--- a/src/site/asciidoc/users/transports/udp.adoc
+++ b/src/site/asciidoc/users/transports/udp.adoc
@@ -17,7 +17,7 @@
:imagesdir: ../../images/
:icons: font
-== UDP
+= UDP
[cols="2,2a,5a"]
|===