Google Git
Sign in
apache / plc4x-website / 2dff5a181c3c96b552b4c64a5eb20d816da0a398 / . / developers / code-gen / protocol / df1.html
blob: e7ba53296f838551e3fb34d195b64ffdb0c22460 [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">
<a class="nav-link" href="../../../users/index.html">Users</a>
</li>
<li class="nav-item active">
<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="../../../developers/infrastructure/issues.html" class="nav-link">Bug & Issue Tracker</a>
</li>
<li class="nav-item">
<a href="../../../developers/index.html" class="nav-link">Section Home</a>
</li>
<li class="nav-item">
<a href="../../../developers/preparing/index.html" class="nav-link">Preparing your Computer</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../../developers/preparing/linux.html" class="nav-link">Linux</a>
</li>
<li class="nav-item">
<a href="../../../developers/preparing/macos.html" class="nav-link">Mac OS</a>
</li>
<li class="nav-item">
<a href="../../../developers/preparing/windows.html" class="nav-link">Windows</a>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../../developers/building.html" class="nav-link">Building</a>
</li>
<li class="nav-item">
<a href="../../../developers/contributing.html" class="nav-link">Contributing</a>
</li>
<li class="nav-item">
<a href="../../../developers/tutorials/index.html" class="nav-link">Tutorials</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../../developers/tutorials/writing-driver.html" class="nav-link">Writing Drivers</a>
</li>
<li class="nav-item">
<a href="../../../developers/tutorials/testing-serializers-and-parsers.html" class="nav-link">Testing Drivers</a>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../../developers/code-gen/index.html" class="nav-link">Code Generation</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../../developers/code-gen/protocol/mspec.html" class="nav-link">Protocol: MSpec Format</a>
</li>
<li class="nav-item">
<a href="../../../developers/code-gen/language/freemarker.html" class="nav-link">Language: Apache Freemarker</a>
</li>
<li class="nav-item">
<strong class="nav-link">Example: DF1 MSpec</strong>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../../developers/infrastructure/index.html" class="nav-link">Infrastructure</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../../developers/infrastructure/ci.html" class="nav-link">Continuous Integration</a>
</li>
<li class="nav-item">
<a href="../../../developers/infrastructure/issues.html" class="nav-link">Bug & Issue Tracker</a>
</li>
<li class="nav-item">
<a href="../../../developers/infrastructure/sonar.html" class="nav-link">Code Analysis</a>
</li>
<li class="nav-item">
<a href="../../../developers/infrastructure/wiki.html" class="nav-link">Wiki</a>
</li>
<li class="nav-item">
<a href="../../../developers/infrastructure/vm.html" class="nav-link">Build VM</a>
</li>
<li class="nav-item">
<a href="../../../developers/infrastructure/website.html" class="nav-link">Website</a>
</li>
<li class="nav-item">
<a href="../../../developers/infrastructure/vpn.html" class="nav-link">IoT VPN</a>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../../developers/release/index.html" class="nav-link">Releasing</a>
<ul class="flex-column pl-4 nav">
<li class="nav-item">
<a href="../../../developers/release/release.html" class="nav-link">Releasing</a>
</li>
<li class="nav-item">
<a href="../../../developers/release/validation.html" class="nav-link">Validating</a>
</li>
<li class="nav-item">
<a href="../../../developers/release/build-tools.html" class="nav-link">Releasing Build-Tools</a>
</li>
</ul>
</li>
<li class="nav-item">
<a href="../../../developers/team.html" class="nav-link">Team</a>
</li>
<li class="nav-item">
<a href="../../../developers/decisions.html" class="nav-link">Decision Making</a>
</li>
<li class="nav-item">
<a href="../../../developers/maturity.html" class="nav-link">Maturity</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="example_df1_mspec">Example: DF1 MSpec</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The DF1 protocol has three basic messages: a command message, acknowledge and not acknowledge.
A <code>0x10</code> is used as delimiter to differentiate between the messages and parts of the command message.</p>
</div>
<table class="tableblock frame-all grid-all" style="width: 25%;">
<colgroup>
<col style="width: 50%;"/>
<col style="width: 50%;"/>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">ACK</th>
<th class="tableblock halign-center valign-top">NAK</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">10 06</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">10 15</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>This is what a read command message looks like in full-duplex mode using CRC as checksum:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6924%;"/>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Name</th>
<th class="tableblock halign-center valign-top">DLE</th>
<th class="tableblock halign-center valign-top">STX</th>
<th class="tableblock halign-center valign-top">DST</th>
<th class="tableblock halign-center valign-top">SRC</th>
<th class="tableblock halign-center valign-top">CMD</th>
<th class="tableblock halign-center valign-top">STS</th>
<th class="tableblock halign-center valign-top">TNS</th>
<th class="tableblock halign-center valign-top">ADDR</th>
<th class="tableblock halign-center valign-top">SIZE</th>
<th class="tableblock halign-center valign-top">DLE</th>
<th class="tableblock halign-center valign-top">ETX</th>
<th class="tableblock halign-center valign-top">CRC</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">Value</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">10</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">02</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">01</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">00</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX XX</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX XX</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">02</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">10</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">03</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX XX</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The according response with the requested byte data:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6923%;"/>
<col style="width: 7.6924%;"/>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Name</th>
<th class="tableblock halign-center valign-top">DLE</th>
<th class="tableblock halign-center valign-top">STX</th>
<th class="tableblock halign-center valign-top">DST</th>
<th class="tableblock halign-center valign-top">SRC</th>
<th class="tableblock halign-center valign-top">CMD</th>
<th class="tableblock halign-center valign-top">STS</th>
<th class="tableblock halign-center valign-top">TNS</th>
<th class="tableblock halign-center valign-top">DATA</th>
<th class="tableblock halign-center valign-top">SIZE</th>
<th class="tableblock halign-center valign-top">DLE</th>
<th class="tableblock halign-center valign-top">ETX</th>
<th class="tableblock halign-center valign-top">CRC</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">Value</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">10</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">02</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">41</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">00</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX XX</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX XX</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">02</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">10</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">03</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">XX XX</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>Every message starts with a <code>DLE = 0x10</code>. The second byte is used to differentiate what type of message will follow.
In the case of a command message it is <code>0x02</code>. DST and SRC specify the target and source of the message.
<code>CMD = 0x01</code> means an unprotected read is requested, the command response code is always attained with the addition of <code>0x40</code>. STS is a status byte,
TNS is the transaction counter that is incremented by the master and used to recognize the specific message response.
ADDR is the memory address being requested, size specifies how many bytes are to be read.
DLE + ETX mark the end of the message, the last two bytes are the CRC that is calculated using the previously sent bytes.</p>
</div>
<div class="paragraph">
<p>Here is the MSpec to model the behaviour:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[discriminatedType DF1Symbol
[const uint 8 messageStart 0x10]
[discriminator uint 8 symbolType]
[typeSwitch 'symbolType'
['0x02' DF1SymbolMessageFrame
[simple uint 8 destinationAddress]
[simple uint 8 sourceAddress]
[simple DF1Command command]
[const uint 8 messageEnd 0x10]
[const uint 8 endTransaction 0x03]
[checksum uint 16 'crc' 'STATIC_CALL("org.apache.plc4x.java.df1.readwrite.utils.StaticHelper.crcCheck", destinationAddress, sourceAddress, command)']
]
['0x06' DF1SymbolMessageFrameACK
]
['0x15' DF1SymbolMessageFrameNAK
]
]
]
[discriminatedType DF1Command
[discriminator uint 8 commandCode]
[simple uint 8 status]
[simple uint 16 transactionCounter]
[typeSwitch 'commandCode'
['0x01' DF1UnprotectedReadRequest
[simple uint 16 address]
[simple uint 8 size]
]
['0x41' DF1UnprotectedReadResponse
[manualArray uint 8 'data' terminated 'STATIC_CALL("org.apache.plc4x.java.df1.readwrite.utils.StaticHelper.dataTerminate", io)' 'STATIC_CALL("org.apache.plc4x.java.df1.readwrite.utils.StaticHelper.readData", io)' 'STATIC_CALL("org.apache.plc4x.java.df1.readwrite.utils.StaticHelper.writeData", io, element)' 'STATIC_CALL("org.apache.plc4x.java.df1.readwrite.utils.StaticHelper.dataLength", data)']
]
]
]</pre>
</div>
</div>
<div class="paragraph">
<p>The basic object is the DF1Symbol, where the second byte is used to distinguish between the different message types using a typeSwitch.
In the case of a command message, the message frame contains the DF1Command to further differentiate between the command types.
Currently only the unprotected read and its response are implemented.</p>
</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>