Updated manual

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,37 @@
+### 2024-12-11: RNS β 0.8.8
+
+This maintenance release adds a single API function and fixes a bug.
+
+**Changes**
+- Allow announce handlers to receive announce packet hash
+- Fix packet RSSI/SNR/Q cache not being available on standalone instances
+
+**Release Hashes**
+```
+9c1755a81049c67b051ecb9fe4b2c5f7d98bf09d20ed52d6ce6a410298b0527b rns-0.8.8-py3-none-any.whl
+d8871d69cde4b0a0b99b383f324d651dc77a2f44ec9641be828902c778a8d128 rnspure-0.8.8-py3-none-any.whl
+```
+
+### 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.

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>

RNS/Cryptography/__init__.py

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

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
@@ -262,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):
@@ -468,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
@@ -809,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)
@@ -1285,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

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

RNS/Interfaces/I2PInterface.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 platform

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

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

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

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
@@ -118,6 +119,8 @@ class RNodeInterface(Interface):
     BATTERY_STATE_CHARGING    = 0x02
     BATTERY_STATE_CHARGED     = 0x03
 
+    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")
@@ -236,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
@@ -453,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])
@@ -916,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

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
@@ -197,14 +197,13 @@ class RNodeMultiInterface(Interface):
         # 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):
+            if isinstance(c[subinterface], dict):
                 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 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
 
@@ -213,9 +212,8 @@ class RNodeMultiInterface(Interface):
         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 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
 

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

RNS/Interfaces/TCPInterface.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 platform

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

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/Packet.py

@@ -501,6 +501,10 @@ class PacketReceipt:
                 return False
         elif len(proof) == PacketReceipt.IMPL_LENGTH:
             # This is an implicit proof
+
+            if not hasattr(self.destination, "identity"):
+                return False
+
             if self.destination.identity == None:
                 return False
 

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
@@ -213,6 +213,9 @@ 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"
@@ -283,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()
 

RNS/Transport.py

@@ -25,6 +25,7 @@ import RNS
 import time
 import math
 import struct
+import inspect
 import threading
 from time import sleep
 from .vendor import umsgpack as umsgpack
@@ -102,9 +103,9 @@ class Transport:
     path_requests               = {}           # A table for storing path request timestamps
     path_states                 = {}           # A table for keeping track of path states
     
-    discovery_path_requests     = {}       # A table for keeping track of path requests on behalf of other nodes
-    discovery_pr_tags           = []       # A table for keeping track of tagged path requests
-    max_pr_tags                 = 32000    # Maximum amount of unique path request tags to remember
+    discovery_path_requests     = {}           # A table for keeping track of path requests on behalf of other nodes
+    discovery_pr_tags           = []           # A table for keeping track of tagged path requests
+    max_pr_tags                 = 32000        # Maximum amount of unique path request tags to remember
 
     # Transport control destinations are used
     # for control purposes like path requests
@@ -1149,29 +1150,23 @@ class Transport:
             if hasattr(interface, "r_stat_rssi"):
                 if interface.r_stat_rssi != None:
                     packet.rssi = interface.r_stat_rssi
