You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by cd...@apache.org on 2020/03/05 11:39:37 UTC
[plc4x] 02/02: - Started adding documentation for transports,
protocols and general concepts
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git
commit 59867a1cd59d71769452d595821ea1a3105991bb
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Thu Mar 5 12:39:28 2020 +0100
- Started adding documentation for transports, protocols and general concepts
---
.../asciidoc/users/plc4j/general-concepts.adoc | 97 ++++++++++++++++++++++
src/site/asciidoc/users/protocols/s7.adoc | 94 +++++++++++++++++++++
.../{protocols/s7.adoc => transports/index.adoc} | 9 +-
.../s7.adoc => transports/pcap-replay.adoc} | 2 +-
.../s7.adoc => transports/raw-socket.adoc} | 2 +-
.../s7.adoc => transports/serial-port.adoc} | 2 +-
.../{protocols/s7.adoc => transports/tcp.adoc} | 34 +++++++-
.../{protocols/s7.adoc => transports/test.adoc} | 2 +-
.../{protocols/s7.adoc => transports/udp.adoc} | 2 +-
src/site/site.xml | 9 ++
10 files changed, 246 insertions(+), 7 deletions(-)
diff --git a/src/site/asciidoc/users/plc4j/general-concepts.adoc b/src/site/asciidoc/users/plc4j/general-concepts.adoc
new file mode 100644
index 0000000..b356032
--- /dev/null
+++ b/src/site/asciidoc/users/plc4j/general-concepts.adoc
@@ -0,0 +1,97 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+== General Concepts
+
+On this page we'll give a short introduction to the most important concepts that will help you understand Apache PLC4X better.
+
+The most important concepts from a user perspective are in general:
+
+- Connections
+-- protocols
+-- transports
+-- configuration
+- Addresses
+
+The two parts where we have built the PLC4X API to abstract are the `connection strings` and the `address strings`.
+
+Both are pretty dependent on the type of device you are planning to communicate with. However these can both be easily configured in an external configuration or passed in as arguments.
+
+=== Connections
+
+In general a connection is a physical or logical connection between two endpoints.
+
+This connection uses a technical transport mechanism and passes data following a given protocol logic.
+Therefore we have modeled both of these aspects separately.
+
+Let's start with the `Transports`. The following are currently available, but they will probably be more soon:
+
+- TCP
+- UDP
+- Raw Socket
+- Serial Port
+- PCAP replay
+- Test
+
+While TCP, UDP are based on the normal TCP and UDP stack of the operating system, Raw sockets directly provide low-level access to `Ethernet Frames`.
+This allows them to not only be used in passive-mode drivers for simply reading all network traffic, it also allows communicating with protocols that are Ethernet based, but don't use TCP or UDP. This is usually the case with `Fieldbus` protocols which usually require lower latency than TCP and UDP can provide.
+
+The Serial Port transport simply reads and writes data to a given serial port.
+
+The probably most special forms of transport are currently the `PCAP replay` and the `Test` transport.
+
+The `PCAP replay` transport allows recording network traffic using tools like `WreShark` and to simply replay these recorded `pcap` and `pcapng` files. This is really helpful for writing new drivers (especially passive mode drivers) without having to be connected to the real device.
+
+From a driver point of view there is actually no difference between a `Raw Socket` and a `PCAP replay` transport.
+
+The `Test` transport is generally built for being used inside the PLC4X testsuite as it allows fine-grained access to the input and output of the drivers.
+
+With this we can explicitly control which data is passed into and retrieved from drivers and to validate this in unit- and integration-tests.
+
+==== Connection Strings
+
+A fully qualified PLC4X connection string would look like this:
+
+----
+{driver code}:{transport code}://{transport config}?{options}
+----
+
+The `driver code` generally selects the protocol we want to use, the `transport code` now selects the type of transport that should be used.
+
+Depending on the selected transport mechanism the `transport config` tells the transport which resource it should use.
+
+For example with a `TCP` and `UDP` transport, this will be the `IP address` or `hostname` optionally followed by the `Port`.
+
+For a `Serial` transport this will be the `name of the serial interface`. `Raw Sockets` will require the `device name` and so on.
+
+For a full description of all transports and their options, please consult the `Transport Documentation`.
+
+The last segment - `options` - can be used to fine tune some protocol or transport options to non-default values. For details on these options, please have a look at the `Protocol Documentation` and the `Transport Documentation`.
+
+A driver for a given protocol however usually has a `default transport`, so sometimes it is possible to omit the transport code.
+
+Then this shorter version can be used. Please inspect the `Protocol Documentation` on `default transports`:
+
+----
+{driver code}://{transport config}?{options}
+----
+
+=== Addresses
+
+Addresses are extremely dependent on the used protocol, as we usually decided to stick to the address formats that are used in that particular environments.
+
+Please check the `Protocol Documentation` on details about these address formats.
\ No newline at end of file
diff --git a/src/site/asciidoc/users/protocols/s7.adoc b/src/site/asciidoc/users/protocols/s7.adoc
index 3f05ee0..750452a 100644
--- a/src/site/asciidoc/users/protocols/s7.adoc
+++ b/src/site/asciidoc/users/protocols/s7.adoc
@@ -18,3 +18,97 @@
:icons: font
== S7 (Step7)
+
+[cols="2,2a,5a"]
+|===
+|Name |Value |Description
+
+|Code
+2+|`s7`
+
+|Name
+2+|Siemens S7 Protocol
+
+|Maven Dependency
+2+|
+----
+<dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-driver-s7</artifactId>
+ <version>{current-last-released-version}</version>
+</dependency>
+----
+
+|Default Transport:
+2+| `tcp`
+
+|Compatible Transports:
+2+| - `tcp`
+- `raw-socket`
+- `pcap-replay`
+
+3+|Supported Operations
+
+|
+| `read`
+| Only supported with `tcp` transport.
+
+|
+| `write`
+| Only supported with `tcp` transport.
+
+|
+| `subscribe`
+| Generally supported with `tcp` transport with S7 devices of types: `S7 300`, `S7 400`, `S7 1500`.
+With `raw-socket` and `pcap-replay` supported on all devices.
+
+3+|Options
+
+|
+| `local-rack` (1)
+| `Rack` value for the client (PLC4X device). Defaults to 1.
+
+|
+| `local-slot` (1)
+| `Slot` value for the client (PLC4X device). Defaults to 1.
+
+|
+| `remote-rack` (0)
+| `Rack` value for the remote (PLC). Defaults to 0.
+
+|
+| `remote-slot` (0)
+| `Slot` value for the remote (PLC). Defaults to 0.
+
+|
+| `pdu-size` (1024)
+| Maximum size of a data-packet sent to and received from the remote PLC.
+During the connection process both parties will negotiate a maximum size both parties can work with and is equal or smaller than the given value is used.
+The driver will automatically split up large requests to not exceed this value in a request or expected response.
+
+|
+| `max-amq-caller` (8)
+| Maximum number of unconfirmed requests the PLC will accept in parallel before discarding with errors.
+This parameter also will be negotiated during the connection process and the maximum both parties can work with and is equal or smaller than the given value is used.
+The driver will automatically take care not exceeding this value while processing requests. Too many requests can cause a growing queue.
+
+|
+| `max-amq-callee` (8)
+| Maximum number of unconfirmed responses or requests PLC4X will accept in parallel before discarding with errors.
+This option is available for completeness and is correctly handled out during the connection process, however it is currently not enforced on PLC4X's side.
+So if a PLC would send more messages than agreed upon, these would still be processed.
+
+|
+| `controller-type`
+| As part of the connection process, usually the PLC4X S7 driver would try to identify the remote device.
+However some devices seem to have problems with this and hang up or cause other problems.
+In such a case, providing the `controller-type` will skip the identification process and hereby avoid this type of problem.
+Possible values are:
+
+- `S7_300`
+- `S7_400`
+- `S7_1200`
+- `S7_1500`
+- `LOGO`
+
+|===
diff --git a/src/site/asciidoc/users/protocols/s7.adoc b/src/site/asciidoc/users/transports/index.adoc
similarity index 81%
copy from src/site/asciidoc/users/protocols/s7.adoc
copy to src/site/asciidoc/users/transports/index.adoc
index 3f05ee0..aa422a6 100644
--- a/src/site/asciidoc/users/protocols/s7.adoc
+++ b/src/site/asciidoc/users/transports/index.adoc
@@ -17,4 +17,11 @@
:imagesdir: ../../images/
:icons: font
-== S7 (Step7)
+== Transports
+
+- link:tcp.html[TCP]
+- link:udp.html[UDP]
+- link:raw-socket.html[Raw Socket]
+- link:serial-port.html[Serial Port]
+- link:pcap-replay.html[PCAP replay]
+- link:test.html[Test]
diff --git a/src/site/asciidoc/users/protocols/s7.adoc b/src/site/asciidoc/users/transports/pcap-replay.adoc
similarity index 98%
copy from src/site/asciidoc/users/protocols/s7.adoc
copy to src/site/asciidoc/users/transports/pcap-replay.adoc
index 3f05ee0..72ca106 100644
--- a/src/site/asciidoc/users/protocols/s7.adoc
+++ b/src/site/asciidoc/users/transports/pcap-replay.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== S7 (Step7)
+== PCAP Replay
diff --git a/src/site/asciidoc/users/protocols/s7.adoc b/src/site/asciidoc/users/transports/raw-socket.adoc
similarity index 98%
copy from src/site/asciidoc/users/protocols/s7.adoc
copy to src/site/asciidoc/users/transports/raw-socket.adoc
index 3f05ee0..f687552 100644
--- a/src/site/asciidoc/users/protocols/s7.adoc
+++ b/src/site/asciidoc/users/transports/raw-socket.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== S7 (Step7)
+== Raw Socket
diff --git a/src/site/asciidoc/users/protocols/s7.adoc b/src/site/asciidoc/users/transports/serial-port.adoc
similarity index 98%
copy from src/site/asciidoc/users/protocols/s7.adoc
copy to src/site/asciidoc/users/transports/serial-port.adoc
index 3f05ee0..4a57553 100644
--- a/src/site/asciidoc/users/protocols/s7.adoc
+++ b/src/site/asciidoc/users/transports/serial-port.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== S7 (Step7)
+== Serial Port
diff --git a/src/site/asciidoc/users/protocols/s7.adoc b/src/site/asciidoc/users/transports/tcp.adoc
similarity index 64%
copy from src/site/asciidoc/users/protocols/s7.adoc
copy to src/site/asciidoc/users/transports/tcp.adoc
index 3f05ee0..e486352 100644
--- a/src/site/asciidoc/users/protocols/s7.adoc
+++ b/src/site/asciidoc/users/transports/tcp.adoc
@@ -17,4 +17,36 @@
:imagesdir: ../../images/
:icons: font
-== S7 (Step7)
+== TCP
+
+[cols="2,2a,5a"]
+|===
+|Name |Value |Description
+
+|Code
+2+|`tcp`
+
+|Name
+2+|TCP Socket Communication
+
+|Maven Dependency
+2+|
+----
+<dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-transport-tcp</artifactId>
+ <version>{current-last-released-version}</version>
+</dependency>
+----
+
+|Transport Syntax:
+|
+----
+{IP address or hostname}:{port}
+----
+|The port can be omitted, if the protocol provides a default port value.
+
+|Options:
+| `tcp`
+| *none*
+|===
diff --git a/src/site/asciidoc/users/protocols/s7.adoc b/src/site/asciidoc/users/transports/test.adoc
similarity index 98%
copy from src/site/asciidoc/users/protocols/s7.adoc
copy to src/site/asciidoc/users/transports/test.adoc
index 3f05ee0..4316357 100644
--- a/src/site/asciidoc/users/protocols/s7.adoc
+++ b/src/site/asciidoc/users/transports/test.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== S7 (Step7)
+== Test
diff --git a/src/site/asciidoc/users/protocols/s7.adoc b/src/site/asciidoc/users/transports/udp.adoc
similarity index 98%
copy from src/site/asciidoc/users/protocols/s7.adoc
copy to src/site/asciidoc/users/transports/udp.adoc
index 3f05ee0..b714a58 100644
--- a/src/site/asciidoc/users/protocols/s7.adoc
+++ b/src/site/asciidoc/users/transports/udp.adoc
@@ -17,4 +17,4 @@
:imagesdir: ../../images/
:icons: font
-== S7 (Step7)
+== UDP
diff --git a/src/site/site.xml b/src/site/site.xml
index f1637a3..c2e2dde 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -51,6 +51,7 @@
<item name="Download" href="users/download.html"/>
<item name="Getting Started" href="users/gettingstarted.html">
<item name="Java" href="users/plc4j/gettingstarted.html"/>
+ <item name="General Conecpts" href="users/plc4j/general-concepts.html"/>
<item name="Virtual Modbus" href="users/plc4j/virtual-modbus.html"/>
</item>
<item name="Blogs, Videos and Slides" href="users/blogs-videos-and-slides.html"/>
@@ -67,6 +68,14 @@
<item name="S7 (Step7)" href="users/protocols/s7.html"/>
<item name="Simulated" href="users/protocols/simulated.html"/>
</item>
+ <item name="Transports" href="users/transports/index.html">
+ <item name="TCP" href="users/transports/tcp.html"/>
+ <item name="UDP" href="users/transports/udp.html"/>
+ <item name="Serial" href="users/transports/serial.html"/>
+ <item name="Raw Socket" href="users/transports/raw-socket.html"/>
+ <item name="PCAP Replay" href="users/transports/pcap-replay.html"/>
+ <item name="Test" href="users/transports/test.html"/>
+ </item>
<item name="Integrations" href="users/integrations/index.html">
<item name="Apache Calcite" href="users/integrations/apache-calcite.html"/>
<item name="Apache Camel" href="users/integrations/apache-camel.html"/>