Git-Mirrors/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2025-08-01 19:16:08 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated documentation

Browse source
This commit is contained in:
Mark Qvist 2022-04-07 20:15:35 +02:00
parent ee90605b30
commit fc83c5b082
9 changed files with 159 additions and 124 deletions
Download patch file Download diff file Expand all files Collapse all files

56
docs/manual/understanding.html
View file

@ -75,8 +75,7 @@ be a microwave network using off-the-shelf radios. At the time of release of thi
recommended setup for development and testing is using LoRa radio modules with an open source firmware
(see the section <a class="reference internal" href="#understanding-referencesystem"><span class="std std-ref">Reference System Setup</span></a>), connected to a small
computer like a Raspberry Pi. As an example, the default reference setup provides a channel capacity
of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (indefinitely extendable
by using multiple hops).</p>
of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (extendable by using multiple hops).</p>
</div>
<div class="section" id="goals">
<span id="understanding-goals"></span><h2>Goals<a class="headerlink" href="#goals" title="Permalink to this headline"></a></h2>
@ -602,70 +601,73 @@ of codes to reliably transfer any amount of data. They can be used to transfer d
or stream data directly from files.</p>
</div>
</div>
<div class="section" id="reference-system-setup">
<span id="understanding-referencesystem"></span><h2>Reference System Setup<a class="headerlink" href="#reference-system-setup" title="Permalink to this headline"></a></h2>
<p>This section will detail the recommended <em>Reference System Setup</em> for Reticulum. It is important to
note that Reticulum is designed to be usable over more or less any medium that allows you to send
and receive data in a digital form, and satisfies some very low minimum requirements. The
communication channel must support at least half-duplex operation, and provide an average
throughput of around 1000 bits per second, and supports a physical layer MTU of 500 bytes. The
Reticulum software should be able to run on more or less any hardware that can provide a Python 3.x
<div class="section" id="reference-setup">
<span id="understanding-referencesystem"></span><h2>Reference Setup<a class="headerlink" href="#reference-setup" title="Permalink to this headline"></a></h2>
<p>This section will detail a recommended <em>Reference Setup</em> for Reticulum. It is important to
note that Reticulum is designed to be usable on more or less any computing device, and over more
or less any medium that allows you to send and receive data, which satisfies some very low
minimum requirements.</p>
<p>The communication channel must support at least half-duplex operation, and provide an average
throughput of around 500 bits per second, and supports a physical layer MTU of 500 bytes. The
Reticulum stack should be able to run on more or less any hardware that can provide a Python 3.x
runtime environment.</p>
<p>That being said, the reference setup has been outlined to provide a common platform for anyone
<p>That being said, this reference setup has been outlined to provide a common platform for anyone
who wants to help in the development of Reticulum, and for everyone who wants to know a
recommended setup to get started. A reference system consists of three parts:</p>
recommended setup to get started experimenting. A reference system consists of three parts:</p>
<ul class="simple">
<li><dl class="simple">
<dt><strong>A channel access device</strong></dt><dd><p>Or <em>CAD</em> , in short, provides access to the physical medium whereupon the communication
<dt><strong>An Interface Device</strong></dt><dd><p>Which provides access to the physical medium whereupon the communication
takes place, for example a radio with an integrated modem. A setup with a separate modem
connected to a radio would also be termed a “channel access device”.</p>
connected to a radio would also be an interface device.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>A host device</strong></dt><dd><p>Some sort of computing device that can run the necessary software, communicates with the
channel access device, and provides user interaction.</p>
<dt><strong>A Host Device</strong></dt><dd><p>Some sort of computing device that can run the necessary software, communicate with the
interface device, and provide user interaction.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>A software stack</strong></dt><dd><p>The software implementing the Reticulum protocol and applications using it.</p>
<dt><strong>A Software Stack</strong></dt><dd><p>The software implementing the Reticulum protocol and applications using it.</p>
</dd>
</dl>
</li>
</ul>
<p>The reference setup can be considered a relatively stable platform to develop on, and also to start
building networks on. While details of the implementation might change at the current stage of
building networks or applications on. While details of the implementation might change at the current stage of
development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
the current reference setup has been determined to provide a functional platform for many years
into the future. The current Reference System Setup is as follows:</p>
<ul class="simple">
<li><dl class="simple">
<dt><strong>Channel Access Device</strong></dt><dd><p>A data radio consisting of a LoRa radio module, and a microcontroller with open source
<dt><strong>Interface Device</strong></dt><dd><p>A data radio consisting of a LoRa radio module, and a microcontroller with open source
firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
MHz frequency bands. More details can be found on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>Host device</strong></dt><dd><p>Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
<dt><strong>Host Device</strong></dt><dd><p>Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
recommended.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>Software stack</strong></dt><dd><p>The current Reference Implementation Release of Reticulum, running on a Debian based
<dt><strong>Software Stack</strong></dt><dd><p>The most recently released Python Implementation of Reticulum, running on a Debian based
operating system.</p>
</dd>
</dl>
</li>
</ul>
<p>It is very important to note, that the reference channel access device <strong>does not</strong> use the LoRaWAN
standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
need a plain LoRa radio module connected to an MCU with the correct firmware. Full details on how to
<p>To avoid confusion, it is very important to note, that the reference interface device <strong>does not</strong>
use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
need a plain LoRa radio module connected to an controller with the correct firmware. Full details on how to
get or make such a device is available on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
<p>With the current reference setup, it should be possible to get on a Reticulum network for around 100$
even if you have none of the hardware already, and need to purchase everything.</p>
<p>This reference setup is of course just a recommendation for getting started easily, and you should
tailor it to your own specific needs, or whatever hardware you have available.</p>
</div>
<div class="section" id="protocol-specifics">
<span id="understanding-protocolspecifics"></span><h2>Protocol Specifics<a class="headerlink" href="#protocol-specifics" title="Permalink to this headline"></a></h2>
@ -736,7 +738,7 @@ proof 11
+- Packet Example -+
HEADER FIELD ADDRESSES FIELD CONTEXT FIELD DATA FIELD
HEADER FIELD DESTINATION FIELDS CONTEXT FIELD DATA FIELD
_______|_______ ________________|________________ ________|______ __|_
| | | | | | | |
01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
@ -750,7 +752,7 @@ proof 11
+- Packet Example -+
HEADER FIELD ADDRESSES FIELD CONTEXT FIELD DATA FIELD
HEADER FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
_______|_______ _______|_______ ________|______ __|_
| | | | | | | |
00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]
@ -813,7 +815,7 @@ proof 11
<li><a class="reference internal" href="#resources">Resources</a></li>
</ul>
</li>
<li><a class="reference internal" href="#reference-system-setup">Reference System Setup</a></li>
<li><a class="reference internal" href="#reference-setup">Reference Setup</a></li>
<li><a class="reference internal" href="#protocol-specifics">Protocol Specifics</a><ul>
<li><a class="reference internal" href="#packet-prioritisation">Packet Prioritisation</a></li>
<li><a class="reference internal" href="#binary-packet-format">Binary Packet Format</a></li>