-                    if len(Transport.local_client_interfaces) > 0:
-                        Transport.local_client_rssi_cache.append([packet.packet_hash, packet.rssi])
-
-                        while len(Transport.local_client_rssi_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
-                            Transport.local_client_rssi_cache.pop(0)
+                    Transport.local_client_rssi_cache.append([packet.packet_hash, packet.rssi])
+                    while len(Transport.local_client_rssi_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
+                        Transport.local_client_rssi_cache.pop(0)
 
             if hasattr(interface, "r_stat_snr"):
                 if interface.r_stat_rssi != None:
                     packet.snr = interface.r_stat_snr
-                    if len(Transport.local_client_interfaces) > 0:
-                        Transport.local_client_snr_cache.append([packet.packet_hash, packet.snr])
-
-                        while len(Transport.local_client_snr_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
-                            Transport.local_client_snr_cache.pop(0)
+                    Transport.local_client_snr_cache.append([packet.packet_hash, packet.snr])
+                    while len(Transport.local_client_snr_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
+                        Transport.local_client_snr_cache.pop(0)
 
             if hasattr(interface, "r_stat_q"):
                 if interface.r_stat_q != None:
                     packet.q = interface.r_stat_q
-                    if len(Transport.local_client_interfaces) > 0:
-                        Transport.local_client_q_cache.append([packet.packet_hash, packet.q])
-
-                        while len(Transport.local_client_q_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
-                            Transport.local_client_q_cache.pop(0)
+                    Transport.local_client_q_cache.append([packet.packet_hash, packet.q])
+                    while len(Transport.local_client_q_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
+                        Transport.local_client_q_cache.pop(0)
 
         if len(Transport.local_client_interfaces) > 0:
             if Transport.is_local_client_interface(interface):
@@ -1713,11 +1708,20 @@ class Transport:
                                             execute_callback = False
 
                                     if execute_callback:
-                                        handler.received_announce(
-                                            destination_hash=packet.destination_hash,
-                                            announced_identity=announce_identity,
-                                            app_data=RNS.Identity.recall_app_data(packet.destination_hash)
-                                        )
+
+                                        if len(inspect.signature(handler.received_announce).parameters) == 3:
+                                            handler.received_announce(destination_hash=packet.destination_hash,
+                                                                      announced_identity=announce_identity,
+                                                                      app_data=RNS.Identity.recall_app_data(packet.destination_hash))
+                                        
+                                        elif len(inspect.signature(handler.received_announce).parameters) == 4:
+                                            handler.received_announce(destination_hash=packet.destination_hash,
+                                                                      announced_identity=announce_identity,
+                                                                      app_data=RNS.Identity.recall_app_data(packet.destination_hash),
+                                                                      announce_packet_hash = packet.packet_hash)
+                                        else:
+                                            raise TypeError("Invalid signature for announce handler callback")
+
                                 except Exception as e:
                                     RNS.log("Error while processing external announce callback.", RNS.LOG_ERROR)
                                     RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -2021,8 +2025,9 @@ class Transport:
         Registers an announce handler.
 
         :param handler: Must be an object with an *aspect_filter* attribute and a *received_announce(destination_hash, announced_identity, app_data)*
-                        callable. Can optionally have a *receive_path_responses* attribute set to ``True``, to also receive all path responses, in addition to live
-                        announces. See the :ref:`Announce Example<example-announce>` for more info.
+                        or *received_announce(destination_hash, announced_identity, app_data, announce_packet_hash)* callable. Can optionally have a
+                        *receive_path_responses* attribute set to ``True``, to also receive all path responses, in addition to live announces. See
+                        the :ref:`Announce Example<example-announce>` for more info.
         """
         if hasattr(handler, "received_announce") and callable(handler.received_announce):
             if hasattr(handler, "aspect_filter"):

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/rnodeconf.py

@@ -278,7 +278,7 @@ models = {
     0xBB: [850000000, 950000000, 17, "850 - 950 MHz", "rnode_firmware_lora32v10.zip", "SX1276"],
     0xC4: [420000000, 520000000, 17, "420 - 520 MHz", "rnode_firmware_heltec32v2.zip", "SX1278"],
     0xC9: [850000000, 950000000, 17, "850 - 950 MHz", "rnode_firmware_heltec32v2.zip", "SX1276"],
-    0xC5: [420000000, 520000000, 21, "420 - 520 MHz", "rnode_firmware_heltec32v3.zip", "SX1262"],
+    0xC5: [420000000, 520000000, 21, "420 - 520 MHz", "rnode_firmware_heltec32v3.zip", "SX1268"],
     0xCA: [850000000, 950000000, 21, "850 - 950 MHz", "rnode_firmware_heltec32v3.zip", "SX1262"],
     0xE4: [420000000, 520000000, 17, "420 - 520 MHz", "rnode_firmware_tbeam.zip", "SX1278"],
     0xE9: [850000000, 950000000, 17, "850 - 950 MHz", "rnode_firmware_tbeam.zip", "SX1276"],

RNS/Utilities/rnstatus.py

@@ -135,7 +135,7 @@ 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):
+                  remote_timeout=RNS.Transport.PATH_REQUEST_TIMEOUT, must_exit=True, rns_instance=None):
     
     if remote:
         require_shared = False
@@ -143,11 +143,18 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
         require_shared = True
 
     try:
-        reticulum = RNS.Reticulum(configdir=configdir, loglevel=3+verbosity, require_shared_instance=require_shared)
+        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")
-        exit(1)
+        if must_exit:
+            exit(1)
+        else:
+            return
 
     link_count = None
     stats = None
@@ -175,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:
@@ -204,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):
@@ -375,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(2)
+        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)
@@ -483,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.6"
+__version__ = "0.8.8"

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: a6abb7db1df16737cc5d923272a50d50
+config: b85b0bd120dc25ae49dd85faeecc48dc
 tags: 645f666f9bcd5a90fca523b33c5a78b7

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,29 +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.
-
-OpenWRT
-^^^^^^^^^^^^^^^^^^^^^^^^^
-On OpenWRT systems with sufficient storage and memory, you can easily install
-Reticulum and related utilities using the `opkg` package manager and `pip`.
-
-.. code::
-
-   # Install dependencies
-   opkg install python3 python3-pip python3-cryptography python3-pyserial
-   
-   # Install Reticulum
-   pip install rns
+With these packages installed, ``pip`` will be able to build any missing dependencies
+on your system locally.
 
 
 Debian Bookworm
@@ -523,10 +518,145 @@ option, you can use the following command:
 
     pip install rns --break-system-packages
 
-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.
+.. 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
@@ -564,13 +694,45 @@ option, you can use the following command:
 
     pip install rns --break-system-packages
 
-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.
+.. 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``
@@ -585,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

@@ -162,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
@@ -238,8 +239,9 @@ can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
       device = tun0
       listen_port = 4343
 
-**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::
 
@@ -311,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::
 
@@ -334,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::
 
@@ -393,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
@@ -480,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
@@ -647,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]]
@@ -710,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

@@ -904,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

@@ -189,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.6 beta',
+    VERSION: '0.8.8 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.6 beta documentation</title>
+        <title>Code Examples - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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/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.6 beta documentation</title>
+        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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.6 beta documentation</title>
+    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/><title>Index - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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.6 beta documentation</title>
+        <title>Getting Started Fast - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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,27 +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>
-</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 easily install
-Reticulum and related utilities using the <cite>opkg</cite> package manager and <cite>pip</cite>.</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>
-</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="debian-bookworm">
 <h3>Debian Bookworm<a class="headerlink" href="#debian-bookworm" title="Permalink to this heading">#</a></h3>
@@ -642,10 +641,132 @@ 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>
-<p>Please note that the “break-system-packages” directive is a somewhat misleading choice
+<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>
@@ -676,14 +797,43 @@ 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>
-<p>Please note that the “break-system-packages” directive is a somewhat misleading choice
+<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>
@@ -697,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>
 
@@ -761,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>
@@ -775,15 +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="#openwrt">OpenWRT</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.6 beta documentation</title>
+        <title>Communications Hardware - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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.6 beta documentation</title>
+        <title>Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="#"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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,15 +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#openwrt">OpenWRT</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>
@@ -322,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>

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.6 beta documentation</title>
+        <title>Configuring Interfaces - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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">
@@ -353,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
@@ -418,8 +421,11 @@ can simply specify the Yggdrasil <code class="docutils literal notranslate"><spa
     <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4343</span>
 </pre></div>
 </div>
-<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">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>
@@ -478,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>
@@ -495,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>
 
@@ -548,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>
 
@@ -630,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>
 
@@ -784,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>
@@ -841,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>
 

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.6 beta documentation</title>
+        <title>Building Networks - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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.6 beta documentation</title>
+        <title>API Reference - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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">
@@ -1943,8 +1943,9 @@ Transport system of Reticulum.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
 <dd class="field-odd"><p><strong>handler</strong> – Must be an object with an <em>aspect_filter</em> attribute and a <em>received_announce(destination_hash, announced_identity, app_data)</em>
-callable. Can optionally have a <em>receive_path_responses</em> attribute set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, to also receive all path responses, in addition to live
-announces. See the <a class="reference internal" href="examples.html#example-announce"><span class="std std-ref">Announce Example</span></a> for more info.</p>
+or <em>received_announce(destination_hash, announced_identity, app_data, announce_packet_hash)</em> callable. Can optionally have a
+<em>receive_path_responses</em> attribute set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, to also receive all path responses, in addition to live announces. See
+the <a class="reference internal" href="examples.html#example-announce"><span class="std std-ref">Announce Example</span></a> for more info.</p>
 </dd>
 </dl>
 </dd></dl>

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.6 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.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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.6 beta documentation</title>
+        <title>Support Reticulum - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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.6 beta documentation</title>
+        <title>Understanding Reticulum - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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">
@@ -1099,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.6 beta documentation</title>
+        <title>Using Reticulum on Your System - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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.6 beta documentation</title>
+        <title>What is Reticulum? - Reticulum Network Stack 0.8.8 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.6 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.8.8 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.6 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.8.8 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/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,29 +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.
-
-OpenWRT
-^^^^^^^^^^^^^^^^^^^^^^^^^
-On OpenWRT systems with sufficient storage and memory, you can easily install
-Reticulum and related utilities using the `opkg` package manager and `pip`.
-
-.. code::
-
-   # Install dependencies
-   opkg install python3 python3-pip python3-cryptography python3-pyserial
-   
-   # Install Reticulum
-   pip install rns
+With these packages installed, ``pip`` will be able to build any missing dependencies
+on your system locally.
 
 
 Debian Bookworm
@@ -523,10 +518,145 @@ option, you can use the following command:
 
     pip install rns --break-system-packages
 
-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.
+.. 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
@@ -564,13 +694,45 @@ option, you can use the following command:
 
     pip install rns --break-system-packages
 
-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.
+.. 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``
@@ -585,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

@@ -162,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
@@ -238,8 +239,9 @@ can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
       device = tun0
       listen_port = 4343
 
-**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::
 
@@ -311,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::
 
@@ -334,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::
 
@@ -393,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
@@ -480,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
@@ -647,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]]
@@ -710,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

@@ -904,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

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