diff --git a/docs/manual/_images/board_heltec32.png b/docs/manual/_images/board_heltec32.png new file mode 100644 index 0000000..9f16786 Binary files /dev/null and b/docs/manual/_images/board_heltec32.png differ diff --git a/docs/manual/_images/board_rnode.png b/docs/manual/_images/board_rnode.png new file mode 100644 index 0000000..97fcce3 Binary files /dev/null and b/docs/manual/_images/board_rnode.png differ diff --git a/docs/manual/_images/board_t3v20.jpg b/docs/manual/_images/board_t3v20.jpg new file mode 100644 index 0000000..12f104f Binary files /dev/null and b/docs/manual/_images/board_t3v20.jpg differ diff --git a/docs/manual/_images/board_t3v20.png b/docs/manual/_images/board_t3v20.png new file mode 100644 index 0000000..369586a Binary files /dev/null and b/docs/manual/_images/board_t3v20.png differ diff --git a/docs/manual/_images/board_t3v21.png b/docs/manual/_images/board_t3v21.png new file mode 100644 index 0000000..28a62df Binary files /dev/null and b/docs/manual/_images/board_t3v21.png differ diff --git a/docs/manual/_images/board_tbeam.png b/docs/manual/_images/board_tbeam.png new file mode 100644 index 0000000..9e8b839 Binary files /dev/null and b/docs/manual/_images/board_tbeam.png differ diff --git a/docs/manual/_images/board_tbeam_alt.jpg b/docs/manual/_images/board_tbeam_alt.jpg new file mode 100644 index 0000000..866f642 Binary files /dev/null and b/docs/manual/_images/board_tbeam_alt.jpg differ diff --git a/docs/manual/_sources/gettingstartedfast.rst.txt b/docs/manual/_sources/gettingstartedfast.rst.txt index 6b7d91c..3e9cc9f 100644 --- a/docs/manual/_sources/gettingstartedfast.rst.txt +++ b/docs/manual/_sources/gettingstartedfast.rst.txt @@ -103,16 +103,16 @@ With Reticulum, you only need to configure what interfaces you want to communica over. There is no need to configure address spaces, subnets, routing tables, or other things you might be used to from other network types. -Once Reticulums knows which interfaces it should use, it will automatically +Once Reticulum knows which interfaces it should use, it will automatically discover topography and configure transport of data to any destinations it knows about. In situations where you already have an established WiFi or ethernet network, and -many devices that want to utilise the same external Reticulum network (for example over +many devices that want to utilise the same external Reticulum network paths (for example over LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by -adding any external interfaces to this systems configuration, and enabling transport. Any +adding any external interfaces to the configuration of this system, and then enabling transport on it. Any other device on your local WiFi will then be able to connect to this wider Reticulum -network just using the default interface configuration. +network just using the default (:ref:`AutoInterface`) 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` @@ -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) `_. To properly use this interface, users must also run an I2P daemon in +(I2P) `_. 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 `_. 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` section of this manual. + +If you do not already have transceiver hardware available, you can easily and +cheaply build an :ref:`RNode`, 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` +chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the +:ref:`list of suppliers`. For more information on RNode, you can also +refer to these additional external resources: + +* `How To Make Your Own RNodes `_ +* `Installing RNode Firmware on Compatible LoRa Devices `_ +* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh `_ +* `RNode Firmware `_ + +If you have communications hardware that is not already supported by any of the +:ref:`existing interface types`, but you think would be suitable for use with Reticulum, +you are welcome to head over to the `GitHub discussion pages `_ +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` 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 `_ -* `Installing RNode Firmware on Compatible LoRa Devices `_ -* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh `_ -* `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 `_ -and propose adding an interface for the hardware. \ No newline at end of file +**Please Note!** If you use the `rnspure` package to run Reticulum on systems that +do not support `PyCA/cryptography `_, it is +important that you read and understand the :ref:`Cryptographic Primitives ` +section of this manual. \ No newline at end of file diff --git a/docs/manual/_sources/hardware.rst.txt b/docs/manual/_sources/hardware.rst.txt new file mode 100644 index 0000000..d99074c --- /dev/null +++ b/docs/manual/_sources/hardware.rst.txt @@ -0,0 +1,220 @@ +.. _hardware-main: + +*********************** +Communications Hardware +*********************** + +One of the truly valuable aspects of Reticulum is the ability to use it over +almost any conceivable kind of communications medium. The :ref:`interface types` +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` or the :ref:`TCPClientInterface` +in combination with code like `TCP KISS Server `_ +by `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` +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 `_ + + +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 `_ + + +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 `_ + + +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 `_ + + +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 `_ + + +.. _rnode-installation: + +Installation +^^^^^^^^^^^^ + +Once you have obtained compatible boards, you can install the `RNode Firmware `_ +using the `RNode Configuration Utility `_. +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` 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` 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 `_ +- `Ubiquiti LTU radios `_ +- `MikroTik radios `_ + +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. \ No newline at end of file diff --git a/docs/manual/_sources/index.rst.txt b/docs/manual/_sources/index.rst.txt index 58fece9..7b28a57 100644 --- a/docs/manual/_sources/index.rst.txt +++ b/docs/manual/_sources/index.rst.txt @@ -13,9 +13,11 @@ to participate in the development of Reticulum itself. using networks interfaces + hardware understanding reference examples + support .. only:: html diff --git a/docs/manual/_sources/interfaces.rst.txt b/docs/manual/_sources/interfaces.rst.txt index 7bfdf0e..15e1b87 100644 --- a/docs/manual/_sources/interfaces.rst.txt +++ b/docs/manual/_sources/interfaces.rst.txt @@ -274,10 +274,6 @@ with all peers in your local ethernet broadcast domain, the :ref:`Auto Interface` 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 diff --git a/docs/manual/_sources/support.rst.txt b/docs/manual/_sources/support.rst.txt new file mode 100644 index 0000000..308ff6c --- /dev/null +++ b/docs/manual/_sources/support.rst.txt @@ -0,0 +1,36 @@ +.. _support-main: + +***************** +Support Reticulum +***************** +This reference guide lists and explains all classes exposed by the RNS API. + +Donations +========= +You can help support the continued development of open, free and private communications systems by donating via one of the following channels: + + Monero: + + 84FpY1QbxHcgdseePYNmhTHcrgMX4nFf + BYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD1 + 9b3B8NiLCGVxzKV17UMmmeEsCrPyA5w + + Ethereum + + 0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a + + Bitcoin + + 3CPmacGm34qYvR6XWLVEJmi2aNe3PZqUuq + + Ko-Fi: https://ko-fi.com/markqvist + +Are certain features in the development roadmap are important to you or your organisation? Make them a reality quickly by sponsoring their implementation. + +Provide Feedback +================ +All feedback on the usage, functioning and potential dysfunctioning of any and +all components of the system is very valuable to the continued development and +improvement of Reticulum. Absolutely no automated analytics, telemetly, error +reporting or statistics is collected and reported by Reticulum under any +circumstances, so we rely on old-fashioned human feedback. \ No newline at end of file diff --git a/docs/manual/_sources/understanding.rst.txt b/docs/manual/_sources/understanding.rst.txt index 56d665a..568312b 100644 --- a/docs/manual/_sources/understanding.rst.txt +++ b/docs/manual/_sources/understanding.rst.txt @@ -839,3 +839,52 @@ of the different interface modes, and how they are configured. Boundary ── ✓ ──┤ ├── ✓ ── Boundary Roaming ─── ✕ ──┘ └── ✕ ── Roaming + +.. _understanding-primitives: + +Cryptographic Primitives +------------------------ + +Reticulum has been designed to use a simple suite of efficient, strong and modern +cryptographic primitives, with widely available implementations that can be used +both on general-purpose CPUs and on microcontrollers. The necessary primitives are: + +* Ed25519 for signatures + +* X22519 for ECDH key exchanges + +* HKDF for key derivation + +* Fernet for encrypted tokens + + * AES-128 in CBC mode + + * HMAC for message authentication + +* SHA-256 + +* SHA-512 + +In the default installation configuration, the ``X25519``, ``Ed25519`` and ``AES-128-CBC`` +primitives are provided by `OpenSSL `_ (via the `PyCA/cryptography `_ +package). The hashing functions ``SHA-256`` and ``SHA-512`` are provided by the standard +Python `hashlib `_. 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. \ No newline at end of file diff --git a/docs/manual/gettingstartedfast.html b/docs/manual/gettingstartedfast.html index e3ff6fa..1b14410 100644 --- a/docs/manual/gettingstartedfast.html +++ b/docs/manual/gettingstartedfast.html @@ -119,15 +119,15 @@ internet, to LoRa and Packet Radio interfaces.

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.

-

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 (AutoInterface) configuration.

Possibly, the examples in the config file are enough to get you started. If you want more information, you can read the Building Networks and Interfaces chapters of this manual.

@@ -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.

The I2PInterface routes messages through the Invisible Internet Protocol -(I2P). To properly use this interface, users must also run an I2P daemon in +(I2P). 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.

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.

-

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.

@@ -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.

+
+

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 +Interfaces section of this manual.

+

If you do not already have transceiver hardware available, you can easily and +cheaply build an RNode, 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 Communications Hardware +chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the +list of suppliers. For more information on RNode, you can also +refer to these additional external resources:

+ +

If you have communications hardware that is not already supported by any of the +existing interface types, but you think would be suitable for use with Reticulum, +you are welcome to head over to the GitHub discussion pages +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 @@ -297,23 +323,26 @@ and a few extra commands are required.

Android APKs. A detailed tutorial and example source code will be included here at a later point.

-
-

Adding Radio Interfaces

-

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 Interfaces section of this manual.

-

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:

- -

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 -and propose adding an interface for the hardware.

+
+

Pure-Python Reticulum

+

In some rare cases, and on more obscure system types, it is not possible to +install one or more dependencies

+

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.

+

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.

+

Please Note! If you use the rnspure package to run Reticulum on systems that +do not support PyCA/cryptography, it is +important that you read and understand the Cryptographic Primitives +section of this manual.

@@ -336,11 +365,12 @@ and propose adding an interface for the hardware.

  • Creating a Network With Reticulum
  • Connecting Reticulum Instances Over the Internet
  • Connect to the Public Testnet
    • +
  • Adding Radio Interfaces
  • Develop a Program with Reticulum
  • Participate in Reticulum Development
  • Reticulum on ARM64
  • Reticulum on Android
    • -
  • Adding Radio Interfaces
    • +
  • Pure-Python Reticulum
    • diff --git a/docs/manual/hardware.html b/docs/manual/hardware.html new file mode 100644 index 0000000..88a51a2 --- /dev/null +++ b/docs/manual/hardware.html @@ -0,0 +1,302 @@ + + + + + + + + Communications Hardware — Reticulum Network Stack 0.3.8 beta documentation + + + + + + + + + + + + + + + +
    +
    +
    +
    + +
    +

    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 interface types +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 PipeInterface or the TCPClientInterface +in combination with code like TCP KISS Server +by 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

    +

    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.

    +
    +

    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. +

    2. Install the RNode firmware with the automated installer

      3. +
    +

    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 RNodeInterface +to the configuration.

    +
    +
    +

    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

    +_images/board_t3v21.png +
      +

    • Supported Firmware Lines v1.x & v2.x

      • +

    • Transceiver IC Semtech SX1276

      • +

    • Device Platform ESP32

      • +

    • Manufacturer LilyGO

      • +
    +
    +
    +

    LilyGO LoRa32 v2.0

    +_images/board_t3v20.png +
      +

    • Supported Firmware Lines v1.x & v2.x

      • +

    • Transceiver IC Semtech SX1276

      • +

    • Device Platform ESP32

      • +

    • Manufacturer LilyGO

      • +
    +
    +
    +

    LilyGO T-Beam

    +_images/board_tbeam.png +
      +

    • Supported Firmware Lines v1.x & v2.x

      • +

    • Transceiver IC Semtech SX1276

      • +

    • Device Platform ESP32

      • +

    • Manufacturer LilyGO

      • +
    +
    +
    +

    Heltec LoRa32 v2.0

    +_images/board_heltec32.png +
      +

    • Supported Firmware Lines v1.x & v2.x

      • +

    • Transceiver IC Semtech SX1276

      • +

    • Device Platform ESP32

      • +

    • Manufacturer Heltec Automation

      • +
    +
    +
    +

    Original RNode v1.x

    +_images/board_rnode.png +
      +

    • Supported Firmware Lines v1.x

      • +

    • Transceiver IC Semtech SX1276

      • +

    • Device Platform AVR ATmega1284p

      • +

    • Manufacturer unsigned.io

      • +
    +
    +
    +
    +

    Installation

    +

    Once you have obtained compatible boards, you can install the RNode Firmware +using the RNode Configuration Utility. +Make sure that Python3 and pip is installed on your system, and then install +the config utility with pip:

    +
    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:

    +
    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.

    +
    +
    +

    Usage with Reticulum

    +

    When the devices have been installed and provisioned, you can use them with Reticulum +by adding the relevant interface section 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.

    +
    +
    +

    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 AutoInterface 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:

    + +

    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.

    +
    +
    + + +
    +
    +
    +
    + +
    +
    + + + + \ No newline at end of file diff --git a/docs/manual/index.html b/docs/manual/index.html index b24e306..58e7dab 100644 --- a/docs/manual/index.html +++ b/docs/manual/index.html @@ -62,11 +62,12 @@ to participate in the development of Reticulum itself.

  • Creating a Network With Reticulum
  • Connecting Reticulum Instances Over the Internet
  • Connect to the Public Testnet
    • +
  • Adding Radio Interfaces
  • Develop a Program with Reticulum
  • Participate in Reticulum Development
  • Reticulum on ARM64
  • Reticulum on Android
    • -
  • Adding Radio Interfaces
    • +
  • Pure-Python Reticulum
  • Using Reticulum on Your System
    • +
  • Communications Hardware +
  • Understanding Reticulum
    • @@ -166,6 +181,11 @@ to participate in the development of Reticulum itself.

  • Filetransfer
    • +
  • Support Reticulum +
    • diff --git a/docs/manual/interfaces.html b/docs/manual/interfaces.html index feed937..39097af 100644 --- a/docs/manual/interfaces.html +++ b/docs/manual/interfaces.html @@ -16,7 +16,7 @@ - +