Updated changelog

Fix RNodeMultiInterface to work with refactored interfaces

.github/workflows/build.yml

@@ -0,0 +1,96 @@
+name: Build Reticulum
+
+on:
+  push:
+    branches: 
+      - '*'
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+*"
+  pull_request:
+    branches: 
+      - master
+    paths-ignore:
+      - .gitignore
+      - LICENSE
+
+permissions:
+  contents: write
+
+concurrency: 
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: make test
+
+  package:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment: ${{ contains(github.ref, '-') && 'development' || 'production' }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: |
+          python -m pip install -q build wheel setuptools
+          make remove_symlinks
+          make build_wheel
+          make build_pure_wheel
+          make create_symlinks
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package
+          path: dist/*.whl
+
+  # documentation:
+  #   needs: test
+  #   if: startsWith(github.ref, 'refs/tags/')
+  #   runs-on: ubuntu-latest
+  #   environment: ${{ contains(github.ref, '-') && 'development' || 'production' }}
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-python@v5
+  #       with:
+  #         python-version: 3.x
+  #     - run: |
+  #         sudo apt-get -qq update && sudo apt-get -qq install latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
+  #         python -m pip -q install sphinx sphinx-copybutton
+  #         cd docs && make latexpdf && make epub
+  #     - uses: actions/upload-artifact@v4
+  #       with:
+  #         name: documentation
+  #         path: |
+  #           docs/build/latex/*.pdf
+  #           docs/build/epub/*.epub
+
+  release:
+    needs: [package]
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment: ${{ contains(github.ref, '-') && 'development' || 'production' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          path: .artifacts
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            .artifacts/package/**.whl
+#            .artifacts/documentation/latex/reticulumnetworkstack.pdf
+#            .artifacts/documentation/epub/ReticulumNetworkStack.epub
+          draft: true
+          generate_release_notes: true
+          prerelease: ${{ contains(github.ref, '-') }}
+          fail_on_unmatched_files: true

.github/workflows/python-app.yml

@@ -1,28 +0,0 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
-name: Test suite
-
-on:
-  push:
-    branches: [ "master" ]
-  pull_request:
-    branches: [ "master" ]
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python 3.10
-      uses: actions/setup-python@v3
-      with:
-        python-version: "3.10"
-    - name: Test
-      run: |
-        make test

Changelog.md

@@ -1,3 +1,49 @@
+### 2024-12-09: RNS β 0.8.7
+
+This maintenance release adds support for OpenWRT packaging, and brings several minor improvements and bugfixes.
+
+Thanks to @gretel and @jacobeva, who contributed to this release!
+
+**Changes**
+- Added support for packaging RNS to OpenWRT
+- Added ability to run `rnstatus` as application-local imported module
+- Added ability to reflect RNS log output to app-internal log handler callback
+- Added display read functionality to `RNodeInterface`
+- Fixed a regression in `RNodeMultiInterface` caused by earlier refactoring
+- Imrpoved documentation
+
+**Release Hashes**
+```
+e76ba8feeeae2c8df27e9906deebd7c721f0f0e887ad3fbd26df0212d6ce907a rns-0.8.7-py3-none-any.whl
+046608539bc235d52c970c7f3c54e7aa01a86016ae00263f8a55fc796b6939f5 rnspure-0.8.7-py3-none-any.whl
+```
+
+### 2024-11-24: RNS β 0.8.6
+
+This release adds full interface modularity and custom interface loading to RNS. Users can now easily create and use their own custom interfaces for communicating over practically anything. Support for IPv6 has also been added to the TCP-based interfaces.
+
+In addition, several bugs have been fixed, and various internal improvements to code consistency and naming conventions have been carried out.
+
+Thanks to @gretel and @deavmi, who contributed to this release!
+
+**Changes**
+- Added ability to load and configure custom, user-supplied interfaces
+- Added IPv6 support to `TCPClientInterface` and `TCPServerInterface`
+- Added an init option to the API for requiring an existing shared instance
+- Changed `rnstatus` behaviour to only show status if Reticulum is already running
+- Fixed `KISSInterface` beacon length for compatibility with software modems
+- Fixed interface client count sometimes reporting incorrect values on TCP and I2P interfaces
+- Refactored and improved interface initialisation and configuration handling
+- Refactored interface code to be more consistent
+- Refactored various deprecated references and names
+- Updated documentation and manual
+
+**Release Hashes**
+```
+60be127f003cd7838149bf8f01020206f829a7bd192706a608e39d8d7193d07b rns-0.8.6-py3-none-any.whl
+d8701e19279d292b5b8af9da7c67b6ac88a992ca65109f8182c3e5c761a9ebeb rnspure-0.8.6-py3-none-any.whl
+```
+
 ### 2024-10-20: RNS β 0.8.5
 
 This maintenance release fixes a number of bugs. Thanks to @faragher for contributing to this release!

Examples/ExampleInterface.py

@@ -0,0 +1,299 @@
+# MIT License - Copyright (c) 2024 Mark Qvist / unsigned.io
+
+# This example illustrates creating a custom interface
+# definition, that can be loaded and used by Reticulum at
+# runtime. Any number of custom interfaces can be created
+# and loaded. To use the interface place it in the folder
+# ~/.reticulum/interfaces, and add an interface entry to
+# your Reticulum configuration file similar to this:
+
+#  [[Example Custom Interface]]
+#    type = ExampleInterface
+#    enabled = no
+#    mode = gateway
+#    port = /dev/ttyUSB0
+#    speed = 115200
+#    databits = 8
+#    parity = none
+#    stopbits = 1
+
+from time import sleep
+import sys
+import threading
+import time
+
+# This HDLC helper class is used by the interface
+# to delimit and packetize data over the physical
+# medium - in this case a serial connection.
+class HDLC():
+    # This example interface packetizes data using
+    # simplified HDLC framing, similar to PPP
+    FLAG     = 0x7E
+    ESC      = 0x7D
+    ESC_MASK = 0x20
+
+    @staticmethod
+    def escape(data):
+        data = data.replace(bytes([HDLC.ESC]), bytes([HDLC.ESC, HDLC.ESC^HDLC.ESC_MASK]))
+        data = data.replace(bytes([HDLC.FLAG]), bytes([HDLC.ESC, HDLC.FLAG^HDLC.ESC_MASK]))
+        return data
+
+# Let's define our custom interface class. It must
+# be a sub-class of the RNS "Interface" class.
+class ExampleInterface(Interface):
+    # All interface classes must define a default
+    # IFAC size, used in IFAC setup when the user
+    # has not specified a custom IFAC size. This
+    # option is specified in bytes.
+    DEFAULT_IFAC_SIZE = 8
+
+    # The following properties are local to this
+    # particular interface implementation.
+    owner    = None
+    port     = None
+    speed    = None
+    databits = None
+    parity   = None
+    stopbits = None
+    serial   = None
+
+    # All Reticulum interfaces must have an __init__
+    # method that takes 2 positional arguments:
+    # The owner RNS Transport instance, and a dict
+    # of configuration values.
+    def __init__(self, owner, configuration):
+
+        # The following lines demonstrate handling
+        # potential dependencies required for the
+        # interface to function correctly.
+        import importlib
+        if importlib.util.find_spec('serial') != None:
+            import serial
+        else:
+            RNS.log("Using this interface requires a serial communication module to be installed.", RNS.LOG_CRITICAL)
+            RNS.log("You can install one with the command: python3 -m pip install pyserial", RNS.LOG_CRITICAL)
+            RNS.panic()
+
+        # We start out by initialising the super-class
+        super().__init__()
+
+        # To make sure the configuration data is in the
+        # correct format, we parse it through the following
+        # method on the generic Interface class. This step
+        # is required to ensure compatibility on all the
+        # platforms that Reticulum supports.
+        ifconf    = Interface.get_config_obj(configuration)
+
+        # Read the interface name from the configuration
+        # and set it on our interface instance.
+        name      = ifconf["name"]
+        self.name = name
+
+        # We read configuration parameters from the supplied
+        # configuration data, and provide default values in
+        # case any are missing.
+        port      = ifconf["port"] if "port" in ifconf else None
+        speed     = int(ifconf["speed"]) if "speed" in ifconf else 9600
+        databits  = int(ifconf["databits"]) if "databits" in ifconf else 8
+        parity    = ifconf["parity"] if "parity" in ifconf else "N"
+        stopbits  = int(ifconf["stopbits"]) if "stopbits" in ifconf else 1
+
+        # In case no port is specified, we abort setup by
+        # raising an exception.
+        if port == None:
+            raise ValueError(f"No port specified for {self}")
+
+        # All interfaces must supply a hardware MTU value
+        # to the RNS Transport instance. This value should
+        # be the maximum data packet payload size that the
+        # underlying medium is capable of handling in all
+        # cases without any segmentation.
+        self.HW_MTU = 564
+
+        # We initially set the "online" property to false,
+        # since the interface has not actually been fully
+        # initialised and connected yet.
+        self.online   = False
+
+        # In this case, we can also set the indicated bit-
+        # rate of the interface to the serial port speed.
+        self.bitrate  = speed
+        
+        # Configure internal properties on the interface
+        # according to the supplied configuration.
+        self.pyserial = serial
+        self.serial   = None
+        self.owner    = owner
+        self.port     = port
+        self.speed    = speed
+        self.databits = databits
+        self.parity   = serial.PARITY_NONE
+        self.stopbits = stopbits
+        self.timeout  = 100
+
+        if parity.lower() == "e" or parity.lower() == "even":
+            self.parity = serial.PARITY_EVEN
+
+        if parity.lower() == "o" or parity.lower() == "odd":
+            self.parity = serial.PARITY_ODD
+
+        # Since all required parameters are now configured,
+        # we will try opening the serial port.
+        try:
+            self.open_port()
+        except Exception as e:
+            RNS.log("Could not open serial port for interface "+str(self), RNS.LOG_ERROR)
+            raise e
+
+        # If opening the port succeeded, run any post-open
+        # configuration required.
+        if self.serial.is_open:
+            self.configure_device()
+        else:
+            raise IOError("Could not open serial port")
+
+    # Open the serial port with supplied configuration
+    # parameters and store a reference to the open port.
+    def open_port(self):
+        RNS.log("Opening serial port "+self.port+"...", RNS.LOG_VERBOSE)
+        self.serial = self.pyserial.Serial(
+            port = self.port,
+            baudrate = self.speed,
+            bytesize = self.databits,
+            parity = self.parity,
+            stopbits = self.stopbits,
+            xonxoff = False,
+            rtscts = False,
+            timeout = 0,
+            inter_byte_timeout = None,
+            write_timeout = None,
+            dsrdtr = False,
+        )
+
+    # The only thing required after opening the port
+    # is to wait a small amount of time for the
+    # hardware to initialise and then start a thread
+    # that reads any incoming data from the device.
+    def configure_device(self):
+        sleep(0.5)
+        thread = threading.Thread(target=self.read_loop)
+        thread.daemon = True
+        thread.start()
+        self.online = True
+        RNS.log("Serial port "+self.port+" is now open", RNS.LOG_VERBOSE)
+
+
+    # This method will be called from our read-loop
+    # whenever a full packet has been received over
+    # the underlying medium.
+    def process_incoming(self, data):
+        # Update our received bytes counter
+        self.rxb += len(data)            
+
+        # And send the data packet to the Transport
+        # instance for processing.
+        self.owner.inbound(data, self)
+
+    # The running Reticulum Transport instance will
+    # call this method on the interface whenever the
+    # interface must transmit a packet.
+    def process_outgoing(self,data):
+        if self.online:
+            # First, escape and packetize the data
+            # according to HDLC framing.
+            data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
+
+            # Then write the framed data to the port
+            written = self.serial.write(data)
+
+            # Update the transmitted bytes counter
+            # and ensure that all data was written
+            self.txb += len(data)            
+            if written != len(data):
+                raise IOError("Serial interface only wrote "+str(written)+" bytes of "+str(len(data)))
+
+    # This read loop runs in a thread and continously
+    # receives bytes from the underlying serial port.
+    # When a full packet has been received, it will
+    # be sent to the process_incoming methed, which
+    # will in turn pass it to the Transport instance.
+    def read_loop(self):
+        try:
+            in_frame = False
+            escape = False
+            data_buffer = b""
+            last_read_ms = int(time.time()*1000)
+
+            while self.serial.is_open:
+                if self.serial.in_waiting:
+                    byte = ord(self.serial.read(1))
+                    last_read_ms = int(time.time()*1000)
+
+                    if (in_frame and byte == HDLC.FLAG):
+                        in_frame = False
+                        self.process_incoming(data_buffer)
+                    elif (byte == HDLC.FLAG):
+                        in_frame = True
+                        data_buffer = b""
+                    elif (in_frame and len(data_buffer) < self.HW_MTU):
+                        if (byte == HDLC.ESC):
+                            escape = True
+                        else:
+                            if (escape):
+                                if (byte == HDLC.FLAG ^ HDLC.ESC_MASK):
+                                    byte = HDLC.FLAG
+                                if (byte == HDLC.ESC  ^ HDLC.ESC_MASK):
+                                    byte = HDLC.ESC
+                                escape = False
+                            data_buffer = data_buffer+bytes([byte])
+                        
+                else:
+                    time_since_last = int(time.time()*1000) - last_read_ms
+                    if len(data_buffer) > 0 and time_since_last > self.timeout:
+                        data_buffer = b""
+                        in_frame = False
+                        escape = False
+                    sleep(0.08)
+                    
+        except Exception as e:
+            self.online = False
+            RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
+            RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is now offline.", RNS.LOG_ERROR)
+            
+            if RNS.Reticulum.panic_on_interface_error:
+                RNS.panic()
+
+            RNS.log("Reticulum will attempt to reconnect the interface periodically.", RNS.LOG_ERROR)
+
+        self.online = False
+        self.serial.close()
+        self.reconnect_port()
+
+    # This method handles serial port disconnects.
+    def reconnect_port(self):
+        while not self.online:
+            try:
+                time.sleep(5)
+                RNS.log("Attempting to reconnect serial port "+str(self.port)+" for "+str(self)+"...", RNS.LOG_VERBOSE)
+                self.open_port()
+                if self.serial.is_open:
+                    self.configure_device()
+            except Exception as e:
+                RNS.log("Error while reconnecting port, the contained exception was: "+str(e), RNS.LOG_ERROR)
+
+        RNS.log("Reconnected serial port for "+str(self))
+
+    # Signal to Reticulum that this interface should
+    # not perform any ingress limiting.
+    def should_ingress_limit(self):
+        return False
+
+    # We must provide a string representation of this
+    # interface, that is used whenever the interface
+    # is printed in logs or external programs.
+    def __str__(self):
+        return "ExampleInterface["+self.name+"]"
+
+# Finally, register the defined interface class as the
+# target class for Reticulum to use as an interface
+interface_class = ExampleInterface

README.md

@@ -1,4 +1,4 @@
-Reticulum Network Stack β <img align="right" src="https://static.pepy.tech/personalized-badge/rns?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Installs" style="padding-left:10px"/><a href="https://github.com/markqvist/reticulum/actions/workflows/python-app.yml"><img align="right" src="https://github.com/markqvist/reticulum/actions/workflows/python-app.yml/badge.svg"/></a>
+Reticulum Network Stack β <img align="right" src="https://static.pepy.tech/personalized-badge/rns?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Installs" style="padding-left:10px"/><a href="https://github.com/markqvist/Reticulum/actions/workflows/build.yml"><img align="right" src="https://github.com/markqvist/Reticulum/actions/workflows/build.yml/badge.svg"/></a>
 ==========
 
 <p align="center"><img width="200" src="https://raw.githubusercontent.com/markqvist/Reticulum/master/docs/source/graphics/rns_logo_512.png"></p>
@@ -42,6 +42,9 @@ For more info, see [reticulum.network](https://reticulum.network/) and [the FAQ
 ## Notable Features
 - Coordination-less globally unique addressing and identification
 - Fully self-configuring multi-hop routing over heterogeneous carriers
+- Flexible scalability over heterogeneous topologies
+  - Reticulum can carry data over any mixture of physical mediums and topologies
+  - Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks
 - Initiator anonymity, communicate without revealing your identity
   - Reticulum does not include source addresses on any packets
 - Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
@@ -53,8 +56,14 @@ For more info, see [reticulum.network](https://reticulum.network/) and [the FAQ
   - HMAC using SHA256 for authentication
   - IVs are generated through os.urandom()
 - Unforgeable packet delivery confirmations
-- A large variety of supported interface types
+- Flexible and extensible interface system
+  - Reticulum includes a large variety of built-in interface types
+  - Ability to load and utilise custom user- or community-supplied interface types
+  - Easily create your own custom interfaces for communicating over anything
+- Authentication and virtual network segmentation on all supported interface types
 - An intuitive and easy-to-use API
+  - Simpler and easier to use than sockets APIs and simpler, but more powerful
+  - Makes building distributed and decentralised applications much simpler
 - Reliable and efficient transfer of arbitrary amounts of data
   - Reticulum can handle a few bytes of data or files of many gigabytes
   - Sequencing, compression, transfer coordination and checksumming are automatic
@@ -172,11 +181,12 @@ program.
 
 Reticulum implements a range of generalised interface types that covers most of
 the communications hardware that Reticulum can run over. If your hardware is
-not supported, it's relatively simple to implement an interface class. I will
-gratefully accept pull requests for custom interfaces if they are generally
-useful.
+not supported, it's [simple to implement a custom interface module](https://markqvist.github.io/Reticulum/manual/interfaces.html#custom-interfaces).
 
-Currently, the following interfaces are supported:
+Pull requests for custom interfaces are gratefully accepted, provided they are
+generally useful and well-tested in real-world usage.
+
+Currently, the following built-in interfaces are supported:
 
 - Any Ethernet device
 - LoRa using [RNode](https://unsigned.io/rnode/)
@@ -322,12 +332,12 @@ In the default installation configuration, the `X25519`, `Ed25519` and
 (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
+`HMAC`, `Token` primitives, and the `PKCS7` padding function are always
 provided by the following internal implementations:
 
 - [HKDF.py](RNS/Cryptography/HKDF.py)
 - [HMAC.py](RNS/Cryptography/HMAC.py)
-- [Fernet.py](RNS/Cryptography/Fernet.py)
+- [Token.py](RNS/Cryptography/Token.py)
 - [PKCS7.py](RNS/Cryptography/PKCS7.py)
 
 

RNS/Cryptography/Token.py

@@ -27,7 +27,7 @@ from RNS.Cryptography import HMAC
 from RNS.Cryptography import PKCS7
 from RNS.Cryptography.AES import AES_128_CBC
 
-class Fernet():
+class Token():
     """
     This class provides a slightly modified implementation of the Fernet spec
     found at: https://github.com/fernet/spec/blob/master/Spec.md
@@ -37,7 +37,7 @@ class Fernet():
     not relevant to Reticulum. They are therefore stripped from this
     implementation, since they incur overhead and leak initiator metadata.
     """
-    FERNET_OVERHEAD  = 48 # Bytes
+    TOKEN_OVERHEAD  = 48 # Bytes
 
     @staticmethod
     def generate_key():

RNS/Cryptography/__init__.py

@@ -5,7 +5,7 @@ from .Hashes import sha256
 from .Hashes import sha512
 from .HKDF import hkdf
 from .PKCS7 import PKCS7
-from .Fernet import Fernet
+from .Token import Token
 from .Provider import backend
 
 import RNS.Cryptography.Provider as cp
@@ -20,5 +20,7 @@ elif cp.PROVIDER == cp.PROVIDER_PYCA:
     from RNS.Cryptography.Proxies import Ed25519PrivateKeyProxy as Ed25519PrivateKey
     from RNS.Cryptography.Proxies import Ed25519PublicKeyProxy as Ed25519PublicKey
 
-modules = glob.glob(os.path.dirname(__file__)+"/*.py")
-__all__ = [ os.path.basename(f)[:-3] for f in modules if not f.endswith('__init__.py')]
+py_modules  = glob.glob(os.path.dirname(__file__)+"/*.py")
+pyc_modules = glob.glob(os.path.dirname(__file__)+"/*.pyc")
+modules     = py_modules+pyc_modules
+__all__ = list(set([os.path.basename(f).replace(".pyc", "").replace(".py", "") for f in modules if not (f.endswith("__init__.py") or f.endswith("__init__.pyc"))]))

RNS/Destination.py

@@ -26,7 +26,7 @@ import time
 import threading
 import RNS
 
-from RNS.Cryptography import Fernet
+from RNS.Cryptography import Token
 from .vendor import umsgpack as umsgpack
 
 class Callbacks:
@@ -525,8 +525,8 @@ class Destination:
             raise TypeError("A single destination holds keys through an Identity instance")
 
         if self.type == Destination.GROUP:
-            self.prv_bytes = Fernet.generate_key()
-            self.prv = Fernet(self.prv_bytes)
+            self.prv_bytes = Token.generate_key()
+            self.prv = Token(self.prv_bytes)
 
     def get_private_key(self):
         """
@@ -556,7 +556,7 @@ class Destination:
 
         if self.type == Destination.GROUP:
             self.prv_bytes = key
-            self.prv = Fernet(self.prv_bytes)
+            self.prv = Token(self.prv_bytes)
 
     def load_public_key(self, key):
         if self.type != Destination.SINGLE:

RNS/Identity.py

@@ -31,7 +31,7 @@ import threading
 from .vendor import umsgpack as umsgpack
 
 from RNS.Cryptography import X25519PrivateKey, X25519PublicKey, Ed25519PrivateKey, Ed25519PublicKey
-from RNS.Cryptography import Fernet
+from RNS.Cryptography import Token
 
 
 class Identity:
@@ -66,7 +66,7 @@ class Identity:
     """
 
     # Non-configurable constants
-    FERNET_OVERHEAD           = RNS.Cryptography.Fernet.FERNET_OVERHEAD
+    TOKEN_OVERHEAD            = RNS.Cryptography.Token.TOKEN_OVERHEAD
     AES128_BLOCKSIZE          = 16          # In bytes
     HASHLENGTH                = 256         # In bits
     SIGLENGTH                 = KEYSIZE     # In bits
@@ -646,8 +646,8 @@ class Identity:
                 context=self.get_context(),
             )
 
-            fernet = Fernet(derived_key)
-            ciphertext = fernet.encrypt(plaintext)
+            token = Token(derived_key)
+            ciphertext = token.encrypt(plaintext)
             token = ephemeral_pub_bytes+ciphertext
 
             return token
@@ -684,8 +684,8 @@ class Identity:
                                     context=self.get_context(),
                                 )
 
-                                fernet = Fernet(derived_key)
-                                plaintext = fernet.decrypt(ciphertext)
+                                token = Token(derived_key)
+                                plaintext = token.decrypt(ciphertext)
                                 if ratchet_id_receiver:
                                     ratchet_id_receiver.latest_ratchet_id = ratchet_id
                                 
@@ -709,8 +709,8 @@ class Identity:
                             context=self.get_context(),
                         )
 
-                        fernet = Fernet(derived_key)
-                        plaintext = fernet.decrypt(ciphertext)
+                        token = Token(derived_key)
+                        plaintext = token.decrypt(ciphertext)
                         if ratchet_id_receiver:
                             ratchet_id_receiver.latest_ratchet_id = None
 

RNS/Interfaces/AX25KISSInterface.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 from time import sleep
 import sys
 import threading
@@ -59,6 +59,7 @@ class AX25():
 class AX25KISSInterface(Interface):
     MAX_CHUNK = 32768
     BITRATE_GUESS = 1200
+    DEFAULT_IFAC_SIZE = 8
 
     owner    = None
     port     = None
@@ -68,7 +69,7 @@ class AX25KISSInterface(Interface):
     stopbits = None
     serial   = None
 
-    def __init__(self, owner, name, callsign, ssid, port, speed, databits, parity, stopbits, preamble, txtail, persistence, slottime, flow_control):
+    def __init__(self, owner, configuration):
         import importlib
         if importlib.util.find_spec('serial') != None:
             import serial
@@ -79,6 +80,25 @@ class AX25KISSInterface(Interface):
 
         super().__init__()
 
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+        preamble = int(c["preamble"]) if "preamble" in c else None
+        txtail = int(c["txtail"]) if "txtail" in c else None
+        persistence = int(c["persistence"]) if "persistence" in c else None
+        slottime = int(c["slottime"]) if "slottime" in c else None
+        flow_control = c.as_bool("flow_control") if "flow_control" in c else False
+        port = c["port"] if "port" in c else None
+        speed = int(c["speed"]) if "speed" in c else 9600
+        databits = int(c["databits"]) if "databits" in c else 8
+        parity = c["parity"] if "parity" in c else "N"
+        stopbits = int(c["stopbits"]) if "stopbits" in c else 1
+
+        callsign = c["callsign"] if "callsign" in c else ""
+        ssid = int(c["ssid"]) if "ssid" in c else -1
+
+        if port == None:
+            raise ValueError("No port specified for serial interface")
+
         self.HW_MTU = 564
         
         self.pyserial = serial
@@ -225,13 +245,13 @@ class AX25KISSInterface(Interface):
                 raise IOError("Could not enable AX.25 KISS interface flow control")
 
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         if (len(data) > AX25.HEADER_SIZE):
             self.rxb += len(data)
             self.owner.inbound(data[AX25.HEADER_SIZE:], self)
 
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         datalen = len(data)
         if self.online:
             if self.interface_ready:
@@ -281,7 +301,7 @@ class AX25KISSInterface(Interface):
         if len(self.packet_queue) > 0:
             data = self.packet_queue.pop(0)
             self.interface_ready = True
-            self.processOutgoing(data)
+            self.process_outgoing(data)
         elif len(self.packet_queue) == 0:
             self.interface_ready = True
 
@@ -300,7 +320,7 @@ class AX25KISSInterface(Interface):
 
                     if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
                         in_frame = False
-                        self.processIncoming(data_buffer)
+                        self.process_incoming(data_buffer)
                     elif (byte == KISS.FEND):
                         in_frame = True
                         command = KISS.CMD_UNKNOWN

RNS/Interfaces/Android/KISSInterface.py

@@ -52,6 +52,7 @@ class KISS():
 class KISSInterface(Interface):
     MAX_CHUNK = 32768
     BITRATE_GUESS = 1200
+    DEFAULT_IFAC_SIZE = 8
 
     owner    = None
     port     = None
@@ -61,7 +62,7 @@ class KISSInterface(Interface):
     stopbits = None
     serial   = None
 
-    def __init__(self, owner, name, port, speed, databits, parity, stopbits, preamble, txtail, persistence, slottime, flow_control, beacon_interval, beacon_data):
+    def __init__(self, owner, configuration):
         import importlib
         if RNS.vendor.platformutils.is_android():
             self.on_android  = True
@@ -83,6 +84,21 @@ class KISSInterface(Interface):
             raise SystemError("Android-specific interface was used on non-Android OS")
 
         super().__init__()
+
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+        preamble = int(c["preamble"]) if "preamble" in c else None
+        txtail = int(c["txtail"]) if "txtail" in c else None
+        persistence = int(c["persistence"]) if "persistence" in c else None
+        slottime = int(c["slottime"]) if "slottime" in c else None
+        flow_control = c.as_bool("flow_control") if "flow_control" in c else False
+        port = c["port"] if "port" in c else None
+        speed = int(c["speed"]) if "speed" in c else 9600
+        databits = int(c["databits"]) if "databits" in c else 8
+        parity = c["parity"] if "parity" in c else "N"
+        stopbits = int(c["stopbits"]) if "stopbits" in c else 1
+        beacon_interval = int(c["beacon_interval"]) if "beacon_interval" in c and c["beacon_interval"] != None else None
+        beacon_data = c["beacon_data"] if "beacon_data" in c else None
         
         self.HW_MTU = 564
         
@@ -267,13 +283,13 @@ class KISSInterface(Interface):
                 raise IOError("Could not enable KISS interface flow control")
 
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)
         def af():
             self.owner.inbound(data, self)
         threading.Thread(target=af, daemon=True).start()
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         datalen = len(data)
         if self.online:
             if self.interface_ready:
@@ -307,7 +323,7 @@ class KISSInterface(Interface):
         if len(self.packet_queue) > 0:
             data = self.packet_queue.pop(0)
             self.interface_ready = True
-            self.processOutgoing(data)
+            self.process_outgoing(data)
         elif len(self.packet_queue) == 0:
             self.interface_ready = True
 
@@ -328,7 +344,7 @@ class KISSInterface(Interface):
 
                     if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
                         in_frame = False
-                        self.processIncoming(data_buffer)
+                        self.process_incoming(data_buffer)
                     elif (byte == KISS.FEND):
                         in_frame = True
                         command = KISS.CMD_UNKNOWN
@@ -373,7 +389,13 @@ class KISSInterface(Interface):
                             if time.time() > self.first_tx + self.beacon_i:
                                 RNS.log("Interface "+str(self)+" is transmitting beacon data: "+str(self.beacon_d.decode("utf-8")), RNS.LOG_DEBUG)
                                 self.first_tx = None
-                                self.processOutgoing(self.beacon_d)
+
+                                # Pad to minimum length
+                                frame = bytearray(self.beacon_d)
+                                while len(frame) < 15:
+                                    frame.append(0x00)
+
+                                self.process_outgoing(bytes(frame))
 
         except Exception as e:
             self.online = False

RNS/Interfaces/Android/RNodeInterface.py

@@ -68,6 +68,7 @@ class KISS():
     CMD_RANDOM      = 0x40
     CMD_FB_EXT      = 0x41
     CMD_FB_READ     = 0x42
+    CMD_DISP_READ   = 0x66
     CMD_FB_WRITE    = 0x43
     CMD_BT_CTRL     = 0x46
     CMD_PLATFORM    = 0x48
@@ -238,6 +239,7 @@ class AndroidBluetoothManager():
 
 class RNodeInterface(Interface):
     MAX_CHUNK = 32768
+    DEFAULT_IFAC_SIZE = 8
 
     FREQ_MIN = 137000000
     FREQ_MAX = 1020000000
@@ -261,6 +263,8 @@ class RNodeInterface(Interface):
     BATTERY_STATE_CHARGING    = 0x02
     BATTERY_STATE_CHARGED     = 0x03
 
+    DISPLAY_READ_INTERVAL     = 1.0
+
     @classmethod
     def bluetooth_control(device_serial = None, port = None, enable_bluetooth = False, disable_bluetooth = False, pairing_mode = False):
         if (port != None or device_serial != None) and (enable_bluetooth or disable_bluetooth or pairing_mode):
@@ -341,12 +345,27 @@ class RNodeInterface(Interface):
                 serial.close()
 
 
-    def __init__(
-        self, owner, name, port, frequency = None, bandwidth = None, txpower = None,
-        sf = None, cr = None, flow_control = False, id_interval = None,
-        allow_bluetooth = False, target_device_name = None,
-        target_device_address = None, id_callsign = None, st_alock = None, lt_alock = None,
-        ble_addr = None, ble_name = None, force_ble=False):
+    def __init__(self, owner, configuration):
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+        allow_bluetooth = c.as_bool("allow_bluetooth") if "allow_bluetooth" in c else False
+        target_device_name = c["target_device_name"] if "target_device_name" in c else None
+        target_device_address = c["target_device_address"] if "target_device_address" in c else None
+        ble_name = c["ble_name"] if "ble_name" in c else None
+        ble_addr = c["ble_addr"] if "ble_addr" in c else None
+        force_ble = c["force_ble"] if "force_ble" in c else False
+        frequency = int(c["frequency"]) if "frequency" in c else 0
+        bandwidth = int(c["bandwidth"]) if "bandwidth" in c else 0
+        txpower = int(c["txpower"]) if "txpower" in c else 0
+        sf = int(c["spreadingfactor"]) if "spreadingfactor" in c else 0
+        cr = int(c["codingrate"]) if "codingrate" in c else 0
+        flow_control = c.as_bool("flow_control") if "flow_control" in c else False
+        id_interval = int(c["id_interval"]) if "id_interval" in c and c["id_interval"] != None else None
+        id_callsign = c["id_callsign"] if "id_callsign" in c else None
+        st_alock = float(c["airtime_limit_short"]) if "airtime_limit_short" in c and c["airtime_limit_short"] != None else None
+        lt_alock = float(c["airtime_limit_long"]) if "airtime_limit_long" in c and c["airtime_limit_long"] != None else None
+        port = c["port"] if "port" in c else None
+
         import importlib
         if RNS.vendor.platformutils.is_android():
             self.on_android  = True
@@ -452,6 +471,15 @@ class RNodeInterface(Interface):
         self.r_premable_time_ms = None
         self.r_battery_state = RNodeInterface.BATTERY_STATE_UNKNOWN
         self.r_battery_percent = 0
+        self.r_framebuffer = b""
+        self.r_framebuffer_readtime = 0
+        self.r_framebuffer_latency = 0
+        self.r_disp = b""
+        self.r_disp_readtime = 0
+        self.r_disp_latency = 0
+
+        self.should_read_display = False
+        self.read_display_interval = RNodeInterface.DISPLAY_READ_INTERVAL
 
         self.packet_queue    = []
         self.flow_control    = flow_control
@@ -793,6 +821,33 @@ class RNodeInterface(Interface):
             if written != len(kiss_command):
                 raise IOError("An IO error occurred while writing framebuffer data device")
 
+    def read_framebuffer(self):
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_FB_READ])+bytes([0x01])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        self.r_framebuffer_readtime = time.time()
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while sending framebuffer read command")
+
+    def read_display(self):
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_DISP_READ])+bytes([0x01])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        self.r_disp_readtime = time.time()
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while sending display read command")
+
+    def _read_display_job(self):
+        while self.should_read_display:
+            self.read_display()
+            time.sleep(self.read_display_interval)
+
+    def start_display_updates(self):
+        if not self.should_read_display:
+            self.should_read_display = True
+            threading.Thread(target=self._read_display_job, daemon=True).start()
+
+    def stop_display_updates(self):
+        self.should_read_display = False
+
     def hard_reset(self):
         kiss_command = bytes([KISS.FEND, KISS.CMD_RESET, 0xf8, KISS.FEND])
         written = self.write_mux(kiss_command)
@@ -941,7 +996,7 @@ class RNodeInterface(Interface):
         except:
             self.bitrate = 0
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)
 
         def af():
@@ -949,7 +1004,7 @@ class RNodeInterface(Interface):
         threading.Thread(target=af, daemon=True).start()
 
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         datalen = len(data)
         if self.online:
             if self.interface_ready:
@@ -980,7 +1035,7 @@ class RNodeInterface(Interface):
         if len(self.packet_queue) > 0:
             data = self.packet_queue.pop(0)
             self.interface_ready = True
-            self.processOutgoing(data)
+            self.process_outgoing(data)
         elif len(self.packet_queue) == 0:
             self.interface_ready = True
 
@@ -1007,7 +1062,7 @@ class RNodeInterface(Interface):
 
                     if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
                         in_frame = False
-                        self.processIncoming(data_buffer)
+                        self.process_incoming(data_buffer)
                         data_buffer = b""
                         command_buffer = b""
                     elif (byte == KISS.FEND):
@@ -1269,6 +1324,37 @@ class RNodeInterface(Interface):
                                         raise IOError("ESP32 reset")
                         elif (command == KISS.CMD_READY):
                             self.process_queue()
+                        
+                        elif (command == KISS.CMD_FB_READ):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                command_buffer = command_buffer+bytes([byte])
+                                if (len(command_buffer) == 512):
+                                    self.r_framebuffer_latency = time.time() - self.r_framebuffer_readtime
+                                    self.r_framebuffer = command_buffer
+
+                        elif (command == KISS.CMD_DISP_READ):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                command_buffer = command_buffer+bytes([byte])
+                                if (len(command_buffer) == 1024):
+                                    self.r_disp_latency = time.time() - self.r_disp_readtime
+                                    self.r_disp = command_buffer
+                        
                         elif (command == KISS.CMD_DETECT):
                             if byte == KISS.DETECT_RESP:
                                 self.detected = True
@@ -1288,7 +1374,7 @@ class RNodeInterface(Interface):
                         if self.first_tx != None:
                             if time.time() > self.first_tx + self.id_interval:
                                 RNS.log("Interface "+str(self)+" is transmitting beacon data: "+str(self.id_callsign.decode("utf-8")), RNS.LOG_DEBUG)
-                                self.processOutgoing(self.id_callsign)
+                                self.process_outgoing(self.id_callsign)
                     
                     if (time.time() - self.last_port_io > self.port_io_timeout):
                         self.detect()

RNS/Interfaces/Android/SerialInterface.py

@@ -42,6 +42,7 @@ class HDLC():
 
 class SerialInterface(Interface):
     MAX_CHUNK = 32768
+    DEFAULT_IFAC_SIZE = 8
 
     owner    = None
     port     = None
@@ -51,7 +52,7 @@ class SerialInterface(Interface):
     stopbits = None
     serial   = None
 
-    def __init__(self, owner, name, port, speed, databits, parity, stopbits):
+    def __init__(self, owner, configuration):
         import importlib
         if RNS.vendor.platformutils.is_android():
             self.on_android  = True
@@ -74,6 +75,17 @@ class SerialInterface(Interface):
 
         super().__init__()
 
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+        port = c["port"] if "port" in c else None
+        speed = int(c["speed"]) if "speed" in c else 9600
+        databits = int(c["databits"]) if "databits" in c else 8
+        parity = c["parity"] if "parity" in c else "N"
+        stopbits = int(c["stopbits"]) if "stopbits" in c else 1
+
+        if port == None:
+            raise ValueError("No port specified for serial interface")
+
         self.HW_MTU = 564
         
         self.pyserial = serial
@@ -172,13 +184,13 @@ class SerialInterface(Interface):
         RNS.log("Serial port "+self.port+" is now open", RNS.LOG_VERBOSE)
 
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)
         def af():
             self.owner.inbound(data, self)
         threading.Thread(target=af, daemon=True).start()
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         if self.online:
             data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
             written = self.serial.write(data)
@@ -202,7 +214,7 @@ class SerialInterface(Interface):
 
                     if (in_frame and byte == HDLC.FLAG):
                         in_frame = False
-                        self.processIncoming(data_buffer)
+                        self.process_incoming(data_buffer)
                     elif (byte == HDLC.FLAG):
                         in_frame = True
                         data_buffer = b""

RNS/Interfaces/Android/__init__.py

@@ -23,5 +23,7 @@
 import os
 import glob
 
-modules = glob.glob(os.path.dirname(__file__)+"/*.py")
-__all__ = [ os.path.basename(f)[:-3] for f in modules if not f.endswith('__init__.py')]
+py_modules  = glob.glob(os.path.dirname(__file__)+"/*.py")
+pyc_modules = glob.glob(os.path.dirname(__file__)+"/*.pyc")
+modules     = py_modules+pyc_modules
+__all__ = list(set([os.path.basename(f).replace(".pyc", "").replace(".py", "") for f in modules if not (f.endswith("__init__.py") or f.endswith("__init__.pyc"))]))

RNS/Interfaces/AutoInterface.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2024 Mark Qvist / unsigned.io
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 from collections import deque
 import socketserver
 import threading
@@ -36,6 +36,7 @@ class AutoInterface(Interface):
     DEFAULT_DISCOVERY_PORT = 29716
     DEFAULT_DATA_PORT      = 42671
     DEFAULT_GROUP_ID       = "reticulum".encode("utf-8")
+    DEFAULT_IFAC_SIZE      = 16
 
     SCOPE_LINK         = "2"
     SCOPE_ADMIN        = "4"
@@ -86,7 +87,18 @@ class AutoInterface(Interface):
 
         return socket.if_nametoindex(ifname)
 
-    def __init__(self, owner, name, group_id=None, discovery_scope=None, discovery_port=None, multicast_address_type=None, data_port=None, allowed_interfaces=None, ignored_interfaces=None, configured_bitrate=None):
+    def __init__(self, owner, configuration):
+        c                      = Interface.get_config_obj(configuration)
+        name                   = c["name"]
+        group_id               = c["group_id"] if "group_id" in c else None
+        discovery_scope        = c["discovery_scope"] if "discovery_scope" in c else None
+        discovery_port         = int(c["discovery_port"]) if "discovery_port" in c else None
+        multicast_address_type = c["multicast_address_type"] if "multicast_address_type" in c else None
+        data_port              = int(c["data_port"]) if "data_port" in c else None
+        allowed_interfaces     = c.as_list("devices") if "devices" in c else None
+        ignored_interfaces     = c.as_list("ignored_devices") if "ignored_devices" in c else None
+        configured_bitrate     = c["configured_bitrate"] if "configured_bitrate" in c else None
+
         from RNS.vendor.ifaddr import niwrapper
         super().__init__()
         self.netinfo = niwrapper
@@ -287,7 +299,7 @@ class AutoInterface(Interface):
                 addr_info = socket.getaddrinfo(local_addr, self.data_port, socket.AF_INET6, socket.SOCK_DGRAM)
                 address = addr_info[0][4]
 
-                udp_server = socketserver.UDPServer(address, self.handler_factory(self.processIncoming))
+                udp_server = socketserver.UDPServer(address, self.handler_factory(self.process_incoming))
                 self.interface_servers[ifname] = udp_server
                 
                 thread = threading.Thread(target=udp_server.serve_forever)
@@ -369,7 +381,7 @@ class AutoInterface(Interface):
 
                                         RNS.log("Starting new UDP listener for "+str(self)+" "+str(ifname), RNS.LOG_DEBUG)
 
-                                        udp_server = socketserver.UDPServer(listen_address, self.handler_factory(self.processIncoming))
+                                        udp_server = socketserver.UDPServer(listen_address, self.handler_factory(self.process_incoming))
                                         self.interface_servers[ifname] = udp_server
 
                                         thread = threading.Thread(target=udp_server.serve_forever)
@@ -443,7 +455,7 @@ class AutoInterface(Interface):
     def refresh_peer(self, addr):
         self.peers[addr][1] = time.time()
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         data_hash = RNS.Identity.full_hash(data)
         deque_hit = False
         if data_hash in self.mif_deque:
@@ -458,7 +470,7 @@ class AutoInterface(Interface):
             self.rxb += len(data)
             self.owner.inbound(data, self)
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
             for peer in self.peers:
                 try:
                     if self.outbound_udp_socket == None:

RNS/Interfaces/I2PInterface.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2024 Mark Qvist / unsigned.io
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 import socketserver
 import threading
 import platform
@@ -627,14 +627,14 @@ class I2PInterfacePeer(Interface):
             RNS.log("Attempt to reconnect on a non-initiator I2P interface. This should not happen.", RNS.LOG_ERROR)
             raise IOError("Attempt to reconnect on a non-initiator I2P interface")
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)
         if hasattr(self, "parent_interface") and self.parent_interface != None and self.parent_count:
             self.parent_interface.rxb += len(data)
                     
         self.owner.inbound(data, self)
 
-    def processOutgoing(self, data):
+    def process_outgoing(self, data):
         if self.online:
             while self.writing:
                 time.sleep(0.001)
@@ -732,7 +732,7 @@ class I2PInterfacePeer(Interface):
                             # Read loop for KISS framing
                             if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
                                 in_frame = False
-                                self.processIncoming(data_buffer)
+                                self.process_incoming(data_buffer)
                             elif (byte == KISS.FEND):
                                 in_frame = True
                                 command = KISS.CMD_UNKNOWN
@@ -759,7 +759,7 @@ class I2PInterfacePeer(Interface):
                             # Read loop for HDLC framing
                             if (in_frame and byte == HDLC.FLAG):
                                 in_frame = False
-                                self.processIncoming(data_buffer)
+                                self.process_incoming(data_buffer)
                             elif (byte == HDLC.FLAG):
                                 in_frame = True
                                 data_buffer = b""
@@ -815,8 +815,8 @@ class I2PInterfacePeer(Interface):
         self.IN = False
 
         if hasattr(self, "parent_interface") and self.parent_interface != None:
-            if self.parent_interface.clients > 0:
-                self.parent_interface.clients -= 1
+            while self in self.parent_interface.spawned_interfaces:
+                self.parent_interface.spawned_interfaces.remove(self)
 
         if self in RNS.Transport.interfaces:
             if not self.initiator:
@@ -829,14 +829,28 @@ class I2PInterfacePeer(Interface):
 
 class I2PInterface(Interface):
     BITRATE_GUESS      = 256*1000
+    DEFAULT_IFAC_SIZE  = 16
 
-    def __init__(self, owner, name, rns_storagepath, peers, connectable = False, ifac_size = 16, ifac_netname = None, ifac_netkey = None):
+    @property
+    def clients(self):
+        return len(self.spawned_interfaces)
+
+    def __init__(self, owner, configuration):
         super().__init__()
+
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+        rns_storagepath = c["storagepath"]
+        peers = c.as_list("peers") if "peers" in c else None
+        connectable = c.as_bool("connectable") if "connectable" in c else False
+        ifac_size = c["ifac_size"] if "ifac_size" in c else None
+        ifac_netname = c["ifac_netname"] if "ifac_netname" in c else None
+        ifac_netkey = c["ifac_netkey"] if "ifac_netkey" in c else None
         
         self.HW_MTU = 1064
 
         self.online = False
-        self.clients = 0
+        self.spawned_interfaces = []
         self.owner = owner
         self.connectable = connectable
         self.i2p_tunneled = True
@@ -956,10 +970,12 @@ class I2PInterface(Interface):
         spawned_interface.HW_MTU = self.HW_MTU
         RNS.log("Spawned new I2PInterface Peer: "+str(spawned_interface), RNS.LOG_VERBOSE)
         RNS.Transport.interfaces.append(spawned_interface)
-        self.clients += 1
+        while spawned_interface in self.spawned_interfaces:
+            self.spawned_interfaces.remove(spawned_interface)
+        self.spawned_interfaces.append(spawned_interface)
         spawned_interface.read_loop()
 
-    def processOutgoing(self, data):
+    def process_outgoing(self, data):
         pass
 
     def received_announce(self, from_spawned=False):

RNS/Interfaces/Interface.py

@@ -24,6 +24,7 @@ import RNS
 import time
 import threading
 from collections import deque
+from RNS.vendor.configobj import ConfigObj
 
 class Interface:
     IN  = False
@@ -222,7 +223,7 @@ class Interface:
                     wait_time = (tx_time / self.announce_cap)
                     self.announce_allowed_at = now + wait_time
 
-                    self.processOutgoing(selected["raw"])
+                    self.process_outgoing(selected["raw"])
                     self.sent_announce()
 
                     if selected in self.announce_queue:
@@ -238,4 +239,15 @@ class Interface:
                 RNS.log("The announce queue for this interface has been cleared.", RNS.LOG_ERROR)
 
     def detach(self):
-        pass
+        pass
+
+    @staticmethod
+    def get_config_obj(config_in):
+        if type(config_in) == ConfigObj:
+            return config_in
+        else:
+            try:
+                return ConfigObj(config_in)
+            except Exception as e:
+                RNS.log(f"Could not parse supplied configuration data. The contained exception was: {e}", RNS.LOG_ERROR)
+                raise SystemError("Invalid configuration data supplied")

RNS/Interfaces/KISSInterface.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 from time import sleep
 import sys
 import threading
@@ -52,6 +52,7 @@ class KISS():
 class KISSInterface(Interface):
     MAX_CHUNK = 32768
     BITRATE_GUESS = 1200
+    DEFAULT_IFAC_SIZE = 8
 
     owner    = None
     port     = None
@@ -61,7 +62,7 @@ class KISSInterface(Interface):
     stopbits = None
     serial   = None
 
-    def __init__(self, owner, name, port, speed, databits, parity, stopbits, preamble, txtail, persistence, slottime, flow_control, beacon_interval, beacon_data):
+    def __init__(self, owner, configuration):
         import importlib
         if importlib.util.find_spec('serial') != None:
             import serial
@@ -71,6 +72,24 @@ class KISSInterface(Interface):
             RNS.panic()
 
         super().__init__()
+
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+        preamble = int(c["preamble"]) if "preamble" in c else None
+        txtail = int(c["txtail"]) if "txtail" in c else None
+        persistence = int(c["persistence"]) if "persistence" in c else None
+        slottime = int(c["slottime"]) if "slottime" in c else None
+        flow_control = c.as_bool("flow_control") if "flow_control" in c else False
+        port = c["port"] if "port" in c else None
+        speed = int(c["speed"]) if "speed" in c else 9600
+        databits = int(c["databits"]) if "databits" in c else 8
+        parity = c["parity"] if "parity" in c else "N"
+        stopbits = int(c["stopbits"]) if "stopbits" in c else 1
+        beacon_interval = int(c["id_interval"]) if "id_interval" in c else None
+        beacon_data = c["id_callsign"] if "id_callsign" in c else None
+
+        if port == None:
+            raise ValueError("No port specified for serial interface")
         
         self.HW_MTU = 564
         
@@ -217,12 +236,12 @@ class KISSInterface(Interface):
                 raise IOError("Could not enable KISS interface flow control")
 
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)  
         self.owner.inbound(data, self)
 
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         datalen = len(data)
         if self.online:
             if self.interface_ready:
@@ -256,7 +275,7 @@ class KISSInterface(Interface):
         if len(self.packet_queue) > 0:
             data = self.packet_queue.pop(0)
             self.interface_ready = True
-            self.processOutgoing(data)
+            self.process_outgoing(data)
         elif len(self.packet_queue) == 0:
             self.interface_ready = True
 
@@ -275,7 +294,7 @@ class KISSInterface(Interface):
 
                     if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
                         in_frame = False
-                        self.processIncoming(data_buffer)
+                        self.process_incoming(data_buffer)
                     elif (byte == KISS.FEND):
                         in_frame = True
                         command = KISS.CMD_UNKNOWN
@@ -319,7 +338,13 @@ class KISSInterface(Interface):
                             if time.time() > self.first_tx + self.beacon_i:
                                 RNS.log("Interface "+str(self)+" is transmitting beacon data: "+str(self.beacon_d.decode("utf-8")), RNS.LOG_DEBUG)
                                 self.first_tx = None
-                                self.processOutgoing(self.beacon_d)
+                                
+                                # Pad to minimum length
+                                frame = bytearray(self.beacon_d)
+                                while len(frame) < 15:
+                                    frame.append(0x00)
+                                    
+                                self.process_outgoing(bytes(frame))
 
         except Exception as e:
             self.online = False

RNS/Interfaces/LocalInterface.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 import socketserver
 import threading
 import socket
@@ -152,7 +152,7 @@ class LocalClientInterface(Interface):
             raise IOError("Attempt to reconnect on a non-initiator local interface")
 
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)
         if hasattr(self, "parent_interface") and self.parent_interface != None:
             self.parent_interface.rxb += len(data)
@@ -166,7 +166,7 @@ class LocalClientInterface(Interface):
         # duration = time.time() - processing_start
         # self.rxptime += duration
 
-    def processOutgoing(self, data):
+    def process_outgoing(self, data):
         if self.online:
             try:
                 self.writing = True
@@ -208,7 +208,7 @@ class LocalClientInterface(Interface):
                         pointer += 1
                         if (in_frame and byte == HDLC.FLAG):
                             in_frame = False
-                            self.processIncoming(data_buffer)
+                            self.process_incoming(data_buffer)
                         elif (byte == HDLC.FLAG):
                             in_frame = True
                             data_buffer = b""
@@ -350,7 +350,7 @@ class LocalServerInterface(Interface):
         self.clients += 1
         spawned_interface.read_loop()
 
-    def processOutgoing(self, data):
+    def process_outgoing(self, data):
         pass
 
     def received_announce(self, from_spawned=False):

RNS/Interfaces/PipeInterface.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 from time import sleep
 import sys
 import threading
@@ -46,16 +46,25 @@ class HDLC():
 class PipeInterface(Interface):
     MAX_CHUNK = 32768
     BITRATE_GUESS = 1*1000*1000
+    DEFAULT_IFAC_SIZE = 8
 
     owner    = None
     command  = None
     
-    def __init__(self, owner, name, command, respawn_delay):
+    def __init__(self, owner, configuration):
+        super().__init__()
+
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+        command = c["command"] if "command" in c else None
+        respawn_delay = c.as_float("respawn_delay") if "respawn_delay" in c else None
+
+        if command == None:
+            raise ValueError("No command specified for PipeInterface")
+
         if respawn_delay == None:
             respawn_delay = 5
 
-        super().__init__()
-
         self.HW_MTU = 1064
         
         self.owner    = owner
@@ -101,12 +110,12 @@ class PipeInterface(Interface):
         RNS.log("Subprocess pipe for "+str(self)+" is now connected", RNS.LOG_VERBOSE)
 
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)            
         self.owner.inbound(data, self)
 
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         if self.online:
             data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
             written = self.process.stdin.write(data)
@@ -134,7 +143,7 @@ class PipeInterface(Interface):
 
                     if (in_frame and byte == HDLC.FLAG):
                         in_frame = False
-                        self.processIncoming(data_buffer)
+                        self.process_incoming(data_buffer)
                     elif (byte == HDLC.FLAG):
                         in_frame = True
                         data_buffer = b""

RNS/Interfaces/RNodeInterface.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 from time import sleep
 import sys
 import threading
@@ -59,6 +59,7 @@ class KISS():
     CMD_RANDOM      = 0x40
     CMD_FB_EXT      = 0x41
     CMD_FB_READ     = 0x42
+    CMD_DISP_READ   = 0x66
     CMD_FB_WRITE    = 0x43
     CMD_BT_CTRL     = 0x46
     CMD_PLATFORM    = 0x48
@@ -95,6 +96,7 @@ class KISS():
 
 class RNodeInterface(Interface):
     MAX_CHUNK = 32768
+    DEFAULT_IFAC_SIZE = 8
 
     FREQ_MIN = 137000000
     FREQ_MAX = 3000000000
@@ -117,7 +119,9 @@ class RNodeInterface(Interface):
     BATTERY_STATE_CHARGING    = 0x02
     BATTERY_STATE_CHARGED     = 0x03
 
-    def __init__(self, owner, name, port, frequency = None, bandwidth = None, txpower = None, sf = None, cr = None, flow_control = False, id_interval = None, id_callsign = None, st_alock = None, lt_alock = None, ble_addr = None, ble_name = None, force_ble=False):
+    DISPLAY_READ_INTERVAL     = 1.0
+
+    def __init__(self, owner, configuration):
         if RNS.vendor.platformutils.is_android():
             raise SystemError("Invalid interface type. The Android-specific RNode interface must be used on Android")
 
@@ -131,6 +135,41 @@ class RNodeInterface(Interface):
 
         super().__init__()
 
+        c = Interface.get_config_obj(configuration)
+        name         = c["name"]
+        frequency    = int(c["frequency"]) if "frequency" in c else 0
+        bandwidth    = int(c["bandwidth"]) if "bandwidth" in c else 0
+        txpower      = int(c["txpower"]) if "txpower" in c else 0
+        sf           = int(c["spreadingfactor"]) if "spreadingfactor" in c else 0
+        cr           = int(c["codingrate"]) if "codingrate" in c else 0
+        flow_control = c.as_bool("flow_control") if "flow_control" in c else False
+        id_interval  = int(c["id_interval"]) if "id_interval" in c else None
+        id_callsign  = c["id_callsign"] if "id_callsign" in c else None
+        st_alock     = float(c["airtime_limit_short"]) if "airtime_limit_short" in c else None
+        lt_alock     = float(c["airtime_limit_long"]) if "airtime_limit_long" in c else None
+
+        force_ble = False
+        ble_name = None
+        ble_addr = None
+
+        port = c["port"] if "port" in c else None
+
+        if port == None:
+            raise ValueError("No port specified for RNode interface")
+
+        if port != None:
+            ble_uri_scheme = "ble://"
+            if port.lower().startswith(ble_uri_scheme):
+                force_ble = True
+                ble_string = port[len(ble_uri_scheme):]
+                port = None
+                if len(ble_string) == 0:
+                    pass
+                elif len(ble_string.split(":")) == 6 and len(ble_string) == 17:
+                    ble_addr = ble_string
+                else:
+                    ble_name = ble_string
+
         self.HW_MTU = 508
         
         self.pyserial    = serial
@@ -200,6 +239,15 @@ class RNodeInterface(Interface):
         self.r_premable_time_ms = None
         self.r_battery_state = RNodeInterface.BATTERY_STATE_UNKNOWN
         self.r_battery_percent = 0
+        self.r_framebuffer = b""
+        self.r_framebuffer_readtime = 0
+        self.r_framebuffer_latency = 0
+        self.r_disp = b""
+        self.r_disp_readtime = 0
+        self.r_disp_latency = 0
+
+        self.should_read_display = False
+        self.read_display_interval = RNodeInterface.DISPLAY_READ_INTERVAL
 
         self.packet_queue    = []
         self.flow_control    = flow_control
@@ -417,7 +465,34 @@ class RNodeInterface(Interface):
             
             written = self.serial.write(kiss_command)
             if written != len(kiss_command):
-                raise IOError("An IO error occurred while writing framebuffer data device")
+                raise IOError("An IO error occurred while writing framebuffer data to device")
+
+    def read_framebuffer(self):
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_FB_READ])+bytes([0x01])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        self.r_framebuffer_readtime = time.time()
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while sending framebuffer read command")
+
+    def read_display(self):
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_DISP_READ])+bytes([0x01])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        self.r_disp_readtime = time.time()
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while sending display read command")
+
+    def _read_display_job(self):
+        while self.should_read_display:
+            self.read_display()
+            time.sleep(self.read_display_interval)
+
+    def start_display_updates(self):
+        if not self.should_read_display:
+            self.should_read_display = True
+            threading.Thread(target=self._read_display_job, daemon=True).start()
+
+    def stop_display_updates(self):
+        self.should_read_display = False
 
     def hard_reset(self):
         kiss_command = bytes([KISS.FEND, KISS.CMD_RESET, 0xf8, KISS.FEND])
@@ -561,14 +636,14 @@ class RNodeInterface(Interface):
         except:
             self.bitrate = 0
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)
         self.owner.inbound(data, self)
         self.r_stat_rssi = None
         self.r_stat_snr = None
 
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         datalen = len(data)
         if self.online:
             if self.interface_ready:
@@ -599,7 +674,7 @@ class RNodeInterface(Interface):
         if len(self.packet_queue) > 0:
             data = self.packet_queue.pop(0)
             self.interface_ready = True
-            self.processOutgoing(data)
+            self.process_outgoing(data)
         elif len(self.packet_queue) == 0:
             self.interface_ready = True
 
@@ -619,7 +694,7 @@ class RNodeInterface(Interface):
 
                     if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
                         in_frame = False
-                        self.processIncoming(data_buffer)
+                        self.process_incoming(data_buffer)
                         data_buffer = b""
                         command_buffer = b""
                     elif (byte == KISS.FEND):
@@ -880,6 +955,36 @@ class RNodeInterface(Interface):
                                         raise IOError("ESP32 reset")
                         elif (command == KISS.CMD_READY):
                             self.process_queue()
+                        elif (command == KISS.CMD_FB_READ):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                command_buffer = command_buffer+bytes([byte])
+                                if (len(command_buffer) == 512):
+                                    self.r_framebuffer_latency = time.time() - self.r_framebuffer_readtime
+                                    self.r_framebuffer = command_buffer
+
+                        elif (command == KISS.CMD_DISP_READ):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                command_buffer = command_buffer+bytes([byte])
+                                if (len(command_buffer) == 1024):
+                                    self.r_disp_latency = time.time() - self.r_disp_readtime
+                                    self.r_disp = command_buffer
+
                         elif (command == KISS.CMD_DETECT):
                             if byte == KISS.DETECT_RESP:
                                 self.detected = True
@@ -899,7 +1004,7 @@ class RNodeInterface(Interface):
                         if self.first_tx != None:
                             if time.time() > self.first_tx + self.id_interval:
                                 RNS.log("Interface "+str(self)+" is transmitting beacon data: "+str(self.id_callsign.decode("utf-8")), RNS.LOG_DEBUG)
-                                self.processOutgoing(self.id_callsign)
+                                self.process_outgoing(self.id_callsign)
 
                     sleep(0.08)
 

RNS/Interfaces/RNodeMultiInterface.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 from time import sleep
 import sys
 import threading
@@ -163,6 +163,7 @@ class KISS():
 
 class RNodeMultiInterface(Interface):
     MAX_CHUNK = 32768
+    DEFAULT_IFAC_SIZE = 8
 
     CALLSIGN_MAX_LEN    = 32
 
@@ -173,7 +174,7 @@ class RNodeMultiInterface(Interface):
 
     MAX_SUBINTERFACES = 11
 
-    def __init__(self, owner, name, port, subint_config, id_interval = None, id_callsign = None):
+    def __init__(self, owner, configuration):
         if RNS.vendor.platformutils.is_android():
             raise SystemError("Invalid interface type. The Android-specific RNode interface must be used on Android")
 
@@ -187,6 +188,75 @@ class RNodeMultiInterface(Interface):
 
         super().__init__()
 
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+
+        count = 0
+        enabled_count = 0
+
+        # Count how many interfaces are in the file
+        for subinterface in c:
+            # if the retrieved entry is not a string, it must be a dictionary, which is what we want
+            if isinstance(c[subinterface], dict):
+                count += 1
+
+        # Count how many interfaces are enabled to allow for appropriate matrix sizing
+        for subinterface in c:
+            if isinstance(c[subinterface], dict):
+                subinterface_config = c[subinterface]
+                if (("interface_enabled" in subinterface_config) and subinterface_config.as_bool("interface_enabled") == True) or (("enabled" in c) and c.as_bool("enabled") == True):
+                    enabled_count += 1
+
+        # Create an array with a row for each subinterface
+        subint_config = [[0 for x in range(11)] for y in range(enabled_count)]
+        subint_index = 0
+
+        for subinterface in c:
+            if isinstance(c[subinterface], dict):
+                subinterface_config = c[subinterface]
+                if (("interface_enabled" in subinterface_config) and subinterface_config.as_bool("interface_enabled") == True) or (("enabled" in c) and c.as_bool("enabled") == True):
+                    subint_config[subint_index][0] = subinterface
+
+                    subint_vport = subinterface_config["vport"] if "vport" in subinterface_config else None
+                    subint_config[subint_index][1] = subint_vport
+
+                    frequency = int(subinterface_config["frequency"]) if "frequency" in subinterface_config else None
+                    subint_config[subint_index][2] = frequency
+                    bandwidth = int(subinterface_config["bandwidth"]) if "bandwidth" in subinterface_config else None
+                    subint_config[subint_index][3] = bandwidth
+                    txpower = int(subinterface_config["txpower"]) if "txpower" in subinterface_config else None
+                    subint_config[subint_index][4] = txpower
+                    spreadingfactor = int(subinterface_config["spreadingfactor"]) if "spreadingfactor" in subinterface_config else None
+                    subint_config[subint_index][5] = spreadingfactor 
+                    codingrate = int(subinterface_config["codingrate"]) if "codingrate" in subinterface_config else None
+                    subint_config[subint_index][6] = codingrate
+                    flow_control = subinterface_config.as_bool("flow_control") if "flow_control" in subinterface_config else False
+                    subint_config[subint_index][7] = flow_control 
+                    st_alock = float(subinterface_config["airtime_limit_short"]) if "airtime_limit_short" in subinterface_config else None
+                    subint_config[subint_index][8] = st_alock
+                    lt_alock = float(subinterface_config["airtime_limit_long"]) if "airtime_limit_long" in subinterface_config else None
+                    subint_config[subint_index][9] = lt_alock
+
+                    if "outgoing" in subinterface_config and subinterface_config.as_bool("outgoing") == False:
+                        subint_config[subint_index][10] = False
+                    else:
+                        subint_config[subint_index][10] = True
+                    subint_index += 1
+
+        # if no subinterfaces are defined
+        if count == 0:
+            raise ValueError("No subinterfaces configured for "+name)
+        # if no subinterfaces are enabled
+        elif enabled_count == 0:
+            raise ValueError("No subinterfaces enabled for "+name)
+
+        id_interval = int(c["id_interval"]) if "id_interval" in c else None
+        id_callsign = c["id_callsign"] if "id_callsign" in c else None
+        port = c["port"] if "port" in c else None
+        
+        if port == None:
+            raise ValueError("No port specified for "+name)
+
         self.HW_MTU = 508
         
         self.clients = 0
@@ -494,7 +564,7 @@ class RNodeMultiInterface(Interface):
         RNS.log("Please update your RNode firmware with rnodeconf from https://github.com/markqvist/Reticulum/RNS/Utilities/rnodeconf.py")
         RNS.panic()
 
-    def processOutgoing(self, data, interface = None):
+    def process_outgoing(self, data, interface = None):
         if interface is None:
             # do nothing if RNS tries to transmit on this interface directly
             pass
@@ -542,7 +612,7 @@ class RNodeMultiInterface(Interface):
                             command == KISS.CMD_INT10_DATA or
                             command == KISS.CMD_INT11_DATA)):
                         in_frame = False
-                        self.subinterfaces[KISS.int_data_cmd_to_index(command)].processIncoming(data_buffer)
+                        self.subinterfaces[KISS.int_data_cmd_to_index(command)].process_incoming(data_buffer)
                         self.selected_index = KISS.int_data_cmd_to_index(command)
                         data_buffer = b""
                         command_buffer = b""
@@ -821,7 +891,7 @@ class RNodeMultiInterface(Interface):
                                 for interface in self.subinterfaces:
                                     if interface != 0 and interface.online:
                                         interface_available = True
-                                        self.subinterfaces[interface.index].processOutgoing(self.id_callsign)
+                                        self.subinterfaces[interface.index].process_outgoing(self.id_callsign)
 
                                 if interface_available:
                                     RNS.log("Interface "+str(self)+" is transmitting beacon data on all subinterfaces: "+str(self.id_callsign.decode("utf-8")), RNS.LOG_DEBUG)
@@ -1127,13 +1197,13 @@ class RNodeSubInterface(Interface):
         except:
             self.bitrate = 0
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)
         self.owner.inbound(data, self)
         self.r_stat_rssi = None
         self.r_stat_snr = None
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         if self.online:
             if self.interface_ready:
                 if self.flow_control:
@@ -1145,7 +1215,7 @@ class RNodeSubInterface(Interface):
                     if self.parent_interface.first_tx == None:
                         self.parent_interface.first_tx = time.time()
                 self.txb += len(data)
-                self.parent_interface.processOutgoing(data, self)
+                self.parent_interface.process_outgoing(data, self)
             else:
                 self.queue(data)
 
@@ -1157,7 +1227,7 @@ class RNodeSubInterface(Interface):
         if len(self.packet_queue) > 0:
             data = self.packet_queue.pop(0)
             self.interface_ready = True
-            self.processOutgoing(data)
+            self.process_outgoing(data)
         elif len(self.packet_queue) == 0:
             self.interface_ready = True
 

RNS/Interfaces/SerialInterface.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 from time import sleep
 import sys
 import threading
@@ -42,6 +42,7 @@ class HDLC():
 
 class SerialInterface(Interface):
     MAX_CHUNK = 32768
+    DEFAULT_IFAC_SIZE = 8
 
     owner    = None
     port     = None
@@ -51,7 +52,7 @@ class SerialInterface(Interface):
     stopbits = None
     serial   = None
 
-    def __init__(self, owner, name, port, speed, databits, parity, stopbits):
+    def __init__(self, owner, configuration):
         import importlib
         if importlib.util.find_spec('serial') != None:
             import serial
@@ -62,6 +63,17 @@ class SerialInterface(Interface):
 
         super().__init__()
 
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+        port = c["port"] if "port" in c else None
+        speed = int(c["speed"]) if "speed" in c else 9600
+        databits = int(c["databits"]) if "databits" in c else 8
+        parity = c["parity"] if "parity" in c else "N"
+        stopbits = int(c["stopbits"]) if "stopbits" in c else 1
+
+        if port == None:
+            raise ValueError("No port specified for serial interface")
+
         self.HW_MTU = 564
         
         self.pyserial = serial
@@ -121,12 +133,12 @@ class SerialInterface(Interface):
         RNS.log("Serial port "+self.port+" is now open", RNS.LOG_VERBOSE)
 
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)            
         self.owner.inbound(data, self)
 
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         if self.online:
             data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
             written = self.serial.write(data)
@@ -149,7 +161,7 @@ class SerialInterface(Interface):
 
                     if (in_frame and byte == HDLC.FLAG):
                         in_frame = False
-                        self.processIncoming(data_buffer)
+                        self.process_incoming(data_buffer)
                     elif (byte == HDLC.FLAG):
                         in_frame = True
                         data_buffer = b""

RNS/Interfaces/TCPInterface.py

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2016-2022 Mark Qvist / unsigned.io
+# Copyright (c) 2016-2024 Mark Qvist / unsigned.io
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 import socketserver
 import threading
 import platform
@@ -58,8 +58,12 @@ class KISS():
 class ThreadingTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
     pass
 
+class ThreadingTCP6Server(socketserver.ThreadingMixIn, socketserver.TCPServer):
+    address_family = socket.AF_INET6
+
 class TCPClientInterface(Interface):
     BITRATE_GUESS = 10*1000*1000
+    DEFAULT_IFAC_SIZE = 16
 
     RECONNECT_WAIT = 5
     RECONNECT_MAX_TRIES = None
@@ -78,8 +82,19 @@ class TCPClientInterface(Interface):
     I2P_PROBE_INTERVAL = 9
     I2P_PROBES = 5
 
-    def __init__(self, owner, name, target_ip=None, target_port=None, connected_socket=None, max_reconnect_tries=None, kiss_framing=False, i2p_tunneled = False, connect_timeout = None):
+    def __init__(self, owner, configuration, connected_socket=None):
         super().__init__()
+
+        c = Interface.get_config_obj(configuration)
+        name = c["name"]
+        target_ip = c["target_host"] if "target_host" in c and c["target_host"] != None else None
+        target_port = int(c["target_port"]) if "target_port" in c and c["target_host"] != None else None
+        kiss_framing = False
+        if "kiss_framing" in c and c.as_bool("kiss_framing") == True:
+            kiss_framing = True
+        i2p_tunneled = c.as_bool("i2p_tunneled") if "i2p_tunneled" in c else False
+        connect_timeout = c.as_int("connect_timeout") if "connect_timeout" in c else None
+        max_reconnect_tries = c.as_int("max_reconnect_tries") if "max_reconnect_tries" in c else None
         
         self.HW_MTU = 1064
         
@@ -200,10 +215,14 @@ class TCPClientInterface(Interface):
             if initial:
                 RNS.log("Establishing TCP connection for "+str(self)+"...", RNS.LOG_DEBUG)
 
-            self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            address_info = socket.getaddrinfo(self.target_ip, self.target_port, proto=socket.IPPROTO_TCP)[0]
+            address_family = address_info[0]
+            target_address = address_info[4]
+
+            self.socket = socket.socket(address_family, socket.SOCK_STREAM)
             self.socket.settimeout(TCPClientInterface.INITIAL_CONNECT_TIMEOUT)
             self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
-            self.socket.connect((self.target_ip, self.target_port))
+            self.socket.connect(target_address)
             self.socket.settimeout(None)
             self.online  = True
 
@@ -265,14 +284,14 @@ class TCPClientInterface(Interface):
             RNS.log("Attempt to reconnect on a non-initiator TCP interface. This should not happen.", RNS.LOG_ERROR)
             raise IOError("Attempt to reconnect on a non-initiator TCP interface")
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)
         if hasattr(self, "parent_interface") and self.parent_interface != None:
             self.parent_interface.rxb += len(data)
                     
         self.owner.inbound(data, self)
 
-    def processOutgoing(self, data):
+    def process_outgoing(self, data):
         if self.online:
             # while self.writing:
             #     time.sleep(0.01)
@@ -316,7 +335,7 @@ class TCPClientInterface(Interface):
                             # Read loop for KISS framing
                             if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
                                 in_frame = False
-                                self.processIncoming(data_buffer)
+                                self.process_incoming(data_buffer)
                             elif (byte == KISS.FEND):
                                 in_frame = True
                                 command = KISS.CMD_UNKNOWN
@@ -343,7 +362,7 @@ class TCPClientInterface(Interface):
                             # Read loop for HDLC framing
                             if (in_frame and byte == HDLC.FLAG):
                                 in_frame = False
-                                self.processIncoming(data_buffer)
+                                self.process_incoming(data_buffer)
                             elif (byte == HDLC.FLAG):
                                 in_frame = True
                                 data_buffer = b""
@@ -394,7 +413,8 @@ class TCPClientInterface(Interface):
         self.IN = False
 
         if hasattr(self, "parent_interface") and self.parent_interface != None:
-            self.parent_interface.clients -= 1
+            while self in self.parent_interface.spawned_interfaces:
+                self.parent_interface.spawned_interfaces.remove(self)
 
         if self in RNS.Transport.interfaces:
             if not self.initiator:
@@ -402,31 +422,72 @@ class TCPClientInterface(Interface):
 
 
     def __str__(self):
-        return "TCPInterface["+str(self.name)+"/"+str(self.target_ip)+":"+str(self.target_port)+"]"
+        if ":" in self.target_ip:
+            ip_str = f"[{self.target_ip}]"
+        else:
+            ip_str = f"{self.target_ip}"
+
+        return "TCPInterface["+str(self.name)+"/"+ip_str+":"+str(self.target_port)+"]"
 
 
 class TCPServerInterface(Interface):
     BITRATE_GUESS      = 10*1000*1000
+    DEFAULT_IFAC_SIZE = 16
 
     @staticmethod
-    def get_address_for_if(name):
+    def get_address_for_if(name, bind_port, prefer_ipv6=False):
         import RNS.vendor.ifaddr.niwrapper as netinfo
         ifaddr = netinfo.ifaddresses(name)
-        return ifaddr[netinfo.AF_INET][0]["addr"]
+        if len(ifaddr) < 1:
+            raise SystemError(f"No addresses available on specified kernel interface \"{name}\" for TCPServerInterface to bind to")
+
+        if (prefer_ipv6 or not netinfo.AF_INET in ifaddr) and netinfo.AF_INET6 in ifaddr:
+            bind_ip = ifaddr[netinfo.AF_INET6][0]["addr"]
+            if bind_ip.lower().startswith("fe80::"):
+                # We'll need to add the interface as scope for link-local addresses
+                return TCPServerInterface.get_address_for_host(f"{bind_ip}%{name}", bind_port)
+            else:
+                return TCPServerInterface.get_address_for_host(bind_ip, bind_port)
+        elif netinfo.AF_INET in ifaddr:
+            bind_ip = ifaddr[netinfo.AF_INET][0]["addr"]
+            return (bind_ip, bind_port)
+        else:
+            raise SystemError(f"No addresses available on specified kernel interface \"{name}\" for TCPServerInterface to bind to")
 
     @staticmethod
-    def get_broadcast_for_if(name):
-        import RNS.vendor.ifaddr.niwrapper as netinfo
-        ifaddr = netinfo.ifaddresses(name)
-        return ifaddr[netinfo.AF_INET][0]["broadcast"]
+    def get_address_for_host(name, bind_port):
+        address_info = socket.getaddrinfo(name, bind_port, proto=socket.IPPROTO_TCP)[0]
+        if address_info[0] == socket.AF_INET6:
+            return (name, bind_port, address_info[4][2], address_info[4][3])
+        elif address_info[0] == socket.AF_INET:
+            return (name, bind_port)
+        else:
+            raise SystemError(f"No suitable kernel interface available for address \"{name}\" for TCPServerInterface to bind to")
 
-    def __init__(self, owner, name, device=None, bindip=None, bindport=None, i2p_tunneled=False):
+
+    @property
+    def clients(self):
+        return len(self.spawned_interfaces)
+
+    def __init__(self, owner, configuration):
         super().__init__()
 
+        c            = Interface.get_config_obj(configuration)
+        name         = c["name"]
+        device       = c["device"] if "device" in c else None
+        port         = int(c["port"]) if "port" in c else None
+        bindip       = c["listen_ip"] if "listen_ip" in c else None
+        bindport     = int(c["listen_port"]) if "listen_port" in c else None
+        i2p_tunneled = c.as_bool("i2p_tunneled") if "i2p_tunneled" in c else False
+        prefer_ipv6  = c.as_bool("prefer_ipv6") if "prefer_ipv6" in c else False
+
+        if port != None:
+            bindport = port
+
         self.HW_MTU = 1064
 
         self.online = False
-        self.clients = 0
+        self.spawned_interfaces = []
         
         self.IN  = True
         self.OUT = False
@@ -436,24 +497,40 @@ class TCPServerInterface(Interface):
         self.i2p_tunneled = i2p_tunneled
         self.mode         = RNS.Interfaces.Interface.Interface.MODE_FULL
 
-        if device != None:
-            bindip = TCPServerInterface.get_address_for_if(device)
-
-        if (bindip != None and bindport != None):
-            self.receives = True
-            self.bind_ip = bindip
+        if bindport == None:
+            raise SystemError(f"No TCP port configured for interface \"{name}\"")
+        else:
             self.bind_port = bindport
 
+        bind_address = None
+        if device != None:
+            bind_address = TCPServerInterface.get_address_for_if(device, self.bind_port, prefer_ipv6)
+        else:
+            if bindip == None:
+                raise SystemError(f"No TCP bind IP configured for interface \"{name}\"")
+            bind_address = TCPServerInterface.get_address_for_host(bindip, self.bind_port)
+
+        if bind_address != None:
+            self.receives = True
+            self.bind_ip = bind_address[0]
+
             def handlerFactory(callback):
                 def createHandler(*args, **keys):
                     return TCPInterfaceHandler(callback, *args, **keys)
                 return createHandler
 
             self.owner = owner
-            address = (self.bind_ip, self.bind_port)
 
-            ThreadingTCPServer.allow_reuse_address = True
-            self.server = ThreadingTCPServer(address, handlerFactory(self.incoming_connection))
+            if len(bind_address) == 4:
+                try:
+                    ThreadingTCP6Server.allow_reuse_address = True
+                    self.server = ThreadingTCP6Server(bind_address, handlerFactory(self.incoming_connection))
+                except Exception as e:
+                    RNS.log(f"Error while binding IPv6 socket for interface, the contained exception was: {e}", RNS.LOG_ERROR)
+                    raise SystemError("Could not bind IPv6 socket for interface. Please check the specified \"listen_ip\" configuration option")
+            else:
+                ThreadingTCPServer.allow_reuse_address = True
+                self.server = ThreadingTCPServer(bind_address, handlerFactory(self.incoming_connection))
 
             self.bitrate = TCPServerInterface.BITRATE_GUESS
 
@@ -463,11 +540,13 @@ class TCPServerInterface(Interface):
 
             self.online = True
 
+        else:
+            raise SystemError("Insufficient parameters to create TCP listener")
 
     def incoming_connection(self, handler):
         RNS.log("Accepting incoming TCP connection", RNS.LOG_VERBOSE)
-        interface_name = "Client on "+self.name
-        spawned_interface = TCPClientInterface(self.owner, interface_name, target_ip=None, target_port=None, connected_socket=handler.request, i2p_tunneled=self.i2p_tunneled)
+        spawned_configuration = {"name": "Client on "+self.name, "target_host": None, "target_port": None, "i2p_tunneled": self.i2p_tunneled}
+        spawned_interface = TCPClientInterface(self.owner, spawned_configuration, connected_socket=handler.request)
         spawned_interface.OUT = self.OUT
         spawned_interface.IN  = self.IN
         spawned_interface.target_ip = handler.client_address[0]
@@ -503,7 +582,9 @@ class TCPServerInterface(Interface):
         spawned_interface.online = True
         RNS.log("Spawned new TCPClient Interface: "+str(spawned_interface), RNS.LOG_VERBOSE)
         RNS.Transport.interfaces.append(spawned_interface)
-        self.clients += 1
+        while spawned_interface in self.spawned_interfaces:
+            self.spawned_interfaces.remove(spawned_interface)
+        self.spawned_interfaces.append(spawned_interface)
         spawned_interface.read_loop()
 
     def received_announce(self, from_spawned=False):
@@ -512,7 +593,7 @@ class TCPServerInterface(Interface):
     def sent_announce(self, from_spawned=False):
         if from_spawned: self.oa_freq_deque.append(time.time())
 
-    def processOutgoing(self, data):
+    def process_outgoing(self, data):
         pass
 
 
@@ -531,7 +612,12 @@ class TCPServerInterface(Interface):
 
 
     def __str__(self):
-        return "TCPServerInterface["+self.name+"/"+self.bind_ip+":"+str(self.bind_port)+"]"
+        if ":" in self.bind_ip:
+            ip_str = f"[{self.bind_ip}]"
+        else:
+            ip_str = f"{self.bind_ip}"
+
+        return "TCPServerInterface["+self.name+"/"+ip_str+":"+str(self.bind_port)+"]"
 
 
 class TCPInterfaceHandler(socketserver.BaseRequestHandler):

RNS/Interfaces/UDPInterface.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-from .Interface import Interface
+from RNS.Interfaces.Interface import Interface
 import socketserver
 import threading
 import socket
@@ -31,6 +31,7 @@ import RNS
 
 class UDPInterface(Interface):
     BITRATE_GUESS = 10*1000*1000
+    DEFAULT_IFAC_SIZE = 16
 
     @staticmethod
     def get_address_for_if(name):
@@ -44,9 +45,24 @@ class UDPInterface(Interface):
         ifaddr = netinfo.ifaddresses(name)
         return ifaddr[netinfo.AF_INET][0]["broadcast"]
 
-    def __init__(self, owner, name, device=None, bindip=None, bindport=None, forwardip=None, forwardport=None):
+    def __init__(self, owner, configuration):
         super().__init__()
 
+        c           = Interface.get_config_obj(configuration)
+        name        = c["name"]
+        device      = c["device"] if "device" in c else None
+        port        = int(c["port"]) if "port" in c else None
+        bindip      = c["listen_ip"] if "listen_ip" in c else None
+        bindport    = int(c["listen_port"]) if "listen_port" in c else None
+        forwardip   = c["forward_ip"] if "forward_ip" in c else None
+        forwardport = int(c["forward_port"]) if "forward_port" in c else None
+
+        if port != None:
+            if bindport == None:
+                bindport = port
+            if forwardport == None:
+                forwardport = port
+
         self.HW_MTU = 1064
 
         self.IN  = True
@@ -75,7 +91,7 @@ class UDPInterface(Interface):
             self.owner = owner
             address = (self.bind_ip, self.bind_port)
             socketserver.UDPServer.address_family = socket.AF_INET
-            self.server = socketserver.UDPServer(address, handlerFactory(self.processIncoming))
+            self.server = socketserver.UDPServer(address, handlerFactory(self.process_incoming))
 
             thread = threading.Thread(target=self.server.serve_forever)
             thread.daemon = True
@@ -89,11 +105,11 @@ class UDPInterface(Interface):
             self.forward_port = forwardport
 
 
-    def processIncoming(self, data):
+    def process_incoming(self, data):
         self.rxb += len(data)
         self.owner.inbound(data, self)
 
-    def processOutgoing(self,data):
+    def process_outgoing(self,data):
         try:
             udp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
             udp_socket.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)

RNS/Interfaces/__init__.py

@@ -24,5 +24,7 @@ import os
 import glob
 import RNS.Interfaces.Android
 
-modules = glob.glob(os.path.dirname(__file__)+"/*.py")
-__all__ = [ os.path.basename(f)[:-3] for f in modules if not f.endswith('__init__.py')]
+py_modules  = glob.glob(os.path.dirname(__file__)+"/*.py")
+pyc_modules = glob.glob(os.path.dirname(__file__)+"/*.pyc")
+modules     = py_modules+pyc_modules
+__all__ = list(set([os.path.basename(f).replace(".pyc", "").replace(".py", "") for f in modules if not (f.endswith("__init__.py") or f.endswith("__init__.pyc"))]))

RNS/Link.py

@@ -21,7 +21,7 @@
 # SOFTWARE.
 
 from RNS.Cryptography import X25519PrivateKey, X25519PublicKey, Ed25519PrivateKey, Ed25519PublicKey
-from RNS.Cryptography import Fernet
+from RNS.Cryptography import Token
 from RNS.Channel import Channel, LinkChannelOutlet
 
 from time import sleep
@@ -61,7 +61,7 @@ class Link:
     ECPUBSIZE         = 32+32
     KEYSIZE           = 32
 
-    MDU = math.floor((RNS.Reticulum.MTU-RNS.Reticulum.IFAC_MIN_SIZE-RNS.Reticulum.HEADER_MINSIZE-RNS.Identity.FERNET_OVERHEAD)/RNS.Identity.AES128_BLOCKSIZE)*RNS.Identity.AES128_BLOCKSIZE - 1
+    MDU = math.floor((RNS.Reticulum.MTU-RNS.Reticulum.IFAC_MIN_SIZE-RNS.Reticulum.HEADER_MINSIZE-RNS.Identity.TOKEN_OVERHEAD)/RNS.Identity.AES128_BLOCKSIZE)*RNS.Identity.AES128_BLOCKSIZE - 1
 
     ESTABLISHMENT_TIMEOUT_PER_HOP = RNS.Reticulum.DEFAULT_PER_HOP_TIMEOUT
     """
@@ -188,7 +188,7 @@ class Link:
             self.prv     = X25519PrivateKey.generate()
             self.sig_prv = Ed25519PrivateKey.generate()
 
-        self.fernet  = None
+        self.token  = None
         
         self.pub = self.prv.public_key()
         self.pub_bytes = self.pub.public_bytes()
@@ -979,14 +979,14 @@ class Link:
 
     def encrypt(self, plaintext):
         try:
-            if not self.fernet:
+            if not self.token:
                 try:
-                    self.fernet = Fernet(self.derived_key)
+                    self.token = Token(self.derived_key)
                 except Exception as e:
-                    RNS.log("Could not instantiate Fernet while performin encryption on link "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
+                    RNS.log("Could not instantiate token while performing encryption on link "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
                     raise e
 
-            return self.fernet.encrypt(plaintext)
+            return self.token.encrypt(plaintext)
 
         except Exception as e:
             RNS.log("Encryption on link "+str(self)+" failed. The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -995,10 +995,10 @@ class Link:
 
     def decrypt(self, ciphertext):
         try:
-            if not self.fernet:
-                self.fernet = Fernet(self.derived_key)
+            if not self.token:
+                self.token = Token(self.derived_key)
                 
-            return self.fernet.decrypt(ciphertext)
+            return self.token.decrypt(ciphertext)
 
         except Exception as e:
             RNS.log("Decryption failed on link "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)

RNS/Packet.py

@@ -95,7 +95,7 @@ class Packet:
     # With an MTU of 500, the maximum of data we can
     # send in a single encrypted packet is given by
     # the below calculation; 383 bytes.
-    ENCRYPTED_MDU  = math.floor((RNS.Reticulum.MDU-RNS.Identity.FERNET_OVERHEAD-RNS.Identity.KEYSIZE//16)/RNS.Identity.AES128_BLOCKSIZE)*RNS.Identity.AES128_BLOCKSIZE - 1
+    ENCRYPTED_MDU  = math.floor((RNS.Reticulum.MDU-RNS.Identity.TOKEN_OVERHEAD-RNS.Identity.KEYSIZE//16)/RNS.Identity.AES128_BLOCKSIZE)*RNS.Identity.AES128_BLOCKSIZE - 1
     """
     The maximum size of the payload data in a single encrypted packet 
     """

RNS/Reticulum.py

@@ -34,9 +34,9 @@ if get_platform() == "android":
     from .Interfaces.Android import SerialInterface
     from .Interfaces.Android import KISSInterface
 else:
-    from .Interfaces import *
+    from RNS.Interfaces import *
 
-from .vendor.configobj import ConfigObj
+from RNS.vendor.configobj import ConfigObj
 import configparser
 import multiprocessing.connection
 import signal
@@ -148,6 +148,7 @@ class Reticulum:
     configpath       = ""
     storagepath      = ""
     cachepath        = ""
+    interfacepath    = ""
 
     __instance       = None
     
@@ -183,7 +184,7 @@ class Reticulum:
         """
         return Reticulum.__instance
 
-    def __init__(self,configdir=None, loglevel=None, logdest=None, verbosity=None):
+    def __init__(self,configdir=None, loglevel=None, logdest=None, verbosity=None, require_shared_instance=False):
         """
         Initialises and starts a Reticulum instance. This must be
         done before any other operations, and Reticulum will not
@@ -212,12 +213,16 @@ class Reticulum:
         if logdest == RNS.LOG_FILE:
             RNS.logdest = RNS.LOG_FILE
             RNS.logfile = Reticulum.configdir+"/logfile"
+        elif callable(logdest):
+            RNS.logdest = RNS.LOG_CALLBACK
+            RNS.logcall = logdest
         
         Reticulum.configpath    = Reticulum.configdir+"/config"
         Reticulum.storagepath   = Reticulum.configdir+"/storage"
         Reticulum.cachepath     = Reticulum.configdir+"/storage/cache"
         Reticulum.resourcepath  = Reticulum.configdir+"/storage/resources"
         Reticulum.identitypath  = Reticulum.configdir+"/storage/identities"
+        Reticulum.interfacepath = Reticulum.configdir+"/interfaces"
 
         Reticulum.__transport_enabled = False
         Reticulum.__remote_management_enabled = False
@@ -245,6 +250,7 @@ class Reticulum:
             RNS.loglevel = self.requested_loglevel
 
         self.is_shared_instance = False
+        self.require_shared = require_shared_instance
         self.is_connected_to_shared_instance = False
         self.is_standalone_instance = False
         self.jobs_thread = None
@@ -263,6 +269,9 @@ class Reticulum:
         if not os.path.isdir(Reticulum.identitypath):
             os.makedirs(Reticulum.identitypath)
 
+        if not os.path.isdir(Reticulum.interfacepath):
+            os.makedirs(Reticulum.interfacepath)
+
         if os.path.isfile(self.configpath):
             try:
                 self.config = ConfigObj(self.configpath)
@@ -277,7 +286,8 @@ class Reticulum:
             time.sleep(1.5)
 
         self.__apply_config()
-        RNS.log("Configuration loaded from "+self.configpath, RNS.LOG_VERBOSE)
+        RNS.log(f"Utilising cryptography backend \"{RNS.Cryptography.Provider.backend()}\"", RNS.LOG_VERBOSE)
+        RNS.log(f"Configuration loaded from {self.configpath}", RNS.LOG_VERBOSE)
         
         RNS.Identity.load_known_destinations()
 
@@ -329,11 +339,17 @@ class Reticulum:
                     interface.bitrate = Reticulum._force_shared_instance_bitrate
                     interface._force_bitrate = Reticulum._force_shared_instance_bitrate
                     RNS.log(f"Forcing shared instance bitrate of {RNS.prettyspeed(interface.bitrate)}", RNS.LOG_WARNING)
-                RNS.Transport.interfaces.append(interface)
                 
-                self.is_shared_instance = True
-                RNS.log("Started shared instance interface: "+str(interface), RNS.LOG_DEBUG)
-                self.__start_jobs()
+                if self.require_shared == True:
+                    interface.detach()
+                    self.is_shared_instance = True
+                    RNS.log("Existing shared instance required, but this instance started as shared instance. Aborting startup.", RNS.LOG_VERBOSE)
+
+                else:
+                    RNS.Transport.interfaces.append(interface)
+                    self.is_shared_instance = True
+                    RNS.log("Started shared instance interface: "+str(interface), RNS.LOG_DEBUG)
+                    self.__start_jobs()
 
             except Exception as e:
                 try:
@@ -361,6 +377,10 @@ class Reticulum:
                     self.is_shared_instance = False
                     self.is_standalone_instance = True
                     self.is_connected_to_shared_instance = False
+
+            if self.is_shared_instance and self.require_shared:
+                raise SystemError("No shared instance available, but application that started Reticulum required it")
+
         else:
             self.is_shared_instance = False
             self.is_standalone_instance = True
@@ -446,14 +466,7 @@ class Reticulum:
             if "interfaces" in self.config:
                 for name in self.config["interfaces"]:
                     if not name in interface_names:
-                        # TODO: We really need to generalise this way of instantiating
-                        # and configuring interfaces. Ideally, interfaces should just
-                        # have a conrfig dict passed to their init method, and return
-                        # a ready interface, onto which this routine can configure any
-                        # generic or extra parameters.
-
                         c = self.config["interfaces"][name]
-
                         interface_mode = Interface.Interface.MODE_FULL
                         
                         if "interface_mode" in c:
@@ -556,516 +569,22 @@ class Reticulum:
                                 announce_cap = c.as_float("announce_cap")/100.0
                                 
                         try:
-                            interface = None
-
-                            if (("interface_enabled" in c) and c.as_bool("interface_enabled") == True) or (("enabled" in c) and c.as_bool("enabled") == True):
-                                if c["type"] == "AutoInterface":
-                                    group_id        = c["group_id"] if "group_id" in c else None
-                                    discovery_scope = c["discovery_scope"] if "discovery_scope" in c else None
-                                    discovery_port  = int(c["discovery_port"]) if "discovery_port" in c else None
-                                    multicast_address_type = c["multicast_address_type"] if "multicast_address_type" in c else None
-                                    data_port  = int(c["data_port"]) if "data_port" in c else None
-                                    allowed_interfaces = c.as_list("devices") if "devices" in c else None
-                                    ignored_interfaces = c.as_list("ignored_devices") if "ignored_devices" in c else None
-
-                                    interface = AutoInterface.AutoInterface(
-                                        RNS.Transport,
-                                        name,
-                                        group_id,
-                                        discovery_scope,
-                                        discovery_port,
-                                        multicast_address_type,
-                                        data_port,
-                                        allowed_interfaces,
-                                        ignored_interfaces
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 16
-
-                                if c["type"] == "UDPInterface":
-                                    device       = c["device"] if "device" in c else None
-                                    port         = int(c["port"]) if "port" in c else None
-                                    listen_ip    = c["listen_ip"] if "listen_ip" in c else None
-                                    listen_port  = int(c["listen_port"]) if "listen_port" in c else None
-                                    forward_ip   = c["forward_ip"] if "forward_ip" in c else None
-                                    forward_port = int(c["forward_port"]) if "forward_port" in c else None
-
-                                    if port != None:
-                                        if listen_port == None:
-                                            listen_port = port
-                                        if forward_port == None:
-                                            forward_port = port
-
-                                    interface = UDPInterface.UDPInterface(
-                                        RNS.Transport,
-                                        name,
-                                        device,
-                                        listen_ip,
-                                        listen_port,
-                                        forward_ip,
-                                        forward_port
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 16
-
-                                if c["type"] == "TCPServerInterface":
-                                    device       = c["device"] if "device" in c else None
-                                    port         = int(c["port"]) if "port" in c else None
-                                    listen_ip    = c["listen_ip"] if "listen_ip" in c else None
-                                    listen_port  = int(c["listen_port"]) if "listen_port" in c else None
-                                    i2p_tunneled = c.as_bool("i2p_tunneled") if "i2p_tunneled" in c else False
-
-                                    if port != None:
-                                        listen_port = port
-
-                                    interface = TCPInterface.TCPServerInterface(
-                                        RNS.Transport,
-                                        name,
-                                        device,
-                                        listen_ip,
-                                        listen_port,
-                                        i2p_tunneled
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    if interface_mode == Interface.Interface.MODE_ACCESS_POINT:
-                                        RNS.log(str(interface)+" does not support Access Point mode, reverting to default mode: Full", RNS.LOG_WARNING)
-                                        interface_mode = Interface.Interface.MODE_FULL
-                                    
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 16
-
-                                if c["type"] == "TCPClientInterface":
-                                    kiss_framing = False
-                                    if "kiss_framing" in c and c.as_bool("kiss_framing") == True:
-                                        kiss_framing = True
-                                    i2p_tunneled = c.as_bool("i2p_tunneled") if "i2p_tunneled" in c else False
-                                    tcp_connect_timeout = c.as_int("connect_timeout") if "connect_timeout" in c else None
-
-
-                                    interface = TCPInterface.TCPClientInterface(
-                                        RNS.Transport,
-                                        name,
-                                        c["target_host"],
-                                        int(c["target_port"]),
-                                        kiss_framing = kiss_framing,
-                                        i2p_tunneled = i2p_tunneled,
-                                        connect_timeout = tcp_connect_timeout,
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    if interface_mode == Interface.Interface.MODE_ACCESS_POINT:
-                                        RNS.log(str(interface)+" does not support Access Point mode, reverting to default mode: Full", RNS.LOG_WARNING)
-                                        interface_mode = Interface.Interface.MODE_FULL
-                                    
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 16
-
-                                if c["type"] == "I2PInterface":
-                                    i2p_peers = c.as_list("peers") if "peers" in c else None
-                                    connectable = c.as_bool("connectable") if "connectable" in c else False
-
-                                    if ifac_size == None:
-                                        ifac_size = 16
-
-                                    interface = I2PInterface.I2PInterface(
-                                        RNS.Transport,
-                                        name,
-                                        Reticulum.storagepath,
-                                        i2p_peers,
-                                        connectable = connectable,
-                                        ifac_size = ifac_size,
-                                        ifac_netname = ifac_netname,
-                                        ifac_netkey = ifac_netkey,
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    if interface_mode == Interface.Interface.MODE_ACCESS_POINT:
-                                        RNS.log(str(interface)+" does not support Access Point mode, reverting to default mode: Full", RNS.LOG_WARNING)
-                                        interface_mode = Interface.Interface.MODE_FULL
-                                    
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-
-                                if c["type"] == "SerialInterface":
-                                    port = c["port"] if "port" in c else None
-                                    speed = int(c["speed"]) if "speed" in c else 9600
-                                    databits = int(c["databits"]) if "databits" in c else 8
-                                    parity = c["parity"] if "parity" in c else "N"
-                                    stopbits = int(c["stopbits"]) if "stopbits" in c else 1
-
-                                    if port == None:
-                                        raise ValueError("No port specified for serial interface")
-
-                                    interface = SerialInterface.SerialInterface(
-                                        RNS.Transport,
-                                        name,
-                                        port,
-                                        speed,
-                                        databits,
-                                        parity,
-                                        stopbits
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 8
-
-                                if c["type"] == "PipeInterface":
-                                    command = c["command"] if "command" in c else None
-                                    respawn_delay = c.as_float("respawn_delay") if "respawn_delay" in c else None
-
-                                    if command == None:
-                                        raise ValueError("No command specified for PipeInterface")
-
-                                    interface = PipeInterface.PipeInterface(
-                                        RNS.Transport,
-                                        name,
-                                        command,
-                                        respawn_delay,
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 8
-
-                                if c["type"] == "KISSInterface":
-                                    preamble = int(c["preamble"]) if "preamble" in c else None
-                                    txtail = int(c["txtail"]) if "txtail" in c else None
-                                    persistence = int(c["persistence"]) if "persistence" in c else None
-                                    slottime = int(c["slottime"]) if "slottime" in c else None
-                                    flow_control = c.as_bool("flow_control") if "flow_control" in c else False
-                                    port = c["port"] if "port" in c else None
-                                    speed = int(c["speed"]) if "speed" in c else 9600
-                                    databits = int(c["databits"]) if "databits" in c else 8
-                                    parity = c["parity"] if "parity" in c else "N"
-                                    stopbits = int(c["stopbits"]) if "stopbits" in c else 1
-                                    beacon_interval = int(c["id_interval"]) if "id_interval" in c else None
-                                    beacon_data = c["id_callsign"] if "id_callsign" in c else None
-
-                                    if port == None:
-                                        raise ValueError("No port specified for serial interface")
-
-                                    interface = KISSInterface.KISSInterface(
-                                        RNS.Transport,
-                                        name,
-                                        port,
-                                        speed,
-                                        databits,
-                                        parity,
-                                        stopbits,
-                                        preamble,
-                                        txtail,
-                                        persistence,
-                                        slottime,
-                                        flow_control,
-                                        beacon_interval,
-                                        beacon_data
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 8
-
-                                if c["type"] == "AX25KISSInterface":
-                                    preamble = int(c["preamble"]) if "preamble" in c else None
-                                    txtail = int(c["txtail"]) if "txtail" in c else None
-                                    persistence = int(c["persistence"]) if "persistence" in c else None
-                                    slottime = int(c["slottime"]) if "slottime" in c else None
-                                    flow_control = c.as_bool("flow_control") if "flow_control" in c else False
-                                    port = c["port"] if "port" in c else None
-                                    speed = int(c["speed"]) if "speed" in c else 9600
-                                    databits = int(c["databits"]) if "databits" in c else 8
-                                    parity = c["parity"] if "parity" in c else "N"
-                                    stopbits = int(c["stopbits"]) if "stopbits" in c else 1
-
-                                    callsign = c["callsign"] if "callsign" in c else ""
-                                    ssid = int(c["ssid"]) if "ssid" in c else -1
-
-                                    if port == None:
-                                        raise ValueError("No port specified for serial interface")
-
-                                    interface = AX25KISSInterface.AX25KISSInterface(
-                                        RNS.Transport,
-                                        name,
-                                        callsign,
-                                        ssid,
-                                        port,
-                                        speed,
-                                        databits,
-                                        parity,
-                                        stopbits,
-                                        preamble,
-                                        txtail,
-                                        persistence,
-                                        slottime,
-                                        flow_control
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 8
-
-                                if c["type"] == "RNodeInterface":
-                                    frequency = int(c["frequency"]) if "frequency" in c else None
-                                    bandwidth = int(c["bandwidth"]) if "bandwidth" in c else None
-                                    txpower = int(c["txpower"]) if "txpower" in c else None
-                                    spreadingfactor = int(c["spreadingfactor"]) if "spreadingfactor" in c else None
-                                    codingrate = int(c["codingrate"]) if "codingrate" in c else None
-                                    flow_control = c.as_bool("flow_control") if "flow_control" in c else False
-                                    id_interval = int(c["id_interval"]) if "id_interval" in c else None
-                                    id_callsign = c["id_callsign"] if "id_callsign" in c else None
-                                    st_alock = float(c["airtime_limit_short"]) if "airtime_limit_short" in c else None
-                                    lt_alock = float(c["airtime_limit_long"]) if "airtime_limit_long" in c else None
-
-                                    force_ble = False
-                                    ble_name = None
-                                    ble_addr = None
-
-                                    port = c["port"] if "port" in c else None
-
-                                    if port == None:
-                                        raise ValueError("No port specified for RNode interface")
-
-                                    if port != None:
-                                        ble_uri_scheme = "ble://"
-                                        if port.lower().startswith(ble_uri_scheme):
-                                            force_ble = True
-                                            ble_string = port[len(ble_uri_scheme):]
-                                            port = None
-                                            if len(ble_string) == 0:
-                                                pass
-                                            elif len(ble_string.split(":")) == 6 and len(ble_string) == 17:
-                                                ble_addr = ble_string
-                                            else:
-                                                ble_name = ble_string
-                                    
-                                    interface = RNodeInterface.RNodeInterface(
-                                        RNS.Transport,
-                                        name,
-                                        port,
-                                        frequency = frequency,
-                                        bandwidth = bandwidth,
-                                        txpower = txpower,
-                                        sf = spreadingfactor,
-                                        cr = codingrate,
-                                        flow_control = flow_control,
-                                        id_interval = id_interval,
-                                        id_callsign = id_callsign,
-                                        st_alock = st_alock,
-                                        lt_alock = lt_alock,
-                                        ble_addr = ble_addr,
-                                        ble_name = ble_name,
-                                        force_ble = force_ble,
-                                    )
-
-                                    if "outgoing" in c and c.as_bool("outgoing") == False:
-                                        interface.OUT = False
-                                    else:
-                                        interface.OUT = True
-
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 8
-
-                                if c["type"] == "RNodeMultiInterface":
-                                    count = 0
-                                    enabled_count = 0
-
-                                    # Count how many interfaces are in the file
-                                    for subinterface in c:
-                                        # if the retrieved entry is not a string, it must be a dictionary, which is what we want
-                                        if not isinstance(c[subinterface], str):
-                                            count += 1
-
-                                    # Count how many interfaces are enabled to allow for appropriate matrix sizing
-                                    for subinterface in c:
-                                        # if the retrieved entry is not a string, it must be a dictionary, which is what we want
-                                        if not isinstance(c[subinterface], str):
-                                            subinterface_config = self.config["interfaces"][name][subinterface]
-                                            if (("interface_enabled" in subinterface_config) and subinterface_config.as_bool("interface_enabled") == True) or (("enabled" in c) and c.as_bool("enabled") == True):
-                                                enabled_count += 1
-
-                                    # Create an array with a row for each subinterface
-                                    subint_config = [[0 for x in range(11)] for y in range(enabled_count)]
-                                    subint_index = 0
-
-                                    for subinterface in c:
-                                        # If the retrieved entry is not a string, it must be a dictionary, which is what we want
-                                        if not isinstance(c[subinterface], str):
-                                            subinterface_config = self.config["interfaces"][name][subinterface]
-                                            if (("interface_enabled" in subinterface_config) and subinterface_config.as_bool("interface_enabled") == True) or (("enabled" in c) and c.as_bool("enabled") == True):
-                                                subint_config[subint_index][0] = subinterface
-
-                                                subint_vport = subinterface_config["vport"] if "vport" in subinterface_config else None
-                                                subint_config[subint_index][1] = subint_vport
-
-                                                frequency = int(subinterface_config["frequency"]) if "frequency" in subinterface_config else None
-                                                subint_config[subint_index][2] = frequency
-                                                bandwidth = int(subinterface_config["bandwidth"]) if "bandwidth" in subinterface_config else None
-                                                subint_config[subint_index][3] = bandwidth
-                                                txpower = int(subinterface_config["txpower"]) if "txpower" in subinterface_config else None
-                                                subint_config[subint_index][4] = txpower
-                                                spreadingfactor = int(subinterface_config["spreadingfactor"]) if "spreadingfactor" in subinterface_config else None
-                                                subint_config[subint_index][5] = spreadingfactor 
-                                                codingrate = int(subinterface_config["codingrate"]) if "codingrate" in subinterface_config else None
-                                                subint_config[subint_index][6] = codingrate
-                                                flow_control = subinterface_config.as_bool("flow_control") if "flow_control" in subinterface_config else False
-                                                subint_config[subint_index][7] = flow_control 
-                                                st_alock = float(subinterface_config["airtime_limit_short"]) if "airtime_limit_short" in subinterface_config else None
-                                                subint_config[subint_index][8] = st_alock
-                                                lt_alock = float(subinterface_config["airtime_limit_long"]) if "airtime_limit_long" in subinterface_config else None
-                                                subint_config[subint_index][9] = lt_alock
-
-                                                if "outgoing" in subinterface_config and subinterface_config.as_bool("outgoing") == False:
-                                                    subint_config[subint_index][10] = False
-                                                else:
-                                                    subint_config[subint_index][10] = True
-                                                subint_index += 1
-
-                                    # if no subinterfaces are defined
-                                    if count == 0:
-                                        raise ValueError("No subinterfaces configured for "+name)
-                                    # if no subinterfaces are enabled
-                                    elif enabled_count == 0:
-                                        raise ValueError("No subinterfaces enabled for "+name)
-
-                                    id_interval = int(c["id_interval"]) if "id_interval" in c else None
-                                    id_callsign = c["id_callsign"] if "id_callsign" in c else None
-                                    port = c["port"] if "port" in c else None
-                                    
-                                    if port == None:
-                                        raise ValueError("No port specified for "+name)
-
-                                    interface = RNodeMultiInterface.RNodeMultiInterface(
-                                        RNS.Transport,
-                                        name,
-                                        port,
-                                        subint_config,
-                                        id_interval = id_interval,
-                                        id_callsign = id_callsign
-                                    )
-
-                                    interface.IN = False
-                                    interface.OUT = False
-
-                                    interface.mode = interface_mode
-
-                                    interface.announce_cap = announce_cap
-                                    if configured_bitrate:
-                                        interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 8
-
-
+                            def interface_post_init(interface):
                                 if interface != None:
+                                    if "outgoing" in c and c.as_bool("outgoing") == False:
+                                        interface.OUT = False
+                                    else:
+                                        interface.OUT = True
+
+                                    interface.mode = interface_mode
+                                    interface.announce_cap = announce_cap
+                                    if configured_bitrate:
+                                        interface.bitrate = configured_bitrate
+                                    if ifac_size != None:
+                                        interface.ifac_size = ifac_size
+                                    else:
+                                        interface.ifac_size = interface.DEFAULT_IFAC_SIZE
+
                                     interface.announce_rate_target = announce_rate_target
                                     interface.announce_rate_grace = announce_rate_grace
                                     interface.announce_rate_penalty = announce_rate_penalty
@@ -1103,8 +622,102 @@ class Reticulum:
 
                                     RNS.Transport.interfaces.append(interface)
 
-                                    if isinstance(interface, RNS.Interfaces.RNodeMultiInterface.RNodeMultiInterface):
-                                        interface.start()
+                            interface = None
+                            if (("interface_enabled" in c) and c.as_bool("interface_enabled") == True) or (("enabled" in c) and c.as_bool("enabled") == True):
+                                interface_config = c
+                                interface_config["name"] = name
+                                interface_config["selected_interface_mode"] = interface_mode
+                                interface_config["configured_bitrate"] = configured_bitrate
+
+                                if c["type"] == "AutoInterface":
+                                    interface = AutoInterface.AutoInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "UDPInterface":
+                                    interface = UDPInterface.UDPInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "TCPServerInterface":
+                                    if interface_mode == Interface.Interface.MODE_ACCESS_POINT:
+                                        RNS.log(str(interface)+" does not support Access Point mode, reverting to default mode: Full", RNS.LOG_WARNING)
+                                        interface_mode = Interface.Interface.MODE_FULL
+
+                                    interface = TCPInterface.TCPServerInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "TCPClientInterface":
+                                    if interface_mode == Interface.Interface.MODE_ACCESS_POINT:
+                                        RNS.log(str(interface)+" does not support Access Point mode, reverting to default mode: Full", RNS.LOG_WARNING)
+                                        interface_mode = Interface.Interface.MODE_FULL
+                                    
+                                    interface = TCPInterface.TCPClientInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "I2PInterface":
+                                    if interface_mode == Interface.Interface.MODE_ACCESS_POINT:
+                                        RNS.log(str(interface)+" does not support Access Point mode, reverting to default mode: Full", RNS.LOG_WARNING)
+                                        interface_mode = Interface.Interface.MODE_FULL
+
+                                    interface_config["storagepath"] = Reticulum.storagepath
+                                    interface_config["ifac_netname"] = ifac_netname
+                                    interface_config["ifac_netkey"] = ifac_netkey
+                                    interface_config["ifac_size"] = ifac_size
+
+                                    interface = I2PInterface.I2PInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "SerialInterface":
+                                    interface = SerialInterface.SerialInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "PipeInterface":
+                                    interface = PipeInterface.PipeInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "KISSInterface":
+                                    interface = KISSInterface.KISSInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "AX25KISSInterface":
+                                    interface = AX25KISSInterface.AX25KISSInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "RNodeInterface":
+                                    interface = RNodeInterface.RNodeInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+
+                                if c["type"] == "RNodeMultiInterface":
+                                    interface = RNodeMultiInterface.RNodeMultiInterface(RNS.Transport, interface_config)
+                                    interface_post_init(interface)
+                                    interface.start()
+
+                                if interface == None:
+                                    # Interface was not handled by any internal interface types,
+                                    # attempt to load and initialise it from user-supplied modules
+                                    interface_type = c["type"]
+                                    interface_file = f"{interface_type}.py"
+                                    interface_path = os.path.join(self.interfacepath, interface_file)
+                                    if not os.path.isfile(interface_path):
+                                        RNS.log(f"Could not locate external interface module \"{interface_file}\" in \"{self.interfacepath}\"", RNS.LOG_ERROR)
+                                    
+                                    else:
+                                        try:
+                                            RNS.log(f"Loading external interface \"{interface_file}\" from \"{self.interfacepath}\"", RNS.LOG_NOTICE)
+                                            interface_globals = {}
+                                            interface_globals["Interface"] = Interface.Interface
+                                            interface_globals["RNS"] = RNS
+                                            with open(interface_path) as class_file:
+                                                interface_code = class_file.read()
+                                                exec(interface_code, interface_globals)
+                                                interface_class = interface_globals["interface_class"]
+                                                
+                                                if interface_class != None:
+                                                    interface = interface_class(RNS.Transport, interface_config)
+                                                    interface_post_init(interface)
+
+                                        except Exception as e:
+                                            RNS.log(f"External interface initialisation failed for {interface_type} / {name}", RNS.LOG_ERROR)
+                                            RNS.trace_exception(e)
 
                             else:
                                 RNS.log("Skipping disabled interface \""+name+"\"", RNS.LOG_DEBUG)
@@ -1119,7 +732,7 @@ class Reticulum:
 
             RNS.log("System interfaces are ready", RNS.LOG_VERBOSE)
 
-    def _add_interface(self,interface, mode = None, configured_bitrate=None, ifac_size=None, ifac_netname=None, ifac_netkey=None, announce_cap=None, announce_rate_target=None, announce_rate_grace=None, announce_rate_penalty=None):
+    def _add_interface(self, interface, mode = None, configured_bitrate=None, ifac_size=None, ifac_netname=None, ifac_netkey=None, announce_cap=None, announce_rate_target=None, announce_rate_grace=None, announce_rate_penalty=None):
         if not self.is_connected_to_shared_instance:
             if interface != None and issubclass(type(interface), RNS.Interfaces.Interface.Interface):
                 
@@ -1564,6 +1177,14 @@ class Reticulum:
 
             return None
 
+    def halt_interface(self, interface):
+        pass
+
+    def resume_interface(self, interface):
+        pass
+
+    def reload_interface(self, interface):
+        pass
 
     @staticmethod
     def should_use_implicit_proof():

RNS/Transport.py

@@ -743,10 +743,10 @@ class Transport:
                     i += 1
 
                 # Send it
-                interface.processOutgoing(masked_raw)
+                interface.process_outgoing(masked_raw)
 
             else:
-                interface.processOutgoing(raw)
+                interface.process_outgoing(raw)
 
         except Exception as e:
             RNS.log("Error while transmitting on "+str(interface)+". The contained exception was: "+str(e), RNS.LOG_ERROR)

RNS/Utilities/__init__.py

@@ -23,5 +23,7 @@
 import os
 import glob
 
-modules = glob.glob(os.path.dirname(__file__)+"/*.py")
-__all__ = [ os.path.basename(f)[:-3] for f in modules if not f.endswith('__init__.py')]
+py_modules  = glob.glob(os.path.dirname(__file__)+"/*.py")
+pyc_modules = glob.glob(os.path.dirname(__file__)+"/*.pyc")
+modules     = py_modules+pyc_modules
+__all__ = list(set([os.path.basename(f).replace(".pyc", "").replace(".py", "") for f in modules if not (f.endswith("__init__.py") or f.endswith("__init__.pyc"))]))

RNS/Utilities/rnstatus.py

@@ -135,8 +135,26 @@ def get_remote_status(destination_hash, include_lstats, identity, no_output=Fals
 
 def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=False, astats=False,
                   lstats=False, sorting=None, sort_reverse=False, remote=None, management_identity=None,
-                  remote_timeout=RNS.Transport.PATH_REQUEST_TIMEOUT):
-    reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity)
+                  remote_timeout=RNS.Transport.PATH_REQUEST_TIMEOUT, must_exit=True, rns_instance=None):
+    
+    if remote:
+        require_shared = False
+    else:
+        require_shared = True
+
+    try:
+        if rns_instance:
+            reticulum = rns_instance
+            must_exit = False
+        else:
+            reticulum = RNS.Reticulum(configdir=configdir, loglevel=3+verbosity, require_shared_instance=require_shared)
+
+    except Exception as e:
+        print("No shared RNS instance available to get status from")
+        if must_exit:
+            exit(1)
+        else:
+            return
 
     link_count = None
     stats = None
@@ -164,7 +182,10 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                     
         except Exception as e:
             print(str(e))
-            exit(20)
+            if must_exit:
+                exit(20)
+            else:
+                return
 
     else:
         if lstats:
@@ -193,7 +214,10 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                                     i[k] = RNS.hexrep(i[k], delimit=False)
 
             print(json.dumps(stats))
-            exit()
+            if must_exit:
+                exit()
+            else:
+                return
 
         interfaces = stats["interfaces"]
         if sorting != None and isinstance(sorting, str):
@@ -364,9 +388,12 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
             print("Could not get RNS status")
         else:
             print("Could not get RNS status from remote transport instance "+RNS.prettyhexrep(identity_hash))
-        exit(1)
+        if must_exit:
+            exit(2)
+        else:
+            return
 
-def main():
+def main(must_exit=True, rns_instance=None):
     try:
         parser = argparse.ArgumentParser(description="Reticulum Network Stack Status")
         parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
@@ -472,11 +499,16 @@ def main():
             remote=args.R,
             management_identity=args.i,
             remote_timeout=args.w,
+            must_exit=must_exit,
+            rns_instance=rns_instance,
         )
 
     except KeyboardInterrupt:
         print("")
-        exit()
+        if must_exit:
+            exit()
+        else:
+            return
 
 def speed_str(num, suffix='bps'):
     units = ['','k','M','G','T','P','E','Z']

RNS/__init__.py

@@ -43,8 +43,10 @@ from .Resource import Resource, ResourceAdvertisement
 from .Cryptography import HKDF
 from .Cryptography import Hashes
 
-modules = glob.glob(os.path.dirname(__file__)+"/*.py")
-__all__ = [ os.path.basename(f)[:-3] for f in modules if not f.endswith('__init__.py')]
+py_modules  = glob.glob(os.path.dirname(__file__)+"/*.py")
+pyc_modules = glob.glob(os.path.dirname(__file__)+"/*.pyc")
+modules     = py_modules+pyc_modules
+__all__ = list(set([os.path.basename(f).replace(".pyc", "").replace(".py", "") for f in modules if not (f.endswith("__init__.py") or f.endswith("__init__.pyc"))]))
 
 LOG_CRITICAL = 0
 LOG_ERROR    = 1
@@ -57,12 +59,14 @@ LOG_EXTREME  = 7
 
 LOG_STDOUT   = 0x91
 LOG_FILE     = 0x92
+LOG_CALLBACK = 0x93
 
 LOG_MAXSIZE  = 5*1024*1024
 
 loglevel        = LOG_NOTICE
 logfile         = None
 logdest         = LOG_STDOUT
+logcall         = None
 logtimefmt      = "%Y-%m-%d %H:%M:%S"
 compact_log_fmt = False
 
@@ -138,6 +142,17 @@ def log(msg, level=3, _override_destination = False):
                 log("Exception occurred while writing log message to log file: "+str(e), LOG_CRITICAL)
                 log("Dumping future log events to console!", LOG_CRITICAL)
                 log(msg, level)
+
+        elif logdest == LOG_CALLBACK:
+            try:
+                logcall(logstring)
+                logging_lock.release()
+            except Exception as e:
+                logging_lock.release()
+                _always_override_destination = True
+                log("Exception occurred while calling external log handler: "+str(e), LOG_CRITICAL)
+                log("Dumping future log events to console!", LOG_CRITICAL)
+                log(msg, level)
                 
 
 def rand():

RNS/_version.py

@@ -1 +1 @@
-__version__ = "0.8.5"
+__version__ = "0.8.7"

RNS/vendor/__init__.py

@@ -1,5 +1,7 @@
 import os
 import glob
 
-modules = glob.glob(os.path.dirname(__file__)+"/*.py")
-__all__ = [ os.path.basename(f)[:-3] for f in modules if not f.endswith('__init__.py')]
+py_modules  = glob.glob(os.path.dirname(__file__)+"/*.py")
+pyc_modules = glob.glob(os.path.dirname(__file__)+"/*.pyc")
+modules     = py_modules+pyc_modules
+__all__ = list(set([os.path.basename(f).replace(".pyc", "").replace(".py", "") for f in modules if not (f.endswith("__init__.py") or f.endswith("__init__.pyc"))]))

docs/manual/.buildinfo

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

docs/manual/_sources/examples.rst.txt

@@ -125,4 +125,18 @@ interface to efficiently pass files of any size over a Reticulum :ref:`Link<api-
 
 .. literalinclude:: ../../Examples/Filetransfer.py
 
-This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py>`_.
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py>`_.
+
+.. _example-custominterface:
+
+Custom Interfaces
+=================
+
+The *ExampleInterface* demonstrates creating custom interfaces for Reticulum.
+Any number of custom interfaces can be loaded and utilised by Reticulum, and
+will be fully on-par with natively included interfaces, including all supported
+:ref:`interface modes<interfaces-modes>` and :ref:`common configuration options<interfaces-options>`.
+
+.. literalinclude:: ../../Examples/ExampleInterface.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/ExampleInterface.py>`_.

docs/manual/_sources/gettingstartedfast.rst.txt

@@ -27,9 +27,14 @@ and install them offline using ``pip``:
 
    pip install ./rns-0.5.1-py3-none-any.whl
 
+For more detailed installation instructions, please see the
+:ref:`Platform-Specific Install Notes<install-guides>` section.
+
+After installation is complete, it might be helpful to refer to the
+:ref:`Using Reticulum on Your System<using-main>` chapter.
 
 Resolving Dependency & Installation Issues
-=============================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 On some platforms, there may not be binary packages available for all dependencies, and
 ``pip`` installation may fail with an error message. In these cases, the issue can usually
 be resolved by installing the development essentials packages for your platform:
@@ -100,10 +105,12 @@ You can install Nomad Network via pip:
    # ... and run
    nomadnet
 
-**Please Note**: If this is the very first time you use pip to install a program
-on your system, you might need to reboot your system for your program to become
-available. If you get a "command not found" error or similar when running the
-program, reboot your system and try again.
+.. note::
+   If this is the very first time you use ``pip`` to install a program
+   on your system, you might need to reboot your system for your program to become
+   available. If you get a "command not found" error or similar when running the
+   program, reboot your system and try again. In some cases, you may even need to
+   manually add the ``pip`` install path to your ``PATH`` environment variable.
 
 Sideband
 ^^^^^^^^
@@ -305,6 +312,20 @@ you are welcome to head over to the `GitHub discussion pages <https://github.com
 and propose adding an interface for the hardware.
 
 
+Creating and Using Custom Interfaces
+===========================================
+
+While Reticulum includes a flexible and broad range of built-in interfaces, these
+will not cover every conceivable type of communications hardware that Reticulum
+can potentially use to communicate.
+
+It is therefore possible to easily write your own interface modules, that can be
+loaded at run-time and used on-par with any of the built-in interface types.
+
+For more information on this subject, and code examples to build on, please see
+the :ref:`Configuring Interfaces<interfaces-main>` chapter.
+
+
 Develop a Program with Reticulum
 ===========================================
 If you want to develop programs that use Reticulum, the easiest way to get
@@ -318,14 +339,8 @@ The above command will install Reticulum and dependencies, and you will be
 ready to import and use RNS in your own programs. The next step will most
 likely be to look at some :ref:`Example Programs<examples-main>`.
 
-For extended functionality, you can install optional dependencies:
-
-.. code::
-
-   pip install pyserial
-
-
-Further information can be found in the :ref:`API Reference<api-main>`.
+The entire Reticulum API is documented in the :ref:`API Reference<api-main>`
+chapter of this manual.
 
 
 Participate in Reticulum Development
@@ -373,6 +388,7 @@ your first pull request, it is probably a good idea to introduce yourself on
 the `disucssion forum on GitHub <https://github.com/markqvist/Reticulum/discussions>`_,
 or ask one of the developers or maintainers for a good place to start.
 
+.. _install-guides:
 
 Platform-Specific Install Notes
 ==============================================
@@ -451,7 +467,7 @@ here at a later point. Until then you can use the `Sideband source code <https:/
 ARM64
 ^^^^^^^^^^^^^^^^^^^^^^^^
 On some architectures, including ARM64, not all dependencies have precompiled
-binaries. On such systems, you may need to install ``python3-dev`` before
+binaries. On such systems, you may need to install ``python3-dev`` (or similar) before
 installing Reticulum or programs that depend on Reticulum.
 
 .. code::
@@ -463,16 +479,8 @@ installing Reticulum or programs that depend on Reticulum.
    # Install Reticulum
    python3 -m pip install rns
 
-
-Raspberry Pi
-^^^^^^^^^^^^^^^^^^^^^^^^^
-It is currently recommended to use a 64-bit version of the Raspberry Pi OS
-if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
-don't always have packages available for some dependencies.
-
-While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
-it will require manually configuring and installing some packages, and is not
-detailed in this manual.
+With these packages installed, ``pip`` will be able to build any missing dependencies
+on your system locally.
 
 
 Debian Bookworm
@@ -503,10 +511,152 @@ following section:
     [global]
     break-system-packages = true
 
-Please note that the "break-system-packages" directive is a somewhat misleading choice
-of words. Setting it will of course not break any system packages, but will simply
-allow installing ``pip`` packages user- and system-wide. While this *could* in rare
-cases lead to version conflicts, it does not generally pose any problems.
+For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages``
+option, you can use the following command:
+
+.. code:: text
+
+    pip install rns --break-system-packages
+
+.. note::
+   The ``--break-system-packages`` directive is a somewhat misleading choice
+   of words. Setting it will of course not break any system packages, but will simply
+   allow installing ``pip`` packages user- and system-wide. While this *could* in rare
+   cases lead to version conflicts, it does not generally pose any problems, especially
+   not in the case of installing Reticulum.
+
+
+MacOS
+^^^^^^^^^^^^^^^^^^^^^^^^^
+To install Reticulum on macOS, you will need to have Python and the ``pip`` package
+manager installed.
+
+Systems running macOS can vary quite widely in whether or not Python is pre-installed,
+and if it is, which version is installed, and whether the ``pip`` package manager is
+also installed and set up. If in doubt, you can `download and install <https://www.python.org/downloads/>`_
+Python manually.
+
+When Python and ``pip`` is available on your system, simply open a terminal window
+and use one of the following commands:
+
+.. code::
+
+   # Install Reticulum and utilities with pip:
+   pip3 install rns
+   
+   # On some versions, you may need to use the
+   # flag --break-system-packages to install:
+   pip3 install rns --break-system-packages
+
+.. note::
+   The ``--break-system-packages`` directive is a somewhat misleading choice
+   of words. Setting it will of course not break any system packages, but will simply
+   allow installing ``pip`` packages user- and system-wide. While this *could* in rare
+   cases lead to version conflicts, it does not generally pose any problems, especially
+   not in the case of installing Reticulum.
+
+Additionally, some version combinations of macOS and Python require you to
+manually add your installed ``pip`` packages directory to your `PATH` environment
+variable, before you can use installed commands in your terminal. Usually, adding
+the following line to your shell init script (for example ``~/.zshrc``) will be enough:
+
+.. code::
+
+   export PATH=$PATH:~/Library/Python/3.9/bin
+
+Adjust Python version and shell init script location according to your system.
+
+
+OpenWRT
+^^^^^^^^^^^^^^^^^^^^^^^^^
+On OpenWRT systems with sufficient storage and memory, you can install
+Reticulum and related utilities using the `opkg` package manager and `pip`.
+
+.. note::
+
+   At the time of releasing this manual, work is underway to create pre-built
+   Reticulum packages for OpenWRT, with full configuration, service
+   and ``uci`` integration. Please see the `feed-reticulum <https://github.com/gretel/feed-reticulum>`_
+   and `reticulum-openwrt <https://github.com/gretel/reticulum-openwrt>`_
+   repositories for more information.
+
+To install Reticulum on OpenWRT, first log into a command line session, and
+then use the following instructions:
+
+.. code::
+
+   # Install dependencies
+   opkg install python3 python3-pip python3-cryptography python3-pyserial
+   
+   # Install Reticulum
+   pip install rns
+
+   # Start rnsd with debug logging enabled
+   rnsd -vvv
+
+.. note::
+   
+   The above instructions have been verified and tested on OpenWRT 21.02 only.
+   It is likely that other versions may require slightly altered installation
+   commands or package names. You will also need enough free space in your
+   overlay FS, and enough free RAM to actually run Reticulum and any related
+   programs and utilities.
+
+Depending on your device configuration, you may need to adjust firewall rules
+for Reticulum connectivity to and from your device to work. Until proper
+packaging is ready, you will also need to manually create a service or startup
+script to automatically laucnh Reticulum at boot time.
+
+Please also note that the `AutoInterface` requires link-local IPv6 addresses
+to be enabled for any Ethernet and WiFi devices you intend to use. If ``ip a``
+shows an address starting with ``fe80::`` for the device in question,
+``AutoInterface`` should work for that device.
+
+Raspberry Pi
+^^^^^^^^^^^^^^^^^^^^^^^^^
+It is currently recommended to use a 64-bit version of the Raspberry Pi OS
+if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
+don't always have packages available for some dependencies. If Python and the
+`pip` package manager is not already installed, do that first, and then
+install Reticulum using `pip`.
+
+.. code::
+
+   # Install dependencies
+   sudo apt install python3 python3-pip python3-cryptography python3-pyserial
+   
+   # Install Reticulum
+   pip install rns --break-system-packages
+
+.. note::
+   The ``--break-system-packages`` directive is a somewhat misleading choice
+   of words. Setting it will of course not break any system packages, but will simply
+   allow installing ``pip`` packages user- and system-wide. While this *could* in rare
+   cases lead to version conflicts, it does not generally pose any problems, especially
+   not in the case of installing Reticulum.
+
+While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
+it will require manually configuring and installing required build dependencies,
+and is not detailed in this manual.
+
+
+RISC-V
+^^^^^^^^^^^^^^^^^^^^^^^^
+On some architectures, including RISC-V, not all dependencies have precompiled
+binaries. On such systems, you may need to install ``python3-dev`` (or similar) before
+installing Reticulum or programs that depend on Reticulum.
+
+.. code::
+
+   # Install Python and development packages
+   sudo apt update
+   sudo apt install python3 python3-pip python3-dev
+
+   # Install Reticulum
+   python3 -m pip install rns
+
+With these packages installed, ``pip`` will be able to build any missing dependencies
+on your system locally.
 
 
 Ubuntu Lunar
@@ -537,13 +687,52 @@ following section:
     [global]
     break-system-packages = true
 
-Please note that the "break-system-packages" directive is a somewhat misleading choice
-of words. Setting it will of course not break any system packages, but will simply
-allow installing ``pip`` packages user- and system-wide. While this _could_ in rare
-cases lead to version conflicts, it does not generally pose any problems.
+For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages``
+option, you can use the following command:
+
+.. code:: text
+
+    pip install rns --break-system-packages
+
+.. note::
+   The ``--break-system-packages`` directive is a somewhat misleading choice
+   of words. Setting it will of course not break any system packages, but will simply
+   allow installing ``pip`` packages user- and system-wide. While this *could* in rare
+   cases lead to version conflicts, it does not generally pose any problems, especially
+   not in the case of installing Reticulum.
+
+Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^
+On Windows operating systems, the easiest way to install Reticulum is by using the
+``pip`` package manager from the command line (either the command prompt or Windows
+Powershell).
+
+If you don't already have Python installed, `download and install Python <https://www.python.org/downloads/>`_.
+At the time of publication of this manual, the recommended version is `Python 3.12.7 <https://www.python.org/downloads/release/python-3127>`_.
+
+**Important!** When asked by the installer, make sure to add the Python program to
+your PATH environment variables. If you don't do this, you will not be able to
+use the ``pip`` installer, or run the included Reticulum utility programs (such as
+``rnsd`` and ``rnstatus``) from the command line.
+
+After installing Python, open the command prompt or Windows Powershell, and type:
+
+.. code::
+
+   pip install rns
+
+You can now use Reticulum and all included utility programs directly from your
+preferred command line interface.
 
 Pure-Python Reticulum
 ==============================================
+
+.. warning::
+   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.
+
 In some rare cases, and on more obscure system types, it is not possible to
 install one or more dependencies. In such situations,
 you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip``
@@ -558,8 +747,3 @@ only if they are *needed* and *available*. If for example you want to use Reticu
 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 <https://github.com/pyca/cryptography>`_, it is
-important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>`
-section of this manual.

docs/manual/_sources/hardware.rst.txt

@@ -75,8 +75,8 @@ completely from scratch, to your exact desired specifications, this chapter
 will explain the easiest possible approach to creating RNodes: 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
+1. Obtain one or more :ref:`supported development boards<rnode-supported>`
+2. Install the RNode firmware with the :ref:`automated installer<rnode-installation>`
 
 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.
@@ -85,8 +85,8 @@ to the configuration.
 
 .. _rnode-supported:
 
-Supported Boards
-^^^^^^^^^^^^^^^^
+Supported Boards and Devices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 To create one or more RNodes, you will need to obtain supported development
 boards. The following boards are supported by the auto-installer.
 

docs/manual/_sources/interfaces.rst.txt

@@ -19,6 +19,16 @@ types, have a look at the :ref:`Building Networks<networks-main>` chapter of thi
 manual.
 
 
+.. _interfaces-custom:
+
+Custom Interfaces
+=================
+
+In addition to the built-in interface types, Reticulum is **fully extensible** with
+custom, user- or community-supplied interfaces, and creating custom interface
+modules is straightforward. Please see the :ref:`custom interface<example-custominterface>`
+example for basic interface code to build upon.
+
 .. _interfaces-auto:
 
 Auto Interface
@@ -152,11 +162,12 @@ It can take anywhere from a few seconds to a few minutes to establish
 I2P connections to the desired peers, so Reticulum handles the process
 in the background, and will output relevant events to the log.
 
-**Please Note!** While the I2P interface is the simplest way to use
-Reticulum over I2P, it is also possible to tunnel the TCP server and
-client interfaces over I2P manually. This can be useful in situations
-where more control is needed, but requires manual tunnel setup through
-the I2P daemon configuration.
+.. note::
+   While the I2P interface is the simplest way to use
+   Reticulum over I2P, it is also possible to tunnel the TCP server and
+   client interfaces over I2P manually. This can be useful in situations
+   where more control is needed, but requires manual tunnel setup through
+   the I2P daemon configuration.
 
 It is important to note that the two methods are *interchangably compatible*.
 You can use the I2PInterface to connect to a TCPServerInterface that
@@ -171,7 +182,7 @@ TCP Server Interface
 ====================
 
 The TCP Server interface is suitable for allowing other peers to connect over
-the Internet or private IP networks. When a TCP server interface has been
+the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been
 configured, other Reticulum peers can connect to it with a TCP Client interface.
 
 .. code::
@@ -200,8 +211,37 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
     # device = eth0
     # port = 4242
 
-**Please Note!** The TCP interfaces support tunneling over I2P, but to do so reliably,
-you must use the i2p_tunneled option:
+If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
+you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
+
+.. code::
+
+  # This example demonstrates a TCP server interface.
+  # It will listen for incoming connections on the
+  # specified IP address and port number.
+  
+  [[TCP Server Interface]]
+    type = TCPServerInterface
+    interface_enabled = True
+
+    device = eth0
+    port = 4242
+    prefer_ipv6 = True
+
+To use the TCP Server Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you
+can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
+
+.. code::
+
+  [[Yggdrasil TCP Server Interface]]
+      type = TCPServerInterface
+      interface_enabled = yes
+      device = tun0
+      listen_port = 4343
+
+.. note::
+   The TCP interfaces support tunneling over I2P, but to do so reliably,
+   you must use the i2p_tunneled option:
 
 .. code::
 
@@ -231,7 +271,7 @@ and restore connectivity after a failure, once the other end of a TCP interface
 .. code::
 
   # Here's an example of a TCP Client interface. The
-  # target_host can either be an IP address or a hostname.
+  # target_host can be a hostname or an IPv4 or IPv6 address.
 
   [[TCP Client Interface]]
     type = TCPClientInterface
@@ -239,6 +279,17 @@ and restore connectivity after a failure, once the other end of a TCP interface
     target_host = 127.0.0.1
     target_port = 4242
 
+To use the TCP Client Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, simply
+specify the target Yggdrasil IPv6 address and port, like so:
+
+.. code::
+
+  [[Yggdrasil TCP Client Interface]]
+      type = TCPClientInterface
+      interface_enabled = yes
+      target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5
+      target_port = 4343
+
 It is also possible to use this interface type to connect via other programs
 or hardware devices that expose a KISS interface on a TCP port, for example
 software-based soundmodems. To do this, use the ``kiss_framing`` option:
@@ -262,8 +313,9 @@ never enable ``kiss_framing``, since this will disable internal reliability and
 recovery mechanisms that greatly improves performance over unreliable and
 intermittent TCP links.
 
-**Please Note!** The TCP interfaces support tunneling over I2P, but to do so reliably,
-you must use the i2p_tunneled option:
+.. note::
+   The TCP interfaces support tunneling over I2P, but to do so reliably,
+   you must use the i2p_tunneled option:
 
 .. code::
 
@@ -285,11 +337,12 @@ private and the internet. It can also allow broadcast communication
 over IP networks, so it can provide an easy way to enable connectivity
 with all other peers on a local area network.
 
-*Please Note!* Using broadcast UDP traffic has performance implications,
-especially on WiFi. If your goal is simply to enable easy communication
-with all peers in your local Ethernet broadcast domain, the
-:ref:`Auto Interface<interfaces-auto>` performs better, and is even
-easier to use.
+.. warning::
+   Using broadcast UDP traffic has performance implications,
+   especially on WiFi. If your goal is simply to enable easy communication
+   with all peers in your local Ethernet broadcast domain, the
+   :ref:`Auto Interface<interfaces-auto>` performs better, and is even
+   easier to use.
 
 .. code::
 
@@ -344,6 +397,11 @@ RNode LoRa Interface
 To use Reticulum over LoRa, the `RNode <https://unsigned.io/rnode/>`_ interface
 can be used, and offers full control over LoRa parameters.
 
+.. warning::
+   Radio frequency spectrum is a legally controlled resource, and legislation
+   varies widely around the world. It is your responsibility to be aware of any
+   relevant regulation for your location, and to make decisions accordingly.
+
 .. code::
 
   # Here's an example of how to add a LoRa interface
@@ -431,6 +489,11 @@ RNode Multi Interface
 For RNodes that support multiple LoRa transceivers, the RNode
 Multi interface can be used to configure sub-interfaces individually.
 
+.. warning::
+   Radio frequency spectrum is a legally controlled resource, and legislation
+   varies widely around the world. It is your responsibility to be aware of any
+   relevant regulation for your location, and to make decisions accordingly.
+
 .. code::
 
   # Here's an example of how to add an RNode Multi interface
@@ -454,89 +517,89 @@ Multi interface can be used to configure sub-interfaces individually.
   # id_interval = 600
 
     # A subinterface
-    [[[HIGHDATARATE]]]
-    # Subinterfaces can be enabled and disabled in of themselves
-    interface_enabled = True
+    [[[High Datarate]]]
+      # Subinterfaces can be enabled and disabled in of themselves
+      interface_enabled = True
 
-    # Set frequency to 2.4GHz
-    frequency = 2400000000
+      # Set frequency to 2.4GHz
+      frequency = 2400000000
 
-    # Set LoRa bandwidth to 1625 KHz
-    bandwidth = 1625000
+      # Set LoRa bandwidth to 1625 KHz
+      bandwidth = 1625000
 
-    # Set TX power to 0 dBm (0.12 mW)
-    txpower = 0
+      # Set TX power to 0 dBm (0.12 mW)
+      txpower = 0
 
-    # The virtual port, only the manufacturer
-    # or the person who wrote the board config
-    # can tell you what it will be for which
-    # physical hardware interface
-    vport = 1
+      # The virtual port, only the manufacturer
+      # or the person who wrote the board config
+      # can tell you what it will be for which
+      # physical hardware interface
+      vport = 1
 
-    # Select spreading factor 5. Valid
-    # range is 5 through 12, with 5 
-    # being the fastest and 12 having
-    # the longest range.
-    spreadingfactor = 5
+      # Select spreading factor 5. Valid
+      # range is 5 through 12, with 5 
+      # being the fastest and 12 having
+      # the longest range.
+      spreadingfactor = 5
 
-    # Select coding rate 5. Valid range
-    # is 5 throough 8, with 5 being the
-    # fastest, and 8 the longest range.
-    codingrate = 5
+      # Select coding rate 5. Valid range
+      # is 5 throough 8, with 5 being the
+      # fastest, and 8 the longest range.
+      codingrate = 5
 
-    # It is possible to limit the airtime
-    # utilisation of an RNode by using the
-    # following two configuration options.
-    # The short-term limit is applied in a
-    # window of approximately 15 seconds,
-    # and the long-term limit is enforced
-    # over a rolling 60 minute window. Both
-    # options are specified in percent.
+      # It is possible to limit the airtime
+      # utilisation of an RNode by using the
+      # following two configuration options.
+      # The short-term limit is applied in a
+      # window of approximately 15 seconds,
+      # and the long-term limit is enforced
+      # over a rolling 60 minute window. Both
+      # options are specified in percent.
 
-    # airtime_limit_long = 100
-    # airtime_limit_short = 100
+      # airtime_limit_long = 100
+      # airtime_limit_short = 100
 
-    [[[LOWDATARATE]]]
-    # Subinterfaces can be enabled and disabled in of themselves
-    interface_enabled = True
+    [[[Low Datarate]]]
+      # Subinterfaces can be enabled and disabled in of themselves
+      interface_enabled = True
 
-    # Set frequency to 865.6 MHz
-    frequency = 865600000
+      # Set frequency to 865.6 MHz
+      frequency = 865600000
 
-    # The virtual port, only the manufacturer
-    # or the person who wrote the board config
-    # can tell you what it will be for which
-    # physical hardware interface
-    vport = 0
+      # The virtual port, only the manufacturer
+      # or the person who wrote the board config
+      # can tell you what it will be for which
+      # physical hardware interface
+      vport = 0
 
-    # Set LoRa bandwidth to 125 KHz
-    bandwidth = 125000
+      # Set LoRa bandwidth to 125 KHz
+      bandwidth = 125000
 
-    # Set TX power to 0 dBm (0.12 mW)
-    txpower = 0
+      # Set TX power to 0 dBm (0.12 mW)
+      txpower = 0
 
-    # Select spreading factor 7. Valid
-    # range is 5 through 12, with 5 
-    # being the fastest and 12 having
-    # the longest range.
-    spreadingfactor = 7
+      # Select spreading factor 7. Valid
+      # range is 5 through 12, with 5 
+      # being the fastest and 12 having
+      # the longest range.
+      spreadingfactor = 7
 
-    # Select coding rate 5. Valid range
-    # is 5 throough 8, with 5 being the
-    # fastest, and 8 the longest range.
-    codingrate = 5
+      # Select coding rate 5. Valid range
+      # is 5 throough 8, with 5 being the
+      # fastest, and 8 the longest range.
+      codingrate = 5
 
-    # It is possible to limit the airtime
-    # utilisation of an RNode by using the
-    # following two configuration options.
-    # The short-term limit is applied in a
-    # window of approximately 15 seconds,
-    # and the long-term limit is enforced
-    # over a rolling 60 minute window. Both
-    # options are specified in percent.
+      # It is possible to limit the airtime
+      # utilisation of an RNode by using the
+      # following two configuration options.
+      # The short-term limit is applied in a
+      # window of approximately 15 seconds,
+      # and the long-term limit is enforced
+      # over a rolling 60 minute window. Both
+      # options are specified in percent.
 
-    # airtime_limit_long = 100
-    # airtime_limit_short = 100
+      # airtime_limit_long = 100
+      # airtime_limit_short = 100
 
 .. _interfaces-serial:
 
@@ -598,6 +661,11 @@ radio modems and TNCs, including `OpenModem <https://unsigned.io/openmodem/>`_.
 KISS interfaces can also be configured to periodically send out beacons
 for station identification purposes.
 
+.. warning::
+   Radio frequency spectrum is a legally controlled resource, and legislation
+   varies widely around the world. It is your responsibility to be aware of any
+   relevant regulation for your location, and to make decisions accordingly.
+
 .. code::
 
   [[Packet Radio KISS Interface]]
@@ -661,6 +729,11 @@ encapsulate in AX.25.
 A more efficient way is to use the plain KISS interface with the
 beaconing functionality described above.
 
+.. warning::
+   Radio frequency spectrum is a legally controlled resource, and legislation
+   varies widely around the world. It is your responsibility to be aware of any
+   relevant regulation for your location, and to make decisions accordingly.
+
 .. code::
 
   [[Packet Radio AX.25 KISS Interface]]

docs/manual/_sources/support.rst.txt

@@ -32,7 +32,9 @@ 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, telemetry, error
+improvement of Reticulum.
+
+Absolutely no automated analytics, telemetry, error
 reporting or statistics is collected and reported by Reticulum under any
 circumstances, so we rely on old-fashioned human feedback.
 

docs/manual/_sources/understanding.rst.txt

@@ -868,13 +868,17 @@ both on general-purpose CPUs and on microcontrollers. The necessary primitives a
 
 * HKDF for key derivation
 
-* Modified Fernet for encrypted tokens
+* Encrypted tokens are based on the Fernet spec
 
-  * AES-128 in CBC mode
+  * Ephemeral keys derived from an ECDH key exchange on Curve25519
 
-  * HMAC for message authentication
+  * AES-128 in CBC mode with PKCS7 padding
 
-  * No Version and Timestamp metadata included
+  * HMAC using SHA256 for message authentication
+
+  * IVs are generated through os.urandom()
+
+  * No Fernet version and timestamp metadata fields
 
 * SHA-256
 
@@ -884,12 +888,12 @@ In the default installation configuration, the ``X25519``, ``Ed25519`` and ``AES
 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
+``Token`` 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/Token.py``
 - ``RNS/Cryptography/PKCS7.py``
 
 
@@ -900,6 +904,7 @@ with the OpenSSL backend being *much* faster. The most important consequence how
 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.
+.. warning::
+   If you want to use the internal pure-python primitives, it is **highly advisable** that you
+   have a good understanding of the risks that this pose, and make an informed decision on whether
+   those risks are acceptable to you.

docs/manual/_sources/whatis.rst.txt

@@ -17,7 +17,7 @@ Reticulum enables secure digital communication that cannot be subjected to
 outside control, manipulation or censorship.
 
 Reticulum enables the construction of both small and potentially planetary-scale
-networks, without any need for hierarchical or beaureucratic structures to control
+networks, without any need for hierarchical or bureaucratic structures to control
 or manage them, while ensuring individuals and communities full sovereignty
 over their own network segments.
 
@@ -43,19 +43,30 @@ considered complete and stable at the moment, but could change if absolutely war
 
 What does Reticulum Offer?
 ==========================
+
 * Coordination-less globally unique addressing and identification
 
-* Fully self-configuring multi-hop routing
+* Fully self-configuring multi-hop routing over heterogeneous carriers
 
-* Complete initiator anonymity, communicate without revealing your identity
+* Flexible scalability over heterogeneous topologies
 
-* Asymmetric encryption based on X25519, and Ed25519 signatures as a basis for all communication
+  * Reticulum can carry data over any mixture of physical mediums and topologies
 
-* Forward Secrecy by using ephemeral Elliptic Curve Diffie-Hellman keys on Curve25519
+  * Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks
 
-* Reticulum uses a modified version of the `Fernet <https://github.com/fernet/spec/blob/master/Spec.md>`_ specification for on-the-wire / over-the-air encryption
+* Initiator anonymity, communicate without revealing your identity
 
-  * Keys are ephemeral and derived from an ECDH key exchange on Curve25519
+  * Reticulum does not include source addresses on any packets
+
+* Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
+
+  * The foundational Reticulum Identity Keys are 512-bit Elliptic Curve keysets
+
+* Forward Secrecy is available for all communication types, both for single packets and over links
+
+* Reticulum uses the following format for encrypted tokens:
+
+  * Ephemeral per-packet and link keys and derived from an ECDH key exchange on Curve25519
 
   * AES-128 in CBC mode with PKCS7 padding
 
@@ -63,13 +74,33 @@ What does Reticulum Offer?
 
   * IVs are generated through os.urandom()
 
-  * No Version and Timestamp metadata included
-
 * Unforgeable packet delivery confirmations
 
-* A variety of supported interface types
+* Flexible and extensible interface system
 
-* An intuitive and developer-friendly API
+  * Reticulum includes a large variety of built-in interface types
+
+  * Ability to load and utilise custom user- or community-supplied interface types
+
+  * Easily create your own custom interfaces for communicating over anything
+
+* Authentication and virtual network segmentation on all supported interface types
+
+* An intuitive and easy-to-use API
+
+  * Simpler and easier to use than sockets APIs and simpler, but more powerful
+
+  * Makes building distributed and decentralised applications much simpler
+
+* Reliable and efficient transfer of arbitrary amounts of data
+
+  * Reticulum can handle a few bytes of data or files of many gigabytes
+
+  * Sequencing, compression, transfer coordination and checksumming are automatic
+
+  * The API is very easy to use, and provides transfer progress
+
+* Lightweight, flexible and expandable Request/Response mechanism
 
 * Efficient link establishment
 
@@ -77,17 +108,7 @@ What does Reticulum Offer?
 
   * Low cost of keeping links open at only 0.44 bits per second
 
-* Reliable and efficient transfer of arbitrary amounts of data
-
-  * Reticulum can handle a few bytes of data or files of many gigabytes
-
-  * Sequencing, transfer coordination and checksumming is automatic
-
-  * The API is very easy to use, and provides transfer progress
-
-* Authentication and virtual network segmentation on all supported interface types
-
-* Flexible scalability allowing extremely low-bandwidth networks to co-exist and interoperate with large, high-bandwidth networks
+* Reliable sequential delivery with Channel and Buffer mechanisms
 
 
 Where can Reticulum be Used?
@@ -118,7 +139,7 @@ network, and vice versa.
 
 Interface Types and Devices
 ===========================
-Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it's relatively simple to implement an interface class. Currently, Reticulum can use the following devices and communication mediums:
+Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it's simple to :ref:`implement an interface class<example-custominterface>`. Currently, Reticulum can use the following devices and communication mediums:
 
 * Any Ethernet device
 
@@ -168,4 +189,4 @@ such. While it has been built with cryptography best-practices very foremost in
 mind, it has not yet been externally security audited, and there could very well be
 privacy-breaking bugs. To be considered secure, Reticulum needs a thorough
 security review by independent cryptographers and security researchers. If you
-want to help out with this, or can help sponsor an audit, please do get in touch.
+want to help out with this, or can help sponsor an audit, please do get in touch.

docs/manual/_static/documentation_options.js

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

docs/manual/examples.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Support Reticulum" href="support.html" /><link rel="prev" title="Building Networks" href="networks.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Code Examples - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>Code Examples - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -3241,6 +3241,315 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
 </div>
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py</a>.</p>
 </section>
+<section id="custom-interfaces">
+<span id="example-custominterface"></span><h2>Custom Interfaces<a class="headerlink" href="#custom-interfaces" title="Permalink to this heading">#</a></h2>
+<p>The <em>ExampleInterface</em> demonstrates creating custom interfaces for Reticulum.
+Any number of custom interfaces can be loaded and utilised by Reticulum, and
+will be fully on-par with natively included interfaces, including all supported
+<a class="reference internal" href="interfaces.html#interfaces-modes"><span class="std std-ref">interface modes</span></a> and <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">common configuration options</span></a>.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># MIT License - Copyright (c) 2024 Mark Qvist / unsigned.io</span>
+
+<span class="c1"># This example illustrates creating a custom interface</span>
+<span class="c1"># definition, that can be loaded and used by Reticulum at</span>
+<span class="c1"># runtime. Any number of custom interfaces can be created</span>
+<span class="c1"># and loaded. To use the interface place it in the folder</span>
+<span class="c1"># ~/.reticulum/interfaces, and add an interface entry to</span>
+<span class="c1"># your Reticulum configuration file similar to this:</span>
+
+<span class="c1">#  [[Example Custom Interface]]</span>
+<span class="c1">#    type = ExampleInterface</span>
+<span class="c1">#    enabled = no</span>
+<span class="c1">#    mode = gateway</span>
+<span class="c1">#    port = /dev/ttyUSB0</span>
+<span class="c1">#    speed = 115200</span>
+<span class="c1">#    databits = 8</span>
+<span class="c1">#    parity = none</span>
+<span class="c1">#    stopbits = 1</span>
+
+<span class="kn">from</span> <span class="nn">time</span> <span class="kn">import</span> <span class="n">sleep</span>
+<span class="kn">import</span> <span class="nn">sys</span>
+<span class="kn">import</span> <span class="nn">threading</span>
+<span class="kn">import</span> <span class="nn">time</span>
+
+<span class="c1"># This HDLC helper class is used by the interface</span>
+<span class="c1"># to delimit and packetize data over the physical</span>
+<span class="c1"># medium - in this case a serial connection.</span>
+<span class="k">class</span> <span class="nc">HDLC</span><span class="p">():</span>
+    <span class="c1"># This example interface packetizes data using</span>
+    <span class="c1"># simplified HDLC framing, similar to PPP</span>
+    <span class="n">FLAG</span>     <span class="o">=</span> <span class="mh">0x7E</span>
+    <span class="n">ESC</span>      <span class="o">=</span> <span class="mh">0x7D</span>
+    <span class="n">ESC_MASK</span> <span class="o">=</span> <span class="mh">0x20</span>
+
+    <span class="nd">@staticmethod</span>
+    <span class="k">def</span> <span class="nf">escape</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
+        <span class="n">data</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="nb">bytes</span><span class="p">([</span><span class="n">HDLC</span><span class="o">.</span><span class="n">ESC</span><span class="p">]),</span> <span class="nb">bytes</span><span class="p">([</span><span class="n">HDLC</span><span class="o">.</span><span class="n">ESC</span><span class="p">,</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">ESC</span><span class="o">^</span><span class="n">HDLC</span><span class="o">.</span><span class="n">ESC_MASK</span><span class="p">]))</span>
+        <span class="n">data</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="nb">bytes</span><span class="p">([</span><span class="n">HDLC</span><span class="o">.</span><span class="n">FLAG</span><span class="p">]),</span> <span class="nb">bytes</span><span class="p">([</span><span class="n">HDLC</span><span class="o">.</span><span class="n">ESC</span><span class="p">,</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">FLAG</span><span class="o">^</span><span class="n">HDLC</span><span class="o">.</span><span class="n">ESC_MASK</span><span class="p">]))</span>
+        <span class="k">return</span> <span class="n">data</span>
+
+<span class="c1"># Let&#39;s define our custom interface class. It must</span>
+<span class="c1"># be a sub-class of the RNS &quot;Interface&quot; class.</span>
+<span class="k">class</span> <span class="nc">ExampleInterface</span><span class="p">(</span><span class="n">Interface</span><span class="p">):</span>
+    <span class="c1"># All interface classes must define a default</span>
+    <span class="c1"># IFAC size, used in IFAC setup when the user</span>
+    <span class="c1"># has not specified a custom IFAC size. This</span>
+    <span class="c1"># option is specified in bytes.</span>
+    <span class="n">DEFAULT_IFAC_SIZE</span> <span class="o">=</span> <span class="mi">8</span>
+
+    <span class="c1"># The following properties are local to this</span>
+    <span class="c1"># particular interface implementation.</span>
+    <span class="n">owner</span>    <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">port</span>     <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">speed</span>    <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">databits</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">parity</span>   <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">stopbits</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="n">serial</span>   <span class="o">=</span> <span class="kc">None</span>
+
+    <span class="c1"># All Reticulum interfaces must have an __init__</span>
+    <span class="c1"># method that takes 2 positional arguments:</span>
+    <span class="c1"># The owner RNS Transport instance, and a dict</span>
+    <span class="c1"># of configuration values.</span>
+    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">configuration</span><span class="p">):</span>
+
+        <span class="c1"># The following lines demonstrate handling</span>
+        <span class="c1"># potential dependencies required for the</span>
+        <span class="c1"># interface to function correctly.</span>
+        <span class="kn">import</span> <span class="nn">importlib</span>
+        <span class="k">if</span> <span class="n">importlib</span><span class="o">.</span><span class="n">util</span><span class="o">.</span><span class="n">find_spec</span><span class="p">(</span><span class="s1">&#39;serial&#39;</span><span class="p">)</span> <span class="o">!=</span> <span class="kc">None</span><span class="p">:</span>
+            <span class="kn">import</span> <span class="nn">serial</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Using this interface requires a serial communication module to be installed.&quot;</span><span class="p">,</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_CRITICAL</span><span class="p">)</span>
+            <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;You can install one with the command: python3 -m pip install pyserial&quot;</span><span class="p">,</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_CRITICAL</span><span class="p">)</span>
+            <span class="n">RNS</span><span class="o">.</span><span class="n">panic</span><span class="p">()</span>
+
+        <span class="c1"># We start out by initialising the super-class</span>
+        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">()</span>
+
+        <span class="c1"># To make sure the configuration data is in the</span>
+        <span class="c1"># correct format, we parse it through the following</span>
+        <span class="c1"># method on the generic Interface class. This step</span>
+        <span class="c1"># is required to ensure compatibility on all the</span>
+        <span class="c1"># platforms that Reticulum supports.</span>
+        <span class="n">ifconf</span>    <span class="o">=</span> <span class="n">Interface</span><span class="o">.</span><span class="n">get_config_obj</span><span class="p">(</span><span class="n">configuration</span><span class="p">)</span>
+
+        <span class="c1"># Read the interface name from the configuration</span>
+        <span class="c1"># and set it on our interface instance.</span>
+        <span class="n">name</span>      <span class="o">=</span> <span class="n">ifconf</span><span class="p">[</span><span class="s2">&quot;name&quot;</span><span class="p">]</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>
+
+        <span class="c1"># We read configuration parameters from the supplied</span>
+        <span class="c1"># configuration data, and provide default values in</span>
+        <span class="c1"># case any are missing.</span>
+        <span class="n">port</span>      <span class="o">=</span> <span class="n">ifconf</span><span class="p">[</span><span class="s2">&quot;port&quot;</span><span class="p">]</span> <span class="k">if</span> <span class="s2">&quot;port&quot;</span> <span class="ow">in</span> <span class="n">ifconf</span> <span class="k">else</span> <span class="kc">None</span>
+        <span class="n">speed</span>     <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">ifconf</span><span class="p">[</span><span class="s2">&quot;speed&quot;</span><span class="p">])</span> <span class="k">if</span> <span class="s2">&quot;speed&quot;</span> <span class="ow">in</span> <span class="n">ifconf</span> <span class="k">else</span> <span class="mi">9600</span>
+        <span class="n">databits</span>  <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">ifconf</span><span class="p">[</span><span class="s2">&quot;databits&quot;</span><span class="p">])</span> <span class="k">if</span> <span class="s2">&quot;databits&quot;</span> <span class="ow">in</span> <span class="n">ifconf</span> <span class="k">else</span> <span class="mi">8</span>
+        <span class="n">parity</span>    <span class="o">=</span> <span class="n">ifconf</span><span class="p">[</span><span class="s2">&quot;parity&quot;</span><span class="p">]</span> <span class="k">if</span> <span class="s2">&quot;parity&quot;</span> <span class="ow">in</span> <span class="n">ifconf</span> <span class="k">else</span> <span class="s2">&quot;N&quot;</span>
+        <span class="n">stopbits</span>  <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">ifconf</span><span class="p">[</span><span class="s2">&quot;stopbits&quot;</span><span class="p">])</span> <span class="k">if</span> <span class="s2">&quot;stopbits&quot;</span> <span class="ow">in</span> <span class="n">ifconf</span> <span class="k">else</span> <span class="mi">1</span>
+
+        <span class="c1"># In case no port is specified, we abort setup by</span>
+        <span class="c1"># raising an exception.</span>
+        <span class="k">if</span> <span class="n">port</span> <span class="o">==</span> <span class="kc">None</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;No port specified for </span><span class="si">{</span><span class="bp">self</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+
+        <span class="c1"># All interfaces must supply a hardware MTU value</span>
+        <span class="c1"># to the RNS Transport instance. This value should</span>
+        <span class="c1"># be the maximum data packet payload size that the</span>
+        <span class="c1"># underlying medium is capable of handling in all</span>
+        <span class="c1"># cases without any segmentation.</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">HW_MTU</span> <span class="o">=</span> <span class="mi">564</span>
+
+        <span class="c1"># We initially set the &quot;online&quot; property to false,</span>
+        <span class="c1"># since the interface has not actually been fully</span>
+        <span class="c1"># initialised and connected yet.</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">online</span>   <span class="o">=</span> <span class="kc">False</span>
+
+        <span class="c1"># In this case, we can also set the indicated bit-</span>
+        <span class="c1"># rate of the interface to the serial port speed.</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">bitrate</span>  <span class="o">=</span> <span class="n">speed</span>
+        
+        <span class="c1"># Configure internal properties on the interface</span>
+        <span class="c1"># according to the supplied configuration.</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">pyserial</span> <span class="o">=</span> <span class="n">serial</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">serial</span>   <span class="o">=</span> <span class="kc">None</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">owner</span>    <span class="o">=</span> <span class="n">owner</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">port</span>     <span class="o">=</span> <span class="n">port</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">speed</span>    <span class="o">=</span> <span class="n">speed</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">databits</span> <span class="o">=</span> <span class="n">databits</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">parity</span>   <span class="o">=</span> <span class="n">serial</span><span class="o">.</span><span class="n">PARITY_NONE</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">stopbits</span> <span class="o">=</span> <span class="n">stopbits</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">timeout</span>  <span class="o">=</span> <span class="mi">100</span>
+
+        <span class="k">if</span> <span class="n">parity</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">==</span> <span class="s2">&quot;e&quot;</span> <span class="ow">or</span> <span class="n">parity</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">==</span> <span class="s2">&quot;even&quot;</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">parity</span> <span class="o">=</span> <span class="n">serial</span><span class="o">.</span><span class="n">PARITY_EVEN</span>
+
+        <span class="k">if</span> <span class="n">parity</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">==</span> <span class="s2">&quot;o&quot;</span> <span class="ow">or</span> <span class="n">parity</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">==</span> <span class="s2">&quot;odd&quot;</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">parity</span> <span class="o">=</span> <span class="n">serial</span><span class="o">.</span><span class="n">PARITY_ODD</span>
+
+        <span class="c1"># Since all required parameters are now configured,</span>
+        <span class="c1"># we will try opening the serial port.</span>
+        <span class="k">try</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">open_port</span><span class="p">()</span>
+        <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+            <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Could not open serial port for interface &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="p">),</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_ERROR</span><span class="p">)</span>
+            <span class="k">raise</span> <span class="n">e</span>
+
+        <span class="c1"># If opening the port succeeded, run any post-open</span>
+        <span class="c1"># configuration required.</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">serial</span><span class="o">.</span><span class="n">is_open</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">configure_device</span><span class="p">()</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">IOError</span><span class="p">(</span><span class="s2">&quot;Could not open serial port&quot;</span><span class="p">)</span>
+
+    <span class="c1"># Open the serial port with supplied configuration</span>
+    <span class="c1"># parameters and store a reference to the open port.</span>
+    <span class="k">def</span> <span class="nf">open_port</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Opening serial port &quot;</span><span class="o">+</span><span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="o">+</span><span class="s2">&quot;...&quot;</span><span class="p">,</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_VERBOSE</span><span class="p">)</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">serial</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">pyserial</span><span class="o">.</span><span class="n">Serial</span><span class="p">(</span>
+            <span class="n">port</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="p">,</span>
+            <span class="n">baudrate</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">speed</span><span class="p">,</span>
+            <span class="n">bytesize</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">databits</span><span class="p">,</span>
+            <span class="n">parity</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">parity</span><span class="p">,</span>
+            <span class="n">stopbits</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">stopbits</span><span class="p">,</span>
+            <span class="n">xonxoff</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+            <span class="n">rtscts</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+            <span class="n">timeout</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
+            <span class="n">inter_byte_timeout</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+            <span class="n">write_timeout</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+            <span class="n">dsrdtr</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+        <span class="p">)</span>
+
+    <span class="c1"># The only thing required after opening the port</span>
+    <span class="c1"># is to wait a small amount of time for the</span>
+    <span class="c1"># hardware to initialise and then start a thread</span>
+    <span class="c1"># that reads any incoming data from the device.</span>
+    <span class="k">def</span> <span class="nf">configure_device</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="n">sleep</span><span class="p">(</span><span class="mf">0.5</span><span class="p">)</span>
+        <span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">read_loop</span><span class="p">)</span>
+        <span class="n">thread</span><span class="o">.</span><span class="n">daemon</span> <span class="o">=</span> <span class="kc">True</span>
+        <span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">online</span> <span class="o">=</span> <span class="kc">True</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Serial port &quot;</span><span class="o">+</span><span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="o">+</span><span class="s2">&quot; is now open&quot;</span><span class="p">,</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_VERBOSE</span><span class="p">)</span>
+
+
+    <span class="c1"># This method will be called from our read-loop</span>
+    <span class="c1"># whenever a full packet has been received over</span>
+    <span class="c1"># the underlying medium.</span>
+    <span class="k">def</span> <span class="nf">process_incoming</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
+        <span class="c1"># Update our received bytes counter</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">rxb</span> <span class="o">+=</span> <span class="nb">len</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>            
+
+        <span class="c1"># And send the data packet to the Transport</span>
+        <span class="c1"># instance for processing.</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">owner</span><span class="o">.</span><span class="n">inbound</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span>
+
+    <span class="c1"># The running Reticulum Transport instance will</span>
+    <span class="c1"># call this method on the interface whenever the</span>
+    <span class="c1"># interface must transmit a packet.</span>
+    <span class="k">def</span> <span class="nf">process_outgoing</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span><span class="n">data</span><span class="p">):</span>
+        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">online</span><span class="p">:</span>
+            <span class="c1"># First, escape and packetize the data</span>
+            <span class="c1"># according to HDLC framing.</span>
+            <span class="n">data</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">([</span><span class="n">HDLC</span><span class="o">.</span><span class="n">FLAG</span><span class="p">])</span><span class="o">+</span><span class="n">HDLC</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="n">data</span><span class="p">)</span><span class="o">+</span><span class="nb">bytes</span><span class="p">([</span><span class="n">HDLC</span><span class="o">.</span><span class="n">FLAG</span><span class="p">])</span>
+
+            <span class="c1"># Then write the framed data to the port</span>
+            <span class="n">written</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">serial</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
+
+            <span class="c1"># Update the transmitted bytes counter</span>
+            <span class="c1"># and ensure that all data was written</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">txb</span> <span class="o">+=</span> <span class="nb">len</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>            
+            <span class="k">if</span> <span class="n">written</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
+                <span class="k">raise</span> <span class="ne">IOError</span><span class="p">(</span><span class="s2">&quot;Serial interface only wrote &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="n">written</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot; bytes of &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">data</span><span class="p">)))</span>
+
+    <span class="c1"># This read loop runs in a thread and continously</span>
+    <span class="c1"># receives bytes from the underlying serial port.</span>
+    <span class="c1"># When a full packet has been received, it will</span>
+    <span class="c1"># be sent to the process_incoming methed, which</span>
+    <span class="c1"># will in turn pass it to the Transport instance.</span>
+    <span class="k">def</span> <span class="nf">read_loop</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">try</span><span class="p">:</span>
+            <span class="n">in_frame</span> <span class="o">=</span> <span class="kc">False</span>
+            <span class="n">escape</span> <span class="o">=</span> <span class="kc">False</span>
+            <span class="n">data_buffer</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">&quot;&quot;</span>
+            <span class="n">last_read_ms</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span><span class="o">*</span><span class="mi">1000</span><span class="p">)</span>
+
+            <span class="k">while</span> <span class="bp">self</span><span class="o">.</span><span class="n">serial</span><span class="o">.</span><span class="n">is_open</span><span class="p">:</span>
+                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">serial</span><span class="o">.</span><span class="n">in_waiting</span><span class="p">:</span>
+                    <span class="n">byte</span> <span class="o">=</span> <span class="nb">ord</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">serial</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span>
+                    <span class="n">last_read_ms</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span><span class="o">*</span><span class="mi">1000</span><span class="p">)</span>
+
+                    <span class="k">if</span> <span class="p">(</span><span class="n">in_frame</span> <span class="ow">and</span> <span class="n">byte</span> <span class="o">==</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">FLAG</span><span class="p">):</span>
+                        <span class="n">in_frame</span> <span class="o">=</span> <span class="kc">False</span>
+                        <span class="bp">self</span><span class="o">.</span><span class="n">process_incoming</span><span class="p">(</span><span class="n">data_buffer</span><span class="p">)</span>
+                    <span class="k">elif</span> <span class="p">(</span><span class="n">byte</span> <span class="o">==</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">FLAG</span><span class="p">):</span>
+                        <span class="n">in_frame</span> <span class="o">=</span> <span class="kc">True</span>
+                        <span class="n">data_buffer</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">&quot;&quot;</span>
+                    <span class="k">elif</span> <span class="p">(</span><span class="n">in_frame</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">data_buffer</span><span class="p">)</span> <span class="o">&lt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">HW_MTU</span><span class="p">):</span>
+                        <span class="k">if</span> <span class="p">(</span><span class="n">byte</span> <span class="o">==</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">ESC</span><span class="p">):</span>
+                            <span class="n">escape</span> <span class="o">=</span> <span class="kc">True</span>
+                        <span class="k">else</span><span class="p">:</span>
+                            <span class="k">if</span> <span class="p">(</span><span class="n">escape</span><span class="p">):</span>
+                                <span class="k">if</span> <span class="p">(</span><span class="n">byte</span> <span class="o">==</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">FLAG</span> <span class="o">^</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">ESC_MASK</span><span class="p">):</span>
+                                    <span class="n">byte</span> <span class="o">=</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">FLAG</span>
+                                <span class="k">if</span> <span class="p">(</span><span class="n">byte</span> <span class="o">==</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">ESC</span>  <span class="o">^</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">ESC_MASK</span><span class="p">):</span>
+                                    <span class="n">byte</span> <span class="o">=</span> <span class="n">HDLC</span><span class="o">.</span><span class="n">ESC</span>
+                                <span class="n">escape</span> <span class="o">=</span> <span class="kc">False</span>
+                            <span class="n">data_buffer</span> <span class="o">=</span> <span class="n">data_buffer</span><span class="o">+</span><span class="nb">bytes</span><span class="p">([</span><span class="n">byte</span><span class="p">])</span>
+                        
+                <span class="k">else</span><span class="p">:</span>
+                    <span class="n">time_since_last</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span><span class="o">*</span><span class="mi">1000</span><span class="p">)</span> <span class="o">-</span> <span class="n">last_read_ms</span>
+                    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">data_buffer</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span> <span class="ow">and</span> <span class="n">time_since_last</span> <span class="o">&gt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">timeout</span><span class="p">:</span>
+                        <span class="n">data_buffer</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">&quot;&quot;</span>
+                        <span class="n">in_frame</span> <span class="o">=</span> <span class="kc">False</span>
+                        <span class="n">escape</span> <span class="o">=</span> <span class="kc">False</span>
+                    <span class="n">sleep</span><span class="p">(</span><span class="mf">0.08</span><span class="p">)</span>
+                    
+        <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">online</span> <span class="o">=</span> <span class="kc">False</span>
+            <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;A serial port error occurred, the contained exception was: &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">),</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_ERROR</span><span class="p">)</span>
+            <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;The interface &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot; experienced an unrecoverable error and is now offline.&quot;</span><span class="p">,</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_ERROR</span><span class="p">)</span>
+            
+            <span class="k">if</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">panic_on_interface_error</span><span class="p">:</span>
+                <span class="n">RNS</span><span class="o">.</span><span class="n">panic</span><span class="p">()</span>
+
+            <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Reticulum will attempt to reconnect the interface periodically.&quot;</span><span class="p">,</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_ERROR</span><span class="p">)</span>
+
+        <span class="bp">self</span><span class="o">.</span><span class="n">online</span> <span class="o">=</span> <span class="kc">False</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">serial</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">reconnect_port</span><span class="p">()</span>
+
+    <span class="c1"># This method handles serial port disconnects.</span>
+    <span class="k">def</span> <span class="nf">reconnect_port</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">while</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">online</span><span class="p">:</span>
+            <span class="k">try</span><span class="p">:</span>
+                <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
+                <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Attempting to reconnect serial port &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">port</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot; for &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot;...&quot;</span><span class="p">,</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_VERBOSE</span><span class="p">)</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">open_port</span><span class="p">()</span>
+                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">serial</span><span class="o">.</span><span class="n">is_open</span><span class="p">:</span>
+                    <span class="bp">self</span><span class="o">.</span><span class="n">configure_device</span><span class="p">()</span>
+            <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+                <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Error while reconnecting port, the contained exception was: &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">),</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_ERROR</span><span class="p">)</span>
+
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Reconnected serial port for &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="p">))</span>
+
+    <span class="c1"># Signal to Reticulum that this interface should</span>
+    <span class="c1"># not perform any ingress limiting.</span>
+    <span class="k">def</span> <span class="nf">should_ingress_limit</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">return</span> <span class="kc">False</span>
+
+    <span class="c1"># We must provide a string representation of this</span>
+    <span class="c1"># interface, that is used whenever the interface</span>
+    <span class="c1"># is printed in logs or external programs.</span>
+    <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">return</span> <span class="s2">&quot;ExampleInterface[&quot;</span><span class="o">+</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="o">+</span><span class="s2">&quot;]&quot;</span>
+
+<span class="c1"># Finally, register the defined interface class as the</span>
+<span class="c1"># target class for Reticulum to use as an interface</span>
+<span class="n">interface_class</span> <span class="o">=</span> <span class="n">ExampleInterface</span>
+</pre></div>
+</div>
+<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/ExampleInterface.py">https://github.com/markqvist/Reticulum/blob/master/Examples/ExampleInterface.py</a>.</p>
+</section>
 </section>
 
         </article>
@@ -3310,6 +3619,7 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
 <li><a class="reference internal" href="#channel">Channel</a></li>
 <li><a class="reference internal" href="#buffer">Buffer</a></li>
 <li><a class="reference internal" href="#filetransfer">Filetransfer</a></li>
+<li><a class="reference internal" href="#custom-interfaces">Custom Interfaces</a></li>
 </ul>
 </li>
 </ul>

docs/manual/forhumans.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">

docs/manual/genindex.html

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="#" /><link rel="search" title="Search" href="search.html" />
 
-    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/><title>Index - Reticulum Network Stack 0.8.5 beta documentation</title>
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/><title>Index - Reticulum Network Stack 0.8.7 beta documentation</title>
 <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -139,7 +139,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -165,7 +165,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">

docs/manual/gettingstartedfast.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Using Reticulum on Your System" href="using.html" /><link rel="prev" title="What is Reticulum?" href="whatis.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Getting Started Fast - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>Getting Started Fast - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -241,9 +241,12 @@ and install them offline using <code class="docutils literal notranslate"><span
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">./</span><span class="n">rns</span><span class="o">-</span><span class="mf">0.5.1</span><span class="o">-</span><span class="n">py3</span><span class="o">-</span><span class="n">none</span><span class="o">-</span><span class="nb">any</span><span class="o">.</span><span class="n">whl</span>
 </pre></div>
 </div>
-</section>
+<p>For more detailed installation instructions, please see the
+<a class="reference internal" href="#install-guides"><span class="std std-ref">Platform-Specific Install Notes</span></a> section.</p>
+<p>After installation is complete, it might be helpful to refer to the
+<a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter.</p>
 <section id="resolving-dependency-installation-issues">
-<h2>Resolving Dependency &amp; Installation Issues<a class="headerlink" href="#resolving-dependency-installation-issues" title="Permalink to this heading">#</a></h2>
+<h3>Resolving Dependency &amp; Installation Issues<a class="headerlink" href="#resolving-dependency-installation-issues" title="Permalink to this heading">#</a></h3>
 <p>On some platforms, there may not be binary packages available for all dependencies, and
 <code class="docutils literal notranslate"><span class="pre">pip</span></code> installation may fail with an error message. In these cases, the issue can usually
 be resolved by installing the development essentials packages for your platform:</p>
@@ -261,6 +264,7 @@ be resolved by installing the development essentials packages for your platform:
 dependencies from source, and complete installation even on platforms that don’t have pre-
 compiled packages available.</p>
 </section>
+</section>
 <section id="try-using-a-reticulum-based-program">
 <h2>Try Using a Reticulum-based Program<a class="headerlink" href="#try-using-a-reticulum-based-program" title="Permalink to this heading">#</a></h2>
 <p>If you simply want to try using a program built with Reticulum, a few different
@@ -288,7 +292,8 @@ provides a complete encrypted communications suite built with Reticulum. It feat
 encrypted messaging (both direct and delayed-delivery for offline users), file sharing,
 and has a built-in text-browser and page server with support for dynamically rendered pages,
 user authentication and more.</p>
-<a class="reference external image-reference" href="_images/nomadnet_3.png"><img alt="_images/nomadnet_3.png" src="_images/nomadnet_3.png" /></a>
+<a class="reference external image-reference" href="_images/nomadnet_3.png"><img alt="_images/nomadnet_3.png" src="_images/nomadnet_3.png" />
+</a>
 <p><a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> is a user-facing client
 for the messaging and information-sharing protocol
 <a class="reference external" href="https://github.com/markqvist/lxmf">LXMF</a>, another project built with Reticulum.</p>
@@ -300,17 +305,22 @@ for the messaging and information-sharing protocol
 <span class="n">nomadnet</span>
 </pre></div>
 </div>
-<p><strong>Please Note</strong>: If this is the very first time you use pip to install a program
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>If this is the very first time you use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install a program
 on your system, you might need to reboot your system for your program to become
 available. If you get a “command not found” error or similar when running the
-program, reboot your system and try again.</p>
+program, reboot your system and try again. In some cases, you may even need to
+manually add the <code class="docutils literal notranslate"><span class="pre">pip</span></code> install path to your <code class="docutils literal notranslate"><span class="pre">PATH</span></code> environment variable.</p>
+</div>
 </section>
 <section id="sideband">
 <h3>Sideband<a class="headerlink" href="#sideband" title="Permalink to this heading">#</a></h3>
 <p>If you would rather use a program with a graphical user interface, you can take
 a look at <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>, which is available for Android,
 Linux, macOS and Windows.</p>
-<a class="reference external image-reference" href="_images/sideband_devices.webp"><img alt="_images/sideband_devices.webp" class="align-center" src="_images/sideband_devices.webp" /></a>
+<a class="reference external image-reference" href="_images/sideband_devices.webp"><img alt="_images/sideband_devices.webp" class="align-center" src="_images/sideband_devices.webp" />
+</a>
 <p>Sideband allows you to communicate with other people or LXMF-compatible
 systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR
 Paper Messages, or anything else Reticulum supports. It also interoperates with
@@ -321,7 +331,8 @@ the Nomad Network program.</p>
 <p>The <a class="reference external" href="https://github.com/liamcottle/reticulum-meshchat">Reticulum MeshChat</a> application
 is a user-friendly LXMF client for macOS and Windows, that also includes voice call
 functionality, and a range of other interesting functions.</p>
-<a class="reference external image-reference" href="_images/meshchat_1.webp"><img alt="_images/meshchat_1.webp" class="align-center" src="_images/meshchat_1.webp" /></a>
+<a class="reference external image-reference" href="_images/meshchat_1.webp"><img alt="_images/meshchat_1.webp" class="align-center" src="_images/meshchat_1.webp" />
+</a>
 <p>Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or
 any other LXMF client.</p>
 </section>
@@ -456,6 +467,16 @@ refer to these additional external resources:</p>
 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>
 </section>
+<section id="creating-and-using-custom-interfaces">
+<h2>Creating and Using Custom Interfaces<a class="headerlink" href="#creating-and-using-custom-interfaces" title="Permalink to this heading">#</a></h2>
+<p>While Reticulum includes a flexible and broad range of built-in interfaces, these
+will not cover every conceivable type of communications hardware that Reticulum
+can potentially use to communicate.</p>
+<p>It is therefore possible to easily write your own interface modules, that can be
+loaded at run-time and used on-par with any of the built-in interface types.</p>
+<p>For more information on this subject, and code examples to build on, please see
+the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Configuring Interfaces</span></a> chapter.</p>
+</section>
 <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 heading">#</a></h2>
 <p>If you want to develop programs that use Reticulum, the easiest way to get
@@ -466,11 +487,8 @@ started is to install the latest release of Reticulum via pip:</p>
 <p>The above command will install Reticulum and dependencies, and you will be
 ready to import and use RNS in your own programs. The next step will most
 likely be to look at some <a class="reference internal" href="examples.html#examples-main"><span class="std std-ref">Example Programs</span></a>.</p>
-<p>For extended functionality, you can install optional dependencies:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">pyserial</span>
-</pre></div>
-</div>
-<p>Further information can be found in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>.</p>
+<p>The entire Reticulum API is documented in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>
+chapter of this manual.</p>
 </section>
 <section id="participate-in-reticulum-development">
 <h2>Participate in Reticulum Development<a class="headerlink" href="#participate-in-reticulum-development" title="Permalink to this heading">#</a></h2>
@@ -516,7 +534,7 @@ the <a class="reference external" href="https://github.com/markqvist/Reticulum/d
 or ask one of the developers or maintainers for a good place to start.</p>
 </section>
 <section id="platform-specific-install-notes">
-<h2>Platform-Specific Install Notes<a class="headerlink" href="#platform-specific-install-notes" title="Permalink to this heading">#</a></h2>
+<span id="install-guides"></span><h2>Platform-Specific Install Notes<a class="headerlink" href="#platform-specific-install-notes" title="Permalink to this heading">#</a></h2>
 <p>Some platforms require a slightly different installation procedure, or have
 various quirks that are worth being aware of. These are listed here.</p>
 <section id="android">
@@ -581,7 +599,7 @@ here at a later point. Until then you can use the <a class="reference external"
 <section id="arm64">
 <h3>ARM64<a class="headerlink" href="#arm64" title="Permalink to this heading">#</a></h3>
 <p>On some architectures, including ARM64, not all dependencies have precompiled
-binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> before
+binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before
 installing Reticulum or programs that depend on Reticulum.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span>
 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">update</span>
@@ -591,15 +609,8 @@ installing Reticulum or programs that depend on Reticulum.</p>
 <span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
 </pre></div>
 </div>
-</section>
-<section id="raspberry-pi">
-<h3>Raspberry Pi<a class="headerlink" href="#raspberry-pi" title="Permalink to this heading">#</a></h3>
-<p>It is currently recommended to use a 64-bit version of the Raspberry Pi OS
-if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
-don’t always have packages available for some dependencies.</p>
-<p>While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
-it will require manually configuring and installing some packages, and is not
-detailed in this manual.</p>
+<p>With these packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> will be able to build any missing dependencies
+on your system locally.</p>
 </section>
 <section id="debian-bookworm">
 <h3>Debian Bookworm<a class="headerlink" href="#debian-bookworm" title="Permalink to this heading">#</a></h3>
@@ -625,10 +636,137 @@ following section:</p>
 break-system-packages = true
 </pre></div>
 </div>
-<p>Please note that the “break-system-packages” directive is a somewhat misleading choice
+<p>For a one-shot installation of Reticulum, without globally enabling the <code class="docutils literal notranslate"><span class="pre">break-system-packages</span></code>
+option, you can use the following command:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>pip install rns --break-system-packages
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
 of words. Setting it will of course not break any system packages, but will simply
 allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
-cases lead to version conflicts, it does not generally pose any problems.</p>
+cases lead to version conflicts, it does not generally pose any problems, especially
+not in the case of installing Reticulum.</p>
+</div>
+</section>
+<section id="macos">
+<h3>MacOS<a class="headerlink" href="#macos" title="Permalink to this heading">#</a></h3>
+<p>To install Reticulum on macOS, you will need to have Python and the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package
+manager installed.</p>
+<p>Systems running macOS can vary quite widely in whether or not Python is pre-installed,
+and if it is, which version is installed, and whether the <code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager is
+also installed and set up. If in doubt, you can <a class="reference external" href="https://www.python.org/downloads/">download and install</a>
+Python manually.</p>
+<p>When Python and <code class="docutils literal notranslate"><span class="pre">pip</span></code> is available on your system, simply open a terminal window
+and use one of the following commands:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Reticulum and utilities with pip:</span>
+<span class="n">pip3</span> <span class="n">install</span> <span class="n">rns</span>
+
+<span class="c1"># On some versions, you may need to use the</span>
+<span class="c1"># flag --break-system-packages to install:</span>
+<span class="n">pip3</span> <span class="n">install</span> <span class="n">rns</span> <span class="o">--</span><span class="k">break</span><span class="o">-</span><span class="n">system</span><span class="o">-</span><span class="n">packages</span>
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
+of words. Setting it will of course not break any system packages, but will simply
+allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
+cases lead to version conflicts, it does not generally pose any problems, especially
+not in the case of installing Reticulum.</p>
+</div>
+<p>Additionally, some version combinations of macOS and Python require you to
+manually add your installed <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages directory to your <cite>PATH</cite> environment
+variable, before you can use installed commands in your terminal. Usually, adding
+the following line to your shell init script (for example <code class="docutils literal notranslate"><span class="pre">~/.zshrc</span></code>) will be enough:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>export PATH=$PATH:~/Library/Python/3.9/bin
+</pre></div>
+</div>
+<p>Adjust Python version and shell init script location according to your system.</p>
+</section>
+<section id="openwrt">
+<h3>OpenWRT<a class="headerlink" href="#openwrt" title="Permalink to this heading">#</a></h3>
+<p>On OpenWRT systems with sufficient storage and memory, you can install
+Reticulum and related utilities using the <cite>opkg</cite> package manager and <cite>pip</cite>.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>At the time of releasing this manual, work is underway to create pre-built
+Reticulum packages for OpenWRT, with full configuration, service
+and <code class="docutils literal notranslate"><span class="pre">uci</span></code> integration. Please see the <a class="reference external" href="https://github.com/gretel/feed-reticulum">feed-reticulum</a>
+and <a class="reference external" href="https://github.com/gretel/reticulum-openwrt">reticulum-openwrt</a>
+repositories for more information.</p>
+</div>
+<p>To install Reticulum on OpenWRT, first log into a command line session, and
+then use the following instructions:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span>
+<span class="n">opkg</span> <span class="n">install</span> <span class="n">python3</span> <span class="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</span><span class="o">-</span><span class="n">cryptography</span> <span class="n">python3</span><span class="o">-</span><span class="n">pyserial</span>
+
+<span class="c1"># Install Reticulum</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
+
+<span class="c1"># Start rnsd with debug logging enabled</span>
+<span class="n">rnsd</span> <span class="o">-</span><span class="n">vvv</span>
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The above instructions have been verified and tested on OpenWRT 21.02 only.
+It is likely that other versions may require slightly altered installation
+commands or package names. You will also need enough free space in your
+overlay FS, and enough free RAM to actually run Reticulum and any related
+programs and utilities.</p>
+</div>
+<p>Depending on your device configuration, you may need to adjust firewall rules
+for Reticulum connectivity to and from your device to work. Until proper
+packaging is ready, you will also need to manually create a service or startup
+script to automatically laucnh Reticulum at boot time.</p>
+<p>Please also note that the <cite>AutoInterface</cite> requires link-local IPv6 addresses
+to be enabled for any Ethernet and WiFi devices you intend to use. If <code class="docutils literal notranslate"><span class="pre">ip</span> <span class="pre">a</span></code>
+shows an address starting with <code class="docutils literal notranslate"><span class="pre">fe80::</span></code> for the device in question,
+<code class="docutils literal notranslate"><span class="pre">AutoInterface</span></code> should work for that device.</p>
+</section>
+<section id="raspberry-pi">
+<h3>Raspberry Pi<a class="headerlink" href="#raspberry-pi" title="Permalink to this heading">#</a></h3>
+<p>It is currently recommended to use a 64-bit version of the Raspberry Pi OS
+if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
+don’t always have packages available for some dependencies. If Python and the
+<cite>pip</cite> package manager is not already installed, do that first, and then
+install Reticulum using <cite>pip</cite>.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span>
+<span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">python3</span> <span class="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</span><span class="o">-</span><span class="n">cryptography</span> <span class="n">python3</span><span class="o">-</span><span class="n">pyserial</span>
+
+<span class="c1"># Install Reticulum</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> <span class="o">--</span><span class="k">break</span><span class="o">-</span><span class="n">system</span><span class="o">-</span><span class="n">packages</span>
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
+of words. Setting it will of course not break any system packages, but will simply
+allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
+cases lead to version conflicts, it does not generally pose any problems, especially
+not in the case of installing Reticulum.</p>
+</div>
+<p>While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
+it will require manually configuring and installing required build dependencies,
+and is not detailed in this manual.</p>
+</section>
+<section id="risc-v">
+<h3>RISC-V<a class="headerlink" href="#risc-v" title="Permalink to this heading">#</a></h3>
+<p>On some architectures, including RISC-V, not all dependencies have precompiled
+binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> (or similar) before
+installing Reticulum or programs that depend on Reticulum.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span>
+<span class="n">sudo</span> <span class="n">apt</span> <span class="n">update</span>
+<span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">python3</span> <span class="n">python3</span><span class="o">-</span><span class="n">pip</span> <span class="n">python3</span><span class="o">-</span><span class="n">dev</span>
+
+<span class="c1"># Install Reticulum</span>
+<span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
+</pre></div>
+</div>
+<p>With these packages installed, <code class="docutils literal notranslate"><span class="pre">pip</span></code> will be able to build any missing dependencies
+on your system locally.</p>
 </section>
 <section id="ubuntu-lunar">
 <h3>Ubuntu Lunar<a class="headerlink" href="#ubuntu-lunar" title="Permalink to this heading">#</a></h3>
@@ -654,14 +792,48 @@ following section:</p>
 break-system-packages = true
 </pre></div>
 </div>
-<p>Please note that the “break-system-packages” directive is a somewhat misleading choice
+<p>For a one-shot installation of Reticulum, without globally enabling the <code class="docutils literal notranslate"><span class="pre">break-system-packages</span></code>
+option, you can use the following command:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>pip install rns --break-system-packages
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">--break-system-packages</span></code> directive is a somewhat misleading choice
 of words. Setting it will of course not break any system packages, but will simply
-allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this _could_ in rare
-cases lead to version conflicts, it does not generally pose any problems.</p>
+allow installing <code class="docutils literal notranslate"><span class="pre">pip</span></code> packages user- and system-wide. While this <em>could</em> in rare
+cases lead to version conflicts, it does not generally pose any problems, especially
+not in the case of installing Reticulum.</p>
+</div>
+</section>
+<section id="windows">
+<h3>Windows<a class="headerlink" href="#windows" title="Permalink to this heading">#</a></h3>
+<p>On Windows operating systems, the easiest way to install Reticulum is by using the
+<code class="docutils literal notranslate"><span class="pre">pip</span></code> package manager from the command line (either the command prompt or Windows
+Powershell).</p>
+<p>If you don’t already have Python installed, <a class="reference external" href="https://www.python.org/downloads/">download and install Python</a>.
+At the time of publication of this manual, the recommended version is <a class="reference external" href="https://www.python.org/downloads/release/python-3127">Python 3.12.7</a>.</p>
+<p><strong>Important!</strong> When asked by the installer, make sure to add the Python program to
+your PATH environment variables. If you don’t do this, you will not be able to
+use the <code class="docutils literal notranslate"><span class="pre">pip</span></code> installer, or run the included Reticulum utility programs (such as
+<code class="docutils literal notranslate"><span class="pre">rnsd</span></code> and <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>) from the command line.</p>
+<p>After installing Python, open the command prompt or Windows Powershell, and type:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
+</pre></div>
+</div>
+<p>You can now use Reticulum and all included utility programs directly from your
+preferred command line interface.</p>
 </section>
 </section>
 <section id="pure-python-reticulum">
 <h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Permalink to this heading">#</a></h2>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>If you use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> 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>
 <p>In some rare cases, and on more obscure system types, it is not possible to
 install one or more dependencies. 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, or use <code class="docutils literal notranslate"><span class="pre">pip</span></code>
@@ -675,10 +847,6 @@ only if they are <em>needed</em> and <em>available</em>. If for example you want
 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>
 </section>
 </section>
 
@@ -739,8 +907,10 @@ section of this manual.</p>
           <div class="toc-tree">
             <ul>
 <li><a class="reference internal" href="#">Getting Started Fast</a><ul>
-<li><a class="reference internal" href="#standalone-reticulum-installation">Standalone Reticulum Installation</a></li>
+<li><a class="reference internal" href="#standalone-reticulum-installation">Standalone Reticulum Installation</a><ul>
 <li><a class="reference internal" href="#resolving-dependency-installation-issues">Resolving Dependency &amp; Installation Issues</a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul>
 <li><a class="reference internal" href="#remote-shell">Remote Shell</a></li>
 <li><a class="reference internal" href="#nomad-network">Nomad Network</a></li>
@@ -753,14 +923,19 @@ section of this manual.</p>
 <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="#creating-and-using-custom-interfaces">Creating and Using Custom 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="#platform-specific-install-notes">Platform-Specific Install Notes</a><ul>
 <li><a class="reference internal" href="#android">Android</a></li>
 <li><a class="reference internal" href="#arm64">ARM64</a></li>
-<li><a class="reference internal" href="#raspberry-pi">Raspberry Pi</a></li>
 <li><a class="reference internal" href="#debian-bookworm">Debian Bookworm</a></li>
+<li><a class="reference internal" href="#macos">MacOS</a></li>
+<li><a class="reference internal" href="#openwrt">OpenWRT</a></li>
+<li><a class="reference internal" href="#raspberry-pi">Raspberry Pi</a></li>
+<li><a class="reference internal" href="#risc-v">RISC-V</a></li>
 <li><a class="reference internal" href="#ubuntu-lunar">Ubuntu Lunar</a></li>
+<li><a class="reference internal" href="#windows">Windows</a></li>
 </ul>
 </li>
 <li><a class="reference internal" href="#pure-python-reticulum">Pure-Python Reticulum</a></li>

docs/manual/hardware.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Configuring Interfaces" href="interfaces.html" /><link rel="prev" title="Understanding Reticulum" href="understanding.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Communications Hardware - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>Communications Hardware - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -279,20 +279,21 @@ completely from scratch, to your exact desired specifications, this chapter
 will explain the easiest possible approach to creating RNodes: 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>
+<li><p>Obtain one or more <a class="reference internal" href="#rnode-supported"><span class="std std-ref">supported development boards</span></a></p></li>
+<li><p>Install the RNode firmware with the <a class="reference internal" href="#rnode-installation"><span class="std std-ref">automated installer</span></a></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>
 </section>
-<section id="supported-boards">
-<span id="rnode-supported"></span><h3>Supported Boards<a class="headerlink" href="#supported-boards" title="Permalink to this heading">#</a></h3>
+<section id="supported-boards-and-devices">
+<span id="rnode-supported"></span><h3>Supported Boards and Devices<a class="headerlink" href="#supported-boards-and-devices" title="Permalink to this heading">#</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>
 <hr class="docutils" />
-<a class="reference internal image-reference" href="_images/board_tbeam_supreme.png"><img alt="_images/board_tbeam_supreme.png" class="align-center" src="_images/board_tbeam_supreme.png" style="width: 75%;" /></a>
+<a class="reference internal image-reference" href="_images/board_tbeam_supreme.png"><img alt="_images/board_tbeam_supreme.png" class="align-center" src="_images/board_tbeam_supreme.png" style="width: 75%;" />
+</a>
 <section id="lilygo-t-beam-supreme">
 <h4>LilyGO T-Beam Supreme<a class="headerlink" href="#lilygo-t-beam-supreme" title="Permalink to this heading">#</a></h4>
 <ul class="simple">
@@ -301,7 +302,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
 </ul>
 <hr class="docutils" />
-<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: 75%;" /></a>
+<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: 75%;" />
+</a>
 </section>
 <section id="lilygo-t-beam">
 <h4>LilyGO T-Beam<a class="headerlink" href="#lilygo-t-beam" title="Permalink to this heading">#</a></h4>
@@ -311,7 +313,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
 </ul>
 <hr class="docutils" />
-<a class="reference internal image-reference" href="_images/board_t3s3.png"><img alt="_images/board_t3s3.png" class="align-center" src="_images/board_t3s3.png" style="width: 50%;" /></a>
+<a class="reference internal image-reference" href="_images/board_t3s3.png"><img alt="_images/board_t3s3.png" class="align-center" src="_images/board_t3s3.png" style="width: 50%;" />
+</a>
 </section>
 <section id="lilygo-t3s3">
 <h4>LilyGO T3S3<a class="headerlink" href="#lilygo-t3s3" title="Permalink to this heading">#</a></h4>
@@ -321,7 +324,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
 </ul>
 <hr class="docutils" />
-<a class="reference internal image-reference" href="_images/board_rak4631.png"><img alt="_images/board_rak4631.png" class="align-center" src="_images/board_rak4631.png" style="width: 45%;" /></a>
+<a class="reference internal image-reference" href="_images/board_rak4631.png"><img alt="_images/board_rak4631.png" class="align-center" src="_images/board_rak4631.png" style="width: 45%;" />
+</a>
 </section>
 <section id="rak4631-based-boards">
 <h4>RAK4631-based Boards<a class="headerlink" href="#rak4631-based-boards" title="Permalink to this heading">#</a></h4>
@@ -331,7 +335,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://www.rakwireless.com">RAK Wireless</a></p></li>
 </ul>
 <hr class="docutils" />
-<a class="reference internal image-reference" href="_images/board_rnodev2.png"><img alt="_images/board_rnodev2.png" class="align-center" src="_images/board_rnodev2.png" style="width: 68%;" /></a>
+<a class="reference internal image-reference" href="_images/board_rnodev2.png"><img alt="_images/board_rnodev2.png" class="align-center" src="_images/board_rnodev2.png" style="width: 68%;" />
+</a>
 </section>
 <section id="unsigned-rnode-v2-x">
 <h4>Unsigned RNode v2.x<a class="headerlink" href="#unsigned-rnode-v2-x" title="Permalink to this heading">#</a></h4>
@@ -341,7 +346,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://unsigned.io">unsigned.io</a></p></li>
 </ul>
 <hr class="docutils" />
-<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: 46%;" /></a>
+<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: 46%;" />
+</a>
 </section>
 <section id="lilygo-lora32-v2-1">
 <h4>LilyGO LoRa32 v2.1<a class="headerlink" href="#lilygo-lora32-v2-1" title="Permalink to this heading">#</a></h4>
@@ -351,7 +357,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
 </ul>
 <hr class="docutils" />
-<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: 46%;" /></a>
+<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: 46%;" />
+</a>
 </section>
 <section id="lilygo-lora32-v2-0">
 <h4>LilyGO LoRa32 v2.0<a class="headerlink" href="#lilygo-lora32-v2-0" title="Permalink to this heading">#</a></h4>
@@ -361,7 +368,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
 </ul>
 <hr class="docutils" />
-<a class="reference internal image-reference" href="_images/board_t3v10.png"><img alt="_images/board_t3v10.png" class="align-center" src="_images/board_t3v10.png" style="width: 46%;" /></a>
+<a class="reference internal image-reference" href="_images/board_t3v10.png"><img alt="_images/board_t3v10.png" class="align-center" src="_images/board_t3v10.png" style="width: 46%;" />
+</a>
 </section>
 <section id="lilygo-lora32-v1-0">
 <h4>LilyGO LoRa32 v1.0<a class="headerlink" href="#lilygo-lora32-v1-0" title="Permalink to this heading">#</a></h4>
@@ -371,7 +379,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
 </ul>
 <hr class="docutils" />
-<a class="reference internal image-reference" href="_images/board_tdeck.png"><img alt="_images/board_tdeck.png" class="align-center" src="_images/board_tdeck.png" style="width: 45%;" /></a>
+<a class="reference internal image-reference" href="_images/board_tdeck.png"><img alt="_images/board_tdeck.png" class="align-center" src="_images/board_tdeck.png" style="width: 45%;" />
+</a>
 </section>
 <section id="lilygo-t-deck">
 <h4>LilyGO T-Deck<a class="headerlink" href="#lilygo-t-deck" title="Permalink to this heading">#</a></h4>
@@ -381,7 +390,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
 </ul>
 <hr class="docutils" />
-<a class="reference internal image-reference" href="_images/board_heltec32v30.png"><img alt="_images/board_heltec32v30.png" class="align-center" src="_images/board_heltec32v30.png" style="width: 58%;" /></a>
+<a class="reference internal image-reference" href="_images/board_heltec32v30.png"><img alt="_images/board_heltec32v30.png" class="align-center" src="_images/board_heltec32v30.png" style="width: 58%;" />
+</a>
 </section>
 <section id="heltec-lora32-v3-0">
 <h4>Heltec LoRa32 v3.0<a class="headerlink" href="#heltec-lora32-v3-0" title="Permalink to this heading">#</a></h4>
@@ -391,7 +401,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://heltec.org">Heltec Automation</a></p></li>
 </ul>
 <hr class="docutils" />
-<a class="reference internal image-reference" href="_images/board_heltec32v20.png"><img alt="_images/board_heltec32v20.png" class="align-center" src="_images/board_heltec32v20.png" style="width: 58%;" /></a>
+<a class="reference internal image-reference" href="_images/board_heltec32v20.png"><img alt="_images/board_heltec32v20.png" class="align-center" src="_images/board_heltec32v20.png" style="width: 58%;" />
+</a>
 </section>
 <section id="heltec-lora32-v2-0">
 <h4>Heltec LoRa32 v2.0<a class="headerlink" href="#heltec-lora32-v2-0" title="Permalink to this heading">#</a></h4>
@@ -401,7 +412,8 @@ boards. The following boards are supported by the auto-installer.</p>
 <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://heltec.org">Heltec Automation</a></p></li>
 </ul>
 <hr class="docutils" />
-<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>
+<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>
 </section>
 <section id="unsigned-rnode-v1-x">
 <h4>Unsigned RNode v1.x<a class="headerlink" href="#unsigned-rnode-v1-x" title="Permalink to this heading">#</a></h4>
@@ -450,8 +462,10 @@ Most devices will behave like this by default, or allow it via configuration opt
 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>
-<a class="reference internal image-reference" href="_images/radio_rblhg5.png"><img alt="_images/radio_rblhg5.png" src="_images/radio_rblhg5.png" style="width: 49%;" /></a>
-<a class="reference internal image-reference" href="_images/radio_is5ac.png"><img alt="_images/radio_is5ac.png" src="_images/radio_is5ac.png" style="width: 49%;" /></a>
+<a class="reference internal image-reference" href="_images/radio_rblhg5.png"><img alt="_images/radio_rblhg5.png" src="_images/radio_rblhg5.png" style="width: 49%;" />
+</a>
+<a class="reference internal image-reference" href="_images/radio_is5ac.png"><img alt="_images/radio_is5ac.png" src="_images/radio_is5ac.png" style="width: 49%;" />
+</a>
 <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">
@@ -550,7 +564,7 @@ can be used with Reticulum. This includes virtual software modems such as
 <li><a class="reference internal" href="#combining-hardware-types">Combining Hardware Types</a></li>
 <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="#supported-boards-and-devices">Supported Boards and Devices</a><ul>
 <li><a class="reference internal" href="#lilygo-t-beam-supreme">LilyGO T-Beam Supreme</a></li>
 <li><a class="reference internal" href="#lilygo-t-beam">LilyGO T-Beam</a></li>
 <li><a class="reference internal" href="#lilygo-t3s3">LilyGO T3S3</a></li>

docs/manual/index.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="What is Reticulum?" href="whatis.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="#"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="#"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -241,8 +241,10 @@ to participate in the development of Reticulum itself.</p>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#standalone-reticulum-installation">Standalone Reticulum Installation</a></li>
-<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#resolving-dependency-installation-issues">Resolving Dependency &amp; Installation Issues</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#standalone-reticulum-installation">Standalone Reticulum Installation</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#resolving-dependency-installation-issues">Resolving Dependency &amp; Installation Issues</a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#remote-shell">Remote Shell</a></li>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#nomad-network">Nomad Network</a></li>
@@ -255,14 +257,19 @@ to participate in the development of Reticulum itself.</p>
 <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#creating-and-using-custom-interfaces">Creating and Using Custom 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#platform-specific-install-notes">Platform-Specific Install Notes</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#android">Android</a></li>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#arm64">ARM64</a></li>
-<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#raspberry-pi">Raspberry Pi</a></li>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#debian-bookworm">Debian Bookworm</a></li>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#macos">MacOS</a></li>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#openwrt">OpenWRT</a></li>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#raspberry-pi">Raspberry Pi</a></li>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#risc-v">RISC-V</a></li>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#ubuntu-lunar">Ubuntu Lunar</a></li>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#windows">Windows</a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#pure-python-reticulum">Pure-Python Reticulum</a></li>
@@ -321,7 +328,7 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="hardware.html#combining-hardware-types">Combining Hardware Types</a></li>
 <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#supported-boards-and-devices">Supported Boards and Devices</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>
 </ul>
@@ -333,6 +340,7 @@ to participate in the development of Reticulum itself.</p>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#custom-interfaces">Custom Interfaces</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#auto-interface">Auto Interface</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#i2p-interface">I2P Interface</a></li>
 <li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-server-interface">TCP Server Interface</a></li>
@@ -371,6 +379,7 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#channel">Channel</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#buffer">Buffer</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#filetransfer">Filetransfer</a></li>
+<li class="toctree-l2"><a class="reference internal" href="examples.html#custom-interfaces">Custom Interfaces</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a><ul>

docs/manual/interfaces.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Building Networks" href="networks.html" /><link rel="prev" title="Communications Hardware" href="hardware.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Configuring Interfaces - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>Configuring Interfaces - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -233,6 +233,13 @@ and gives example configurations for the respective interface types.</p>
 <p>For a high-level overview of how networks can be formed over different interface
 types, have a look at the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> chapter of this
 manual.</p>
+<section id="custom-interfaces">
+<span id="interfaces-custom"></span><h2>Custom Interfaces<a class="headerlink" href="#custom-interfaces" title="Permalink to this heading">#</a></h2>
+<p>In addition to the built-in interface types, Reticulum is <strong>fully extensible</strong> with
+custom, user- or community-supplied interfaces, and creating custom interface
+modules is straightforward. Please see the <a class="reference internal" href="examples.html#example-custominterface"><span class="std std-ref">custom interface</span></a>
+example for basic interface code to build upon.</p>
+</section>
 <section id="auto-interface">
 <span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this heading">#</a></h2>
 <p>The Auto Interface enables communication with other discoverable Reticulum
@@ -346,11 +353,14 @@ list of I2P base32 addresses to the <code class="docutils literal notranslate"><
 <p>It can take anywhere from a few seconds to a few minutes to establish
 I2P connections to the desired peers, so Reticulum handles the process
 in the background, and will output relevant events to the log.</p>
-<p><strong>Please Note!</strong> While the I2P interface is the simplest way to use
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>While the I2P interface is the simplest way to use
 Reticulum over I2P, it is also possible to tunnel the TCP server and
 client interfaces over I2P manually. This can be useful in situations
 where more control is needed, but requires manual tunnel setup through
 the I2P daemon configuration.</p>
+</div>
 <p>It is important to note that the two methods are <em>interchangably compatible</em>.
 You can use the I2PInterface to connect to a TCPServerInterface that
 was manually tunneled over I2P, for example. This offers a high degree
@@ -360,7 +370,7 @@ use-cases.</p>
 <section id="tcp-server-interface">
 <span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Permalink to this heading">#</a></h2>
 <p>The TCP Server interface is suitable for allowing other peers to connect over
-the Internet or private IP networks. When a TCP server interface has been
+the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been
 configured, other Reticulum peers can connect to it with a TCP Client interface.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a TCP server interface.</span>
 <span class="c1"># It will listen for incoming connections on the</span>
@@ -387,8 +397,35 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
   <span class="c1"># port = 4242</span>
 </pre></div>
 </div>
-<p><strong>Please Note!</strong> The TCP interfaces support tunneling over I2P, but to do so reliably,
+<p>If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
+you can use the <code class="docutils literal notranslate"><span class="pre">prefer_ipv6</span></code> option to bind to the IPv6 address:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a TCP server interface.</span>
+<span class="c1"># It will listen for incoming connections on the</span>
+<span class="c1"># specified IP address and port number.</span>
+
+<span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span>
+  <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
+  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+
+  <span class="n">device</span> <span class="o">=</span> <span class="n">eth0</span>
+  <span class="n">port</span> <span class="o">=</span> <span class="mi">4242</span>
+  <span class="n">prefer_ipv6</span> <span class="o">=</span> <span class="kc">True</span>
+</pre></div>
+</div>
+<p>To use the TCP Server Interface over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, you
+can simply specify the Yggdrasil <code class="docutils literal notranslate"><span class="pre">tun</span></code> device and a listening port, like so:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span>
+    <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
+    <span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
+    <span class="n">device</span> <span class="o">=</span> <span class="n">tun0</span>
+    <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4343</span>
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The TCP interfaces support tunneling over I2P, but to do so reliably,
 you must use the i2p_tunneled option:</p>
+</div>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">on</span> <span class="n">I2P</span><span class="p">]]</span>
     <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
     <span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
@@ -409,7 +446,7 @@ same TCP Server interface at the same time.</p>
 This means that Reticulum will gracefully handle IP links that go up and down,
 and restore connectivity after a failure, once the other end of a TCP interface reappears.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of a TCP Client interface. The</span>
-<span class="c1"># target_host can either be an IP address or a hostname.</span>
+<span class="c1"># target_host can be a hostname or an IPv4 or IPv6 address.</span>
 
 <span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span>
   <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
@@ -418,6 +455,15 @@ and restore connectivity after a failure, once the other end of a TCP interface
   <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span>
 </pre></div>
 </div>
+<p>To use the TCP Client Interface over <a class="reference external" href="https://yggdrasil-network.github.io/">Yggdrasil</a>, simply
+specify the target Yggdrasil IPv6 address and port, like so:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Yggdrasil</span> <span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span>
+    <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
+    <span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
+    <span class="n">target_host</span> <span class="o">=</span> <span class="mi">201</span><span class="p">:</span><span class="mi">5</span><span class="n">d78</span><span class="p">:</span><span class="n">af73</span><span class="p">:</span><span class="mi">5</span><span class="n">caf</span><span class="p">:</span><span class="n">a4de</span><span class="p">:</span><span class="n">a79f</span><span class="p">:</span><span class="mi">3278</span><span class="p">:</span><span class="mf">71e5</span>
+    <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4343</span>
+</pre></div>
+</div>
 <p>It is also possible to use this interface type to connect via other programs
 or hardware devices that expose a KISS interface on a TCP port, for example
 software-based soundmodems. To do this, use the <code class="docutils literal notranslate"><span class="pre">kiss_framing</span></code> option:</p>
@@ -438,8 +484,11 @@ and programs like soundmodems and similar over TCP. When using the
 never enable <code class="docutils literal notranslate"><span class="pre">kiss_framing</span></code>, since this will disable internal reliability and
 recovery mechanisms that greatly improves performance over unreliable and
 intermittent TCP links.</p>
-<p><strong>Please Note!</strong> The TCP interfaces support tunneling over I2P, but to do so reliably,
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The TCP interfaces support tunneling over I2P, but to do so reliably,
 you must use the i2p_tunneled option:</p>
+</div>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">over</span> <span class="n">I2P</span><span class="p">]]</span>
     <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
     <span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
@@ -455,11 +504,14 @@ you must use the i2p_tunneled option:</p>
 private and the internet. It can also allow broadcast communication
 over IP networks, so it can provide an easy way to enable connectivity
 with all other peers on a local area network.</p>
-<p><em>Please Note!</em> Using broadcast UDP traffic has performance implications,
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Using broadcast UDP traffic has performance implications,
 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>
+</div>
 <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>
 
@@ -508,6 +560,12 @@ easier to use.</p>
 <span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Permalink to this heading">#</a></h2>
 <p>To use Reticulum over LoRa, the <a class="reference external" href="https://unsigned.io/rnode/">RNode</a> interface
 can be used, and offers full control over LoRa parameters.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Radio frequency spectrum is a legally controlled resource, and legislation
+varies widely around the world. It is your responsibility to be aware of any
+relevant regulation for your location, and to make decisions accordingly.</p>
+</div>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of how to add a LoRa interface</span>
 <span class="c1"># using the RNode LoRa transceiver.</span>
 
@@ -590,6 +648,12 @@ can be used, and offers full control over LoRa parameters.</p>
 <span id="interfaces-rnode-multi"></span><h2>RNode Multi Interface<a class="headerlink" href="#rnode-multi-interface" title="Permalink to this heading">#</a></h2>
 <p>For RNodes that support multiple LoRa transceivers, the RNode
 Multi interface can be used to configure sub-interfaces individually.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Radio frequency spectrum is a legally controlled resource, and legislation
+varies widely around the world. It is your responsibility to be aware of any
+relevant regulation for your location, and to make decisions accordingly.</p>
+</div>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of how to add an RNode Multi interface</span>
 <span class="c1"># using the RNode LoRa transceiver.</span>
 
@@ -611,89 +675,89 @@ Multi interface can be used to configure sub-interfaces individually.</p>
 <span class="c1"># id_interval = 600</span>
 
   <span class="c1"># A subinterface</span>
-  <span class="p">[[[</span><span class="n">HIGHDATARATE</span><span class="p">]]]</span>
-  <span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span>
-  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+  <span class="p">[[[</span><span class="n">High</span> <span class="n">Datarate</span><span class="p">]]]</span>
+    <span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span>
+    <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
 
-  <span class="c1"># Set frequency to 2.4GHz</span>
-  <span class="n">frequency</span> <span class="o">=</span> <span class="mi">2400000000</span>
+    <span class="c1"># Set frequency to 2.4GHz</span>
+    <span class="n">frequency</span> <span class="o">=</span> <span class="mi">2400000000</span>
 
-  <span class="c1"># Set LoRa bandwidth to 1625 KHz</span>
-  <span class="n">bandwidth</span> <span class="o">=</span> <span class="mi">1625000</span>
+    <span class="c1"># Set LoRa bandwidth to 1625 KHz</span>
+    <span class="n">bandwidth</span> <span class="o">=</span> <span class="mi">1625000</span>
 
-  <span class="c1"># Set TX power to 0 dBm (0.12 mW)</span>
-  <span class="n">txpower</span> <span class="o">=</span> <span class="mi">0</span>
+    <span class="c1"># Set TX power to 0 dBm (0.12 mW)</span>
+    <span class="n">txpower</span> <span class="o">=</span> <span class="mi">0</span>
 
-  <span class="c1"># The virtual port, only the manufacturer</span>
-  <span class="c1"># or the person who wrote the board config</span>
-  <span class="c1"># can tell you what it will be for which</span>
-  <span class="c1"># physical hardware interface</span>
-  <span class="n">vport</span> <span class="o">=</span> <span class="mi">1</span>
+    <span class="c1"># The virtual port, only the manufacturer</span>
+    <span class="c1"># or the person who wrote the board config</span>
+    <span class="c1"># can tell you what it will be for which</span>
+    <span class="c1"># physical hardware interface</span>
+    <span class="n">vport</span> <span class="o">=</span> <span class="mi">1</span>
 
-  <span class="c1"># Select spreading factor 5. Valid</span>
-  <span class="c1"># range is 5 through 12, with 5</span>
-  <span class="c1"># being the fastest and 12 having</span>
-  <span class="c1"># the longest range.</span>
-  <span class="n">spreadingfactor</span> <span class="o">=</span> <span class="mi">5</span>
+    <span class="c1"># Select spreading factor 5. Valid</span>
+    <span class="c1"># range is 5 through 12, with 5</span>
+    <span class="c1"># being the fastest and 12 having</span>
+    <span class="c1"># the longest range.</span>
+    <span class="n">spreadingfactor</span> <span class="o">=</span> <span class="mi">5</span>
 
-  <span class="c1"># Select coding rate 5. Valid range</span>
-  <span class="c1"># is 5 throough 8, with 5 being the</span>
-  <span class="c1"># fastest, and 8 the longest range.</span>
-  <span class="n">codingrate</span> <span class="o">=</span> <span class="mi">5</span>
+    <span class="c1"># Select coding rate 5. Valid range</span>
+    <span class="c1"># is 5 throough 8, with 5 being the</span>
+    <span class="c1"># fastest, and 8 the longest range.</span>
+    <span class="n">codingrate</span> <span class="o">=</span> <span class="mi">5</span>
 
-  <span class="c1"># It is possible to limit the airtime</span>
-  <span class="c1"># utilisation of an RNode by using the</span>
-  <span class="c1"># following two configuration options.</span>
-  <span class="c1"># The short-term limit is applied in a</span>
-  <span class="c1"># window of approximately 15 seconds,</span>
-  <span class="c1"># and the long-term limit is enforced</span>
-  <span class="c1"># over a rolling 60 minute window. Both</span>
-  <span class="c1"># options are specified in percent.</span>
+    <span class="c1"># It is possible to limit the airtime</span>
+    <span class="c1"># utilisation of an RNode by using the</span>
+    <span class="c1"># following two configuration options.</span>
+    <span class="c1"># The short-term limit is applied in a</span>
+    <span class="c1"># window of approximately 15 seconds,</span>
+    <span class="c1"># and the long-term limit is enforced</span>
+    <span class="c1"># over a rolling 60 minute window. Both</span>
+    <span class="c1"># options are specified in percent.</span>
 
-  <span class="c1"># airtime_limit_long = 100</span>
-  <span class="c1"># airtime_limit_short = 100</span>
+    <span class="c1"># airtime_limit_long = 100</span>
+    <span class="c1"># airtime_limit_short = 100</span>
 
-  <span class="p">[[[</span><span class="n">LOWDATARATE</span><span class="p">]]]</span>
-  <span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span>
-  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+  <span class="p">[[[</span><span class="n">Low</span> <span class="n">Datarate</span><span class="p">]]]</span>
+    <span class="c1"># Subinterfaces can be enabled and disabled in of themselves</span>
+    <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
 
-  <span class="c1"># Set frequency to 865.6 MHz</span>
-  <span class="n">frequency</span> <span class="o">=</span> <span class="mi">865600000</span>
+    <span class="c1"># Set frequency to 865.6 MHz</span>
+    <span class="n">frequency</span> <span class="o">=</span> <span class="mi">865600000</span>
 
-  <span class="c1"># The virtual port, only the manufacturer</span>
-  <span class="c1"># or the person who wrote the board config</span>
-  <span class="c1"># can tell you what it will be for which</span>
-  <span class="c1"># physical hardware interface</span>
-  <span class="n">vport</span> <span class="o">=</span> <span class="mi">0</span>
+    <span class="c1"># The virtual port, only the manufacturer</span>
+    <span class="c1"># or the person who wrote the board config</span>
+    <span class="c1"># can tell you what it will be for which</span>
+    <span class="c1"># physical hardware interface</span>
+    <span class="n">vport</span> <span class="o">=</span> <span class="mi">0</span>
 
-  <span class="c1"># Set LoRa bandwidth to 125 KHz</span>
-  <span class="n">bandwidth</span> <span class="o">=</span> <span class="mi">125000</span>
+    <span class="c1"># Set LoRa bandwidth to 125 KHz</span>
+    <span class="n">bandwidth</span> <span class="o">=</span> <span class="mi">125000</span>
 
-  <span class="c1"># Set TX power to 0 dBm (0.12 mW)</span>
-  <span class="n">txpower</span> <span class="o">=</span> <span class="mi">0</span>
+    <span class="c1"># Set TX power to 0 dBm (0.12 mW)</span>
+    <span class="n">txpower</span> <span class="o">=</span> <span class="mi">0</span>
 
-  <span class="c1"># Select spreading factor 7. Valid</span>
-  <span class="c1"># range is 5 through 12, with 5</span>
-  <span class="c1"># being the fastest and 12 having</span>
-  <span class="c1"># the longest range.</span>
-  <span class="n">spreadingfactor</span> <span class="o">=</span> <span class="mi">7</span>
+    <span class="c1"># Select spreading factor 7. Valid</span>
+    <span class="c1"># range is 5 through 12, with 5</span>
+    <span class="c1"># being the fastest and 12 having</span>
+    <span class="c1"># the longest range.</span>
+    <span class="n">spreadingfactor</span> <span class="o">=</span> <span class="mi">7</span>
 
-  <span class="c1"># Select coding rate 5. Valid range</span>
-  <span class="c1"># is 5 throough 8, with 5 being the</span>
-  <span class="c1"># fastest, and 8 the longest range.</span>
-  <span class="n">codingrate</span> <span class="o">=</span> <span class="mi">5</span>
+    <span class="c1"># Select coding rate 5. Valid range</span>
+    <span class="c1"># is 5 throough 8, with 5 being the</span>
+    <span class="c1"># fastest, and 8 the longest range.</span>
+    <span class="n">codingrate</span> <span class="o">=</span> <span class="mi">5</span>
 
-  <span class="c1"># It is possible to limit the airtime</span>
-  <span class="c1"># utilisation of an RNode by using the</span>
-  <span class="c1"># following two configuration options.</span>
-  <span class="c1"># The short-term limit is applied in a</span>
-  <span class="c1"># window of approximately 15 seconds,</span>
-  <span class="c1"># and the long-term limit is enforced</span>
-  <span class="c1"># over a rolling 60 minute window. Both</span>
-  <span class="c1"># options are specified in percent.</span>
+    <span class="c1"># It is possible to limit the airtime</span>
+    <span class="c1"># utilisation of an RNode by using the</span>
+    <span class="c1"># following two configuration options.</span>
+    <span class="c1"># The short-term limit is applied in a</span>
+    <span class="c1"># window of approximately 15 seconds,</span>
+    <span class="c1"># and the long-term limit is enforced</span>
+    <span class="c1"># over a rolling 60 minute window. Both</span>
+    <span class="c1"># options are specified in percent.</span>
 
-  <span class="c1"># airtime_limit_long = 100</span>
-  <span class="c1"># airtime_limit_short = 100</span>
+    <span class="c1"># airtime_limit_long = 100</span>
+    <span class="c1"># airtime_limit_short = 100</span>
 </pre></div>
 </div>
 </section>
@@ -744,6 +808,12 @@ Reticulum will try to respawn the program after waiting for <code class="docutil
 radio modems and TNCs, including <a class="reference external" href="https://unsigned.io/openmodem/">OpenModem</a>.
 KISS interfaces can also be configured to periodically send out beacons
 for station identification purposes.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Radio frequency spectrum is a legally controlled resource, and legislation
+varies widely around the world. It is your responsibility to be aware of any
+relevant regulation for your location, and to make decisions accordingly.</p>
+</div>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span>
   <span class="nb">type</span> <span class="o">=</span> <span class="n">KISSInterface</span>
   <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
@@ -801,6 +871,12 @@ layer for anything, and it incurs extra overhead on every packet to
 encapsulate in AX.25.</p>
 <p>A more efficient way is to use the plain KISS interface with the
 beaconing functionality described above.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Radio frequency spectrum is a legally controlled resource, and legislation
+varies widely around the world. It is your responsibility to be aware of any
+relevant regulation for your location, and to make decisions accordingly.</p>
+</div>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">AX</span><span class="mf">.25</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span>
   <span class="nb">type</span> <span class="o">=</span> <span class="n">AX25KISSInterface</span>
 
@@ -1226,6 +1302,7 @@ to <code class="docutils literal notranslate"><span class="pre">30</span></code>
           <div class="toc-tree">
             <ul>
 <li><a class="reference internal" href="#">Configuring Interfaces</a><ul>
+<li><a class="reference internal" href="#custom-interfaces">Custom Interfaces</a></li>
 <li><a class="reference internal" href="#auto-interface">Auto Interface</a></li>
 <li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li>
 <li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li>

docs/manual/networks.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Code Examples" href="examples.html" /><link rel="prev" title="Configuring Interfaces" href="interfaces.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Building Networks - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>Building Networks - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">

docs/manual/reference.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="prev" title="Support Reticulum" href="support.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>API Reference - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>API Reference - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -228,7 +228,7 @@ This chapter lists and explains all classes exposed by the Reticulum Network Sta
 <p id="api-reticulum"><h3> Reticulum </h3></p>
 <dl class="py class">
 <dt class="sig sig-object py" id="RNS.Reticulum">
-<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Reticulum</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">configdir</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loglevel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">logdest</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbosity</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Reticulum" title="Permalink to this definition">#</a></dt>
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Reticulum</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">configdir</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loglevel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">logdest</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbosity</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">require_shared_instance</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Reticulum" title="Permalink to this definition">#</a></dt>
 <dd><p>This class is used to initialise access to Reticulum within a
 program. You must create exactly one instance of this class before
 carrying out any other RNS operations, such as creating destinations

docs/manual/search.html

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="#" />
 
-    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/><title>Search - Reticulum Network Stack 0.8.5 beta documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/><title>Search - Reticulum Network Stack 0.8.7 beta documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
@@ -138,7 +138,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -164,7 +164,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="#" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">

docs/manual/support.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <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="Code Examples" href="examples.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Support Reticulum - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>Support Reticulum - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -248,7 +248,8 @@ organisation? Make them a reality quickly by sponsoring their implementation.</p
 <h2>Provide Feedback<a class="headerlink" href="#provide-feedback" title="Permalink to this heading">#</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, telemetry, error
+improvement of Reticulum.</p>
+<p>Absolutely no automated analytics, telemetry, error
 reporting or statistics is collected and reported by Reticulum under any
 circumstances, so we rely on old-fashioned human feedback.</p>
 </section>

docs/manual/understanding.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Communications Hardware" href="hardware.html" /><link rel="prev" title="Using Reticulum on Your System" href="using.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Understanding Reticulum - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>Understanding Reticulum - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -1069,11 +1069,13 @@ both on general-purpose CPUs and on microcontrollers. The necessary primitives a
 <li><p>Ed25519 for signatures</p></li>
 <li><p>X25519 for ECDH key exchanges</p></li>
 <li><p>HKDF for key derivation</p></li>
-<li><p>Modified Fernet for encrypted tokens</p>
+<li><p>Encrypted tokens are based on the Fernet spec</p>
 <ul>
-<li><p>AES-128 in CBC mode</p></li>
-<li><p>HMAC for message authentication</p></li>
-<li><p>No Version and Timestamp metadata included</p></li>
+<li><p>Ephemeral keys derived from an ECDH key exchange on Curve25519</p></li>
+<li><p>AES-128 in CBC mode with PKCS7 padding</p></li>
+<li><p>HMAC using SHA256 for message authentication</p></li>
+<li><p>IVs are generated through os.urandom()</p></li>
+<li><p>No Fernet version and timestamp metadata fields</p></li>
 </ul>
 </li>
 <li><p>SHA-256</p></li>
@@ -1083,12 +1085,12 @@ both on general-purpose CPUs and on microcontrollers. The necessary primitives a
 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
+<code class="docutils literal notranslate"><span class="pre">Token</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/Token.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.
@@ -1097,9 +1099,12 @@ instead use the internal pure-python primitives. A trivial consequence of this i
 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>
+<div class="admonition warning">
+<p class="admonition-title">Warning</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>
 </section>
 </section>
 </section>

docs/manual/using.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <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="Getting Started Fast" href="gettingstartedfast.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Using Reticulum on Your System - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>Using Reticulum on Your System - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">

docs/manual/whatis.html

@@ -2,11 +2,11 @@
 <html class="no-js" lang="en">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
-    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
+    <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Getting Started Fast" href="gettingstartedfast.html" /><link rel="prev" title="Reticulum Network Stack Manual" href="index.html" />
 
     <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>What is Reticulum? - Reticulum Network Stack 0.8.5 beta documentation</title>
+        <title>What is Reticulum? - Reticulum Network Stack 0.8.7 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=189ec851f9bb375a2509b67be1f64f0cf212b702" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.5 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.7 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.5 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.7 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -235,7 +235,7 @@ respect and empower the autonomy and sovereignty of communities and individuals.
 Reticulum enables secure digital communication that cannot be subjected to
 outside control, manipulation or censorship.</p>
 <p>Reticulum enables the construction of both small and potentially planetary-scale
-networks, without any need for hierarchical or beaureucratic structures to control
+networks, without any need for hierarchical or bureaucratic structures to control
 or manage them, while ensuring individuals and communities full sovereignty
 over their own network segments.</p>
 <p>Reticulum is a <strong>complete networking stack</strong>, and does not need IP or higher
@@ -258,37 +258,62 @@ considered complete and stable at the moment, but could change if absolutely war
 <h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Permalink to this heading">#</a></h2>
 <ul class="simple">
 <li><p>Coordination-less globally unique addressing and identification</p></li>
-<li><p>Fully self-configuring multi-hop routing</p></li>
-<li><p>Complete initiator anonymity, communicate without revealing your identity</p></li>
-<li><p>Asymmetric encryption based on X25519, and Ed25519 signatures as a basis for all communication</p></li>
-<li><p>Forward Secrecy by using ephemeral Elliptic Curve Diffie-Hellman keys on Curve25519</p></li>
-<li><p>Reticulum uses a modified version of the <a class="reference external" href="https://github.com/fernet/spec/blob/master/Spec.md">Fernet</a> specification for on-the-wire / over-the-air encryption</p>
+<li><p>Fully self-configuring multi-hop routing over heterogeneous carriers</p></li>
+<li><p>Flexible scalability over heterogeneous topologies</p>
 <ul>
-<li><p>Keys are ephemeral and derived from an ECDH key exchange on Curve25519</p></li>
+<li><p>Reticulum can carry data over any mixture of physical mediums and topologies</p></li>
+<li><p>Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks</p></li>
+</ul>
+</li>
+<li><p>Initiator anonymity, communicate without revealing your identity</p>
+<ul>
+<li><p>Reticulum does not include source addresses on any packets</p></li>
+</ul>
+</li>
+<li><p>Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication</p>
+<ul>
+<li><p>The foundational Reticulum Identity Keys are 512-bit Elliptic Curve keysets</p></li>
+</ul>
+</li>
+<li><p>Forward Secrecy is available for all communication types, both for single packets and over links</p></li>
+<li><p>Reticulum uses the following format for encrypted tokens:</p>
+<ul>
+<li><p>Ephemeral per-packet and link keys and derived from an ECDH key exchange on Curve25519</p></li>
 <li><p>AES-128 in CBC mode with PKCS7 padding</p></li>
 <li><p>HMAC using SHA256 for authentication</p></li>
 <li><p>IVs are generated through os.urandom()</p></li>
-<li><p>No Version and Timestamp metadata included</p></li>
 </ul>
 </li>
 <li><p>Unforgeable packet delivery confirmations</p></li>
-<li><p>A variety of supported interface types</p></li>
-<li><p>An intuitive and developer-friendly API</p></li>
+<li><p>Flexible and extensible interface system</p>
+<ul>
+<li><p>Reticulum includes a large variety of built-in interface types</p></li>
+<li><p>Ability to load and utilise custom user- or community-supplied interface types</p></li>
+<li><p>Easily create your own custom interfaces for communicating over anything</p></li>
+</ul>
+</li>
+<li><p>Authentication and virtual network segmentation on all supported interface types</p></li>
+<li><p>An intuitive and easy-to-use API</p>
+<ul>
+<li><p>Simpler and easier to use than sockets APIs and simpler, but more powerful</p></li>
+<li><p>Makes building distributed and decentralised applications much simpler</p></li>
+</ul>
+</li>
+<li><p>Reliable and efficient transfer of arbitrary amounts of data</p>
+<ul>
+<li><p>Reticulum can handle a few bytes of data or files of many gigabytes</p></li>
+<li><p>Sequencing, compression, transfer coordination and checksumming are automatic</p></li>
+<li><p>The API is very easy to use, and provides transfer progress</p></li>
+</ul>
+</li>
+<li><p>Lightweight, flexible and expandable Request/Response mechanism</p></li>
 <li><p>Efficient link establishment</p>
 <ul>
 <li><p>Total cost of setting up an encrypted and verified link is only 3 packets, totalling 297 bytes</p></li>
 <li><p>Low cost of keeping links open at only 0.44 bits per second</p></li>
 </ul>
 </li>
-<li><p>Reliable and efficient transfer of arbitrary amounts of data</p>
-<ul>
-<li><p>Reticulum can handle a few bytes of data or files of many gigabytes</p></li>
-<li><p>Sequencing, transfer coordination and checksumming is automatic</p></li>
-<li><p>The API is very easy to use, and provides transfer progress</p></li>
-</ul>
-</li>
-<li><p>Authentication and virtual network segmentation on all supported interface types</p></li>
-<li><p>Flexible scalability allowing extremely low-bandwidth networks to co-exist and interoperate with large, high-bandwidth networks</p></li>
+<li><p>Reliable sequential delivery with Channel and Buffer mechanisms</p></li>
 </ul>
 </section>
 <section id="where-can-reticulum-be-used">
@@ -316,7 +341,7 @@ network, and vice versa.</p>
 </section>
 <section id="interface-types-and-devices">
 <h2>Interface Types and Devices<a class="headerlink" href="#interface-types-and-devices" title="Permalink to this heading">#</a></h2>
-<p>Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it’s relatively simple to implement an interface class. Currently, Reticulum can use the following devices and communication mediums:</p>
+<p>Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it’s simple to <a class="reference internal" href="examples.html#example-custominterface"><span class="std std-ref">implement an interface class</span></a>. Currently, Reticulum can use the following devices and communication mediums:</p>
 <ul class="simple">
 <li><p>Any Ethernet device</p>
 <ul>

docs/source/examples.rst

@@ -125,4 +125,18 @@ interface to efficiently pass files of any size over a Reticulum :ref:`Link<api-
 
 .. literalinclude:: ../../Examples/Filetransfer.py
 
-This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py>`_.
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py>`_.
+
+.. _example-custominterface:
+
+Custom Interfaces
+=================
+
+The *ExampleInterface* demonstrates creating custom interfaces for Reticulum.
+Any number of custom interfaces can be loaded and utilised by Reticulum, and
+will be fully on-par with natively included interfaces, including all supported
+:ref:`interface modes<interfaces-modes>` and :ref:`common configuration options<interfaces-options>`.
+
+.. literalinclude:: ../../Examples/ExampleInterface.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/ExampleInterface.py>`_.

docs/source/gettingstartedfast.rst

@@ -27,9 +27,14 @@ and install them offline using ``pip``:
 
    pip install ./rns-0.5.1-py3-none-any.whl
 
+For more detailed installation instructions, please see the
+:ref:`Platform-Specific Install Notes<install-guides>` section.
+
+After installation is complete, it might be helpful to refer to the
+:ref:`Using Reticulum on Your System<using-main>` chapter.
 
 Resolving Dependency & Installation Issues
-=============================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 On some platforms, there may not be binary packages available for all dependencies, and
 ``pip`` installation may fail with an error message. In these cases, the issue can usually
 be resolved by installing the development essentials packages for your platform:
@@ -100,10 +105,12 @@ You can install Nomad Network via pip:
    # ... and run
    nomadnet
 
-**Please Note**: If this is the very first time you use pip to install a program
-on your system, you might need to reboot your system for your program to become
-available. If you get a "command not found" error or similar when running the
-program, reboot your system and try again.
+.. note::
+   If this is the very first time you use ``pip`` to install a program
+   on your system, you might need to reboot your system for your program to become
+   available. If you get a "command not found" error or similar when running the
+   program, reboot your system and try again. In some cases, you may even need to
+   manually add the ``pip`` install path to your ``PATH`` environment variable.
 
 Sideband
 ^^^^^^^^
@@ -305,6 +312,20 @@ you are welcome to head over to the `GitHub discussion pages <https://github.com
 and propose adding an interface for the hardware.
 
 
+Creating and Using Custom Interfaces
+===========================================
+
+While Reticulum includes a flexible and broad range of built-in interfaces, these
+will not cover every conceivable type of communications hardware that Reticulum
+can potentially use to communicate.
+
+It is therefore possible to easily write your own interface modules, that can be
+loaded at run-time and used on-par with any of the built-in interface types.
+
+For more information on this subject, and code examples to build on, please see
+the :ref:`Configuring Interfaces<interfaces-main>` chapter.
+
+
 Develop a Program with Reticulum
 ===========================================
 If you want to develop programs that use Reticulum, the easiest way to get
@@ -318,14 +339,8 @@ The above command will install Reticulum and dependencies, and you will be
 ready to import and use RNS in your own programs. The next step will most
 likely be to look at some :ref:`Example Programs<examples-main>`.
 
-For extended functionality, you can install optional dependencies:
-
-.. code::
-
-   pip install pyserial
-
-
-Further information can be found in the :ref:`API Reference<api-main>`.
+The entire Reticulum API is documented in the :ref:`API Reference<api-main>`
+chapter of this manual.
 
 
 Participate in Reticulum Development
@@ -373,6 +388,7 @@ your first pull request, it is probably a good idea to introduce yourself on
 the `disucssion forum on GitHub <https://github.com/markqvist/Reticulum/discussions>`_,
 or ask one of the developers or maintainers for a good place to start.
 
+.. _install-guides:
 
 Platform-Specific Install Notes
 ==============================================
@@ -451,7 +467,7 @@ here at a later point. Until then you can use the `Sideband source code <https:/
 ARM64
 ^^^^^^^^^^^^^^^^^^^^^^^^
 On some architectures, including ARM64, not all dependencies have precompiled
-binaries. On such systems, you may need to install ``python3-dev`` before
+binaries. On such systems, you may need to install ``python3-dev`` (or similar) before
 installing Reticulum or programs that depend on Reticulum.
 
 .. code::
@@ -463,16 +479,8 @@ installing Reticulum or programs that depend on Reticulum.
    # Install Reticulum
    python3 -m pip install rns
 
-
-Raspberry Pi
-^^^^^^^^^^^^^^^^^^^^^^^^^
-It is currently recommended to use a 64-bit version of the Raspberry Pi OS
-if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
-don't always have packages available for some dependencies.
-
-While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
-it will require manually configuring and installing some packages, and is not
-detailed in this manual.
+With these packages installed, ``pip`` will be able to build any missing dependencies
+on your system locally.
 
 
 Debian Bookworm
@@ -503,10 +511,152 @@ following section:
     [global]
     break-system-packages = true
 
-Please note that the "break-system-packages" directive is a somewhat misleading choice
-of words. Setting it will of course not break any system packages, but will simply
-allow installing ``pip`` packages user- and system-wide. While this *could* in rare
-cases lead to version conflicts, it does not generally pose any problems.
+For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages``
+option, you can use the following command:
+
+.. code:: text
+
+    pip install rns --break-system-packages
+
+.. note::
+   The ``--break-system-packages`` directive is a somewhat misleading choice
+   of words. Setting it will of course not break any system packages, but will simply
+   allow installing ``pip`` packages user- and system-wide. While this *could* in rare
+   cases lead to version conflicts, it does not generally pose any problems, especially
+   not in the case of installing Reticulum.
+
+
+MacOS
+^^^^^^^^^^^^^^^^^^^^^^^^^
+To install Reticulum on macOS, you will need to have Python and the ``pip`` package
+manager installed.
+
+Systems running macOS can vary quite widely in whether or not Python is pre-installed,
+and if it is, which version is installed, and whether the ``pip`` package manager is
+also installed and set up. If in doubt, you can `download and install <https://www.python.org/downloads/>`_
+Python manually.
+
+When Python and ``pip`` is available on your system, simply open a terminal window
+and use one of the following commands:
+
+.. code::
+
+   # Install Reticulum and utilities with pip:
+   pip3 install rns
+   
+   # On some versions, you may need to use the
+   # flag --break-system-packages to install:
+   pip3 install rns --break-system-packages
+
+.. note::
+   The ``--break-system-packages`` directive is a somewhat misleading choice
+   of words. Setting it will of course not break any system packages, but will simply
+   allow installing ``pip`` packages user- and system-wide. While this *could* in rare
+   cases lead to version conflicts, it does not generally pose any problems, especially
+   not in the case of installing Reticulum.
+
+Additionally, some version combinations of macOS and Python require you to
+manually add your installed ``pip`` packages directory to your `PATH` environment
+variable, before you can use installed commands in your terminal. Usually, adding
+the following line to your shell init script (for example ``~/.zshrc``) will be enough:
+
+.. code::
+
+   export PATH=$PATH:~/Library/Python/3.9/bin
+
+Adjust Python version and shell init script location according to your system.
+
+
+OpenWRT
+^^^^^^^^^^^^^^^^^^^^^^^^^
+On OpenWRT systems with sufficient storage and memory, you can install
+Reticulum and related utilities using the `opkg` package manager and `pip`.
+
+.. note::
+
+   At the time of releasing this manual, work is underway to create pre-built
+   Reticulum packages for OpenWRT, with full configuration, service
+   and ``uci`` integration. Please see the `feed-reticulum <https://github.com/gretel/feed-reticulum>`_
+   and `reticulum-openwrt <https://github.com/gretel/reticulum-openwrt>`_
+   repositories for more information.
+
+To install Reticulum on OpenWRT, first log into a command line session, and
+then use the following instructions:
+
+.. code::
+
+   # Install dependencies
+   opkg install python3 python3-pip python3-cryptography python3-pyserial
+   
+   # Install Reticulum
+   pip install rns
+
+   # Start rnsd with debug logging enabled
+   rnsd -vvv
+
+.. note::
+   
+   The above instructions have been verified and tested on OpenWRT 21.02 only.
+   It is likely that other versions may require slightly altered installation
+   commands or package names. You will also need enough free space in your
+   overlay FS, and enough free RAM to actually run Reticulum and any related
+   programs and utilities.
+
+Depending on your device configuration, you may need to adjust firewall rules
+for Reticulum connectivity to and from your device to work. Until proper
+packaging is ready, you will also need to manually create a service or startup
+script to automatically laucnh Reticulum at boot time.
+
+Please also note that the `AutoInterface` requires link-local IPv6 addresses
+to be enabled for any Ethernet and WiFi devices you intend to use. If ``ip a``
+shows an address starting with ``fe80::`` for the device in question,
+``AutoInterface`` should work for that device.
+
+Raspberry Pi
+^^^^^^^^^^^^^^^^^^^^^^^^^
+It is currently recommended to use a 64-bit version of the Raspberry Pi OS
+if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
+don't always have packages available for some dependencies. If Python and the
+`pip` package manager is not already installed, do that first, and then
+install Reticulum using `pip`.
+
+.. code::
+
+   # Install dependencies
+   sudo apt install python3 python3-pip python3-cryptography python3-pyserial
+   
+   # Install Reticulum
+   pip install rns --break-system-packages
+
+.. note::
+   The ``--break-system-packages`` directive is a somewhat misleading choice
+   of words. Setting it will of course not break any system packages, but will simply
+   allow installing ``pip`` packages user- and system-wide. While this *could* in rare
+   cases lead to version conflicts, it does not generally pose any problems, especially
+   not in the case of installing Reticulum.
+
+While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes,
+it will require manually configuring and installing required build dependencies,
+and is not detailed in this manual.
+
+
+RISC-V
+^^^^^^^^^^^^^^^^^^^^^^^^
+On some architectures, including RISC-V, not all dependencies have precompiled
+binaries. On such systems, you may need to install ``python3-dev`` (or similar) before
+installing Reticulum or programs that depend on Reticulum.
+
+.. code::
+
+   # Install Python and development packages
+   sudo apt update
+   sudo apt install python3 python3-pip python3-dev
+
+   # Install Reticulum
+   python3 -m pip install rns
+
+With these packages installed, ``pip`` will be able to build any missing dependencies
+on your system locally.
 
 
 Ubuntu Lunar
@@ -537,13 +687,52 @@ following section:
     [global]
     break-system-packages = true
 
-Please note that the "break-system-packages" directive is a somewhat misleading choice
-of words. Setting it will of course not break any system packages, but will simply
-allow installing ``pip`` packages user- and system-wide. While this _could_ in rare
-cases lead to version conflicts, it does not generally pose any problems.
+For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages``
+option, you can use the following command:
+
+.. code:: text
+
+    pip install rns --break-system-packages
+
+.. note::
+   The ``--break-system-packages`` directive is a somewhat misleading choice
+   of words. Setting it will of course not break any system packages, but will simply
+   allow installing ``pip`` packages user- and system-wide. While this *could* in rare
+   cases lead to version conflicts, it does not generally pose any problems, especially
+   not in the case of installing Reticulum.
+
+Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^
+On Windows operating systems, the easiest way to install Reticulum is by using the
+``pip`` package manager from the command line (either the command prompt or Windows
+Powershell).
+
+If you don't already have Python installed, `download and install Python <https://www.python.org/downloads/>`_.
+At the time of publication of this manual, the recommended version is `Python 3.12.7 <https://www.python.org/downloads/release/python-3127>`_.
+
+**Important!** When asked by the installer, make sure to add the Python program to
+your PATH environment variables. If you don't do this, you will not be able to
+use the ``pip`` installer, or run the included Reticulum utility programs (such as
+``rnsd`` and ``rnstatus``) from the command line.
+
+After installing Python, open the command prompt or Windows Powershell, and type:
+
+.. code::
+
+   pip install rns
+
+You can now use Reticulum and all included utility programs directly from your
+preferred command line interface.
 
 Pure-Python Reticulum
 ==============================================
+
+.. warning::
+   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.
+
 In some rare cases, and on more obscure system types, it is not possible to
 install one or more dependencies. In such situations,
 you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip``
@@ -558,8 +747,3 @@ only if they are *needed* and *available*. If for example you want to use Reticu
 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 <https://github.com/pyca/cryptography>`_, it is
-important that you read and understand the :ref:`Cryptographic Primitives <understanding-primitives>`
-section of this manual.

docs/source/hardware.rst

@@ -75,8 +75,8 @@ completely from scratch, to your exact desired specifications, this chapter
 will explain the easiest possible approach to creating RNodes: 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
+1. Obtain one or more :ref:`supported development boards<rnode-supported>`
+2. Install the RNode firmware with the :ref:`automated installer<rnode-installation>`
 
 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.
@@ -85,8 +85,8 @@ to the configuration.
 
 .. _rnode-supported:
 
-Supported Boards
-^^^^^^^^^^^^^^^^
+Supported Boards and Devices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 To create one or more RNodes, you will need to obtain supported development
 boards. The following boards are supported by the auto-installer.
 

docs/source/interfaces.rst

@@ -19,6 +19,16 @@ types, have a look at the :ref:`Building Networks<networks-main>` chapter of thi
 manual.
 
 
+.. _interfaces-custom:
+
+Custom Interfaces
+=================
+
+In addition to the built-in interface types, Reticulum is **fully extensible** with
+custom, user- or community-supplied interfaces, and creating custom interface
+modules is straightforward. Please see the :ref:`custom interface<example-custominterface>`
+example for basic interface code to build upon.
+
 .. _interfaces-auto:
 
 Auto Interface
@@ -152,11 +162,12 @@ It can take anywhere from a few seconds to a few minutes to establish
 I2P connections to the desired peers, so Reticulum handles the process
 in the background, and will output relevant events to the log.
 
-**Please Note!** While the I2P interface is the simplest way to use
-Reticulum over I2P, it is also possible to tunnel the TCP server and
-client interfaces over I2P manually. This can be useful in situations
-where more control is needed, but requires manual tunnel setup through
-the I2P daemon configuration.
+.. note::
+   While the I2P interface is the simplest way to use
+   Reticulum over I2P, it is also possible to tunnel the TCP server and
+   client interfaces over I2P manually. This can be useful in situations
+   where more control is needed, but requires manual tunnel setup through
+   the I2P daemon configuration.
 
 It is important to note that the two methods are *interchangably compatible*.
 You can use the I2PInterface to connect to a TCPServerInterface that
@@ -171,7 +182,7 @@ TCP Server Interface
 ====================
 
 The TCP Server interface is suitable for allowing other peers to connect over
-the Internet or private IP networks. When a TCP server interface has been
+the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been
 configured, other Reticulum peers can connect to it with a TCP Client interface.
 
 .. code::
@@ -200,8 +211,37 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
     # device = eth0
     # port = 4242
 
-**Please Note!** The TCP interfaces support tunneling over I2P, but to do so reliably,
-you must use the i2p_tunneled option:
+If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
+you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
+
+.. code::
+
+  # This example demonstrates a TCP server interface.
+  # It will listen for incoming connections on the
+  # specified IP address and port number.
+  
+  [[TCP Server Interface]]
+    type = TCPServerInterface
+    interface_enabled = True
+
+    device = eth0
+    port = 4242
+    prefer_ipv6 = True
+
+To use the TCP Server Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you
+can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
+
+.. code::
+
+  [[Yggdrasil TCP Server Interface]]
+      type = TCPServerInterface
+      interface_enabled = yes
+      device = tun0
+      listen_port = 4343
+
+.. note::
+   The TCP interfaces support tunneling over I2P, but to do so reliably,
+   you must use the i2p_tunneled option:
 
 .. code::
 
@@ -231,7 +271,7 @@ and restore connectivity after a failure, once the other end of a TCP interface
 .. code::
 
   # Here's an example of a TCP Client interface. The
-  # target_host can either be an IP address or a hostname.
+  # target_host can be a hostname or an IPv4 or IPv6 address.
 
   [[TCP Client Interface]]
     type = TCPClientInterface
@@ -239,6 +279,17 @@ and restore connectivity after a failure, once the other end of a TCP interface
     target_host = 127.0.0.1
     target_port = 4242
 
+To use the TCP Client Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, simply
+specify the target Yggdrasil IPv6 address and port, like so:
+
+.. code::
+
+  [[Yggdrasil TCP Client Interface]]
+      type = TCPClientInterface
+      interface_enabled = yes
+      target_host = 201:5d78:af73:5caf:a4de:a79f:3278:71e5
+      target_port = 4343
+
 It is also possible to use this interface type to connect via other programs
 or hardware devices that expose a KISS interface on a TCP port, for example
 software-based soundmodems. To do this, use the ``kiss_framing`` option:
@@ -262,8 +313,9 @@ never enable ``kiss_framing``, since this will disable internal reliability and
 recovery mechanisms that greatly improves performance over unreliable and
 intermittent TCP links.
 
-**Please Note!** The TCP interfaces support tunneling over I2P, but to do so reliably,
-you must use the i2p_tunneled option:
+.. note::
+   The TCP interfaces support tunneling over I2P, but to do so reliably,
+   you must use the i2p_tunneled option:
 
 .. code::
 
@@ -285,11 +337,12 @@ private and the internet. It can also allow broadcast communication
 over IP networks, so it can provide an easy way to enable connectivity
 with all other peers on a local area network.
 
-*Please Note!* Using broadcast UDP traffic has performance implications,
-especially on WiFi. If your goal is simply to enable easy communication
-with all peers in your local Ethernet broadcast domain, the
-:ref:`Auto Interface<interfaces-auto>` performs better, and is even
-easier to use.
+.. warning::
+   Using broadcast UDP traffic has performance implications,
+   especially on WiFi. If your goal is simply to enable easy communication
+   with all peers in your local Ethernet broadcast domain, the
+   :ref:`Auto Interface<interfaces-auto>` performs better, and is even
+   easier to use.
 
 .. code::
 
@@ -344,6 +397,11 @@ RNode LoRa Interface
 To use Reticulum over LoRa, the `RNode <https://unsigned.io/rnode/>`_ interface
 can be used, and offers full control over LoRa parameters.
 
+.. warning::
+   Radio frequency spectrum is a legally controlled resource, and legislation
+   varies widely around the world. It is your responsibility to be aware of any
+   relevant regulation for your location, and to make decisions accordingly.
+
 .. code::
 
   # Here's an example of how to add a LoRa interface
@@ -431,6 +489,11 @@ RNode Multi Interface
 For RNodes that support multiple LoRa transceivers, the RNode
 Multi interface can be used to configure sub-interfaces individually.
 
+.. warning::
+   Radio frequency spectrum is a legally controlled resource, and legislation
+   varies widely around the world. It is your responsibility to be aware of any
+   relevant regulation for your location, and to make decisions accordingly.
+
 .. code::
 
   # Here's an example of how to add an RNode Multi interface
@@ -454,89 +517,89 @@ Multi interface can be used to configure sub-interfaces individually.
   # id_interval = 600
 
     # A subinterface
-    [[[HIGHDATARATE]]]
-    # Subinterfaces can be enabled and disabled in of themselves
-    interface_enabled = True
+    [[[High Datarate]]]
+      # Subinterfaces can be enabled and disabled in of themselves
+      interface_enabled = True
 
-    # Set frequency to 2.4GHz
-    frequency = 2400000000
+      # Set frequency to 2.4GHz
+      frequency = 2400000000
 
-    # Set LoRa bandwidth to 1625 KHz
-    bandwidth = 1625000
+      # Set LoRa bandwidth to 1625 KHz
+      bandwidth = 1625000
 
-    # Set TX power to 0 dBm (0.12 mW)
-    txpower = 0
+      # Set TX power to 0 dBm (0.12 mW)
+      txpower = 0
 
-    # The virtual port, only the manufacturer
-    # or the person who wrote the board config
-    # can tell you what it will be for which
-    # physical hardware interface
-    vport = 1
+      # The virtual port, only the manufacturer
+      # or the person who wrote the board config
+      # can tell you what it will be for which
+      # physical hardware interface
+      vport = 1
 
-    # Select spreading factor 5. Valid
-    # range is 5 through 12, with 5 
-    # being the fastest and 12 having
-    # the longest range.
-    spreadingfactor = 5
+      # Select spreading factor 5. Valid
+      # range is 5 through 12, with 5 
+      # being the fastest and 12 having
+      # the longest range.
+      spreadingfactor = 5
 
-    # Select coding rate 5. Valid range
-    # is 5 throough 8, with 5 being the
-    # fastest, and 8 the longest range.
-    codingrate = 5
+      # Select coding rate 5. Valid range
+      # is 5 throough 8, with 5 being the
+      # fastest, and 8 the longest range.
+      codingrate = 5
 
-    # It is possible to limit the airtime
-    # utilisation of an RNode by using the
-    # following two configuration options.
-    # The short-term limit is applied in a
-    # window of approximately 15 seconds,
-    # and the long-term limit is enforced
-    # over a rolling 60 minute window. Both
-    # options are specified in percent.
+      # It is possible to limit the airtime
+      # utilisation of an RNode by using the
+      # following two configuration options.
+      # The short-term limit is applied in a
+      # window of approximately 15 seconds,
+      # and the long-term limit is enforced
+      # over a rolling 60 minute window. Both
+      # options are specified in percent.
 
-    # airtime_limit_long = 100
-    # airtime_limit_short = 100
+      # airtime_limit_long = 100
+      # airtime_limit_short = 100
 
-    [[[LOWDATARATE]]]
-    # Subinterfaces can be enabled and disabled in of themselves
-    interface_enabled = True
+    [[[Low Datarate]]]
+      # Subinterfaces can be enabled and disabled in of themselves
+      interface_enabled = True
 
-    # Set frequency to 865.6 MHz
-    frequency = 865600000
+      # Set frequency to 865.6 MHz
+      frequency = 865600000
 
-    # The virtual port, only the manufacturer
-    # or the person who wrote the board config
-    # can tell you what it will be for which
-    # physical hardware interface
-    vport = 0
+      # The virtual port, only the manufacturer
+      # or the person who wrote the board config
+      # can tell you what it will be for which
+      # physical hardware interface
+      vport = 0
 
-    # Set LoRa bandwidth to 125 KHz
-    bandwidth = 125000
+      # Set LoRa bandwidth to 125 KHz
+      bandwidth = 125000
 
-    # Set TX power to 0 dBm (0.12 mW)
-    txpower = 0
+      # Set TX power to 0 dBm (0.12 mW)
+      txpower = 0
 
-    # Select spreading factor 7. Valid
-    # range is 5 through 12, with 5 
-    # being the fastest and 12 having
-    # the longest range.
-    spreadingfactor = 7
+      # Select spreading factor 7. Valid
+      # range is 5 through 12, with 5 
+      # being the fastest and 12 having
+      # the longest range.
+      spreadingfactor = 7
 
-    # Select coding rate 5. Valid range
-    # is 5 throough 8, with 5 being the
-    # fastest, and 8 the longest range.
-    codingrate = 5
+      # Select coding rate 5. Valid range
+      # is 5 throough 8, with 5 being the
+      # fastest, and 8 the longest range.
+      codingrate = 5
 
-    # It is possible to limit the airtime
-    # utilisation of an RNode by using the
-    # following two configuration options.
-    # The short-term limit is applied in a
-    # window of approximately 15 seconds,
-    # and the long-term limit is enforced
-    # over a rolling 60 minute window. Both
-    # options are specified in percent.
+      # It is possible to limit the airtime
+      # utilisation of an RNode by using the
+      # following two configuration options.
+      # The short-term limit is applied in a
+      # window of approximately 15 seconds,
+      # and the long-term limit is enforced
+      # over a rolling 60 minute window. Both
+      # options are specified in percent.
 
-    # airtime_limit_long = 100
-    # airtime_limit_short = 100
+      # airtime_limit_long = 100
+      # airtime_limit_short = 100
 
 .. _interfaces-serial:
 
@@ -598,6 +661,11 @@ radio modems and TNCs, including `OpenModem <https://unsigned.io/openmodem/>`_.
 KISS interfaces can also be configured to periodically send out beacons
 for station identification purposes.
 
+.. warning::
+   Radio frequency spectrum is a legally controlled resource, and legislation
+   varies widely around the world. It is your responsibility to be aware of any
+   relevant regulation for your location, and to make decisions accordingly.
+
 .. code::
 
   [[Packet Radio KISS Interface]]
@@ -661,6 +729,11 @@ encapsulate in AX.25.
 A more efficient way is to use the plain KISS interface with the
 beaconing functionality described above.
 
+.. warning::
+   Radio frequency spectrum is a legally controlled resource, and legislation
+   varies widely around the world. It is your responsibility to be aware of any
+   relevant regulation for your location, and to make decisions accordingly.
+
 .. code::
 
   [[Packet Radio AX.25 KISS Interface]]

docs/source/support.rst

@@ -32,7 +32,9 @@ 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, telemetry, error
+improvement of Reticulum.
+
+Absolutely no automated analytics, telemetry, error
 reporting or statistics is collected and reported by Reticulum under any
 circumstances, so we rely on old-fashioned human feedback.
 

docs/source/understanding.rst

@@ -868,13 +868,17 @@ both on general-purpose CPUs and on microcontrollers. The necessary primitives a
 
 * HKDF for key derivation
 
-* Modified Fernet for encrypted tokens
+* Encrypted tokens are based on the Fernet spec
 
-  * AES-128 in CBC mode
+  * Ephemeral keys derived from an ECDH key exchange on Curve25519
 
-  * HMAC for message authentication
+  * AES-128 in CBC mode with PKCS7 padding
 
-  * No Version and Timestamp metadata included
+  * HMAC using SHA256 for message authentication
+
+  * IVs are generated through os.urandom()
+
+  * No Fernet version and timestamp metadata fields
 
 * SHA-256
 
@@ -884,12 +888,12 @@ In the default installation configuration, the ``X25519``, ``Ed25519`` and ``AES
 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
+``Token`` 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/Token.py``
 - ``RNS/Cryptography/PKCS7.py``
 
 
@@ -900,6 +904,7 @@ with the OpenSSL backend being *much* faster. The most important consequence how
 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.
+.. warning::
+   If you want to use the internal pure-python primitives, it is **highly advisable** that you
+   have a good understanding of the risks that this pose, and make an informed decision on whether
+   those risks are acceptable to you.

docs/source/whatis.rst

@@ -17,7 +17,7 @@ Reticulum enables secure digital communication that cannot be subjected to
 outside control, manipulation or censorship.
 
 Reticulum enables the construction of both small and potentially planetary-scale
-networks, without any need for hierarchical or beaureucratic structures to control
+networks, without any need for hierarchical or bureaucratic structures to control
 or manage them, while ensuring individuals and communities full sovereignty
 over their own network segments.
 
@@ -43,19 +43,30 @@ considered complete and stable at the moment, but could change if absolutely war
 
 What does Reticulum Offer?
 ==========================
+
 * Coordination-less globally unique addressing and identification
 
-* Fully self-configuring multi-hop routing
+* Fully self-configuring multi-hop routing over heterogeneous carriers
 
-* Complete initiator anonymity, communicate without revealing your identity
+* Flexible scalability over heterogeneous topologies
 
-* Asymmetric encryption based on X25519, and Ed25519 signatures as a basis for all communication
+  * Reticulum can carry data over any mixture of physical mediums and topologies
 
-* Forward Secrecy by using ephemeral Elliptic Curve Diffie-Hellman keys on Curve25519
+  * Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks
 
-* Reticulum uses a modified version of the `Fernet <https://github.com/fernet/spec/blob/master/Spec.md>`_ specification for on-the-wire / over-the-air encryption
+* Initiator anonymity, communicate without revealing your identity
 
-  * Keys are ephemeral and derived from an ECDH key exchange on Curve25519
+  * Reticulum does not include source addresses on any packets
+
+* Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
+
+  * The foundational Reticulum Identity Keys are 512-bit Elliptic Curve keysets
+
+* Forward Secrecy is available for all communication types, both for single packets and over links
+
+* Reticulum uses the following format for encrypted tokens:
+
+  * Ephemeral per-packet and link keys and derived from an ECDH key exchange on Curve25519
 
   * AES-128 in CBC mode with PKCS7 padding
 
@@ -63,13 +74,33 @@ What does Reticulum Offer?
 
   * IVs are generated through os.urandom()
 
-  * No Version and Timestamp metadata included
-
 * Unforgeable packet delivery confirmations
 
-* A variety of supported interface types
+* Flexible and extensible interface system
 
-* An intuitive and developer-friendly API
+  * Reticulum includes a large variety of built-in interface types
+
+  * Ability to load and utilise custom user- or community-supplied interface types
+
+  * Easily create your own custom interfaces for communicating over anything
+
+* Authentication and virtual network segmentation on all supported interface types
+
+* An intuitive and easy-to-use API
+
+  * Simpler and easier to use than sockets APIs and simpler, but more powerful
+
+  * Makes building distributed and decentralised applications much simpler
+
+* Reliable and efficient transfer of arbitrary amounts of data
+
+  * Reticulum can handle a few bytes of data or files of many gigabytes
+
+  * Sequencing, compression, transfer coordination and checksumming are automatic
+
+  * The API is very easy to use, and provides transfer progress
+
+* Lightweight, flexible and expandable Request/Response mechanism
 
 * Efficient link establishment
 
@@ -77,17 +108,7 @@ What does Reticulum Offer?
 
   * Low cost of keeping links open at only 0.44 bits per second
 
-* Reliable and efficient transfer of arbitrary amounts of data
-
-  * Reticulum can handle a few bytes of data or files of many gigabytes
-
-  * Sequencing, transfer coordination and checksumming is automatic
-
-  * The API is very easy to use, and provides transfer progress
-
-* Authentication and virtual network segmentation on all supported interface types
-
-* Flexible scalability allowing extremely low-bandwidth networks to co-exist and interoperate with large, high-bandwidth networks
+* Reliable sequential delivery with Channel and Buffer mechanisms
 
 
 Where can Reticulum be Used?
@@ -118,7 +139,7 @@ network, and vice versa.
 
 Interface Types and Devices
 ===========================
-Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it's relatively simple to implement an interface class. Currently, Reticulum can use the following devices and communication mediums:
+Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it's simple to :ref:`implement an interface class<example-custominterface>`. Currently, Reticulum can use the following devices and communication mediums:
 
 * Any Ethernet device
 
@@ -168,4 +189,4 @@ such. While it has been built with cryptography best-practices very foremost in
 mind, it has not yet been externally security audited, and there could very well be
 privacy-breaking bugs. To be considered secure, Reticulum needs a thorough
 security review by independent cryptographers and security researchers. If you
-want to help out with this, or can help sponsor an audit, please do get in touch.
+want to help out with this, or can help sponsor an audit, please do get in touch.