Google Git
Sign in
apache / plc4x-website / 9e66895b49a29df6488482547272e4797c6cd6d3 / . / users / getting-started / virtual-modbus.html
blob: ed7bf939e17f31226ce59677ca6665d64aa7e7c2 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<title>PLC4X &#x2013; </title>
<script src="../../js/jquery.slim.min.js" type="text/javascript"></script>
<!--script src="../../js/popper.min.js" type="javascript"></script-->
<script src="../../js/bootstrap.bundle.min.js" type="text/javascript"></script>
<!-- The tooling for adding images and links to Apache events -->
<script src="https://www.apachecon.com/event-images/snippet.js" type="text/javascript"></script>
<!-- FontAwesome -->
<link rel="stylesheet" href="../../css/all.min.css" type="text/css"/>
<!-- Bootstrap -->
<link rel="stylesheet" href="../../css/bootstrap.min.css" type="text/css"/>
<!-- Some Maven Site defaults -->
<link rel="stylesheet" href="../../css/maven-base.css" type="text/css"/>
<link rel="stylesheet" href="../../css/maven-theme.css" type="text/css"/>
<!-- The PLC4X version of a bootstrap theme -->
<link rel="stylesheet" href="../../css/themes/plc4x.css" type="text/css" id="pagestyle"/>
<!-- A custom style for printing content -->
<link rel="stylesheet" href="../../css/print.css" type="text/css" media="print"/>
<meta http-equiv="Content-Language" content="en"/>
</head>
<body class="composite">
<nav class="navbar navbar-light navbar-expand-md bg-faded justify-content-center border-bottom">
<!--a href="/" class="navbar-brand d-flex w-50 mr-auto">Navbar 3</a-->
<a href="https://plc4x.apache.org/" id="bannerLeft"><img src="../../images/apache_plc4x_logo_small.png" alt="Apache PLC4X"/></a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#collapsingNavbar3">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse w-100" id="collapsingNavbar3">
<ul class="navbar-nav w-100 justify-content-center">
<li class="nav-item">
<a class="nav-link" href="../../index.html">Home</a>
</li>
<li class="nav-item active">
<a class="nav-link" href="../../users/index.html">Users</a>
</li>
<li class="nav-item">
<a class="nav-link" href="../../developers/index.html">Developers</a>
</li>
<li class="nav-item">
<a class="nav-link" href="../../apache/index.html">Apache</a>
</li>
</ul>
<ul class="nav navbar-nav ml-auto justify-content-end">
<li class="nav-item row valign-middle">
<a class="acevent" data-format="wide" data-mode="light" data-event="random" style="width:240px;height:60px;"></a>
</li>
</ul>
</div>
</nav>
<div class="container-fluid">
<div class="row h-100">
<nav class="col-sm-push col-md-2 pt-3 sidebar">
<div class="sidebar-sticky">
<ul class="nav flex-column">
<li class="nav-item">
<a href="../../users/index.html" class="nav-link">Section Home</a>
</li>
<li class="nav-item">
<a href="../../users/download.html" class="nav-link">Download</a>
</li>
<li class="nav-item">
<a href="../../users/adopters.html" class="nav-link">Adopters</a>
</li>
<li class="nav-item">
<a href="../../users/commercial-support.html" class="nav-link">Commercial support</a>
</li>
<li class="nav-item">
<a href="../../users/gettingstarted.html" class="nav-link">Getting Started</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../users/getting-started/plc4go.html" class="nav-link">Go</a>
</li>
<li class="nav-item">
<a href="../../users/getting-started/plc4j.html" class="nav-link">Java</a>
</li>
<li class="nav-item">
<a href="../../users/getting-started/using-snapshots.html" class="nav-link">Using SNAPSHOTS</a>
</li>
<li class="nav-item">
<a href="../../users/getting-started/general-concepts.html" class="nav-link">General Concepts</a>
</li>
<li class="nav-item">
<strong class="nav-link">Virtual Modbus</strong>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../users/blogs-videos-and-slides.html" class="nav-link">Blogs, Videos and Slides</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/index.html" class="nav-link">Protocols</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../users/protocols/ab-eth.html" class="nav-link">AB-ETH</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/ads.html" class="nav-link">ADS/AMS</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/bacnetip.html" class="nav-link">BACnet/IP</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/canopen.html" class="nav-link">CANopen</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/deltav.html" class="nav-link">DeltaV</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/df1.html" class="nav-link">DF1</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/ethernet-ip.html" class="nav-link">EtherNet/IP</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/firmata.html" class="nav-link">Firmata</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/knxnetip.html" class="nav-link">KNXnet/IP</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/modbus.html" class="nav-link">Modbus</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/opc-ua.html" class="nav-link">OPC UA</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/plc4x.html" class="nav-link">PLC4X (Proxy)</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/s7.html" class="nav-link">S7 (Step7)</a>
</li>
<li class="nav-item">
<a href="../../users/protocols/simulated.html" class="nav-link">Simulated</a>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../users/transports/index.html" class="nav-link">Transports</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../users/transports/tcp.html" class="nav-link">TCP</a>
</li>
<li class="nav-item">
<a href="../../users/transports/udp.html" class="nav-link">UDP</a>
</li>
<li class="nav-item">
<a href="../../users/transports/serial.html" class="nav-link">Serial</a>
</li>
<li class="nav-item">
<a href="../../users/transports/socketcan.html" class="nav-link">SocketCAN</a>
</li>
<li class="nav-item">
<a href="../../users/transports/raw-socket.html" class="nav-link">Raw Socket</a>
</li>
<li class="nav-item">
<a href="../../users/transports/pcap-replay.html" class="nav-link">PCAP Replay</a>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../users/integrations/index.html" class="nav-link">Integrations</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../users/integrations/apache-calcite.html" class="nav-link">Apache Calcite</a>
</li>
<li class="nav-item">
<a href="../../users/integrations/apache-camel.html" class="nav-link">Apache Camel</a>
</li>
<li class="nav-item">
<a href="../../users/integrations/apache-edgent.html" class="nav-link">Apache Edgent</a>
</li>
<li class="nav-item">
<a href="../../users/integrations/apache-iotdb.html" class="nav-link">Apache IoTDB</a>
</li>
<li class="nav-item">
<a href="../../users/integrations/apache-kafka.html" class="nav-link">Apache Kafka</a>
</li>
<li class="nav-item">
<a href="../../users/integrations/apache-nifi.html" class="nav-link">Apache NiFi</a>
</li>
<li class="nav-item">
<a href="../../users/integrations/apache-streampipes.html" class="nav-link">Apache StreamPipes</a>
</li>
<li class="nav-item">
<a href="../../users/integrations/eclipse-ditto.html" class="nav-link">Eclipse Ditto</a>
</li>
<li class="nav-item">
<a href="../../users/integrations/eclipse-milo.html" class="nav-link">Eclipse Milo OPC UA Server</a>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../users/tools/index.html" class="nav-link">Tools</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../users/tools/capture-replay.html" class="nav-link">Capture Replay</a>
</li>
<li class="nav-item">
<a href="../../users/tools/connection-pool.html" class="nav-link">Connection Pool</a>
</li>
<li class="nav-item">
<a href="../../users/tools/connection-cache.html" class="nav-link">Connection Cache</a>
</li>
<li class="nav-item">
<a href="../../users/tools/opm.html" class="nav-link">Object PLC Mapping (OPM)</a>
</li>
<li class="nav-item">
<a href="../../users/tools/scraper.html" class="nav-link">Scraper</a>
</li>
<li class="nav-item">
<a href="../../users/tools/testing.html" class="nav-link">PLC4X without a PLC and Unit Testing</a>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../users/industry40.html" class="nav-link">Industry 4.0 with Apache</a>
</li>
<li class="nav-item">
<a href="../../users/security.html" class="nav-link">Security</a>
</li>
</ul>
</div>
</nav>
<main role="main" class="ml-sm-auto px-4 col-sm-pull col-md-9 col-lg-10 h-100">
<div class="sect1">
<h2 id="playing_around_with_apache_plc4x_with_a_virtual_modbus_plc">Playing around with Apache PLC4X with a virtual Modbus PLC</h2>
<div class="sectionbody">
<div class="paragraph">
<p>If you want to get started with Apache PLC4X, but don&#8217;t have any PLC at hand, this tutorial will demonstrate how you can use a virtual <code>Modbus Slave</code> software to simulate communication with <code>Modbus</code> enabled PLCs.</p>
</div>
<div class="paragraph">
<p>Such a fully open-source software is <code>ModbusPal</code> which is available from <a href="http://modbuspal.sourceforge.net/">here</a>.</p>
</div>
<div class="paragraph">
<p>All you need, is to download the file called <code>ModbusPal.jar</code>.</p>
</div>
<div class="sect2">
<h3 id="setting_up_the_virtual_modbus_slave">Setting up the virtual Modbus Slave</h3>
<div class="paragraph">
<p>In order to run the software, you just need to execute the following command in the same directory you downloaded the Jar to:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>java -jar ModbusPal.jar</pre>
</div>
</div>
<div class="paragraph">
<p>After this you will see the ModbusPal UI, which will look like this:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../images/tutorials/modbus/ModbusPal-1.png" alt="ModbusPal 1" width="300"/>
</div>
<div class="title">Figure 1. ModbusPal Main UI</div>
</div>
<div class="paragraph">
<p>Here be sure that the <code>TCP port</code> is set to <code>502</code> (Which is the default Modbus port).</p>
</div>
<div class="paragraph">
<p>Next click on <code>Add</code> to add a new Modbus slave:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../images/tutorials/modbus/ModbusPal-2.png" alt="ModbusPal 2" width="300"/>
</div>
<div class="title">Figure 2. ModbusPal Add slave UI</div>
</div>
<div class="paragraph">
<p>Select a <code>Slave ID</code> as well as a <code>name</code>.</p>
</div>
<div class="paragraph">
<p>After clicking on <code>Add</code> your new Modbus slave is ready to start.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../images/tutorials/modbus/ModbusPal-3.png" alt="ModbusPal 3" width="300"/>
</div>
<div class="title">Figure 3. ModbusPal Main UI with one started slave</div>
</div>
<div class="paragraph">
<p>By clicking on the <code>Run</code> button your slave is generally ready to communicate.</p>
</div>
<div class="paragraph">
<p>However up until now this new wouldn&#8217;t have anything to share as we haven&#8217;t created any resources, so it would be an empty slave.</p>
</div>
<div class="paragraph">
<p>So as last steps, we have to create some resources to access.</p>
</div>
<div class="paragraph">
<p>In order do to this, click on the <code>eye</code> icon of your newly created slave.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../images/tutorials/modbus/ModbusPal-4.png" alt="ModbusPal 4" width="300"/>
</div>
<div class="title">Figure 4. ModbusPal Main UI with one slave</div>
</div>
<div class="paragraph">
<p>This will bring up an editor in which we can add some so-called <code>Holding registers</code> and some <code>Coils</code>.</p>
</div>
<div class="paragraph">
<p>Let&#8217;s start with adding some Holding registers.</p>
</div>
<div class="paragraph">
<p>So make sure <code>Holding registers</code> is selected and then click on the <code>Add</code> button:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../images/tutorials/modbus/ModbusPal-6.png" alt="ModbusPal 6" width="300"/>
</div>
<div class="title">Figure 5. Holding register view</div>
</div>
<div class="paragraph">
<p>The tool will suggest creating <code>65536</code> new registers, I usually create 10 or so.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<div class="title">Tip</div>
</td>
<td class="content">
When I use ths tool some times I have to click the <code>Add</code> button more than once as the editor doesn&#8217;t always open the first time.
</td>
</tr>
</table>
</div>
<div class="imageblock">
<div class="content">
<img src="../../images/tutorials/modbus/ModbusPal-7.png" alt="ModbusPal 7" width="300"/>
</div>
<div class="title">Figure 6. Add Holding register dialog</div>
</div>
<div class="paragraph">
<p>After this the <code>Holding register</code> tab should look like this:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../images/tutorials/modbus/ModbusPal-9.png" alt="ModbusPal 9" width="300"/>
</div>
<div class="title">Figure 7. Add Holding register dialog</div>
</div>
<div class="paragraph">
<p>Now do the same on the <code>Coils</code> tab, which should look like this after that:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../images/tutorials/modbus/ModbusPal-8.png" alt="ModbusPal 8" width="300"/>
</div>
<div class="title">Figure 8. Add Holding register dialog</div>
</div>
<div class="paragraph">
<p>As a last step, I would suggest to open the <code>Console</code>.</p>
</div>
<div class="paragraph">
<p>You can do this by clicking on the <code>Console</code> button of the main UI.</p>
</div>
<div class="paragraph">
<p>This will open the following window:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="../../images/tutorials/modbus/ModbusPal-5.png" alt="ModbusPal 5" width="300"/>
</div>
<div class="title">Figure 9. Console</div>
</div>
<div class="paragraph">
<p>Here ModbusPal will log every important event &#8230;&#8203; especially when getting new connections from PLC4X.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="some_modbus_basics">Some Modbus basics</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In general Modbus only knows two types of data: <code>Coils</code> and <code>Registers</code>.</p>
</div>
<div class="paragraph">
<p>Coils are always simple <code>bits</code> or <code>boolean</code> values and Registers are always <code>16 bit short values</code>.</p>
</div>
<div class="paragraph">
<p>However there are different types of these and they have different names:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>Discrete Inputs</code> (Boolean values) (read-only)</p>
</li>
<li>
<p><code>Coils</code> (Boolean values) (read-write)</p>
</li>
<li>
<p><code>Input Registers</code> (16 bit short values) (read-only)</p>
</li>
<li>
<p><code>Holding Registers</code> (16 bit short values) (read-write)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For Modbus there is no universally agreed upon notation for addresses, however as the addresses are extremely simple, in PLC4X we address these as follows:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 1. Table Title</caption>
<colgroup>
<col style="width: 50%;"/>
<col style="width: 50%;"/>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Modbus Type</th>
<th class="tableblock halign-left valign-top">PLC4X Address Syntax</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Discrete Inputs</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>discrete-input:{start-number}</code> or <code>discrete-input:{start-number}[{number-of-elements}]</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Coils</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>coil:{start-number}</code> or <code>coil:{start-number}[{number-of-elements}]</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Input Registers</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>input-register:{start-number}</code> or <code>input-register:{start-number}[{number-of-elements}]</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Holding Registers</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>holding-register:{start-number}</code> or <code>holding-register:{start-number}[{number-of-elements}]</code></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>All addresses support a notation with and without a size. If the size is not specified, then PLC4X assumes a size of <code>1</code>.</p>
</div>
<div class="paragraph">
<p>A PLC4X connection-string generally has the same structure for all drivers:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{driver-name}:{transport-name}://{transport-config}?{parameters}</pre>
</div>
</div>
<div class="paragraph">
<p>The fragments <code>transport-name</code> and <code>parameters</code> herby are usually optional, as every driver can support a default-transport, which is used if the transport is omitted.
Also are most drivers implemented in a way that doesn&#8217;t require any parameters.
These are only required if the connection requires some non-default settings.</p>
</div>
<div class="paragraph">
<p>For Modbus the typical transports are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>tcp (transport-config is the ip or host-name of the slave and can be suffixed by a port separated from the ip/host with <code>:</code>)</p>
</li>
<li>
<p>serial (transport-config is the device name of the serial interface)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If we have setup ModbusPal as described above and are running this on the same computer, the connection string to connect to this should be:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>modbus-tcp://localhost</pre>
</div>
</div>
<div class="paragraph">
<p>If you stated ModbusPal on a port different from Modbus' default port <code>502</code> you would have to also provide this port in the connection string.</p>
</div>
<div class="paragraph">
<p>So assuming you started it on port 1502, then the connection string would look as follows:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>modbus-tcp://localhost:1502</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="writing_code">Writing code</h2>
<div class="sectionbody">
<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> &lt;dependency&gt;
&lt;groupId&gt;org.apache.plc4x&lt;/groupId&gt;
&lt;artifactId&gt;plc4j-api&lt;/artifactId&gt;
&lt;version&gt;{project-version}&lt;/version&gt;
&lt;/dependency&gt;</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 using the <code>Modbus</code> protocol, you would need to add the following dependency:</p>
</div>
<div class="listingblock">
<div class="content">
<pre> &lt;dependency&gt;
&lt;groupId&gt;org.apache.plc4x&lt;/groupId&gt;
&lt;artifactId&gt;plc4j-driver-modbus&lt;/artifactId&gt;
&lt;version&gt;{project-version}&lt;/version&gt;
&lt;scope&gt;runtime&lt;/scope&gt;
&lt;/dependency&gt;</pre>
</div>
</div>
<div class="sect2">
<h3 id="connecting">Connecting</h3>
<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 = "modbus-tcp://localhost";
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&#8217;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&#8217;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&#8217;t simulate or features are simply disabled intentionally:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If a PLC and/or protocol don&#8217;t support executing of functions, we simply can&#8217;t provide this functionality.</p>
</li>
<li>
<p>We will be providing stripped down versions of drivers, that for example intentionally don&#8217;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>
<div class="sect2">
<h3 id="reading_data">Reading Data</h3>
<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", "coil:1");
builder.addItem("value-2", "coil:3[4]");
builder.addItem("value-3", "holding-register:1");
builder.addItem("value-4", "holding-register:3[4]");
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.
Hereby the first string value is simply an alias you can give the the address as this is usually a more readable way.
The second argument is then the address string itself.</p>
</div>
<div class="paragraph">
<p>In above example we didn&#8217;t add <code>discrete-input</code> and <code>input-registers</code> as ModbusPal doesn&#8217;t seem to support these.</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&lt;? extends PlcReadResponse&gt; asyncResponse = readRequest.execute();
asyncResponse.whenComplete((response, throwable) -&gt; {
... 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 &lt; 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 compatible.</p>
</div>
</div>
<div class="sect2">
<h3 id="writing_data">Writing Data</h3>
<div class="paragraph">
<p>The code for writing is very similar to the code for reading, however when creating the write request, we have to pass in the data alongside the field definitions.</p>
</div>
<div class="paragraph">
<p>While all of the 4 field types support reading from, only the <code>coil</code> and <code>holding-register</code> field types support writing to.
If you attempt to write to these, this will result in errors.</p>
</div>
<div class="paragraph">
<p>So again, we first check if this driver supports writing (Some drivers such as passive-mode drivers or read-only versions might generally not support writing):</p>
</div>
<div class="listingblock">
<div class="content">
<pre>// Check if this connection support reading of data.
if (!plcConnection.getMetadata().canWrite()) {
logger.error("This connection doesn't support writing.");
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"
PlcWriteRequest.Builder builder = plcConnection.writeRequestBuilder();
builder.addItem("value-1", "coil:1", true);
builder.addItem("value-2", "coil:3[4]", true, false, true, true);
builder.addItem("value-3", "holding-register:1", 42);
builder.addItem("value-4", "holding-register:3[4]", 1, 2, 3, 4);
PlcWriteRequest writeRequest = builder.build();</pre>
</div>
</div>
<div class="paragraph">
<p>You can see that for every element that should be written, the same number of arguments have to be provided.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>PlcWriteResponse response = writeRequest.execute().get();</pre>
</div>
</div>
<div class="paragraph">
<p>Actually executing the write operation is almost identical to the reading, with the only difference, that the result only provides status codes and no values.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>for (String fieldName : response.getFieldNames()) {
if(response.getResponseCode(fieldName) == PlcResponseCode.OK) {
logger.info("Value[" + fieldName + "]: successfully written to device.");
}
// Something went wrong, to output an error message instead.
else {
logger.error("Error[" + fieldName + "]: " + response.getResponseCode(fieldName).name());
}
}</pre>
</div>
</div>
</div>
</div>
</div>
</main>
<footer class="pt-4 my-md-5 pt-md-5 w-100 border-top">
<div class="row justify-content-md-center" style="font-size: 13px">
<div class="col col-6 text-center">
Copyright &#169; 2017&#x2013;2022 <a href="https://www.apache.org/">The Apache Software Foundation</a>.
All rights reserved.<br/>
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.
<br/><div style="text-align:center;">Home screen image taken from <a
href="https://flic.kr/p/chEftd">Flickr</a>, "Tesla Robot Dance" by Steve Jurvetson, licensed
under <a href="https://creativecommons.org/licenses/by/2.0/">CC BY 2.0 Generic</a>, image cropped
and blur effect added.</div>
</div>
</div>
</footer>
</div>
</div>
<!-- Bootstrap core JavaScript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="../../js/jquery.slim.min.js"></script>
<script src="../../js/popper.min.js"></script>
<script src="../../js/bootstrap.min.js"></script>
<script type="text/javascript">
$('.carousel .carousel-item').each(function(){
var next = $(this).next();
if (!next.length) {
next = $(this).siblings(':first');
}
next.children(':first-child').clone().appendTo($(this));
for (let i = 0; i < 3; i++) {
next=next.next();
if (!next.length) {
next = $(this).siblings(':first');
}
next.children(':first-child').clone().appendTo($(this));
}
});
</script>
</body>
</html>