William/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2024-11-22 13:40:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/manual/_sources/gettingstartedfast.rst.txt
View File

@ -97,32 +97,36 @@ The ``TCPServerInterface`` allows users to host an instance accessible over TCP/
method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``, method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``,
however it also leaks considerable metadata about the server host. however it also leaks considerable metadata about the server host.
Direct TCP client connections are able to see your node's IP address and may be able Direct TCP client connections are able to see the IP address of your instance and may be able
to use this information to determine your location or identity. Adversaries to use this information to determine your location or identity. Adversaries
inspecting your network's internet packets may be able to record packet metadata inspecting your packets may be able to record packet metadata like time of transmission and packet size.
like time of transmission and packet size. By default TCP does not encrypt traffic, Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
so an adversary may be able to use packet inspection to learn that a system is running packet inspection to learn that a system is running Reticulum, and what other IP adresses connect to it.
Reticulum, and what other IP adresses connect to it. Hosting a node via TCP server also Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
requires a public IP address. which most Internet connections don't offer anymore.
The ``I2PInterface`` routes messages through the `Invisible Internet Protocol The ``I2PInterface`` routes messages through the `Invisible Internet Protocol
(I2P) <https://geti2p.net/en/>`_. To properly use this interface, users must also run an I2P daemon in (I2P) <https://geti2p.net/en/>`_. To properly use this interface, users must also run an I2P daemon in
parallel to ``rnsd``. For always-on nodes it is recommended to use `i2pd <https://i2pd.website/>`_ because it parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_ because it
generally runs more efficiently. generally runs more efficiently.
By default, I2P will fully encrypt all traffic sent over the network, and By default, I2P will encrypt all traffic sent over the Internet, and
obfuscate both the sender's and receiver's IP addresses. Running an I2P node hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
will also relay other I2P user's encrypted packets, which will use extra will also relay other I2P user's encrypted packets, which will use extra
bandwidth and compute power, but also makes timing attacks and other forms of bandwidth and compute power, but also makes timing attacks and other forms of
deep-packet-inspection much more difficult. Similar to RNS, I2P uses cryptographic deep-packet-inspection much more difficult.
public keys as destination addresses, which allows users to host nodes on non-static IPs.
I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls.
In general it is recommended to use an I2P node if you want to host a publically accessible In general it is recommended to use an I2P node if you want to host a publically accessible
instance, while preserving anonymity. If you care more about performance, and a slightly instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP. easier setup, use TCP.
There is a experimental public testnet you can join by adding one of the following Connect to the Public Testnet
interfaces to your ``.reticulum/config`` file: ===========================================
An experimental public testnet has been made accessible over both I2P and TCP. You can join it
by adding one of the following interfaces to your ``.reticulum/config`` file:
.. code:: .. code::
@ -141,6 +145,10 @@ interfaces to your ``.reticulum/config`` file:
interface_enabled = yes interface_enabled = yes
peers = ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha.b32.i2p peers = ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha.b32.i2p
Many other Reticulum instances are connecting to this testnet, and you can also join it
via other entry points if you know them. There is absolutely no control over the network
topography, usage or what types of instances connect. It will also occasionally be used
to test various failure scenarios, and there are no availability or service guarantees.
Develop a Program with Reticulum Develop a Program with Reticulum
=========================================== ===========================================

60
docs/manual/_sources/understanding.rst.txt
View File

