This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git
The following commit(s) were added to refs/heads/develop by this push:
new 962374fd2a docs: Updated the getting started documentation to the new
version.
962374fd2a is described below
commit 962374fd2a37efdae9c2338056166d7f4d20e77c
Author: Christofer Dutz <[email protected]>
AuthorDate: Wed Oct 11 14:57:55 2023 -0300
docs: Updated the getting started documentation to the new version.
---
src/site/asciidoc/users/getting-started/plc4j.adoc | 95 +++-------------------
1 file changed, 10 insertions(+), 85 deletions(-)
diff --git a/src/site/asciidoc/users/getting-started/plc4j.adoc
b/src/site/asciidoc/users/getting-started/plc4j.adoc
index 960d23b732..b7c120861a 100644
--- a/src/site/asciidoc/users/getting-started/plc4j.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4j.adoc
@@ -47,12 +47,12 @@ For example in order to communicate with an `S7 device`
using the `S7 Protocol`,
----
So as soon as your project has the API and a driver implementation available,
you first need to get a `PlcConnection` instance.
-This is done via the `PlcDriverManager` by asking this to create an instance
for a given `PLC4X connection string`.
+This is done via the `PlcConnectionManager`, which is provided to you by the
`PlcDriverManager` by asking this to create an instance for a given `PLC4X
connection string`.
----
String connectionString = "s7://10.10.64.20";
-try (PlcConnection plcConnection = new
PlcDriverManager().getConnection(connectionString)) {
+try (PlcConnection plcConnection =
PlcDriverManager.getDefault().getConnectionManager().getConnection(connectionString))
{
... do something with the connection here ...
@@ -96,14 +96,16 @@ This is done by getting a `PlcReadRequest.Builder`:
// Create a new read request:
// - Give the single item requested an alias name
PlcReadRequest.Builder builder = plcConnection.readRequestBuilder();
-builder.addItem("value-1", "%Q0.4:BOOL");
-builder.addItem("value-2", "%Q0:BYTE");
-builder.addItem("value-3", "%I0.2:BOOL");
-builder.addItem("value-4", "%DB.DB1.4:INT");
+builder.addTagAddress("value-1", "%Q0.4:BOOL");
+builder.addTagAddress("value-2", "%Q0:BYTE");
+builder.addTagAddress("value-3", "%I0.2:BOOL");
+builder.addTagAddress("value-4", "%DB.DB1.4:INT");
PlcReadRequest readRequest = builder.build();
----
-So, as you can see, you prepare a request, by adding items to the request and
in the end by calling the `build` method.
+So, as you can see, you prepare a request, by adding tag addresses to the
request and in the end by calling the `build` method.
+
+If you are using the `BrowseApi` you might also have been provided with `Tag`
objects. In that case simply use `addTag` and pass in the `Tag` object instead
of the address string.
The request is sent to the PLC by issuing the `execute` method on the request
object:
@@ -118,7 +120,7 @@ asyncResponse.whenComplete((response, throwable) -> {
});
----
-In general all requests are executed asynchronously.
+In general, all requests are executed asynchronously.
As soon as the request is fully processed, the callback gets called and will
contain a `readResponse`, if everything went right or a `throwable` if there
were problems.
However, if you want to write your code in a more synchronous fashion, the
following alternative will provide this:
@@ -131,31 +133,6 @@ Processing of the responses is identical in both cases in
the synchronous approa
The following example will demonstrate some of the options you have:
-.Up to version 0.10.0
-----
-for (String fieldName : response.getFieldNames()) {
- if(response.getResponseCode(fieldName) == PlcResponseCode.OK) {
- int numValues = response.getNumberOfValues(fieldName);
- // If it's just one element, output just one single line.
- if(numValues == 1) {
- logger.info("Value[" + fieldName + "]: " +
response.getObject(fieldName));
- }
- // If it's more than one element, output each in a single row.
- else {
- logger.info("Value[" + fieldName + "]:");
- for(int i = 0; i < numValues; i++) {
- logger.info(" - " + response.getObject(fieldName, i));
- }
- }
- }
- // Something went wrong, to output an error message instead.
- else {
- logger.error("Error[" + fieldName + "]: " +
response.getResponseCode(fieldName).name());
- }
-}
-----
-
-.SNAPSHOT version (The general process is still the same we however cleaned up
some naming)
----
for (String tagName : response.getTagNames()) {
if(response.getResponseCode(tagName) == PlcResponseCode.OK) {
@@ -224,19 +201,6 @@ if (!plcConnection.getMetadata().canWrite()) {
As soon as we are sure that we can write, we create a new
`PlcWriteRequest.Builder`:
-.Up to version 0.10.0
-----
-// Create a new write request:
-// - Give the single item requested an alias name
-// - Pass in the data you want to write (for arrays, pass in one value for
every element)
-PlcWriteRequest.Builder builder = plcConnection.writeRequestBuilder();
-builder.addItem("value-1", "%Q0.4:BOOL", true);
-builder.addItem("value-2", "%Q0:BYTE", (byte) 0xFF);
-builder.addItem("value-4", "%DB.DB1.4:INT[3]", 7, 23, 42);
-PlcWriteRequest writeRequest = builder.build();
-----
-
-.SNAPSHOT version
----
// Create a new write request:
// - Give the single item requested an alias name
@@ -265,20 +229,6 @@ PlcWriteResponse response = writeRequest.execute().get();
As we don't have to process the data itself, for the write request, it's
enough to simply check the return code for each field.
-.Up to version 0.10.0
-----
-for (String fieldName : response.getFieldNames()) {
- if(response.getResponseCode(fieldName) == PlcResponseCode.OK) {
- logger.info("Value[" + fieldName + "]: updated");
- }
- // Something went wrong, to output an error message instead.
- else {
- logger.error("Error[" + fieldName + "]: " +
response.getResponseCode(fieldName).name());
- }
-}
-----
-
-.SNAPSHOT version (The general process is still the same we however cleaned up
some naming)
----
for (String tagName : response.getTagNames()) {
if(response.getResponseCode(tagName) == PlcResponseCode.OK) {
@@ -315,18 +265,6 @@ The main difference is that while reading there is only
one form how you could r
Therefore instead of using a normal `addItem` or `addTag` in newer versions,
there are tree different methods as you can see in the following examples.
-.Up to version 0.10.0
-----
-// Create a new subscription request:
-// - Give the single item requested an alias name
-PlcSubscriptionRequest.Builder builder =
plcConnection.subscriptionRequestBuilder();
-builder.addChangeOfStateField("value-1", "{some address}");
-builder.addCyclicField("value-2", "{some address}", Duration.ofMillis(1000));
-builder.addEventField("value-3", "{some alarm address}");
-PlcSubscriptionRequest subscriptionRequest = builder.build();
-----
-
-.SNAPSHOT version
----
// Create a new subscription request:
// - Give the single tag requested an alias name
@@ -350,19 +288,6 @@ Now comes the little more tricky part, as subscriptions
are always asynchronous,
In general, you can't say how many of your subscribed fields will be available
in every callback.
So it is double important to check or iterate over the field names.
-.Up to version 0.10.0
-----
-for (String subscriptionName : response.getFieldNames()) {
- final PlcSubscriptionHandle subscriptionHandle =
response.getSubscriptionHandle(subscriptionName);
- subscriptionHandle.register(plcSubscriptionEvent -> {
- for (String fieldName : plcSubscriptionEvent.getFieldNames()) {
- System.out.println(plcSubscriptionEvent.getPlcValue(fieldName));
- }
- });
-}
-----
-
-.SNAPSHOT version
----
for (String subscriptionName : response.getFieldNames()) {
final PlcSubscriptionHandle subscriptionHandle =
response.getSubscriptionHandle(subscriptionName);
