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 2019/05/05 11:38:32 UTC
[plc4x] branch develop updated (2e6085f -> c59147b)
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a change to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git.
from 2e6085f Merge branch 'bjoernhoeper-feature/plc4net' into develop
new f6548ed - Moved up the format descriptor to the top or visual studio won't be able to read the solution.
new c59147b - Added some documentation on how to use PLC4J - Added a warning to the windows installation guide (If you don't run the setup, things will be problematic)
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
README | 5 +
plc4j/src/site/asciidoc/users/gettingstarted.adoc | 178 ++++++++++++++++++++++
plc4net/plc4net.sln | 5 +-
pom.xml | 1 +
src/site/asciidoc/users/gettingstarted.adoc | 3 +
5 files changed, 190 insertions(+), 2 deletions(-)
create mode 100644 plc4j/src/site/asciidoc/users/gettingstarted.adoc
[plc4x] 02/02: - Added some documentation on how to use PLC4J -
Added a warning to the windows installation guide (If you don't run the
setup, things will be problematic)
Posted by cd...@apache.org.
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 c59147bc048e1ceadfa830be62edaec5ba0cb04b
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Sun May 5 13:38:26 2019 +0200
- Added some documentation on how to use PLC4J
- Added a warning to the windows installation guide (If you don't run the setup, things will be problematic)
---
README | 5 +
plc4j/src/site/asciidoc/users/gettingstarted.adoc | 178 ++++++++++++++++++++++
pom.xml | 1 +
src/site/asciidoc/users/gettingstarted.adoc | 3 +
4 files changed, 187 insertions(+)
diff --git a/README b/README
index a22df76..cba79a5 100644
--- a/README
+++ b/README
@@ -85,6 +85,11 @@ When running the installer, make sure to select the options:
- x86_64
Not quite sure which elements are really needed, better just install all of them.
+WARNING: If you don't use the installer version of the distribution. The build will probably fail and it will be pretty
+impossible to see the problem. When manually executing the command, a popup will appear complaining about not being able
+to find some DLL. So if you are having these problems, please try using the installer instead of the manually unpackable
+archive.
+
For Bison, please download the Setup installer version from here: http://gnuwin32.sourceforge.net/packages/bison.htm (When using the zip version the bison.exe couldn't find some DLL files)
It seems the official 2.4.1 version has issues when installed in a directory which's path contains spaces. Please make sure you replace the exe with a patched version form here: http://marin.jb.free.fr/bison/bison-2.4.1-modified.zip
(More infos on this issue here: https://sourceforge.net/p/gnuwin32/bugs/473/)
diff --git a/plc4j/src/site/asciidoc/users/gettingstarted.adoc b/plc4j/src/site/asciidoc/users/gettingstarted.adoc
new file mode 100644
index 0000000..c2a692d
--- /dev/null
+++ b/plc4j/src/site/asciidoc/users/gettingstarted.adoc
@@ -0,0 +1,178 @@
+//
+// 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.
+//
+
+== Getting Started
+
+=== Using the PLC4X 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:
+
+[subs=attributes+]
+----
+ <dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-api</artifactId>
+ <version>{project-version}</version>
+ </dependency>
+----
+
+This will allow you to write a valid application, that compiles fine.
+However in order to actually connect to a device using a given protocol, you need to add this protocol implementation to the classpath.
+
+For example in order to communicate with an `S7 device` using the `S7 Protocol`, you would need to add the following dependency:
+
+[subs=attributes+]
+----
+ <dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-driver-s7</artifactId>
+ <version>{project-version}</version>
+ <scope>runtime</scope>
+ </dependency>
+----
+
+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`.
+
+----
+String connectionString = "s7://10.10.64.20/1/1";
+
+try (PlcConnection plcConnection = new PlcDriverManager().getConnection(connectionString)) {
+
+ ... do something with the connection here ...
+
+}
+----
+
+PLC4X generally supports a very limited set of functions, which is not due to the fact, that we didn't implement things, but that PLCs generally support a very limited set of functions.
+
+The basic functions supported by PLCs and therefore supported by PLC4X are:
+
+* Read data
+* Write data
+* Subscribe for data
+* Execute functions in the PLC
+* List resources in the PLC
+
+In general we will try to offer as many features as possible.
+So if a protocol doesn't support subscription based communication it is our goal to simulate this by polling in the background so it is transparent for the users.
+
+But there are some cases in which we can't simulate or features are simply disabled intentionally:
+
+* If a PLC and/or protocol don't support executing of functions, we simply can't provide this functionality.
+* We will be providing stripped down versions of drivers, that for example intentionally don't support any writing of data and executing of functions.
+
+Therefore we use metadata to check programmatically, if a given feature is available:
+
+----
+// Check if this connection support reading of data.
+if (!plcConnection.getMetadata().canRead()) {
+ logger.error("This connection doesn't support reading.");
+ return;
+}
+----
+
+As soon as you have ensured that a feature is available, you are ready to build a first request.
+This is done by getting a `PlcRequestBuilder`:
+
+----
+// Create a new read request:
+// - Give the single item requested the alias name "value"
+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");
+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.
+
+The request is sent to the PLC by issuing the `execute` method on the request object:
+
+----
+CompletableFuture<? extends PlcReadResponse> asyncResponse = readRequest.execute();
+asyncResponse.whenComplete((response, throwable) -> {
+ ... process the response ...
+});
+----
+
+In general all requests are executed asynchronously.
+So 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:
+
+----
+PlcReadResponse response = readRequest.execute().get();
+----
+
+Processing of the responses is identical in both cases.
+The following example will demonstrate some of the options you have:
+
+----
+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());
+ }
+}
+----
+
+In the for loop, we are demonstrating how the user can iterate over the address aliases in the response.
+In case of an ordinary read request, this will be predefined by the items in the request, however in case of a subscription response, the response might only contain some of the items that were subscribed.
+
+Before accessing the data, it is advisable to check if an item was correctly returned.
+This is done by the `getResponseCode` method for a given alias.
+If this is `PlcResponseCode.OK`, everything is ok, however it could be one of the following:
+
+- NOT_FOUND
+- ACCESS_DENIED
+- INVALID_ADDRESS
+- INVALID_DATATYPE
+- INTERNAL_ERROR
+- RESPONSE_PENDING
+
+Assuming the return code was `OK`, we can continue accessing the data.
+
+As some addresses support reading arrays, with the method `getNumberOfValues` the user can check how many items of a given type are returned.
+For convenience the response object has single-argument methods for accessing the data, which default to returning the first element.
+
+ response.getObject(fieldName)
+
+If you want to access a given element number, please use the two-argument version instead:
+
+ response.getObject(fieldName, 42)
+
+PLC4X provides getters and setters for a wide variety of Java types and automatically handles the type conversion.
+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.
diff --git a/pom.xml b/pom.xml
index ff37648..7129389 100644
--- a/pom.xml
+++ b/pom.xml
@@ -1038,6 +1038,7 @@
<attributes>
<source-highlighter>prettify</source-highlighter>
<imagesoutdir>${project.build.directory}/site/images</imagesoutdir>
+ <project-version>${project.version}</project-version>
</attributes>
<requires>
<require>asciidoctor-diagram</require>
diff --git a/src/site/asciidoc/users/gettingstarted.adoc b/src/site/asciidoc/users/gettingstarted.adoc
index c975484..6de1c67 100644
--- a/src/site/asciidoc/users/gettingstarted.adoc
+++ b/src/site/asciidoc/users/gettingstarted.adoc
@@ -17,5 +17,8 @@
== Getting Started
+Depending on the programming language, the usage will differ, therefore please go to the `Getting Started` version of the language of choice.
+=== Java
+For guides on how to write PLC4X applications with Java, please go to the link:../plc4j/users/gettingstarted.html[Java Getting Started]
\ No newline at end of file
[plc4x] 01/02: - Moved up the format descriptor to the top or
visual studio won't be able to read the solution.
Posted by cd...@apache.org.
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 f6548ed2c018fc322818765e1edc0558f05c699b
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Sun May 5 11:14:06 2019 +0200
- Moved up the format descriptor to the top or visual studio won't be able to read the solution.
---
plc4net/plc4net.sln | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/plc4net/plc4net.sln b/plc4net/plc4net.sln
index 0f4ddcc..a872a2d 100644
--- a/plc4net/plc4net.sln
+++ b/plc4net/plc4net.sln
@@ -1,4 +1,6 @@
-#
+Microsoft Visual Studio Solution File, Format Version 12.00
+
+#
# 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
@@ -17,7 +19,6 @@
# under the License.
#
-Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 16
VisualStudioVersion = 16.0.28803.156
MinimumVisualStudioVersion = 10.0.40219.1