This is an automated email from the ASF dual-hosted git repository.
chrisdutz pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git
The following commit(s) were added to refs/heads/develop by this push:
new 3c8251707d docs(website): Updated the Other driver documentations
(Second pass)
3c8251707d is described below
commit 3c8251707d700a7e5459244e4359b5040a7a8a60
Author: Christofer Dutz <[email protected]>
AuthorDate: Fri Aug 14 12:35:13 2026 +0200
docs(website): Updated the Other driver documentations (Second pass)
---
plc4j/drivers/all/pom.xml | 6 ++
.../readwrite/connection/CtrlXConnection.java | 7 +-
website/asciidoc/modules/users/nav.adoc | 1 +
.../modules/users/pages/protocols/ctrlx.adoc | 85 +++++++++++++++++++++-
.../modules/users/pages/protocols/index.adoc | 9 ++-
.../modules/users/pages/protocols/umas.adoc | 54 ++++++++------
website/asciidoc/modules/users/partials/umas.adoc | 57 +++++++++++++++
7 files changed, 188 insertions(+), 31 deletions(-)
diff --git a/plc4j/drivers/all/pom.xml b/plc4j/drivers/all/pom.xml
index 0b1b386e54..15f74a4e73 100644
--- a/plc4j/drivers/all/pom.xml
+++ b/plc4j/drivers/all/pom.xml
@@ -184,6 +184,12 @@
<version>1.0.0-SNAPSHOT</version>
<scope>runtime</scope>
</dependency>
+ <dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-driver-umas</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <scope>runtime</scope>
+ </dependency>
<dependency>
<groupId>org.apache.plc4x</groupId>
diff --git
a/plc4j/drivers/ctrlx/src/main/java/org/apache/plc4x/java/ctrlx/readwrite/connection/CtrlXConnection.java
b/plc4j/drivers/ctrlx/src/main/java/org/apache/plc4x/java/ctrlx/readwrite/connection/CtrlXConnection.java
index 2b2d535e80..555301e6b4 100644
---
a/plc4j/drivers/ctrlx/src/main/java/org/apache/plc4x/java/ctrlx/readwrite/connection/CtrlXConnection.java
+++
b/plc4j/drivers/ctrlx/src/main/java/org/apache/plc4x/java/ctrlx/readwrite/connection/CtrlXConnection.java
@@ -229,8 +229,7 @@ public class CtrlXConnection implements PlcConnection,
PlcPinger, PlcBrowser {
responseCodes.put(queryName, PlcResponseCode.OK);
responseItems.put(queryName, new ArrayList<>());
PlcQuery query = browseRequest.getQuery(queryName);
- if (query instanceof CtrlXQuery) {
- CtrlXQuery ctrlXQuery = (CtrlXQuery) query;
+ if (query instanceof CtrlXQuery ctrlXQuery) {
matchers.put(queryName, ctrlXQuery.getMatcher());
} else {
future.completeExceptionally(
@@ -268,7 +267,7 @@ public class CtrlXConnection implements PlcConnection,
PlcPinger, PlcBrowser {
if (children.isEmpty()) {
List<String> matchingQueryNames =
matchers.entrySet().stream()
.filter(entry ->
entry.getValue().matches(curNode)).map(Map.Entry::getKey)
- .collect(Collectors.toList());
+ .toList();
// If there's at least one matching query, read the
"metadata", which contains information
// on if the property is readable or writable.
if (!matchingQueryNames.isEmpty()) {
@@ -292,7 +291,7 @@ public class CtrlXConnection implements PlcConnection,
PlcPinger, PlcBrowser {
// If this node has children, then it's branch, and we
need to add its children to the queue.
else {
// Add all children to the list.
- uncheckedNodeList.addAll(children.stream().map(child
-> curNode + "/" + child).collect(Collectors.toList()));
+ uncheckedNodeList.addAll(children.stream().map(child
-> curNode + "/" + child).toList());
}
} catch (ApiException e) {
// Ignore ...
diff --git a/website/asciidoc/modules/users/nav.adoc
b/website/asciidoc/modules/users/nav.adoc
index c9d016a6d5..52c2c38fdd 100644
--- a/website/asciidoc/modules/users/nav.adoc
+++ b/website/asciidoc/modules/users/nav.adoc
@@ -52,6 +52,7 @@
*** xref:protocols/s7.adoc[]
*** xref:protocols/simulated.adoc[]
*** xref:protocols/slmp.adoc[]
+*** xref:protocols/umas.adoc[]
** xref:transports/index.adoc[]
*** xref:transports/tcp.adoc[]
diff --git a/website/asciidoc/modules/users/pages/protocols/ctrlx.adoc
b/website/asciidoc/modules/users/pages/protocols/ctrlx.adoc
index 91bce84da5..f65ff4e551 100644
--- a/website/asciidoc/modules/users/pages/protocols/ctrlx.adoc
+++ b/website/asciidoc/modules/users/pages/protocols/ctrlx.adoc
@@ -17,10 +17,89 @@
:imagesdir: ../../images/users/protocols
:icons: font
-= CtlrX
+= CtrlX
+WARNING: This driver is unfinished and not usable yet. Only browsing and
pinging work at all; there
+is no tag address syntax, so reading and writing are not available. This page
describes the current
+state for anyone continuing the work - it is not linked from the navigation.
+The CtrlX driver talks to Bosch Rexroth ctrlX CORE devices through their
REST/Data-Layer API over
+HTTPS, rather than over an industrial fieldbus protocol.
-== Connection String Options
+== Supported Operations
-//include::../../../ctrlx.adoc[]
\ No newline at end of file
+[cols="2,5a"]
+|===
+|Operation |Description
+
+|`browse`
+|Enumerates the device's Data Layer nodes. This is the driver's main
capability.
+
+|`ping`
+|Checks that the device is reachable and the credentials are accepted.
+
+|`read` / `write` / `subscribe`
+|*Not implemented.* The connection reports these as supported in its metadata,
but the
+corresponding request builders return `null`, so attempting one fails. Use
`browse` for now.
+|===
+
+== Connection String
+
+----
+ctrlx:https://{host}
+ctrlx://{host}
+----
+
+`https` is the only supported transport, and it is also the default - so the
transport part can be
+omitted. Any other transport is rejected with
+`Only 'https' transport is supported by this driver`.
+
+== Authentication
+
+IMPORTANT: A CtrlX connection *always* requires a username and password.
Obtaining a connection
+without authentication throws `CtrlX connections require authentication.`, and
an authentication
+object that is not a username/password pair is rejected as well.
+
+[source,java]
+----
+PlcConnection connection = new DefaultPlcDriverManager()
+ .getConnection("ctrlx://192.168.1.1",
+ new PlcUsernamePasswordAuthentication("boschrexroth", "boschrexroth"));
+----
+
+== Browsing
+
+Browse queries are glob patterns matched against the Data Layer node paths,
not tag addresses.
+`**` matches everything and is the simplest way to see what a device exposes:
+
+[source,java]
+----
+PlcBrowseResponse response = connection.browseRequestBuilder()
+ .addQuery("all", "**")
+ .build().execute().get();
+----
+
+The driver has no tag address syntax of its own - `parseTag` is not
implemented - which is the
+reason read and write are unavailable.
+
+== Discovery
+
+The driver supports discovery, which locates ctrlX CORE devices on the local
network.
+
+== Maven Dependency
+
+The driver is not part of the `plc4j-driver-all` meta package while it is
unfinished, so it has to
+be added explicitly:
+
+[source,xml,subs=attributes+]
+----
+<dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-driver-ctrlx</artifactId>
+ <version>{page-component-version}</version>
+</dependency>
+----
+
+NOTE: The driver declares no connection-string parameters of its own, which is
why this page has no
+generated options table like the other protocols. Everything it needs comes
from the host in the
+connection string plus the credentials.
diff --git a/website/asciidoc/modules/users/pages/protocols/index.adoc
b/website/asciidoc/modules/users/pages/protocols/index.adoc
index 9c468c97b7..5db9eaefa4 100644
--- a/website/asciidoc/modules/users/pages/protocols/index.adoc
+++ b/website/asciidoc/modules/users/pages/protocols/index.adoc
@@ -58,6 +58,13 @@
|icon:exclamation[role="yellow"]
|icon:times[role="red"]
+|ctrlX
+|icon:times[role="red"]
+|icon:times[role="red"]
+|icon:times[role="red"]
+|icon:times[role="red"]
+|icon:times[role="red"]
+
|DF1
|icon:times[role="red"]
|icon:times[role="red"]
@@ -160,7 +167,7 @@
|icon:times[role="red"]
|icon:times[role="red"]
|icon:times[role="red"]
-|icon:times[role="red"]
+|icon:check[role="green"]
|icon:check[role="green"]
|===
diff --git a/website/asciidoc/modules/users/pages/protocols/umas.adoc
b/website/asciidoc/modules/users/pages/protocols/umas.adoc
index fd17e2de00..f706f755ab 100644
--- a/website/asciidoc/modules/users/pages/protocols/umas.adoc
+++ b/website/asciidoc/modules/users/pages/protocols/umas.adoc
@@ -21,28 +21,16 @@
This protocol is used by Schneider Electric PLCs such as the M340, M580 and
the Quantum PLCs with the Unity firmware.
-This driver supports reading/writing/browsing of PLC tags as well as %S/%SW
addresses.
+This driver supports reading, writing and browsing of PLC tags.
The Data Dictionary needs to be enabled on the PLC.
-(Supported by Plc4Py Only)
+NOTE: The driver is available in Java and in Plc4Py. The tag address syntax
differs slightly
+between the two; where that is the case it is called out below.
== Connection String Options
-[cols="2,2a,2a,2a,4a"]
-|===
-|Name |Type |Default Value |Required |Description
-|Name 4+|UMAS
-|Code 4+|`umas`
-|Default Transport 4+|`tcp`
-|Supported Transports 4+|
- - `tcp`
-5+|Config options:
-|`request-timeout` |INT |5000| |Default timeout for all types of requests.
-|`unit-identifier` |INT |1| |Unit-identifier or slave-id that identifies the
target PLC. Defaults to 1.
-+++
-
-|===
+include::partial$umas.adoc[]
== Supported Operations
[cols="2,2a,5a"]
@@ -59,6 +47,9 @@ The Data Dictionary needs to be enabled on the PLC.
|
2+| `browse`
+
+|
+2+| `ping`
|===
== Individual Resource Address Format
@@ -78,23 +69,37 @@ Note the transport, port and option fields are optional.
=== General Format
-In general all UMAS addresses have this format:
+UMAS addresses are the symbolic names declared in the PLC program, following
the usual
+IEC 61131-3 conventions:
----
-{tag-name}.{child-name}.{child-name}:{data-type}[{array-size}]
+{tag-name}
+{tag-name}[{index}]
+{tag-name}.{child-name}
+{tag-name}.{child-name}[{index}].{child-name}
----
Depending on the type of tag the child-name parameters are optional.
-e.g. A tag with a BOOL data type could be 'TESTING_BOOL_1' whereas
-if it is a UDT the tag name is followed by the child 'TESTING_UDT_1.START'
which in itself could be a BOOL.
+e.g. A tag with a BOOL data type could be `TESTING_BOOL_1`, whereas if it is a
UDT the tag name is
+followed by the child `TESTING_UDT_1.START`, which in itself could be a BOOL.
+An index in square brackets selects a single element and may appear at any
position of the path.
-If the array-size part is omitted, the size-default of `1` is assumed.
+.Examples
+[cols="2" ,options="header"]
+|===
+|Address |Meaning
+|`g_r32` |a simple global variable
+|`g_plant.meta.r32` |a nested struct member
+|`g_arrInt[3]` |the fourth element of an array
+|`g_plant.items[2].value` |mixed struct and array access
+|===
-If the data-type part is omitted, it defaults to the data type of the tag read
from the PLC.
+IMPORTANT: The Java driver takes the data type from the PLC's data dictionary,
so an address carries
+no `:{data-type}` suffix - appending one makes the address invalid.
=== Memory Areas
-Apart from tags defined in the PLC the driver is also able to access the %S
and %SW
+Apart from tags defined in the PLC, Plc4Py is also able to access the %S and
%SW
system memory areas.
The specific address details of the data in these areas are outlined in the
devices
@@ -102,6 +107,9 @@ manual.
An example of the address format of these areas is %SW1 or %S20.
+NOTE: These system memory addresses are supported by Plc4Py only. The Java
driver's address parser
+accepts symbolic names only and rejects addresses starting with `%`.
+
=== Data Types
The following data types are supported
diff --git a/website/asciidoc/modules/users/partials/umas.adoc
b/website/asciidoc/modules/users/partials/umas.adoc
new file mode 100644
index 0000000000..922c881d11
--- /dev/null
+++ b/website/asciidoc/modules/users/partials/umas.adoc
@@ -0,0 +1,57 @@
+//
+// 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
+//
+// https://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.
+//
+
+// Code generated by code-generation. DO NOT EDIT.
+
+[cols="2,2a,2a,2a,4a"]
+|===
+|Name |Type |Default Value |Required |Description
+|Name 4+|UMAS (Schneider Electric)
+|Code 4+|`umas`
+|Maven Dependency 4+|
+
+[subs=attributes+]
+----
+<dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-driver-umas</artifactId>
+ <version>{page-component-version}</version>
+</dependency>
+----
+|Default Transport 4+|`tcp`
+|Supported Transports 4+|
+ - `tcp`
+5+|Config options:
+|`unit-identifier` |INT |0| |Modbus unit identifier (slave address). UMAS
typically uses 0.
+|`request-timeout` |INT |4000| |Timeout in milliseconds for UMAS requests.
+|`max-frame-size` |INT |65535| |Maximum UMAS frame size. The PLC reports its
actual limit during InitComms.
+|`browser-generate-array-nodes` |BOOLEAN |true| |Tells the browser to generate
artificial child nodes representing individual array elements.
+5+|Transport config options:
+5+|
++++
+<h4>tcp</h4>
++++
+|`tcp.connect-timeout` |INT |5000| |
+|`tcp.read-timeout` |INT |0| |
+|`tcp.write-timeout` |INT |0| |
+|`tcp.tcp-no-delay` |BOOLEAN |true| |
+|`tcp.keep-alive` |BOOLEAN |false| |
+|`tcp.send-buffer-size` |INT |81920| |
+|`tcp.receive-buffer-size` |INT |81920| |
+|`tcp.local-address` |STRING | | |
+|`tcp.local-port` |INT |0| |
+|===
