Added interface modes to documentation

docs/manual/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: d4939f555bda9c488f47cdcede85949d
+config: cb185315f69a86407f1dca0f5d7d25ef
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/manual/_sources/interfaces.rst.txt

@@ -84,6 +84,60 @@ These can be used to control various aspects of interface behaviour.
      option, to set the interface speed in *bits per second*.
 
 
+.. _interfaces-modes:
+
+Interface Modes
+===============
+
+The optional ``mode`` option is available on all interfaces, and allows
+selecting the high-level behaviour of the interface from a number of modes.
+These modes affect how Reticulum selects paths in the network, how announces
+are propagated and how long paths are valid.
+
+Configuring modes on interfaces is not strictly necessary, but can be useful
+when building or connecting to more complex networks. When not running a
+Transport Node, it is rarely useful to configure an interface mode.
+
+ * | The default value is ``full``. In this mode, all discovery,
+     meshing and transport functionality is activated.
+
+ * | In the ``access_point`` (or shorthand ``ap``) mode, the
+     interface will operate as a network access point. In this
+     mode, announces will not be automatically broadcasted on
+     the interface, and paths to destinations on the interface
+     will have a much shorter expiry time. This mode is useful
+     for creating interfaces that are mostly quiet, unless when
+     someone is actually using them. An example of this could
+     be a radio interface serving a wide area, where users are
+     expected to connect momentarily, use the network, and then
+     disappear again.
+
+ * | The ``roaming`` mode should be used on interfaces that are
+     roaming (physically mobile), seen from the perspective of
+     other nodes in the network. As an example, if a vehicle is
+     equipped with an external LoRa interface, and an internal,
+     WiFi-based interface, that serves devices that are moving
+     _with_ the vehicle, the external LoRa interface should be
+     configured as ``roaming``, and the internal interface can
+     be left in the default mode. With transport enabled, such
+     a setup will allow all internal devices to reach each other,
+     and all other devices that are available on the LoRa side
+     of the network, when they are in range. Devices on the LoRa
+     side of the network will also be able to reach devices
+     internal to the vehicle, when it is in range. Paths via
+     ``roaming`` interfaces also expire faster.
+
+ * | The purpose of the ``boundary`` mode is to specify interfaces
+     that establish connectivity with network segments that are
+     significantly different than the one this node exists on.
+     As an example, if a Reticulum instance is part of a LoRa-based
+     network, but also has a high-speed connection to a
+     public Transport Node available on the Internet, the interface
+     connecting over the Internet should be set to ``boundary`` mode.
+
+For a table describing the impact of all modes on announce propagation,
+please see the :ref:`Announce Propagation Rules<understanding-announcepropagation>` section.
+
 .. _interfaces-auto:
 
 Auto Interface

docs/manual/_sources/understanding.rst.txt

@@ -802,3 +802,38 @@ Wire Format
     - Link Proof      :    77  bytes
     - Link RTT packet :    83  bytes
     - Link keepalive  :    14  bytes
+
+
+.. _understanding-announcepropagation:
+
+Announce Propagation Rules
+--------------------------
+
+The following table illustrates the rules for automatically propagating announces
+from one interface type to another, for all possible combinations. See the
+:ref:`Interface Modes<interfaces-modes>` section for a conceptual overview of the
+different interface modes, and how they are configured.
+
+.. code-block:: text
+
+    Full ────── ✓ ──┐              ┌── ✓ ── Full
+    AP ──────── ✓ ──┼──── Full ────┼── ✕ ── AP
+    Boundary ── ✓ ──┤              ├── ✓ ── Boundary
+    Roaming ─── ✓ ──┘              └── ✓ ── Roaming
+
+    Full ────── ✕ ──┐              ┌── ✓ ── Full
+    AP ──────── ✕ ──┼───── AP ─────┼── ✕ ── AP
+    Boundary ── ✕ ──┤              ├── ✓ ── Boundary
+    Roaming ─── ✕ ──┘              └── ✓ ── Roaming
+
+    Full ────── ✓ ──┐              ┌── ✓ ── Full
+    AP ──────── ✓ ──┼── Roaming ───┼── ✕ ── AP
+    Boundary ── ✕ ──┤              ├── ✕ ── Boundary
+    Roaming ─── ✕ ──┘              └── ✕ ── Roaming
+
+    Full ────── ✓ ──┐              ┌── ✓ ── Full
+    AP ──────── ✓ ──┼── Boundary ──┼── ✕ ── AP
+    Boundary ── ✓ ──┤              ├── ✓ ── Boundary
+    Roaming ─── ✕ ──┘              └── ✕ ── Roaming
+
+

