This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/plc4x-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new fe77e1a Site checkin for project PLC4X: Jenkins Tools
fe77e1a is described below
commit fe77e1a040d07c6fdcffc6f05a86afdd65f3cae6
Author: jenkins <[email protected]>
AuthorDate: Sun May 5 12:40:32 2019 +0000
Site checkin for project PLC4X: Jenkins Tools
---
plc4j/users/gettingstarted.html | 420 ++++++++++++++++++++++++++++++++++++++++
users/gettingstarted.html | 12 +-
2 files changed, 431 insertions(+), 1 deletion(-)
diff --git a/plc4j/users/gettingstarted.html b/plc4j/users/gettingstarted.html
new file mode 100644
index 0000000..9f13077
--- /dev/null
+++ b/plc4j/users/gettingstarted.html
@@ -0,0 +1,420 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<!--
+ Generated by Apache Maven Doxia
+ Rendered using Reflow Maven Skin 1.5.0
(http://devacfr.github.io/reflow-maven-skin)
+-->
+<html xml:lang="en" lang="en">
+
+ <head>
+ <meta charset="UTF-8" />
+ <title>Apache PLC4X® - Getting Started</title>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="description" content="" />
+ <meta http-equiv="content-language" content="en" />
+ <link
href="../../css/bootstrap.min.css" rel="stylesheet" />
+ <link href="../../css/docs.css" rel="stylesheet" />
+ <link href="../../css/reflow-skin.css" rel="stylesheet" />
+
+ <link rel="stylesheet" href="../../js/styles/default.min.css" />
+
+ <link href="../../css/lightbox.css" rel="stylesheet" />
+ <link href="../../css/site.css" rel="stylesheet" />
+ <link href="../../css/print.css" rel="stylesheet" media="print" />
+<script>
+ document.addEventListener("DOMContentLoaded", function(event) {
+ /* Add an image for promoting Apache events below the right banner
*/
+ $("#bannerRight").append('<p id="apacheEvents"><a
href="//www.apache.org/events/current-event.html"><img
src="//www.apache.org/events/current-event-234x60.png"/></a></p>');
+ /* Append the trademarks info to the copyright section */
+ $(".copyright").append('<p>Apache PLC4X, PLC4X, Apache, the Apache
feather logo, and the Apache PLC4X project logo are either registered
trademarks or trademarks of The Apache Software Foundation in the United States
and other countries. All other marks mentioned may be trademarks or registered
trademarks of their respective owners.</p>');
+ });
+ </script>
+ </head> <!-- end : head -->
+ <body class="page-users-gettingstarted project-plc4j">
+
+ <div id="m-top-navbar" class="navbar navbar-default navbar-fixed-top">
+ <div class="container">
+ <!-- Brand and toggle get grouped for better mobile display -->
+ <div class="navbar-header">
+ <button type="button" class="navbar-toggle collapsed"
data-toggle="collapse"
+ data-target="#top-navbar-collapse-1"
aria-expanded="false" aria-controls="navbar">
+ <span class="sr-only">Toggle navigation</span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </button>
+ <a class="navbar-brand" href="../..">Apache PLC4X</a>
+ </div> <!-- .navbar-header -->
+ <div class="collapse navbar-collapse" id="top-navbar-collapse-1">
+ <ul class="nav navbar-nav navbar-right">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle"
data-toggle="dropdown">Reports <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li class="dropdown-submenu ">
+<a href="../project-info.html" title="Project Information" >Project
Information</a> <ul class="dropdown-menu">
+ <li ><a href="../dependency-info.html"
title="Dependency Information" >Dependency Information</a></li>
+ <li ><a href="../dependency-management.html"
title="Dependency Management" >Dependency Management</a></li>
+ <li ><a href="../distribution-management.html"
title="Distribution Management" >Distribution Management</a></li>
+ <li ><a href="../index.html" title="About"
>About</a></li>
+ <li ><a href="../issue-management.html" title="Issue
Management" >Issue Management</a></li>
+ <li ><a href="../licenses.html" title="Licenses"
>Licenses</a></li>
+ <li ><a href="../mailing-lists.html" title="Mailing
Lists" >Mailing Lists</a></li>
+ <li ><a href="../modules.html" title="Project
Modules" >Project Modules</a></li>
+ <li ><a href="../plugin-management.html"
title="Plugin Management" >Plugin Management</a></li>
+ <li ><a href="../plugins.html" title="Plugins"
>Plugins</a></li>
+ <li ><a href="../scm.html" title="Source Code
Management" >Source Code Management</a></li>
+ <li ><a href="../summary.html" title="Summary"
>Summary</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle"
data-toggle="dropdown">Apache <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li ><a href="http://www.apache.org"; title="Apache
Software Foundation" class="externalLink" >Apache Software Foundation</a></li>
+ <li ><a
href="https://www.apache.org/foundation/how-it-works.html"; title="How Apache
Works" class="externalLink" >How Apache Works</a></li>
+ <li ><a href="http://www.apache.org/licenses";
title="License" class="externalLink" >License</a></li>
+ <li ><a
href="http://www.apache.org/foundation/sponsorship.html"; title="Sponsoring
Apache" class="externalLink" >Sponsoring Apache</a></li>
+ <li ><a
href="http://www.apache.org/foundation/thanks.html"; title="Thanks"
class="externalLink" >Thanks</a></li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle"
data-toggle="dropdown">Modules <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li ><a href="../plc4j-api/index.html" title="PLC4J:
API" >PLC4J: API</a></li>
+ <li ><a href="../plc4j-drivers/index.html" title="PLC4J:
Drivers" >PLC4J: Drivers</a></li>
+ <li ><a href="../plc4j-protocols/index.html"
title="PLC4J: Protocols" >PLC4J: Protocols</a></li>
+ <li ><a href="../plc4j-utils/index.html" title="PLC4J:
Utils" >PLC4J: Utils</a></li>
+ </ul>
+ </li>
+ </ul>
+ </div><!--/.nav-collapse -->
+ </div> <!--/.container -->
+ </div> <!--/.navbar -->
+ <div class="container">
+ <!-- Masthead -->
+ <!-- ================================================== --> <div
class="header container-fluid">
+ <div class="jumbotron subhead">
+ <div class="row" id="banner">
+ <div class="col-md-12">
+ <div class="pull-left">
+ <a href="https://plc4x.apache.org/";
id="bannerLeft">
+ <img
src="https://plc4x.apache.org/images/apache_plc4x_logo.png";
+ alt='"'Apache PLC4X'"'
+ /> </a>
+ <p class="lead">The industrial IoT adapter</p>
+ </div>
+ <div class="pull-right">
+ <a href="http://www.apache.org/";
id="bannerRight">
+ <img src="https://plc4x.apache.org/images/apache_logo.png";
+ alt='"'Apache Software Foundation'"'
+ /> </a>
+ </div>
+ </div>
+ </div>
+ </div>
+ <hr class="toc-separator" />
+ <div id="toc-bar" class="navbar navbar-default">
+ <div id="toc-scroll-target" class="container">
+ <div class="navbar-header">
+ <button type="button" class="navbar-toggle collapsed"
data-toggle="collapse" data-target="#toc-nav-collapse" aria-expanded="false">
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </button>
+ </div> <!-- .navbar-header -->
+ <div class="collapse navbar-collapse" id="toc-nav-collapse">
+ <ul id="toc" class="nav navbar-nav">
+ <li
class="toplevel"><a href="#_toc_getting_started1" title="Getting
Started">Getting Started</a></li>
+ <li class="toplevel"><a
href="#_toc_using_the_plc4x_api_directly1" title="Using the PLC4X API
directly">Using the PLC4X API directly</a></li>
+ </ul>
+ </div>
+ </div> <!-- .container -->
+ </div> <!-- end: toc-bar -->
+ </div> <!-- end : header -->
+ <div class="main-body">
+
+ <div class="row">
+ <div class="col-md-12">
+ <div class="body-content">
+<div class="sect1">
+ <div class="page-header">
+ <h2 id="_toc_getting_started1">Getting Started</h2>
+ </div>
+ <div class="sectionbody">
+ <div class="sect2">
+ <h3 id="_toc_using_the_plc4x_api_directly1">Using the PLC4X API
directly</h3>
+ <div class="paragraph">
+ <p>In order to write a valid PLC4X Java application, all you need, is to
add a dependency to the <code>api module</code>. When using Maven, all you need
to do is add this dependency:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre> <dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-api</artifactId>
+ <version>0.4.0-SNAPSHOT</version>
+ </dependency></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example in order to communicate with an <code>S7 device</code>
using the <code>S7 Protocol</code>, you would need to add the following
dependency:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre> <dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-driver-s7</artifactId>
+ <version>0.4.0-SNAPSHOT</version>
+ <scope>runtime</scope>
+ </dependency></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>So as soon as your project has the API and a driver implementation
available, you first need to get a <code>PlcConnection</code> instance. This is
done via the <code>PlcDriverManager</code> by asking this to create an instance
for a given <code>PLC4X connection string</code>.</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre>String connectionString = "s7://10.10.64.20/1/1";
+
+try (PlcConnection plcConnection = new
PlcDriverManager().getConnection(connectionString)) {
+
+ ... do something with the connection here ...
+
+}</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>The basic functions supported by PLCs and therefore supported by PLC4X
are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>Read data</p> </li>
+ <li> <p>Write data</p> </li>
+ <li> <p>Subscribe for data</p> </li>
+ <li> <p>Execute functions in the PLC</p> </li>
+ <li> <p>List resources in the PLC</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>But there are some cases in which we can’t simulate or features are
simply disabled intentionally:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>If a PLC and/or protocol don’t support executing of functions, we
simply can’t provide this functionality.</p> </li>
+ <li> <p>We will be providing stripped down versions of drivers, that for
example intentionally don’t support any writing of data and executing of
functions.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Therefore we use metadata to check programmatically, if a given feature
is available:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre>// Check if this connection support reading of data.
+if (!plcConnection.getMetadata().canRead()) {
+ logger.error("This connection doesn't support reading.");
+ return;
+}</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>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
<code>PlcRequestBuilder</code>:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre>// 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();</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>So, as you can see, you prepare a request, by adding items to the
request and in the end by calling the <code>build</code> method.</p>
+ </div>
+ <div class="paragraph">
+ <p>The request is sent to the PLC by issuing the <code>execute</code>
method on the request object:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre>CompletableFuture<? extends PlcReadResponse> asyncResponse =
readRequest.execute();
+asyncResponse.whenComplete((response, throwable) -> {
+ ... process the response ...
+});</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>In general all requests are executed asynchronously. So as soon as the
request is fully processed, the callback gets called and will contain a
<code>readResponse</code>, if everything went right or a <code>throwable</code>
if there were problems.</p>
+ </div>
+ <div class="paragraph">
+ <p>However if you want to write your code in a more synchronous fashion,
the following alternative will provide this:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre>PlcReadResponse response = readRequest.execute().get();</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Processing of the responses is identical in both cases. The following
example will demonstrate some of the options you have:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre>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());
+ }
+}</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>Before accessing the data, it is advisable to check if an item was
correctly returned. This is done by the <code>getResponseCode</code> method for
a given alias. If this is <code>PlcResponseCode.OK</code>, everything is ok,
however it could be one of the following:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>NOT_FOUND</p> </li>
+ <li> <p>ACCESS_DENIED</p> </li>
+ <li> <p>INVALID_ADDRESS</p> </li>
+ <li> <p>INVALID_DATATYPE</p> </li>
+ <li> <p>INTERNAL_ERROR</p> </li>
+ <li> <p>RESPONSE_PENDING</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Assuming the return code was <code>OK</code>, we can continue accessing
the data.</p>
+ </div>
+ <div class="paragraph">
+ <p>As some addresses support reading arrays, with the method
<code>getNumberOfValues</code> 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.</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>response.getObject(fieldName)</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>If you want to access a given element number, please use the
two-argument version instead:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>response.getObject(fieldName, 42)</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>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 <code>RuntimeException</code> of type
<code>PlcIncompatibleDatatypeException</code>. In order to avoid causing this
exception to be thrown, however there are <code>isValid{TypeName}</code>
methods that you can use to check if the value is [...]
+ </div>
+ </div>
+ </div>
+</div> </div>
+ </div>
+ </div> <!-- /row -->
+ </div>
+ </div> <!-- end : row -->
+</div> <!-- /container -->
+ <!-- Footer
+ ================================================== -->
+ <footer class="well">
+ <div class="container">
+ <div class="row">
+ <div class="col-md-3 bottom-nav">
+
+ <ul class="nav nav-list">
+ <li class="nav-header">Reports</li>
+ <li ><a href="../project-info.html" title="Project
Information" >Project Information <i class="glyphicon
glyphicon-chevron-right"></i></a></li>
+ </ul>
+
+ </div>
+ <div class="col-md-3 bottom-nav">
+
+ <ul class="nav nav-list">
+ <li class="nav-header">Apache</li>
+ <li ><a href="http://www.apache.org"; title="Apache
Software Foundation" class="externalLink" >Apache Software Foundation</a></li>
+ <li ><a
href="https://www.apache.org/foundation/how-it-works.html"; title="How Apache
Works" class="externalLink" >How Apache Works</a></li>
+ <li ><a href="http://www.apache.org/licenses";
title="License" class="externalLink" >License</a></li>
+ <li ><a
href="http://www.apache.org/foundation/sponsorship.html"; title="Sponsoring
Apache" class="externalLink" >Sponsoring Apache</a></li>
+ <li ><a
href="http://www.apache.org/foundation/thanks.html"; title="Thanks"
class="externalLink" >Thanks</a></li>
+ </ul>
+
+ </div>
+ <div class="col-md-3 bottom-nav">
+
+ <ul class="nav nav-list">
+ <li class="nav-header">Modules</li>
+ <li ><a href="../plc4j-api/index.html" title="PLC4J:
API" >PLC4J: API</a></li>
+ <li ><a href="../plc4j-drivers/index.html" title="PLC4J:
Drivers" >PLC4J: Drivers</a></li>
+ <li ><a href="../plc4j-protocols/index.html"
title="PLC4J: Protocols" >PLC4J: Protocols</a></li>
+ <li ><a href="../plc4j-utils/index.html" title="PLC4J:
Utils" >PLC4J: Utils</a></li>
+ </ul>
+
+ </div>
+ <div class="col-md-3 bottom-nav">
+
+ <ul class="nav nav-list">
+ </ul>
+
+ </div>
+ </div>
+ </div>
+ </footer>
+ <div class="container subfooter">
+ <div class="row">
+ <div class="col-md-12">
+ <p class="pull-right"><a id="m-scroll-top" href="#">Back to top</a></p>
+ <p class="copyright">Copyright ©2017-2019 <a
href="https://www.apache.org/";>The Apache Software Foundation</a>
+. All Rights Reserved.</p>
+ <p><a href="https://github.com/devacfr/reflow-maven-skin";
title="Reflow Maven skin">Reflow Maven skin</a> by <a
href="http://devacfr.github.io"; target="_blank" title="devacfr">devacfr</a>.</p>
+
+ </div>
+ </div>
+ </div>
+ <!-- Le javascript
+ ================================================== -->
+ <!-- Placed at the end of the document so the pages load faster -->
+ <script src="../../js/jquery.min.js"></script>
+ <script src="../../js/bootstrap.min.js"></script>
+
+ <script src="../../js/lightbox.min.js"></script>
+
+ <script src="../../js/reflow-scroll.js"></script>
+ <script src="../../js/highlight.min.js"></script>
+ <script src="../../js/reflow-skin.js"></script>
+ <script src="../../js/anchor.min.js"></script>
+ <script>
+ document.addEventListener("DOMContentLoaded", function(event) {
+ anchors.options = {
+ placement: 'left',
+ };
+ anchors.add('h1,h2, h3, h4, h5, h6');
+ });
+ </script>
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/users/gettingstarted.html b/users/gettingstarted.html
index 4a62e8c..1d728fc 100644
--- a/users/gettingstarted.html
+++ b/users/gettingstarted.html
@@ -168,7 +168,8 @@
</div> <!-- .navbar-header -->
<div class="collapse navbar-collapse" id="toc-nav-collapse">
<ul id="toc" class="nav navbar-nav">
- <li class="toplevel"><a
href="#_toc_getting_started1" title="Getting Started">Getting Started</a></li>
+ <li
class="toplevel"><a href="#_toc_getting_started1" title="Getting
Started">Getting Started</a></li>
+ <li class="toplevel"><a href="#_toc_java1"
title="Java">Java</a></li>
</ul>
</div>
</div> <!-- .container -->
@@ -184,6 +185,15 @@
<h2 id="_toc_getting_started1">Getting Started</h2>
</div>
<div class="sectionbody">
+ <div class="paragraph">
+ <p>Depending on the programming language, the usage will differ, therefore
please go to the <code>Getting Started</code> version of the language of
choice.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_toc_java1">Java</h3>
+ <div class="paragraph">
+ <p>For guides on how to write PLC4X applications with Java, please go to
the <a href="../plc4j/users/gettingstarted.html">Java Getting Started</a></p>
+ </div>
+ </div>
</div>
</div> </div>
</div>
![https://plc4x.apache.org/images/apache_plc4x_logo.png"](https://plc4x.apache.org/images/apache_plc4x_logo.png"){kind=link}
![https://plc4x.apache.org/images/apache_logo.png"](https://plc4x.apache.org/images/apache_logo.png"){kind=link}