@ -44,8 +44,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 recommended setup for development and testing is using LoRa radio modules with an open source firmware
(see the section :ref:`Reference System Setup<understanding-referencesystem>`), connected to a small (see the section :ref:`Reference System Setup<understanding-referencesystem>`), connected to a small
computer like a Raspberry Pi. As an example, the default reference setup provides a channel capacity 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 of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (extendable by using multiple hops).
by using multiple hops).
.. _understanding-goals: .. _understanding-goals:
@ -543,57 +542,62 @@ or stream data directly from files.
.. _understanding-referencesystem: .. _understanding-referencesystem:
Reference System Setup Reference Setup
====================== ======================
This section will detail the recommended *Reference System Setup* for Reticulum. It is important to This section will detail a recommended *Reference Setup* 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 note that Reticulum is designed to be usable on more or less any computing device, and over more
and receive data in a digital form, and satisfies some very low minimum requirements. The or less any medium that allows you to send and receive data, which satisfies some very low
communication channel must support at least half-duplex operation, and provide an average minimum requirements.
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 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. runtime environment.
That being said, the reference setup has been outlined to provide a common platform for anyone 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 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: recommended setup to get started experimenting. A reference system consists of three parts:
* **A channel access device** * **An Interface Device**
Or *CAD* , in short, provides access to the physical medium whereupon the communication 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 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”. connected to a radio would also be an interface device.
* **A host device** * **A Host Device**
Some sort of computing device that can run the necessary software, communicates with the Some sort of computing device that can run the necessary software, communicate with the
channel access device, and provides user interaction. interface device, and provide user interaction.
* **A software stack** * **A Software Stack**
The software implementing the Reticulum protocol and applications using it. The software implementing the Reticulum protocol and applications using it.
The reference setup can be considered a relatively stable platform to develop on, and also to start 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 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 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: into the future. The current Reference System Setup is as follows:
* **Channel Access Device** * **Interface Device**
A data radio consisting of a LoRa radio module, and a microcontroller with open source 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 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 `RNode Page <https://unsigned.io/rnode>`_. MHz frequency bands. More details can be found on the `RNode Page <https://unsigned.io/rnode>`_.
* **Host device** * **Host Device**
Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
recommended. recommended.
* **Software stack** * **Software Stack**
The current Reference Implementation Release of Reticulum, running on a Debian based The most recently released Python Implementation of Reticulum, running on a Debian based
operating system. operating system.
It is very important to note, that the reference channel access device **does not** use the LoRaWAN To avoid confusion, it is very important to note, that the reference interface device **does not**
standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will 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 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 `RNode Page <https://unsigned.io/rnode>`_. get or make such a device is available on the `RNode Page <https://unsigned.io/rnode>`_.
With the current reference setup, it should be possible to get on a Reticulum network for around 100$ 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. even if you have none of the hardware already, and need to purchase everything.
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.
.. _understanding-protocolspecifics: .. _understanding-protocolspecifics:
Protocol Specifics Protocol Specifics
@ -675,7 +679,7 @@ Binary Packet Format
+- Packet Example -+ +- 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] 01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
@ -689,7 +693,7 @@ Binary Packet Format
+- Packet Example -+ +- 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] 00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]

34
docs/manual/gettingstartedfast.html
View File

