| <!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 – </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"> |
| <strong class="nav-link">General Concepts</strong> |
| </li> |
| <li class="nav-item"> |
| <a href="../../users/getting-started/virtual-modbus.html" class="nav-link">Virtual Modbus</a> |
| </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="general_concepts">General Concepts</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>On this page we’ll give a short introduction to the most important concepts that will help you understand Apache PLC4X better.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The most important concepts from a user perspective are in general:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Connections — protocols — transports — configuration</p> |
| </li> |
| <li> |
| <p>Addresses</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The two parts where we have built the PLC4X API to abstract are the <code>connection strings</code> and the <code>address strings</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Both are pretty dependent on the type of device you are planning to communicate with. However these can both be easily configured in an external configuration or passed in as arguments.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="connections">Connections</h3> |
| <div class="paragraph"> |
| <p>In general a connection is a physical or logical connection between two endpoints.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This connection uses a technical transport mechanism and passes data following a given protocol logic. |
| Therefore we have modeled both of these aspects separately.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Let’s start with the <code>Transports</code>. The following are currently available, but they will probably be more soon:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>TCP</p> |
| </li> |
| <li> |
| <p>UDP</p> |
| </li> |
| <li> |
| <p>Raw Socket</p> |
| </li> |
| <li> |
| <p>Serial Port</p> |
| </li> |
| <li> |
| <p>PCAP replay</p> |
| </li> |
| <li> |
| <p>Test</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>While TCP, UDP are based on the normal TCP and UDP stack of the operating system, Raw sockets directly provide low-level access to <code>Ethernet Frames</code>. |
| This allows them to not only be used in passive-mode drivers for simply reading all network traffic, it also allows communicating with protocols that are Ethernet based, but don’t use TCP or UDP. This is usually the case with <code>Fieldbus</code> protocols which usually require lower latency than TCP and UDP can provide.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Serial Port transport simply reads and writes data to a given serial port.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The probably most special forms of transport are currently the <code>PCAP replay</code> and the <code>Test</code> transport.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>PCAP replay</code> transport allows recording network traffic using tools like <code>WireShark</code> and to simply replay these recorded <code>pcap</code> and <code>pcapng</code> files. This is really helpful for writing new drivers (especially passive mode drivers) without having to be connected to the real device.</p> |
| </div> |
| <div class="paragraph"> |
| <p>From a driver point of view there is actually no difference between a <code>Raw Socket</code> and a <code>PCAP replay</code> transport.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>Test</code> transport is generally built for being used inside the PLC4X testsuite as it allows fine-grained access to the input and output of the drivers.</p> |
| </div> |
| <div class="paragraph"> |
| <p>With this we can explicitly control which data is passed into and retrieved from drivers and to validate this in unit- and integration-tests.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="connection_strings">Connection Strings</h4> |
| <div class="paragraph"> |
| <p>A fully qualified PLC4X connection string would look like this:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>{driver code}:{transport code}://{transport config}?{options}</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>driver code</code> generally selects the protocol we want to use, the <code>transport code</code> now selects the type of transport that should be used.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Depending on the selected transport mechanism the <code>transport config</code> tells the transport which resource it should use.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example with a <code>TCP</code> and <code>UDP</code> transport, this will be the <code>IP address</code> or <code>hostname</code> optionally followed by the <code>Port</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a <code>Serial</code> transport this will be the <code>name of the serial interface</code>. <code>Raw Sockets</code> will require the <code>device name</code> and so on.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a full description of all transports and their options, please consult the <code>Transport Documentation</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The last segment - <code>options</code> - can be used to fine tune some protocol or transport options to non-default values. For details on these options, please have a look at the <code>Protocol Documentation</code> and the <code>Transport Documentation</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The general structure of this part is always the same:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>?{option-1-name}={option-1-value}&{option-2-name}={option-2-value}&{option-3-name}={option-3-value}</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>So in general the options are stared with a <code>?</code> and then followed by <code>name-value</code> pairs, which are separated by ampersand characters <code>&</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A driver for a given protocol however usually has a <code>default transport</code>, so sometimes it is possible to omit the transport code.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Then this shorter version can be used. Please inspect the <code>Protocol Documentation</code> on <code>default transports</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>{driver code}://{transport config}?{options}</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="individual_resource_addresses">Individual Resource Addresses</h3> |
| <div class="paragraph"> |
| <p>Addresses for individual fields on a PLC are extremely dependent on the used protocol. |
| As we usually decided to stick to the address formats that are used in those particular environments.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Please check the <code>Protocol Documentation</code> on details about these address formats.</p> |
| </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 © 2017–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> |