docs/manual/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.3.5 beta',
+    VERSION: '0.3.6 beta',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/manual/examples.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Code Examples &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>Code Examples &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -27,7 +27,7 @@
         <li class="right" >
           <a href="reference.html" title="API Reference"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Code Examples</a></li> 
       </ul>
     </div>  
@@ -2366,12 +2366,12 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
         <li class="right" >
           <a href="reference.html" title="API Reference"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Code Examples</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/genindex.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Index &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>Index &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -23,7 +23,7 @@
         <li class="right" style="margin-right: 10px">
           <a href="#" title="General Index"
              accesskey="I">index</a></li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Index</a></li> 
       </ul>
     </div>  
@@ -418,12 +418,12 @@
         <li class="right" style="margin-right: 10px">
           <a href="#" title="General Index"
              >index</a></li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Index</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/gettingstartedfast.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Getting Started Fast &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>Getting Started Fast &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -31,7 +31,7 @@
         <li class="right" >
           <a href="whatis.html" title="What is Reticulum?"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Getting Started Fast</a></li> 
       </ul>
     </div>  
@@ -384,12 +384,12 @@ and propose adding an interface for the hardware.</p>
         <li class="right" >
           <a href="whatis.html" title="What is Reticulum?"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Getting Started Fast</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/index.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Reticulum Network Stack Manual &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>Reticulum Network Stack Manual &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -27,7 +27,7 @@
         <li class="right" >
           <a href="whatis.html" title="What is Reticulum?"
              accesskey="N">next</a> |</li>
-        <li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Manual</a></li> 
       </ul>
     </div>  
@@ -96,6 +96,7 @@ to participate in the development of Reticulum itself.</p>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#common-interface-options">Common Interface Options</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#interface-modes">Interface Modes</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#auto-interface">Auto Interface</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#i2p-interface">I2P Interface</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-server-interface">TCP Server Interface</a></li>
@@ -129,6 +130,7 @@ to participate in the development of Reticulum itself.</p>
 <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#interface-access-codes">Interface Access Codes</a></li>
 <li class="toctree-l3"><a class="reference internal" href="understanding.html#wire-format">Wire Format</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#announce-propagation-rules">Announce Propagation Rules</a></li>
 </ul>
 </li>
 </ul>
@@ -218,12 +220,12 @@ to participate in the development of Reticulum itself.</p>
         <li class="right" >
           <a href="whatis.html" title="What is Reticulum?"
              >next</a> |</li>
-        <li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Manual</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/interfaces.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Supported Interfaces &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>Supported Interfaces &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -31,7 +31,7 @@
         <li class="right" >
           <a href="networks.html" title="Building Networks"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Supported Interfaces</a></li> 
       </ul>
     </div>  
@@ -135,6 +135,67 @@ option, to set the interface speed in <em>bits per second</em>.</div>
 </ul>
 </div></blockquote>
 </div>