@ -114,28 +114,31 @@ users should carefully choose the interface which best suites their needs.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> allows users to host an instance accessible over TCP/IP. This <p>The <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> allows users to host an instance accessible over TCP/IP. This
method is generally faster, lower latency, and more energy efficient than using <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>, method is generally faster, lower latency, and more energy efficient than using <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>,
however it also leaks considerable metadata about the server host.</p> however it also leaks considerable metadata about the server host.</p>
<p>Direct TCP client connections are able to see your node’s IP address and may be able <p>Direct TCP client connections are able to see the IP address of your instance and may be able
to use this information to determine your location or identity. Adversaries to use this information to determine your location or identity. Adversaries
inspecting your network’s internet packets may be able to record packet metadata inspecting your packets may be able to record packet metadata like time of transmission and packet size.
like time of transmission and packet size. By default TCP does not encrypt traffic, Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
so an adversary may be able to use packet inspection to learn that a system is running packet inspection to learn that a system is running Reticulum, and what other IP adresses connect to it.
Reticulum, and what other IP adresses connect to it. Hosting a node via TCP server also Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
requires a public IP address.</p> which most Internet connections don’t offer anymore.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code> routes messages through the <a class="reference external" href="https://geti2p.net/en/">Invisible Internet Protocol <p>The <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code> routes messages through the <a class="reference external" href="https://geti2p.net/en/">Invisible Internet Protocol
(I2P)</a>. To properly use this interface, users must also run an I2P daemon in (I2P)</a>. To properly use this interface, users must also run an I2P daemon in
parallel to <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>. For always-on nodes it is recommended to use <a class="reference external" href="https://i2pd.website/">i2pd</a> because it parallel to <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>. For always-on I2P nodes it is recommended to use <a class="reference external" href="https://i2pd.website/">i2pd</a> because it
generally runs more efficiently.</p> generally runs more efficiently.</p>
<p>By default, I2P will fully encrypt all traffic sent over the network, and <p>By default, I2P will encrypt all traffic sent over the Internet, and
obfuscate both the sender’s and receiver’s IP addresses. Running an I2P node hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
will also relay other I2P user’s encrypted packets, which will use extra will also relay other I2P user’s encrypted packets, which will use extra
bandwidth and compute power, but also makes timing attacks and other forms of bandwidth and compute power, but also makes timing attacks and other forms of
deep-packet-inspection much more difficult. Similar to RNS, I2P uses cryptographic deep-packet-inspection much more difficult.</p>
public keys as destination addresses, which allows users to host nodes on non-static IPs.</p> <p>I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls.</p>
<p>In general it is recommended to use an I2P node if you want to host a publically accessible <p>In general it is recommended to use an I2P node if you want to host a publically accessible
instance, while preserving anonymity. If you care more about performance, and a slightly instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP.</p> easier setup, use TCP.</p>
<p>There is a experimental public testnet you can join by adding one of the following </div>
interfaces to your <code class="docutils literal notranslate"><span class="pre">.reticulum/config</span></code> file:</p> <div class="section" id="connect-to-the-public-testnet">
<h2>Connect to the Public Testnet<a class="headerlink" href="#connect-to-the-public-testnet" title="Permalink to this headline"></a></h2>
<p>An experimental public testnet has been made accessible over both I2P and TCP. You can join it
by adding one of the following interfaces to your <code class="docutils literal notranslate"><span class="pre">.reticulum/config</span></code> file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># For connecting over TCP/IP:</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># For connecting over TCP/IP:</span>
<span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">Frankfurt</span><span class="p">]]</span> <span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">Frankfurt</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
@ -152,6 +155,10 @@ interfaces to your <code class="docutils literal notranslate"><span class="pre">
<span class="n">peers</span> <span class="o">=</span> <span class="n">ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha</span><span class="o">.</span><span class="n">b32</span><span class="o">.</span><span class="n">i2p</span> <span class="n">peers</span> <span class="o">=</span> <span class="n">ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha</span><span class="o">.</span><span class="n">b32</span><span class="o">.</span><span class="n">i2p</span>
</pre></div> </pre></div>
</div> </div>
<p>Many other Reticulum instances are connecting to this testnet, and you can also join it
via other entry points if you know them. There is absolutely no control over the network
topography, usage or what types of instances connect. It will also occasionally be used
to test various failure scenarios, and there are no availability or service guarantees.</p>
</div> </div>
<div class="section" id="develop-a-program-with-reticulum"> <div class="section" id="develop-a-program-with-reticulum">
<h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this headline"></a></h2> <h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this headline"></a></h2>
@ -296,6 +303,7 @@ for more information:</p>
<li><a class="reference internal" href="#using-the-included-utilities">Using the Included Utilities</a></li> <li><a class="reference internal" href="#using-the-included-utilities">Using the Included Utilities</a></li>
<li><a class="reference internal" href="#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li> <li><a class="reference internal" href="#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li>
<li><a class="reference internal" href="#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li> <li><a class="reference internal" href="#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li>
<li><a class="reference internal" href="#connect-to-the-public-testnet">Connect to the Public Testnet</a></li>
<li><a class="reference internal" href="#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li> <li><a class="reference internal" href="#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
<li><a class="reference internal" href="#participate-in-reticulum-development">Participate in Reticulum Development</a></li> <li><a class="reference internal" href="#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
<li><a class="reference internal" href="#reticulum-on-arm64">Reticulum on ARM64</a></li> <li><a class="reference internal" href="#reticulum-on-arm64">Reticulum on ARM64</a></li>

