Updated documentation
BIN
docs/manual/_images/board_heltec32.png
Normal file
After Width: | Height: | Size: 191 KiB |
BIN
docs/manual/_images/board_rnode.png
Normal file
After Width: | Height: | Size: 259 KiB |
BIN
docs/manual/_images/board_t3v20.jpg
Normal file
After Width: | Height: | Size: 122 KiB |
BIN
docs/manual/_images/board_t3v20.png
Normal file
After Width: | Height: | Size: 249 KiB |
BIN
docs/manual/_images/board_t3v21.png
Normal file
After Width: | Height: | Size: 236 KiB |
BIN
docs/manual/_images/board_tbeam.png
Normal file
After Width: | Height: | Size: 191 KiB |
BIN
docs/manual/_images/board_tbeam_alt.jpg
Normal file
After Width: | Height: | Size: 34 KiB |
@ -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
|
||||
any compatible hardware you have available. For information on how to configure
|
||||
this, see the :ref:`Interfaces<interfaces-main>` section of this manual.
|
||||
In some rare cases, and on more obscure system types, it is not possible to
|
||||
install one or more dependencies
|
||||
|
||||
A range of common LoRa development boards and transceiver modules can be used
|
||||
as interfaces with Reticulum. You can refer to the following external resources
|
||||
for more information:
|
||||
On more unusual systems, and in some rare cases, it might not be possible to
|
||||
install or even compile one or more of the above modules. In such situations,
|
||||
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/>`_
|
||||
* `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/>`_
|
||||
No matter how Reticulum is installed and started, it will load external dependencies
|
||||
only if they are *needed* and *available*. If for example you want to use Reticulum
|
||||
on a system that cannot support ``pyserial``, it is perfectly possible to do so using
|
||||
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,
|
||||
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.
|
||||
**Please Note!** If you use the `rnspure` package to run Reticulum on systems that
|
||||
do not support `PyCA/cryptography <https://github.com/pyca/cryptography>`_, it is
|
||||
important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>`
|
||||
section of this manual.
|
220
docs/manual/_sources/hardware.rst.txt
Normal file
@ -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.
|
@ -13,9 +13,11 @@ to participate in the development of Reticulum itself.
|
||||
using
|
||||
networks
|
||||
interfaces
|
||||
hardware
|
||||
understanding
|
||||
reference
|
||||
examples
|
||||
support
|
||||
|
||||
|
||||
.. only:: html
|
||||
|
@ -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
|
||||
|
36
docs/manual/_sources/support.rst.txt
Normal file
@ -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.
|
@ -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.
|
@ -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">
|
||||
<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. 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>A range of common LoRa development boards and transceiver modules can be used
|
||||
as interfaces with Reticulum. You can refer to the following external resources
|
||||
for more information:</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 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 class="section" id="pure-python-reticulum">
|
||||
<h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Permalink to this headline">¶</a></h2>
|
||||
<p>In some rare cases, and on more obscure system types, it is not possible to
|
||||
install one or more dependencies</p>
|
||||
<p>On more unusual systems, and in some rare cases, it might not be possible to
|
||||
install or even compile one or more of the above modules. In such situations,
|
||||
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>
|
||||
package requires no external dependencies for installation. Please note that the
|
||||
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>.
|
||||
The only difference is that the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package lists no dependencies required
|
||||
for installation.</p>
|
||||
<p>No matter how Reticulum is installed and started, it will load external dependencies
|
||||
only if they are <em>needed</em> and <em>available</em>. If for example you want to use Reticulum
|
||||
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
|
||||
the <cite>rnspure</cite> package, but Reticulum will not be able to use serial-based interfaces.
|
||||
All other available modules will still be loaded when needed.</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>
|
||||
|
302
docs/manual/hardware.html
Normal file
@ -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 — 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> »</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 & 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 & 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 & 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 & 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> »</li>
|
||||
<li class="nav-item nav-item-this"><a href="">Communications Hardware</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2022, Mark Qvist.
|
||||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
|
||||
</div>
|
||||
</body>
|
||||
</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">
|
||||
|
@ -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"
|
||||
title="next chapter">Understanding Reticulum</a></p>
|
||||
<p class="topless"><a href="hardware.html"
|
||||
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"
|
||||
|
127
docs/manual/support.html
Normal file
@ -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 — 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> »</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> »</li>
|
||||
<li class="nav-item nav-item-this"><a href="">Support Reticulum</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2022, Mark Qvist.
|
||||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
|
||||
</div>
|
||||
</body>
|
||||
</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> »</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 & 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"
|
||||
title="previous chapter">Supported Interfaces</a></p>
|
||||
<p class="topless"><a href="hardware.html"
|
||||
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> »</li>
|
||||
<li class="nav-item nav-item-this"><a href="">Understanding Reticulum</a></li>
|
||||
|
@ -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
|
||||
any compatible hardware you have available. For information on how to configure
|
||||
this, see the :ref:`Interfaces<interfaces-main>` section of this manual.
|
||||
In some rare cases, and on more obscure system types, it is not possible to
|
||||
install one or more dependencies
|
||||
|
||||
A range of common LoRa development boards and transceiver modules can be used
|
||||
as interfaces with Reticulum. You can refer to the following external resources
|
||||
for more information:
|
||||
On more unusual systems, and in some rare cases, it might not be possible to
|
||||
install or even compile one or more of the above modules. In such situations,
|
||||
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/>`_
|
||||
* `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/>`_
|
||||
No matter how Reticulum is installed and started, it will load external dependencies
|
||||
only if they are *needed* and *available*. If for example you want to use Reticulum
|
||||
on a system that cannot support ``pyserial``, it is perfectly possible to do so using
|
||||
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,
|
||||
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.
|
||||
**Please Note!** If you use the `rnspure` package to run Reticulum on systems that
|
||||
do not support `PyCA/cryptography <https://github.com/pyca/cryptography>`_, it is
|
||||
important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>`
|
||||
section of this manual.
|
BIN
docs/source/graphics/board_heltec32.png
Normal file
After Width: | Height: | Size: 191 KiB |
BIN
docs/source/graphics/board_rnode.png
Normal file
After Width: | Height: | Size: 259 KiB |
BIN
docs/source/graphics/board_t3v20.png
Normal file
After Width: | Height: | Size: 249 KiB |
BIN
docs/source/graphics/board_t3v21.png
Normal file
After Width: | Height: | Size: 236 KiB |
BIN
docs/source/graphics/board_tbeam.png
Normal file
After Width: | Height: | Size: 191 KiB |
220
docs/source/hardware.rst
Normal file
@ -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.
|
@ -13,9 +13,11 @@ to participate in the development of Reticulum itself.
|
||||
using
|
||||
networks
|
||||
interfaces
|
||||
hardware
|
||||
understanding
|
||||
reference
|
||||
examples
|
||||
support
|
||||
|
||||
|
||||
.. only:: html
|
||||
|
@ -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
|
||||
|
36
docs/source/support.rst
Normal file
@ -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.
|
@ -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.
|