+<div class="section" id="interface-modes">
+<span id="interfaces-modes"></span><h2>Interface Modes<a class="headerlink" href="#interface-modes" title="Permalink to this headline">¶</a></h2>
+<p>The optional <code class="docutils literal notranslate"><span class="pre">mode</span></code> option is available on all interfaces, and allows
+selecting the high-level behaviour of the interface from a number of modes.
+These modes affect how Reticulum selects paths in the network, how announces
+are propagated and how long paths are valid.</p>
+<p>Configuring modes on interfaces is not strictly necessary, but can be useful
+when building or connecting to more complex networks. When not running a
+Transport Node, it is rarely useful to configure an interface mode.</p>
+<blockquote>
+<div><ul>
+<li><div class="line-block">
+<div class="line">The default value is <code class="docutils literal notranslate"><span class="pre">full</span></code>. In this mode, all discovery,
+meshing and transport functionality is activated.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">In the <code class="docutils literal notranslate"><span class="pre">access_point</span></code> (or shorthand <code class="docutils literal notranslate"><span class="pre">ap</span></code>) mode, the
+interface will operate as a network access point. In this
+mode, announces will not be automatically broadcasted on
+the interface, and paths to destinations on the interface
+will have a much shorter expiry time. This mode is useful
+for creating interfaces that are mostly quiet, unless when
+someone is actually using them. An example of this could
+be a radio interface serving a wide area, where users are
+expected to connect momentarily, use the network, and then
+disappear again.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="pre">roaming</span></code> mode should be used on interfaces that are
+roaming (physically mobile), seen from the perspective of
+other nodes in the network. As an example, if a vehicle is
+equipped with an external LoRa interface, and an internal,
+WiFi-based interface, that serves devices that are moving
+_with_ the vehicle, the external LoRa interface should be
+configured as <code class="docutils literal notranslate"><span class="pre">roaming</span></code>, and the internal interface can
+be left in the default mode. With transport enabled, such
+a setup will allow all internal devices to reach each other,
+and all other devices that are available on the LoRa side
+of the network, when they are in range. Devices on the LoRa
+side of the network will also be able to reach devices
+internal to the vehicle, when it is in range. Paths via
+<code class="docutils literal notranslate"><span class="pre">roaming</span></code> interfaces also expire faster.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The purpose of the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode is to specify interfaces
+that establish connectivity with network segments that are
+significantly different than the one this node exists on.
+As an example, if a Reticulum instance is part of a LoRa-based
+network, but also has a high-speed connection to a
+public Transport Node available on the Internet, the interface
+connecting over the Internet should be set to <code class="docutils literal notranslate"><span class="pre">boundary</span></code> mode.</div>
+</div>
+</li>
+</ul>
+</div></blockquote>
+<p>For a table describing the impact of all modes on announce propagation,
+please see the <a class="reference internal" href="understanding.html#understanding-announcepropagation"><span class="std std-ref">Announce Propagation Rules</span></a> section.</p>
+</div>
 <div class="section" id="auto-interface">
 <span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this headline">¶</a></h2>
 <p>The Auto Interface enables communication with other discoverable Reticulum
@@ -580,6 +641,7 @@ beaconing functionality described above.</p>
   <ul>
 <li><a class="reference internal" href="#">Supported Interfaces</a><ul>
 <li><a class="reference internal" href="#common-interface-options">Common Interface Options</a></li>
+<li><a class="reference internal" href="#interface-modes">Interface Modes</a></li>
 <li><a class="reference internal" href="#auto-interface">Auto Interface</a></li>
 <li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li>
 <li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li>
@@ -632,12 +694,12 @@ beaconing functionality described above.</p>
         <li class="right" >
           <a href="networks.html" title="Building Networks"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Supported Interfaces</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/networks.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Building Networks &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>Building Networks &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -31,7 +31,7 @@
         <li class="right" >
           <a href="using.html" title="Using Reticulum on Your System"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Building Networks</a></li> 
       </ul>
     </div>  
@@ -272,12 +272,12 @@ connected outliers are now an integral part of the network.</p>
         <li class="right" >
           <a href="using.html" title="Using Reticulum on Your System"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Building Networks</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/reference.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>API Reference &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>API Reference &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -31,7 +31,7 @@
         <li class="right" >
           <a href="understanding.html" title="Understanding Reticulum"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">API Reference</a></li> 
       </ul>
     </div>  
@@ -1258,12 +1258,12 @@ will announce it.</p>
         <li class="right" >
           <a href="understanding.html" title="Understanding Reticulum"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">API Reference</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/search.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Search &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>Search &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -29,7 +29,7 @@
         <li class="right" style="margin-right: 10px">
           <a href="genindex.html" title="General Index"
              accesskey="I">index</a></li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Search</a></li> 
       </ul>
     </div>  
@@ -85,12 +85,12 @@
         <li class="right" style="margin-right: 10px">
           <a href="genindex.html" title="General Index"
              >index</a></li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Search</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/understanding.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Understanding Reticulum &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>Understanding Reticulum &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -31,7 +31,7 @@
         <li class="right" >
           <a href="interfaces.html" title="Supported Interfaces"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Understanding Reticulum</a></li> 
       </ul>
     </div>  
@@ -858,6 +858,34 @@ but excluding any interface access codes.
 </pre></div>
 </div>
 </div>