3
docs/manual/index.html
View File

@ -57,6 +57,7 @@ to participate in the development of Reticulum itself.</p>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#using-the-included-utilities">Using the Included Utilities</a></li> <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#using-the-included-utilities">Using the Included Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li> <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li> <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#connecting-reticulum-instances-over-the-internet">Connecting Reticulum Instances Over the Internet</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#connect-to-the-public-testnet">Connect to the Public Testnet</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li> <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#participate-in-reticulum-development">Participate in Reticulum Development</a></li> <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#reticulum-on-arm64">Reticulum on ARM64</a></li> <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#reticulum-on-arm64">Reticulum on ARM64</a></li>
@ -119,7 +120,7 @@ to participate in the development of Reticulum itself.</p>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#resources">Resources</a></li> <li class="toctree-l3"><a class="reference internal" href="understanding.html#resources">Resources</a></li>
</ul> </ul>
</li> </li>
<li class="toctree-l2"><a class="reference internal" href="understanding.html#reference-system-setup">Reference System Setup</a></li> <li class="toctree-l2"><a class="reference internal" href="understanding.html#reference-setup">Reference Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="understanding.html#protocol-specifics">Protocol Specifics</a><ul> <li class="toctree-l2"><a class="reference internal" href="understanding.html#protocol-specifics">Protocol Specifics</a><ul>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#packet-prioritisation">Packet Prioritisation</a></li> <li class="toctree-l3"><a class="reference internal" href="understanding.html#packet-prioritisation">Packet Prioritisation</a></li>
<li class="toctree-l3"><a class="reference internal" href="understanding.html#binary-packet-format">Binary Packet Format</a></li> <li class="toctree-l3"><a class="reference internal" href="understanding.html#binary-packet-format">Binary Packet Format</a></li>

BIN
docs/manual/objects.inv
View File

Binary file not shown.

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

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 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 (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 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 of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (extendable by using multiple hops).</p>
by using multiple hops).</p>
</div> </div>
<div class="section" id="goals"> <div class="section" id="goals">
<span id="understanding-goals"></span><h2>Goals<a class="headerlink" href="#goals" title="Permalink to this headline"></a></h2> <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> or stream data directly from files.</p>
</div> </div>
</div> </div>
<div class="section" id="reference-system-setup"> <div class="section" id="reference-setup">
<span id="understanding-referencesystem"></span><h2>Reference System Setup<a class="headerlink" href="#reference-system-setup" title="Permalink to this headline"></a></h2> <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 the recommended <em>Reference System Setup</em> for Reticulum. It is important to <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 over more or less any medium that allows you to send note that Reticulum is designed to be usable on more or less any computing device, and over more
and receive data in a digital form, and satisfies some very low minimum requirements. The or less any medium that allows you to send and receive data, which satisfies some very low
communication channel must support at least half-duplex operation, and provide an average minimum requirements.</p>
throughput of around 1000 bits per second, and supports a physical layer MTU of 500 bytes. The <p>The communication channel must support at least half-duplex operation, and provide an average
Reticulum software should be able to run on more or less any hardware that can provide a Python 3.x 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> 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 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"> <ul class="simple">
<li><dl 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 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> </dd>
</dl> </dl>
</li> </li>
<li><dl class="simple"> <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 <dt><strong>A Host Device</strong></dt><dd><p>Some sort of computing device that can run the necessary software, communicate with the
channel access device, and provides user interaction.</p> interface device, and provide user interaction.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
<li><dl class="simple"> <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> </dd>
</dl> </dl>
</li> </li>
</ul> </ul>
<p>The reference setup can be considered a relatively stable platform to develop on, and also to start <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 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 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> into the future. The current Reference System Setup is as follows:</p>
<ul class="simple"> <ul class="simple">
<li><dl 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 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> MHz frequency bands. More details can be found on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
<li><dl class="simple"> <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> recommended.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
<li><dl class="simple"> <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> operating system.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
</ul> </ul>
<p>It is very important to note, that the reference channel access device <strong>does not</strong> use the LoRaWAN <p>To avoid confusion, it is very important to note, that the reference interface device <strong>does not</strong>
standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will 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 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> 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$ <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> 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>
<div class="section" id="protocol-specifics"> <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> <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 -+ +- 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] 01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
@ -750,7 +752,7 @@ proof 11
+- Packet Example -+ +- 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] 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> <li><a class="reference internal" href="#resources">Resources</a></li>
</ul> </ul>
</li> </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="#protocol-specifics">Protocol Specifics</a><ul>
<li><a class="reference internal" href="#packet-prioritisation">Packet Prioritisation</a></li> <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> <li><a class="reference internal" href="#binary-packet-format">Binary Packet Format</a></li>

