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 ae85d07 Site checkin for project PLC4X: Jenkins Tools
ae85d07 is described below
commit ae85d0711dcad46d0dd280586209c97dc6829271
Author: jenkins <[email protected]>
AuthorDate: Thu Sep 16 20:02:30 2021 +0000
Site checkin for project PLC4X: Jenkins Tools
---
images/apache-plc4x-can-canopen.png | Bin 0 -> 20760 bytes
.../{transports/index.html => protocols/can.html} | 70 +++--
users/protocols/canopen.html | 4 +-
users/protocols/{canopen.html => genericcan.html} | 299 +++------------------
users/transports/{index.html => can.html} | 108 ++++++--
users/transports/index.html | 3 +
6 files changed, 184 insertions(+), 300 deletions(-)
diff --git a/images/apache-plc4x-can-canopen.png
b/images/apache-plc4x-can-canopen.png
new file mode 100644
index 0000000..07b5ec8
Binary files /dev/null and b/images/apache-plc4x-can-canopen.png differ
diff --git a/users/transports/index.html b/users/protocols/can.html
similarity index 87%
copy from users/transports/index.html
copy to users/protocols/can.html
index b4ac505..d62755b 100644
--- a/users/transports/index.html
+++ b/users/protocols/can.html
@@ -159,7 +159,7 @@
<li
class="nav-item">
- <strong class="nav-link">Transports</strong>
+ <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>
@@ -287,29 +287,53 @@
</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="transports">Transports</h2>
+<h2 id="can_bus_driver_adapter">CAN Bus Driver Adapter</h2>
<div class="sectionbody">
-<div class="ulist">
-<ul>
-<li>
-<p><a href="tcp.html">TCP</a></p>
-</li>
-<li>
-<p><a href="udp.html">UDP</a></p>
-</li>
-<li>
-<p><a href="raw-socket.html">Raw Socket</a></p>
-</li>
-<li>
-<p><a href="serial.html">Serial Port</a></p>
-</li>
-<li>
-<p><a href="socketcan.html">SocketCAN</a></p>
-</li>
-<li>
-<p><a href="pcap-replay.html">PCAP replay</a></p>
-</li>
-</ul>
+<div class="paragraph">
+<p>The CAN Bus driver is a special kind of driver which does not bring any
logic.
+Its responsibility is to combine <a href="../transports/can.html">CAN
transport facade</a> and custom application layer protocols.
+In this way, the protocol can use its own "root frame" type which is not
delivered from CAN bus frame.</p>
+</div>
+<div class="sect2">
+<h3 id="more_details_on_the_driver">More details on the driver</h3>
+<div class="paragraph">
+<p>The <code>CANDriverAdapter</code> is a full implementation of Apache PLC4X
API.
+Under the hood adapter will forward all operations to delegate driver.
+Work which is done by the adapter is to transform data incoming via CAN
transport into frame supported by driver.
+In this regard the <code>CANDriverAdapter</code> does not implement any real
protocol.
+All it does is transformation of incoming frames into frame desired by real
driver.</p>
+</div>
+<div class="paragraph">
+<p>Below diagram explains how driver adapter works with CANopen.
+Given that this is currently biggest CAN driver implemented in Apache PLC4X we
will use it as a reference.</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="../../images/users/protocols/apache-plc4x-can-canopen.png"
alt="apache plc4x can canopen" width="1480" height="224"/>
+</div>
+</div>
+<div class="paragraph">
+<p>Looking at left most side of diagram we can see a CAN transport.
+The transport knows how to receive and send data to the CAN bus.
+Transport can create its own intermediate representation of CAN data frame.
+In case of <code>SocketCAN</code> there is a dedicated type called
<code>SocketCANFrame</code>.</p>
+</div>
+<div class="paragraph">
+<p>Most of other drivers in Apache PLC4X which rely on TCP, UDP or serial
transports can unify right above transport.
+Yet due to variety of APIs which are possible to be used with CAN bus such
early unification at API level is not possible.</p>
+</div>
+<div class="paragraph">
+<p>Place where <code>CANDriverAdapter</code> jumps in is once transport formed
the frame structure.
+Then, adapter asks the transport to turn that structure into a
<code>FrameData</code>.
+An instance of <code>FrameData</code> is then passed to an adapter delivered
by CANopen Driver.
+This adapter can then create a <code>CANopenFrame</code> which is processed by
desired driver logic.</p>
+</div>
+<div class="paragraph">
+<p>The return side, when desired driver wants to publish information is a bit
simplified.
+Because <code>FrameData</code> does not be a real type (it is an interface) we
can skip it.
+With a help of a <code>CANFrameBuilder</code> provided by CAN transport driver
can easily construct a structure which is supported by it.
+While this makes an API asymmetric it also makes it possible to use any third
party transport with <code>CANopenDriver</code>.</p>
+</div>
</div>
</div>
</div>
diff --git a/users/protocols/canopen.html b/users/protocols/canopen.html
index 6da7412..a2f8035 100644
--- a/users/protocols/canopen.html
+++ b/users/protocols/canopen.html
@@ -433,13 +433,13 @@ There are multiple articles and sources which attempts to
give introduction, yet
<p>CAN 2.0A uses 11 bit identifier and up to 8 bytes of data.</p>
</li>
<li>
-<p>CAN 2.0B uses 29 bit identifier and up to 64 bytes of data.</p>
+<p>CAN 2.0B uses 29 bit identifier and up to 8 bytes of data.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To make things worse with introduction of CAN FD amount of combinations
increased even more.
-Double check frame format as this integration supports CANopen and does not
support CANopen FD.</p>
+Double check frame format as this integration supports CANopen and does not
support CANopen FD nor CAN 2.0B.</p>
</div>
<div class="paragraph">
<p>Further reading on CAN flavors:
diff --git a/users/protocols/canopen.html b/users/protocols/genericcan.html
similarity index 73%
copy from users/protocols/canopen.html
copy to users/protocols/genericcan.html
index 6da7412..3f3d855 100644
--- a/users/protocols/canopen.html
+++ b/users/protocols/genericcan.html
@@ -125,7 +125,7 @@
<a href="../../users/protocols/bacnetip.html"
class="nav-link">BACnet/IP</a>
</li>
<li class="nav-item">
- <strong class="nav-link">CANopen</strong>
+ <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>
@@ -287,12 +287,16 @@
</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="canopen">CANopen</h2>
+<h2 id="generic_can">Generic CAN</h2>
<div class="sectionbody">
<div class="sect2">
-<h3 id="can_in_automation">CAN in Automation</h3>
+<h3 id="can_bus_semantics">CAN Bus semantics</h3>
<div class="paragraph">
-<p>CANopen is a specific protocol built on top of CAN bus.</p>
+<p>This driver is a generic purpose driver.
+It allows implementing a basic CAN bus listening or writing scenarios.</p>
+</div>
+<div class="paragraph">
+<p>CAN bus open is a specific protocol built on top of CAN bus.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
@@ -311,13 +315,13 @@
<tr>
<td class="tableblock halign-left valign-top"><p
class="tableblock">Code</p></td>
<td class="tableblock halign-left valign-top" colspan="2"><div
class="content"><div class="paragraph">
-<p><code>canopen</code></p>
+<p><code>genericcan</code></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p
class="tableblock">Name</p></td>
<td class="tableblock halign-left valign-top" colspan="2"><div
class="content"><div class="paragraph">
-<p>CANopen (based on CAN 2.0A) - client side</p>
+<p>Generic CAN</p>
</div></div></td>
</tr>
<tr>
@@ -326,7 +330,7 @@
<div class="content">
<pre><dependency>
<groupId>org.apache.plc4x</groupId>
- <artifactId>plc4j-driver-canopen</artifactId>
+ <artifactId>plc4j-driver-can</artifactId>
<version>{current-last-released-version}</version>
</dependency></pre>
</div>
@@ -340,80 +344,36 @@
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Compatible
Transports:</p></td>
-<td class="tableblock halign-left valign-top" colspan="2"><div
class="content"><div class="ulist">
-<ul>
-<li>
-<p><code>socketcan</code></p>
-</li>
-</ul>
+<td class="tableblock halign-left valign-top" colspan="2"><div
class="content"><div class="paragraph">
+<p>Any <code>can</code> transport, see <a href="../transports/can.html">CAN
transport</a></p>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" colspan="3"><p
class="tableblock">Supported Operations</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CANopen
PDO</p></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p><code>read</code> / <code>write</code></p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>PDO messages are broadcasted to the bus and have to be mapped at
application layer.</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">CANopen
SDO</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock">publish</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p><code>read</code> / <code>write</code></p>
+<p><code>write</code></p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>SDO are request/response conversations. Both read and write path is
supported.</p>
+<p>Allows to publish a CAN frame via CAN transport.</p>
</div></div></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock">receive</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
<p><code>subscribe</code></p>
</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
-<ul>
-<li>
-<p>Receiving PDO messages requires construction of valid subscription.</p>
-</li>
-<li>
-<p>It is possible to subscribe to CANopen NMT messages.</p>
-</li>
-</ul>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top" colspan="3"><p
class="tableblock">Options</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p><code>heartbeat</code></p>
-</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>Forces PLC4X to send CANopen heartbeat (NMT) messages to the bus.</p>
+<p>This operation allows listening for incoming data or requests.</p>
</div></div></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p><code>nodeId</code></p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>CAN node identifier. Depending on used CAN version it might be 11 or 29 bit
unsigned int.</p>
-</div></div></td>
+<td class="tableblock halign-left valign-top" colspan="3"><p
class="tableblock">Options</p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p><code>request-timeout</code></p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>Time after which dispatched BUS operation (ie. SDO request) will be marked
as failed.</p>
-</div></div></td>
+<td class="tableblock halign-center valign-top" colspan="3"><p
class="tableblock">none</p></td>
</tr>
</tbody>
</table>
@@ -421,59 +381,16 @@
<div class="sect2">
<h3 id="more_details_on_the_driver">More details on the driver</h3>
<div class="paragraph">
-<p>CAN, despite (or due) to its popularity has ambiguous meaning.
-There are multiple articles and sources which attempts to give introduction,
yet very few of them is consistent between each other.</p>
+<p>Given popularity of CAN in multiple market segments there is variety of
protocols which can’t be published.
+Also, for many cases which are data acquisition oriented it is necessary to
tap only parts of communications.</p>
</div>
<div class="paragraph">
-<p>There are two dominant formats of frames - CAN 2.0A and 2.0B:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>CAN 2.0A uses 11 bit identifier and up to 8 bytes of data.</p>
-</li>
-<li>
-<p>CAN 2.0B uses 29 bit identifier and up to 64 bytes of data.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>To make things worse with introduction of CAN FD amount of combinations
increased even more.
-Double check frame format as this integration supports CANopen and does not
support CANopen FD.</p>
-</div>
-<div class="paragraph">
-<p>Further reading on CAN flavors:
-<a
href="https://en.wikipedia.org/wiki/CAN_bus";>https://en.wikipedia.org/wiki/CAN_bus</a></p>
-</div>
-<div class="paragraph">
-<p>Default transport used with this protocol is socketcan.
-Currently, only 2.0A format (up to 8 bytes of data) is supported.</p>
-</div>
-<div class="paragraph">
-<p>Implemented driver supports currently socketcan transport.
-Change of transport requires code modifications and injection of new
"transport" type which will encode CANopen payloads to specific frame
format.</p>
-</div>
-<div class="paragraph">
-<p>Socketcan seems to be most widespread way to access CAN bus.
-It also masks different hardware variants which might come with their own
drivers.</p>
-</div>
-<div class="paragraph">
-<p>The CANopen specification defines Object Dictionary (OD).
-This driver does honor OD structure through usage of index and sub index for
addressing fields.
-It does not ship Electronic Data Sheet (EDS) parser leaving it for
applications who wish to utilize it.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="address_format">Address Format</h3>
-<div class="paragraph">
-<p>CANopen specification defines several groups of addresses dedicated to
certain kind of operations.
-Critical services and message exchanges related with them have lower
identifiers making them wining eventual bus access.</p>
-</div>
-<div class="paragraph">
-<p>The array size block is necessary only if application expect same value
several times.
-If SDO returns for example 4 values of UNSIGNED8 it can be declared as
<code><service>:<nodeId>:UNSIGNED8[4]</code> for PDO.
-Equivalent for SDO is
<code><service>:<nodeId>:<index>/<subindex>:UNSIGNED8[4]</code>.</p>
+<p>This driver allows to model incoming and outgoing communication using plain
Apache PLC4X api.
+The written CAN data is constructed from fields submitted via write request
builder.
+The receiving data is transformed in similar fashion, based on subscribed
fields.</p>
</div>
+<div class="sect3">
+<h4 id="address_format">Address format</h4>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 20%;"/>
@@ -491,138 +408,37 @@ Equivalent for SDO is
<code><service>:<nodeId>:<index>/<sub
</thead>
<tbody>
<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">SDO</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock">n/a</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>SDO:nodeId:index/subindex:type[arraySize]</p>
+<p>nodeId:type[arraySize]</p>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
<ul>
<li>
-<p><code>read</code></p>
-</li>
-<li>
<p><code>write</code></p>
</li>
-</ul>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>SDO is for request/response communication.
-Both expedited and segmented modes are supported.
-No support for block transfer.</p>
-</div>
-<div class="paragraph">
-<p>Transfer kind is automatically determined based on payload length.
-All numeric values - ndodeId, index, subindex can be specified using
hexadecimal notation (ie. <code>0xA</code>).</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">PDO</p></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
-<ul>
-<li>
-<p>TRANSMIT_PDO_1:nodeId:type[arraySize]</p>
-</li>
-<li>
-<p>RECEIVE_PDO_1:nodeId:type[arraySize]</p>
-</li>
-<li>
-<p>TRANSMIT_PDO_2:nodeId:type[arraySize]</p>
-</li>
-<li>
-<p>RECEIVE_PDO_2:nodeId:type[arraySize]</p>
-</li>
-<li>
-<p>TRANSMIT_PDO_3:nodeId:type[arraySize]</p>
-</li>
-<li>
-<p>RECEIVE_PDO_3:nodeId:type[arraySize]</p>
-</li>
-<li>
-<p>TRANSMIT_PDO_4:nodeId:type[arraySize]</p>
-</li>
-<li>
-<p>RECEIVE_PDO_4:nodeId:type[arraySize]</p>
-</li>
-</ul>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
-<ul>
<li>
<p><code>subscribe</code></p>
</li>
-<li>
-<p><code>write</code></p>
-</li>
</ul>
</div></div></td>
<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>PDO is an asynchronous operation hence receiving of it requires
subscription.
-Check Apache PLC4X API documentation for more detailed example of how to use
subscriptions API.
-Subscriber will be notified with value mapped to type defined in field
syntax.</p>
+<p>There is only one syntax which is currently supported by this driver.</p>
</div></div></td>
</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">NMT</p></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
-<ul>
-<li>
-<p>NMT</p>
-</li>
-<li>
-<p>NMT:nodeId</p>
-</li>
-</ul>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
-<ul>
-<li>
-<p><code>subscribe</code></p>
-</li>
-</ul>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>NMT messages are sent using CAN node ID <code>0</code>.
-They have the highest priority on the bus.
-Messages of this kind indicate operating state of an node (booted,
operational).</p>
-</div>
+</tbody>
+</table>
<div class="paragraph">
-<p>Subscriptions to this service receive structure with two fields:
<code>node</code> (USINT) and <code>state</code> (USINT).
-If subscription sets <code>nodeId</code> to 0 it will receive state updates
for all bus participants.</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">HEARTBEAT</p></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
-<ul>
-<li>
-<p>HEARTBEAT</p>
-</li>
-<li>
-<p>HEARTBEAT:nodeId</p>
-</li>
-</ul>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
-<ul>
-<li>
-<p><code>subscribe</code></p>
-</li>
-</ul>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
-<p>HEARTBEAT messages have the lowest priority on the bus.
-They have the highest priority on the bus.
-Messages of this kind indicate operating state of an node (booted,
operational).</p>
+<p>Pay attention.
+You can use multiple fields to write and subscribe actual data.
+All fields must sum to up to 64 bits.
+If you subscribe less, then remaining data is discarded and not available via
PLC4X api.</p>
</div>
<div class="paragraph">
-<p>Subscriptions to this service receive structure with two fields:
<code>node</code> (USINT) and <code>state</code> (USINT).
-If subscription sets <code>nodeId</code> to 0 it will receive state updates
for all bus participants.</p>
-</div></div></td>
-</tr>
-</tbody>
-</table>
+<p>The data will be sent in the same order as fields.</p>
+</div>
<div class="paragraph">
-<p>Below table contains type mapping defined in CANopen specification.</p>
+<p>Below table contains type mapping defined in Generic CAN driver.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
@@ -731,45 +547,12 @@ If subscription sets <code>nodeId</code> to 0 it will
receive state updates for
<td class="tableblock halign-left valign-top"><p class="tableblock">64</p></td>
<td class="tableblock halign-left valign-top"><p
class="tableblock">LREAL</p></td>
</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">RECORD</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">8 *
size</p></td>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">BYTE</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">OCTET_STRING</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">8 *
size</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">STRING
(UTF-8)</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">VISIBLE_STRING</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">8 *
size</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">STRING
(UTF-8)</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">TIME_OF_DAY</p></td>
-<td class="tableblock halign-center valign-top" colspan="2"><p
class="tableblock">unsupported</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">TIME_DIFFERENCE</p></td>
-<td class="tableblock halign-center valign-top" colspan="2"><p
class="tableblock">unsupported</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p
class="tableblock">UNICODE_STRING</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">8 *
size</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">STRING
(UTF-8)</p></td>
-</tr>
</tbody>
</table>
<div class="paragraph">
-<p>All string types are decoded using UTF-8 encoding regardless of their kind
(octet, visible, unicode).
-In case if device returns text using different encoding it is recommended to
use <code>RECORD</code> type and construct text manually above PLC4X.</p>
+<p>The type table is similar to CANopen.
+Main difference is lack of support for string types.</p>
</div>
-<div class="paragraph">
-<p>The size in case of variable length structures is automatically assumed to
full length of SDO answer.
-In case of writing length of field can be ommited.
-For example request <code>write(SDO:1:2/3:RECORD, payload)</code> will try to
write whole payload to specified address.
-Same applies to responses sent by devies as requester often might not know
full length of reply payload.</p>
</div>
</div>
</div>
diff --git a/users/transports/index.html b/users/transports/can.html
similarity index 83%
copy from users/transports/index.html
copy to users/transports/can.html
index b4ac505..5dfaf27 100644
--- a/users/transports/index.html
+++ b/users/transports/can.html
@@ -159,7 +159,7 @@
<li
class="nav-item">
- <strong class="nav-link">Transports</strong>
+ <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>
@@ -287,28 +287,102 @@
</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="transports">Transports</h2>
+<h2 id="can">CAN</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>A CAN transport is a special category of transport which can bring CAN
frame data to various drivers.
+All of these transports are meant to follow basic CAN frame data semantics.</p>
+</div>
+<div class="paragraph">
+<p>Each CAN transport must provide a <code>CANFrameBuilder</code> interface
realization.
+This builder can be used by drivers which implement application layer
protocols on top of CAN bus.
+The builder allow constructing requests which should be passed to the bus
operations.</p>
+</div>
+<div class="paragraph">
+<p>Note this API is available since Apache PLC4X 0.9.</p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<colgroup>
+<col style="width: 22.2222%;"/>
+<col style="width: 22.2222%;"/>
+<col style="width: 55.5556%;"/>
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Name</th>
+<th class="tableblock halign-left valign-top">Value</th>
+<th class="tableblock halign-left valign-top">Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock">Code</p></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
+<p>not available</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="paragraph">
+<p>This transport ships only additional API on top of existing Apache PLC4X
Transport API.</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock">Name</p></td>
+<td class="tableblock halign-left valign-top" colspan="2"><div
class="content"><div class="paragraph">
+<p>CAN</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Maven
Dependency</p></td>
+<td class="tableblock halign-left valign-top" colspan="2"><div
class="content"><div class="listingblock">
+<div class="content">
+<pre><dependency>
+ <groupId>org.apache.plc4x</groupId>
+ <artifactId>plc4j-transport-can</artifactId>
+ <version>{current-last-released-version}</version>
+</dependency></pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock">Options:</p></td>
+<td class="tableblock halign-left valign-top" colspan="2"><div
class="content"><div class="paragraph">
+<p><strong>none</strong>, an abstract transport</p>
+</div></div></td>
+</tr>
+</tbody>
+</table>
+<div class="paragraph">
+<p>Main purpose of this transport is basic unification of various CAN bus APIs.
+There is no unified way to access CAN (beside SocketCAN for linux) across
multiple platforms.
+We brought this simplistic facade-alike API to serve very basic project needs.
+Its main purpose is to let transport implementer bridge with actual transport
or another library.
+With as little effort as possible.</p>
+</div>
+<div class="paragraph">
+<p>Major advantage of CAN transport facade is possibility to implement
application layer protocols in a fully portable way.
+This flexibility is not guaranteed with SocketCAN alone.</p>
+</div>
+<div class="paragraph">
+<p>The CAN transport responsibility is to bring CAN data to driver implementer.
+This API does not enforce, require or promote a low level bus operations.
+In this regard, these operations can be made by library available for specific
CAN adapter in use.</p>
+</div>
+<div class="sect2">
+<h3 id="developer_notes">Developer notes</h3>
+<div class="paragraph">
+<p>Usage of CAN transport APIs is recommended for portability reasons.
+Please have a look on <a href="../protocols/can.html">CAN</a> describe usage
of CAN driver adapter with CAN transport facade.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="compatible_can_transports">Compatible CAN transports</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
-<p><a href="tcp.html">TCP</a></p>
-</li>
-<li>
-<p><a href="udp.html">UDP</a></p>
-</li>
-<li>
-<p><a href="raw-socket.html">Raw Socket</a></p>
-</li>
-<li>
-<p><a href="serial.html">Serial Port</a></p>
-</li>
-<li>
<p><a href="socketcan.html">SocketCAN</a></p>
</li>
-<li>
-<p><a href="pcap-replay.html">PCAP replay</a></p>
-</li>
</ul>
</div>
</div>
diff --git a/users/transports/index.html b/users/transports/index.html
index b4ac505..2f45996 100644
--- a/users/transports/index.html
+++ b/users/transports/index.html
@@ -304,6 +304,9 @@
<p><a href="serial.html">Serial Port</a></p>
</li>
<li>
+<p><a href="can.html">CAN bus</a></p>
+</li>
+<li>
<p><a href="socketcan.html">SocketCAN</a></p>
</li>
<li>