+<div class="section" id="announce-propagation-rules">
+<span id="understanding-announcepropagation"></span><h3>Announce Propagation Rules<a class="headerlink" href="#announce-propagation-rules" title="Permalink to this headline">¶</a></h3>
+<p>The following table illustrates the rules for automatically propagating announces
+from one interface type to another, for all possible combinations. See the
+<a class="reference internal" href="interfaces.html#interfaces-modes"><span class="std std-ref">Interface Modes</span></a> section for a conceptual overview of the
+different interface modes, and how they are configured.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Full ────── ✓ ──┐              ┌── ✓ ── Full
+AP ──────── ✓ ──┼──── Full ────┼── ✕ ── AP
+Boundary ── ✓ ──┤              ├── ✓ ── Boundary
+Roaming ─── ✓ ──┘              └── ✓ ── Roaming
+
+Full ────── ✕ ──┐              ┌── ✓ ── Full
+AP ──────── ✕ ──┼───── AP ─────┼── ✕ ── AP
+Boundary ── ✕ ──┤              ├── ✓ ── Boundary
+Roaming ─── ✕ ──┘              └── ✓ ── Roaming
+
+Full ────── ✓ ──┐              ┌── ✓ ── Full
+AP ──────── ✓ ──┼── Roaming ───┼── ✕ ── AP
+Boundary ── ✕ ──┤              ├── ✕ ── Boundary
+Roaming ─── ✕ ──┘              └── ✕ ── Roaming
+
+Full ────── ✓ ──┐              ┌── ✓ ── Full
+AP ──────── ✓ ──┼── Boundary ──┼── ✕ ── AP
+Boundary ── ✓ ──┤              ├── ✓ ── Boundary
+Roaming ─── ✕ ──┘              └── ✕ ── Roaming
+</pre></div>
+</div>
+</div>
 </div>
 </div>
 
@@ -898,6 +926,7 @@ but excluding any interface access codes.
 <li><a class="reference internal" href="#packet-prioritisation">Packet Prioritisation</a></li>
 <li><a class="reference internal" href="#interface-access-codes">Interface Access Codes</a></li>
 <li><a class="reference internal" href="#wire-format">Wire Format</a></li>
+<li><a class="reference internal" href="#announce-propagation-rules">Announce Propagation Rules</a></li>
 </ul>
 </li>
 </ul>
@@ -943,12 +972,12 @@ but excluding any interface access codes.
         <li class="right" >
           <a href="interfaces.html" title="Supported Interfaces"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Understanding Reticulum</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/using.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Using Reticulum on Your System &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>Using Reticulum on Your System &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -31,7 +31,7 @@
         <li class="right" >
           <a href="gettingstartedfast.html" title="Getting Started Fast"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Using Reticulum on Your System</a></li> 
       </ul>
     </div>  
@@ -352,12 +352,12 @@ WantedBy=multi-user.target
         <li class="right" >
           <a href="gettingstartedfast.html" title="Getting Started Fast"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Using Reticulum on Your System</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/manual/whatis.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>What is Reticulum? &#8212; Reticulum Network Stack 0.3.5 beta documentation</title>
+    <title>What is Reticulum? &#8212; Reticulum Network Stack 0.3.6 beta documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/classic.css" />
     
@@ -31,7 +31,7 @@
         <li class="right" >
           <a href="index.html" title="Reticulum Network Stack Manual"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">What is Reticulum?</a></li> 
       </ul>
     </div>  
@@ -204,12 +204,12 @@ network, and vice versa.</p>
         <li class="right" >
           <a href="index.html" title="Reticulum Network Stack Manual"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.5 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.6 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">What is Reticulum?</a></li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">
-        &#169; Copyright 2021, Mark Qvist.
+        &#169; Copyright 2022, Mark Qvist.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
     </div>
   </body>

docs/source/conf.py

@@ -18,11 +18,11 @@ sys.path.insert(0, os.path.abspath('../..'))
 # -- Project information -----------------------------------------------------
 
 project = 'Reticulum Network Stack'
-copyright = '2021, Mark Qvist'
+copyright = '2022, Mark Qvist'
 author = 'Mark Qvist'
 
 # The full version, including alpha/beta/rc tags
-release = '0.3.5 beta'
+release = '0.3.6 beta'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/interfaces.rst

@@ -84,6 +84,60 @@ These can be used to control various aspects of interface behaviour.
      option, to set the interface speed in *bits per second*.
 
 
