Updated documentation

docs/manual/_sources/gettingstartedfast.rst.txt

@@ -103,16 +103,16 @@ With Reticulum, you only need to configure what interfaces you want to communica
 over. There is no need to configure address spaces, subnets, routing tables,
 or other things you might be used to from other network types.
 
-Once Reticulums knows which interfaces it should use, it will automatically
+Once Reticulum knows which interfaces it should use, it will automatically
 discover topography and configure transport of data to any destinations it
 knows about.
 
 In situations where you already have an established WiFi or ethernet network, and
-many devices that want to utilise the same external Reticulum network (for example over
+many devices that want to utilise the same external Reticulum network paths (for example over
 LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
-adding any external interfaces to this systems configuration, and enabling transport. Any
+adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
 other device on your local WiFi will then be able to connect to this wider Reticulum
-network just using the default interface configuration.
+network just using the default (:ref:`AutoInterface<interfaces-auto>`) configuration.
 
 Possibly, the examples in the config file are enough to get you started. If
 you want more information, you can read the :ref:`Building Networks<networks-main>`
@@ -137,7 +137,7 @@ Hosting a publicly reachable instance over TCP also requires a publicly reachabl
 which most Internet connections don't offer anymore.
 
 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 use this interface, users must also run an I2P daemon in
 parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_. 
 
 By default, I2P will encrypt and mix all traffic sent over the Internet, and 
@@ -146,12 +146,13 @@ 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 
 deep-packet-inspection much more difficult.
 
-I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls.
+I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls and NAT.
 
 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
 easier setup, use TCP.
 
+
 Connect to the Public Testnet
 ===========================================
 
@@ -180,6 +181,36 @@ via other entry points if you know them. There is absolutely no control over the
 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.
 
+
+Adding Radio Interfaces
+==============================================
+Once you have Reticulum installed and working, you can add radio interfaces with
+any compatible hardware you have available. Reticulum supports a wide range of radio
+hardware, and if you already have any available, it is very likely that it will
+work with Reticulum. For information on how to configure this, see the
+:ref:`Interfaces<interfaces-main>` section of this manual.
+
+If you do not already have transceiver hardware available, you can easily and
+cheaply build an :ref:`RNode<rnode-main>`, which is a general-purpose long-range
+digital radio transceiver, that integrates easily with Reticulum.
+
+To build one yourself requires installing a custom firmware on a supported LoRa
+development board with an auto-install script. Please see the :ref:`Communications Hardware<hardware-main>`
+chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the
+:ref:`list of suppliers<rnode-suppliers>`. For more information on RNode, you can also
+refer to these additional external resources:
+
+* `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
+* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
+* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
+* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
+
+If you have communications hardware that is not already supported by any of the
+:ref:`existing interface types<interfaces-main>`, but you think would be suitable for use with Reticulum,
+you are welcome to head over to the `GitHub discussion pages <https://github.com/markqvist/Reticulum/discussions>`_
+and propose adding an interface for the hardware.
+
+
 Develop a Program with Reticulum
 ===========================================
 If you want to develop programs that use Reticulum, the easiest way to get
@@ -310,21 +341,26 @@ It is also possible to include Reticulum in apps compiled and distributed as
 Android APKs. A detailed tutorial and example source code will be included
 here at a later point.
 
-Adding Radio Interfaces
+Pure-Python Reticulum
 ==============================================
-Once you have Reticulum installed and working, you can add radio interfaces with
+In some rare cases, and on more obscure system types, it is not possible to
-any compatible hardware you have available. For information on how to configure
+install one or more dependencies
-this, see the :ref:`Interfaces<interfaces-main>` section of this manual.
 
-A range of common LoRa development boards and transceiver modules can be used
+On more unusual systems, and in some rare cases, it might not be possible to
-as interfaces with Reticulum. You can refer to the following external resources
+install or even compile one or more of the above modules. In such situations,
-for more information:
+you can use the ``rnspure`` package instead of the ``rns`` package. The ``rnspure``
+package requires no external dependencies for installation. Please note that the
+actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*.
+The only difference is that the ``rnspure`` package lists no dependencies required
+for installation.
 
-* `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
+No matter how Reticulum is installed and started, it will load external dependencies
-* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
+only if they are *needed* and *available*. If for example you want to use Reticulum
-* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
+on a system that cannot support ``pyserial``, it is perfectly possible to do so using
-* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
+the `rnspure` package, but Reticulum will not be able to use serial-based interfaces.
+All other available modules will still be loaded when needed.
 
-If you have communications hardware that you think would be suitable for use with Reticulum,
+**Please Note!** If you use the `rnspure` package to run Reticulum on systems that
-you are welcome to head over to the `GitHub discussion pages <https://github.com/markqvist/Reticulum/discussions>`_
+do not support `PyCA/cryptography <https://github.com/pyca/cryptography>`_, it is
-and propose adding an interface for the hardware.
+important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>`
+section of this manual.

docs/manual/_sources/hardware.rst.txt

@@ -0,0 +1,220 @@
+.. _hardware-main:
+
+***********************
+Communications Hardware
+***********************
+
+One of the truly valuable aspects of Reticulum is the ability to use it over
+almost any conceivable kind of communications medium. The :ref:`interface types<interfaces-main>`
+available for configuration in Reticulum are flexible enough to cover the use
+of most wired and wireless communications hardware available, from decades-old
+packet radio modems to modern millimeter-wave backhaul systems.
+
+If you already have or operate some kind of communications hardware, there is a
+very good chance that it will work with Reticulum out of the box. In case it does
+not, it is possible to provide the necessary glue with very little effort using
+for example the :ref:`PipeInterface<interfaces-pipe>` or the :ref:`TCPClientInterface<interfaces-tcpc>`
+in combination with code like `TCP KISS Server <https://github.com/simplyequipped/tcpkissserver>`_
+by `simplyequipped <https://github.com/simplyequipped>`_.
+
+While this broad support and flexibility is very useful, an abundance of options
+can sometimes make it difficult to know where to begin, especially when you are
+starting from scratch.
+
+This chapter will outline a few different sensible easy starting paths to get
+real-world functional wireless communications up and running with minimal cost
+and effort. Two fundamental devices types will be covered, *RNodes* and *WiFi-based radios*.
+
+.. _rnode-main:
+
+RNode
+=====
+
+Reliable and general-purpose long-range digital radio transceiver systems are
+commonly either very expensive, difficult to set up and operate, hard to source,
+power-hungry, or all of the above at the same time. In an attempt to alleviate
+this situation, the transceiver system *RNode* was designed. It is important to
+note that RNode is not one specific device, from one particular vendor, but
+*an open plaform* that anyone can use to build digital transceivers suited to
+their needs and particular situations.
+
+An RNode is a general purpose, interoperable, low-power and long-range, reliable,
+open and flexible radio communications device. Depending on its components, it can
+operate on many different frequency bands, and use many different modulation
+schemes, but most commonly, and for the purposes of this chapter, we will limit
+the discussion to RNodes using *LoRa* modulation in common ISM bands.
+
+**Avoid Confusion!** An RNode can use LoRa as a *physical-layer modulation*, but it
+does not use, and has nothing to do with the *LoRaWAN* protocol and standard, commonly
+used for IoT devices. RNodes use *raw LoRa modulation*, without any additional
+protocol overhead. All high-level protocol funcionality is handled directly by
+Reticulum.
+
+.. _rnode-creating:
+
+Creating RNodes
+^^^^^^^^^^^^^^^
+RNode has been designed as a system that is easy to replicate across time and
+space. You can put together a functioning transceiver using commonly available
+components, and a few software tools. While you can design and build RNodes
+completely from scratch, to your exact desired specifications, this chapter
+will explain the easiest possible approach to creating RNodes, which is using common
+LoRa development boards. This approach can be boiled down to two simple steps:
+
+1. Obtain one or more supported development boards
+2. Install the RNode firmware with the automated installer
+
+Once the firmware has been installed and provisioned by the install script, it
+is ready to use with any software that supports RNodes, including Reticulum.
+The device can be used with Reticulum by adding an :ref:`RNodeInterface<interfaces-rnode>`
+to the configuration.
+
+.. _rnode-supported:
+
+Supported Boards
+^^^^^^^^^^^^^^^^
+To create one or more RNodes, you will need to obtain supported development
+boards. The following boards are supported by the auto-installer.
+
+LilyGO LoRa32 v2.1
+""""""""""""""""""
+.. image:: graphics/board_t3v21.png
+    :width: 50%
+    :align: center
+
+- **Supported Firmware Lines** v1.x & v2.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** ESP32
+- **Manufacturer** `LilyGO <https://lilygo.cn>`_
+
+
+LilyGO LoRa32 v2.0
+""""""""""""""""""
+.. image:: graphics/board_t3v20.png
+    :width: 50%
+    :align: center
+
+- **Supported Firmware Lines** v1.x & v2.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** ESP32
+- **Manufacturer** `LilyGO <https://lilygo.cn>`_
+
+
+LilyGO T-Beam
+"""""""""""""
+.. image:: graphics/board_tbeam.png
+    :width: 65%
+    :align: center
+
+- **Supported Firmware Lines** v1.x & v2.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** ESP32
+- **Manufacturer** `LilyGO <https://lilygo.cn>`_
+
+
+Heltec LoRa32 v2.0
+""""""""""""""""""
+.. image:: graphics/board_heltec32.png
+    :width: 50%
+    :align: center
+
+- **Supported Firmware Lines** v1.x & v2.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** ESP32
+- **Manufacturer** `Heltec Automation <https://heltec.org>`_
+
+
+Original RNode v1.x
+"""""""""""""""""""
+.. image:: graphics/board_rnode.png
+    :width: 50%
+    :align: center
+
+- **Supported Firmware Lines** v1.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** AVR ATmega1284p
+- **Manufacturer** `unsigned.io <https://unsigned.io>`_
+
+
+.. _rnode-installation:
+
+Installation
+^^^^^^^^^^^^
+
+Once you have obtained compatible boards, you can install the `RNode Firmware <https://github.com/markqvist/RNode_Firmware>`_
+using the `RNode Configuration Utility <https://github.com/markqvist/rnodeconfigutil>`_.
+Make sure that ``Python3`` and ``pip`` is installed on your system, and then install
+the config utility with ``pip``:
+
+.. code::
+
+   pip3 install rnodeconf
+
+Once installation has completed, it is time to start installing the firmware on your
+devices. Run ``rnodeconf`` in auto-install mode like so:
+
+.. code::
+
+   rnodeconf --autoinstall
+
+The utility will guide you through the installation process by asking a series of
+questions about your hardware. Simply follow the guide, and the utility will
+auto-install and configure your devices
+
+**Important Note!** It is currently recommended to use the v1.x line of the RNode firmware,
+even though the v2.x line is available for early testing. The v2.x line should still be
+considered an experimental pre-release. Only use the v2.x firmware line if you want to test
+out the absolutely newest version, and don't care about stability.
+
+.. _rnode-usage:
+
+Usage with Reticulum
+^^^^^^^^^^^^^^^^^^^^
+When the devices have been installed and provisioned, you can use them with Reticulum
+by adding the :ref:`relevant interface section<interfaces-rnode>` to the configuration
+file of Reticulum. For v1.x firmwares, you will have to specify all interface parameters,
+such as serial port and on-air parameters. For v2.x firmwares, you just need to specify
+the Connection ID of the RNode, and Reticulum will automatically locate and connect to the
+RNode, using the parameters stored in the RNode itself.
+
+.. _rnode-suppliers:
+
+Suppliers
+^^^^^^^^^
+Get in touch if you want to have your RNode supplier listed here, or if you want help to
+get started with producing RNodes.
+
+
+WiFi-based Hardware
+===================
+
+It is possible to use all kinds of both short- and long-range Wifi-based hardware
+with Reticulum. Any kind of hardware that fully supports bridged ethernet over the
+WiFi interface will work with the :ref:`AutoInterface<interfaces-auto>` in Reticulum.
+Most devices will behave like this by default, or allow it via configuration options.
+
+This means that you can simply configure the physical links of the WiFi based devices,
+and start communicating over them using Reticulum. It is not necessary to enable any IP
+infrastructure such as DHCP servers, DNS or similar, as long as at least Ethernet is
+available, and packets are passed transparently over the physical WiFi-based devices.
+
+Below is a list of example WiFi (and similar) radios that work well for high capacity
+Reticulum links over long distances:
+
+- `Ubiquiti airMAX radios <https://store.ui.com/collections/operator-airmax-devices>`_
+- `Ubiquiti LTU radios <https://store.ui.com/collections/operator-ltu>`_
+- `MikroTik radios <https://mikrotik.com/products/group/wireless-systems>`_
+
+This list is by no means exhaustive, and only serves as a few examples of radio hardware
+that is relatively cheap while providing long range and high capacity for Reticulum
+networks. As in all other cases, it is also possible for Reticulum to co-exist with IP
+networks running concurrently on such devices.
+
+Combining Hardware Types
+========================
+
+It is a useful tool to combine different link and hardware types when designing and
+building a network. One useful design pattern is to employ high-capacity point-to-point
+links based on WiFi or millimeter-wave radios (with high-gain directional antennas)
+for the network backbone, and using LoRa-based RNodes for covering large areas with
+connectivity for client devices.

docs/manual/_sources/index.rst.txt

@@ -13,9 +13,11 @@ to participate in the development of Reticulum itself.
    using
    networks
    interfaces
+   hardware
    understanding
    reference
    examples
+   support
 
 
 .. only:: html

docs/manual/_sources/interfaces.rst.txt

@@ -274,10 +274,6 @@ with all peers in your local ethernet broadcast domain, the
 :ref:`Auto Interface<interfaces-auto>` performs better, and is even
 easier to use.
 
-The below example is enabled by default on new Reticulum installations,
-as it provides an easy way to get started and to test Reticulum on a
-pre-existing LAN.
-
 .. code::
 
   # This example enables communication with other

docs/manual/_sources/support.rst.txt

@@ -0,0 +1,36 @@
+.. _support-main:
+
+*****************
+Support Reticulum
+*****************
+This reference guide lists and explains all classes exposed by the RNS API.
+
+Donations
+=========
+You can help support the continued development of open, free and private communications systems by donating via one of the following channels:
+
+    Monero:
+
+    84FpY1QbxHcgdseePYNmhTHcrgMX4nFf
+    BYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD1
+    9b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
+
+    Ethereum
+
+    0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a
+
+    Bitcoin
+
+    3CPmacGm34qYvR6XWLVEJmi2aNe3PZqUuq
+
+    Ko-Fi: https://ko-fi.com/markqvist
+
+Are certain features in the development roadmap are important to you or your organisation? Make them a reality quickly by sponsoring their implementation.
+
+Provide Feedback
+================
+All feedback on the usage, functioning and potential dysfunctioning of any and
+all components of the system is very valuable to the continued development and
+improvement of Reticulum. Absolutely no automated analytics, telemetly, error
+reporting or statistics is collected and reported by Reticulum under any
+circumstances, so we rely on old-fashioned human feedback.

docs/manual/_sources/understanding.rst.txt

@@ -839,3 +839,52 @@ of the different interface modes, and how they are configured.
       Boundary ── ✓ ──┤              ├── ✓ ── Boundary
       Roaming ─── ✕ ──┘              └── ✕ ── Roaming
 
+
+.. _understanding-primitives:
+
+Cryptographic Primitives
+------------------------
+
+Reticulum has been designed to use a simple suite of efficient, strong and modern
+cryptographic primitives, with widely available implementations that can be used
+both on general-purpose CPUs and on microcontrollers. The necessary primitives are:
+
+* Ed25519 for signatures
+
+* X22519 for ECDH key exchanges
+
+* HKDF for key derivation
+
+* Fernet for encrypted tokens
+
+  * AES-128 in CBC mode
+
+  * HMAC for message authentication
+
+* SHA-256
+
+* SHA-512
+
+In the default installation configuration, the ``X25519``, ``Ed25519`` and ``AES-128-CBC``
+primitives are provided by `OpenSSL <https://www.openssl.org/>`_ (via the `PyCA/cryptography <https://github.com/pyca/cryptography>`_
+package). The hashing functions ``SHA-256`` and ``SHA-512`` are provided by the standard
+Python `hashlib <https://docs.python.org/3/library/hashlib.html>`_. The ``HKDF``, ``HMAC``,
+``Fernet`` primitives, and the ``PKCS7`` padding function are always provided by the
+following internal implementations:
+
+- ``RNS/Cryptography/HKDF.py``
+- ``RNS/Cryptography/HMAC.py``
+- ``RNS/Cryptography/Fernet.py``
+- ``RNS/Cryptography/PKCS7.py``
+
+
+Reticulum also includes a complete implementation of all necessary primitives in pure Python.
+If OpenSSL & PyCA are not available on the system when Reticulum is started, Reticulum will
+instead use the internal pure-python primitives. A trivial consequence of this is performance,
+with the OpenSSL backend being *much* faster. The most important consequence however, is the
+potential loss of security by using primitives that has not seen the same amount of scrutiny,
+testing and review as those from OpenSSL.
+
+If you want to use the internal pure-python primitives, it is **highly advisable** that you
+have a good understanding of the risks that this pose, and make an informed decision on whether
+those risks are acceptable to you.

docs/manual/gettingstartedfast.html

@@ -119,15 +119,15 @@ internet, to LoRa and Packet Radio interfaces.</p>
 <p>With Reticulum, you only need to configure what interfaces you want to communicate
 over. There is no need to configure address spaces, subnets, routing tables,
 or other things you might be used to from other network types.</p>
-<p>Once Reticulums knows which interfaces it should use, it will automatically
+<p>Once Reticulum knows which interfaces it should use, it will automatically
 discover topography and configure transport of data to any destinations it
 knows about.</p>
 <p>In situations where you already have an established WiFi or ethernet network, and
-many devices that want to utilise the same external Reticulum network (for example over
+many devices that want to utilise the same external Reticulum network paths (for example over
 LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
-adding any external interfaces to this systems configuration, and enabling transport. Any
+adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
 other device on your local WiFi will then be able to connect to this wider Reticulum
-network just using the default interface configuration.</p>
+network just using the default (<a class="reference internal" href="interfaces.html#interfaces-auto"><span class="std std-ref">AutoInterface</span></a>) configuration.</p>
 <p>Possibly, the examples in the config file are enough to get you started. If
 you want more information, you can read the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a>
 and <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapters of this manual.</p>
@@ -148,14 +148,14 @@ packet inspection to learn that a system is running Reticulum, and what other IP
 Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address,
 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
-(I2P)</a>. To properly use this interface, users must also run an I2P daemon in
+(I2P)</a>. To 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 I2P nodes it is recommended to use <a class="reference external" href="https://i2pd.website/">i2pd</a>.</p>
 <p>By default, I2P will encrypt and mix all traffic sent over the Internet, and
 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
 bandwidth and compute power, but also makes timing attacks and other forms of
 deep-packet-inspection much more difficult.</p>
-<p>I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls.</p>
+<p>I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls and NAT.</p>
 <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
 easier setup, use TCP.</p>
@@ -185,6 +185,32 @@ via other entry points if you know them. There is absolutely no control over the
 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 class="section" id="adding-radio-interfaces">
+<h2>Adding Radio Interfaces<a class="headerlink" href="#adding-radio-interfaces" title="Permalink to this headline">¶</a></h2>
+<p>Once you have Reticulum installed and working, you can add radio interfaces with
+any compatible hardware you have available. Reticulum supports a wide range of radio
+hardware, and if you already have any available, it is very likely that it will
+work with Reticulum. For information on how to configure this, see the
+<a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> section of this manual.</p>
+<p>If you do not already have transceiver hardware available, you can easily and
+cheaply build an <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNode</span></a>, which is a general-purpose long-range
+digital radio transceiver, that integrates easily with Reticulum.</p>
+<p>To build one yourself requires installing a custom firmware on a supported LoRa
+development board with an auto-install script. Please see the <a class="reference internal" href="hardware.html#hardware-main"><span class="std std-ref">Communications Hardware</span></a>
+chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the
+<a class="reference internal" href="hardware.html#rnode-suppliers"><span class="std std-ref">list of suppliers</span></a>. For more information on RNode, you can also
+refer to these additional external resources:</p>
+<ul class="simple">
+<li><p><a class="reference external" href="https://unsigned.io/how-to-make-your-own-rnodes/">How To Make Your Own RNodes</a></p></li>
+<li><p><a class="reference external" href="https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/">Installing RNode Firmware on Compatible LoRa Devices</a></p></li>
+<li><p><a class="reference external" href="https://unsigned.io/private-messaging-over-lora/">Private, Secure and Uncensorable Messaging Over a LoRa Mesh</a></p></li>
+<li><p><a class="reference external" href="https://github.com/markqvist/RNode_Firmware/">RNode Firmware</a></p></li>
+</ul>
+<p>If you have communications hardware that is not already supported by any of the
+<a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">existing interface types</span></a>, but you think would be suitable for use with Reticulum,
+you are welcome to head over to the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a>
+and propose adding an interface for the hardware.</p>
+</div>
 <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>
 <p>If you want to develop programs that use Reticulum, the easiest way to get
@@ -297,23 +323,26 @@ and a few extra commands are required.</p>
 Android APKs. A detailed tutorial and example source code will be included
 here at a later point.</p>
 </div>
-<div class="section" id="adding-radio-interfaces">
+<div class="section" id="pure-python-reticulum">
-<h2>Adding Radio Interfaces<a class="headerlink" href="#adding-radio-interfaces" title="Permalink to this headline">¶</a></h2>
+<h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Permalink to this headline">¶</a></h2>
-<p>Once you have Reticulum installed and working, you can add radio interfaces with
+<p>In some rare cases, and on more obscure system types, it is not possible to
-any compatible hardware you have available. For information on how to configure
+install one or more dependencies</p>
-this, see the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> section of this manual.</p>
+<p>On more unusual systems, and in some rare cases, it might not be possible to
-<p>A range of common LoRa development boards and transceiver modules can be used
+install or even compile one or more of the above modules. In such situations,
-as interfaces with Reticulum. You can refer to the following external resources
+you can use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package instead of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> package. The <code class="docutils literal notranslate"><span class="pre">rnspure</span></code>
-for more information:</p>
+package requires no external dependencies for installation. Please note that the
-<ul class="simple">
+actual contents of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> and <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> packages are <em>completely identical</em>.
-<li><p><a class="reference external" href="https://unsigned.io/how-to-make-your-own-rnodes/">How To Make Your Own RNodes</a></p></li>
+The only difference is that the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package lists no dependencies required
-<li><p><a class="reference external" href="https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/">Installing RNode Firmware on Compatible LoRa Devices</a></p></li>
+for installation.</p>
-<li><p><a class="reference external" href="https://unsigned.io/private-messaging-over-lora/">Private, Secure and Uncensorable Messaging Over a LoRa Mesh</a></p></li>
+<p>No matter how Reticulum is installed and started, it will load external dependencies
-<li><p><a class="reference external" href="https://github.com/markqvist/RNode_Firmware/">RNode Firmware</a></p></li>
+only if they are <em>needed</em> and <em>available</em>. If for example you want to use Reticulum
-</ul>
+on a system that cannot support <code class="docutils literal notranslate"><span class="pre">pyserial</span></code>, it is perfectly possible to do so using
-<p>If you have communications hardware that you think would be suitable for use with Reticulum,
+the <cite>rnspure</cite> package, but Reticulum will not be able to use serial-based interfaces.
-you are welcome to head over to the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a>
+All other available modules will still be loaded when needed.</p>
-and propose adding an interface for the hardware.</p>
+<p><strong>Please Note!</strong> If you use the <cite>rnspure</cite> package to run Reticulum on systems that
+do not support <a class="reference external" href="https://github.com/pyca/cryptography">PyCA/cryptography</a>, it is
+important that you read and understand the <a class="reference internal" href="understanding.html#understanding-primitives"><span class="std std-ref">Cryptographic Primitives</span></a>
+section of this manual.</p>
 </div>
 </div>
 
@@ -336,11 +365,12 @@ and propose adding an interface for the hardware.</p>
 <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="#connect-to-the-public-testnet">Connect to the Public Testnet</a></li>
+<li><a class="reference internal" href="#adding-radio-interfaces">Adding Radio Interfaces</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="#reticulum-on-arm64">Reticulum on ARM64</a></li>
 <li><a class="reference internal" href="#reticulum-on-android">Reticulum on Android</a></li>
-<li><a class="reference internal" href="#adding-radio-interfaces">Adding Radio Interfaces</a></li>
+<li><a class="reference internal" href="#pure-python-reticulum">Pure-Python Reticulum</a></li>
 </ul>
 </li>
 </ul>

docs/manual/hardware.html

@@ -0,0 +1,302 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Communications Hardware &#8212; Reticulum Network Stack 0.3.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
+    <script src="_static/jquery.js"></script>
+    <script src="_static/underscore.js"></script>
+    <script src="_static/doctools.js"></script>
+    
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="Understanding Reticulum" href="understanding.html" />
+    <link rel="prev" title="Supported Interfaces" href="interfaces.html" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="understanding.html" title="Understanding Reticulum"
+             accesskey="N">next</a> |</li>
+        <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.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Communications Hardware</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="section" id="communications-hardware">
+<span id="hardware-main"></span><h1>Communications Hardware<a class="headerlink" href="#communications-hardware" title="Permalink to this headline">¶</a></h1>
+<p>One of the truly valuable aspects of Reticulum is the ability to use it over
+almost any conceivable kind of communications medium. The <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">interface types</span></a>
+available for configuration in Reticulum are flexible enough to cover the use
+of most wired and wireless communications hardware available, from decades-old
+packet radio modems to modern millimeter-wave backhaul systems.</p>
+<p>If you already have or operate some kind of communications hardware, there is a
+very good chance that it will work with Reticulum out of the box. In case it does
+not, it is possible to provide the necessary glue with very little effort using
+for example the <a class="reference internal" href="interfaces.html#interfaces-pipe"><span class="std std-ref">PipeInterface</span></a> or the <a class="reference internal" href="interfaces.html#interfaces-tcpc"><span class="std std-ref">TCPClientInterface</span></a>
+in combination with code like <a class="reference external" href="https://github.com/simplyequipped/tcpkissserver">TCP KISS Server</a>
+by <a class="reference external" href="https://github.com/simplyequipped">simplyequipped</a>.</p>
+<p>While this broad support and flexibility is very useful, an abundance of options
+can sometimes make it difficult to know where to begin, especially when you are
+starting from scratch.</p>
+<p>This chapter will outline a few different sensible easy starting paths to get
+real-world functional wireless communications up and running with minimal cost
+and effort. Two fundamental devices types will be covered, <em>RNodes</em> and <em>WiFi-based radios</em>.</p>
+<div class="section" id="rnode">
+<span id="rnode-main"></span><h2>RNode<a class="headerlink" href="#rnode" title="Permalink to this headline">¶</a></h2>
+<p>Reliable and general-purpose long-range digital radio transceiver systems are
+commonly either very expensive, difficult to set up and operate, hard to source,
+power-hungry, or all of the above at the same time. In an attempt to alleviate
+this situation, the transceiver system <em>RNode</em> was designed. It is important to
+note that RNode is not one specific device, from one particular vendor, but
+<em>an open plaform</em> that anyone can use to build digital transceivers suited to
+their needs and particular situations.</p>
+<p>An RNode is a general purpose, interoperable, low-power and long-range, reliable,
+open and flexible radio communications device. Depending on its components, it can
+operate on many different frequency bands, and use many different modulation
+schemes, but most commonly, and for the purposes of this chapter, we will limit
+the discussion to RNodes using <em>LoRa</em> modulation in common ISM bands.</p>
+<p><strong>Avoid Confusion!</strong> An RNode can use LoRa as a <em>physical-layer modulation</em>, but it
+does not use, and has nothing to do with the <em>LoRaWAN</em> protocol and standard, commonly
+used for IoT devices. RNodes use <em>raw LoRa modulation</em>, without any additional
+protocol overhead. All high-level protocol funcionality is handled directly by
+Reticulum.</p>
+<div class="section" id="creating-rnodes">
+<span id="rnode-creating"></span><h3>Creating RNodes<a class="headerlink" href="#creating-rnodes" title="Permalink to this headline">¶</a></h3>
+<p>RNode has been designed as a system that is easy to replicate across time and
+space. You can put together a functioning transceiver using commonly available
+components, and a few software tools. While you can design and build RNodes
+completely from scratch, to your exact desired specifications, this chapter
+will explain the easiest possible approach to creating RNodes, which is using common
+LoRa development boards. This approach can be boiled down to two simple steps:</p>
+<ol class="arabic simple">
+<li><p>Obtain one or more supported development boards</p></li>
+<li><p>Install the RNode firmware with the automated installer</p></li>
+</ol>
+<p>Once the firmware has been installed and provisioned by the install script, it
+is ready to use with any software that supports RNodes, including Reticulum.
+The device can be used with Reticulum by adding an <a class="reference internal" href="interfaces.html#interfaces-rnode"><span class="std std-ref">RNodeInterface</span></a>
+to the configuration.</p>
+</div>
+<div class="section" id="supported-boards">
+<span id="rnode-supported"></span><h3>Supported Boards<a class="headerlink" href="#supported-boards" title="Permalink to this headline">¶</a></h3>
+<p>To create one or more RNodes, you will need to obtain supported development
+boards. The following boards are supported by the auto-installer.</p>
+<div class="section" id="lilygo-lora32-v2-1">
+<h4>LilyGO LoRa32 v2.1<a class="headerlink" href="#lilygo-lora32-v2-1" title="Permalink to this headline">¶</a></h4>
+<a class="reference internal image-reference" href="_images/board_t3v21.png"><img alt="_images/board_t3v21.png" class="align-center" src="_images/board_t3v21.png" style="width: 50%;" /></a>
+<ul class="simple">
+<li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li>
+<li><p><strong>Transceiver IC</strong> Semtech SX1276</p></li>
+<li><p><strong>Device Platform</strong> ESP32</p></li>
+<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
+</ul>
+</div>
+<div class="section" id="lilygo-lora32-v2-0">
+<h4>LilyGO LoRa32 v2.0<a class="headerlink" href="#lilygo-lora32-v2-0" title="Permalink to this headline">¶</a></h4>
+<a class="reference internal image-reference" href="_images/board_t3v20.png"><img alt="_images/board_t3v20.png" class="align-center" src="_images/board_t3v20.png" style="width: 50%;" /></a>
+<ul class="simple">
+<li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li>
+<li><p><strong>Transceiver IC</strong> Semtech SX1276</p></li>
+<li><p><strong>Device Platform</strong> ESP32</p></li>
+<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
+</ul>
+</div>
+<div class="section" id="lilygo-t-beam">
+<h4>LilyGO T-Beam<a class="headerlink" href="#lilygo-t-beam" title="Permalink to this headline">¶</a></h4>
+<a class="reference internal image-reference" href="_images/board_tbeam.png"><img alt="_images/board_tbeam.png" class="align-center" src="_images/board_tbeam.png" style="width: 65%;" /></a>
+<ul class="simple">
+<li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li>
+<li><p><strong>Transceiver IC</strong> Semtech SX1276</p></li>
+<li><p><strong>Device Platform</strong> ESP32</p></li>
+<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
+</ul>
+</div>
+<div class="section" id="heltec-lora32-v2-0">
+<h4>Heltec LoRa32 v2.0<a class="headerlink" href="#heltec-lora32-v2-0" title="Permalink to this headline">¶</a></h4>
+<a class="reference internal image-reference" href="_images/board_heltec32.png"><img alt="_images/board_heltec32.png" class="align-center" src="_images/board_heltec32.png" style="width: 50%;" /></a>
+<ul class="simple">
+<li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li>
+<li><p><strong>Transceiver IC</strong> Semtech SX1276</p></li>
+<li><p><strong>Device Platform</strong> ESP32</p></li>
+<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://heltec.org">Heltec Automation</a></p></li>
+</ul>
+</div>
+<div class="section" id="original-rnode-v1-x">
+<h4>Original RNode v1.x<a class="headerlink" href="#original-rnode-v1-x" title="Permalink to this headline">¶</a></h4>
+<a class="reference internal image-reference" href="_images/board_rnode.png"><img alt="_images/board_rnode.png" class="align-center" src="_images/board_rnode.png" style="width: 50%;" /></a>
+<ul class="simple">
+<li><p><strong>Supported Firmware Lines</strong> v1.x</p></li>
+<li><p><strong>Transceiver IC</strong> Semtech SX1276</p></li>
+<li><p><strong>Device Platform</strong> AVR ATmega1284p</p></li>
+<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://unsigned.io">unsigned.io</a></p></li>
+</ul>
+</div>
+</div>
+<div class="section" id="installation">
+<span id="rnode-installation"></span><h3>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h3>
+<p>Once you have obtained compatible boards, you can install the <a class="reference external" href="https://github.com/markqvist/RNode_Firmware">RNode Firmware</a>
+using the <a class="reference external" href="https://github.com/markqvist/rnodeconfigutil">RNode Configuration Utility</a>.
+Make sure that <code class="docutils literal notranslate"><span class="pre">Python3</span></code> and <code class="docutils literal notranslate"><span class="pre">pip</span></code> is installed on your system, and then install
+the config utility with <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip3</span> <span class="n">install</span> <span class="n">rnodeconf</span>
+</pre></div>
+</div>
+<p>Once installation has completed, it is time to start installing the firmware on your
+devices. Run <code class="docutils literal notranslate"><span class="pre">rnodeconf</span></code> in auto-install mode like so:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rnodeconf</span> <span class="o">--</span><span class="n">autoinstall</span>
+</pre></div>
+</div>
+<p>The utility will guide you through the installation process by asking a series of
+questions about your hardware. Simply follow the guide, and the utility will
+auto-install and configure your devices</p>
+<p><strong>Important Note!</strong> It is currently recommended to use the v1.x line of the RNode firmware,
+even though the v2.x line is available for early testing. The v2.x line should still be
+considered an experimental pre-release. Only use the v2.x firmware line if you want to test
+out the absolutely newest version, and don’t care about stability.</p>
+</div>
+<div class="section" id="usage-with-reticulum">
+<span id="rnode-usage"></span><h3>Usage with Reticulum<a class="headerlink" href="#usage-with-reticulum" title="Permalink to this headline">¶</a></h3>
+<p>When the devices have been installed and provisioned, you can use them with Reticulum
+by adding the <a class="reference internal" href="interfaces.html#interfaces-rnode"><span class="std std-ref">relevant interface section</span></a> to the configuration
+file of Reticulum. For v1.x firmwares, you will have to specify all interface parameters,
+such as serial port and on-air parameters. For v2.x firmwares, you just need to specify
+the Connection ID of the RNode, and Reticulum will automatically locate and connect to the
+RNode, using the parameters stored in the RNode itself.</p>
+</div>
+<div class="section" id="suppliers">
+<span id="rnode-suppliers"></span><h3>Suppliers<a class="headerlink" href="#suppliers" title="Permalink to this headline">¶</a></h3>
+<p>Get in touch if you want to have your RNode supplier listed here, or if you want help to
+get started with producing RNodes.</p>
+</div>
+</div>
+<div class="section" id="wifi-based-hardware">
+<h2>WiFi-based Hardware<a class="headerlink" href="#wifi-based-hardware" title="Permalink to this headline">¶</a></h2>
+<p>It is possible to use all kinds of both short- and long-range Wifi-based hardware
+with Reticulum. Any kind of hardware that fully supports bridged ethernet over the
+WiFi interface will work with the <a class="reference internal" href="interfaces.html#interfaces-auto"><span class="std std-ref">AutoInterface</span></a> in Reticulum.
+Most devices will behave like this by default, or allow it via configuration options.</p>
+<p>This means that you can simply configure the physical links of the WiFi based devices,
+and start communicating over them using Reticulum. It is not necessary to enable any IP
+infrastructure such as DHCP servers, DNS or similar, as long as at least Ethernet is
+available, and packets are passed transparently over the physical WiFi-based devices.</p>
+<p>Below is a list of example WiFi (and similar) radios that work well for high capacity
+Reticulum links over long distances:</p>
+<ul class="simple">
+<li><p><a class="reference external" href="https://store.ui.com/collections/operator-airmax-devices">Ubiquiti airMAX radios</a></p></li>
+<li><p><a class="reference external" href="https://store.ui.com/collections/operator-ltu">Ubiquiti LTU radios</a></p></li>
+<li><p><a class="reference external" href="https://mikrotik.com/products/group/wireless-systems">MikroTik radios</a></p></li>
+</ul>
+<p>This list is by no means exhaustive, and only serves as a few examples of radio hardware
+that is relatively cheap while providing long range and high capacity for Reticulum
+networks. As in all other cases, it is also possible for Reticulum to co-exist with IP
+networks running concurrently on such devices.</p>
+</div>
+<div class="section" id="combining-hardware-types">
+<h2>Combining Hardware Types<a class="headerlink" href="#combining-hardware-types" title="Permalink to this headline">¶</a></h2>
+<p>It is a useful tool to combine different link and hardware types when designing and
+building a network. One useful design pattern is to employ high-capacity point-to-point
+links based on WiFi or millimeter-wave radios (with high-gain directional antennas)
+for the network backbone, and using LoRa-based RNodes for covering large areas with
+connectivity for client devices.</p>
+</div>
+</div>
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Communications Hardware</a><ul>
+<li><a class="reference internal" href="#rnode">RNode</a><ul>
+<li><a class="reference internal" href="#creating-rnodes">Creating RNodes</a></li>
+<li><a class="reference internal" href="#supported-boards">Supported Boards</a><ul>
+<li><a class="reference internal" href="#lilygo-lora32-v2-1">LilyGO LoRa32 v2.1</a></li>
+<li><a class="reference internal" href="#lilygo-lora32-v2-0">LilyGO LoRa32 v2.0</a></li>
+<li><a class="reference internal" href="#lilygo-t-beam">LilyGO T-Beam</a></li>
+<li><a class="reference internal" href="#heltec-lora32-v2-0">Heltec LoRa32 v2.0</a></li>
+<li><a class="reference internal" href="#original-rnode-v1-x">Original RNode v1.x</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#installation">Installation</a></li>
+<li><a class="reference internal" href="#usage-with-reticulum">Usage with Reticulum</a></li>
+<li><a class="reference internal" href="#suppliers">Suppliers</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#wifi-based-hardware">WiFi-based Hardware</a></li>
+<li><a class="reference internal" href="#combining-hardware-types">Combining Hardware Types</a></li>
+</ul>
+</li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="interfaces.html"
+                        title="previous chapter">Supported Interfaces</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="understanding.html"
+                        title="next chapter">Understanding Reticulum</a></p>
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/hardware.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="understanding.html" title="Understanding Reticulum"
+             >next</a> |</li>
+        <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.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Communications Hardware</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2022, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/index.html

@@ -62,11 +62,12 @@ to participate in the development of Reticulum itself.</p>
 <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#connect-to-the-public-testnet">Connect to the Public Testnet</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#adding-radio-interfaces">Adding Radio Interfaces</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#reticulum-on-arm64">Reticulum on ARM64</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#reticulum-on-android">Reticulum on Android</a></li>
-<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#adding-radio-interfaces">Adding Radio Interfaces</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#pure-python-reticulum">Pure-Python Reticulum</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a><ul>
@@ -113,6 +114,19 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#announce-rate-control">Announce Rate Control</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="hardware.html#rnode">RNode</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="hardware.html#creating-rnodes">Creating RNodes</a></li>
+<li class="toctree-l3"><a class="reference internal" href="hardware.html#supported-boards">Supported Boards</a></li>
+<li class="toctree-l3"><a class="reference internal" href="hardware.html#installation">Installation</a></li>
+<li class="toctree-l3"><a class="reference internal" href="hardware.html#usage-with-reticulum">Usage with Reticulum</a></li>
+<li class="toctree-l3"><a class="reference internal" href="hardware.html#suppliers">Suppliers</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="hardware.html#wifi-based-hardware">WiFi-based Hardware</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hardware.html#combining-hardware-types">Combining Hardware Types</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="understanding.html#motivation">Motivation</a></li>
 <li class="toctree-l2"><a class="reference internal" href="understanding.html#goals">Goals</a></li>
@@ -136,6 +150,7 @@ to participate in the development of Reticulum itself.</p>
 <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>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#cryptographic-primitives">Cryptographic Primitives</a></li>
 </ul>
 </li>
 </ul>
@@ -166,6 +181,11 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#filetransfer">Filetransfer</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="support.html#donations">Donations</a></li>
+<li class="toctree-l2"><a class="reference internal" href="support.html#provide-feedback">Provide Feedback</a></li>
+</ul>
+</li>
 </ul>
 </div>
 <div class="section" id="indices-and-tables">

docs/manual/interfaces.html

@@ -16,7 +16,7 @@
     
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="Understanding Reticulum" href="understanding.html" />
+    <link rel="next" title="Communication Hardware" href="hardware.html" />
     <link rel="prev" title="Building Networks" href="networks.html" /> 
   </head><body>
     <div class="related" role="navigation" aria-label="related navigation">
@@ -26,7 +26,7 @@
           <a href="genindex.html" title="General Index"
              accesskey="I">index</a></li>
         <li class="right" >
-          <a href="understanding.html" title="Understanding Reticulum"
+          <a href="hardware.html" title="Communication Hardware"
              accesskey="N">next</a> |</li>
         <li class="right" >
           <a href="networks.html" title="Building Networks"
@@ -263,9 +263,6 @@ especially on WiFi. If your goal is simply to enable easy communication
 with all peers in your local ethernet broadcast domain, the
 <a class="reference internal" href="#interfaces-auto"><span class="std std-ref">Auto Interface</span></a> performs better, and is even
 easier to use.</p>
-<p>The below example is enabled by default on new Reticulum installations,
-as it provides an easy way to get started and to test Reticulum on a
-pre-existing LAN.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example enables communication with other</span>
 <span class="c1"># local Reticulum peers over UDP.</span>
 
@@ -779,8 +776,8 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
   <p class="topless"><a href="networks.html"
                         title="previous chapter">Building Networks</a></p>
   <h4>Next topic</h4>
-  <p class="topless"><a href="understanding.html"
+  <p class="topless"><a href="hardware.html"
-                        title="next chapter">Understanding Reticulum</a></p>
+                        title="next chapter">Communication Hardware</a></p>
   <div role="note" aria-label="source link">
     <h3>This Page</h3>
     <ul class="this-page-menu">
@@ -809,7 +806,7 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
           <a href="genindex.html" title="General Index"
              >index</a></li>
         <li class="right" >
-          <a href="understanding.html" title="Understanding Reticulum"
+          <a href="hardware.html" title="Communication Hardware"
              >next</a> |</li>
         <li class="right" >
           <a href="networks.html" title="Building Networks"

docs/manual/support.html

@@ -0,0 +1,127 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Support Reticulum &#8212; Reticulum Network Stack 0.3.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
+    <script src="_static/jquery.js"></script>
+    <script src="_static/underscore.js"></script>
+    <script src="_static/doctools.js"></script>
+    
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <link rel="prev" title="Code Examples" href="examples.html" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="examples.html" title="Code Examples"
+             accesskey="P">previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Support Reticulum</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="section" id="support-reticulum">
+<span id="support-main"></span><h1>Support Reticulum<a class="headerlink" href="#support-reticulum" title="Permalink to this headline">¶</a></h1>
+<p>This reference guide lists and explains all classes exposed by the RNS API.</p>
+<div class="section" id="donations">
+<h2>Donations<a class="headerlink" href="#donations" title="Permalink to this headline">¶</a></h2>
+<p>You can help support the continued development of open, free and private communications systems by donating via one of the following channels:</p>
+<blockquote>
+<div><p>Monero:</p>
+<p>84FpY1QbxHcgdseePYNmhTHcrgMX4nFf
+BYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD1
+9b3B8NiLCGVxzKV17UMmmeEsCrPyA5w</p>
+<p>Ethereum</p>
+<p>0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a</p>
+<p>Bitcoin</p>
+<p>3CPmacGm34qYvR6XWLVEJmi2aNe3PZqUuq</p>
+<p>Ko-Fi: <a class="reference external" href="https://ko-fi.com/markqvist">https://ko-fi.com/markqvist</a></p>
+</div></blockquote>
+<p>Are certain features in the development roadmap are important to you or your organisation? Make them a reality quickly by sponsoring their implementation.</p>
+</div>
+<div class="section" id="provide-feedback">
+<h2>Provide Feedback<a class="headerlink" href="#provide-feedback" title="Permalink to this headline">¶</a></h2>
+<p>All feedback on the usage, functioning and potential dysfunctioning of any and
+all components of the system is very valuable to the continued development and
+improvement of Reticulum. Absolutely no automated analytics, telemetly, error
+reporting or statistics is collected and reported by Reticulum under any
+circumstances, so we rely on old-fashioned human feedback.</p>
+</div>
+</div>
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Support Reticulum</a><ul>
+<li><a class="reference internal" href="#donations">Donations</a></li>
+<li><a class="reference internal" href="#provide-feedback">Provide Feedback</a></li>
+</ul>
+</li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="examples.html"
+                        title="previous chapter">Code Examples</a></p>
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/support.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="examples.html" title="Code Examples"
+             >previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Support Reticulum</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2022, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/understanding.html

@@ -17,7 +17,7 @@
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
     <link rel="next" title="API Reference" href="reference.html" />
-    <link rel="prev" title="Supported Interfaces" href="interfaces.html" /> 
+    <link rel="prev" title="Communications Hardware" href="hardware.html" /> 
   </head><body>
     <div class="related" role="navigation" aria-label="related navigation">
       <h3>Navigation</h3>
@@ -29,7 +29,7 @@
           <a href="reference.html" title="API Reference"
              accesskey="N">next</a> |</li>
         <li class="right" >
-          <a href="interfaces.html" title="Supported Interfaces"
+          <a href="hardware.html" title="Communications Hardware"
              accesskey="P">previous</a> |</li>
         <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.8 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Understanding Reticulum</a></li> 
@@ -867,6 +867,46 @@ of announce propagation, the <em>Full</em> and <em>Gateway</em> modes are identi
 <p>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>
+<div class="section" id="cryptographic-primitives">
+<span id="understanding-primitives"></span><h3>Cryptographic Primitives<a class="headerlink" href="#cryptographic-primitives" title="Permalink to this headline">¶</a></h3>
+<p>Reticulum has been designed to use a simple suite of efficient, strong and modern
+cryptographic primitives, with widely available implementations that can be used
+both on general-purpose CPUs and on microcontrollers. The necessary primitives are:</p>
+<ul class="simple">
+<li><p>Ed25519 for signatures</p></li>
+<li><p>X22519 for ECDH key exchanges</p></li>
+<li><p>HKDF for key derivation</p></li>
+<li><p>Fernet for encrypted tokens</p>
+<ul>
+<li><p>AES-128 in CBC mode</p></li>
+<li><p>HMAC for message authentication</p></li>
+</ul>
+</li>
+<li><p>SHA-256</p></li>
+<li><p>SHA-512</p></li>
+</ul>
+<p>In the default installation configuration, the <code class="docutils literal notranslate"><span class="pre">X25519</span></code>, <code class="docutils literal notranslate"><span class="pre">Ed25519</span></code> and <code class="docutils literal notranslate"><span class="pre">AES-128-CBC</span></code>
+primitives are provided by <a class="reference external" href="https://www.openssl.org/">OpenSSL</a> (via the <a class="reference external" href="https://github.com/pyca/cryptography">PyCA/cryptography</a>
+package). The hashing functions <code class="docutils literal notranslate"><span class="pre">SHA-256</span></code> and <code class="docutils literal notranslate"><span class="pre">SHA-512</span></code> are provided by the standard
+Python <a class="reference external" href="https://docs.python.org/3/library/hashlib.html">hashlib</a>. The <code class="docutils literal notranslate"><span class="pre">HKDF</span></code>, <code class="docutils literal notranslate"><span class="pre">HMAC</span></code>,
+<code class="docutils literal notranslate"><span class="pre">Fernet</span></code> primitives, and the <code class="docutils literal notranslate"><span class="pre">PKCS7</span></code> padding function are always provided by the
+following internal implementations:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">RNS/Cryptography/HKDF.py</span></code></p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">RNS/Cryptography/HMAC.py</span></code></p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">RNS/Cryptography/Fernet.py</span></code></p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">RNS/Cryptography/PKCS7.py</span></code></p></li>
+</ul>
+<p>Reticulum also includes a complete implementation of all necessary primitives in pure Python.
+If OpenSSL &amp; PyCA are not available on the system when Reticulum is started, Reticulum will
+instead use the internal pure-python primitives. A trivial consequence of this is performance,
+with the OpenSSL backend being <em>much</em> faster. The most important consequence however, is the
+potential loss of security by using primitives that has not seen the same amount of scrutiny,
+testing and review as those from OpenSSL.</p>
+<p>If you want to use the internal pure-python primitives, it is <strong>highly advisable</strong> that you
+have a good understanding of the risks that this pose, and make an informed decision on whether
+those risks are acceptable to you.</p>
+</div>
 </div>
 </div>
 
@@ -908,6 +948,7 @@ of the different interface modes, and how they are configured.</p>
 <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>
+<li><a class="reference internal" href="#cryptographic-primitives">Cryptographic Primitives</a></li>
 </ul>
 </li>
 </ul>
@@ -915,8 +956,8 @@ of the different interface modes, and how they are configured.</p>
 </ul>
 
   <h4>Previous topic</h4>
-  <p class="topless"><a href="interfaces.html"
+  <p class="topless"><a href="hardware.html"
-                        title="previous chapter">Supported Interfaces</a></p>
+                        title="previous chapter">Communications Hardware</a></p>
   <h4>Next topic</h4>
   <p class="topless"><a href="reference.html"
                         title="next chapter">API Reference</a></p>
@@ -951,7 +992,7 @@ of the different interface modes, and how they are configured.</p>
           <a href="reference.html" title="API Reference"
              >next</a> |</li>
         <li class="right" >
-          <a href="interfaces.html" title="Supported Interfaces"
+          <a href="hardware.html" title="Communications Hardware"
              >previous</a> |</li>
         <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.3.8 beta documentation</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">Understanding Reticulum</a></li> 

docs/source/gettingstartedfast.rst

@@ -103,16 +103,16 @@ With Reticulum, you only need to configure what interfaces you want to communica
 over. There is no need to configure address spaces, subnets, routing tables,
 or other things you might be used to from other network types.
 
-Once Reticulums knows which interfaces it should use, it will automatically
+Once Reticulum knows which interfaces it should use, it will automatically
 discover topography and configure transport of data to any destinations it
 knows about.
 
 In situations where you already have an established WiFi or ethernet network, and
-many devices that want to utilise the same external Reticulum network (for example over
+many devices that want to utilise the same external Reticulum network paths (for example over
 LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by
-adding any external interfaces to this systems configuration, and enabling transport. Any
+adding any external interfaces to the configuration of this system, and then enabling transport on it. Any
 other device on your local WiFi will then be able to connect to this wider Reticulum
-network just using the default interface configuration.
+network just using the default (:ref:`AutoInterface<interfaces-auto>`) configuration.
 
 Possibly, the examples in the config file are enough to get you started. If
 you want more information, you can read the :ref:`Building Networks<networks-main>`
@@ -137,7 +137,7 @@ Hosting a publicly reachable instance over TCP also requires a publicly reachabl
 which most Internet connections don't offer anymore.
 
 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 use this interface, users must also run an I2P daemon in
 parallel to ``rnsd``. For always-on I2P nodes it is recommended to use `i2pd <https://i2pd.website/>`_. 
 
 By default, I2P will encrypt and mix all traffic sent over the Internet, and 
@@ -146,12 +146,13 @@ 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 
 deep-packet-inspection much more difficult.
 
-I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls.
+I2P also allows users to host globally available Reticulum instances from non-public IPs and behind firewalls and NAT.
 
 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
 easier setup, use TCP.
 
+
 Connect to the Public Testnet
 ===========================================
 
@@ -180,6 +181,36 @@ via other entry points if you know them. There is absolutely no control over the
 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.
 
+
+Adding Radio Interfaces
+==============================================
+Once you have Reticulum installed and working, you can add radio interfaces with
+any compatible hardware you have available. Reticulum supports a wide range of radio
+hardware, and if you already have any available, it is very likely that it will
+work with Reticulum. For information on how to configure this, see the
+:ref:`Interfaces<interfaces-main>` section of this manual.
+
+If you do not already have transceiver hardware available, you can easily and
+cheaply build an :ref:`RNode<rnode-main>`, which is a general-purpose long-range
+digital radio transceiver, that integrates easily with Reticulum.
+
+To build one yourself requires installing a custom firmware on a supported LoRa
+development board with an auto-install script. Please see the :ref:`Communications Hardware<hardware-main>`
+chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the
+:ref:`list of suppliers<rnode-suppliers>`. For more information on RNode, you can also
+refer to these additional external resources:
+
+* `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
+* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
+* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
+* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
+
+If you have communications hardware that is not already supported by any of the
+:ref:`existing interface types<interfaces-main>`, but you think would be suitable for use with Reticulum,
+you are welcome to head over to the `GitHub discussion pages <https://github.com/markqvist/Reticulum/discussions>`_
+and propose adding an interface for the hardware.
+
+
 Develop a Program with Reticulum
 ===========================================
 If you want to develop programs that use Reticulum, the easiest way to get
@@ -310,21 +341,26 @@ It is also possible to include Reticulum in apps compiled and distributed as
 Android APKs. A detailed tutorial and example source code will be included
 here at a later point.
 
-Adding Radio Interfaces
+Pure-Python Reticulum
 ==============================================
-Once you have Reticulum installed and working, you can add radio interfaces with
+In some rare cases, and on more obscure system types, it is not possible to
-any compatible hardware you have available. For information on how to configure
+install one or more dependencies
-this, see the :ref:`Interfaces<interfaces-main>` section of this manual.
 
-A range of common LoRa development boards and transceiver modules can be used
+On more unusual systems, and in some rare cases, it might not be possible to
-as interfaces with Reticulum. You can refer to the following external resources
+install or even compile one or more of the above modules. In such situations,
-for more information:
+you can use the ``rnspure`` package instead of the ``rns`` package. The ``rnspure``
+package requires no external dependencies for installation. Please note that the
+actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*.
+The only difference is that the ``rnspure`` package lists no dependencies required
+for installation.
 
-* `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
+No matter how Reticulum is installed and started, it will load external dependencies
-* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
+only if they are *needed* and *available*. If for example you want to use Reticulum
-* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
+on a system that cannot support ``pyserial``, it is perfectly possible to do so using
-* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
+the `rnspure` package, but Reticulum will not be able to use serial-based interfaces.
+All other available modules will still be loaded when needed.
 
-If you have communications hardware that you think would be suitable for use with Reticulum,
+**Please Note!** If you use the `rnspure` package to run Reticulum on systems that
-you are welcome to head over to the `GitHub discussion pages <https://github.com/markqvist/Reticulum/discussions>`_
+do not support `PyCA/cryptography <https://github.com/pyca/cryptography>`_, it is
-and propose adding an interface for the hardware.
+important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>`
+section of this manual.

docs/source/hardware.rst

@@ -0,0 +1,220 @@
+.. _hardware-main:
+
+***********************
+Communications Hardware
+***********************
+
+One of the truly valuable aspects of Reticulum is the ability to use it over
+almost any conceivable kind of communications medium. The :ref:`interface types<interfaces-main>`
+available for configuration in Reticulum are flexible enough to cover the use
+of most wired and wireless communications hardware available, from decades-old
+packet radio modems to modern millimeter-wave backhaul systems.
+
+If you already have or operate some kind of communications hardware, there is a
+very good chance that it will work with Reticulum out of the box. In case it does
+not, it is possible to provide the necessary glue with very little effort using
+for example the :ref:`PipeInterface<interfaces-pipe>` or the :ref:`TCPClientInterface<interfaces-tcpc>`
+in combination with code like `TCP KISS Server <https://github.com/simplyequipped/tcpkissserver>`_
+by `simplyequipped <https://github.com/simplyequipped>`_.
+
+While this broad support and flexibility is very useful, an abundance of options
+can sometimes make it difficult to know where to begin, especially when you are
+starting from scratch.
+
+This chapter will outline a few different sensible easy starting paths to get
+real-world functional wireless communications up and running with minimal cost
+and effort. Two fundamental devices types will be covered, *RNodes* and *WiFi-based radios*.
+
+.. _rnode-main:
+
+RNode
+=====
+
+Reliable and general-purpose long-range digital radio transceiver systems are
+commonly either very expensive, difficult to set up and operate, hard to source,
+power-hungry, or all of the above at the same time. In an attempt to alleviate
+this situation, the transceiver system *RNode* was designed. It is important to
+note that RNode is not one specific device, from one particular vendor, but
+*an open plaform* that anyone can use to build digital transceivers suited to
+their needs and particular situations.
+
+An RNode is a general purpose, interoperable, low-power and long-range, reliable,
+open and flexible radio communications device. Depending on its components, it can
+operate on many different frequency bands, and use many different modulation
+schemes, but most commonly, and for the purposes of this chapter, we will limit
+the discussion to RNodes using *LoRa* modulation in common ISM bands.
+
+**Avoid Confusion!** An RNode can use LoRa as a *physical-layer modulation*, but it
+does not use, and has nothing to do with the *LoRaWAN* protocol and standard, commonly
+used for IoT devices. RNodes use *raw LoRa modulation*, without any additional
+protocol overhead. All high-level protocol funcionality is handled directly by
+Reticulum.
+
+.. _rnode-creating:
+
+Creating RNodes
+^^^^^^^^^^^^^^^
+RNode has been designed as a system that is easy to replicate across time and
+space. You can put together a functioning transceiver using commonly available
+components, and a few software tools. While you can design and build RNodes
+completely from scratch, to your exact desired specifications, this chapter
+will explain the easiest possible approach to creating RNodes, which is using common
+LoRa development boards. This approach can be boiled down to two simple steps:
+
+1. Obtain one or more supported development boards
+2. Install the RNode firmware with the automated installer
+
+Once the firmware has been installed and provisioned by the install script, it
+is ready to use with any software that supports RNodes, including Reticulum.
+The device can be used with Reticulum by adding an :ref:`RNodeInterface<interfaces-rnode>`
+to the configuration.
+
+.. _rnode-supported:
+
+Supported Boards
+^^^^^^^^^^^^^^^^
+To create one or more RNodes, you will need to obtain supported development
+boards. The following boards are supported by the auto-installer.
+
+LilyGO LoRa32 v2.1
+""""""""""""""""""
+.. image:: graphics/board_t3v21.png
+    :width: 50%
+    :align: center
+
+- **Supported Firmware Lines** v1.x & v2.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** ESP32
+- **Manufacturer** `LilyGO <https://lilygo.cn>`_
+
+
+LilyGO LoRa32 v2.0
+""""""""""""""""""
+.. image:: graphics/board_t3v20.png
+    :width: 50%
+    :align: center
+
+- **Supported Firmware Lines** v1.x & v2.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** ESP32
+- **Manufacturer** `LilyGO <https://lilygo.cn>`_
+
+
+LilyGO T-Beam
+"""""""""""""
+.. image:: graphics/board_tbeam.png
+    :width: 65%
+    :align: center
+
+- **Supported Firmware Lines** v1.x & v2.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** ESP32
+- **Manufacturer** `LilyGO <https://lilygo.cn>`_
+
+
+Heltec LoRa32 v2.0
+""""""""""""""""""
+.. image:: graphics/board_heltec32.png
+    :width: 50%
+    :align: center
+
+- **Supported Firmware Lines** v1.x & v2.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** ESP32
+- **Manufacturer** `Heltec Automation <https://heltec.org>`_
+
+
+Original RNode v1.x
+"""""""""""""""""""
+.. image:: graphics/board_rnode.png
+    :width: 50%
+    :align: center
+
+- **Supported Firmware Lines** v1.x
+- **Transceiver IC** Semtech SX1276
+- **Device Platform** AVR ATmega1284p
+- **Manufacturer** `unsigned.io <https://unsigned.io>`_
+
+
+.. _rnode-installation:
+
+Installation
+^^^^^^^^^^^^
+
+Once you have obtained compatible boards, you can install the `RNode Firmware <https://github.com/markqvist/RNode_Firmware>`_
+using the `RNode Configuration Utility <https://github.com/markqvist/rnodeconfigutil>`_.
+Make sure that ``Python3`` and ``pip`` is installed on your system, and then install
+the config utility with ``pip``:
+
+.. code::
+
+   pip3 install rnodeconf
+
+Once installation has completed, it is time to start installing the firmware on your
+devices. Run ``rnodeconf`` in auto-install mode like so:
+
+.. code::
+
+   rnodeconf --autoinstall
+
+The utility will guide you through the installation process by asking a series of
+questions about your hardware. Simply follow the guide, and the utility will
+auto-install and configure your devices
+
+**Important Note!** It is currently recommended to use the v1.x line of the RNode firmware,
+even though the v2.x line is available for early testing. The v2.x line should still be
+considered an experimental pre-release. Only use the v2.x firmware line if you want to test
+out the absolutely newest version, and don't care about stability.
+
+.. _rnode-usage:
+
+Usage with Reticulum
+^^^^^^^^^^^^^^^^^^^^
+When the devices have been installed and provisioned, you can use them with Reticulum
+by adding the :ref:`relevant interface section<interfaces-rnode>` to the configuration
+file of Reticulum. For v1.x firmwares, you will have to specify all interface parameters,
+such as serial port and on-air parameters. For v2.x firmwares, you just need to specify
+the Connection ID of the RNode, and Reticulum will automatically locate and connect to the
+RNode, using the parameters stored in the RNode itself.
+
+.. _rnode-suppliers:
+
+Suppliers
+^^^^^^^^^
+Get in touch if you want to have your RNode supplier listed here, or if you want help to
+get started with producing RNodes.
+
+
+WiFi-based Hardware
+===================
+
+It is possible to use all kinds of both short- and long-range Wifi-based hardware
+with Reticulum. Any kind of hardware that fully supports bridged ethernet over the
+WiFi interface will work with the :ref:`AutoInterface<interfaces-auto>` in Reticulum.
+Most devices will behave like this by default, or allow it via configuration options.
+
+This means that you can simply configure the physical links of the WiFi based devices,
+and start communicating over them using Reticulum. It is not necessary to enable any IP
+infrastructure such as DHCP servers, DNS or similar, as long as at least Ethernet is
+available, and packets are passed transparently over the physical WiFi-based devices.
+
+Below is a list of example WiFi (and similar) radios that work well for high capacity
+Reticulum links over long distances:
+
+- `Ubiquiti airMAX radios <https://store.ui.com/collections/operator-airmax-devices>`_
+- `Ubiquiti LTU radios <https://store.ui.com/collections/operator-ltu>`_
+- `MikroTik radios <https://mikrotik.com/products/group/wireless-systems>`_
+
+This list is by no means exhaustive, and only serves as a few examples of radio hardware
+that is relatively cheap while providing long range and high capacity for Reticulum
+networks. As in all other cases, it is also possible for Reticulum to co-exist with IP
+networks running concurrently on such devices.
+
+Combining Hardware Types
+========================
+
+It is a useful tool to combine different link and hardware types when designing and
+building a network. One useful design pattern is to employ high-capacity point-to-point
+links based on WiFi or millimeter-wave radios (with high-gain directional antennas)
+for the network backbone, and using LoRa-based RNodes for covering large areas with
+connectivity for client devices.

docs/source/index.rst

@@ -13,9 +13,11 @@ to participate in the development of Reticulum itself.
    using
    networks
    interfaces
+   hardware
    understanding
    reference
    examples
+   support
 
 
 .. only:: html

docs/source/interfaces.rst

@@ -274,10 +274,6 @@ with all peers in your local ethernet broadcast domain, the
 :ref:`Auto Interface<interfaces-auto>` performs better, and is even
 easier to use.
 
-The below example is enabled by default on new Reticulum installations,
-as it provides an easy way to get started and to test Reticulum on a
-pre-existing LAN.
-
 .. code::
 
   # This example enables communication with other

docs/source/support.rst

@@ -0,0 +1,36 @@
+.. _support-main:
+
+*****************
+Support Reticulum
+*****************
+This reference guide lists and explains all classes exposed by the RNS API.
+
+Donations
+=========
+You can help support the continued development of open, free and private communications systems by donating via one of the following channels:
+
+    Monero:
+
+    84FpY1QbxHcgdseePYNmhTHcrgMX4nFf
+    BYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD1
+    9b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
+
+    Ethereum
+
+    0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a
+
+    Bitcoin
+
+    3CPmacGm34qYvR6XWLVEJmi2aNe3PZqUuq
+
+    Ko-Fi: https://ko-fi.com/markqvist
+
+Are certain features in the development roadmap are important to you or your organisation? Make them a reality quickly by sponsoring their implementation.
+
+Provide Feedback
+================
+All feedback on the usage, functioning and potential dysfunctioning of any and
+all components of the system is very valuable to the continued development and
+improvement of Reticulum. Absolutely no automated analytics, telemetly, error
+reporting or statistics is collected and reported by Reticulum under any
+circumstances, so we rely on old-fashioned human feedback.

docs/source/understanding.rst

@@ -839,3 +839,52 @@ of the different interface modes, and how they are configured.
       Boundary ── ✓ ──┤              ├── ✓ ── Boundary
       Roaming ─── ✕ ──┘              └── ✕ ── Roaming
 
+
+.. _understanding-primitives:
+
+Cryptographic Primitives
+------------------------
+
+Reticulum has been designed to use a simple suite of efficient, strong and modern
+cryptographic primitives, with widely available implementations that can be used
+both on general-purpose CPUs and on microcontrollers. The necessary primitives are:
+
+* Ed25519 for signatures
+
+* X22519 for ECDH key exchanges
+
+* HKDF for key derivation
+
+* Fernet for encrypted tokens
+
+  * AES-128 in CBC mode
+
+  * HMAC for message authentication
+
+* SHA-256
+
+* SHA-512
+
+In the default installation configuration, the ``X25519``, ``Ed25519`` and ``AES-128-CBC``
+primitives are provided by `OpenSSL <https://www.openssl.org/>`_ (via the `PyCA/cryptography <https://github.com/pyca/cryptography>`_
+package). The hashing functions ``SHA-256`` and ``SHA-512`` are provided by the standard
+Python `hashlib <https://docs.python.org/3/library/hashlib.html>`_. The ``HKDF``, ``HMAC``,
+``Fernet`` primitives, and the ``PKCS7`` padding function are always provided by the
+following internal implementations:
+
+- ``RNS/Cryptography/HKDF.py``
+- ``RNS/Cryptography/HMAC.py``
+- ``RNS/Cryptography/Fernet.py``
+- ``RNS/Cryptography/PKCS7.py``
+
+
+Reticulum also includes a complete implementation of all necessary primitives in pure Python.
+If OpenSSL & PyCA are not available on the system when Reticulum is started, Reticulum will
+instead use the internal pure-python primitives. A trivial consequence of this is performance,
+with the OpenSSL backend being *much* faster. The most important consequence however, is the
+potential loss of security by using primitives that has not seen the same amount of scrutiny,
+testing and review as those from OpenSSL.
+
+If you want to use the internal pure-python primitives, it is **highly advisable** that you
+have a good understanding of the risks that this pose, and make an informed decision on whether
+those risks are acceptable to you.