34
docs/source/gettingstartedfast.rst
View File

@ -97,32 +97,36 @@ The ``TCPServerInterface`` allows users to host an instance accessible over TCP/
method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``, method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``,
however it also leaks considerable metadata about the server host. however it also leaks considerable metadata about the server host.
Direct TCP client connections are able to see your node's IP address and may be able Direct TCP client connections are able to see the IP address of your instance and may be able
to use this information to determine your location or identity. Adversaries to use this information to determine your location or identity. Adversaries
inspecting your network's internet packets may be able to record packet metadata inspecting your packets may be able to record packet metadata like time of transmission and packet size.
like time of transmission and packet size. By default TCP does not encrypt traffic, Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use
so an adversary may be able to use packet inspection to learn that a system is running packet inspection to learn that a system is running Reticulum, and what other IP adresses connect to it.
Reticulum, and what other IP adresses connect to it. Hosting a node via TCP server also Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
requires a public IP address. which most Internet connections don't offer anymore.
The ``I2PInterface`` routes messages through the `Invisible Internet Protocol The ``I2PInterface`` routes messages through the `Invisible Internet Protocol
(I2P) <https://geti2p.net/en/>`_. To properly use this interface, users must also run an I2P daemon in (I2P) <https://geti2p.net/en/>`_. To properly use this interface, users must also run an I2P daemon in
parallel to ``rnsd``. For always-on nodes it is recommended to use `i2pd <https://i2pd.website/>`_ because it parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_ because it
generally runs more efficiently. generally runs more efficiently.
By default, I2P will fully encrypt all traffic sent over the network, and By default, I2P will encrypt all traffic sent over the Internet, and
obfuscate both the sender's and receiver's IP addresses. Running an I2P node hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node
will also relay other I2P user's encrypted packets, which will use extra will also relay other I2P user's encrypted packets, which will use extra
bandwidth and compute power, but also makes timing attacks and other forms of bandwidth and compute power, but also makes timing attacks and other forms of
deep-packet-inspection much more difficult. Similar to RNS, I2P uses cryptographic deep-packet-inspection much more difficult.
public keys as destination addresses, which allows users to host nodes on non-static IPs.
I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls.
In general it is recommended to use an I2P node if you want to host a publically accessible In general it is recommended to use an I2P node if you want to host a publically accessible
instance, while preserving anonymity. If you care more about performance, and a slightly instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP. easier setup, use TCP.
There is a experimental public testnet you can join by adding one of the following Connect to the Public Testnet
interfaces to your ``.reticulum/config`` file: ===========================================
An experimental public testnet has been made accessible over both I2P and TCP. You can join it
by adding one of the following interfaces to your ``.reticulum/config`` file:
.. code:: .. code::
@ -141,6 +145,10 @@ interfaces to your ``.reticulum/config`` file:
interface_enabled = yes interface_enabled = yes
peers = ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha.b32.i2p peers = ykzlw5ujbaqc2xkec4cpvgyxj257wcrmmgkuxqmqcur7cq3w3lha.b32.i2p
Many other Reticulum instances are connecting to this testnet, and you can also join it
via other entry points if you know them. There is absolutely no control over the network
topography, usage or what types of instances connect. It will also occasionally be used
to test various failure scenarios, and there are no availability or service guarantees.
Develop a Program with Reticulum Develop a Program with Reticulum
=========================================== ===========================================