+.. _interfaces-modes:
+
+Interface Modes
+===============
+
+The optional ``mode`` option is available on all interfaces, and allows
+selecting the high-level behaviour of the interface from a number of modes.
+These modes affect how Reticulum selects paths in the network, how announces
+are propagated and how long paths are valid.
+
+Configuring modes on interfaces is not strictly necessary, but can be useful
+when building or connecting to more complex networks. When not running a
+Transport Node, it is rarely useful to configure an interface mode.
+
+ * | The default value is ``full``. In this mode, all discovery,
+     meshing and transport functionality is activated.
+
+ * | In the ``access_point`` (or shorthand ``ap``) mode, the
+     interface will operate as a network access point. In this
+     mode, announces will not be automatically broadcasted on
+     the interface, and paths to destinations on the interface
+     will have a much shorter expiry time. This mode is useful
+     for creating interfaces that are mostly quiet, unless when
+     someone is actually using them. An example of this could
+     be a radio interface serving a wide area, where users are
+     expected to connect momentarily, use the network, and then
+     disappear again.
+
+ * | The ``roaming`` mode should be used on interfaces that are
+     roaming (physically mobile), seen from the perspective of
+     other nodes in the network. As an example, if a vehicle is
+     equipped with an external LoRa interface, and an internal,
+     WiFi-based interface, that serves devices that are moving
+     _with_ the vehicle, the external LoRa interface should be
+     configured as ``roaming``, and the internal interface can
+     be left in the default mode. With transport enabled, such
+     a setup will allow all internal devices to reach each other,
+     and all other devices that are available on the LoRa side
+     of the network, when they are in range. Devices on the LoRa
+     side of the network will also be able to reach devices
+     internal to the vehicle, when it is in range. Paths via
+     ``roaming`` interfaces also expire faster.
+
+ * | The purpose of the ``boundary`` mode is to specify interfaces
+     that establish connectivity with network segments that are
+     significantly different than the one this node exists on.
+     As an example, if a Reticulum instance is part of a LoRa-based
+     network, but also has a high-speed connection to a
+     public Transport Node available on the Internet, the interface
+     connecting over the Internet should be set to ``boundary`` mode.
+
+For a table describing the impact of all modes on announce propagation,
+please see the :ref:`Announce Propagation Rules<understanding-announcepropagation>` section.
+
 .. _interfaces-auto:
 
 Auto Interface

docs/source/understanding.rst

@@ -802,3 +802,38 @@ Wire Format
     - Link Proof      :    77  bytes
     - Link RTT packet :    83  bytes
     - Link keepalive  :    14  bytes
+
+
+.. _understanding-announcepropagation:
+
+Announce Propagation Rules
+--------------------------
+
+The following table illustrates the rules for automatically propagating announces
+from one interface type to another, for all possible combinations. See the
+:ref:`Interface Modes<interfaces-modes>` section for a conceptual overview of the
+different interface modes, and how they are configured.
+
+.. code-block:: text
+
+    Full ────── ✓ ──┐              ┌── ✓ ── Full
+    AP ──────── ✓ ──┼──── Full ────┼── ✕ ── AP
+    Boundary ── ✓ ──┤              ├── ✓ ── Boundary
+    Roaming ─── ✓ ──┘              └── ✓ ── Roaming
+
+    Full ────── ✕ ──┐              ┌── ✓ ── Full
+    AP ──────── ✕ ──┼───── AP ─────┼── ✕ ── AP
+    Boundary ── ✕ ──┤              ├── ✓ ── Boundary
+    Roaming ─── ✕ ──┘              └── ✓ ── Roaming
+
+    Full ────── ✓ ──┐              ┌── ✓ ── Full
+    AP ──────── ✓ ──┼── Roaming ───┼── ✕ ── AP
+    Boundary ── ✕ ──┤              ├── ✕ ── Boundary
+    Roaming ─── ✕ ──┘              └── ✕ ── Roaming
+
+    Full ────── ✓ ──┐              ┌── ✓ ── Full
+    AP ──────── ✓ ──┼── Boundary ──┼── ✕ ── AP
+    Boundary ── ✓ ──┤              ├── ✓ ── Boundary
+    Roaming ─── ✕ ──┘              └── ✕ ── Roaming
+
+