60
docs/source/understanding.rst
View File

@ -44,8 +44,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 recommended setup for development and testing is using LoRa radio modules with an open source firmware
(see the section :ref:`Reference System Setup<understanding-referencesystem>`), connected to a small (see the section :ref:`Reference System Setup<understanding-referencesystem>`), connected to a small
computer like a Raspberry Pi. As an example, the default reference setup provides a channel capacity 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 of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (extendable by using multiple hops).
by using multiple hops).
.. _understanding-goals: .. _understanding-goals:
@ -543,57 +542,62 @@ or stream data directly from files.
.. _understanding-referencesystem: .. _understanding-referencesystem:
Reference System Setup Reference Setup
====================== ======================
This section will detail the recommended *Reference System Setup* for Reticulum. It is important to This section will detail a recommended *Reference Setup* 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 note that Reticulum is designed to be usable on more or less any computing device, and over more
and receive data in a digital form, and satisfies some very low minimum requirements. The or less any medium that allows you to send and receive data, which satisfies some very low
communication channel must support at least half-duplex operation, and provide an average minimum requirements.
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 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. runtime environment.
That being said, the reference setup has been outlined to provide a common platform for anyone 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 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: recommended setup to get started experimenting. A reference system consists of three parts:
* **A channel access device** * **An Interface Device**
Or *CAD* , in short, provides access to the physical medium whereupon the communication 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 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”. connected to a radio would also be an interface device.
* **A host device** * **A Host Device**
Some sort of computing device that can run the necessary software, communicates with the Some sort of computing device that can run the necessary software, communicate with the
channel access device, and provides user interaction. interface device, and provide user interaction.
* **A software stack** * **A Software Stack**
The software implementing the Reticulum protocol and applications using it. The software implementing the Reticulum protocol and applications using it.
The reference setup can be considered a relatively stable platform to develop on, and also to start 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 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 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: into the future. The current Reference System Setup is as follows:
* **Channel Access Device** * **Interface Device**
A data radio consisting of a LoRa radio module, and a microcontroller with open source 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 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 `RNode Page <https://unsigned.io/rnode>`_. MHz frequency bands. More details can be found on the `RNode Page <https://unsigned.io/rnode>`_.
* **Host device** * **Host Device**
Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
recommended. recommended.
* **Software stack** * **Software Stack**
The current Reference Implementation Release of Reticulum, running on a Debian based The most recently released Python Implementation of Reticulum, running on a Debian based
operating system. operating system.
It is very important to note, that the reference channel access device **does not** use the LoRaWAN To avoid confusion, it is very important to note, that the reference interface device **does not**
standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will 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 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 `RNode Page <https://unsigned.io/rnode>`_. get or make such a device is available on the `RNode Page <https://unsigned.io/rnode>`_.
With the current reference setup, it should be possible to get on a Reticulum network for around 100$ 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. even if you have none of the hardware already, and need to purchase everything.
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.
.. _understanding-protocolspecifics: .. _understanding-protocolspecifics:
Protocol Specifics Protocol Specifics
@ -675,7 +679,7 @@ Binary Packet Format
+- Packet Example -+ +- 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] 01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
@ -689,7 +693,7 @@ Binary Packet Format
+- Packet Example -+ +- 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] 00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]