Prepare release

Added custom identity support to rncp utility

.github/workflows/build.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.x
+          python-version: 3.11
       - run: |
           python -m pip install -q cryptography
           make test
@@ -43,7 +43,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.x
+          python-version: 3.11
       - run: |
           python -m pip install -q build wheel setuptools
           make remove_symlinks
@@ -93,6 +93,6 @@ jobs:
 #            .artifacts/documentation/latex/reticulumnetworkstack.pdf
 #            .artifacts/documentation/epub/ReticulumNetworkStack.epub
           draft: true
-          generate_release_notes: true
+          generate_release_notes: false
           prerelease: ${{ contains(github.ref, '-') }}
           fail_on_unmatched_files: true

.gitignore

@@ -13,3 +13,4 @@ tests/rnsconfig/storage
 tests/rnsconfig/logfile*
 *.data
 *.result
+.buildinfo.bak

Changelog.md

@@ -1,3 +1,287 @@
+### 2026-04-28: RNS 1.2.0
+
+This release brings the ability to use Git natively over Reticulum networks, adds the `rnsh` program as part of the included utilities, and additionally includes several improvements and performance optimizations.
+
+**Changes**
+- Added Reticulum Git Repositories Node utility as part of included utility programs.
+- Added git remote helper to interact with git repositories over Reticulum.
+- Added the `rnsh` program to the included utilities.
+- Added LocalInterface client TX hold on client app sleep on Android.
+- Added AutoInterface filters for `rmnet` interfaces on Android.
+- Added inbound packet wait during transport core initialization.
+- Added the ability to set logfile destination before RNS initialization.
+- Added automatic active link teardown on instance shutdown.
+- Improved link teardown on SIGINT/SIGTERM.
+- Improved ratchet cleaning.
+
+**Release Hashes**
+```
+b58e97332241755ed32e309d46e09615a123490430ae85fcbdec9318c9e26154 rns-1.2.0-py3-none-any.whl
+9813a6c2236edba18af7d3a072a6226bc65ae384d23b1f41467cb3617d65fdae rnspure-1.2.0-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.2.0-py3-none-any.whl.rsg
+```
+
+### 2026-04-22: RNS 1.1.9
+
+This maintenance release fixes a critical security issue, that would allow an attacker to craft a BZ2 decompression bomb via Resource transfers or Buffer StreamDataMessage, causing an out-of-memory condition and crashing the receiving process via OOM killer.
+
+Big thanks to @defidude (github.com/ratspeak) for discovering and reporting this vulnerability!
+
+**Changes**
+- Fixed bz2 decompression bomb vulnerability in Resource transfer assembly and Buffer StreamDataMessage unpacking.
+
+**Release Hashes**
+```
+39a131aeb5d76fd73bfc67f68135f49ab0cf8628af154e04096a05c208ce77b6 rns-1.1.9-py3-none-any.whl
+aab7bfc8c65514c9bdf4c22f00d288faf6c9e1777fc002dbe3eb29c286e67128 rnspure-1.1.9-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.9-py3-none-any.whl.rsg
+```
+
+### 2026-04-21: RNS 1.1.8
+
+This maintenance release fixes a critical bug in path state management, that could result in significant path convergence degradation under certain conditions.
+
+**Changes**
+- Fixed path state potentially being applied before path table entry exists, causing worse paths to be selected.
+
+**Release Hashes**
+```
+9cf728e9e9a9fe113e4ac14e6b833f7ee65feedf8468e6ab94a261bf205f2632 rns-1.1.8-py3-none-any.whl
+407dc3975335e9eabaaddb7ed1dc75fc3a1b8d24a7207e740797440c2ad0b3e5 rnspure-1.1.8-py3-none-any.wh
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.8-py3-none-any.whl.rsg
+```
+
+### 2026-04-21: RNS 1.1.7
+
+**Changes**
+- Added periodic known destination data cleaning based on local relevance.
+- Improved resource transfer sequencing timing calculations and reliability.
+- Improved BackboneInterface error handling on EPOLL errors.
+- Ensured non-background data persist runs synchronously.
+
+**Release Hashes**
+```
+4d9702c5d9bb8a3c8b94766cb51cccad5afd78d615af9a6b146730347044e6f0 rns-1.1.7-py3-none-any.whl
+172dede7656b41b85e4319354ed04649b518e58c54586da7e443579c620a0a5b rnspure-1.1.7-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.7-py3-none-any.whl.rsg
+```
+
+### 2026-04-18: RNS 1.1.6
+
+**Changes**
+- Improved transport memory consumption.
+- Improved transport tunnel handling.
+- Improved gracious transport data persist handling.
+- Added ingress control bypass for pending path requests.
+- Added local destinations lookup map for better transport efficiency to local destinations.
+- Fixed disk I/O bound thread execution time starvation on cache management jobs.
+- Fixed invalid EPOLL modification error handler.
+- Fixed incorrect default IFAC size for autoconnected, discovered interfaces. Thanks @taprootmx!
+- Ensure loop-originating closures have variables captured at iteration-time. Thanks @taprootmx!
+
+**Release Hashes**
+```
+2ce4451668f8c464295cc269188c232e7805ddd618ec0135550a5e6809df5de0 rns-1.1.6-py3-none-any.whl
+ba3e541e69a2f4892177383c8ec4e7d172d298546317e08270928c0163865aa3 rnspure-1.1.6-py3-none-any.wh
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.6-py3-none-any.whl.rsg
+```
+
+### 2026-04-13: RNS 1.1.5
+
+**Changes**
+- Initial refactoring work for free-threaded transport I/O.
+- Improved interface discovery validation.
+- Fixed invalid ingress control burst activation and subsequent path resolution failure due to incorrect announce frequency calculation.
+- Fixed missing configuration entry generation for discovered I2P interfaces.
+- Fixed resource transfer cancellation failing on in-flight split resource transfers.
+- Fixed ingress control configuration not inheriting down to spawned interfaces on some interface types.
+
+**Release Hashes**
+```
+28f39ad97ef307a1e270b91ef19db07d8e1a7bbc8628c478303725894c64deff rns-1.1.5-py3-none-any.whl
+1a90db16d2cff4ad909b44baf9b4fd0177da2ed545cdb9cfb2c51423707b49e9 rnspure-1.1.5-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.5-py3-none-any.whl.rsg
+```
+
+#
+
+### 2026-03-12: RNS 1.1.4
+
+**Changes**
+- Fixed invalid application of IP/hostname validation for on non-relevant interfaces. Thanks @joakim!
+
+**Release Hashes**
+```
+b2a175abd64d1581dd058206832793dbf7053a304c819ff8bc143a79c49cb747 rns-1.1.4-py3-none-any.whl
+16c4ae6722bbd016e8db046e7bdd60eb24f9ec55966ec5723dc39301265d0186 rnspure-1.1.4-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.4-py3-none-any.whl.rsg
+```
+
+### 2026-01-17: RNS 1.1.3
+
+**Changes**
+- Improved discovered interface auto-connect handling
+- Improved interface discovery handling
+- Added `discovered_interfaces` API method
+- Fixed a potential race condition in request timeout handling
+- Fixed a regression in resource file transfers
+
+**Release Hashes**
+```
+1de9b46c8f24931fa41974664ddbf4251d3fdd069be4de03c64b42a7cf4f8fb4 rns-1.1.3-py3-none-any.whl
+eac8d223fcb6ce94e1bd3f04730d8542675caf4b22286e11988e9402ea9b69c0 rnspure-1.1.3-py3-none-any.whl
+```
+
+**Release Signatures**
+Release artifacts include `rsg` signature files that can be validated against the RNS release signing identity `<bc7291552be7a58f361522990465165c>` using `rnid`:
+
+```sh
+rnid -i bc7291552be7a58f361522990465165c -V rns-1.1.3-py3-none-any.whl.rsg
+```
+
+### 2026-01-04: RNS 1.1.0
+
+Enjoy.
+
+**Changes**
+- Added on-network global interface discovery. Hello world.
+- Added discovered interface auto-connection. Robotic.
+- Added external IP resolution for discovery-enabled interfaces. Snip-snip.
+- Added encrypted interface discovery announces. Welcome home.
+- Added bootstrap interface functionality. Decent.
+- Added blackhole handling and management. Thank the Chinese guy.
+- Added distributed blackhole list publishing and updating. Spammers go home.
+- Added foundational network identity implementation. All your base.
+- Added `await_path` method to API. Tick-tock.
+- Added reverse-unicast peer discovery packet mechanism to AutoInterface. Ping-pong.
+- Added custom identity support to `rncp`, thanks MikelCalvo!
+- Added monitor mode to `rnstatus`, thanks MikelCalvo!
+- Improved announce processing. Swoosh.
+- Updated documentation quite a bit. Looky.
+- Enabled per-peer ingress limiting on Weave and Auto interfaces. Hammertime.
+- Fixed **the** typo, yes it's the olny one I'm sure.
+- Fixed bugs. Squish.
+
+**Release Hashes**
+```
+180b8baec2ec7d21abe2cec25ff763e70b2129c012fb02fc23c2fd654f94c1f5 dist/rns-1.1.0-py3-none-any.whl
+d9e32caf66a9c53199e901d2c173e1de1bf50f1f0c9d5250e5d1b3b07bedcd7c dist/rnspure-1.1.0-py3-none-any.whl
+```
+
+### 2025-11-19: RNS 1.0.4
+
+This maintenance release adds improved handling for RNodes with a PA/LNA combo.
+
+**Changes**
+- Improved handling for RNodes with PA/LNA combo
+- Added interference detection stats to `rnstatus` output for RNode interfaces
+- Updated documentation
+
+**Release Hashes**
+```
+7a2b7893410833b42c0fa7f9a9e3369cebb085cdd26bd83f3031fa6c1051653c rns-1.0.4-py3-none-any.whl
+ee647e7b3b94abdf1fab618a861390531a4aacc93eecce12c9e97280195c0e2d rnspure-1.0.4-py3-none-any.whl
+```
+
+### 2025-11-19: RNS 1.0.3
+
+This release includes updates to RNode BLE reliability, and adds support for connecting RNodes to a host over WiFi and Ethernet.
+
+**Changes**
+- Added support for connecting RNode devices over WiFi and Ethernet
+- Added support for configuring RNode WiFi and IP settings to `rnodeconf`
+- Updated BLE connection read timeouts on Android, fixes intermittent BLE connection resets in areas with high 2.4GHz spectrum utilization
+- Added handling for edge case where RNode serial port was never opened due to failure on interface detach
+- Fixed broken links in documentation
+
+**Release Hashes**
+```
+6bafde4c838ad778bf6878967e84c798e34d6ca621b255f59a60f38cb04ac138 rns-1.0.3-py3-none-any.whl
+f277899f95c1189c6bf3beb40ac656c8b36dfd3d7e4cfb2bc3b4a1e6dc3484fa rnspure-1.0.3-py3-none-any.whl
+```
+
+### 2025-11-10: RNS 1.0.2
+
+This maintenance release adds support for high-power RNodes with a LoRa PA and/or LNA.
+
+**Changes**
+- Added support for RNodes with a PA and/or LNA
+- Added support for monitoring RNode CPU temperature via `rnodeconf`
+
+**Release Hashes**
+```
+723bcf0a839025060ff680c4202b09fa766b35093a4a08506bb85485b8a1f154 rns-1.0.2-py3-none-any.whl
+b02de8aeb1381ed2610f27f78799bab031367ed7bf500951fb8d5c2542d4a409 rnspure-1.0.2-py3-none-any.whl
+```
+
+### 2025-11-02: RNS 1.0.1
+
+This release brings a number of bugfixes, as well as stability and reliability improvements. It also adds support for using Weave devices as Reticulum interfaces, fixes long-standing Bluetooth Low Energy connection issues on Android, and includes several API and usability improvements.
+
+**Changes**
+- Added path response signalling to announce handler API
+- Added interface module for Weave devices
+- Added support for connecting to Weave devices over serial/USB on Android
+- Added support for allow files to `rnx`
+- Added detection and logging of multicast echoes never arriving on AutoInterface system devices.
+- Added Heltec v4 support to `rnodeconf`
+- Implemented handler for ensuring dynamic destination app data can be generated and sent even on first system-internal discovery announce
+- Updated documentation and manual
+- Improved `AutoInterface` peering timing
+- Fixed RNodeInterface Bluetooth Low Energy connection hangs on Android
+- Fixed RNodeInterface Bluetooth Low Energy MTU not being configured correctly on Android
+- Fixed command byte collision in RNodeInterface and RNodeMultiInterface
+- Fixed string formatting for Android log output
+- Updated output formatting for `rnid`
+
+**Release Hashes**
+```
+aa77b4c8e1b6899117666e1e55b05b3250416ab5fea2826254358ae320e8b3ed rns-1.0.1-py3-none-any.whl
+b3ddfa0b533631d9f1213043a0282952ae6e9f72c3072bbca053ac48e0483f7e rnspure-1.0.1-py3-none-any.whl
+```
+
 ### 2025-07-14: RNS 1.0.0
 
 We're out of beta. Thanks to **everyone** who helped make it this far.

Contributing.md

@@ -8,21 +8,28 @@ Apart from writing code, there are many ways in which you can contribute. Before
 
 First and foremost, there is one simple requirement for taking part in this community: While we primarily interact virtually, your actions matter and have real consequences. Therefore: **Act like a responsible, civilized person** - especially in the face of disputes and heated disagreements. Speak your mind here; discussions are welcome. Just do so in the spirit of being face-to-face with everyone else. Thank you.
 
+In order to keep the discussion forums and issue trackers navigable and useful, the following types of posts will be deleted without notice:
+
+- Spam.
+- Questions that have already been adequately answered elsewhere. Use the search function.
+- Low-effort posts or comments that contain no actual information or useful content. This is not a tea-house.
+- Post or comments solely containing personal opinions or beliefs without adding anything to the discussion. Facebook and X exists.
+- Content that simply waste the developer's / maintainer's time with completely obvious "ideas", "insights" or "recommendations". Yes, we have *at least* 8 neurons ourselves.
+- Posts that fail to understand that developing a highly complex software project with a very small amount of resources and people takes time. Imagining perfection on our behalf is useless.
+
+If you're new to the community and start out your engagement with any of the above transgressions, you will simply be banned without notice or explanation, and your post will be deleted.
+
+If you find this "harsh", "unfair" or "unwelcoming", go somewhere else. This is not social club, but a work environment for the people contributing to the project.
+
 ## Asking Questions
 
-If you want to ask a question, **do not open an issue**. The issue tracker is used by people *working on Reticulum* to track bugs, issues and improvements.
+If you want to ask a question, **do not open an issue**. The issue tracker is used by people *working on Reticulum* to track bugs, issues and improvements. Instead, ask away on the [discussions](https://github.com/markqvist/Reticulum/discussions).
 
-Instead, ask away on the [discussions](https://github.com/markqvist/Reticulum/discussions) or on the [Reticulum Matrix channel](https://matrix.to/#/#reticulum:matrix.org) at `#reticulum:matrix.org`
-
-## Providing Feedback & Ideas
-
-Likewise, feedback, ideas and feature requests are a very welcome way to contribute, and should also be posted on the [discussions](https://github.com/markqvist/Reticulum/discussions), or on the [Reticulum Matrix channel](https://matrix.to/#/#reticulum:matrix.org) at `#reticulum:matrix.org`.
-
-Please do not post feature requests or general ideas on the issue tracker, or in direct messages to the primary developers. You are much more likely to get a response and start a constructive discussion by posting your ideas in the public channels created for these purposes.
+Do not post feature requests or general ideas on the issue tracker, or in direct messages to the primary developers. You are much more likely to get a response and start a constructive discussion by posting your ideas in the public channels created for these purposes.
 
 ## Reporting Issues
 
-If you have found a bug or issue in this project, please report it using the [issue tracker](https://github.com/markqvist/Reticulum/issues). If at all possible, be sure to include details on how to reproduce the bug.
+If you have found a bug or issue in this project, please report it using the [issue tracker](https://github.com/markqvist/Reticulum/issues). Be sure to include details on how to reproduce the bug.
 
 Anything submitted to the issue tracker that does not follow these guidelines will be closed and removed without comments or explanation.
 
@@ -42,9 +49,9 @@ Even new ideas and proposals that have not been approved by a maintainer, or fal
 
 ## Generative AI Policy
 
-Contributions written using large language models (LLMs) or other generative 'AI' programs are prohibited. LLMs produce errors so frequently and in a way that is so unlike human error that issues will regularly remain undetected and slip through, even with stringent review. This is not a worthwhile tradeoff for Reticulum, especially considering the limited time maintainers have to correct these issues, and we ask that you refrain from using any such output in your contributions.
+Contributions written using large language models (LLMs) or other generative 'AI' programs are prohibited. LLMs produce errors so frequently and in a way that is so unlike human error that such issues are incredibly time-consuming to spot and fix. This is not a worthwhile tradeoff for Reticulum.
 
-This applies to all official Reticlulm projects and documentation as well as all submitted issues and discussion in official channels, except in cases where language translation and/or speech recogntion technologies are required for communication.  We also ask that you avoid using LLMs for troubleshooting, as results can be misleading, and instead request help in one of our [various communities](https://reticulum.network/start.html).
+This applies to all Reticulum-related projects and documentation, as well as all submitted issues and discussion in official channels, except in cases where language translation and/or speech recogntion technologies are required for communication.
 
 ## Contributor License Agreement
 

Examples/Resource.py

@@ -222,7 +222,7 @@ def link_established(link):
 
     # Inform the user that the server is
     # connected
-    RNS.log("Link established with server, hit enter to sand a resource, or type in \"quit\" to quit")
+    RNS.log("Link established with server, hit enter to send a resource, or type in \"quit\" to quit")
 
 # When a link is closed, we'll inform the
 # user, and exit the program

FUNDING.json

@@ -0,0 +1,7 @@
+{
+  "drips": {
+    "ethereum": {
+      "ownedBy": "0xae89F3B94fC4AD6563F0864a55F9a697a90261ff"
+    }
+  }
+}

LICENSE

@@ -1,6 +1,6 @@
 Reticulum License
 
-Copyright (c) 2016-2025 Mark Qvist
+Copyright (c) 2016-2026 Mark Qvist
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MIRROR.md

@@ -0,0 +1,33 @@
+This repository is a public mirror. All potential future development is happening elsewhere.
+
+I am stepping back from all public-facing interaction with this project. Reticulum has always been primarily my work, and continuing in the current public, internet-facing model is no longer sustainable.
+
+The software remains available for use as-is. Occasional updates may appear at unpredictable intervals, but there will be no support, no responses to issues, no discussions, and no community management in this or any other public venue. If it doesn't work for you, it doesn't work. That is the entire extent of available troubleshooting assistance I can offer you.
+
+If you've followed this project for a while, you already know what this means. You know who designed, wrote and tested this, and you know how many years of my life it took. You'll also know about both my particular challenges and strengths, and how I believe anything worth building needs to be built and  maintained with our own hands.
+
+Seven months ago, I said I needed to step back, that I was exhausted, and that I needed to recover. I believed a public resolve would be enough to effectuate that, but while striving to get just a few more useful features and protocols out, the unproductive requests and demands also ramped up, and I got pulled back into the same patterns and draining interactions that I'd explicitly said I couldn't sustain anymore.
+
+So here's what you might have already guessed: I'm done playing the game by rules I can't win at.
+
+Everything you need is right here, and by any sensible measure, it's done. Anyone who wants to invest the time, skill and persistence can build on it, or completely re-imagine it with different priorities. That was always the point.
+
+The people who actually contributed - you know who you are, and you know I mean it when I say: Thank you. All of you who've used this to build something real - that was the goal, and you did it without needing me to hold your hand.
+
+The rest of you: You have what you need. Use it or don't. I am not going to be the person who explains it to you anymore.
+
+This is not a temporary break. It's not "see you after some rest", but a recognition that the current model is fundamentally incompatible with my life, my health, and my reality.
+
+If you want to support continued work, you can do so at the donation links listed in this repository. But please understand, that this is not purchasing support or guaranteeing updates. It is support for work that happens on my timeline, according to my capacity, which at the moment is not what it was.
+
+If you want Reticulum to continue evolving, you have the power to make that happen. The protocol is public domain. The code is open source. Everything you need is right here. I've provided the tools, but building what comes next is not my responsibility anymore. It's yours.
+
+To the small group of people who has actually been here, and understood what this work was and what it cost - you already know where to find me if it actually matters.
+
+To everyone else: This is where we part ways. No hard feelings. It's just time.
+
+---
+
+असतो मा सद्गमय
+तमसो मा ज्योतिर्गमय
+मृत्योर्मा अमृतं गमय

Makefile

@@ -55,13 +55,24 @@ documentation:
 manual:
 	make -C docs latexpdf epub
 
+build_spkg: remove_symlinks build_sdist create_symlinks
+
 release: test remove_symlinks build_sdist build_wheel build_pure_wheel documentation manual create_symlinks
 
 debug: remove_symlinks build_wheel build_pure_wheel create_symlinks
 
-upload:
-	@echo Ready to publish release, hit enter to continue
+upload: upload-rns upload-rnspure
+
+upload-rns:
+	@echo Ready to publish rns release, hit enter to continue
 	@read VOID
 	@echo Uploading to PyPi...
-	twine upload dist/*
+	twine upload dist/rns-*.whl dist/rns-*.tar.gz
 	@echo Release published
+
+upload-rnspure:
+	@echo Ready to publish rnspure release, hit enter to continue
+	@read VOID
+	@echo Uploading to PyPi...
+	twine upload dist/rnspure-*.whl
+	@echo Release published

README.md

@@ -3,6 +3,10 @@ Reticulum Network Stack <img align="right" src="https://static.pepy.tech/persona
 
 <p align="center"><img width="200" src="https://raw.githubusercontent.com/markqvist/Reticulum/master/docs/source/graphics/rns_logo_512.png"></p>
 
+*This repository is [a public mirror](./MIRROR.md). All development is happening elsewhere.*
+
+To understand the foundational philosophy and goals of this system, read the [Zen of Reticulum](Zen%20of%20Reticulum.md).
+
 Reticulum is the cryptography-based networking stack for building local and wide-area
 networks with readily available hardware. It can operate even with very high latency
 and extremely low bandwidth. Reticulum allows you to build wide-area networks
@@ -74,22 +78,32 @@ For more info, see [reticulum.network](https://reticulum.network/) and [the FAQ
   - Low cost of keeping links open at only 0.44 bits per second
 - Reliable sequential delivery with Channel and Buffer mechanisms
 
-## Roadmap
-While Reticulum is already a fully featured and functional networking stack,
-many improvements and additions are actively being worked on, and planned for the future.
+## Reference Implementation
 
-To learn more about the direction and future of Reticulum, please see the [Development Roadmap](./Roadmap.md).
+The Python code in this repository is the Reference Implementation of Reticulum.
+The Reticulum Protocol is defined entirely and authoritatively by this reference
+implementation, and its associated manual. It is maintained by Mark Qvist,
+identified by the Reticulum Identity `<bc7291552be7a58f361522990465165c>`.
+
+Compatibility with the Reticulum Protocol is defined as having full interoperability,
+and sufficient functional parity with this reference implementation. Any specific protocol
+implementation that achieves this is Reticulum. Any that does not is not Reticulum.
+
+The reference implementation is licensed under the Reticulum License.
+
+The Reticulum Protocol was dedicated to the Public Domain in 2016.
 
 ## Examples of Reticulum Applications
 If you want to quickly get an idea of what Reticulum can do, take a look at the
-following resources.
+[Programs Using Reticulum](https://reticulum.network/manual/software.html)
+section of the manual, or the following resources:
 
-- You can use the [rnsh](https://github.com/acehoss/rnsh) program to establish remote shell sessions over Reticulum.
 - [LXMF](https://github.com/markqvist/lxmf) is a distributed, delay and disruption tolerant message transfer protocol built on Reticulum
 - The [LXST](https://github.com/markqvist/lxst) protocol and framework provides real-time audio and signals transport over Reticulum. It includes primitives and utilities for building voice-based applications and hardware devices, such as the `rnphone` program, that can be used to build hardware telephones.
 - For an off-grid, encrypted and resilient mesh communications platform, see [Nomad Network](https://github.com/markqvist/NomadNet)
 - The Android, Linux, macOS and Windows app [Sideband](https://github.com/markqvist/Sideband) has a graphical interface and many advanced features, such as file transfers, image and voice messages, real-time voice calls, a distributed telemetry system, mapping capabilities and full plugin extensibility.
-- [MeshChat](https://github.com/liamcottle/reticulum-meshchat) is a user-friendly LXMF client with a web-based interface, that also supports image and voice messages, as well as file transfers. It also includes a built-in page browser for browsing Nomad Network nodes.
+- [MeshChatX](https://git.quad4.io/RNS-Things/MeshChatX) is a full-featured LXMF client with many built-in tools and functionalities, that also supports image and voice messages, file transfers and voice calls. It also includes a built-in page browser for browsing Nomad Network nodes.
+- You can use the included [rnsh](https://reticulum.network/manual/using.html#the-rnsh-utility) program to establish remote shell sessions over Reticulum.
 
 ## Where can Reticulum be used?
 Over practically any medium that can support at least a half-duplex channel
@@ -170,8 +184,10 @@ section of the [Reticulum Manual](https://markqvist.github.io/Reticulum/manual/)
 - A diagnostics tool called `rnprobe` for checking connectivity to destinations
 - A simple file transfer program called `rncp` making it easy to transfer files between systems
 - The identity management and encryption utility `rnid` let's you manage Identities and encrypt/decrypt files
-- The remote command execution program `rnx` let's you run commands and
-  programs and retrieve output from remote systems
+- The `rnsh` program allows you to establish fully interactive shell session with remote systems
+- The remote command execution program `rnx` let's you run simple commands and programs and retrieve output from remote systems
+- The `rngit` program provides a full multi-repository Git node for serving repositories over Reticulum
+- The included `git-remote-rns` helper allows you to interact with Git repositories over Reticulum
 
 All tools, including `rnx` and `rncp`, work reliably and well even over very
 low-bandwidth links like LoRa or Packet Radio. For full-featured remote shells
@@ -206,7 +222,7 @@ provide a dynamic performance envelope from 250 bits per second, to 1 gigabit
 per second on normal hardware.
 
 Currently, the usable performance envelope is approximately 150 bits per second
-to 40 megabits per second, with physical mediums faster than that not being
+to 500 megabits per second, with physical mediums faster than that not being
 saturated. Performance beyond the current level is intended for future
 upgrades, but not highly prioritised at this point in time.
 
@@ -216,7 +232,7 @@ probably occur as real-world use is explored and understood. The API and wire-fo
 can be considered stable.
 
 ## Dependencies
-The installation of the default `rns` package requires the dependencies listed
+The installation of the default `rns` package requires only two external dependencies, listed
 below. Almost all systems and distributions have readily available packages for
 these dependencies, and when the `rns` package is installed with `pip`, they
 will be downloaded and installed as well.
@@ -244,53 +260,24 @@ that do not support [PyCA/cryptography](https://github.com/pyca/cryptography),
 it is important that you read and understand the [Cryptographic
 Primitives](#cryptographic-primitives) section of this document.
 
+## Bootstrapping Connectivity
+
+Reticulum is not a service you subscribe to, nor is it a single global network you "join".
+Reticulum provides functionality for discovering available public interfaces
+over the network itself, and the broader community has provided various directories
+of publicly available entrypoints to bootstrap connectivity.
+
+To learn how to establish initial connectivity over Reticulum, read the [Bootstrapping Connectivity](https://reticulum.network/manual/gettingstartedfast.html#bootstrapping-connectivity) section of the manual.
+
+If you already have a general idea of how this works, you can use community-run
+sites such as [directory.rns.recipes](https://directory.rns.recipes/) and [rmap.world](https://rmap.world)
+to find interface definitions for initial connectivity to the global distributed Reticulum backbone.
+
 ## Public Testnet
-If you just want to get started experimenting without building any physical
-networks, you are welcome to join the RNS Development Testnet.
-
-The testnet is just that, an informal network for testing and experimenting.
-It will be up most of the time, and anyone can join, but it also means that
-there's no guarantees for service availability.
-
-It probably goes without saying, but *don't use the testnet entry-points as 
-hardcoded or default interfaces in any applications you ship to users*. When
-shipping applications, the best practice is to provide your own default
-connectivity solutions, if needed and applicable, or in most cases, simply
-leave it up to the user which networks to connect to, and how.
-
-The testnet runs the very latest version of Reticulum (often even a short while
-before it is publicly released). Sometimes experimental versions of Reticulum
-might be deployed to nodes on the testnet, which means strange behaviour might
-occur. If none of that scares you, you can join the testnet via either TCP or
-I2P. Just add one of the following interfaces to your Reticulum configuration
-file:
-
-```
-# TCP/IP interface to the RNS Amsterdam Hub
-  [[RNS Testnet Amsterdam]]
-    type = TCPClientInterface
-    enabled = yes
-    target_host = amsterdam.connect.reticulum.network
-    target_port = 4965
-
-# TCP/IP interface to the BetweenTheBorders Hub (community-provided)
-  [[RNS Testnet BetweenTheBorders]]
-    type = TCPClientInterface
-    enabled = yes
-    target_host = reticulum.betweentheborders.com
-    target_port = 4242
-
-# Interface to Testnet I2P Hub
-  [[RNS Testnet I2P Hub]]
-    type = I2PInterface
-    enabled = yes
-    peers = g3br23bvx3lq5uddcsjii74xgmn6y5q325ovrkq2zw2wbzbqgbuq.b32.i2p
-```
-
-The testnet also contains a number of [Nomad Network](https://github.com/markqvist/nomadnet) nodes, and LXMF propagation nodes.
+***Important!** Historically, a developer-targeted testnet was made available by the Reticulum project itself. As the amount of global Reticulum nodes and entrypoints have grown to a substantial quantity, this public testnet, including the Amsterdam Testnet entrypoint, has now been decommissioned. If your still have instances that relied on this entrypoint for connectivity, transition to using the distributed backbone instead. Reticulum now includes a full on-network interface discovery and connectivity bootstrapping system. Read the [Bootstrapping Connectivity](https://reticulum.network/manual/gettingstartedfast.html#bootstrapping-connectivity) section of the manual for pointers.*
 
 ## Support Reticulum
-You can help support the continued development of open, free and private communications systems by donating via one of the following channels:
+For this to be possible, I need your help. Please support the continued development of open, free and private communications systems by donating via one of the following channels:
 
 - Monero:
   ```
@@ -298,11 +285,11 @@ You can help support the continued development of open, free and private communi
   ```
 - Bitcoin
   ```
-  bc1p4a6axuvl7n9hpapfj8sv5reqj8kz6uxa67d5en70vzrttj0fmcusgxsfk5
+  bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6
   ```
 - Ethereum
   ```
-  0xae89F3B94fC4AD6563F0864a55F9a697a90261ff
+  0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E
   ```
 - Liberapay: https://liberapay.com/Reticulum/
 
@@ -393,4 +380,5 @@ projects:
 - [Configobj](https://github.com/DiffSK/configobj) by Michael Foord, Nicola Larosa, Rob Dennis & Eli Courtwright, *BSD License*
 - [ifaddr](https://github.com/pydron/ifaddr) by Stefan C. Mueller, *MIT License*
 - [Umsgpack.py](https://github.com/vsergeev/u-msgpack-python) by [Ivan A. Sergeev](https://github.com/vsergeev)
+- [rnsh](https://github.com/acehoss/rnsh) by [Aaron Heise](https://github.com/acehoss)
 - [Python](https://www.python.org)

RNS/Buffer.py

@@ -92,7 +92,9 @@ class StreamDataMessage(MessageBase):
         self.data = raw[2:]
 
         if self.compressed:
-            self.data = bz2.decompress(self.data)
+            decompressor = bz2.BZ2Decompressor()
+            self.data = decompressor.decompress(self.data, max_length=RawChannelWriter.MAX_CHUNK_LEN)
+            if not decompressor.eof: raise IOError("Decompressed buffer chunk exceeds maximum legitimate size")
 
 
 class RawChannelReader(RawIOBase, AbstractContextManager):

RNS/Destination.py

@@ -295,33 +295,26 @@ class Destination:
                         app_data = returned_app_data
             
             signed_data = self.hash+self.identity.get_public_key()+self.name_hash+random_hash+ratchet
-            if app_data != None:
-                signed_data += app_data
+            if app_data != None: signed_data += app_data
 
             signature = self.identity.sign(signed_data)
             announce_data = self.identity.get_public_key()+self.name_hash+random_hash+ratchet+signature
 
-            if app_data != None:
-                announce_data += app_data
+            if app_data != None: announce_data += app_data
 
             self.path_responses[tag] = [time.time(), announce_data]
 
-        if path_response:
-            announce_context = RNS.Packet.PATH_RESPONSE
-        else:
-            announce_context = RNS.Packet.NONE
+        if path_response: announce_context = RNS.Packet.PATH_RESPONSE
+        else:             announce_context = RNS.Packet.NONE
 
-        if ratchet:
-            context_flag = RNS.Packet.FLAG_SET
-        else:
-            context_flag = RNS.Packet.FLAG_UNSET
+        if ratchet: context_flag = RNS.Packet.FLAG_SET
+        else:       context_flag = RNS.Packet.FLAG_UNSET
 
         announce_packet = RNS.Packet(self, announce_data, RNS.Packet.ANNOUNCE, context = announce_context,
                                      attached_interface = attached_interface, context_flag=context_flag)
-        if send:
-            announce_packet.send()
-        else:
-            return announce_packet
+        
+        if send: announce_packet.send()
+        else:    return announce_packet
 
     def accepts_links(self, accepts = None):
         """
@@ -330,13 +323,10 @@ class Destination:
         :param accepts: If ``True`` or ``False``, this method sets whether the destination accepts incoming link requests. If not provided or ``None``, the method returns whether the destination currently accepts link requests.
         :returns: ``True`` or ``False`` depending on whether the destination accepts incoming link requests, if the *accepts* parameter is not provided or ``None``.
         """
-        if accepts == None:
-            return self.accept_link_requests
+        if accepts == None: return self.accept_link_requests
 
-        if accepts:
-            self.accept_link_requests = True
-        else:
-            self.accept_link_requests = False
+        if accepts: self.accept_link_requests = True
+        else:       self.accept_link_requests = False
 
     def set_link_established_callback(self, callback):
         """
@@ -421,8 +411,7 @@ class Destination:
             else:
                 if packet.packet_type == RNS.Packet.DATA:
                     if self.callbacks.packet != None:
-                        try:
-                            self.callbacks.packet(plaintext, packet)
+                        try: self.callbacks.packet(plaintext, packet)
                         except Exception as e:
                             RNS.log("Error while executing receive callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
@@ -462,6 +451,10 @@ class Destination:
                     self.ratchets = None
                     self.ratchets_path = None
                     RNS.trace_exception(e)
+                    RNS.log(f"The ratchet file located at {ratchets_path} could not be loaded. This could indicate that the ratchet file has become corrupt.", RNS.LOG_CRITICAL)
+                    RNS.log(f"You can attempt to manually recover the ratchet file, or simply remove it to have Reticulum recreate it on the next use.", RNS.LOG_CRITICAL)
+                    RNS.log(f"If re-initialize this ratchet file, make sure to send an announce for the relevant destination as soon as possible,", RNS.LOG_CRITICAL)
+                    RNS.log(f"so that the new ratchet information is synchronized to the network.", RNS.LOG_CRITICAL)
                     raise OSError("Could not read ratchet file contents for "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
         else:

RNS/Discovery.py

@@ -0,0 +1,742 @@
+import os
+import re
+import RNS
+import time
+import random
+import threading
+import ipaddress
+import subprocess
+from .vendor import umsgpack as msgpack
+
+NAME            = 0xFF
+TRANSPORT_ID    = 0xFE
+INTERFACE_TYPE  = 0x00
+TRANSPORT       = 0x01
+REACHABLE_ON    = 0x02
+LATITUDE        = 0x03
+LONGITUDE       = 0x04
+HEIGHT          = 0x05
+PORT            = 0x06
+IFAC_NETNAME    = 0x07
+IFAC_NETKEY     = 0x08
+FREQUENCY       = 0x09
+BANDWIDTH       = 0x0A
+SPREADINGFACTOR = 0x0B
+CODINGRATE      = 0x0C
+MODULATION      = 0x0D
+CHANNEL         = 0x0E
+
+APP_NAME = "rnstransport"
+
+class InterfaceAnnouncer():
+    JOB_INTERVAL = 60
+    DEFAULT_STAMP_VALUE = 14
+    WORKBLOCK_EXPAND_ROUNDS = 20
+
+    DISCOVERABLE_INTERFACE_TYPES = ["BackboneInterface", "TCPServerInterface", "TCPClientInterface",
+                                    "RNodeInterface", "WeaveInterface", "I2PInterface", "KISSInterface"]
+
+    def __init__(self, owner):
+        import importlib.util
+        if importlib.util.find_spec('LXMF') != None: from LXMF import LXStamper
+        else:
+            RNS.log("Using on-network interface discovery requires the LXMF module to be installed.", RNS.LOG_CRITICAL)
+            RNS.log("You can install it with the command: pip install lxmf", RNS.LOG_CRITICAL)
+            RNS.panic()
+
+        self.owner        = owner
+        self.should_run   = False
+        self.job_interval = self.JOB_INTERVAL
+        self.stamper      = LXStamper
+        self.stamp_cache  = {}
+
+        if self.owner.has_network_identity(): identity = self.owner.network_identity
+        else:                                 identity = self.owner.identity
+
+        self.discovery_destination = RNS.Destination(identity, RNS.Destination.IN, RNS.Destination.SINGLE,
+                                                     APP_NAME, "discovery", "interface")
+
+    def start(self):
+        if not self.should_run:
+            self.should_run = True
+            threading.Thread(target=self.job, daemon=True).start()
+
+    def stop(self): self.should_run = False
+
+    def job(self):
+        while self.should_run:
+            time.sleep(self.job_interval)
+            try:
+                now = time.time()
+                due_interfaces = [i for i in self.owner.interfaces if i.supports_discovery and i.discoverable and now > (i.last_discovery_announce+i.discovery_announce_interval)]
+                due_interfaces.sort(key=lambda i: now-i.last_discovery_announce, reverse=True)
+
+                if len(due_interfaces) > 0:
+                    selected_interface = due_interfaces[0]
+                    selected_interface.last_discovery_announce = time.time()
+                    RNS.log(f"Preparing interface discovery announce for {selected_interface.name}", RNS.LOG_DEBUG)
+                    app_data = self.get_interface_announce_data(selected_interface)
+                    if not app_data: RNS.log(f"Could not generate interface discovery announce data for {selected_interface.name}", RNS.LOG_ERROR)
+                    else:
+                        RNS.log(f"Sending interface discovery announce for {selected_interface.name} with {len(app_data)}B payload", RNS.LOG_DEBUG)
+                        self.discovery_destination.announce(app_data=app_data)
+
+            except Exception as e:
+                RNS.log(f"Error while preparing interface discovery announces: {e}", RNS.LOG_ERROR)
+                RNS.trace_exception(e)
+
+    def sanitize(self, in_str):
+        sanitized = in_str.replace("\n", "")
+        sanitized = sanitized.replace("\r", "")
+        sanitized = sanitized.strip()
+        return sanitized
+
+    def get_interface_announce_data(self, interface):
+        interface_type = type(interface).__name__
+        stamp_value    = interface.discovery_stamp_value if interface.discovery_stamp_value else self.DEFAULT_STAMP_VALUE
+
+        if not interface_type in self.DISCOVERABLE_INTERFACE_TYPES: return None
+        else:
+            flags = 0x00
+            info  = {INTERFACE_TYPE: interface_type,
+                     TRANSPORT:      RNS.Reticulum.transport_enabled(),
+                     TRANSPORT_ID:   RNS.Transport.identity.hash,
+                     NAME:           self.sanitize(interface.discovery_name),
+                     LATITUDE:       interface.discovery_latitude,
+                     LONGITUDE:      interface.discovery_longitude,
+                     HEIGHT:         interface.discovery_height}
+
+            if interface_type == "TCPClientInterface" and not interface.kiss_framing:
+                RNS.log(f"Invalid interface discovery configuration for {interface}, aborting discovery announce", RNS.LOG_ERROR)
+                return None
+
+            if interface_type in ["BackboneInterface", "TCPServerInterface"]:
+                reachable_on = self.sanitize(interface.reachable_on)
+
+                if not RNS.vendor.platformutils.is_windows():
+                    try:
+                        exec_path = os.path.expanduser(reachable_on)
+                        if os.path.isfile(exec_path) and os.access(exec_path, os.X_OK):
+                            RNS.log(f"Evaluating reachable_on from executable at {exec_path}", RNS.LOG_DEBUG)
+                            exec_result = subprocess.run([exec_path], stdout=subprocess.PIPE)
+                            exec_stdout = exec_result.stdout.decode("utf-8")
+                            if exec_result.returncode != 0: raise ValueError("Non-zero exit code from subprocess")
+                            reachable_on = self.sanitize(exec_stdout)
+                            if not (is_ip_address(reachable_on) or is_hostname(reachable_on)):
+                                raise ValueError(f"Valid IP address or hostname was not found in external script output \"{reachable_on}\"")
+
+                    except Exception as e:
+                        RNS.log(f"Error while getting reachable_on from executable at {interface.reachable_on}: {e}", RNS.LOG_ERROR)
+                        RNS.log(f"Aborting discovery announce", RNS.LOG_ERROR)
+                        return None
+
+                if not (is_ip_address(reachable_on) or is_hostname(reachable_on)):
+                    RNS.log(f"The configured reachable_on parameter \"{reachable_on}\" for {interface} is not a valid IP address or hostname", RNS.LOG_ERROR)
+                    RNS.log(f"Aborting discovery announce", RNS.LOG_ERROR)
+                    return None
+
+                info[REACHABLE_ON]    = reachable_on
+                info[PORT]            = interface.bind_port
+
+            if interface_type == "I2PInterface" and interface.connectable and interface.b32:
+                info[REACHABLE_ON]    = interface.b32
+
+            if interface_type == "RNodeInterface":
+                info[FREQUENCY]       = interface.frequency
+                info[BANDWIDTH]       = interface.bandwidth
+                info[SPREADINGFACTOR] = interface.sf
+                info[CODINGRATE]      = interface.cr
+
+            if interface_type == "WeaveInterface":
+                info[FREQUENCY]       = interface.discovery_frequency
+                info[BANDWIDTH]       = interface.discovery_bandwidth
+                info[CHANNEL]         = interface.discovery_channel
+                info[MODULATION]      = interface.discovery_modulation
+
+            if interface_type == "KISSInterface" or (interface_type == "TCPClientInterface" and interface.kiss_framing):
+                info[INTERFACE_TYPE]  = "KISSInterface"
+                info[FREQUENCY]       = interface.discovery_frequency
+                info[BANDWIDTH]       = interface.discovery_bandwidth
+                info[MODULATION]      = self.sanitize(interface.discovery_modulation)
+
+            if interface.discovery_publish_ifac == True:
+                info[IFAC_NETNAME]    = self.sanitize(interface.ifac_netname)
+                info[IFAC_NETKEY]     = self.sanitize(interface.ifac_netkey)
+
+            packed    = msgpack.packb(info)
+            infohash  = RNS.Identity.full_hash(packed)
+
+            if infohash in self.stamp_cache: stamp = self.stamp_cache[infohash]
+            else: stamp, v = self.stamper.generate_stamp(infohash, stamp_cost=stamp_value, expand_rounds=self.WORKBLOCK_EXPAND_ROUNDS)
+            if not stamp: return None
+            else: self.stamp_cache[infohash] = stamp
+
+            if interface.discovery_encrypt:
+                flags |= InterfaceAnnounceHandler.FLAG_ENCRYPTED
+                if not self.owner.has_network_identity():
+                    RNS.log(f"Discovery encryption requested for {interface}, but no network identity configured. Aborting discovery announce.", RNS.LOG_ERROR)
+                    return None
+                
+                else: payload = self.owner.network_identity.encrypt(packed+stamp)
+                    
+            else: payload = packed+stamp
+
+            return bytes([flags])+payload
+
+class InterfaceAnnounceHandler:
+    FLAG_SIGNED       = 0b00000001
+    FLAG_ENCRYPTED    = 0b00000010
+
+    def __init__(self, required_value=InterfaceAnnouncer.DEFAULT_STAMP_VALUE, callback=None):
+        import importlib.util
+        if importlib.util.find_spec('LXMF') != None: from LXMF import LXStamper
+        else:
+            RNS.log("Using on-network interface discovery requires the LXMF module to be installed.", RNS.LOG_CRITICAL)
+            RNS.log("You can install it with the command: pip install lxmf", RNS.LOG_CRITICAL)
+            RNS.panic()
+
+        self.aspect_filter  = APP_NAME+".discovery.interface"
+        self.required_value = required_value
+        self.callback       = callback
+        self.stamper        = LXStamper
+
+    def received_announce(self, destination_hash, announced_identity, app_data):
+        try:
+            discovery_sources = RNS.Reticulum.interface_discovery_sources()
+            if discovery_sources and not announced_identity.hash in discovery_sources:
+                RNS.log(f"Interface discovered from non-authorized network identity {RNS.prettyhexrep(announced_identity.hash)}, ignoring", RNS.LOG_DEBUG)
+                return
+
+            if app_data and len(app_data) > self.stamper.STAMP_SIZE+1:
+                flags     = app_data[0]
+                app_data  = app_data[1:]
+                signed    = flags & self.FLAG_SIGNED
+                encrypted = flags & self.FLAG_ENCRYPTED
+
+                if encrypted:
+                    if not RNS.Transport.has_network_identity(): return
+                    app_data = RNS.Transport.network_identity.decrypt(app_data)
+                    if not app_data: return
+
+                stamp     = app_data[-self.stamper.STAMP_SIZE:]
+                packed    = app_data[:-self.stamper.STAMP_SIZE]
+                infohash  = RNS.Identity.full_hash(packed)
+                workblock = self.stamper.stamp_workblock(infohash, expand_rounds=InterfaceAnnouncer.WORKBLOCK_EXPAND_ROUNDS)
+                value     = self.stamper.stamp_value(workblock, stamp)
+                valid     = self.stamper.stamp_valid(stamp, self.required_value, workblock)
+
+                if not valid:
+                    RNS.log(f"Ignored discovered interface with invalid stamp", RNS.LOG_DEBUG)
+                    return
+
+                if value < self.required_value: RNS.log(f"Ignored discovered interface with stamp value {value}", RNS.LOG_DEBUG)
+                else:
+                    info     = None
+                    unpacked = msgpack.unpackb(packed)
+                    if INTERFACE_TYPE in unpacked:
+                        interface_type        = unpacked[INTERFACE_TYPE]
+                        info = {"type":         interface_type,
+                                "transport":    unpacked[TRANSPORT],
+                                "name":         unpacked[NAME] or f"Discovered {interface_type}",
+                                "received":     time.time(),
+                                "stamp":        stamp,
+                                "value":        value,
+                                "transport_id": RNS.hexrep(unpacked[TRANSPORT_ID], delimit=False),
+                                "network_id":   RNS.hexrep(announced_identity.hash, delimit=False),
+                                "hops":         RNS.Transport.hops_to(destination_hash),
+                                "latitude":     unpacked[LATITUDE],
+                                "longitude":    unpacked[LONGITUDE],
+                                "height":       unpacked[HEIGHT]}
+
+                        if REACHABLE_ON in unpacked:
+                            if not (is_ip_address(unpacked[REACHABLE_ON]) or is_hostname(unpacked[REACHABLE_ON])):
+                                raise ValueError("Invalid data in reachable_on field of announce")
+
+                        if IFAC_NETNAME in unpacked: info["ifac_netname"] = unpacked[IFAC_NETNAME]
+                        if IFAC_NETKEY  in unpacked: info["ifac_netkey"]  = unpacked[IFAC_NETKEY]
+
+                        if interface_type in ["BackboneInterface", "TCPServerInterface"]:
+                            backbone_support     = not RNS.vendor.platformutils.is_windows()
+                            info["reachable_on"] = unpacked[REACHABLE_ON]
+                            info["port"]         = unpacked[PORT]
+                            connection_interface = "BackboneInterface" if backbone_support else "TCPClientInterface"
+                            remote_str           = "remote" if backbone_support else "target_host"
+                            cfg_name             = info["name"]
+                            cfg_remote           = info["reachable_on"]
+                            cfg_port             = info["port"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = {connection_interface}\n  enabled = yes\n  {remote_str} = {cfg_remote}\n  target_port = {cfg_port}{cfg_identity_str}{cfg_netname_str}{cfg_netkey_str}"
+
+                        if interface_type == "I2PInterface":
+                            info["reachable_on"] = unpacked[REACHABLE_ON]
+                            cfg_name             = info["name"]
+                            cfg_remote           = info["reachable_on"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = I2PInterface\n  enabled = yes\n  peers = {cfg_remote}{cfg_identity_str}{cfg_netname_str}{cfg_netkey_str}"
+
+                        if interface_type == "RNodeInterface":
+                            info["frequency"]    = unpacked[FREQUENCY]
+                            info["bandwidth"]    = unpacked[BANDWIDTH]
+                            info["sf"]           = unpacked[SPREADINGFACTOR]
+                            info["cr"]           = unpacked[CODINGRATE]
+                            cfg_name             = info["name"]
+                            cfg_frequency        = info["frequency"]
+                            cfg_bandwidth        = info["bandwidth"]
+                            cfg_sf               = info["sf"]
+                            cfg_cr               = info["cr"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = RNodeInterface\n  enabled = yes\n  port = \n  frequency = {cfg_frequency}\n  bandwidth = {cfg_bandwidth}\n  spreadingfactor = {cfg_sf}\n  codingrate = {cfg_cr}\n  txpower = {cfg_netname_str}{cfg_netkey_str}"
+
+                        if interface_type == "WeaveInterface":
+                            info["frequency"]    = unpacked[FREQUENCY]
+                            info["bandwidth"]    = unpacked[BANDWIDTH]
+                            info["channel"]      = unpacked[CHANNEL]
+                            info["modulation"]   = unpacked[MODULATION]
+                            cfg_name             = info["name"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = WeaveInterface\n  enabled = yes\n  port = {cfg_netname_str}{cfg_netkey_str}"
+
+                        if interface_type == "KISSInterface":
+                            info["frequency"]    = unpacked[FREQUENCY]
+                            info["bandwidth"]    = unpacked[BANDWIDTH]
+                            info["modulation"]   = unpacked[MODULATION]
+                            cfg_name             = info["name"]
+                            cfg_frequency        = info["frequency"]
+                            cfg_bandwidth        = info["bandwidth"]
+                            cfg_modulation       = info["modulation"]
+                            cfg_identity         = info["transport_id"]
+                            cfg_netname          = info["ifac_netname"] if "ifac_netname" in info else None
+                            cfg_netkey           = info["ifac_netkey"] if "ifac_netkey" in info else None
+                            cfg_netname_str      = f"\n  network_name = {cfg_netname}" if cfg_netname else ""
+                            cfg_netkey_str       = f"\n  passphrase = {cfg_netkey}" if cfg_netkey else ""
+                            cfg_identity_str     = f"\n  transport_identity = {cfg_identity}"
+                            info["config_entry"] = f"[[{cfg_name}]]\n  type = KISSInterface\n  enabled = yes\n  port = \n  # Frequency: {cfg_frequency}\n  # Bandwidth: {cfg_bandwidth}\n  # Modulation: {cfg_modulation}{cfg_identity_str}{cfg_netname_str}{cfg_netkey_str}"
+
+                        discovery_hash_material = info["transport_id"]+info["name"]
+                        info["discovery_hash"] = RNS.Identity.full_hash(discovery_hash_material.encode("utf-8"))
+
+                    if self.callback and callable(self.callback): self.callback(info)
+
+        except Exception as e:
+            RNS.log(f"An error occurred while trying to decode discovered interface. The contained exception was: {e}", RNS.LOG_DEBUG)
+
+class InterfaceDiscovery():
+    THRESHOLD_UNKNOWN  = 24*60*60
+    THRESHOLD_STALE    = 3*24*60*60
+    THRESHOLD_REMOVE   = 7*24*60*60
+
+    MONITOR_INTERVAL   = 5
+    DETACH_THRESHOLD   = 12
+
+    STATUS_STALE       = 0
+    STATUS_UNKNOWN     = 100
+    STATUS_AVAILABLE   = 1000
+    STATUS_CODE_MAP    = {"available": STATUS_AVAILABLE, "unknown": STATUS_UNKNOWN, "stale": STATUS_STALE}
+    AUTOCONNECT_TYPES  = ["BackboneInterface", "TCPServerInterface"]
+    DISCOVERABLE_TYPES = ["BackboneInterface", "TCPServerInterface", "I2PInterface", "RNodeInterface", "WeaveInterface", "KISSInterface"]
+
+    def __init__(self, required_value=InterfaceAnnouncer.DEFAULT_STAMP_VALUE, callback=None, discover_interfaces=True):
+        if not required_value: required_value = InterfaceAnnouncer.DEFAULT_STAMP_VALUE
+
+        self.required_value          = required_value
+        self.discovery_callback      = callback
+        self.rns_instance            = RNS.Reticulum.get_instance()
+        self.monitored_interfaces    = []
+        self.monitoring_autoconnects = False
+        self.monitor_interval        = self.MONITOR_INTERVAL
+        self.detach_threshold        = self.DETACH_THRESHOLD
+        self.initial_autoconnect_ran = False
+
+        if not self.rns_instance: raise SystemError("Attempt to start interface discovery listener without an active RNS instance")
+        self.storagepath = os.path.join(RNS.Reticulum.storagepath, "discovery", "interfaces")
+        if not os.path.isdir(self.storagepath): os.makedirs(self.storagepath)
+        
+        if discover_interfaces:
+            self.handler = InterfaceAnnounceHandler(callback=self.interface_discovered, required_value=self.required_value)
+            RNS.Transport.register_announce_handler(self.handler)
+            threading.Thread(target=self.connect_discovered, daemon=True).start()
+
+    def list_discovered_interfaces(self, only_available=False, only_transport=False):
+        now = time.time()
+        discovered_interfaces = []
+        discovery_sources = RNS.Reticulum.interface_discovery_sources()
+        for filename in os.listdir(self.storagepath):
+            try:
+                filepath = os.path.join(self.storagepath, filename)
+                with open(filepath, "rb") as f: info = msgpack.unpackb(f.read())
+                should_remove = False
+                heard_delta = now-info["last_heard"]
+                
+                if heard_delta > self.THRESHOLD_REMOVE: should_remove = True
+                elif discovery_sources and not "network_id" in info: should_remove = True
+                elif discovery_sources and not bytes.fromhex(info["network_id"]) in discovery_sources: should_remove = True
+                elif not "type" in info or ("type" in info and not info["type"] in self.DISCOVERABLE_TYPES): should_remove = True
+                elif "reachable_on" in info:
+                    if not (is_ip_address(info["reachable_on"]) or is_hostname(info["reachable_on"])): should_remove = True
+
+                if should_remove:
+                    os.unlink(filepath)
+                    continue
+                
+                else:
+                    if   heard_delta > self.THRESHOLD_STALE:   info["status"] = "stale"
+                    elif heard_delta > self.THRESHOLD_UNKNOWN: info["status"] = "unknown"
+                    else:                                      info["status"] = "available"
+
+                    info["status_code"] = self.STATUS_CODE_MAP[info["status"]]
+                    if not only_available and not only_transport: discovered_interfaces.append(info)
+                    else:
+                        should_append = True
+                        status = info["status"]
+                        transport = info["transport"]
+                        if only_available and status != "available": should_append = False
+                        if only_transport and not transport:         should_append = False
+                        if should_append: discovered_interfaces.append(info)
+
+            except Exception as e:
+                RNS.log(f"Error while loading discovered interface data: {e}", RNS.LOG_ERROR)
+                RNS.log(f"The interface data file {os.path.join(self.storagepath, filename)} may be corrupt", RNS.LOG_ERROR)
+                RNS.trace_exception(e)
+
+        discovered_interfaces.sort(key=lambda info: (info["status_code"], info["value"], info["last_heard"]), reverse=True)
+        return discovered_interfaces
+
+    def interface_discovered(self, info):
+        try:
+            name = info["name"]
+            value = info["value"]
+            interface_type = info["type"]
+            discovery_hash = info["discovery_hash"]
+            discovered_type = info["type"]
+            if not discovered_type in self.DISCOVERABLE_TYPES: return
+            hops = info["hops"]; ms = "" if hops == 1 else "s"
+            filename = RNS.hexrep(discovery_hash, delimit=False)
+            filepath = os.path.join(self.storagepath, filename)
+            RNS.log(f"Discovered {interface_type} {hops} hop{ms} away with stamp value {value}: {name}", RNS.LOG_DEBUG)
+            if not os.path.isfile(filepath):
+                try:
+                    with open(filepath, "wb") as f:
+                        info["discovered"]  = info["received"]
+                        info["last_heard"]  = info["received"]
+                        info["heard_count"] = 0
+                        f.write(msgpack.packb(info))
+                
+                except Exception as e:
+                    RNS.log(f"Error while persisting discovered interface data: {e}", RNS.LOG_ERROR)
+                    RNS.trace_exception(e)
+                    return
+
+            else:
+                discovered  = None
+                heard_count = None
+                try:
+                    with open(filepath, "rb") as f:
+                        last_info   = msgpack.unpackb(f.read())
+                        discovered  = last_info["discovered"]
+                        heard_count = last_info["heard_count"]
+
+                    if discovered  == None: discovered  = info["discovered"]
+                    if heard_count == None: heard_count = 0
+
+                    with open(filepath, "wb") as f:
+                        info["discovered"] = discovered
+                        info["last_heard"] = info["received"]
+                        info["heard_count"] = heard_count+1
+                        f.write(msgpack.packb(info))
+
+                except Exception as e:
+                    RNS.log(f"Error while persisting discovered interface data: {e}", RNS.LOG_ERROR)
+                    RNS.trace_exception(e)
+                    return
+
+        except Exception as e:
+            RNS.log(f"Error processing discovered interface data: {e}", RNS.LOG_ERROR)
+            RNS.trace_exception(e)
+            return
+
+        self.autoconnect(info)
+
+        try:
+            if self.discovery_callback and callable(self.discovery_callback): self.discovery_callback(info)
+        except Exception as e: RNS.log(f"Error while processing external interface discovery callback: {e}", RNS.LOG_ERROR)
+
+    def monitor_interface(self, interface):
+        if not interface in self.monitored_interfaces:
+            self.monitored_interfaces.append(interface)
+
+        if not self.monitoring_autoconnects:
+            self.monitoring_autoconnects = True
+            threading.Thread(target=self.__monitor_job, daemon=True).start()
+
+    def __monitor_job(self):
+        while self.monitoring_autoconnects:
+            time.sleep(self.monitor_interval)
+            detached_interfaces = []
+            online_interfaces = 0
+            autoconnected_interfaces = self.autoconnect_count()
+            for interface in self.monitored_interfaces:
+                try:
+                    if interface.online:
+                        online_interfaces += 1
+                        if hasattr(interface, "autoconnect_down") and interface.autoconnect_down != None:
+                            RNS.log(f"Auto-discovered interface {interface} reconnected")
+                            interface.autoconnect_down = None
+
+                    else:
+                        if not hasattr(interface, "autoconnect_down") or interface.autoconnect_down == None:
+                            RNS.log(f"Auto-discovered interface {interface} disconnected", RNS.LOG_DEBUG)
+                            interface.autoconnect_down = time.time()
+
+                        else:
+                            down_for = time.time()-interface.autoconnect_down
+                            if down_for >= self.detach_threshold:
+                                RNS.log(f"Auto-discovered interface {interface} has been down for {RNS.prettytime(down_for)}, detaching", RNS.LOG_DEBUG)
+                                detached_interfaces.append(interface)
+
+                except Exception as e:
+                    RNS.log(f"Error while checking auto-connected interface state for {interface}: {e}", RNS.LOG_ERROR)
+
+            max_autoconnected_interfaces = RNS.Reticulum.max_autoconnected_interfaces()
+            free_slots = max(0, max_autoconnected_interfaces - autoconnected_interfaces)
+            reserved_slots = max_autoconnected_interfaces//4
+
+            if online_interfaces >= max_autoconnected_interfaces:
+                for interface in RNS.Transport.interfaces:
+                    if hasattr(interface, "bootstrap_only") and interface.bootstrap_only == True:
+                        RNS.log(f"Tearing down bootstrap-only {interface} since target connected auto-discovered interface count has been reached", RNS.LOG_INFO)
+                        if not interface in detached_interfaces: detached_interfaces.append(interface)
+
+            if online_interfaces == 0:
+                if self.bootstrap_interface_count() == 0:
+                    RNS.log(f"No auto-discovered interfaces connected, re-enabling bootstrap interfaces", RNS.LOG_NOTICE)
+                    for config in RNS.Reticulum.get_instance().bootstrap_configs:
+                        RNS.Reticulum.get_instance()._synthesize_interface(config, config["name"])
+
+            if self.initial_autoconnect_ran and free_slots > reserved_slots:
+                candidate_interfaces = self.list_discovered_interfaces(only_available=True, only_transport=True)
+                if len(candidate_interfaces) > 0:
+                    random.shuffle(candidate_interfaces)
+                    selected_interface = candidate_interfaces[0]
+                    if not self.interface_exists(selected_interface): self.autoconnect(selected_interface)
+
+            for interface in detached_interfaces:
+                try: self.teardown_interface(interface)
+                except Exception as e:
+                    RNS.log(f"Error while de-registering auto-connected interface from transport: {e}", RNS.LOG_ERROR)
+
+    def teardown_interface(self, interface):
+        interface.detach()
+        if interface in RNS.Transport.interfaces:  RNS.Transport.interfaces.remove(interface)
+        if interface in self.monitored_interfaces: self.monitored_interfaces.remove(interface)
+
+    def autoconnect_count(self):
+        return len([i for i in RNS.Transport.interfaces if hasattr(i, "autoconnect_hash")])
+
+    def bootstrap_interface_count(self):
+        return len([i for i in RNS.Transport.interfaces if hasattr(i, "bootstrap_only") and i.bootstrap_only == True])
+        
+    def connect_discovered(self):
+        if RNS.Reticulum.should_autoconnect_discovered_interfaces():
+            try:
+                discovered_interfaces = self.list_discovered_interfaces(only_transport=True)
+                for info in discovered_interfaces:
+                    if self.autoconnect_count() >= RNS.Reticulum.max_autoconnected_interfaces(): break
+                    self.autoconnect(info)
+
+                self.initial_autoconnect_ran = True
+
+            except Exception as e:
+                RNS.log(f"Error while reconnecting discovered interfaces: {e}", RNS.LOG_ERROR)
+
+    def endpoint_hash(self, info):
+        endpoint_specifier = ""
+        if "reachable_on" in info: endpoint_specifier += str(info["reachable_on"])
+        if "port" in info:         endpoint_specifier += ":"+str(info["port"])
+        endpoint_hash = RNS.Identity.full_hash(endpoint_specifier.encode("utf-8"))
+        return endpoint_hash
+
+    def interface_exists(self, info):
+        exists = False
+        for interface in RNS.Transport.interfaces:
+            if hasattr(interface, "autoconnect_hash") and interface.autoconnect_hash == self.endpoint_hash(info):
+                exists = True
+                break
+            
+            else:
+                dest_match = "reachable_on" in info and hasattr(interface, "target_ip") and interface.target_ip == info["reachable_on"]
+                port_match = not "port" in info or (hasattr(interface, "target_port") and "port" in info and interface.target_port == info["port"])
+                b32d_match = "reachable_on" in info and hasattr(interface, "b32") and interface.b32 == info["reachable_on"]
+
+                if (dest_match and port_match) or b32d_match:
+                    exists = True
+                    break
+
+        return exists
+
+    def autoconnect(self, info):
+        try:
+            if RNS.Reticulum.should_autoconnect_discovered_interfaces():
+                autoconnected_count = self.autoconnect_count()
+                if autoconnected_count < RNS.Reticulum.max_autoconnected_interfaces():
+                    interface_type = info["type"]
+                    if interface_type in self.AUTOCONNECT_TYPES:
+                        endpoint_hash = self.endpoint_hash(info)
+                        exists = self.interface_exists(info)
+
+                        if exists: RNS.log(f"Discovered {interface_type} already exists, not auto-connecting", RNS.LOG_DEBUG)
+                        else:
+                            if interface_type == "TCPClientInterface":
+                                RNS.log(f"Your operating system does not support the Backbone interface type, and must degrade to using TCPClientInterface instead", RNS.LOG_WARNING)
+                                RNS.log(f"Auto-connecting discovered TCPClient interfaces is not yet implemented, aborting auto-connect", RNS.LOG_WARNING)
+                                RNS.log(f"You can obtain the configuration entry and add this interface manually instead using rnstatus -D", RNS.LOG_WARNING)
+                                return
+
+                            if interface_type == "I2PInterface":
+                                RNS.log(f"Auto-connecting discovered I2P interfaces is not yet implemented, aborting auto-connect", RNS.LOG_WARNING)
+                                RNS.log(f"You can obtain the configuration entry and add this interface manually instead using rnstatus -D", RNS.LOG_WARNING)
+                                return
+
+                            interface_name = info["name"]
+                            RNS.log(f"Auto-connecting discovered {interface_type} {interface_name}")
+                            config_entry = info["config_entry"]
+                            interface_config = {}
+                            interface_config["name"] = f"{interface_name}"
+                            ifac_netname = info["ifac_netname"] if "ifac_netname" in info else None
+                            ifac_netkey  = info["ifac_netkey"]  if "ifac_netkey"  in info else None
+                            interface    = None
+
+                            if interface_type == "BackboneInterface":
+                                from RNS.Interfaces import BackboneInterface
+                                interface_config["target_host"] = info["reachable_on"]
+                                interface_config["target_port"] = info["port"]
+                                interface = BackboneInterface.BackboneClientInterface(RNS.Transport, interface_config)
+
+                            if interface:
+                                interface.autoconnect_hash = endpoint_hash
+                                interface.autoconnect_source = info["network_id"]
+                                RNS.Reticulum.get_instance()._add_interface(interface, ifac_netname=ifac_netname, ifac_netkey=ifac_netkey, configured_bitrate=5E6)
+                                self.monitor_interface(interface)
+
+        except Exception as e:
+            RNS.log(f"Error while auto-connecting discovered interface: {e}", RNS.LOG_ERROR)
+            RNS.trace_exception(e)
+
+class BlackholeUpdater():
+    INITIAL_WAIT    = 20
+    JOB_INTERVAL    = 60
+    UPDATE_INTERVAL = 1*60*60
+    SOURCE_TIMEOUT  = 25
+
+    def __init__(self):
+        self.last_updates = {}
+        self.should_run   = False
+        self.job_interval = self.JOB_INTERVAL
+        self.update_lock  = threading.Lock()
+
+    def start(self):
+        if not self.should_run:
+            source_count = len(RNS.Reticulum.blackhole_sources())
+            ms = "" if source_count == 1 else "s"
+            RNS.log(f"Starting blackhole updater with {source_count} source{ms}", RNS.LOG_DEBUG)
+            self.should_run = True
+            threading.Thread(target=self.job, daemon=True).start()
+
+    def stop(self): self.should_run = False
+
+    def update_link_established(self, link):
+        remote_identity = link.get_remote_identity()
+        RNS.log(f"Link established for blackhole list update from {RNS.prettyhexrep(remote_identity.hash)}", RNS.LOG_DEBUG)
+        receipt = link.request("/list")
+        while not receipt.concluded(): time.sleep(0.2)
+        response = receipt.get_response()
+        link.teardown()
+        
+        if type(response) == dict: blackhole_list = response
+        else:                      blackhole_list = None
+
+        if blackhole_list:
+            added = 0
+            for identity_hash in blackhole_list:
+                entry = blackhole_list[identity_hash]
+                if not identity_hash in RNS.Transport.blackholed_identities:
+                    RNS.Transport.blackholed_identities[identity_hash] = entry
+                    added += 1
+
+            if added > 0:
+                spec = "identity" if added == 1 else "identities"
+                RNS.log(f"Added {added} blackholed {spec} from {RNS.prettyhexrep(remote_identity.hash)}", RNS.LOG_DEBUG)
+
+                try:
+                    sourcelistpath = os.path.join(RNS.Reticulum.blackholepath, RNS.hexrep(remote_identity.hash, delimit=False))
+                    tmppath = f"{sourcelistpath}.tmp"
+                    with open(tmppath, "wb") as f: f.write(msgpack.packb(blackhole_list))
+                    if os.path.isfile(sourcelistpath): os.unlink(sourcelistpath)
+                    os.rename(tmppath, sourcelistpath)
+                
+                except Exception as e:
+                    RNS.log(f"Error while persisting blackhole list from {RNS.prettyhexrep(remote_identity.hash)}: {e}", RNS.LOG_ERROR)
+
+        RNS.log(f"Blackhole list update from {RNS.prettyhexrep(remote_identity.hash)} completed", RNS.LOG_DEBUG)
+
+    def job(self):
+        time.sleep(self.INITIAL_WAIT)
+        while self.should_run:
+            try:
+                now = time.time()
+                for identity_hash in RNS.Reticulum.blackhole_sources():
+                    if identity_hash in self.last_updates: last_update = self.last_updates[identity_hash]
+                    else:                                  last_update = 0
+
+                    if now > last_update+self.UPDATE_INTERVAL:
+                        try:
+                            destination_hash = RNS.Destination.hash_from_name_and_identity("rnstransport.info.blackhole", identity_hash)
+                            RNS.log(f"Attempting blackhole list update from {RNS.prettyhexrep(identity_hash)}...", RNS.LOG_DEBUG)
+                            if not RNS.Transport.await_path(destination_hash): RNS.log(f"No path available for blackhole list update from {RNS.prettyhexrep(identity_hash)}, retrying later", RNS.LOG_VERBOSE)
+                            else:
+                                remote_identity = RNS.Identity.recall(destination_hash)
+                                destination = RNS.Destination(remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, "rnstransport", "info", "blackhole")
+                                RNS.Link(destination, established_callback=self.update_link_established)
+                                self.last_updates[identity_hash] = time.time()
+
+                        except Exception as e:
+                            RNS.log(f"Error while establishing link for blackhole list update from {RNS.prettyhexrep(identity_hash)}: {e}", RNS.LOG_ERROR)
+
+            except Exception as e:
+                RNS.log(f"Error in blackhole list updater job: {e}", RNS.LOG_ERROR)
+                RNS.trace_exception(e)
+
+            time.sleep(self.job_interval)
+
+def is_ip_address(address_string):
+    try:
+        ipaddress.ip_address(address_string)
+        return True
+    except: return False
+
+def is_hostname(hostname):
+    if hostname[-1] == ".": hostname = hostname[:-1]
+    if len(hostname) > 253: return False
+    components = hostname.split(".")
+    if re.match(r"[0-9]+$", components[-1]): return False
+    allowed = re.compile(r"(?!-)[a-z0-9-]{1,63}(?<!-)$", re.IGNORECASE)
+    return all(allowed.match(label) for label in components)

RNS/Identity.py

@@ -94,17 +94,25 @@ class Identity:
     known_ratchets = {}
 
     ratchet_persist_lock = threading.Lock()
+    known_destinations_lock = threading.Lock()
 
     @staticmethod
     def remember(packet_hash, destination_hash, public_key, app_data = None):
         if len(public_key) != Identity.KEYSIZE//8:
             raise TypeError("Can't remember "+RNS.prettyhexrep(destination_hash)+", the public key size of "+str(len(public_key))+" is not valid.", RNS.LOG_ERROR)
         else:
-            Identity.known_destinations[destination_hash] = [time.time(), packet_hash, public_key, app_data]
-
+            with Identity.known_destinations_lock:
+                if not destination_hash in Identity.known_destinations:
+                    Identity.known_destinations[destination_hash] = [time.time(), packet_hash, public_key, app_data, 0]
+                else:
+                    entry = Identity.known_destinations[destination_hash]
+                    entry[0] = time.time()
+                    entry[1] = packet_hash
+                    entry[2] = public_key
+                    entry[3] = app_data
 
     @staticmethod
-    def recall(target_hash, from_identity_hash=False):
+    def recall(target_hash, from_identity_hash=False, _no_use=False):
         """
         Recall identity for a destination or identity hash. By default, this function
         will return the identity associated with a given *destination* hash. As an
@@ -120,6 +128,7 @@ class Identity:
         if from_identity_hash:
             for destination_hash in Identity.known_destinations:
                 if target_hash == Identity.truncated_hash(Identity.known_destinations[destination_hash][2]):
+                    if not _no_use: RNS.Reticulum.get_instance()._used_destination_data(destination_hash)
                     identity_data = Identity.known_destinations[destination_hash]
                     identity = Identity(create_keys=False)
                     identity.load_public_key(identity_data[2])
@@ -130,6 +139,7 @@ class Identity:
 
         else:
             if target_hash in Identity.known_destinations:
+                if not _no_use: RNS.Reticulum.get_instance()._used_destination_data(target_hash)
                 identity_data = Identity.known_destinations[target_hash]
                 identity = Identity(create_keys=False)
                 identity.load_public_key(identity_data[2])
@@ -146,7 +156,7 @@ class Identity:
                 return None
 
     @staticmethod
-    def recall_app_data(destination_hash):
+    def recall_app_data(destination_hash, _no_use=False):
         """
         Recall last heard app_data for a destination hash.
 
@@ -154,13 +164,14 @@ class Identity:
         :returns: *Bytes* containing app_data, or *None* if the destination is unknown.
         """
         if destination_hash in Identity.known_destinations:
+            if not _no_use: RNS.Reticulum.get_instance()._used_destination_data(destination_hash)
             app_data = Identity.known_destinations[destination_hash][3]
             return app_data
-        else:
-            return None
+        
+        else: return None
 
     @staticmethod
-    def save_known_destinations():
+    def save_known_destinations(background=False, recombine=True):
         # TODO: Improve the storage method so we don't have to
         # deserialize and serialize the entire table on every
         # save, but the only changes. It might be possible to
@@ -181,34 +192,33 @@ class Identity:
             Identity.saving_known_destinations = True
             save_start = time.time()
 
-            storage_known_destinations = {}
-            if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
+            if recombine:
+                storage_known_destinations = {}
+                if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
+                    try:
+                        with open(RNS.Reticulum.storagepath+"/known_destinations","rb") as file:
+                            storage_known_destinations = umsgpack.load(file)
+     
+                    except: pass
+
                 try:
-                    with open(RNS.Reticulum.storagepath+"/known_destinations","rb") as file:
-                        storage_known_destinations = umsgpack.load(file)
- 
-                except:
-                    pass
+                    for destination_hash in storage_known_destinations:
+                        if not destination_hash in Identity.known_destinations:
+                            with Identity.known_destinations_lock:
+                                Identity.known_destinations[destination_hash] = storage_known_destinations[destination_hash]
+                
+                except Exception as e:
+                    RNS.log("Skipped recombining known destinations from disk, since an error occurred: "+str(e), RNS.LOG_WARNING)
 
-            try:
-                for destination_hash in storage_known_destinations:
-                    if not destination_hash in Identity.known_destinations:
-                        Identity.known_destinations[destination_hash] = storage_known_destinations[destination_hash]
-            except Exception as e:
-                RNS.log("Skipped recombining known destinations from disk, since an error occurred: "+str(e), RNS.LOG_WARNING)
-
-            RNS.log("Saving "+str(len(Identity.known_destinations))+" known destinations to storage...", RNS.LOG_DEBUG)
+            RNS.log("Saving "+str(len(Identity.known_destinations))+" known destinations to storage...", RNS.LOG_VERBOSE)
             with open(RNS.Reticulum.storagepath+"/known_destinations","wb") as file:
-                umsgpack.dump(Identity.known_destinations, file)
-            
+                umsgpack.dump(Identity.known_destinations.copy(), file)
 
             save_time = time.time() - save_start
-            if save_time < 1:
-                time_str = str(round(save_time*1000,2))+"ms"
-            else:
-                time_str = str(round(save_time,2))+"s"
+            if save_time < 1: time_str = str(round(save_time*1000,2))+"ms"
+            else:             time_str = str(round(save_time,2))+"s"
 
-            RNS.log("Saved known destinations to storage in "+time_str, RNS.LOG_DEBUG)
+            RNS.log("Saved known destinations to storage in "+time_str, RNS.LOG_VERBOSE)
 
         except Exception as e:
             RNS.log("Error while saving known destinations to disk, the contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -219,6 +229,7 @@ class Identity:
     @staticmethod
     def load_known_destinations():
         if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
+            st = time.time()
             try:
                 with open(RNS.Reticulum.storagepath+"/known_destinations","rb") as file:
                     loaded_known_destinations = umsgpack.load(file)
@@ -226,15 +237,102 @@ class Identity:
                 Identity.known_destinations = {}
                 for known_destination in loaded_known_destinations:
                     if len(known_destination) == RNS.Reticulum.TRUNCATED_HASHLENGTH//8:
-                        Identity.known_destinations[known_destination] = loaded_known_destinations[known_destination]
+                        if len(loaded_known_destinations[known_destination]) < 5:
+                            e = loaded_known_destinations[known_destination]
+                            loaded_known_destinations[known_destination] = [e[0], e[1], e[2], e[3], 0]
 
-                RNS.log("Loaded "+str(len(Identity.known_destinations))+" known destination from storage", RNS.LOG_VERBOSE)
+                        with Identity.known_destinations_lock:
+                            Identity.known_destinations[known_destination] = loaded_known_destinations[known_destination]
+
+                RNS.log(f"Loaded {len(Identity.known_destinations)} known destination from storage in {RNS.prettyshorttime(time.time()-st)}", RNS.LOG_VERBOSE)
 
             except Exception as e:
                 RNS.log("Error loading known destinations from disk, file will be recreated on exit", RNS.LOG_ERROR)
+                RNS.trace_exception(e)
         else:
             RNS.log("Destinations file does not exist, no known destinations loaded", RNS.LOG_VERBOSE)
 
+    @staticmethod
+    def _used_destination_data(destination_hash):
+        with Identity.known_destinations_lock:
+            if destination_hash in Identity.known_destinations:
+                if not Identity.known_destinations[destination_hash][4] < 0:
+                    Identity.known_destinations[destination_hash][4] = time.time()
+                    return True
+
+        return False
+
+    @staticmethod
+    def _retain_destination_data(destination_hash):
+        with Identity.known_destinations_lock:
+            if destination_hash in Identity.known_destinations:
+                Identity.known_destinations[destination_hash][4] = -1
+                return True
+
+        return False
+
+    @staticmethod
+    def _unretain_destination_data(destination_hash):
+        with Identity.known_destinations_lock:
+            if destination_hash in Identity.known_destinations:
+                Identity.known_destinations[destination_hash][4] = time.time()
+                return True
+
+        return False
+    
+    @staticmethod
+    def clean_known_destinations():
+        now        = time.time()
+        st         = now
+        total      = len(Identity.known_destinations)
+        stale      = []
+        no_path    = 0
+        retained   = 0
+        never_used = 0
+        for destination_hash in Identity.known_destinations:
+            try:
+                if RNS.Transport.has_path(destination_hash): has_path = True
+                else:
+                    has_path = False
+                    no_path += 1
+
+                with Identity.known_destinations_lock:
+                    if destination_hash in Identity.known_destinations:
+                        last_announce =  Identity.known_destinations[destination_hash][0]
+                        last_use = 0
+                        was_used = False
+                        is_retained = False
+
+                        if Identity.known_destinations[destination_hash][4] > 0:
+                            was_used = True
+                            last_use = Identity.known_destinations[destination_hash][4]
+
+                        elif Identity.known_destinations[destination_hash][4] == 0:
+                            was_used = False
+                            never_used += 1
+
+                        elif Identity.known_destinations[destination_hash][4] == -1:
+                            is_retained = True
+                            retained += 1
+
+                        unused_for = time.time() - Identity.known_destinations[destination_hash][4]
+
+                        if not is_retained and not has_path:
+                            if not was_used and now - last_announce > RNS.Transport.UNUSED_DESTINATION_LINGER: stale.append(destination_hash)
+                            elif unused_for > RNS.Transport.DESTINATION_TIMEOUT*1.25:                          stale.append(destination_hash)
+
+            except Exception as e: RNS.log(f"Faulty entry for {RNS.prettyhexrep(destination_hash)} while cleaning known destinations: {e}", RNS.LOG_DEBUG)
+
+        removed = 0
+        for destination_hash in stale:
+            with Identity.known_destinations_lock:
+                if destination_hash in Identity.known_destinations:
+                    Identity.known_destinations.pop(destination_hash)
+                    removed += 1
+
+        # RNS.log(f"Total destinations: {total}, stale: {len(stale)}, removed: {removed}, no path: {no_path}, never used: {never_used}, with path: {total-no_path}, used: {total-never_used}, retained: {retained}. Completed in {RNS.prettyshorttime(time.time()-st)}", RNS.LOG_WARNING) # TODO: Remove
+        if not RNS.Transport.owner.is_connected_to_shared_instance: Identity.save_known_destinations(recombine=False)
+
     @staticmethod
     def full_hash(data):
         """
@@ -333,33 +431,40 @@ class Identity:
     def _clean_ratchets():
         RNS.log("Cleaning ratchets...", RNS.LOG_DEBUG)
         try:
+            count = 0
+            removed = 0
+            not_known = 0
             now = time.time()
             ratchetdir = RNS.Reticulum.storagepath+"/ratchets"
             if os.path.isdir(ratchetdir):
                 for filename in os.listdir(ratchetdir):
+                    count += 1
                     try:
                         expired = False
                         corrupted = False
                         with open(f"{ratchetdir}/{filename}", "rb") as rf:
-                            # TODO: Remove individual ratchet file if corrupt
                             try:
                                 ratchet_data = umsgpack.unpackb(rf.read())
-                                if now > ratchet_data["received"]+Identity.RATCHET_EXPIRY:
-                                    expired = True
+                                if now > ratchet_data["received"]+Identity.RATCHET_EXPIRY: expired = True
 
                             except Exception as e:
                                 RNS.log(f"Corrupted ratchet data while reading {ratchetdir}/{filename}, removing file", RNS.LOG_ERROR)
                                 corrupted = True
 
-                        if expired or corrupted:
+                        destination_hash = bytes.fromhex(filename)
+                        if not destination_hash in RNS.Identity.known_destinations: unknown = True; not_known += 1
+                        else:                                                       unknown = False
+
+                        if expired or corrupted or unknown:
                             os.unlink(f"{ratchetdir}/{filename}")
+                            removed += 1
 
                     except Exception as e:
                         RNS.log(f"An error occurred while cleaning ratchets, in the processing of {ratchetdir}/{filename}.", RNS.LOG_ERROR)
                         RNS.log(f"The contained exception was: {e}", RNS.LOG_ERROR)
 
-        except Exception as e:
-            RNS.log(f"An error occurred while cleaning ratchets. The contained exception was: {e}", RNS.LOG_ERROR)
+        except Exception as e: RNS.log(f"An error occurred while cleaning ratchets. The contained exception was: {e}", RNS.LOG_ERROR)
+        RNS.log(f"Processed {count} ratchets in {RNS.prettytime(time.time()-now)}, not in use {not_known}, removed {removed}", RNS.LOG_DEBUG)
 
     @staticmethod
     def get_ratchet(destination_hash):
@@ -430,6 +535,11 @@ class Identity:
                 announced_identity = Identity(create_keys=False)
                 announced_identity.load_public_key(public_key)
 
+                if len(RNS.Transport.blackholed_identities) > 0:
+                    if announced_identity.hash in RNS.Transport.blackholed_identities:
+                        RNS.log(f"Invalidated and dropped announce from blackholed identity {RNS.prettyhexrep(announced_identity.hash)}", RNS.LOG_EXTREME)
+                        return False
+
                 if announced_identity.pub != None and announced_identity.validate(signature, signed_data):
                     if only_validate_signature:
                         del announced_identity
@@ -488,9 +598,9 @@ class Identity:
             return False
 
     @staticmethod
-    def persist_data():
+    def persist_data(background=False):
         if not RNS.Transport.owner.is_connected_to_shared_instance:
-            Identity.save_known_destinations()
+            Identity.save_known_destinations(background=background)
 
     @staticmethod
     def exit_handler():

RNS/Interfaces/Android/RNodeInterface.py

@@ -32,6 +32,7 @@ from RNS.Interfaces.Interface import Interface
 from time import sleep
 import sys
 import threading
+import socket
 import time
 import math
 import RNS
@@ -73,6 +74,7 @@ class KISS():
     CMD_STAT_PHYPRM = 0x26
     CMD_STAT_BAT    = 0x27
     CMD_STAT_CSMA   = 0x28
+    CMD_STAT_TEMP   = 0x29
     CMD_BLINK       = 0x30
     CMD_RANDOM      = 0x40
     CMD_FB_EXT      = 0x41
@@ -363,7 +365,9 @@ class RNodeInterface(Interface):
         target_device_address = c["target_device_address"] if "target_device_address" in c else None
         ble_name = c["ble_name"] if "ble_name" in c else None
         ble_addr = c["ble_addr"] if "ble_addr" in c else None
+        tcp_host = c["tcp_host"] if "tcp_host" in c else None
         force_ble = c["force_ble"] if "force_ble" in c else False
+        force_tcp = c["force_tcp"] if "force_tcp" in c else False
         frequency = int(c["frequency"]) if "frequency" in c else 0
         bandwidth = int(c["bandwidth"]) if "bandwidth" in c else 0
         txpower = int(c["txpower"]) if "txpower" in c else 0
@@ -435,6 +439,14 @@ class RNodeInterface(Interface):
         self.ble_rx_queue= b""
         self.ble_tx_queue= b""
 
+        self.tcp         = None
+        self.use_tcp     = False
+        self.tcp_host    = tcp_host
+        self.tcp_rx_queue= b""
+        self.tcp_tx_queue= b""
+        self.tcp_rx_lock = threading.Lock()
+        self.tcp_tx_lock = threading.Lock()
+
         self.frequency   = frequency
         self.bandwidth   = bandwidth
         self.txpower     = txpower
@@ -444,6 +456,7 @@ class RNodeInterface(Interface):
         self.bitrate     = 0
         self.st_alock    = st_alock
         self.lt_alock    = lt_alock
+        self.cpu_temp    = None
         self.platform    = None
         self.display     = None
         self.mcu         = None
@@ -456,6 +469,7 @@ class RNodeInterface(Interface):
         self.first_tx    = None
         self.reconnect_w = RNodeInterface.RECONNECT_WAIT
         self.reconnect_lock = threading.Lock()
+        self.awaiting_ble_reset = False
 
         self.r_frequency = None
         self.r_bandwidth = None
@@ -486,6 +500,9 @@ class RNodeInterface(Interface):
         self.r_csma_cw_max        = None
         self.r_current_rssi       = None
         self.r_noise_floor        = None
+        self.r_interference       = None
+        self.r_interference_l     = None
+        self.r_temperature        = None
 
         self.r_battery_state = RNodeInterface.BATTERY_STATE_UNKNOWN
         self.r_battery_percent = 0
@@ -507,15 +524,15 @@ class RNodeInterface(Interface):
         self.port_io_timeout = RNodeInterface.PORT_IO_TIMEOUT
         self.last_imagedata = None
 
-        if force_ble or self.ble_addr != None or self.ble_name != None:
-            self.use_ble = True
+        if force_ble or self.ble_addr != None or self.ble_name != None: self.use_ble = True
+        if force_tcp or self.tcp_host != None:                          self.use_tcp = True
 
         self.validcfg  = True
         if (self.frequency < RNodeInterface.FREQ_MIN or self.frequency > RNodeInterface.FREQ_MAX):
             RNS.log("Invalid frequency configured for "+str(self), RNS.LOG_ERROR)
             self.validcfg = False
 
-        if (self.txpower < 0 or self.txpower > 22):
+        if (self.txpower < 0 or self.txpower > 37):
             RNS.log("Invalid TX power configured for "+str(self), RNS.LOG_ERROR)
             self.validcfg = False
 
@@ -558,10 +575,8 @@ class RNodeInterface(Interface):
             self.open_port()
 
             if self.serial != None:
-                if self.serial.is_open:
-                    self.configure_device()
-                else:
-                    raise IOError("Could not open serial port")
+                if self.serial.is_open: self.configure_device()
+                else: raise IOError("Could not open serial port")
             elif self.bt_manager != None:
                 if self.bt_manager.connected:
                     self.configure_device()
@@ -579,12 +594,9 @@ class RNodeInterface(Interface):
 
 
     def read_mux(self, len=None):
-        if self.serial != None:
-            return self.serial.read()
-        elif self.bt_manager != None:
-            return self.bt_manager.read()
-        else:
-            raise IOError("No ports available for reading")
+        if self.serial != None: return self.serial.read()
+        elif self.bt_manager != None: return self.bt_manager.read()
+        else: raise IOError("No ports available for reading")
 
     def write_mux(self, data):
         if self.serial != None:
@@ -599,17 +611,19 @@ class RNodeInterface(Interface):
         else:
             raise IOError("No ports available for writing")
 
-    # def reset_ble(self):
-    #     RNS.log(f"Clearing previous connection instance: "+str(self.ble))
-    #     del self.ble
-    #     self.ble = None
-    #     self.serial = None
-    #     self.ble = BLEConnection(owner=self, target_name=self.ble_name, target_bt_addr=self.ble_addr)
-    #     self.serial = self.ble
-    #     RNS.log(f"New connection instance: "+str(self.ble))
+    def reset_ble(self):
+        if not self.awaiting_ble_reset: return
+        else:
+            RNS.log(f"Clearing previous connection instance: "+str(self.ble), RNS.LOG_DEBUG)
+            self.ble = None
+            self.serial = None
+            self.ble = BLEConnection(owner=self, target_name=self.ble_name, target_bt_addr=self.ble_addr)
+            self.serial = self.ble
+            self.awaiting_ble_reset = False
+            RNS.log(f"New connection instance: "+str(self.ble), RNS.LOG_DEBUG)
         
     def open_port(self):
-        if not self.use_ble:
+        if not self.use_ble and not self.use_tcp:
             if self.port != None:
                 RNS.log("Opening serial port "+self.port+"...")
                 # Get device parameters
@@ -677,7 +691,7 @@ class RNodeInterface(Interface):
                 if self.bt_manager != None:
                     self.bt_manager.connect_any_device()
 
-        else:
+        elif self.use_ble:
             if self.ble == None:
                 self.ble = BLEConnection(owner=self, target_name=self.ble_name, target_bt_addr=self.ble_addr)
                 self.serial = self.ble
@@ -686,6 +700,24 @@ class RNodeInterface(Interface):
             while not self.ble.connected and time.time() < open_time + self.ble.CONNECT_TIMEOUT:
                 time.sleep(1)
 
+        elif self.use_tcp:
+            RNS.log(f"Opening TCP connection for {self}...")
+            if self.tcp != None and self.tcp.running == False:
+                self.tcp.close()
+                self.tcp.cleanup()
+                self.tcp = None
+
+            if self.tcp == None:
+                self.tcp = TCPConnection(owner=self, target_host=self.tcp_host)
+                self.serial = self.tcp
+
+            open_time = time.time()
+            while not self.tcp.connected and time.time() < open_time + self.tcp.CONNECT_TIMEOUT:
+                time.sleep(1)
+
+        else:
+            raise TypeError("No valid device connection type defined for RNode interface")
+
 
     def configure_device(self):
         self.resetRadioState()
@@ -693,17 +725,19 @@ class RNodeInterface(Interface):
         thread = threading.Thread(target=self.readLoop, daemon=True).start()
 
         self.detect()
-        if not self.use_ble:
-            sleep(0.5)
-        else:
+        if self.use_tcp:
+            tcp_detect_timeout = 5.0
+            detect_time = time.time()
+            while not self.detected and time.time() < detect_time + tcp_detect_timeout: time.sleep(0.1)
+            if not self.detected: RNS.log(f"RNode detect timed out over TCP", RNS.LOG_ERROR)
+        elif self.use_ble:
             ble_detect_timeout = 5
             detect_time = time.time()
-            while not self.detected and time.time() < detect_time + ble_detect_timeout:
-                time.sleep(0.1)
-            if self.detected:
-                detect_time = RNS.prettytime(time.time()-detect_time)
-            else:
-                RNS.log(f"RNode detect timed out over {self.port}", RNS.LOG_ERROR)
+            while not self.detected and time.time() < detect_time + ble_detect_timeout: time.sleep(0.1)
+            if self.detected: detect_time = RNS.prettytime(time.time()-detect_time)
+            else: RNS.log(f"RNode detect timed out over {self.port}", RNS.LOG_ERROR)
+        else:
+            sleep(0.2)
 
         if not self.detected:
             raise IOError("Could not detect device")
@@ -716,11 +750,19 @@ class RNodeInterface(Interface):
 
         if self.serial != None and self.port != None:
             self.timeout = 200
-            RNS.log("Serial port "+self.port+" is now open")
+            RNS.log(f"Serial port {self.port} is now open")
 
         if self.bt_manager != None and self.bt_manager.connected:
             self.timeout = 1500
-            RNS.log("Bluetooth connection to RNode now open")
+            RNS.log(f"Bluetooth connection to RNode now open")
+
+        if self.ble != None and self.ble.connected:
+            self.timeout = 1500
+            RNS.log(f"BLE connection {self.port} to RNode now open")
+
+        if self.tcp != None and self.tcp.connected:
+            self.timeout = 1500
+            RNS.log(f"TCP connection tcp://{self.tcp_host} to RNode now open")
 
         RNS.log("Configuring RNode interface...", RNS.LOG_VERBOSE)
         self.initRadio()
@@ -972,10 +1014,8 @@ class RNodeInterface(Interface):
 
     def validateRadioState(self):
         RNS.log("Waiting for radio configuration validation for "+str(self)+"...", RNS.LOG_VERBOSE)
-        if not self.platform == KISS.PLATFORM_ESP32:
-            sleep(1.00);
-        else:
-            sleep(2.00);
+        if not self.platform == KISS.PLATFORM_ESP32: sleep(1.00);
+        else: sleep(2.00);
 
         self.validcfg = True
         if (self.r_frequency != None and abs(self.frequency - int(self.r_frequency)) > 100):
@@ -1272,10 +1312,12 @@ class RNodeInterface(Interface):
                                     self.r_channel_load_long  = cul/100.0
                                     self.r_current_rssi       = crs-RNodeInterface.RSSI_OFFSET
                                     self.r_noise_floor        = nfl-RNodeInterface.RSSI_OFFSET
+                                    
                                     if ntf == 0xFF:
                                         self.r_interference   = None
                                     else:
                                         self.r_interference   = ntf-RNodeInterface.RSSI_OFFSET
+                                        self.r_interference_l = [time.time(), self.r_interference]
                                     
                                     if self.r_interference != None:
                                         RNS.log(f"{self} Radio detected interference at {self.r_interference} dBm", RNS.LOG_DEBUG)
@@ -1355,6 +1397,22 @@ class RNodeInterface(Interface):
                                         bat_percent = 0
                                     self.r_battery_state   = command_buffer[0]
                                     self.r_battery_percent = bat_percent
+                        elif (command == KISS.CMD_STAT_TEMP):
+                            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) == 1):
+                                    temp = command_buffer[0]-120
+                                    if temp >= -30 and temp <= 90: self.r_temperature = temp
+                                    else:                          self.r_temperature = None
+                                    self.cpu_temp = self.r_temperature
                         elif (command == KISS.CMD_RANDOM):
                             self.r_random = byte
                         elif (command == KISS.CMD_PLATFORM):
@@ -1425,7 +1483,7 @@ class RNodeInterface(Interface):
                 if got == 0:
                     time_since_last = int(time.time()*1000) - last_read_ms
                     if len(data_buffer) > 0 and time_since_last > self.timeout:
-                        RNS.log(str(self)+" serial read timeout in command "+str(command), RNS.LOG_WARNING)
+                        RNS.log(f"{self} device read timeout in command {command} after {RNS.prettytime(self.timeout/1000.0)}", RNS.LOG_WARNING)
                         data_buffer = b""
                         in_frame = False
                         command = KISS.CMD_UNKNOWN
@@ -1436,19 +1494,19 @@ class RNodeInterface(Interface):
                             if time.time() > self.first_tx + self.id_interval:
                                 RNS.log("Interface "+str(self)+" is transmitting beacon data: "+str(self.id_callsign.decode("utf-8")), RNS.LOG_DEBUG)
                                 self.process_outgoing(self.id_callsign)
-                    
-                    if (time.time() - self.last_port_io > self.port_io_timeout):
-                        self.detect()
-                    
-                    if (time.time() - self.last_port_io > self.port_io_timeout*3):
-                        raise IOError("Connected port for "+str(self)+" became unresponsive")
 
-                    if self.bt_manager != None:
-                        sleep(0.08)
+                    if self.use_tcp:
+                        if self.tcp and self.tcp.connected:
+                            if time.time() > self.tcp.last_write + self.tcp.ACTIVITY_KEEPALIVE:
+                                self.detect()
+                    
+                    if (time.time() - self.last_port_io > self.port_io_timeout): self.detect()
+                    if (time.time() - self.last_port_io > self.port_io_timeout*3): raise IOError("Connected port for "+str(self)+" became unresponsive")
+                    if self.bt_manager != None or self.ble != None: sleep(0.08)
 
         except Exception as e:
             self.online = False
-            RNS.log("A serial port occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
+            RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
             RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is now offline.", RNS.LOG_ERROR)
 
             if RNS.Reticulum.panic_on_interface_error:
@@ -1506,12 +1564,18 @@ class RNodeInterface(Interface):
 
     def detach(self):
         self.detached = True
-        self.disable_external_framebuffer()
-        self.setRadioState(KISS.RADIO_STATE_OFF)
-        self.leave()
+        try:
+            self.disable_external_framebuffer()
+            self.setRadioState(KISS.RADIO_STATE_OFF)
+            self.leave()
 
-        if self.use_ble:
-            self.ble.close()
+        except Exception as e:
+            RNS.log(f"An error occurred while detaching {self}: {e}", RNS.LOG_ERROR)
+
+        if self.use_ble: self.ble.close()
+        if self.use_tcp:
+            time.sleep(0.5)
+            self.tcp.close()
 
     def should_ingress_limit(self):
         return False
@@ -1532,6 +1596,17 @@ class RNodeInterface(Interface):
     def get_battery_percent(self):
         return self.r_battery_percent
 
+    def tcp_receive(self, data):
+        with self.tcp_rx_lock: self.tcp_rx_queue += data
+
+    def tcp_waiting(self): return len(self.tcp_tx_queue) > 0
+
+    def get_tcp_waiting(self, n):
+        with self.tcp_tx_lock:
+            data = self.tcp_tx_queue[:n]
+            self.tcp_tx_queue = self.tcp_tx_queue[n:]
+            return data
+
     def ble_receive(self, data):
         with self.ble_rx_lock:
             self.ble_rx_queue += data
@@ -1546,7 +1621,7 @@ class RNodeInterface(Interface):
             return data
 
     def __str__(self):
-        return "RNodeInterface["+str(self.name)+"]"
+        return f"RNodeInterface[{self.name}]"
 
 class BLEConnection(BluetoothDispatcher):
     UART_SERVICE_UUID = "6e400001-b5a3-f393-e0a9-e50e24dcca9e"
@@ -1554,7 +1629,7 @@ class BLEConnection(BluetoothDispatcher):
     UART_TX_CHAR_UUID = "6e400003-b5a3-f393-e0a9-e50e24dcca9e"
     MAX_GATT_ATTR_LEN = 512
     BASE_MTU          = 20
-    TARGET_MTU        = 242
+    TARGET_MTU        = 512
 
     MTU_TIMEOUT = 4.0
     CONNECT_TIMEOUT = 7.0
@@ -1699,12 +1774,15 @@ class BLEConnection(BluetoothDispatcher):
             else:
                 RNS.log(f"BLE device connection timed out for {self.owner}", RNS.LOG_DEBUG)
                 if self.mtu_requested_time:
-                    RNS.log("MTU update timeout, tearing down connection")
+                    RNS.log("MTU update timeout, tearing down connection and resetting BLE dispatcher")
                     self.owner.hw_errors.append({"error": KISS.ERROR_INVALID_BLE_MTU, "description": "The Bluetooth Low Energy transfer MTU could not be configured for the connected device, and communication has failed. Restart Reticulum and any connected applications to retry connecting."})
                     self.close()
+                    self.close_gatt()
                     self.should_run = False
-                
-                self.close_gatt()
+                    self.owner.awaiting_ble_reset = True
+
+                else:
+                    self.close_gatt()
 
             self.connect_job_running = False
 
@@ -1786,4 +1864,139 @@ class BLEConnection(BluetoothDispatcher):
     def on_characteristic_changed(self, characteristic):
         if characteristic.getUuid().toString() == BLEConnection.UART_TX_CHAR_UUID:
             recvd = bytes(characteristic.getValue())
-            self.owner.ble_receive(recvd)
+            self.owner.ble_receive(recvd)
+
+class TCPConnection():
+    TARGET_PORT = 7633
+    CONNECT_TIMEOUT = 5.0
+    INITIAL_CONNECT_TIMEOUT = 5.0
+    RECONNECT_WAIT = 4.0
+    ACTIVITY_TIMEOUT = 6.0
+    ACTIVITY_KEEPALIVE = ACTIVITY_TIMEOUT-2.5
+
+    TCP_USER_TIMEOUT = 24
+    TCP_PROBE_AFTER = 5
+    TCP_PROBE_INTERVAL = 2
+    TCP_PROBES = 12
+
+    @property
+    def is_open(self):
+        return self.connected
+
+    @property
+    def in_waiting(self):
+        buflen = len(self.owner.tcp_rx_queue)
+        return buflen > 0
+
+    def write(self, data_bytes):
+        if self.connected and self.socket:
+            with self.owner.tcp_tx_lock:
+                if len(self.owner.tcp_tx_queue) > 0:
+                    self.socket.sendall(self.owner.tcp_tx_queue)
+                    self.owner.tcp_tx_queue = b""
+
+            self.socket.sendall(data_bytes)
+            self.last_write = time.time()
+
+        else:
+            with self.owner.tcp_tx_lock: self.owner.tcp_tx_queue += data_bytes
+
+        return len(data_bytes)
+
+    def read(self, n=4096):
+        with self.owner.tcp_rx_lock:
+            data = self.owner.tcp_rx_queue[:n]
+            self.owner.tcp_rx_queue = self.owner.tcp_rx_queue[n:]
+            return data
+
+    def close(self):
+        if self.connected:
+            RNS.log(f"Disconnecting TCP socket for {self.owner}", RNS.LOG_DEBUG)
+            self.must_disconnect = True
+            if self.socket: self.socket.close()
+
+    def __init__(self, owner=None, target_host=None):
+        self.owner = owner
+        self.target_host = target_host
+        self.connected = False
+        self.reconnecting = False
+        self.running = False
+        self.should_run = False
+        self.must_disconnect = False
+        self.connect_job_running = False
+        self.last_write = time.time()
+
+        self.should_run = True
+        self.connection_thread = threading.Thread(target=self.initial_connect, daemon=True).start()
+
+    def set_timeouts_linux(self):
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_USER_TIMEOUT, int(self.TCP_USER_TIMEOUT * 1000))
+        self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, int(self.TCP_PROBE_AFTER))
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, int(self.TCP_PROBE_INTERVAL))
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, int(self.TCP_PROBES))
+
+    def set_timeouts_osx(self):
+        if hasattr(socket, "TCP_KEEPALIVE"): TCP_KEEPIDLE = socket.TCP_KEEPALIVE
+        else: TCP_KEEPIDLE = 0x10
+        self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+        self.socket.setsockopt(socket.IPPROTO_TCP, TCP_KEEPIDLE, int(self.TCP_PROBE_AFTER))
+
+    def cleanup(self):
+        try:
+            if self.socket: self.socket.close()
+        except Exception as e:
+            RNS.log(f"Error while disconnecting TCP socket on cleanup for {self.owner}", RNS.LOG_ERROR)
+
+        self.should_run = False
+
+    def initial_connect(self):
+        if self.connect(initial=True): threading.Thread(target=self.read_loop, daemon=True).start()
+
+    def connect(self, initial=False):
+        try:
+            if initial:
+                RNS.log(f"Establishing TCP connection to device for {self.owner}...", RNS.LOG_DEBUG)
+
+            address_info = socket.getaddrinfo(self.target_host, self.TARGET_PORT, proto=socket.IPPROTO_TCP)[0]
+            address_family = address_info[0]
+            target_address = address_info[4]
+
+            self.socket = socket.socket(address_family, socket.SOCK_STREAM)
+            self.socket.settimeout(self.INITIAL_CONNECT_TIMEOUT)
+            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+            self.socket.connect(target_address)
+            self.socket.settimeout(None)
+            self.connected  = True
+            self.last_write = time.time()
+
+            RNS.log(f"TCP connection to device for {self.owner} established", RNS.LOG_DEBUG)
+
+            if RNS.vendor.platformutils.is_linux():    self.set_timeouts_linux()
+            elif RNS.vendor.platformutils.is_darwin(): self.set_timeouts_osx()
+
+            return True
+        
+        except Exception as e:
+            if initial:
+                RNS.log(f"TCP connection to device for {self.owner} could not be established: {e}", RNS.LOG_ERROR)
+                return False
+            
+            else: raise e
+
+    def read_loop(self):
+        try:
+            data_in = b""
+            while not self.must_disconnect:
+                if self.socket: data_in = self.socket.recv(4096)
+                else: data_in = b""
+
+                if len(data_in) > 0: self.owner.tcp_receive(data_in)
+                else:
+                    self.connected = False
+                    RNS.log(f"The TCP socket for {self} was closed", RNS.LOG_WARNING)
+                    break
+
+        except Exception as e:
+            self.connected = False
+            RNS.log(f"A TCP read error occurred for {self}, the contained exception was: {e}", RNS.LOG_WARNING)

RNS/Interfaces/AutoInterface.py

@@ -58,11 +58,14 @@ class AutoInterface(Interface):
     MULTICAST_PERMANENT_ADDRESS_TYPE = "0"
     MULTICAST_TEMPORARY_ADDRESS_TYPE = "1"
 
-    PEERING_TIMEOUT    = 10.0
+    PEERING_TIMEOUT    = 22.0
+    ANNOUNCE_INTERVAL  =  1.6
+    PEER_JOB_INTERVAL  =  4.0
+    MCAST_ECHO_TIMEOUT =  6.5
 
     ALL_IGNORE_IFS     = ["lo0"]
     DARWIN_IGNORE_IFS  = ["awdl0", "llw0", "lo0", "en5"]
-    ANDROID_IGNORE_IFS = ["dummy0", "lo", "tun0"]
+    ANDROID_IGNORE_IFS = ["dummy0", "lo", "tun0", "rmnet0", "rmnet1", "rmnet2", "rmnet3", "rmnet4", "rmnet5", "rmnet6", "rmnet7"]
 
     BITRATE_GUESS      = 10*1000*1000
 
@@ -125,6 +128,7 @@ class AutoInterface(Interface):
         self.adopted_interfaces = {}
         self.interface_servers = {}
         self.multicast_echoes = {}
+        self.initial_echoes = {}
         self.timed_out_interfaces = {}
         self.spawned_interfaces = {}
         self.write_lock = threading.Lock()
@@ -134,16 +138,17 @@ class AutoInterface(Interface):
 
         self.outbound_udp_socket = None
 
-        self.announce_rate_target = None
-        self.announce_interval = AutoInterface.PEERING_TIMEOUT/6.0
-        self.peer_job_interval = AutoInterface.PEERING_TIMEOUT*1.1
-        self.peering_timeout   = AutoInterface.PEERING_TIMEOUT
-        self.multicast_echo_timeout = AutoInterface.PEERING_TIMEOUT/2
+        self.announce_rate_target     = None
+        self.announce_interval        = AutoInterface.ANNOUNCE_INTERVAL
+        self.peer_job_interval        = AutoInterface.PEER_JOB_INTERVAL
+        self.peering_timeout          = AutoInterface.PEERING_TIMEOUT
+        self.multicast_echo_timeout   = AutoInterface.MCAST_ECHO_TIMEOUT
+        self.reverse_peering_interval = self.announce_interval*3.25
 
         # Increase peering timeout on Android, due to potential
         # low-power modes implemented on many chipsets.
         if RNS.vendor.platformutils.is_android():
-            self.peering_timeout *= 2.5
+            self.peering_timeout *= 1.25
 
         if allowed_interfaces == None:
             self.allowed_interfaces = []
@@ -165,6 +170,8 @@ class AutoInterface(Interface):
         else:
             self.discovery_port = discovery_port
 
+        self.unicast_discovery_port = self.discovery_port+1
+
         if multicast_address_type == None:
             self.multicast_address_type = AutoInterface.MULTICAST_TEMPORARY_ADDRESS_TYPE
         elif str(multicast_address_type).lower() == "temporary":
@@ -240,33 +247,48 @@ class AutoInterface(Interface):
                             if link_local_addr == None:
                                 RNS.log(str(self)+" No link-local IPv6 address configured for "+str(ifname)+", skipping interface", RNS.LOG_EXTREME)
                             else:
-                                mcast_addr = self.mcast_discovery_address
-                                RNS.log(str(self)+" Creating multicast discovery listener on "+str(ifname)+" with address "+str(mcast_addr), RNS.LOG_EXTREME)
+                                RNS.log(str(self)+" Creating unicast discovery listener on "+str(ifname)+" with address "+str(link_local_addr), RNS.LOG_EXTREME)
 
                                 # Struct with interface index
                                 if_struct = struct.pack("I", self.interface_name_to_index(ifname))
 
-                                # Set up multicast socket
+                                # Set up unicast discovery socket
+                                unicast_discovery_socket = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
+                                unicast_discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                                if hasattr(socket, "SO_REUSEPORT"): unicast_discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+
+                                # Bind unicast discovery socket
+                                if RNS.vendor.platformutils.is_windows():
+                                    # Windows throws "[WinError 10049] The requested address is not valid in its context"
+                                    # when trying to use the multicast address as host, or when providing interface index
+                                    # passing an empty host appears to work, but probably not exactly how we want it to...
+                                    unicast_discovery_socket.bind(('', self.unicast_discovery_port))
+
+                                else:
+                                    addr_info = socket.getaddrinfo(link_local_addr+"%"+ifname, self.unicast_discovery_port, socket.AF_INET6, socket.SOCK_DGRAM)
+                                    unicast_discovery_socket.bind(addr_info[0][4])
+
+                                mcast_addr = self.mcast_discovery_address
+                                RNS.log(str(self)+" Creating multicast discovery listener on "+str(ifname)+" with address "+str(mcast_addr), RNS.LOG_EXTREME)
+
+                                # Set up multicast discovery socket
                                 discovery_socket = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
                                 discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-                                if hasattr(socket, "SO_REUSEPORT"):
-                                    discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+                                if hasattr(socket, "SO_REUSEPORT"): discovery_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
                                 discovery_socket.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_MULTICAST_IF, if_struct)
 
                                 # Join multicast group
                                 mcast_group = socket.inet_pton(socket.AF_INET6, mcast_addr) + if_struct
                                 discovery_socket.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_JOIN_GROUP, mcast_group)
 
-                                # Bind socket
+                                # Bind multicast socket
                                 if RNS.vendor.platformutils.is_windows():
-
-                                    # window throws "[WinError 10049] The requested address is not valid in its context"
+                                    # Windows throws "[WinError 10049] The requested address is not valid in its context"
                                     # when trying to use the multicast address as host, or when providing interface index
                                     # passing an empty host appears to work, but probably not exactly how we want it to...
                                     discovery_socket.bind(('', self.discovery_port))
 
                                 else:
-
                                     if self.discovery_scope == AutoInterface.SCOPE_LINK:
                                         addr_info = socket.getaddrinfo(mcast_addr+"%"+ifname, self.discovery_port, socket.AF_INET6, socket.SOCK_DGRAM)
                                     else:
@@ -274,12 +296,13 @@ class AutoInterface(Interface):
 
                                     discovery_socket.bind(addr_info[0][4])
 
-                                # Set up thread for discovery packets
+                                # Set up thread for multicast discovery packets
                                 def discovery_loop(): self.discovery_handler(discovery_socket, ifname)
-
-                                thread = threading.Thread(target=discovery_loop)
-                                thread.daemon = True
-                                thread.start()
+                                thread = threading.Thread(target=discovery_loop, daemon=True).start()
+                                
+                                # Set up thread for unicast discovery packets
+                                def unicast_discovery_loop(): self.discovery_handler(unicast_discovery_socket, ifname, announce=False)
+                                thread = threading.Thread(target=unicast_discovery_loop, daemon=True).start()
 
                                 suitable_interfaces += 1
 
@@ -327,13 +350,13 @@ class AutoInterface(Interface):
         self.online = True
         self.final_init_done = True
 
-    def discovery_handler(self, socket, ifname):
-        def announce_loop():
-            self.announce_handler(ifname)
-            
-        thread = threading.Thread(target=announce_loop)
-        thread.daemon = True
-        thread.start()
+    def discovery_handler(self, socket, ifname, announce=True):
+        def announce_loop(): self.announce_handler(ifname)
+        
+        if announce:
+            thread = threading.Thread(target=announce_loop)
+            thread.daemon = True
+            thread.start()
         
         while True:
             data, ipv6_src = socket.recvfrom(1024)
@@ -367,6 +390,18 @@ class AutoInterface(Interface):
                     spawned_interface.teardown()
                 RNS.log(str(self)+" removed peer "+str(peer_addr)+" on "+str(removed_peer[0]), RNS.LOG_DEBUG)
 
+            # Send reverse peering packets
+            for peer_addr in self.peers:
+                try:
+                    peer = self.peers[peer_addr]
+                    ifname = peer[0]
+                    last_outbound = peer[2]
+                    if now > last_outbound+self.reverse_peering_interval:
+                        self.reverse_announce(ifname, peer_addr)
+                        peer[2] = time.time()
+                except Exception as e:
+                    RNS.log(f"Error while sending reverse peering packet to {peer_addr}: {e}", RNS.LOG_ERROR)
+
             for ifname in self.adopted_interfaces:
                 # Check that the link-local address has not changed
                 try:
@@ -412,9 +447,10 @@ class AutoInterface(Interface):
                     RNS.log("Could not get device information while updating link-local addresses for "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
                 # Check multicast echo timeouts
-                last_multicast_echo = 0
-                if ifname in self.multicast_echoes:
-                    last_multicast_echo = self.multicast_echoes[ifname]
+                last_multicast_echo     = 0
+                multicast_echo_received = False
+                if ifname in self.multicast_echoes: last_multicast_echo     = self.multicast_echoes[ifname]
+                if ifname in self.initial_echoes:   multicast_echo_received = True
 
                 if now - last_multicast_echo > self.multicast_echo_timeout:
                     if ifname in self.timed_out_interfaces and self.timed_out_interfaces[ifname] == False:
@@ -426,6 +462,11 @@ class AutoInterface(Interface):
                         self.carrier_changed = True
                         RNS.log(str(self)+" Carrier recovered on "+str(ifname), RNS.LOG_WARNING)
                     self.timed_out_interfaces[ifname] = False
+
+                if not multicast_echo_received:
+                    RNS.log(f"{self} No multicast echoes received on {ifname}. The networking hardware or a firewall may be blocking multicast traffic.", RNS.LOG_ERROR)
+                # else:
+                #     RNS.log(f"{self} Initial multicast echo on {ifname} received {RNS.prettytime(time.time()-self.initial_echoes[ifname])} ago.", RNS.LOG_DEBUG)
                 
 
     def announce_handler(self, ifname):
@@ -433,6 +474,20 @@ class AutoInterface(Interface):
             self.peer_announce(ifname)
             time.sleep(self.announce_interval)
             
+    def reverse_announce(self, ifname, peer_addr):
+        try:
+            link_local_address = self.adopted_interfaces[ifname]
+            discovery_token = RNS.Identity.full_hash(self.group_id+link_local_address.encode("utf-8"))
+            announce_socket = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
+            addr_info = socket.getaddrinfo(f"{peer_addr}%{ifname}", self.unicast_discovery_port, socket.AF_INET6, socket.SOCK_DGRAM)
+
+            ifis = struct.pack("I", self.interface_name_to_index(ifname))
+            announce_socket.sendto(discovery_token, addr_info[0][4])
+            announce_socket.close()
+            
+        except Exception as e:
+            RNS.log(f"Could not send reverse peering packet to {peer_addr} on {ifname}: {e}", RNS.LOG_ERROR)
+
     def peer_announce(self, ifname):
         try:
             link_local_address = self.adopted_interfaces[ifname]
@@ -464,16 +519,27 @@ class AutoInterface(Interface):
 
             if ifname != None:
                 self.multicast_echoes[ifname] = time.time()
+                if not ifname in self.initial_echoes: self.initial_echoes[ifname] = time.time()
             else:
                 RNS.log(str(self)+" received multicast echo on unexpected interface "+str(ifname), RNS.LOG_WARNING)
 
         else:
             if not addr in self.peers:
-                self.peers[addr] = [ifname, time.time()]
+                self.peers[addr] = [ifname, time.time(), time.time()]
 
                 spawned_interface = AutoInterfacePeer(self, addr, ifname)
                 spawned_interface.OUT = self.OUT
                 spawned_interface.IN  = self.IN
+
+                spawned_interface.ingress_control = self.ingress_control
+                spawned_interface.ic_max_held_announces = self.ic_max_held_announces
+                spawned_interface.ic_burst_hold = self.ic_burst_hold
+                spawned_interface.ic_burst_freq = self.ic_burst_freq
+                spawned_interface.ic_burst_freq_new = self.ic_burst_freq_new
+                spawned_interface.ic_new_time = self.ic_new_time
+                spawned_interface.ic_burst_penalty = self.ic_burst_penalty
+                spawned_interface.ic_held_release_interval = self.ic_held_release_interval
+                
                 spawned_interface.parent_interface = self
                 spawned_interface.bitrate = self.bitrate
                 
@@ -507,7 +573,7 @@ class AutoInterface(Interface):
                 if addr in self.spawned_interfaces:
                     self.spawned_interfaces[addr].detach()
                     self.spawned_interfaces[addr].teardown()
-                    self.spawned_interfaces.pop(spawned_interface)
+                    if addr in self.spawned_interfaces: self.spawned_interfaces.pop(addr)
                 self.spawned_interfaces[addr] = spawned_interface
 
                 RNS.log(str(self)+" added peer "+str(addr)+" on "+str(ifname), RNS.LOG_DEBUG)
@@ -515,28 +581,18 @@ class AutoInterface(Interface):
                 self.refresh_peer(addr)
 
     def refresh_peer(self, addr):
-        try:
-            self.peers[addr][1] = time.time()
-        except Exception as e:
-            RNS.log(f"An error occurred while refreshing peer {addr} on {self}: {e}", RNS.LOG_ERROR)
+        try: self.peers[addr][1] = time.time()
+        except Exception as e: RNS.log(f"An error occurred while refreshing peer {addr} on {self}: {e}", RNS.LOG_ERROR)
 
     def process_incoming(self, data, addr=None):
         if self.online and addr in self.spawned_interfaces:
             self.spawned_interfaces[addr].process_incoming(data, addr)
 
-    def process_outgoing(self,data):
-        pass
+    def process_outgoing(self, data): pass
 
-    # Until per-device sub-interfacing is implemented,
-    # ingress limiting should be disabled on AutoInterface
-    def should_ingress_limit(self):
-        return False
+    def detach(self): self.online = False
 
-    def detach(self):
-        self.online = False
-
-    def __str__(self):
-        return "AutoInterface["+self.name+"]"
+    def __str__(self): return f"AutoInterface[{self.name}]"
 
 class AutoInterfacePeer(Interface):
 
@@ -591,12 +647,10 @@ class AutoInterfacePeer(Interface):
         
     def teardown(self):
         if not self.detached:
-            RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down.", RNS.LOG_ERROR)
-            if RNS.Reticulum.panic_on_interface_error:
-                RNS.panic()
+            RNS.log(f"The interface {self} experienced an unrecoverable error and is being torn down.", RNS.LOG_ERROR)
+            if RNS.Reticulum.panic_on_interface_error: RNS.panic()
 
-        else:
-            RNS.log("The interface "+str(self)+" is being torn down.", RNS.LOG_VERBOSE)
+        else: RNS.log(f"The interface {self} is being torn down.", RNS.LOG_VERBOSE)
 
         self.online = False
         self.OUT = False
@@ -607,13 +661,7 @@ class AutoInterfacePeer(Interface):
             except Exception as e:
                 RNS.log(f"Could not remove {self} from parent interface on detach. The contained exception was: {e}", RNS.LOG_ERROR)
 
-        if self in RNS.Transport.interfaces:
-            RNS.Transport.interfaces.remove(self)
-
-    # Until per-device sub-interfacing is implemented,
-    # ingress limiting should be disabled on AutoInterface
-    def should_ingress_limit(self):
-        return False
+        if self in RNS.Transport.interfaces: RNS.Transport.interfaces.remove(self)
 
 class AutoInterfaceHandler(socketserver.BaseRequestHandler):
     def __init__(self, callback, *args, **keys):

RNS/Interfaces/BackboneInterface.py

@@ -127,6 +127,7 @@ class BackboneInterface(Interface):
         self.detached = False
         self.mode = RNS.Interfaces.Interface.Interface.MODE_FULL
         self.spawned_interfaces = []
+        self.supports_discovery = True
 
         if bindport == None:
             raise SystemError(f"No TCP port configured for interface \"{name}\"")
@@ -227,10 +228,10 @@ class BackboneInterface(Interface):
         if interface.socket:
             fileno = interface.socket.fileno()
             if fileno in BackboneInterface.spawned_interface_filenos:
-                try:
-                    BackboneInterface.epoll.modify(interface.socket.fileno(), select.EPOLLOUT)
+                try: BackboneInterface.epoll.modify(fileno, select.EPOLLOUT)
                 except Exception as e:
-                    RNS.trace_exception(e)
+                    RNS.log(f"Error occurred on {interface} while modifying socket EPOLL state: {e}", RNS.LOG_WARNING)
+                    raise e
 
     @staticmethod
     def __job():
@@ -269,8 +270,7 @@ class BackboneInterface(Interface):
                                         spawned_interface.receive(received_bytes)
                                 
                                 elif client_socket and fileno == client_socket.fileno() and (event & select.EPOLLOUT):
-                                    try:
-                                        written = client_socket.send(spawned_interface.transmit_buffer)
+                                    try: written = client_socket.send(spawned_interface.transmit_buffer)
                                     except Exception as e:
                                         written = 0
                                         if not spawned_interface.detached: RNS.log(f"Error while writing to {spawned_interface}: {e}", RNS.LOG_DEBUG)
@@ -292,7 +292,11 @@ class BackboneInterface(Interface):
                                         spawned_interface.receive(b"")
 
                                     spawned_interface.transmit_buffer = spawned_interface.transmit_buffer[written:]
-                                    if len(spawned_interface.transmit_buffer) == 0: BackboneInterface.epoll.modify(fileno, select.EPOLLIN)
+                                    try:
+                                        if len(spawned_interface.transmit_buffer) == 0: BackboneInterface.epoll.modify(fileno, select.EPOLLIN)
+                                    except Exception as e:
+                                        RNS.log(f"Error while setting EPOLLIN on {spawned_interface}: {e}", RNS.LOG_ERROR)
+
                                     spawned_interface.txb += written
                                     if spawned_interface.parent_interface: spawned_interface.parent_interface.txb += written
                                 
@@ -343,6 +347,16 @@ class BackboneInterface(Interface):
             spawned_interface = BackboneClientInterface(self.owner, spawned_configuration, connected_socket=socket)
             spawned_interface.OUT = self.OUT
             spawned_interface.IN  = self.IN
+
+            spawned_interface.ingress_control = self.ingress_control
+            spawned_interface.ic_max_held_announces = self.ic_max_held_announces
+            spawned_interface.ic_burst_hold = self.ic_burst_hold
+            spawned_interface.ic_burst_freq = self.ic_burst_freq
+            spawned_interface.ic_burst_freq_new = self.ic_burst_freq_new
+            spawned_interface.ic_new_time = self.ic_new_time
+            spawned_interface.ic_burst_penalty = self.ic_burst_penalty
+            spawned_interface.ic_held_release_interval = self.ic_held_release_interval
+            
             spawned_interface.socket = socket
             spawned_interface.target_ip = socket.getpeername()[0]
             spawned_interface.target_port = str(socket.getpeername()[1])
@@ -407,7 +421,9 @@ class BackboneInterface(Interface):
                 if hasattr(listener_socket, "shutdown"):
                     if callable(listener_socket.shutdown):
                         try: listener_socket.shutdown(socket.SHUT_RDWR)
-                        except Exception as e: RNS.log("Error while shutting down socket for "+str(self)+": "+str(e), RNS.LOG_ERROR)
+                        except Exception as e:
+                            if str(e).endswith("Transport endpoint is not connected"): pass
+                            else: RNS.log("Error while shutting down socket for "+str(self)+": "+str(e), RNS.LOG_ERROR)
 
     def __str__(self):
         if ":" in self.bind_ip:
@@ -522,7 +538,9 @@ class BackboneClientInterface(Interface):
                     
                     try:
                         if self.socket != None: self.socket.shutdown(socket.SHUT_RDWR)
-                    except Exception as e: RNS.log("Error while shutting down socket for "+str(self)+": "+str(e), RNS.LOG_ERROR)
+                    except Exception as e:
+                        if str(e).endswith("Transport endpoint is not connected"): pass
+                        else: RNS.log("Error while shutting down socket for "+str(self)+": "+str(e), RNS.LOG_ERROR)
 
                     try:
                         if self.socket != None: self.socket.close()
@@ -579,7 +597,7 @@ class BackboneClientInterface(Interface):
             if not self.reconnecting:
                 self.reconnecting = True
                 attempts = 0
-                while not self.online:
+                while not self.online and not self.detached:
                     time.sleep(BackboneClientInterface.RECONNECT_WAIT)
                     attempts += 1
 
@@ -592,6 +610,8 @@ class BackboneClientInterface(Interface):
                     except Exception as e:
                         RNS.log("Connection attempt for "+str(self)+" failed: "+str(e), RNS.LOG_DEBUG)
 
+                if not self.online: return
+
                 if not self.never_connected:
                     RNS.log("Reconnected socket for "+str(self)+".", RNS.LOG_INFO)
 

RNS/Interfaces/I2PInterface.py

@@ -880,6 +880,7 @@ class I2PInterface(Interface):
         self.ifac_size = ifac_size
         self.ifac_netname = ifac_netname
         self.ifac_netkey = ifac_netkey
+        self.supports_discovery = True
 
         self.online = False
 
@@ -947,6 +948,16 @@ class I2PInterface(Interface):
         spawned_interface = I2PInterfacePeer(self, self.owner, interface_name, connected_socket=handler.request)
         spawned_interface.OUT = True
         spawned_interface.IN  = True
+
+        spawned_interface.ingress_control = self.ingress_control
+        spawned_interface.ic_max_held_announces = self.ic_max_held_announces
+        spawned_interface.ic_burst_hold = self.ic_burst_hold
+        spawned_interface.ic_burst_freq = self.ic_burst_freq
+        spawned_interface.ic_burst_freq_new = self.ic_burst_freq_new
+        spawned_interface.ic_new_time = self.ic_new_time
+        spawned_interface.ic_burst_penalty = self.ic_burst_penalty
+        spawned_interface.ic_held_release_interval = self.ic_held_release_interval
+        
         spawned_interface.parent_interface = self
         spawned_interface.online = True
         spawned_interface.bitrate = self.bitrate

RNS/Interfaces/Interface.py

@@ -55,8 +55,8 @@ class Interface:
 
     # How many samples to use for announce
     # frequency calculations
-    IA_FREQ_SAMPLES     = 6
-    OA_FREQ_SAMPLES     = 6
+    IA_FREQ_SAMPLES     = 128
+    OA_FREQ_SAMPLES     = 128
 
     # Maximum amount of ingress limited announces
     # to hold at any given time.
@@ -66,11 +66,12 @@ class Interface:
     # considered to be newly created. Two
     # hours by default.
     IC_NEW_TIME              = 2*60*60
-    IC_BURST_FREQ_NEW        = 3.5
-    IC_BURST_FREQ            = 12
+    IC_BURST_FREQ_NEW        = 6
+    IC_BURST_FREQ            = 35
     IC_BURST_HOLD            = 1*60
-    IC_BURST_PENALTY         = 5*60
-    IC_HELD_RELEASE_INTERVAL = 30
+    IC_BURST_PENALTY         = 15
+    IC_HELD_RELEASE_INTERVAL = 2
+    IC_DEQUE_MIN_SAMPLE      = 32
 
     AUTOCONFIGURE_MTU = False
     FIXED_MTU         = False
@@ -84,10 +85,15 @@ class Interface:
         self.bitrate  = 62500
         self.HW_MTU   = None
 
+        self.supports_discovery = False
+        self.discoverable = False
+        self.last_discovery_announce = 0
+        self.bootstrap_only = False
         self.parent_interface = None
         self.spawned_interfaces = None
         self.tunnel_id = None
         self.ingress_control = True
+        self.phy_keepalive = False
         self.ic_max_held_announces = Interface.MAX_HELD_ANNOUNCES
         self.ic_burst_hold = Interface.IC_BURST_HOLD
         self.ic_burst_active = False
@@ -118,20 +124,19 @@ class Interface:
             if self.ic_burst_active:
                 if ia_freq < freq_threshold and time.time() > self.ic_burst_activated+self.ic_burst_hold:
                     self.ic_burst_active = False
-                    self.ic_held_release = time.time() + self.ic_burst_penalty
+
                 return True
 
             else:
                 if ia_freq > freq_threshold:
                     self.ic_burst_active = True
                     self.ic_burst_activated = time.time()
+                    self.ic_held_release = time.time() + self.ic_burst_penalty
                     return True
 
-                else:
-                    return False
+                else: return False
 
-        else:
-            return False
+        else: return False
 
     def optimise_mtu(self):
         if self.AUTOCONFIGURE_MTU:
@@ -171,7 +176,7 @@ class Interface:
 
     def process_held_announces(self):
         try:
-            if not self.should_ingress_limit() and len(self.held_announces) > 0 and time.time() > self.ic_held_release:
+            if len(self.held_announces) > 0 and time.time() > self.ic_held_release:
                 freq_threshold = self.ic_burst_freq_new if self.age() < self.ic_new_time else self.ic_burst_freq
                 ia_freq = self.incoming_announce_frequency()
                 if ia_freq < freq_threshold:
@@ -187,8 +192,7 @@ class Interface:
                         RNS.log("Releasing held announce packet "+str(selected_announce_packet)+" from "+str(self), RNS.LOG_EXTREME)
                         self.ic_held_release = time.time() + self.ic_held_release_interval
                         self.held_announces.pop(selected_announce_packet.destination_hash)
-                        def release():
-                            RNS.Transport.inbound(selected_announce_packet.raw, selected_announce_packet.receiving_interface)
+                        def release(): RNS.Transport.inbound(selected_announce_packet.raw, selected_announce_packet.receiving_interface)
                         threading.Thread(target=release, daemon=True).start()
         
         except Exception as e:
@@ -206,38 +210,24 @@ class Interface:
             self.parent_interface.sent_announce(from_spawned=True)
 
     def incoming_announce_frequency(self):
-        if not len(self.ia_freq_deque) > 1:
-            return 0
+        n = len(self.ia_freq_deque)
+        if not n > self.IC_DEQUE_MIN_SAMPLE: return 0
         else:
-            dq_len = len(self.ia_freq_deque)
-            delta_sum = 0
-            for i in range(1,dq_len):
-                delta_sum += self.ia_freq_deque[i]-self.ia_freq_deque[i-1]
-            delta_sum += time.time() - self.ia_freq_deque[dq_len-1]
-            
-            if delta_sum == 0:
-                avg = 0
-            else:
-                avg = 1/(delta_sum/(dq_len))
-
-            return avg
+            oldest = self.ia_freq_deque[0]
+            span = time.time() - oldest
+            if span <= 0: return 0
+            hz = n / span
+            return hz
 
     def outgoing_announce_frequency(self):
-        if not len(self.oa_freq_deque) > 1:
-            return 0
+        n = len(self.oa_freq_deque)
+        if not len(self.oa_freq_deque) > 1: return 0
         else:
-            dq_len = len(self.oa_freq_deque)
-            delta_sum = 0
-            for i in range(1,dq_len):
-                delta_sum += self.oa_freq_deque[i]-self.oa_freq_deque[i-1]
-            delta_sum += time.time() - self.oa_freq_deque[dq_len-1]
-            
-            if delta_sum == 0:
-                avg = 0
-            else:
-                avg = 1/(delta_sum/(dq_len))
-
-            return avg
+            oldest = self.oa_freq_deque[0]
+            span   = time.time() - oldest
+            if span <= 0: return 0
+            hz = n / span
+            return hz
 
     def process_announce_queue(self):
         if not hasattr(self, "announce_cap"):

RNS/Interfaces/LocalInterface.py

@@ -62,6 +62,7 @@ class ThreadingTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
 class LocalClientInterface(Interface):
     RECONNECT_WAIT = 8
     AUTOCONFIGURE_MTU = True
+    CLIENT_SLEEP_PAUSE_TIMEOUT = 12
 
     def __init__(self, owner, name, target_port = None, connected_socket=None, socket_path=None):
         super().__init__()
@@ -85,8 +86,9 @@ class LocalClientInterface(Interface):
         self.frame_buffer     = b""
         self.transmit_buffer  = b""
 
-        if RNS.vendor.platformutils.use_epoll():
-            self.epoll_backend = True
+        if RNS.vendor.platformutils.use_epoll(): self.epoll_backend = True
+
+        self.pause_on_client_sleep = False
 
         if connected_socket != None:
             self.receives    = True
@@ -99,6 +101,10 @@ class LocalClientInterface(Interface):
 
             self.is_connected_to_shared_instance = False
 
+            if RNS.vendor.platformutils.is_android():
+                self.pause_on_client_sleep = True
+                self.pause_timeout = time.time() + self.CLIENT_SLEEP_PAUSE_TIMEOUT
+
         elif self.socket_path != None:
             self.receives    = True
             self.target_ip   = None
@@ -145,6 +151,7 @@ class LocalClientInterface(Interface):
         self.is_connected_to_shared_instance = True
         self.never_connected = False
 
+        if RNS.vendor.platformutils.is_android(): self.phy_keepalive = True
         if self.epoll_backend: BackboneInterface.add_client_socket(self.socket, self)
 
         return True
@@ -185,17 +192,36 @@ class LocalClientInterface(Interface):
             raise IOError("Attempt to reconnect on a non-initiator local interface")
 
 
+    def send_keepalive(self):
+        if self.online:
+            RNS.log(f"Sending keepalive on {self}", RNS.LOG_DEBUG) # TODO: Remove
+            try:
+                if self.epoll_backend:
+                    self.transmit_buffer += bytes([HDLC.FLAG])+bytes([HDLC.FLAG])
+                    BackboneInterface.tx_ready(self)
+
+                else:
+                    self.writing = True
+                    data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
+                    self.socket.sendall(data)
+                    self.writing = False
+
+            except Exception as e: RNS.log(f"Exception occurred while sending keepalive on {self}: {e}", RNS.LOG_ERROR)
+
     def process_incoming(self, data):
         self.rxb += len(data)
         if self.parent_interface != None: self.parent_interface.rxb += len(data)
         
-        try:
-            self.owner.inbound(data, self)
+        try: self.owner.inbound(data, self)
         except Exception as e:
-            RNS.log(f"An error in the processing of an incoming frame for {self}: {e}", RNS.LOG_ERROR)
+            RNS.log(f"An error occurred in the processing of an incoming frame for {self}: {e}", RNS.LOG_ERROR)
             RNS.trace_exception(e)
 
     def process_outgoing(self, data):
+        if self.pause_on_client_sleep and time.time() > self.pause_timeout:
+            RNS.log(f"TX paused for LocalInterface client, dropping outbound packet", RNS.LOG_DEBUG) # TODO: Remove
+            return
+
         if self.online:
             try:
                 if self.epoll_backend:
@@ -238,13 +264,12 @@ class LocalClientInterface(Interface):
                     frame = self.frame_buffer[frame_start+1:frame_end]
                     frame = frame.replace(bytes([HDLC.ESC, HDLC.FLAG ^ HDLC.ESC_MASK]), bytes([HDLC.FLAG]))
                     frame = frame.replace(bytes([HDLC.ESC, HDLC.ESC  ^ HDLC.ESC_MASK]), bytes([HDLC.ESC]))
-                    if len(frame) > RNS.Reticulum.HEADER_MINSIZE:
-                        self.process_incoming(frame)
+                    if len(frame) > RNS.Reticulum.HEADER_MINSIZE: self.process_incoming(frame)
                     self.frame_buffer = self.frame_buffer[frame_end:]
-                else:
-                    flags_remaining = False
-            else:
-                flags_remaining = False
+                
+                else: flags_remaining = False
+            
+            else: flags_remaining = False
 
     def receive(self, data_in):
         try:
@@ -267,6 +292,8 @@ class LocalClientInterface(Interface):
             RNS.log("Tearing down "+str(self), RNS.LOG_ERROR)
             self.teardown()
 
+        if self.pause_on_client_sleep: self.pause_timeout = time.time() + self.CLIENT_SLEEP_PAUSE_TIMEOUT
+
     def read_loop(self):
         try:
             self.frame_buffer = b""
@@ -328,7 +355,8 @@ class LocalClientInterface(Interface):
             if hasattr(self, "parent_interface") and self.parent_interface != None:
                 self.parent_interface.clients -= 1
                 if hasattr(RNS.Transport, "owner") and RNS.Transport.owner != None:
-                    RNS.Transport.owner._should_persist_data()
+                    background = not self.detached
+                    RNS.Transport.owner._should_persist_data(background=background)
 
         if nowarning == False:
             RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down. Restart Reticulum to attempt to open this interface again.", RNS.LOG_ERROR)

RNS/Interfaces/RNodeInterface.py

@@ -32,6 +32,7 @@ from RNS.Interfaces.Interface import Interface
 from time import sleep
 import sys
 import threading
+import socket
 import time
 import math
 import RNS
@@ -64,6 +65,7 @@ class KISS():
     CMD_STAT_PHYPRM = 0x26
     CMD_STAT_BAT    = 0x27
     CMD_STAT_CSMA   = 0x28
+    CMD_STAT_TEMP   = 0x29
     CMD_BLINK       = 0x30
     CMD_RANDOM      = 0x40
     CMD_FB_EXT      = 0x41
@@ -158,8 +160,11 @@ class RNodeInterface(Interface):
         lt_alock     = float(c["airtime_limit_long"]) if "airtime_limit_long" in c else None
 
         force_ble = False
-        ble_name = None
-        ble_addr = None
+        ble_name  = None
+        ble_addr  = None
+
+        force_tcp = False
+        tcp_host  = None
 
         port = c["port"] if "port" in c else None
 
@@ -167,6 +172,7 @@ class RNodeInterface(Interface):
             raise ValueError("No port specified for RNode interface")
 
         if port != None:
+            tcp_uri_scheme = "tcp://"
             ble_uri_scheme = "ble://"
             if port.lower().startswith(ble_uri_scheme):
                 force_ble = True
@@ -179,6 +185,13 @@ class RNodeInterface(Interface):
                 else:
                     ble_name = ble_string
 
+            elif port.lower().startswith(tcp_uri_scheme):
+                force_tcp = True
+                tcp_string = port[len(tcp_uri_scheme):]
+                port = None
+                if len(tcp_string) == 0: pass
+                else: tcp_host = tcp_string
+
         self.HW_MTU = 508
         
         self.pyserial    = serial
@@ -195,6 +208,14 @@ class RNodeInterface(Interface):
         self.reconnecting= False
         self.hw_errors   = []
 
+        self.use_tcp     = False
+        self.tcp         = None
+        self.tcp_host    = tcp_host
+        self.tcp_rx_queue= b""
+        self.tcp_tx_queue= b""
+        self.tcp_rx_lock = threading.Lock()
+        self.tcp_tx_lock = threading.Lock()
+
         self.use_ble     = False
         self.ble_name    = ble_name
         self.ble_addr    = ble_addr
@@ -213,6 +234,7 @@ class RNodeInterface(Interface):
         self.bitrate     = 0
         self.st_alock    = st_alock
         self.lt_alock    = lt_alock
+        self.cpu_temp    = None
         self.platform    = None
         self.display     = None
         self.mcu         = None
@@ -254,9 +276,12 @@ class RNodeInterface(Interface):
         self.r_csma_cw_max        = None
         self.r_current_rssi       = None
         self.r_noise_floor        = None
+        self.r_interference       = None
+        self.r_interference_l     = None
 
         self.r_battery_state = RNodeInterface.BATTERY_STATE_UNKNOWN
         self.r_battery_percent = 0
+        self.r_temperature = None
         self.r_framebuffer = b""
         self.r_framebuffer_readtime = 0
         self.r_framebuffer_latency = 0
@@ -271,16 +296,17 @@ class RNodeInterface(Interface):
         self.flow_control    = flow_control
         self.interface_ready = False
         self.announce_rate_target = None
+        self.supports_discovery = True
 
-        if force_ble or self.ble_addr != None or self.ble_name != None:
-            self.use_ble = True
+        if force_ble or self.ble_addr != None or self.ble_name != None: self.use_ble = True
+        if force_tcp or self.tcp_host != None:                          self.use_tcp = True
 
         self.validcfg  = True
         if (self.frequency < RNodeInterface.FREQ_MIN or self.frequency > RNodeInterface.FREQ_MAX):
             RNS.log("Invalid frequency configured for "+str(self), RNS.LOG_ERROR)
             self.validcfg = False
 
-        if (self.txpower < 0 or self.txpower > 22):
+        if (self.txpower < 0 or self.txpower > 37):
             RNS.log("Invalid TX power configured for "+str(self), RNS.LOG_ERROR)
             self.validcfg = False
 
@@ -322,10 +348,8 @@ class RNodeInterface(Interface):
         try:
             self.open_port()
 
-            if self.serial.is_open:
-                self.configure_device()
-            else:
-                raise IOError("Could not open serial port")
+            if self.serial.is_open: self.configure_device()
+            else: raise IOError("Could not open serial port")
 
         except Exception as e:
             RNS.log("Could not open serial port for interface "+str(self), RNS.LOG_ERROR)
@@ -338,8 +362,8 @@ class RNodeInterface(Interface):
 
 
     def open_port(self):
-        if not self.use_ble:
-            RNS.log("Opening serial port "+self.port+"...")
+        if not self.use_ble and not self.use_tcp:
+            RNS.log(f"Opening serial port {self.port}...")
             self.serial = self.pyserial.Serial(
                 port = self.port,
                 baudrate = self.speed,
@@ -355,19 +379,37 @@ class RNodeInterface(Interface):
             )
         
         else:
-            RNS.log(f"Opening BLE connection for {self}...")
-            if self.ble != None and self.ble.running == False:
-                self.ble.close()
-                self.ble.cleanup()
-                self.ble = None
+            if self.use_ble:
+                RNS.log(f"Opening BLE connection for {self}...")
+                self.timeout = 1250
+                if self.ble != None and self.ble.running == False:
+                    self.ble.close()
+                    self.ble.cleanup()
+                    self.ble = None
 
-            if self.ble == None:
-                self.ble = BLEConnection(owner=self, target_name=self.ble_name, target_bt_addr=self.ble_addr)
-                self.serial = self.ble
+                if self.ble == None:
+                    self.ble = BLEConnection(owner=self, target_name=self.ble_name, target_bt_addr=self.ble_addr)
+                    self.serial = self.ble
 
-            open_time = time.time()
-            while not self.ble.connected and time.time() < open_time + self.ble.CONNECT_TIMEOUT:
-                time.sleep(1)
+                open_time = time.time()
+                while not self.ble.connected and time.time() < open_time + self.ble.CONNECT_TIMEOUT:
+                    time.sleep(1)
+
+            if self.use_tcp:
+                self.timeout = 1500
+                RNS.log(f"Opening TCP connection for {self}...")
+                if self.tcp != None and self.tcp.running == False:
+                    self.tcp.close()
+                    self.tcp.cleanup()
+                    self.tcp = None
+
+                if self.tcp == None:
+                    self.tcp = TCPConnection(owner=self, target_host=self.tcp_host)
+                    self.serial = self.tcp
+
+                open_time = time.time()
+                while not self.tcp.connected and time.time() < open_time + self.tcp.CONNECT_TIMEOUT:
+                    time.sleep(1)
 
     def reset_radio_state(self):
         self.r_frequency = None
@@ -388,38 +430,41 @@ class RNodeInterface(Interface):
         thread.start()
 
         self.detect()
-        if not self.use_ble:
-            sleep(0.2)
-        else:
-            ble_detect_timeout = 5
+        if self.use_tcp:
+            tcp_detect_timeout = 5.0
             detect_time = time.time()
-            while not self.detected and time.time() < detect_time + ble_detect_timeout:
-                time.sleep(0.1)
-            if self.detected:
-                detect_time = RNS.prettytime(time.time()-detect_time)
-            else:
-                RNS.log(f"RNode detect timed out over {self.port}", RNS.LOG_ERROR)
+            while not self.detected and time.time() < detect_time + tcp_detect_timeout: time.sleep(0.1)
+            if not self.detected: RNS.log(f"RNode detect timed out over TCP", RNS.LOG_ERROR)
+        elif self.use_ble:
+            ble_detect_timeout = 5.0
+            detect_time = time.time()
+            while not self.detected and time.time() < detect_time + ble_detect_timeout: time.sleep(0.1)
+            if not self.detected: RNS.log(f"RNode detect timed out over BLE", RNS.LOG_ERROR)
+        else:
+            sleep(0.2)
         
         if not self.detected:
-            RNS.log("Could not detect device for "+str(self), RNS.LOG_ERROR)
+            RNS.log(f"Could not detect device for {self}", RNS.LOG_ERROR)
             self.serial.close()
+            
         else:
-            if self.platform == KISS.PLATFORM_ESP32 or self.platform == KISS.PLATFORM_NRF52:
-                self.display = True
+            if self.platform == KISS.PLATFORM_ESP32 or self.platform == KISS.PLATFORM_NRF52: self.display = True
 
-        RNS.log("Serial port "+self.port+" is now open")
-        RNS.log("Configuring RNode interface...", RNS.LOG_VERBOSE)
-        self.initRadio()
-        if (self.validateRadioState()):
-            self.interface_ready = True
-            RNS.log(str(self)+" is configured and powered up")
-            sleep(0.3)
-            self.online = True
-        else:
-            RNS.log("After configuring "+str(self)+", the reported radio parameters did not match your configuration.", RNS.LOG_ERROR)
-            RNS.log("Make sure that your hardware actually supports the parameters specified in the configuration", RNS.LOG_ERROR)
-            RNS.log("Aborting RNode startup", RNS.LOG_ERROR)
-            self.serial.close()
+            if   self.use_tcp: RNS.log(f"TCP connection to {self.tcp_host} is now open", RNS.LOG_VERBOSE)
+            elif self.use_ble: RNS.log(f"BLE connection to {self} is now open", RNS.LOG_VERBOSE)
+            else:              RNS.log(f"Serial port {self.port} is now open", RNS.LOG_VERBOSE)
+            RNS.log("Configuring RNode interface...", RNS.LOG_VERBOSE)
+            self.initRadio()
+            if (self.validateRadioState()):
+                self.interface_ready = True
+                RNS.log(str(self)+" is configured and powered up")
+                sleep(0.3)
+                self.online = True
+            else:
+                RNS.log("After configuring "+str(self)+", the reported radio parameters did not match your configuration.", RNS.LOG_ERROR)
+                RNS.log("Make sure that your hardware actually supports the parameters specified in the configuration", RNS.LOG_ERROR)
+                RNS.log("Aborting RNode startup", RNS.LOG_ERROR)
+                self.serial.close()
             
 
     def initRadio(self):
@@ -614,10 +659,9 @@ class RNodeInterface(Interface):
 
     def validateRadioState(self):
         RNS.log("Waiting for radio configuration validation for "+str(self)+"...", RNS.LOG_VERBOSE)
-        if self.use_ble:
-            sleep(1.00)
-        else:
-            sleep(0.25)
+        if self.use_ble: sleep(1.00)
+        elif self.use_tcp: sleep(1.5)
+        else: sleep(0.25)
 
         if self.use_ble and self.ble != None and self.ble.device_disappeared:
             RNS.log(f"Device disappeared during radio state validation for {self}", RNS.LOG_ERROR)
@@ -902,16 +946,35 @@ class RNodeInterface(Interface):
                                     self.r_channel_load_long  = cul/100.0
                                     self.r_current_rssi       = crs-RNodeInterface.RSSI_OFFSET
                                     self.r_noise_floor        = nfl-RNodeInterface.RSSI_OFFSET
+
+                                    # TODO: Remove debug
+                                    # interference_log_threshold = 10
+                                    # if ntf == 0xFF:
+                                    #     self.r_interference   = None
+                                    #     if self.r_noise_floor != None:
+                                    #         # Filter potential false interference events due to LNA recalibration
+                                    #         if self.r_interference_l != None:
+                                    #             if self.r_interference_l[1] < self.r_noise_floor+interference_log_threshold:
+                                    #                 self.r_interference_l = None
+                                    # else:
+                                    #     if self.r_noise_floor != None:
+                                    #         interference   = ntf-RNodeInterface.RSSI_OFFSET
+                                    #         # Filter potential false interference events due to LNA recalibration
+                                    #         if interference > self.r_noise_floor+interference_log_threshold:
+                                    #             self.r_interference   = ntf-RNodeInterface.RSSI_OFFSET
+                                    #             self.r_interference_l = [time.time(), self.r_interference]
+
                                     if ntf == 0xFF:
                                         self.r_interference   = None
                                     else:
                                         self.r_interference   = ntf-RNodeInterface.RSSI_OFFSET
+                                        self.r_interference_l = [time.time(), self.r_interference]
                                     
                                     if self.r_interference != None:
                                         RNS.log(f"{self} Radio detected interference at {self.r_interference} dBm", RNS.LOG_DEBUG)
 
                                     # TODO: Remove debug
-                                    # RNS.log(f"RSSI: {self.r_current_rssi}, Noise floor: {self.r_noise_floor}, Interference: {self.r_interference}", RNS.LOG_EXTREME)
+                                    # RNS.log(f"RSSI: {self.r_current_rssi}, Noise floor: {self.r_noise_floor}, Interference: {self.r_interference}", RNS.LOG_DEBUG)
                         elif (command == KISS.CMD_STAT_PHYPRM):
                             if (byte == KISS.FESC):
                                 escape = True
@@ -985,6 +1048,22 @@ class RNodeInterface(Interface):
                                         bat_percent = 0
                                     self.r_battery_state   = command_buffer[0]
                                     self.r_battery_percent = bat_percent
+                        elif (command == KISS.CMD_STAT_TEMP):
+                            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) == 1):
+                                    temp = command_buffer[0]-120
+                                    if temp >= -30 and temp <= 90: self.r_temperature = temp
+                                    else:                          self.r_temperature = None
+                                    self.cpu_temp = self.r_temperature
                         elif (command == KISS.CMD_RANDOM):
                             self.r_random = byte
                         elif (command == KISS.CMD_PLATFORM):
@@ -1054,7 +1133,7 @@ class RNodeInterface(Interface):
                 else:
                     time_since_last = int(time.time()*1000) - last_read_ms
                     if len(data_buffer) > 0 and time_since_last > self.timeout:
-                        RNS.log(str(self)+" serial read timeout in command "+str(command), RNS.LOG_WARNING)
+                        RNS.log(f"{self} device read timeout in command {command} after {RNS.prettytime(self.timeout/1000.0)}", RNS.LOG_WARNING)
                         data_buffer = b""
                         in_frame = False
                         command = KISS.CMD_UNKNOWN
@@ -1066,6 +1145,11 @@ class RNodeInterface(Interface):
                                 RNS.log("Interface "+str(self)+" is transmitting beacon data: "+str(self.id_callsign.decode("utf-8")), RNS.LOG_DEBUG)
                                 self.process_outgoing(self.id_callsign)
 
+                    if self.use_tcp:
+                        if self.tcp and self.tcp.connected:
+                            if time.time() > self.tcp.last_write + self.tcp.ACTIVITY_KEEPALIVE:
+                                self.detect()
+
                     sleep(0.08)
 
         except Exception as e:
@@ -1094,23 +1178,28 @@ class RNodeInterface(Interface):
                 time.sleep(5)
                 RNS.log("Attempting to reconnect serial port "+str(self.port)+" for "+str(self)+"...", RNS.LOG_VERBOSE)
                 self.open_port()
-                if self.serial.is_open:
-                    self.configure_device()
+                if self.serial.is_open: self.configure_device()
+            
             except Exception as e:
                 RNS.log("Error while reconnecting port, the contained exception was: "+str(e), RNS.LOG_ERROR)
 
         self.reconnecting = False
-        if self.online:
-            RNS.log("Reconnected serial port for "+str(self))
+        if self.online: RNS.log(f"Reconnected port for {self}")
 
     def detach(self):
         self.detached = True
-        self.disable_external_framebuffer()
-        self.setRadioState(KISS.RADIO_STATE_OFF)
-        self.leave()
+        try:
+            self.disable_external_framebuffer()
+            self.setRadioState(KISS.RADIO_STATE_OFF)
+            self.leave()
+
+        except Exception as e:
+            RNS.log(f"An error occurred while detaching {self}: {e}", RNS.LOG_ERROR)
         
-        if self.use_ble:
-            self.ble.close()
+        if self.use_ble: self.ble.close()
+        if self.use_tcp:
+            time.sleep(0.5)
+            self.tcp.close()
 
     def should_ingress_limit(self):
         return False
@@ -1131,6 +1220,17 @@ class RNodeInterface(Interface):
     def get_battery_percent(self):
         return self.r_battery_percent
 
+    def tcp_receive(self, data):
+        with self.tcp_rx_lock: self.tcp_rx_queue += data
+
+    def tcp_waiting(self): return len(self.tcp_tx_queue) > 0
+
+    def get_tcp_waiting(self, n):
+        with self.tcp_tx_lock:
+            data = self.tcp_tx_queue[:n]
+            self.tcp_tx_queue = self.tcp_tx_queue[n:]
+            return data
+
     def ble_receive(self, data):
         with self.ble_rx_lock:
             self.ble_rx_queue += data
@@ -1145,7 +1245,7 @@ class RNodeInterface(Interface):
             return data
 
     def __str__(self):
-        return "RNodeInterface["+str(self.name)+"]"
+        return f"RNodeInterface[{self.name}]"
 
 class BLEConnection():
     UART_SERVICE_UUID = "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"
@@ -1324,3 +1424,136 @@ class BLEConnection():
             RNS.log(f"Error while determining device bond status for {device}, the contained exception was: {e}", RNS.LOG_ERROR)
 
         return False
+
+class TCPConnection():
+    TARGET_PORT = 7633
+    CONNECT_TIMEOUT = 5.0
+    INITIAL_CONNECT_TIMEOUT = 5.0
+    RECONNECT_WAIT = 4.0
+    ACTIVITY_TIMEOUT = 6.0
+    ACTIVITY_KEEPALIVE = ACTIVITY_TIMEOUT-2.5
+
+    TCP_USER_TIMEOUT = 24
+    TCP_PROBE_AFTER = 5
+    TCP_PROBE_INTERVAL = 2
+    TCP_PROBES = 12
+
+    @property
+    def is_open(self):
+        return self.connected
+
+    @property
+    def in_waiting(self):
+        buflen = len(self.owner.tcp_rx_queue)
+        return buflen > 0
+
+    def write(self, data_bytes):
+        if self.connected and self.socket:
+            with self.owner.tcp_tx_lock:
+                if len(self.owner.tcp_tx_queue) > 0:
+                    self.socket.sendall(self.owner.tcp_tx_queue)
+                    self.owner.tcp_tx_queue = b""
+
+            self.socket.sendall(data_bytes)
+            self.last_write = time.time()
+
+        else:
+            with self.owner.tcp_tx_lock: self.owner.tcp_tx_queue += data_bytes
+
+        return len(data_bytes)
+
+    def read(self, n):
+        with self.owner.tcp_rx_lock:
+            data = self.owner.tcp_rx_queue[:n]
+            self.owner.tcp_rx_queue = self.owner.tcp_rx_queue[n:]
+            return data
+
+    def close(self):
+        if self.connected:
+            RNS.log(f"Disconnecting TCP socket for {self.owner}", RNS.LOG_DEBUG)
+            self.must_disconnect = True
+            if self.socket: self.socket.close()
+
+    def __init__(self, owner=None, target_host=None):
+        self.owner = owner
+        self.target_host = target_host
+        self.connected = False
+        self.reconnecting = False
+        self.running = False
+        self.should_run = False
+        self.must_disconnect = False
+        self.connect_job_running = False
+        self.last_write = time.time()
+
+        self.should_run = True
+        self.connection_thread = threading.Thread(target=self.initial_connect, daemon=True).start()
+
+    def set_timeouts_linux(self):
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_USER_TIMEOUT, int(self.TCP_USER_TIMEOUT * 1000))
+        self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, int(self.TCP_PROBE_AFTER))
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, int(self.TCP_PROBE_INTERVAL))
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, int(self.TCP_PROBES))
+
+    def set_timeouts_osx(self):
+        if hasattr(socket, "TCP_KEEPALIVE"): TCP_KEEPIDLE = socket.TCP_KEEPALIVE
+        else: TCP_KEEPIDLE = 0x10
+        self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+        self.socket.setsockopt(socket.IPPROTO_TCP, TCP_KEEPIDLE, int(self.TCP_PROBE_AFTER))
+
+    def cleanup(self):
+        try:
+            if self.socket: self.socket.close()
+        except Exception as e: RNS.log(f"Error while disconnecting TCP socket on cleanup for {self.owner}", RNS.LOG_ERROR)
+        self.should_run = False
+
+    def initial_connect(self):
+        if self.connect(initial=True): threading.Thread(target=self.read_loop, daemon=True).start()
+
+    def connect(self, initial=False):
+        try:
+            if initial:
+                RNS.log(f"Establishing TCP connection to device for {self.owner}...", RNS.LOG_DEBUG)
+
+            address_info = socket.getaddrinfo(self.target_host, self.TARGET_PORT, proto=socket.IPPROTO_TCP)[0]
+            address_family = address_info[0]
+            target_address = address_info[4]
+
+            self.socket = socket.socket(address_family, socket.SOCK_STREAM)
+            self.socket.settimeout(self.INITIAL_CONNECT_TIMEOUT)
+            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+            self.socket.connect(target_address)
+            self.socket.settimeout(None)
+            self.connected  = True
+            self.last_write = time.time()
+
+            RNS.log(f"TCP connection to device for {self.owner} established", RNS.LOG_DEBUG)
+
+            if RNS.vendor.platformutils.is_linux():    self.set_timeouts_linux()
+            elif RNS.vendor.platformutils.is_darwin(): self.set_timeouts_osx()
+
+            return True
+        
+        except Exception as e:
+            if initial:
+                RNS.log(f"TCP connection to device for {self.owner} could not be established: {e}", RNS.LOG_ERROR)
+                return False
+            
+            else: raise e
+
+    def read_loop(self):
+        try:
+            data_in = b""
+            while not self.must_disconnect:
+                if self.socket: data_in = self.socket.recv(4096)
+                else: data_in = b""
+
+                if len(data_in) > 0: self.owner.tcp_receive(data_in)
+                else:
+                    self.connected = False
+                    RNS.log(f"The TCP socket for {self} was closed", RNS.LOG_WARNING)
+                    break
+
+        except Exception as e:
+            self.connected = False
+            RNS.log(f"A TCP read error occurred for {self}, the contained exception was: {e}", RNS.LOG_WARNING)

RNS/Interfaces/RNodeMultiInterface.py

@@ -74,7 +74,7 @@ class KISS():
     CMD_FW_VERSION  = 0x50
     CMD_ROM_READ    = 0x51
     CMD_RESET       = 0x55
-    CMD_INTERFACES  = 0x64
+    CMD_INTERFACES  = 0x71
 
     CMD_INT0_DATA   = 0x00
     CMD_INT1_DATA   = 0x10
@@ -1012,7 +1012,7 @@ class RNodeSubInterface(Interface):
             RNS.log("Invalid interface type configured for "+str(self), RNS.LOG_ERROR)
             self.validcfg = False
 
-        if (self.txpower < -9 or self.txpower > 27):
+        if (self.txpower < -9 or self.txpower > 37):
             RNS.log("Invalid TX power configured for "+str(self), RNS.LOG_ERROR)
             self.validcfg = False
 

RNS/Interfaces/TCPInterface.py

@@ -107,8 +107,13 @@ class TCPClientInterface(Interface):
         i2p_tunneled = c.as_bool("i2p_tunneled") if "i2p_tunneled" in c else False
         connect_timeout = c.as_int("connect_timeout") if "connect_timeout" in c else None
         max_reconnect_tries = c.as_int("max_reconnect_tries") if "max_reconnect_tries" in c else None
+        fixed_mtu = c.as_int("fixed_mtu") if "fixed_mtu" in c else None
+        if fixed_mtu:
+            if fixed_mtu < RNS.Reticulum.MTU: raise ValueError(f"Configured MTU of {fixed_mtu} bytes is too small")
+            self.AUTOCONFIGURE_MTU = False
+            self.FIXED_MTU = True
         
-        self.HW_MTU           = TCPInterface.HW_MTU
+        self.HW_MTU           = TCPInterface.HW_MTU if not fixed_mtu else fixed_mtu
         self.IN               = True
         self.OUT              = False
         self.socket           = None
@@ -126,10 +131,9 @@ class TCPClientInterface(Interface):
         self.mode             = RNS.Interfaces.Interface.Interface.MODE_FULL
         self.bitrate          = TCPClientInterface.BITRATE_GUESS
         
-        if max_reconnect_tries == None:
-            self.max_reconnect_tries = TCPClientInterface.RECONNECT_MAX_TRIES
-        else:
-            self.max_reconnect_tries = max_reconnect_tries
+        self.supports_discovery = True
+        if max_reconnect_tries == None: self.max_reconnect_tries = TCPClientInterface.RECONNECT_MAX_TRIES
+        else: self.max_reconnect_tries = max_reconnect_tries
 
         if connected_socket != None:
             self.receives    = True
@@ -508,6 +512,7 @@ class TCPServerInterface(Interface):
         if port != None:
             bindport = port
 
+        self.supports_discovery = True
         self.HW_MTU = TCPInterface.HW_MTU
 
         self.online = False
@@ -574,6 +579,16 @@ class TCPServerInterface(Interface):
         spawned_interface = TCPClientInterface(self.owner, spawned_configuration, connected_socket=handler.request)
         spawned_interface.OUT = self.OUT
         spawned_interface.IN  = self.IN
+        
+        spawned_interface.ingress_control = self.ingress_control
+        spawned_interface.ic_max_held_announces = self.ic_max_held_announces
+        spawned_interface.ic_burst_hold = self.ic_burst_hold
+        spawned_interface.ic_burst_freq = self.ic_burst_freq
+        spawned_interface.ic_burst_freq_new = self.ic_burst_freq_new
+        spawned_interface.ic_new_time = self.ic_new_time
+        spawned_interface.ic_burst_penalty = self.ic_burst_penalty
+        spawned_interface.ic_held_release_interval = self.ic_held_release_interval
+
         spawned_interface.target_ip = handler.client_address[0]
         spawned_interface.target_port = str(handler.client_address[1])
         spawned_interface.parent_interface = self

RNS/Link.py

@@ -722,12 +722,9 @@ class Link:
             pass
 
     def link_closed(self):
-        for resource in self.incoming_resources:
-            resource.cancel()
-        for resource in self.outgoing_resources:
-            resource.cancel()
-        if self._channel:
-            self._channel._shutdown()
+        for resource in self.incoming_resources: resource.cancel()
+        for resource in self.outgoing_resources: resource.cancel()
+        if self._channel: self._channel._shutdown()
             
         self.prv = None
         self.pub = None
@@ -741,8 +738,7 @@ class Link:
                     self.destination.links.remove(self)
 
         if self.callbacks.link_closed != None:
-            try:
-                self.callbacks.link_closed(self)
+            try: self.callbacks.link_closed(self)
             except Exception as e:
                 RNS.log("Error while executing link closed callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
@@ -935,7 +931,8 @@ class Link:
             request_id        = RNS.Identity.truncated_hash(packed_request)
             request_data      = unpacked_request
 
-            self.handle_request(request_id, request_data)
+            def job(): self.handle_request(request_id, request_data)
+            threading.Thread(target=job, daemon=True).start()
         else:
             RNS.log("Incoming request resource failed with status: "+RNS.hexrep([resource.status]), RNS.LOG_DEBUG)
 
@@ -1036,7 +1033,8 @@ class Link:
                             packed_request = self.decrypt(packet.data)
                             if packed_request != None:
                                 unpacked_request = umsgpack.unpackb(packed_request)
-                                self.handle_request(request_id, unpacked_request)
+                                def job(): self.handle_request(request_id, unpacked_request)
+                                threading.Thread(target=job, daemon=True).start()
                                 self.__update_phy_stats(packet, query_shared=True)
                         except Exception as e:
                             RNS.log("Error occurred while handling request. The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -1049,7 +1047,8 @@ class Link:
                                 request_id = unpacked_response[0]
                                 response_data = unpacked_response[1]
                                 transfer_size = len(umsgpack.packb(response_data))-2
-                                self.handle_response(request_id, response_data, transfer_size, transfer_size)
+                                def job(): self.handle_response(request_id, response_data, transfer_size, transfer_size)
+                                threading.Thread(target=job, daemon=True).start()
                                 self.__update_phy_stats(packet, query_shared=True)
                         except Exception as e:
                             RNS.log("Error occurred while handling response. The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -1085,17 +1084,14 @@ class Link:
                                                 pending_request.started_at = time.time()
                                             pending_request.response_resource_progress(response_resource)
 
-                            elif self.resource_strategy == Link.ACCEPT_NONE:
-                                pass
+                            elif self.resource_strategy == Link.ACCEPT_NONE: pass
                             elif self.resource_strategy == Link.ACCEPT_APP:
                                 if self.callbacks.resource != None:
                                     try:
                                         resource_advertisement = RNS.ResourceAdvertisement.unpack(packet.plaintext)
                                         resource_advertisement.link = self
-                                        if self.callbacks.resource(resource_advertisement):
-                                            RNS.Resource.accept(packet, self.callbacks.resource_concluded)
-                                        else:
-                                            RNS.Resource.reject(packet)
+                                        if self.callbacks.resource(resource_advertisement): RNS.Resource.accept(packet, self.callbacks.resource_concluded)
+                                        else:                                               RNS.Resource.reject(packet)
                                     except Exception as e:
                                         RNS.log("Error while executing resource accept callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
                             elif self.resource_strategy == Link.ACCEPT_ALL:
@@ -1181,7 +1177,8 @@ class Link:
                         resource_hash = packet.data[0:RNS.Identity.HASHLENGTH//8]
                         for resource in self.outgoing_resources:
                             if resource_hash == resource.hash:
-                                resource.validate_proof(packet.data)
+                                def job(resource=resource): resource.validate_proof(packet.data)
+                                threading.Thread(target=job, daemon=True).start()
                                 self.__update_phy_stats(packet, query_shared=True)
 
         self.watchdog_lock = False
@@ -1299,10 +1296,8 @@ class Link:
         :param resource_strategy: One of ``RNS.Link.ACCEPT_NONE``, ``RNS.Link.ACCEPT_ALL`` or ``RNS.Link.ACCEPT_APP``. If ``RNS.Link.ACCEPT_APP`` is set, the `resource_callback` will be called to determine whether the resource should be accepted or not.
         :raises: *TypeError* if the resource strategy is unsupported.
         """
-        if not resource_strategy in Link.resource_strategies:
-            raise TypeError("Unsupported resource strategy")
-        else:
-            self.resource_strategy = resource_strategy
+        if not resource_strategy in Link.resource_strategies: raise TypeError("Unsupported resource strategy")
+        else: self.resource_strategy = resource_strategy
 
     def register_outgoing_resource(self, resource):
         self.outgoing_resources.append(resource)
@@ -1312,8 +1307,7 @@ class Link:
 
     def has_incoming_resource(self, resource):
         for incoming_resource in self.incoming_resources:
-            if incoming_resource.hash == resource.hash:
-                return True
+            if incoming_resource.hash == resource.hash: return True
 
         return False
 
@@ -1324,25 +1318,18 @@ class Link:
         return self.last_resource_eifr
 
     def cancel_outgoing_resource(self, resource):
-        if resource in self.outgoing_resources:
-            self.outgoing_resources.remove(resource)
-        else:
-            RNS.log("Attempt to cancel a non-existing outgoing resource", RNS.LOG_ERROR)
+        if resource in self.outgoing_resources: self.outgoing_resources.remove(resource)
+        else: RNS.log("Attempt to cancel a non-existing outgoing resource", RNS.LOG_WARNING)
 
     def cancel_incoming_resource(self, resource):
-        if resource in self.incoming_resources:
-            self.incoming_resources.remove(resource)
-        else:
-            RNS.log("Attempt to cancel a non-existing incoming resource", RNS.LOG_ERROR)
+        if resource in self.incoming_resources: self.incoming_resources.remove(resource)
+        else: RNS.log("Attempt to cancel a non-existing incoming resource", RNS.LOG_WARNING)
 
     def ready_for_new_resource(self):
-        if len(self.outgoing_resources) > 0:
-            return False
-        else:
-            return True
+        if len(self.outgoing_resources) > 0: return False
+        else:                                return True
 
-    def __str__(self):
-        return RNS.prettyhexrep(self.link_id)
+    def __str__(self): return RNS.prettyhexrep(self.link_id)
 
 
 class RequestReceipt():
@@ -1427,20 +1414,21 @@ class RequestReceipt():
             now = time.time()
             if now > self.__resource_response_timeout:
                 self.request_timed_out(None)
+                break
 
             time.sleep(0.1)
 
 
     def request_timed_out(self, packet_receipt):
-        self.status = RequestReceipt.FAILED
-        self.concluded_at = time.time()
-        self.link.pending_requests.remove(self)
+        if self in self.link.pending_requests and self.status == RequestReceipt.DELIVERED:
+            self.status = RequestReceipt.FAILED
+            self.concluded_at = time.time()
+            self.link.pending_requests.remove(self)
 
-        if self.callbacks.failed != None:
-            try:
-                self.callbacks.failed(self)
-            except Exception as e:
-                RNS.log("Error while executing request timed out callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
+            if self.callbacks.failed != None:
+                try: self.callbacks.failed(self)
+                except Exception as e:
+                    RNS.log("Error while executing request timed out callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
 
     def response_resource_progress(self, resource):
@@ -1482,14 +1470,12 @@ class RequestReceipt():
                     self.packet_receipt.callbacks.delivery(self.packet_receipt)
 
             if self.callbacks.progress != None:
-                try:
-                    self.callbacks.progress(self)
+                try: self.callbacks.progress(self)
                 except Exception as e:
                     RNS.log("Error while executing response progress callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
             if self.callbacks.response != None:
-                try:
-                    self.callbacks.response(self)
+                try: self.callbacks.response(self)
                 except Exception as e:
                     RNS.log("Error while executing response received callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 

RNS/Packet.py

@@ -289,13 +289,11 @@ class Packet:
                     self.destination.tx += 1
                     self.destination.txbytes += len(self.data)
 
-            if not self.packed:
-                self.pack()
+            if not self.packed: self.pack()
 
-            if RNS.Transport.outbound(self):
-                return self.receipt
+            if RNS.Transport.outbound(self): return self.receipt
             else:
-                RNS.log("No interfaces could process the outbound packet", RNS.LOG_ERROR)
+                RNS.log("No interfaces could process the outbound packet", RNS.LOG_DEBUG)
                 self.sent = False
                 self.receipt = None
                 return False
@@ -317,7 +315,7 @@ class Packet:
             if RNS.Transport.outbound(self):
                 return self.receipt
             else:
-                RNS.log("No interfaces could process the outbound packet", RNS.LOG_ERROR)
+                RNS.log("Re-send failed. No interfaces could process the outbound packet", RNS.LOG_WARNING)
                 self.sent = False
                 self.receipt = None
                 return False

RNS/Resource.py

@@ -126,6 +126,7 @@ class Resource:
     PART_TIMEOUT_FACTOR           = 4
     PART_TIMEOUT_FACTOR_AFTER_RTT = 2
     PROOF_TIMEOUT_FACTOR          = 3
+    HMU_WAIT_FACTOR               = 3.5
     MAX_RETRIES                   = 16
     MAX_ADV_RETRIES               = 4
     SENDER_GRACE_TIME             = 10.0
@@ -193,6 +194,7 @@ class Resource:
             resource.window_flexibility   = Resource.WINDOW_FLEXIBILITY
             resource.last_activity        = time.time()
             resource.started_transferring = resource.last_activity
+            resource.advertisement_packet = advertisement_packet
 
             resource.storagepath          = RNS.Reticulum.resourcepath+"/"+resource.original_hash.hex()
             resource.meta_storagepath     = resource.storagepath+".meta"
@@ -359,6 +361,7 @@ class Resource:
         self.request_id = request_id
         self.started_transferring = None
         self.is_response = is_response
+        self.max_decompressed_size = Resource.AUTO_COMPRESS_MAX_SIZE
         self.auto_compress_limit = Resource.AUTO_COMPRESS_MAX_SIZE
         self.auto_compress_option = auto_compress
 
@@ -594,21 +597,22 @@ class Resource:
                     extra_wait = retries_used * Resource.PER_RETRY_DELAY
 
                     self.update_eifr()
+                    expected_hmu_wait_remaining = (self.sdu*8*self.HMU_WAIT_FACTOR)/self.eifr if self.waiting_for_hmu or self.outstanding_parts == 0 else 0
                     expected_tof_remaining = (self.outstanding_parts*self.sdu*8)/self.eifr
 
                     if self.req_resp_rtt_rate != 0:
-                        sleep_time = self.last_activity + self.part_timeout_factor*expected_tof_remaining + Resource.RETRY_GRACE_TIME + extra_wait - time.time()
+                        sleep_time = self.last_activity + self.part_timeout_factor*expected_tof_remaining + expected_hmu_wait_remaining + Resource.RETRY_GRACE_TIME + extra_wait - time.time()
                     else:
                         sleep_time = self.last_activity + self.part_timeout_factor*((3*self.sdu)/self.eifr) + Resource.RETRY_GRACE_TIME + extra_wait - time.time()
                     
                     # TODO: Remove debug at some point
-                    # RNS.log(f"EIFR {RNS.prettyspeed(self.eifr)}, ETOF {RNS.prettyshorttime(expected_tof_remaining)} ", RNS.LOG_DEBUG, pt=True)
+                    # RNS.log(f"EIFR {RNS.prettyspeed(self.eifr)}, ETOF {RNS.prettyshorttime(expected_tof_remaining)}, EHWR {RNS.prettyshorttime(expected_hmu_wait_remaining)}", RNS.LOG_DEBUG, pt=True)
                     # RNS.log(f"Resource ST {RNS.prettyshorttime(sleep_time)}, RTT {RNS.prettyshorttime(self.rtt or self.link.rtt)}, {self.outstanding_parts} left", RNS.LOG_DEBUG, pt=True)
                     
                     if sleep_time < 0:
                         if self.retries_left > 0:
                             ms = "" if self.outstanding_parts == 1 else "s"
-                            RNS.log("Timed out waiting for "+str(self.outstanding_parts)+" part"+ms+", requesting retry", RNS.LOG_DEBUG)
+                            RNS.log(f"Timed out waiting for {self.outstanding_parts} part{ms}, requesting retry on {self}", RNS.LOG_DEBUG)
                             if self.window > self.window_min:
                                 self.window -= 1
                                 if self.window_max > self.window_min:
@@ -677,6 +681,16 @@ class Resource:
                 # Strip off random hash
                 data = data[Resource.RANDOM_HASH_SIZE:]
 
+                if not self.compressed: self.data = data
+                else:
+                    decompressor = bz2.BZ2Decompressor()
+                    self.data = decompressor.decompress(data, max_length=self.max_decompressed_size)
+                    if not decompressor.eof:
+                        self.status = Resource.CORRUPT
+                        self.cancel()
+                        RNS.log(f"Decompressed resource exceeded maximum decompressed size. The resource was rejected.", RNS.LOG_ERROR)
+                        return
+
                 if self.compressed: self.data = bz2.decompress(data)
                 else: self.data = data
 
@@ -755,18 +769,18 @@ class Resource:
         # Prepare the next segment for advertisement
         RNS.log(f"Preparing segment {self.segment_index+1} of {self.total_segments} for resource {self}", RNS.LOG_DEBUG)
         self.preparing_next_segment = True
-        self.next_segment = Resource(
-            self.input_file, self.link,
-            callback = self.callback,
-            segment_index = self.segment_index+1,
-            original_hash=self.original_hash,
-            progress_callback = self.__progress_callback,
-            request_id = self.request_id,
-            is_response = self.is_response,
-            advertise = False,
-            auto_compress = self.auto_compress_option,
-            sent_metadata_size = self.metadata_size,
-        )
+        self.next_segment = Resource(self.input_file, self.link,
+                                     callback = self.callback,
+                                     segment_index = self.segment_index+1,
+                                     original_hash=self.original_hash,
+                                     progress_callback = self.__progress_callback,
+                                     request_id = self.request_id,
+                                     is_response = self.is_response,
+                                     advertise = False,
+                                     auto_compress = self.auto_compress_option,
+                                     sent_metadata_size = self.metadata_size)
+        if self.__progress_callback:
+            self.next_segment.progress_callback(self.__progress_callback)
 
     def validate_proof(self, proof_data):
         if not self.status == Resource.FAILED:
@@ -882,7 +896,7 @@ class Resource:
 
                 if self.received_count == self.total_parts and not self.assembly_lock:
                     self.assembly_lock = True
-                    self.assemble()
+                    threading.Thread(target=self.assemble, daemon=True).start()
                 elif self.outstanding_parts == 0:
                     # TODO: Figure out if there is a mathematically
                     # optimal way to adjust windows
@@ -959,6 +973,7 @@ class Resource:
                     self.last_activity = time.time()
                     self.req_sent = self.last_activity
                     self.req_sent_bytes = len(request_packet.raw)
+                    self.rtt_rxd_bytes_at_part_req = self.rtt_rxd_bytes
                     self.req_resp = None
 
                 except Exception as e:
@@ -1056,8 +1071,7 @@ class Resource:
                 self.retries_left = 3
 
             if self.__progress_callback != None:
-                try:
-                    self.__progress_callback(self)
+                try: self.__progress_callback(self)
                 except Exception as e:
                     RNS.log("Error while executing progress callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
@@ -1065,7 +1079,14 @@ class Resource:
         """
         Cancels transferring the resource.
         """
-        if self.status < Resource.COMPLETE:
+        if self.next_segment: self.next_segment.cancel()
+
+        if self.status == Resource.CORRUPT:
+            self.link.cancel_incoming_resource(self)
+            self.reject(self.advertisement_packet)
+            self.link.teardown()
+
+        elif self.status < Resource.COMPLETE:
             self.status = Resource.FAILED
             if self.initiator:
                 if self.link.status == RNS.Link.ACTIVE:
@@ -1093,7 +1114,8 @@ class Resource:
                 if self.callback != None:
                     try:
                         self.link.resource_concluded(self)
-                        self.callback(self)
+                        def job(): self.callback(self)
+                        threading.Thread(target=job, daemon=True).start()
                     except Exception as e:
                         RNS.log("Error while executing callbacks on resource reject from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
@@ -1102,6 +1124,7 @@ class Resource:
 
     def progress_callback(self, callback):
         self.__progress_callback = callback
+        if self.next_segment: self.next_segment.progress_callback(callback)
 
     def get_progress(self):
         """

RNS/Utilities/rncp.py

@@ -49,17 +49,34 @@ fetch_jail = None
 save_path = None
 show_phy_rates = False
 allowed_identity_hashes = []
+identity = None
+
+def prepare_identity(identity_path):
+    global identity
+    if identity_path == None:
+        identity_path = RNS.Reticulum.identitypath+"/"+APP_NAME
+
+    if os.path.isfile(identity_path):
+        identity = RNS.Identity.from_file(identity_path)
+        if identity == None:
+            RNS.log(f"Could not load identity for rncp. The identity file at \"{identity_path}\" may be corrupt or unreadable.", RNS.LOG_ERROR)
+            RNS.exit(2)
+
+    if identity == None:
+        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
+        identity = RNS.Identity()
+        identity.to_file(identity_path)
 
 REQ_FETCH_NOT_ALLOWED = 0xF0
 
 es = " "
 erase_str = "\33[2K\r"
 
-def listen(configdir, verbosity = 0, quietness = 0, allowed = [], display_identity = False,
+def listen(configdir, identitypath = None, verbosity = 0, quietness = 0, allowed = [], display_identity = False,
            limit = None, disable_auth = None, fetch_allowed = False, no_compress=False,
            jail = None, save = None, announce = False, allow_overwrite=False):
 
-    global allow_all, allow_fetch, allowed_identity_hashes, fetch_jail, save_path
+    global allow_all, allow_fetch, allowed_identity_hashes, fetch_jail, save_path, identity
     global fetch_auto_compress, allow_overwrite_on_receive
 
     allow_fetch = fetch_allowed
@@ -90,14 +107,7 @@ def listen(configdir, verbosity = 0, quietness = 0, allowed = [], display_identi
 
         RNS.log("Saving received files in \""+save_path+"\"", RNS.LOG_VERBOSE)
 
-    identity_path = RNS.Reticulum.identitypath+"/"+APP_NAME
-    if os.path.isfile(identity_path):
-        identity = RNS.Identity.from_file(identity_path)                
-
-    if identity == None:
-        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
-        identity = RNS.Identity()
-        identity.to_file(identity_path)
+    prepare_identity(identitypath)
 
     destination = RNS.Destination(identity, RNS.Destination.IN, RNS.Destination.SINGLE, APP_NAME, "receive")
 
@@ -345,8 +355,8 @@ def sender_progress(resource):
         resource_done = True
 
 link = None
-def fetch(configdir, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False, phy_rates=False, save=None, allow_overwrite=False):
-    global current_resource, resource_done, link, speed, show_phy_rates, save_path, allow_overwrite_on_receive
+def fetch(configdir, identitypath = None, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False, phy_rates=False, save=None, allow_overwrite=False):
+    global current_resource, resource_done, link, speed, show_phy_rates, save_path, allow_overwrite_on_receive, identity
     targetloglevel = 3+verbosity-quietness
     show_phy_rates = phy_rates
     allow_overwrite_on_receive = allow_overwrite
@@ -377,19 +387,8 @@ def fetch(configdir, verbosity = 0, quietness = 0, destination = None, file = No
 
     reticulum = RNS.Reticulum(configdir=configdir, loglevel=targetloglevel)
 
-    identity_path = RNS.Reticulum.identitypath+"/"+APP_NAME
-    if os.path.isfile(identity_path):
-        identity = RNS.Identity.from_file(identity_path)
-        if identity == None:
-            RNS.log("Could not load identity for rncp. The identity file at \""+str(identity_path)+"\" may be corrupt or unreadable.", RNS.LOG_ERROR)
-            RNS.exit(2)
-    else:
-        identity = None
-
     if identity == None:
-        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
-        identity = RNS.Identity()
-        identity.to_file(identity_path)
+        prepare_identity(identitypath)
 
     if not RNS.Transport.has_path(destination_hash):
         RNS.Transport.request_path(destination_hash)
@@ -614,8 +613,8 @@ def fetch(configdir, verbosity = 0, quietness = 0, destination = None, file = No
     RNS.exit(0)
 
 
-def send(configdir, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False, phy_rates=False, no_compress=False):
-    global current_resource, resource_done, link, speed, show_phy_rates, phy_got_total, phy_speed
+def send(configdir, identitypath = None, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False, phy_rates=False, no_compress=False):
+    global current_resource, resource_done, link, speed, show_phy_rates, phy_got_total, phy_speed, identity
     targetloglevel = 3+verbosity-quietness
     show_phy_rates = phy_rates
 
@@ -643,19 +642,8 @@ def send(configdir, verbosity = 0, quietness = 0, destination = None, file = Non
 
     reticulum = RNS.Reticulum(configdir=configdir, loglevel=targetloglevel)
 
-    identity_path = RNS.Reticulum.identitypath+"/"+APP_NAME
-    if os.path.isfile(identity_path):
-        identity = RNS.Identity.from_file(identity_path)
-        if identity == None:
-            RNS.log("Could not load identity for rncp. The identity file at \""+str(identity_path)+"\" may be corrupt or unreadable.", RNS.LOG_ERROR)
-            RNS.exit(2)
-    else:
-        identity = None
-
     if identity == None:
-        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
-        identity = RNS.Identity()
-        identity.to_file(identity_path)
+        prepare_identity(identitypath)
 
     if not RNS.Transport.has_path(destination_hash):
         RNS.Transport.request_path(destination_hash)
@@ -822,6 +810,7 @@ def main():
         parser.add_argument('-a', metavar="allowed_hash", dest="allowed", action='append', help="allow this identity (or add in ~/.rncp/allowed_identities)", type=str)
         parser.add_argument('-n', '--no-auth', action='store_true', default=False, help="accept requests from anyone")
         parser.add_argument('-p', '--print-identity', action='store_true', default=False, help="print identity and destination info and exit")
+        parser.add_argument('-i', metavar="identity", action='store', dest="identity", default=None, help="path to identity to use", type=str)
         parser.add_argument("-w", action="store", metavar="seconds", type=float, help="sender timeout before giving up", default=RNS.Transport.PATH_REQUEST_TIMEOUT)
         parser.add_argument('-P', '--phy-rates', action='store_true', default=False, help="display physical layer transfer rates")
         # parser.add_argument("--limit", action="store", metavar="files", type=float, help="maximum number of files to accept", default=None)
@@ -832,6 +821,7 @@ def main():
         if args.listen or args.print_identity:
             listen(
                 configdir = args.config,
+                identitypath = args.identity,
                 verbosity=args.verbose,
                 quietness=args.quiet,
                 allowed = args.allowed,
@@ -850,6 +840,7 @@ def main():
             if args.destination != None and args.file != None:
                 fetch(
                     configdir = args.config,
+                    identitypath = args.identity,
                     verbosity = args.verbose,
                     quietness = args.quiet,
                     destination = args.destination,
@@ -868,6 +859,7 @@ def main():
         elif args.destination != None and args.file != None:
             send(
                 configdir = args.config,
+                identitypath = args.identity,
                 verbosity = args.verbose,
                 quietness = args.quiet,
                 destination = args.destination,

RNS/Utilities/rngit/__init__.py

@@ -0,0 +1,39 @@
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+APP_NAME = "git"
+
+import os
+import glob
+
+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/rngit/client.py

@@ -0,0 +1,675 @@
+#!/usr/bin/env python3
+
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import RNS
+import os
+import sys
+import time
+import shutil
+import threading
+import subprocess
+
+from RNS._version import __version__
+from RNS.Utilities.rngit import APP_NAME
+
+from RNS.vendor.configobj import ConfigObj
+from tempfile import TemporaryDirectory
+
+def program_setup(configdir, rnsconfigdir, destination_hexhash, group_name, repo_name):
+    git_client = ReticulumGitClient(configdir=configdir, rnsconfigdir=rnsconfigdir, destination_hexhash=destination_hexhash,
+                                    group_name=group_name, repo_name=repo_name)
+
+    if not git_client.ready: sys.exit(1)
+    else:                    git_client.run()
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: git-remote-rns <remote-name> <url>", file=sys.stderr)
+        sys.exit(1)
+    
+    url = sys.argv[2]
+    if not url.startswith("rns://"):
+        print("Invalid URL scheme. Must be rns://", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        parts = url[6:].split("/", 2)
+        destination_hexhash = parts[0]
+        group_name = parts[1]
+        repo_name = parts[2]
+    
+    except IndexError: print("Invalid URL format. Use rns://<hash>/<group>/<repo>", file=sys.stderr); sys.exit(1)
+
+    configdir    = os.environ.get("RNGIT_CONFIG", None)
+    rnsconfigdir = os.environ.get("RNS_CONFIG", None)
+
+    program_setup(configdir, rnsconfigdir, destination_hexhash, group_name, repo_name)
+    exit(0)
+
+
+class ReticulumGitClient():
+    PATH_LIST       = "/git/list"
+    PATH_FETCH      = "/git/fetch"
+    PATH_PUSH       = "/git/push"
+    PATH_DELETE     = "/git/delete"
+
+    RES_DISALLOWED  = 0x01
+    RES_INVALID_REQ = 0x02
+    RES_NOT_FOUND   = 0x03
+    RES_REMOTE_FAIL = 0xFF
+
+    IDX_REPOSITORY  = 0x00
+    IDX_RESULT_CODE = 0x01
+
+    REF_BATCH_SIZE  = 25
+    PATH_TIMEOUT    = 15
+    LINK_TIMEOUT    = 15
+
+    def __init__(self, configdir, rnsconfigdir, destination_hexhash, group_name, repo_name):
+        # Client state and configuration
+        self.identity            = None
+        self.userdir             = os.path.expanduser("~")
+        self.config              = None
+        self.ready               = False
+        
+        self.remote_identity     = None
+        self.destination         = None
+        self.link                = None
+        self.link_ready          = False
+        self.link_failed         = False
+        self.link_timeout        = self.LINK_TIMEOUT
+        self.path_timeout        = self.PATH_TIMEOUT
+
+        self.destination_hexhash = destination_hexhash
+        self.group_name          = group_name
+        self.repo_name           = repo_name
+        self.repo_path           = f"{group_name}/{repo_name}"
+
+        self.tmp_dir             = TemporaryDirectory()
+        self.request_event       = threading.Event()
+        self.request_response    = None
+        self.response_metadata   = None
+
+        self.ref_batch_size      = self.REF_BATCH_SIZE
+        self.remote_refs         = {}
+
+        # Response progress tracking
+        self.response_progress      = 0
+        self.previous_progress      = 0
+        self.response_size          = None
+        self.response_transfer_size = None
+        self.progress_updated_at    = None
+        self.progress_enabled       = False
+
+        if configdir != None: self.configdir = configdir
+        else:
+            if os.path.isdir(self.userdir+"/.config/rngit") and os.path.isfile(self.userdir+"/.config/rngit/config"): self.configdir = self.userdir+"/.rngit/reticulum"
+            else: self.configdir = self.userdir+"/.rngit"
+        
+        self.logfile = self.configdir+"/client_log"
+        self.configpath = self.configdir+"/client_config"
+        self.identitypath = self.configdir+"/client_identity"
+
+        RNS.logfile = self.logfile
+        try: self.reticulum = RNS.Reticulum(configdir=rnsconfigdir, logdest=RNS.LOG_FILE)
+        except Exception as e:
+            print(f"Failed to initialize Reticulum: {e}", file=sys.stderr)
+            return
+
+        if os.path.isfile(self.configpath):
+            try: self.config = ConfigObj(self.configpath)
+            except Exception as e:
+                RNS.log("Could not parse the configuration at "+self.configpath, RNS.LOG_ERROR)
+                return
+        
+        else: self.__create_default_config()
+
+        self.__apply_config()
+        self.ready = True
+
+    def __create_default_config(self):
+        self.config = ConfigObj(__default_rngit_config__)
+        self.config.filename = self.configpath
+        if not os.path.isdir(self.configdir): os.makedirs(self.configdir)
+        self.config.write()
+
+    def __apply_config(self):
+        if "logging" in self.config:
+            section = self.config["logging"]
+            if "loglevel" in section: RNS.loglevel = max(RNS.LOG_NONE, min(RNS.LOG_EXTREME, section.as_int("loglevel")))
+        
+        if "client" in self.config:
+            section = self.config["client"]
+            if "ref_batch_size" in section: self.ref_batch_size = max(0, min(1024, section.as_int("ref_batch_size")))
+
+        if not os.path.isfile(self.identitypath):
+            identity = RNS.Identity()
+            identity.to_file(self.identitypath)
+            RNS.log(f"Client identity generated and persisted to {self.identitypath}", RNS.LOG_VERBOSE)
+        
+        else:
+            identity = RNS.Identity.from_file(self.identitypath)
+            RNS.log(f"Client identity loaded from {self.identitypath}", RNS.LOG_VERBOSE)
+
+        if not identity:
+            RNS.log("Could not initialize client identity.", RNS.LOG_ERROR)
+            self.ready = False
+        
+        else: self.identity = identity
+
+    def abort(self, reason=None, code=255):
+        if not reason: reason = "Unknown reason"
+        print(f"git-remote-rns failed: {reason}", file=sys.stderr)
+        if self.link: self.link.teardown()
+        sys.exit(code)
+
+    def connect_server(self):
+        try: destination_hash = bytes.fromhex(self.destination_hexhash)
+        except Exception as e: self.abort(f"Invalid destination hash: {e}")
+
+        RNS.log(f"Requesting path to {RNS.prettyhexrep(destination_hash)}", RNS.LOG_DEBUG)
+        sys.stderr.write(f"Requesting path..."); sys.stderr.flush()
+        if not RNS.Transport.await_path(destination_hash, timeout=self.path_timeout):
+            sys.stderr.write(f"\n"); sys.stderr.flush()
+            self.abort(f"Could not resolve path to {RNS.prettyhexrep(destination_hash)}")
+        
+        else:
+            RNS.log(f"Path to {RNS.prettyhexrep(destination_hash)} resolved", RNS.LOG_DEBUG);
+            sys.stderr.write(f"\rPath resolved     "); sys.stderr.flush()
+
+        self.remote_identity = RNS.Identity.recall(destination_hash)
+        if not self.remote_identity: self.abort("Could not recall remote identity. Is the server announcing?")
+
+        sys.stderr.write(f"\rEstablishing link..."); sys.stderr.flush()
+        self.destination = RNS.Destination(self.remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, APP_NAME, "repositories")
+        self.link = RNS.Link(self.destination)
+        self.link.set_link_established_callback(self.link_established)
+        self.link.set_link_closed_callback(self.link_closed)
+
+    def link_established(self, link):
+        RNS.log(f"Link established, identifying...", RNS.LOG_DEBUG)
+        sys.stderr.write(f"\rLink established with remote\n"); sys.stderr.flush()
+        link.identify(self.identity)
+        self.link_ready = True
+
+    def link_closed(self, link):
+        RNS.log(f"Link was closed", RNS.LOG_DEBUG)
+        if not self.link_ready: self.link_failed = True
+
+    def _on_progress(self, transfer_instance):
+        if hasattr(transfer_instance, "progress"):
+            self.response_progress      = transfer_instance.progress
+            self.response_size          = transfer_instance.response_size
+            self.response_transfer_size = transfer_instance.response_transfer_size
+        
+        elif hasattr(transfer_instance, "get_progress") and callable(transfer_instance.get_progress):
+            self.response_progress      = transfer_instance.get_progress()
+            self.response_size          = transfer_instance.total_size
+            self.response_transfer_size = transfer_instance.size
+        
+        now = time.time()
+        if self.progress_updated_at == None: self.progress_updated_at = now
+
+        if now > self.progress_updated_at+1:
+            td = now - self.progress_updated_at
+            pd = self.response_progress - self.previous_progress
+            bd = pd*self.response_size if self.response_size else 0
+            self.response_speed = (bd/td)*8 if td > 0 else 0
+            self.previous_progress = self.response_progress
+            self.progress_updated_at = now
+            
+            # Report progress to git via stderr
+            if self.progress_enabled and self.response_size:
+                percent = round(self.response_progress * 100, 1)
+                size = self.response_size
+                rxd = size*self.response_progress
+                speed_kbps = (self.response_speed / 1024) if hasattr(self, 'response_speed') else 0
+                sys.stderr.write(f"Transferring: {percent}% ({RNS.prettysize(rxd)}/{RNS.prettysize(size)}) {RNS.prettyspeed(self.response_speed)}          \r")
+                sys.stderr.flush()
+
+    ################################
+    # Synchronous Request Wrappers #
+    ################################
+
+    def _response_ready(self, request_receipt):
+        self.request_response = request_receipt.response
+        self.response_metadata = request_receipt.metadata
+
+        if hasattr(self.request_response, "read") and callable(self.request_response.read):
+            response_path = self.request_response.name
+            base_name = os.path.basename(response_path)
+            retained_path = os.path.join(self.tmp_dir.name, base_name)
+            shutil.move(response_path, retained_path)
+            self.request_response = open(retained_path, "rb")
+
+        self.request_event.set()
+
+    def _response_failed(self, request_receipt=None):
+        self.request_response = None
+        self.request_event.set()
+
+    def send_request(self, path, data, timeout=7200):
+        if not self.link_ready: self.abort("Link not ready for request")
+        
+        self.request_event.clear()
+        self.request_response  = None
+        self.response_metadata = None
+        self.previous_progress = 0
+        self.progress_updated_at = None
+        
+        RNS.log(f"Sending request: {path}", RNS.LOG_DEBUG)
+        request_receipt = self.link.request(path, data, progress_callback=self._on_progress, response_callback=self._response_ready, failed_callback=self._response_failed, timeout=timeout)
+        if request_receipt.resource: request_receipt.resource.progress_callback(self._on_progress)
+        self.request_event.wait(timeout=timeout)
+        
+        if self.request_response is None: self.abort("Request failed or timed out")
+        RNS.log(f"Got response for: {path}", RNS.LOG_DEBUG)
+        
+        return self.request_response, self.response_metadata
+
+    #############################
+    # Git Helper Protocol Logic #
+    #############################
+
+    def _detach_stdout(self):
+        sys.stdout = open(os.devnull, "w")
+        sys.stderr = open(os.devnull, "w")
+
+    def run(self):
+        try: self.connect_server()
+        except Exception as e: self.abort(str(e))
+
+        timeout = self.link_timeout
+        while not self.link_ready and not self.link_failed and timeout > 0:
+            time.sleep(0.5)
+            timeout -= 1
+
+        if not self.link_ready: self.abort("Failed to establish link")
+
+        self.progress_enabled = False
+
+        git_stdin  = sys.stdin
+        git_stdout = sys.stdout
+        git_stderr = sys.stderr
+
+        fetch_queue = []
+        push_queue  = []
+
+        while True:
+            line = git_stdin.readline()
+            if not line: break
+
+            line = line.strip()
+            if line == "capabilities":
+                git_stdout.write("list\n")
+                git_stdout.write("fetch\n")
+                git_stdout.write("push\n")
+                git_stdout.write("option\n")
+                git_stdout.write("\n")
+                git_stdout.flush()
+
+            elif line == "list": self.handle_git_list(git_stdout)
+
+            elif line.startswith("list "): self.handle_git_list(git_stdout, for_push=True) # List for push
+
+            elif line.startswith("option"):
+                # Line format: option <name> <value>
+                parts = line.split(maxsplit=2)
+                opt_name = parts[1] if len(parts) > 1 else ""
+                opt_value = parts[2] if len(parts) > 2 else ""
+                
+                if opt_name == "progress": self.progress_enabled = opt_value.lower() in ("true", "1", "yes"); git_stdout.write("ok\n")
+                else: git_stdout.write("unsupported\n")
+                
+                git_stdout.flush()
+
+            elif line.startswith("fetch"):
+                # Line format: fetch <sha> <ref>
+                parts = line.split()
+                sha = parts[1]
+                ref = parts[2]
+                # Avoid duplicates in the same batch - TODO: Re-evaluate this
+                if (sha, ref) not in fetch_queue: fetch_queue.append((sha, ref))
+                push_queue = []
+
+            elif line.startswith("push"):
+                # Line format: push <local_ref>:<remote_ref>
+                parts = line.split()
+                refspec = parts[1]
+                local_ref, remote_ref = refspec.split(":", 1)
+                push_queue.append((local_ref, remote_ref))
+                fetch_queue = []
+
+            elif line == "": # End of batch
+                try:
+                    self.process_fetch_queue(fetch_queue, git_stdout, self.progress_enabled, self.ref_batch_size)
+                    self.process_push_queue(push_queue, git_stdout, git_stderr, self.progress_enabled)
+                    fetch_queue = []
+                    push_queue = []
+                    git_stdout.write("\n")
+                    git_stdout.flush()
+                
+                except BrokenPipeError:
+                    self._detach_stdout()
+                    RNS.log("Git closed connection, exiting", RNS.LOG_DEBUG)
+                    break
+
+            else: self.abort(f"Unknown Git command: {line}")
+
+        try: sys.stdout.flush()
+        except BrokenPipeError: pass
+
+        if self.link: self.link.teardown()
+
+    def handle_git_list(self, git_stdout, for_push=False):
+        RNS.log("Handle git list" + (" for-push" if for_push else ""), RNS.LOG_DEBUG)
+        request_data = {self.IDX_REPOSITORY: self.repo_path, "for_push": for_push}
+        response, metadata = self.send_request(self.PATH_LIST, request_data)
+
+        if not response or not isinstance(response, bytes): self.abort("Invalid list response from server")
+
+        status_byte = response[0]
+        payload = response[1:]
+
+        if status_byte != 0: self.abort(f"Server refused list: {payload.decode('utf-8', errors='ignore')}")
+
+        response_text = payload.decode("utf-8")
+
+        self.remote_refs = {}
+        for line in response_text.split("\n"):
+            line = line.strip()
+            if not line: continue
+            parts = line.split(" ", 1)
+            if len(parts) == 2:
+                sha, ref_name = parts
+                if ref_name == "HEAD": continue
+                self.remote_refs[ref_name] = sha
+
+        git_stdout.write(response_text)
+        git_stdout.write("\n") # Required to terminate list
+        git_stdout.flush()
+
+    def escape_for_stdout(self, value):
+        if isinstance(value, bytes): value = value.decode('utf-8', errors='replace')
+
+        escaped = '"'
+        for char in value:
+            if   char == '\\': escaped += '\\\\'
+            elif char == '"': escaped += '\\"'
+            elif char == '\n': escaped += '\\n'
+            elif char == '\t': escaped += '\\t'
+            elif char == '\r': escaped += '\\r'
+            elif ord(char) < 32 or ord(char) > 126: escaped += f'\\x{ord(char):02x}'
+            else: escaped += char
+        
+        return escaped + '"'
+
+    def process_fetch_queue(self, fetch_queue, git_stdout, progress_enabled=False, ref_batch_size=REF_BATCH_SIZE):
+        import tempfile
+        import subprocess
+
+        if not fetch_queue: return
+
+        # Build a global have list from all remote refs that the client already has objects for
+        have_shas = []
+        for sha in self.remote_refs.values():
+            try:
+                result = subprocess.run(["git", "cat-file", "-t", sha], capture_output=True, check=False)
+                if result.returncode == 0: have_shas.append(sha)
+            
+            except Exception as e: RNS.log(f"Could not verify remote SHA {sha} locally: {e}", RNS.LOG_WARNING)
+
+        while fetch_queue:
+            batch = fetch_queue[:ref_batch_size]
+            fetch_queue = fetch_queue[ref_batch_size:]
+
+            refs_list = []
+            for sha, ref in batch:
+                ref_entry = {"sha": sha, "ref": ref}
+                try:
+                    # Attempt to get local ref SHA for incremental bundle generation on remote
+                    result = subprocess.run(["git", "rev-parse", ref], capture_output=True, text=True, check=False)
+                    if result.returncode == 0:
+                        local_sha = result.stdout.strip()
+                        if local_sha != sha: ref_entry["have"] = local_sha
+
+                except Exception as e:
+                    RNS.log(f"Could not resolve local SHA for {ref} during fetch enumeration, getting full history for this ref: {e}", RNS.LOG_WARNING)
+
+                refs_list.append(ref_entry)
+
+            ref_names = [ref for _, ref in batch]
+            RNS.log(f"Fetching batch of {len(refs_list)} refs: {ref_names} (have {len(have_shas)} common objects)", RNS.LOG_DEBUG)
+
+            request_data = { self.IDX_REPOSITORY: self.repo_path, "refs": refs_list }
+            if have_shas: request_data["have"] = have_shas
+
+            response, metadata = self.send_request(self.PATH_FETCH, request_data)
+
+            if not response: self.abort(f"No data in fetch response for batch")
+            if not metadata:
+                if not isinstance(response, bytes): self.abort(f"Invalid fetch response for batch")
+                status_byte = response[0]
+
+                if status_byte == 0:
+                    RNS.log(f"Server returned empty bundle, all objects already exist locally", RNS.LOG_DEBUG)
+                    continue
+
+                else:
+                    error_msg = response[1:].decode('utf-8', errors='ignore')
+                    self.abort(f"Fetch failed for batch: {error_msg}")
+
+            else:
+                if not self.IDX_RESULT_CODE in metadata: self.abort(f"No result metadata on bundle response")
+                status_byte = metadata[self.IDX_RESULT_CODE]
+                if status_byte == 0: bundle_path = response.name
+                else: self.abort(f"Unknown remote state for batch ref fetch")
+
+                if progress_enabled:
+                    size = os.stat(bundle_path).st_size
+                    sys.stderr.write(f"Transferring: 100% ({RNS.prettysize(size)}).                       \n")
+                    sys.stderr.flush()
+
+                stderr_arg = sys.stderr if progress_enabled else subprocess.DEVNULL
+
+                verify_cmd = ["git", "bundle", "verify", "-q", bundle_path]
+                verify_result = subprocess.run(verify_cmd, stderr=subprocess.DEVNULL, stdout=subprocess.DEVNULL)
+
+                if verify_result.returncode != 0: self.abort(f"Bundle verification failed for batch")
+
+                unbundle_cmd = ["git", "bundle", "unbundle"]
+                if progress_enabled: unbundle_cmd.append("--progress")
+                unbundle_cmd.append(bundle_path)
+
+                unbundle_result = subprocess.run(unbundle_cmd, stderr=stderr_arg, stdout=subprocess.DEVNULL)
+
+                if unbundle_result.returncode != 0: self.abort(f"Bundle unbundle failed for batch: Non-zero return code")
+
+    def process_push_queue(self, push_queue, git_stdout, git_stderr, progress_enabled=False):
+        import tempfile
+        import subprocess
+
+        for local_ref, remote_ref in push_queue:
+            RNS.log(f"Pushing {local_ref} to {remote_ref}", RNS.LOG_DEBUG)
+
+            # Handle potential deletions
+            if not local_ref or local_ref == "":
+                request_data = { self.IDX_REPOSITORY: self.repo_path, "ref": remote_ref }
+                response, metadata = self.send_request(self.PATH_DELETE, request_data)
+
+                if not response or not isinstance(response, bytes):
+                    git_stdout.write(f"error {remote_ref} {self.escape_for_stdout('No response from server')}\n")
+                    git_stdout.flush()
+                    continue
+
+                status_byte = response[0]
+                if status_byte != 0:
+                    error_msg = response[1:].decode("utf-8", errors="ignore")
+                    git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                    git_stdout.flush()
+                    continue
+
+                git_stdout.write(f"ok {remote_ref}\n")
+                git_stdout.flush()
+                continue
+
+            force = local_ref.startswith("+")
+            if force: local_ref = local_ref[1:]
+
+            stderr_arg = sys.stderr if progress_enabled else subprocess.DEVNULL
+
+            # Resolve the SHA that local_ref points to
+            sha_result = subprocess.run(["git", "rev-parse", local_ref], capture_output=True, text=True, check=False)
+            if sha_result.returncode != 0:
+                error_msg = f"Could not resolve local ref {local_ref}"
+                git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                git_stdout.flush()
+                continue
+
+            local_sha = sha_result.stdout.strip()
+
+            bundle_empty = False
+            with tempfile.TemporaryDirectory() as tmpdir:
+                bundle_path = tmpdir + "/push.bundle"
+
+                create_cmd = ["git", "bundle", "create", bundle_path, local_ref]
+
+                # Exclude all remote ref SHAs that exist locally, so the
+                # bundle only contains objects the remote doesn't already have
+                exclude_count = 0
+                for sha in self.remote_refs.values():
+                    try:
+                        # We need to verify each SHA actually exists locally, since git
+                        # bundle create will fail if a ^<sha> argument references an object
+                        # not present in the local repository.
+                        result = subprocess.run(["git", "cat-file", "-t", sha], capture_output=True, check=False)
+                        if result.returncode == 0:
+                            create_cmd.append(f"^{sha}")
+                            exclude_count += 1
+                    
+                    except Exception as e: RNS.log(f"Could not verify remote SHA {sha} locally: {e}", RNS.LOG_WARNING)
+
+                RNS.log(f"Excluding {exclude_count}/{len(self.remote_refs)} remote refs for {local_ref}", RNS.LOG_DEBUG)
+
+                if progress_enabled: create_cmd.insert(3, "--progress")
+
+                create_result = subprocess.run(create_cmd, capture_output=True, text=True, check=False)
+
+                if create_result.returncode == 0:
+                    if create_result.stderr:
+                        # git_stderr.write(create_result.stderr)
+                        pass
+                else:
+                    if "empty bundle" in create_result.stderr.lower():
+                        # All objects reachable from local_ref already exist on
+                        # the remote. In this case, no bundle is needed and we can
+                        # update the ref directly via the operations path instead.
+                        bundle_empty = True
+                        RNS.log(f"Empty bundle for {local_ref}, all objects already on remote", RNS.LOG_DEBUG)
+
+                    else:
+                        if progress_enabled and create_result.stderr: git_stderr.write(create_result.stderr)
+                        error_msg = "Bundle creation failed"
+                        git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                        git_stdout.flush()
+                        continue
+
+                if not bundle_empty:
+                    with open(bundle_path, "rb") as f: bundle_data = f.read()
+
+                    request_data = { self.IDX_REPOSITORY: self.repo_path, "local_ref": local_ref, "remote_ref": remote_ref,
+                                     "force": force, "bundle": bundle_data }
+                    
+                    response, metadata = self.send_request(self.PATH_PUSH, request_data)
+
+                    if not response or not isinstance(response, bytes):
+                        git_stdout.write(f"error {remote_ref} {self.escape_for_stdout('No response from server')}\n")
+                        git_stdout.flush()
+                        continue
+
+                    status_byte = response[0]
+                    if status_byte != 0:
+                        error_msg = response[1:].decode('utf-8', errors='ignore')
+                        git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                        git_stdout.flush()
+                        continue
+
+            # When all reachable objects already exist on the remote, send a
+            # direct ref update operation instead of a bundle.
+            if bundle_empty:
+                operation    = {"action": "update_ref", "ref": remote_ref, "sha": local_sha, "force": force}
+                request_data = { self.IDX_REPOSITORY: self.repo_path,
+                                 "operations": [operation] }
+
+                response, metadata = self.send_request(self.PATH_PUSH, request_data)
+
+                if not response or not isinstance(response, bytes):
+                    git_stdout.write(f"error {remote_ref} {self.escape_for_stdout('No response from server')}\n")
+                    git_stdout.flush()
+                    continue
+
+                status_byte = response[0]
+                if status_byte != 0:
+                    error_msg = response[1:].decode('utf-8', errors='ignore')
+                    git_stdout.write(f"error {remote_ref} {self.escape_for_stdout(error_msg)}\n")
+                    git_stdout.flush()
+                    continue
+
+            git_stdout.write(f"ok {remote_ref}\n")
+            git_stdout.flush()
+
+
+__default_rngit_config__ = '''# This is the default rngit client config file.
+
+[client]
+
+# You can control the batch size of ref transfers
+# using the ref_batch_size directive:
+
+ref_batch_size = 25
+
+[logging]
+# Valid log levels are 0 through 7:
+#   0: Log only critical information
+#   1: Log errors and lower log levels
+#   2: Log warnings and lower log levels
+#   3: Log notices and lower log levels
+#   4: Log info and lower (this is the default)
+#   5: Verbose logging
+#   6: Debug logging
+#   7: Extreme logging
+
+loglevel = 4
+
+'''.splitlines()
+
+if __name__ == "__main__": main()

RNS/Utilities/rngit/main.py

@@ -0,0 +1,40 @@
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import sys
+from RNS.Utilities.rngit import client, server
+
+if __name__ == "__main__":
+    cmd = sys.argv[0]
+    if   cmd == "rngit":          ec = server.main()
+    elif cmd == "git-remote-rns": ec = client.main()
+    else: raise NotImplementedError(f"The {cmd} executable entrypoint is not yet implemented in rngit")
+
+    sys.exit(ec)

RNS/Utilities/rngit/server.py

@@ -0,0 +1,765 @@
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import RNS
+import os
+import time
+import argparse
+import threading
+import subprocess
+
+from threading import Lock
+from tempfile import TemporaryDirectory
+
+from RNS._version import __version__
+from RNS.Utilities.rngit import APP_NAME
+from RNS.vendor.configobj import ConfigObj
+
+def program_setup(configdir, rnsconfigdir=None, verbosity=0, quietness=0, service=False, interactive=False, print_identity=False):
+    targetverbosity = verbosity-quietness
+
+    if service:
+        targetlogdest  = RNS.LOG_FILE
+        targetverbosity = None
+    else:
+        targetlogdest  = RNS.LOG_STDOUT
+
+    if print_identity: git_node = ReticulumGitNode(configdir=configdir, print_identity=True)
+
+    reticulum  = RNS.Reticulum(configdir=rnsconfigdir, verbosity=targetverbosity, logdest=targetlogdest)
+
+    RNS.log("Starting Reticulum Git Node...", RNS.LOG_NOTICE)
+    git_node = ReticulumGitNode(configdir=configdir, verbosity=targetverbosity)
+    if not git_node.ready: exit(255)
+    else: git_node.start()
+
+    if interactive:
+        import code
+        code.interact(local=globals())
+    
+    else:
+        while git_node._should_run: time.sleep(1)
+
+    exit(0)
+
+def main():
+    try:
+        parser = argparse.ArgumentParser(description="Reticulum Git Repository Node")
+        parser.add_argument("--config", action="store", default=None, help="path to alternative config directory", type=str)
+        parser.add_argument("--rnsconfig", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser.add_argument('-p', '--print-identity', action='store_true', default=False, help="print identity and destination info and exit")
+        parser.add_argument('-s', '--service', action='store_true', default=False, help="rngit is running as a service and should log to file")
+        parser.add_argument('-i', '--interactive', action='store_true', default=False, help="drop into interactive shell after initialisation")
+        parser.add_argument('-v', '--verbose', action='count', default=0)
+        parser.add_argument('-q', '--quiet', action='count', default=0)
+        parser.add_argument("--version", action="version", version="rngit {version}".format(version=__version__))
+        
+        args = parser.parse_args()
+
+        if args.config:    configarg = args.config
+        else:              configarg = None
+
+        if args.rnsconfig: rnsconfigarg = args.rnsconfig
+        else:              rnsconfigarg = None
+
+        program_setup(configdir = configarg, rnsconfigdir=rnsconfigarg, service=args.service, verbosity=args.verbose,
+                      quietness=args.quiet, interactive=args.interactive, print_identity=args.print_identity)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()
+
+class ReticulumGitNode():
+    JOBS_INTERVAL   = 5
+
+    PERM_READ       = 0x01
+    PERM_WRITE      = 0x02
+    PERM_READWRITE  = 0x03
+    PERM_R_SMPHR    = ["r", "read"]
+    PERM_W_SMPHR    = ["w", "write"]
+    PERM_RW_SMPHR   = ["f", "full", "rw", "readwrite"]
+
+    TGT_NONE        = 0x01
+    TGT_ALL         = 0x02
+    TGT_NONE_SMPHR  = ["n", "none", "nobody"]
+    TGT_ALL_SMPHR   = ["a", "all", "everyone"]
+
+    PATH_LIST       = "/git/list"
+    PATH_FETCH      = "/git/fetch"
+    PATH_PUSH       = "/git/push"
+    PATH_DELETE     = "/git/delete"
+
+    RES_OK          = 0x00
+    RES_DISALLOWED  = 0x01
+    RES_INVALID_REQ = 0x02
+    RES_NOT_FOUND   = 0x03
+    RES_REMOTE_FAIL = 0xFF
+
+    IDX_REPOSITORY  = 0x00
+    IDX_RESULT_CODE = 0x01
+
+    def __init__(self, configdir=None, verbosity=None, print_identity=False):
+        self.identity            = None
+        self.userdir             = os.path.expanduser("~")
+        self.global_allow        = RNS.Destination.ALLOW_ALL
+        self.groups              = {}
+        self.active_links        = {}
+        self.last_announce       = 0
+        self.announce_interval   = 0
+        self.link_clean_interval = 5
+        self.last_link_clean     = 0
+        self.active_links_lock   = Lock()
+        self.node_name           = "Anonymous Git Node"
+
+        self.config              = None
+        self.verbosity           = verbosity or 0
+        self.ready               = False
+        self._should_run         = False
+
+        if not self.__ensure_git(): RNS.log("The \"git\" command is not available. Aborting server startup.", RNS.LOG_ERROR)
+        else:
+            if configdir != None: self.configdir = configdir
+            else:
+                if os.path.isdir("/etc/rngit") and os.path.isfile("/etc/rngit/config"):
+                    self.configdir = "/etc/rngit"
+                elif os.path.isdir(self.userdir+"/.config/rngit") and os.path.isfile(self.userdir+"/.config/rngit/config"):
+                    self.configdir = self.userdir+"/.rngit/reticulum"
+                else:
+                    self.configdir = self.userdir+"/.rngit"
+            
+            RNS.logfile = self.configdir+"/server_log"
+            self.configpath = self.configdir+"/config"
+            self.identitypath = self.configdir+"/repositories_identity"
+
+            if os.path.isfile(self.configpath):
+                try: self.config = ConfigObj(self.configpath)
+                except Exception as e:
+                    RNS.log("Could not parse the configuration at "+self.configpath, RNS.LOG_ERROR)
+                    RNS.log("Check your configuration file for errors!", RNS.LOG_ERROR)
+                    RNS.panic()
+            else:
+                RNS.log("Could not load config file, creating default configuration file...")
+                self.__create_default_config()
+                RNS.log("Default config file created. Make any necessary changes in "+self.configdir+"/config and restart rngit.")
+                RNS.log("Exiting now")
+                exit(1)
+
+            self.__apply_config()
+
+            if print_identity:
+                client_identity_path = self.configdir+"/client_identity"
+                if not os.path.isfile(client_identity_path):
+                    client_identity = RNS.Identity()
+                    client_identity.to_file(client_identity_path)
+                    RNS.log(f"Client identity generated and persisted to {client_identity_path}", RNS.LOG_VERBOSE)
+                
+                else: client_identity = RNS.Identity.from_file(client_identity_path)
+
+                destination_hash = RNS.Destination.hash_from_name_and_identity(f"{APP_NAME}.repositories", self.identity)
+                print(f"Git Peer Identity        : {RNS.prettyhexrep(client_identity.hash)}")
+                print(f"Repository Node Identity : {RNS.prettyhexrep(self.identity.hash)}")
+                print(f"Repositories Destination : {RNS.prettyhexrep(destination_hash)}")
+                exit(0)
+
+            self.destination = RNS.Destination(self.identity, RNS.Destination.IN, RNS.Destination.SINGLE, APP_NAME, "repositories")
+            self.destination.set_link_established_callback(self.remote_connected)
+            self.register_request_handlers()
+            RNS.log(f"Reticulum Git Node listening on {RNS.prettyhexrep(self.destination.hash)}", RNS.LOG_NOTICE)
+            self.ready = True
+
+    def __create_default_config(self):
+        self.config = ConfigObj(__default_rngit_config__)
+        self.config.filename = self.configpath
+
+        if not os.path.isdir(self.configdir): os.makedirs(self.configdir)
+        self.config.write()
+
+    def __apply_config(self):
+        if not os.path.isfile(self.identitypath):
+            identity = RNS.Identity()
+            identity.to_file(self.identitypath)
+            RNS.log(f"Repositories identity generated and persisted to {self.identitypath}", RNS.LOG_VERBOSE)
+        
+        else:
+            identity = RNS.Identity.from_file(self.identitypath)
+            RNS.log(f"Repositories identity loaded from {self.identitypath}", RNS.LOG_VERBOSE)
+
+        if not identity:
+            RNS.log(f"Could not initialize repositories identity. Exiting now.", RNS.LOG_ERROR)
+            RNS.panic()
+
+        else: self.identity = identity
+
+        if "rngit" in self.config:
+            section = self.config["rngit"]
+            if "node_name" in section: self.node_name = section["node_name"]
+            if "announce_interval" in section: self.announce_interval = section.as_int("announce_interval")*60
+
+        if "logging" in self.config:
+            section = self.config["logging"]
+            if "loglevel" in section: RNS.loglevel = max(RNS.LOG_NONE, min(RNS.LOG_EXTREME, section.as_int("loglevel")+self.verbosity))
+
+        if "repositories" in self.config:
+            section = self.config["repositories"]
+            for group_name in section:
+                RNS.log(f"Loading repositery group \"{group_name}\"", RNS.LOG_VERBOSE)
+                group_path = os.path.expanduser(section[group_name])
+                if not os.path.isdir(group_path): RNS.log(f"The path \"{group_path}\" specified for repository group \"{group_name}\" does not exist, skipping.", RNS.LOG_ERROR)
+                else:
+                    self.load_repository_group(group_name, group_path)
+
+        if "access" in self.config:
+            section = self.config["access"]
+            for group_name in section:
+                if group_name in self.groups:
+                    group_permissions = section.as_list(group_name)
+                    for entry in group_permissions:
+                        perm, target = self.parse_permission(entry)
+                        if not perm or not target: continue
+                        else:
+                            read = False; write = False
+                            if perm == self.PERM_READ  or perm == self.PERM_READWRITE: read  = True
+                            if perm == self.PERM_WRITE or perm == self.PERM_READWRITE: write = True
+
+                            if read  and not target in self.groups[group_name]["read"]:  self.groups[group_name]["read"].append(target)
+                            if write and not target in self.groups[group_name]["write"]: self.groups[group_name]["write"].append(target)
+
+    def parse_permission(self, permission_string):
+        comps = permission_string.split(":")
+        if not len(comps) == 2: return None, None
+        else:
+            perm = comps[0].lower(); target = comps[1]
+            if   perm in self.PERM_R_SMPHR:  perm = self.PERM_READ
+            elif perm in self.PERM_W_SMPHR:  perm = self.PERM_WRITE
+            elif perm in self.PERM_RW_SMPHR: perm = self.PERM_READWRITE
+            else:                            perm = None
+
+            if   target in self.TGT_NONE_SMPHR: target = self.TGT_NONE
+            elif target in self.TGT_ALL_SMPHR:  target = self.TGT_ALL
+            elif len(target) == RNS.Reticulum.TRUNCATED_HASHLENGTH//8*2:
+                try: target = bytes.fromhex(target)
+                except Exception as e:
+                    RNS.log(f"Invalid identity hash \"{target}\" in access permissions: {e}", RNS.LOG_ERROR)
+                    target = None
+            else:   target = None
+
+            return perm, target
+
+    def parse_request_repository_path(self, path):
+        components = path.split("/")
+        if not len(components) == 2: return None, None
+        else:
+            limit = 256
+            group = components[0]
+            repository_name = components[1]
+            if len(group) > limit or len(repository_name) > limit: return None, None
+            else:                                                  return group, repository_name
+
+    def resolve_permission(self, remote_identity, group_name, repository_name, permission):
+        remote_hash = remote_identity.hash
+        RNS.log(f"Resolving {group_name}/{repository_name} permission {permission} for {RNS.prettyhexrep(remote_hash)}", RNS.LOG_DEBUG) # TODO: Remove
+        if not group_name in self.groups: return False
+        if not repository_name in self.groups[group_name]["repositories"]: return False
+        else:
+            if permission == self.PERM_READ:
+                repository_permissions = self.groups[group_name]["repositories"][repository_name]["read"]
+                group_permissions      = self.groups[group_name]["read"]
+
+            elif permission == self.PERM_WRITE:
+                repository_permissions = self.groups[group_name]["repositories"][repository_name]["write"]
+                group_permissions      = self.groups[group_name]["write"]
+
+            else: return False
+
+            if   self.TGT_NONE in repository_permissions: return False
+            elif self.TGT_ALL  in repository_permissions: return True
+            elif remote_hash   in repository_permissions: return True
+            else:
+                if   self.TGT_NONE in group_permissions: return False
+                elif self.TGT_ALL  in group_permissions: return True
+                elif remote_hash   in group_permissions: return True
+                else:                                    return False
+
+            return False
+
+        return False
+
+    def load_repository_group(self, group_name, group_path):
+        # TODO: Implement group.allowed file
+        if not group_name in self.groups: self.groups[group_name] = { "path": group_path, "repositories": {}, "read": [], "write": [] }
+        if group_name in self.groups and self.groups[group_name]["path"] != group_path:
+            RNS.log(f"Repository group path did not match existing entry while loading {group_name}, aborting load", RNS.LOG_ERROR)
+            return
+
+        loaded = 0
+        group  = self.groups[group_name]
+        for entry in os.listdir(group_path):
+            path = f"{group_path}/{entry}"
+            if os.path.isdir(path):
+                if not self.__is_git_repository(path): RNS.log(f"The directory \"{path}\" is not a git repository, skipping", RNS.LOG_WARNING)
+                else:
+                    if not self.__is_bare_repository(path):
+                        RNS.log(f"The directory \"{path}\" is not a bare git repository, skipping", RNS.LOG_WARNING)
+                        RNS.log(f"You can change it to a bare repository using \"git config --bool core.bare true\".", RNS.LOG_WARNING)
+
+                    else:
+                        repository_name = os.path.basename(path)
+                        allowed_path    = f"{path}.allowed"
+                        read_allowed    = []
+                        write_allowed   = []
+
+                        if os.path.isfile(allowed_path):
+                            if os.access(allowed_path, os.X_OK):
+                                allowed_result = subprocess.run([allowed_path], stdout=subprocess.PIPE)
+                                allowed_input = allowed_result.stdout.decode("utf-8")
+
+                            else:
+                                fh = open(allowed_path, "rb")
+                                allowed_input = fh.read().decode("utf-8")
+                                fh.close()
+
+                            for entry in allowed_input.splitlines():
+                                perm_input = entry.strip()
+                                if not perm_input.startswith("#"):
+                                    perm, target = self.parse_permission(perm_input)
+                                    if not perm or not target: continue
+                                    else:
+                                        read = False; write = False
+                                        if perm == self.PERM_READ  or perm == self.PERM_READWRITE: read  = True
+                                        if perm == self.PERM_WRITE or perm == self.PERM_READWRITE: write = True
+
+                                        if read  and not target in read_allowed:  read_allowed.append(target)
+                                        if write and not target in write_allowed: write_allowed.append(target)
+
+                        group["repositories"][repository_name] = {"name": repository_name, "group": group_name, "path": path, "read": read_allowed, "write": write_allowed }
+                        loaded += 1
+
+        ms = "y" if loaded == 1 else "ies"
+        RNS.log(f"Loaded {loaded} repositor{ms} for group \"{group_name}\"", RNS.LOG_VERBOSE)
+
+    def start(self):
+        self._should_run = True
+        threading.Thread(target=self.jobs, daemon=True).start()
+
+    def announce(self):
+        RNS.log("Announcing repositories destination", RNS.LOG_VERBOSE)
+        self.destination.announce()
+        self.last_announce = time.time()
+
+    def jobs(self):
+        while self._should_run:
+            time.sleep(self.JOBS_INTERVAL)
+            try:
+                if self.announce_interval and time.time() > self.last_announce + self.announce_interval: self.announce()
+                if time.time() > self.last_link_clean + self.link_clean_interval:
+                    stale_links = []
+                    with self.active_links_lock:
+                        for link_id in self.active_links:
+                            link = self.active_links[link_id]
+                            if not link.status == RNS.Link.ACTIVE: stale_links.append(link_id)
+
+                    cleaned_links = 0
+                    for link_id in stale_links:
+                        link = None
+                        with self.active_links_lock:
+                            if link_id in self.active_links:
+                                link = self.active_links.pop(link_id)
+                                cleaned_links += 1
+
+                        if link and hasattr(link, "temporary_directories"):
+                            for tmpdir in link.temporary_directories:
+                                try:
+                                    tmpdir.cleanup()
+                                    RNS.log(f"Cleaned up {tmpdir.name}", RNS.LOG_DEBUG)
+
+                                except Exception as e:
+                                    RNS.log(f"Error while cleaning temporary directory: {e}", RNS.LOG_ERROR)
+
+                    self.last_link_clean = time.time()
+                    if cleaned_links > 0: RNS.log(f"Cleaned {cleaned_links} links", RNS.LOG_DEBUG)
+
+            except Exception as e: RNS.log(f"Error while running periodic jobs: {e}", RNS.LOG_ERROR)
+
+    def __ensure_git(self):
+        try: subprocess.run(["git", "--version"], check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL); return True
+        except: return False
+
+    def __is_git_repository(self, path):
+        try:
+            result = subprocess.run(["git", "rev-parse", "--git-dir"], cwd=path, check=True, capture_output=True, text=True)
+            if not result: return False
+            else: check = result.stdout.strip()
+            if check == ".": return True
+            else:            return False
+        
+        except: return False
+
+    def __is_bare_repository(self, path):
+        try:
+            result = subprocess.run(["git", "config", "--bool", "core.bare"], cwd=path, check=True, capture_output=True, text=True)
+            if not result: return False
+            else: check = result.stdout.strip()
+            if check == "true": return True
+            else:               return False
+        
+        except: return False
+
+    def register_request_handlers(self):
+        ga_list = self.global_allowed_list if self.global_allow == RNS.Destination.ALLOW_LIST else None
+        self.destination.register_request_handler(self.PATH_LIST,   self.handle_list,   allow=self.global_allow, allowed_list=ga_list)
+        self.destination.register_request_handler(self.PATH_FETCH,  self.handle_fetch,  allow=self.global_allow, allowed_list=ga_list)
+        self.destination.register_request_handler(self.PATH_PUSH,   self.handle_push,   allow=self.global_allow, allowed_list=ga_list)
+        self.destination.register_request_handler(self.PATH_DELETE, self.handle_delete, allow=self.global_allow, allowed_list=ga_list)
+
+    def remote_connected(self, link):
+        RNS.log(f"Peer connected to {self.destination}", RNS.LOG_DEBUG)
+        link.set_remote_identified_callback(self.remote_identified)
+        link.set_link_closed_callback(self.remote_disconnected)
+
+    def remote_disconnected(self, link):
+        RNS.log(f"Peer disconnected from {self.destination}", RNS.LOG_DEBUG)
+
+    def remote_identified(self, link, identity):
+        self.active_links[link.link_id] = link
+        RNS.log(f"Peer identified as {link.get_remote_identity()} on {link}", RNS.LOG_DEBUG)
+
+    def handle_list(self, path, data, request_id, remote_identity, requested_at):
+        RNS.log(f"List request from remote {remote_identity}", RNS.LOG_DEBUG)
+        if not remote_identity:             return self.RES_DISALLOWED.to_bytes(1, "big") + b"Not identified"
+        if not type(data) == dict:          return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Invalid request"
+        if not self.IDX_REPOSITORY in data: return self.RES_INVALID_REQ.to_bytes(1, "big") + b"No repository specified"
+
+        group_name, repository_name = self.parse_request_repository_path(data[self.IDX_REPOSITORY])
+        
+        # Check for_push permission if requested
+        for_push = data.get("for_push", False)
+        if for_push: access = self.resolve_permission(remote_identity, group_name, repository_name, self.PERM_WRITE)
+        else:        access = self.resolve_permission(remote_identity, group_name, repository_name, self.PERM_READ)
+        
+        if not access: return self.RES_NOT_FOUND.to_bytes(1, "big") + b"Not found"
+        else:
+            repository_path = self.groups[group_name]["repositories"][repository_name]["path"]
+
+            try:
+                RNS.log(f"Listing refs for {group_name}/{repository_name}", RNS.LOG_DEBUG)
+                
+                # Get HEAD symref
+                head_path = os.path.join(repository_path, "HEAD")                
+                head_ref = "master"  # Use "master" as default
+                if os.path.exists(head_path):
+                    with open(head_path, "rb") as fh:
+                        head_content = fh.read()
+                        if head_content.startswith(b"ref: "): head_ref = head_content[5:].strip().decode("utf-8", errors="ignore")
+                
+                execv = ["git", "for-each-ref", "--format", "%(objectname) %(refname)"]
+                result = subprocess.run(execv, cwd=repository_path, capture_output=True, check=False, text=True)
+                
+                if result.returncode != 0: return self.RES_REMOTE_FAIL.to_bytes(1, "big") + result.stderr.encode("utf-8")
+                
+                # Build response in format: refs + @<ref> HEAD
+                response_lines = result.stdout.strip()
+                
+                # Deduplicate refs - TODO: Re-evaluate this
+                seen_refs = set()
+                unique_lines = []
+                for line in response_lines.split('\n'):
+                    if not line.strip(): continue
+                    parts = line.split(' ', 1)
+                    if len(parts) == 2:
+                        ref_name = parts[1]
+                        if ref_name not in seen_refs:
+                            seen_refs.add(ref_name)
+                            unique_lines.append(line)
+                
+                if unique_lines: output = '\n'.join(unique_lines) + f"\n@{head_ref} HEAD\n"
+                else:            output = f"@{head_ref} HEAD\n"
+                
+                return b"\x00" + output.encode("utf-8")
+
+            except Exception as e:
+                RNS.log(f"Error while handling list request for {group_name}/{repository_name}: {e}", RNS.LOG_ERROR)
+                return self.RES_REMOTE_FAIL.to_bytes(1, "big") + str(e).encode("utf-8")
+
+    def handle_fetch(self, path, data, request_id, link_id, remote_identity, requested_at):
+        RNS.log(f"Fetch request from remote {remote_identity}", RNS.LOG_DEBUG)
+        with self.active_links_lock:
+            if not link_id in self.active_links: return self.RES_DISALLOWED.to_bytes(1, "big")  + b"Not identified"
+            else: link = self.active_links[link_id]
+
+        if not remote_identity:             return self.RES_DISALLOWED.to_bytes(1, "big")  + b"Not identified"
+        if not type(data) == dict:          return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Invalid request"
+        if not self.IDX_REPOSITORY in data: return self.RES_INVALID_REQ.to_bytes(1, "big") + b"No repository specified"
+
+        group_name, repository_name = self.parse_request_repository_path(data[self.IDX_REPOSITORY])
+        read_access = self.resolve_permission(remote_identity, group_name, repository_name, self.PERM_READ)
+        
+        if not read_access: return self.RES_NOT_FOUND.to_bytes(1, "big") + b"Not found"
+        else:
+            repository_path = self.groups[group_name]["repositories"][repository_name]["path"]
+            refs = data.get("refs", [])
+            
+            if not refs: return self.RES_INVALID_REQ.to_bytes(1, "big") + b"No refs specified"
+            
+            try:
+                ref_names = [r["ref"] for r in refs]
+                RNS.log(f"Fetching refs {ref_names} for {group_name}/{repository_name}", RNS.LOG_DEBUG)
+
+                if not hasattr(link, "temporary_directories"): link.temporary_directories = []
+                tmpdir = TemporaryDirectory()
+                link.temporary_directories.append(tmpdir)
+                tmp_path = tmpdir.name
+                RNS.log(f"Created {tmp_path} for {link}", RNS.LOG_DEBUG)
+                
+                bundle_path = os.path.join(tmp_path, "fetch.bundle")
+                execv = ["git", "bundle", "create", "--no-progress", bundle_path]
+
+                for r in refs:
+                    execv.append(r["ref"])
+                    # Per-ref have: The client already has this ancestor,
+                    # so the server can exclude objects reachable from it.
+                    if "have" in r and r["have"]:
+                        have_sha = r["have"]
+                        cat_result = subprocess.run(["git", "cat-file", "-t", have_sha], cwd=repository_path, capture_output=True, check=False)
+                        if cat_result.returncode == 0: execv.append(f"^{have_sha}")
+                        else: RNS.log(f"Client have-sha {have_sha} not found in repository, skipping", RNS.LOG_WARNING)
+
+                # Global have list: SHAs of objects the client already has.
+                # Exclude objects reachable from these to produce thin bundles.
+                have_shas = data.get("have", [])
+                for sha in have_shas:
+                    cat_result = subprocess.run(["git", "cat-file", "-t", sha], cwd=repository_path, capture_output=True, check=False)
+                    if cat_result.returncode == 0: execv.append(f"^{sha}")
+                    else: RNS.log(f"Client have-sha {sha} not found in repository, skipping", RNS.LOG_WARNING)
+
+                result = subprocess.run(execv, cwd=repository_path, capture_output=True, text=True, check=False)
+                if result.returncode != 0:
+                    if "empty bundle" in result.stderr.lower():
+                        # All objects reachable from the requested refs are already
+                        # available to the client. Return success with no bundle data.
+                        RNS.log(f"Empty bundle for {ref_names}, all objects already on client", RNS.LOG_DEBUG)
+                        return b"\x00"
+                    
+                    else: return self.RES_REMOTE_FAIL.to_bytes(1, "big") + result.stderr.encode("utf-8")
+                
+                return open(bundle_path, "rb"), {self.IDX_RESULT_CODE: self.RES_OK}
+
+            except Exception as e:
+                RNS.log(f"Error while handling fetch request for {group_name}/{repository_name}: {e}", RNS.LOG_ERROR)
+                return self.RES_REMOTE_FAIL.to_bytes(1, "big") + str(e).encode("utf-8")
+
+    def handle_push(self, path, data, request_id, remote_identity, requested_at):
+        RNS.log(f"Push request from remote {remote_identity}", RNS.LOG_DEBUG)
+        if not remote_identity:             return self.RES_DISALLOWED.to_bytes(1, "big")  + b"Not identified"
+        if not type(data) == dict:          return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Invalid request"
+        if not self.IDX_REPOSITORY in data: return self.RES_INVALID_REQ.to_bytes(1, "big") + b"No repository specified"
+
+        group_name, repository_name = self.parse_request_repository_path(data[self.IDX_REPOSITORY])
+        read_access  = self.resolve_permission(remote_identity, group_name, repository_name, self.PERM_READ)
+        write_access = self.resolve_permission(remote_identity, group_name, repository_name, self.PERM_WRITE)
+        
+        if not write_access: return self.RES_NOT_FOUND.to_bytes(1, "big") + b"Not found" if not read_access else self.RES_DISALLOWED.to_bytes(1, "big") + b"Not allowed"
+        else:
+            repository_path = self.groups[group_name]["repositories"][repository_name]["path"]
+            local_ref   = data.get("local_ref", "")
+            remote_ref  = data.get("remote_ref", "")
+            force       = data.get("force", False)
+            bundle_data = data.get("bundle", None)
+            operations  = data.get("operations", None)
+            
+            if bundle_data:
+                if not local_ref or not remote_ref: return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Missing ref specification"
+                try:
+                    RNS.log(f"Push {local_ref}:{remote_ref} to {group_name}/{repository_name}", RNS.LOG_DEBUG)
+                    
+                    with TemporaryDirectory() as tmpdir:
+                        bundle_path = os.path.join(tmpdir, "push.bundle")
+
+                        if isinstance(bundle_data, str): bundle_data = bundle_data.encode("utf-8")
+                        with open(bundle_path, "wb") as f: f.write(bundle_data)
+
+                        execv = ["git", "bundle", "verify", bundle_path]
+                        result = subprocess.run(execv, cwd=repository_path, capture_output=True, check=False)
+
+                        if result.returncode != 0: return self.RES_REMOTE_FAIL.to_bytes(1, "big") + result.stderr
+
+                        execv = ["git", "fetch", bundle_path, f"{local_ref}:{remote_ref}"]
+                        if force: execv.append("--force")
+
+                        result = subprocess.run(execv, cwd=repository_path, capture_output=True, check=False)
+
+                        if result.returncode != 0: return self.RES_REMOTE_FAIL.to_bytes(1, "big") + result.stderr
+
+                        return b"\x00"
+
+                except Exception as e:
+                    RNS.log(f"Error while handling push request for {group_name}/{repository_name}: {e}", RNS.LOG_ERROR)
+                    return self.RES_REMOTE_FAIL.to_bytes(1, "big") + str(e).encode("utf-8")
+
+            elif operations:
+                if not type(operations) == list: return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Invalid data for operations"
+
+                try:
+                    for op in operations:
+                        action = op.get("action", "")
+                        ref    = op.get("ref", "")
+                        sha    = op.get("sha", "")
+                        op_force = op.get("force", False)
+
+                        if action != "update_ref": return self.RES_INVALID_REQ.to_bytes(1, "big") + f"Unknown operation: {action}".encode("utf-8")
+                        if not ref.startswith("refs/"): return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Invalid ref"
+                        if not sha or len(sha) < 40: return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Invalid SHA"
+
+                        # Verify the target object exists in the repository
+                        cat_result = subprocess.run(["git", "cat-file", "-t", sha], cwd=repository_path, capture_output=True, check=False)
+                        if cat_result.returncode != 0: return self.RES_REMOTE_FAIL.to_bytes(1, "big") + f"Object {sha} does not exist in repository".encode("utf-8")
+
+                        # Check force flag: If the ref already exists and
+                        # points to a different SHA, the push must be forced.
+                        rev_result = subprocess.run(["git", "rev-parse", ref], cwd=repository_path, capture_output=True, text=True, check=False)
+                        if rev_result.returncode == 0:
+                            existing_sha = rev_result.stdout.strip()
+                            if existing_sha != sha and not op_force:
+                                return self.RES_DISALLOWED.to_bytes(1, "big") + f"Ref {ref} already exists at different SHA (force required)".encode("utf-8")
+
+                        RNS.log(f"Updating ref {ref} to {sha} in {group_name}/{repository_name}", RNS.LOG_DEBUG)
+                        execv = ["git", "update-ref", ref, sha]
+                        result = subprocess.run(execv, cwd=repository_path, capture_output=True, check=False)
+
+                        if result.returncode != 0: return self.RES_REMOTE_FAIL.to_bytes(1, "big") + result.stderr
+
+                    return b"\x00"
+
+                except Exception as e:
+                    RNS.log(f"Error while handling push operations for {group_name}/{repository_name}: {e}", RNS.LOG_ERROR)
+                    return self.RES_REMOTE_FAIL.to_bytes(1, "big") + str(e).encode("utf-8")
+
+            else: return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Invalid request data"
+
+    def handle_delete(self, path, data, request_id, remote_identity, requested_at):
+        RNS.log(f"Delete request from remote {remote_identity}", RNS.LOG_DEBUG)
+        if not remote_identity:             return self.RES_DISALLOWED.to_bytes(1, "big")  + b"Not identified"
+        if not type(data) == dict:          return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Invalid request"
+        if not self.IDX_REPOSITORY in data: return self.RES_INVALID_REQ.to_bytes(1, "big") + b"No repository specified"
+
+        group_name, repository_name = self.parse_request_repository_path(data[self.IDX_REPOSITORY])
+        read_access  = self.resolve_permission(remote_identity, group_name, repository_name, self.PERM_READ)
+        write_access = self.resolve_permission(remote_identity, group_name, repository_name, self.PERM_WRITE)
+        
+        if not write_access: return self.RES_NOT_FOUND.to_bytes(1, "big") + b"Not found" if not read_access else self.RES_DISALLOWED.to_bytes(1, "big") + b"Not allowed"
+        else:
+            repository_path = self.groups[group_name]["repositories"][repository_name]["path"]
+            ref_to_delete = data.get("ref", "")
+
+            if not ref_to_delete.startswith("refs/"): return self.RES_INVALID_REQ.to_bytes(1, "big") + b"Invalid ref"
+            try:
+                RNS.log(f"Deleting ref {ref_to_delete} in {group_name}/{repository_name}", RNS.LOG_DEBUG)
+                execv = ["git", "update-ref", "-d", ref_to_delete]
+                result = subprocess.run(execv, cwd=repository_path, capture_output=True, check=False)
+                
+                if result.returncode != 0: return self.RES_REMOTE_FAIL.to_bytes(1, "big") + result.stderr
+                else:                      return b"\x00"
+
+            except Exception as e:
+                RNS.log(f"Error while handling delete request for {group_name}/{repository_name}: {e}", RNS.LOG_ERROR)
+                return self.RES_REMOTE_FAIL.to_bytes(1, "big") + str(e).encode("utf-8")
+
+
+__default_rngit_config__ = '''# This is the default rngit config file.
+# You will need to edit it to specify repository locations and
+# access permissions.
+
+[rngit]
+
+# Automatic announce interval in minutes.
+# 6 hours by default.
+
+announce_interval = 360
+
+# An optional name for this node, included
+# in announces.
+
+# node_name = Anonymous Git Node
+
+[repositories]
+
+# You can define multiple repository groups, each with a path
+# to the directory containing "repo_name.git" directories.
+
+internal = /path/to/directory/with/git/repositories
+public = /another/path/to/directory/with/git/repositories
+showcase = /another/path/to/directory/with/git/repositories
+
+
+[access]
+
+# You can apply permissions for all repositories within
+# different repository collections like this:
+
+public = r:all, w:9710b86ba12c42d1d8f30f74fe509286
+internal = rw:9710b86ba12c42d1d8f30f74fe509286
+
+# By default, all repositories sourced from the con-
+# figured repository collection paths have no permissions
+# enabled, and will be neither readable nor writable.
+#
+# To configure permissions per repository, you must create
+# an ".allowed" file matching the repository name. If the
+# repository is in a folder called "my_project.git", create
+# a "my_project.allowed" file next to it. This file must
+# contain a permission statement on each line in the form of
+# "r=IDENTITY_HASH", "w=IDENTITY_HASH" or "rw=IDENTITY_HASH".
+# Instead of IDENTITY_HASH, you can also use "all" or "none".
+#
+# You can also make the allow-files executable, and have them
+# evaluate or source the permissions from somewhere else,
+# and then output the results to stdout.
+#
+# Additionally, you can create a "group.allowed" file in the
+# root of a repository group directory, which will apply to
+# all repositories within this group. The same syntax and
+# functionality applies here.
+
+
+[logging]
+# Valid log levels are 0 through 7:
+#   0: Log only critical information
+#   1: Log errors and lower log levels
+#   2: Log warnings and lower log levels
+#   3: Log notices and lower log levels
+#   4: Log info and lower (this is the default)
+#   5: Verbose logging
+#   6: Debug logging
+#   7: Extreme logging
+
+loglevel = 4
+
+'''.splitlines()
+
+if __name__ == "__main__": main()

RNS/Utilities/rnid.py

@@ -202,7 +202,7 @@ def main():
                 else:
                     try:
                         identity.to_file(args.generate)
-                        RNS.log("New identity written to "+str(args.generate))
+                        RNS.log(f"New identity {identity} written to {args.generate}")
                         exit(0)
                     except Exception as e:
                         RNS.log("An error ocurred while saving the generated Identity.", RNS.LOG_ERROR)

RNS/Utilities/rnir.py

@@ -56,7 +56,7 @@ def main():
         parser.add_argument('-v', '--verbose', action='count', default=0)
         parser.add_argument('-q', '--quiet', action='count', default=0)
         parser.add_argument("--exampleconfig", action='store_true', default=False, help="print verbose configuration example to stdout and exit")
-        parser.add_argument("--version", action="version", version="ir {version}".format(version=__version__))
+        parser.add_argument("--version", action="version", version="rnir {version}".format(version=__version__))
         
         args = parser.parse_args()
 
@@ -75,8 +75,5 @@ def main():
         print("")
         exit()
 
-__example_rns_config__ = '''# This is an example Identity Resolver file.
-'''
-
 if __name__ == "__main__":
     main()

RNS/Utilities/rnodeconf.py

@@ -49,9 +49,9 @@ import RNS
 RNS.logtimefmt      = "%H:%M:%S"
 RNS.compact_log_fmt = True
 
-program_version = "2.4.0"
-eth_addr = "0xFDabC71AC4c0C78C95aDDDe3B4FA19d6273c5E73"
-btc_addr = "35G9uWVzrpJJibzUwpNUQGQNFzLirhrYAH"
+program_version = "2.5.0"
+eth_addr = "0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E"
+btc_addr = "bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6"
 xmr_addr = "87HcDx6jRSkMQ9nPRd5K9hGGpZLn2s7vWETjMaVM5KfV4TD36NcYa8J8WSxhTSvBzzFpqDwp2fg5GX2moZ7VAP9QMZCZGET"
 
 rnode = None
@@ -97,10 +97,17 @@ class KISS():
     CMD_BT_CTRL     = 0x46
     CMD_BT_PIN      = 0x62
     CMD_DIS_IA      = 0x69
+    CMD_WIFI_MODE   = 0x6A
+    CMD_WIFI_SSID   = 0x6B
+    CMD_WIFI_PSK    = 0x6C
+    CMD_WIFI_CHN    = 0x6E
+    CMD_WIFI_IP     = 0x84
+    CMD_WIFI_NM     = 0x85
     CMD_BOARD       = 0x47
     CMD_PLATFORM    = 0x48
     CMD_MCU         = 0x49
     CMD_FW_VERSION  = 0x50
+    CMD_CFG_READ    = 0x6D
     CMD_ROM_READ    = 0x51
     CMD_ROM_WRITE   = 0x52
     CMD_ROM_WIPE    = 0x59
@@ -167,6 +174,7 @@ class ROM():
     MODEL_B9            = 0xB9
     MODEL_B4_TCXO       = 0x04 # The TCXO model codes are only used here to select the correct firmware,
     MODEL_B9_TCXO       = 0x09 # actual model codes in firmware is still 0xB4 and 0xB9.
+    
     PRODUCT_H32_V2      = 0xC0
     MODEL_C4            = 0xC4
     MODEL_C9            = 0xC9
@@ -175,6 +183,9 @@ class ROM():
     MODEL_C5            = 0xC5
     MODEL_CA            = 0xCA
 
+    PRODUCT_H32_V4      = 0xC3
+    MODEL_C8            = 0xC8 # 868/915/923 MHz with PA
+
     PRODUCT_TBEAM       = 0xE0
     MODEL_E4            = 0xE4
     MODEL_E9            = 0xE9
@@ -241,6 +252,12 @@ class ROM():
     ADDR_CONF_PINT = 0xB6
     ADDR_CONF_BSET = 0xB7
     ADDR_CONF_DIA  = 0xB9
+    ADDR_CONF_WIFI = 0xBA
+    ADDR_CONF_WCHN = 0xBB
+    ADDR_CONF_SSID = 0x00
+    ADDR_CONF_PSK  = 0x21
+    ADDR_CONF_IP   = 0x42
+    ADDR_CONF_NM   = 0x46
 
     INFO_LOCK_BYTE = 0x73
     CONF_OK_BYTE   = 0x73
@@ -270,6 +287,7 @@ products = {
     ROM.PRODUCT_T32_21: "LilyGO LoRa32 v2.1",
     ROM.PRODUCT_H32_V2: "Heltec LoRa32 v2",
     ROM.PRODUCT_H32_V3: "Heltec LoRa32 v3",
+    ROM.PRODUCT_H32_V4: "Heltec LoRa32 v4",
     ROM.PRODUCT_TECHO:  "LilyGO T-Echo",
     ROM.PRODUCT_RAK4631: "RAK4631",
     ROM.PRODUCT_OPENCOM_XL: "openCom XL",
@@ -314,6 +332,7 @@ models = {
     0xC9: [850000000, 950000000, 17, "850 - 950 MHz", "rnode_firmware_heltec32v2.zip", "SX1276"],
     0xC5: [420000000, 520000000, 22, "420 - 520 MHz", "rnode_firmware_heltec32v3.zip", "SX1268"],
     0xCA: [850000000, 950000000, 22, "850 - 950 MHz", "rnode_firmware_heltec32v3.zip", "SX1262"],
+    0xC8: [860000000, 930000000, 28, "850 - 950 MHz", "rnode_firmware_heltec32v4pa.zip", "SX1262"],
     0xC6: [420000000, 520000000, 22, "420 - 520 MHz", "rnode_firmware_heltec_t114.zip", "SX1268"],
     0xC7: [850000000, 950000000, 22, "850 - 950 MHz", "rnode_firmware_heltec_t114.zip", "SX1262"],
     0xE4: [420000000, 520000000, 17, "420 - 520 MHz", "rnode_firmware_tbeam.zip", "SX1278"],
@@ -396,6 +415,7 @@ class RNode():
         self.platform = None
         self.mcu = None
         self.eeprom = None
+        self.cfg_sector = None
         self.major_version = None
         self.minor_version = None
         self.version = None
@@ -455,12 +475,17 @@ class RNode():
                         in_frame = False
                         data_buffer = b""
                         command_buffer = b""
+                    elif (in_frame and byte == KISS.FEND and command == KISS.CMD_CFG_READ):
+                        self.cfg_sector = data_buffer
+                        in_frame = False
+                        data_buffer = b""
+                        command_buffer = b""
                     elif (byte == KISS.FEND):
                         in_frame = True
                         command = KISS.CMD_UNKNOWN
                         data_buffer = b""
                         command_buffer = b""
-                    elif (in_frame and len(data_buffer) < 512):
+                    elif (in_frame and len(data_buffer) < 1024):
                         if (len(data_buffer) == 0 and command == KISS.CMD_UNKNOWN):
                             command = byte
                         elif (command == KISS.CMD_ROM_READ):
@@ -474,6 +499,17 @@ class RNode():
                                         byte = KISS.FESC
                                     escape = False
                                 data_buffer = data_buffer+bytes([byte])
+                        elif (command == KISS.CMD_CFG_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
+                                data_buffer = data_buffer+bytes([byte])
                         elif (command == KISS.CMD_DATA):
                             if (byte == KISS.FESC):
                                 escape = True
@@ -782,6 +818,92 @@ class RNode():
         if written != len(kiss_command):
             raise IOError("An IO error occurred while sending firmware update command to device")
 
+    def set_wifi_mode(self, mode):
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_WIFI_MODE, mode])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while sending wifi mode command to device")
+
+    def set_wifi_channel(self, channel):
+        try: ch = int(channel)
+        except: raise ValueError("Invalid WiFi channel")
+        if ch < 1 or ch > 14: raise ValueError("Invalid WiFi channel")
+        ch_data = bytes([ch])
+        data = KISS.escape(ch_data)
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_WIFI_CHN])+data+bytes([KISS.FEND])
+
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while sending wifi channel to device")
+
+    def set_wifi_ip(self, ip):
+        if ip == None: ip_data = bytes([0x00, 0x00, 0x00, 0x00])
+        else:
+            ip_data = b""
+            if not type(ip) == str: raise TypeError("Invalid IP address")
+            octets = ip.split(".")
+            if not len(octets) == 4: raise ValueError("Invalid IP address length")
+            try:
+                for i in range(0, 4):
+                    octet = int(octets[i])
+                    if octet < 0 or octet > 255: raise ValueError("Invalid IP octet value")
+                    else: ip_data += bytes([octet])
+            except Exception as e:
+                raise ValueError(f"Could not decode IP address octet: {e}")
+        
+        data = KISS.escape(ip_data)
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_WIFI_IP])+data+bytes([KISS.FEND])
+
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command): raise IOError("An IO error occurred while sending wifi IP address to device")
+
+    def set_wifi_nm(self, nm):
+        if nm == None: nm_data = bytes([0x00, 0x00, 0x00, 0x00])
+        else:
+            nm_data = b""
+            if not type(nm) == str: raise TypeError("Invalid IP address")
+            octets = nm.split(".")
+            if not len(octets) == 4: raise ValueError("Invalid IP address length")
+            try:
+                for i in range(0, 4):
+                    octet = int(octets[i])
+                    if octet < 0 or octet > 255: raise ValueError("Invalid IP octet value")
+                    else: nm_data += bytes([octet])
+            except Exception as e:
+                raise ValueError(f"Could not decode IP address octet: {e}")
+        
+        data = KISS.escape(nm_data)
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_WIFI_NM])+data+bytes([KISS.FEND])
+
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command): raise IOError("An IO error occurred while sending wifi netmask to device")
+
+    def set_wifi_ssid(self, ssid):
+        if ssid == None: data = bytes([0x00])
+        else:
+            ssid_data = ssid.encode("utf-8")+bytes([0x00])
+            if len(ssid_data) < 0 or len(ssid_data) > 33: raise ValueError("Invalid SSID length")
+            data = KISS.escape(ssid_data)
+
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_WIFI_SSID])+data+bytes([KISS.FEND])
+
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while sending wifi SSID to device")
+
+    def set_wifi_psk(self, psk):
+        if psk == None: data = bytes([0x00])
+        else:
+            psk_data = psk.encode("utf-8")+bytes([0x00])
+            if len(psk_data) < 8 or len(psk_data) > 33: raise ValueError("Invalid psk length")
+            data = KISS.escape(psk_data)
+        
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_WIFI_PSK])+data+bytes([KISS.FEND])
+
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while sending wifi SSID to device")
+
     def initRadio(self):
         self.setFrequency()
         self.setBandwidth()
@@ -888,7 +1010,7 @@ class RNode():
         kiss_command = bytes([KISS.FEND, KISS.CMD_ROM_READ, 0x00, KISS.FEND])
         written = self.serial.write(kiss_command)
         if written != len(kiss_command):
-            raise IOError("An IO error occurred while configuring radio state")
+            raise IOError("An IO error occurred while downloading EEPROM")
 
         sleep(0.6)
         if self.eeprom == None:
@@ -897,6 +1019,15 @@ class RNode():
         else:
             self.parse_eeprom()
 
+    def download_cfg_sector(self):
+        self.cfg_sector = None
+        kiss_command = bytes([KISS.FEND, KISS.CMD_CFG_READ, 0x00, KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while downloading config sector")
+
+        sleep(0.6)
+
     def parse_eeprom(self):
         global squashvw;
         try:
@@ -1054,8 +1185,8 @@ class RNode():
                             print("     Always use a firmware downloaded as binaries or compiled from source")
                             print("     from one of the following locations:")
                             print("     ")
-                            print("        https://unsigned.io/rnode")
                             print("        https://github.com/markqvist/rnode_firmware")
+                            print("        https://github.com/liberatedsystems/RNode_Firmware_CE")
                             print("     ")
                             print("     You can reflash and bootstrap this device to a verifiable state")
                             print("     by using this utility. It is recommended to do so NOW!")
@@ -1097,7 +1228,7 @@ class RNode():
 
 selected_version = None
 selected_hash = None
-firmware_version_url = "https://unsigned.io/firmware/latest/?v="+program_version+"&variant="
+firmware_version_url          = "https://github.com/markqvist/rnode_firmware/releases/latest/download/release.json"
 fallback_firmware_version_url = "https://github.com/markqvist/rnode_firmware/releases/latest/download/release.json"
 def ensure_firmware_file(fw_filename):
     global selected_version, selected_hash, upd_nocheck
@@ -1138,9 +1269,15 @@ def ensure_firmware_file(fw_filename):
                 try:
                     # if custom firmware url, download latest release
                     if selected_version == None and fw_url == None:
-                        version_url = firmware_version_url+fw_filename
-                        RNS.log("Retrieving latest version info from "+version_url)
-                        urlretrieve(firmware_version_url+fw_filename, UPD_DIR+"/"+fw_filename+".version.latest")
+                        urlretrieve(firmware_version_url, UPD_DIR+"/release_info.json")
+                        import json
+                        with open(UPD_DIR+"/release_info.json", "rb") as rif:
+                            rdat = json.loads(rif.read())
+                            variant = rdat[fw_filename]
+                            with open(UPD_DIR+"/"+fw_filename+".version.latest", "wb") as verf:
+                                inf_str = str(variant["version"])+" "+str(variant["hash"])
+                                verf.write(inf_str.encode("utf-8"))
+
                     else:
                         if fw_url != None:
                             if selected_version == None:
@@ -1359,6 +1496,14 @@ def main():
         parser.add_argument("-B", "--bluetooth-off", action="store_true", help="Turn device bluetooth off")
         parser.add_argument("-p", "--bluetooth-pair", action="store_true", help="Put device into bluetooth pairing mode")
 
+        parser.add_argument("-w", "--wifi", action="store", metavar="mode", default=None, help="Set WiFi mode (OFF, AP or STATION)")
+        parser.add_argument("--channel", action="store", metavar="channel", default=None, help="Set WiFi channel")
+        parser.add_argument("--ssid", action="store", metavar="ssid", default=None, help="Set WiFi SSID (NONE to delete)")
+        parser.add_argument("--psk", action="store", metavar="psk", default=None, help="Set WiFi PSK (NONE to delete)")
+        parser.add_argument("--show-psk", action="store_true", default=False, help="Display stored WiFi PSK")
+        parser.add_argument("--ip", action="store", metavar="ip", default=None, help="Set static WiFi IP address (NONE for DHCP)")
+        parser.add_argument("--nm", action="store", metavar="nm", default=None, help="Set static WiFi network mask (NONE for DHCP)")
+
         parser.add_argument("-D", "--display", action="store", metavar="i", type=int, default=None, help="Set display intensity (0-255)")
         parser.add_argument("-t", "--timeout", action="store", metavar="s", type=int, default=None, help="Set display timeout in seconds, 0 to disable")
         parser.add_argument("-R", "--rotation", action="store", metavar="rotation", type=int, default=None, help="Set display rotation, valid values are 0 through 3")
@@ -1403,13 +1548,14 @@ def main():
         args = parser.parse_args()
 
         def print_donation_block():
-            print("  Ethereum : "+eth_addr)
-            print("  Bitcoin  : "+btc_addr)
-            print("  Monero   : "+xmr_addr)
-            print("  Ko-Fi    : https://ko-fi.com/markqvist")
+            print("  Ethereum  : "+eth_addr)
+            print("  Bitcoin   : "+btc_addr)
+            print("  Monero    : "+xmr_addr)
+            print("  Ko-Fi     : https://ko-fi.com/markqvist")
+            print("  LiberaPay : https://liberapay.com/reticulum")
             print("")
-            print("  Info     : https://unsigned.io/")
-            print("  Code     : https://github.com/markqvist")
+            print("  Info      : https://reticulum.network")
+            print("  Code      : https://github.com/markqvist")
 
         if args.version:
             print("rnodeconf "+program_version)
@@ -1730,13 +1876,14 @@ def main():
             print("[6]  LilyGO T-Beam")
             print("[7]  Heltec LoRa32 v2")
             print("[8]  Heltec LoRa32 v3")
-            print("[9]  LilyGO LoRa T3S3")
-            print("[10] RAK4631")
-            print("[11] LilyGo T-Echo")
-            print("[12] LilyGO T-Beam Supreme")
-            print("[13] LilyGO T-Deck")
-            print("[14] Heltec T114")
-            print("[15] Seeed XIAO ESP32S3 Wio-SX1262")
+            print("[9]  Heltec LoRa32 v4")
+            print("[10] LilyGO LoRa T3S3")
+            print("[11] RAK4631")
+            print("[12] LilyGo T-Echo")
+            print("[13] LilyGO T-Beam Supreme")
+            print("[14] LilyGO T-Deck")
+            print("[15] Heltec T114")
+            print("[16] Seeed XIAO ESP32S3 Wio-SX1262")
             print("")
             print("---------------------------------------------------------------------------")
             print("\nEnter the number that matches your device type:\n? ", end="")
@@ -1745,7 +1892,7 @@ def main():
             try:
                 c_dev = int(input())
                 c_mod = False
-                if c_dev < 1 or c_dev > 15:
+                if c_dev < 1 or c_dev > 16:
                     raise ValueError()
                 elif c_dev == 1:
                     selected_product = ROM.PRODUCT_RNODE
@@ -1782,7 +1929,7 @@ def main():
                     print("who would like to experiment with it. Hit enter to continue.")
                     print("---------------------------------------------------------------------------")
                     input()
-                elif c_dev == 12:
+                elif c_dev == 13:
                     selected_product = ROM.PRODUCT_TBEAM_S_V1
                     clear()
                     print("")
@@ -1798,7 +1945,7 @@ def main():
                     print("who would like to experiment with it. Hit enter to continue.")
                     print("---------------------------------------------------------------------------")
                     input()
-                elif c_dev == 13:
+                elif c_dev == 14:
                     selected_product = ROM.PRODUCT_TDECK
                     clear()
                     print("")
@@ -1873,7 +2020,7 @@ def main():
                     print("who would like to experiment with it. Hit enter to continue.")
                     print("---------------------------------------------------------------------------")
                     input()
-                elif c_dev == 9:
+                elif c_dev == 10:
                     selected_product = ROM.PRODUCT_RNODE
                     c_mod = True
                     clear()
@@ -1902,7 +2049,21 @@ def main():
                     print("who would like to experiment with it. Hit enter to continue.")
                     print("---------------------------------------------------------------------------")
                     input()
-                elif c_dev == 10:
+                elif c_dev == 9:
+                    selected_product = ROM.PRODUCT_H32_V4
+                    clear()
+                    print("")
+                    print("---------------------------------------------------------------------------")
+                    print("                      Heltec LoRa32 v4 RNode Installer")
+                    print("")
+                    print("Important! Using RNode firmware on Heltec devices should currently be")
+                    print("considered experimental. It is not intended for production or critical use.")
+                    print("")
+                    print("The currently supplied firmware is provided AS-IS as a courtesy to those")
+                    print("who would like to experiment with it. Hit enter to continue.")
+                    print("---------------------------------------------------------------------------")
+                    input()
+                elif c_dev == 11:
                     selected_product = ROM.PRODUCT_RAK4631
                     clear()
                     print("")
@@ -1915,7 +2076,7 @@ def main():
                     print("who would like to experiment with it. Hit enter to continue.")
                     print("---------------------------------------------------------------------------")
                     input()
-                elif c_dev == 11:
+                elif c_dev == 12:
                     selected_product = ROM.PRODUCT_TECHO
                     clear()
                     print("")
@@ -1928,7 +2089,7 @@ def main():
                     print("who would like to experiment with it. Hit enter to continue.")
                     print("---------------------------------------------------------------------------")
                     input()
-                elif c_dev == 14:
+                elif c_dev == 15:
                     selected_product = ROM.PRODUCT_HELTEC_T114
                     clear()
                     print("")
@@ -1941,7 +2102,7 @@ def main():
                     print("who would like to experiment with it. Hit enter to continue.")
                     print("---------------------------------------------------------------------------")
                     input()
-                elif c_dev == 15:
+                elif c_dev == 16:
                     selected_product = ROM.PRODUCT_XIAO_S3
                     clear()
                     print("")
@@ -2264,6 +2425,7 @@ def main():
                 print("[2] 868 MHz")
                 print("[3] 915 MHz")
                 print("[4] 923 MHz")
+                print("\n? ", end="")
                 try:
                     c_model = int(input())
                     if c_model < 1 or c_model > 4:
@@ -2278,6 +2440,24 @@ def main():
                     print("That band does not exist, exiting now.")
                     exit()
             
+            elif selected_product == ROM.PRODUCT_H32_V4:
+                selected_mcu = ROM.MCU_ESP32
+                print("\nWhat band is this Heltec LoRa32 V4 for?\n")
+                print("[1] 868 MHz (28 dBm output)")
+                print("[2] 915 MHz (28 dBm output)")
+                print("[3] 923 MHz (28 dBm output)")
+                print("\n? ", end="")
+                try:
+                    c_model = int(input())
+                    if c_model < 1 or c_model > 3:
+                        raise ValueError()
+                    else:
+                        selected_model = ROM.MODEL_C8
+                        selected_platform = ROM.PLATFORM_ESP32
+                except Exception as e:
+                    print("That band does not exist, exiting now.")
+                    exit()
+            
             elif selected_product == ROM.PRODUCT_HELTEC_T114:
                 selected_mcu = ROM.MCU_NRF52
                 print("\nWhat band is this Heltec T114 for?\n")
@@ -2285,6 +2465,7 @@ def main():
                 print("[2] 868 MHz")
                 print("[3] 915 MHz")
                 print("[4] 923 MHz")
+                print("\n? ", end="")
                 try:
                     c_model = int(input())
                     if c_model < 1 or c_model > 4:
@@ -2304,6 +2485,7 @@ def main():
                 print("\nWhat band is this XIAO esp32s3 wio module for?\n")
                 print("[1] 433 MHz")
                 print("[2] 868 MHz")
+                print("\n? ", end="")
                 try:
                     c_model = int(input())
                     if c_model < 1 or c_model > 2:
@@ -2875,6 +3057,24 @@ def main():
                             "0x210000",UPD_DIR+"/"+selected_version+"/console_image.bin",
                             "0x8000",  UPD_DIR+"/"+selected_version+"/rnode_firmware_heltec32v3.partitions",
                         ]
+                    elif fw_filename == "rnode_firmware_heltec32v4pa.zip":
+                        return [
+                            sys.executable, flasher,
+                            "--chip", "esp32-s3",
+                            "--port", args.port,
+                            "--baud", args.baud_flash,
+                            "--before", "default_reset",
+                            "--after", "hard_reset",
+                            "write_flash", "-z",
+                            "--flash_mode", "dio",
+                            "--flash_freq", "80m",
+                            "--flash_size", "16MB",
+                            "0xe000",  UPD_DIR+"/"+selected_version+"/rnode_firmware_heltec32v4pa.boot_app0",
+                            "0x0",     UPD_DIR+"/"+selected_version+"/rnode_firmware_heltec32v4pa.bootloader",
+                            "0x10000", UPD_DIR+"/"+selected_version+"/rnode_firmware_heltec32v4pa.bin",
+                            "0x210000",UPD_DIR+"/"+selected_version+"/console_image.bin",
+                            "0x8000",  UPD_DIR+"/"+selected_version+"/rnode_firmware_heltec32v4pa.partitions",
+                        ]
                     elif fw_filename == "rnode_firmware_featheresp32.zip":
                         if numeric_version >= 1.55:
                             return [
@@ -3498,17 +3698,14 @@ def main():
                     graceful_exit()
 
             if args.config:
+                rnode.download_cfg_sector()
                 eeprom_reserved = 200
-                if rnode.platform == ROM.PLATFORM_ESP32:
-                    eeprom_size = 296
-                elif rnode.platform == ROM.PLATFORM_NRF52:
-                    eeprom_size = 296
-                else:
-                    eeprom_size = 4096
+                if rnode.platform == ROM.PLATFORM_ESP32: eeprom_size = 296
+                elif rnode.platform == ROM.PLATFORM_NRF52: eeprom_size = 296
+                else: eeprom_size = 4096
 
                 eeprom_offset = eeprom_size-eeprom_reserved
-                def ea(a):
-                    return a+eeprom_offset
+                def ea(a): return a+eeprom_offset
                 ec_bt   = rnode.eeprom[ROM.ADDR_CONF_BT]
                 ec_dint = rnode.eeprom[ROM.ADDR_CONF_DINT]
                 ec_dadr = rnode.eeprom[ROM.ADDR_CONF_DADR]
@@ -3518,40 +3715,89 @@ def main():
                 ec_pint = rnode.eeprom[ROM.ADDR_CONF_PINT]
                 ec_bset = rnode.eeprom[ROM.ADDR_CONF_BSET]
                 ec_dia  = rnode.eeprom[ROM.ADDR_CONF_DIA]
+                ec_wifi = rnode.eeprom[ROM.ADDR_CONF_WIFI]
+                ec_wchn = rnode.eeprom[ROM.ADDR_CONF_WCHN]
+                ec_ssid = None
+                ec_psk  = None
+                ec_ip   = None
+                ec_nm   = None
+
+                if ec_wchn < 1 or ec_wchn > 14: ec_wchn = 1
+                if rnode.cfg_sector:
+                    ssid_bytes = b""
+                    for i in range(0, 32):
+                        byte = rnode.cfg_sector[ROM.ADDR_CONF_SSID+i]
+                        if byte == 0xFF: byte = 0x00
+                        if byte == 0x00: break
+                        else: ssid_bytes += bytes([byte])
+
+                    try: ec_ssid = ssid_bytes.decode("utf-8")
+                    except Exception as e: print(f"Error: Could not decode WiFi SSID read from device")
+
+                    psk_bytes = b""
+                    for i in range(0, 32):
+                        byte = rnode.cfg_sector[ROM.ADDR_CONF_PSK+i]
+                        if byte == 0xFF: byte = 0x00
+                        if byte == 0x00: break
+                        else: psk_bytes += bytes([byte])
+
+                    ip_bytes = b""
+                    for i in range(0, 4):
+                        byte = rnode.cfg_sector[ROM.ADDR_CONF_IP+i]
+                        ip_bytes += bytes([byte])
+                    if len(ip_bytes) == 4: ec_ip = f"{int(ip_bytes[0])}.{int(ip_bytes[1])}.{int(ip_bytes[2])}.{int(ip_bytes[3])}"
+                    if ec_ip == "255.255.255.255" or ec_ip == "0.0.0.0": ec_ip = None
+
+                    nm_bytes = b""
+                    for i in range(0, 4):
+                        byte = rnode.cfg_sector[ROM.ADDR_CONF_NM+i]
+                        nm_bytes += bytes([byte])
+                    if len(nm_bytes) == 4: ec_nm = f"{int(nm_bytes[0])}.{int(nm_bytes[1])}.{int(nm_bytes[2])}.{int(nm_bytes[3])}"
+                    if ec_nm == "255.255.255.255" or ec_nm == "0.0.0.0": ec_nm = None
+
+                    if ec_wifi == 0x02:
+                        ec_ip = "10.0.0.1"
+                        ec_nm = "255.255.255.0"
+
+                    try: ec_psk = psk_bytes.decode("utf-8")
+                    except Exception as e: print(f"Error: Could not decode WiFi PSK read from device")
+                    if not args.show_psk and ec_psk: ec_psk = "*"*len(ec_psk)
+
                 print("\nDevice configuration:")
-                if ec_bt == 0x73:
-                    print(f"  Bluetooth              : Enabled")
-                else:
-                    print(f"  Bluetooth              : Disabled")
-                if ec_dia == 0x00:
-                    print(f"  Interference avoidance : Enabled")
-                else:
-                    print(f"  Interference avoidance : Disabled")
+                if ec_bt == 0x73:       print(f"  Bluetooth              : Enabled")
+                else:                   print(f"  Bluetooth              : Disabled")
+                if ec_wifi == 0x01:     print(f"  WiFi                   : Enabled (Station)")
+                if ec_wifi == 0x02:     print(f"  WiFi                   : Enabled (AP)")
+                else:                   print(f"  WiFi                   : Disabled")
+                if ec_wifi == 0x01 or ec_wifi == 0x02:
+                    if not ec_wchn:     print(f"    Channel              : Unknown")
+                    else:               print(f"    Channel              : {ec_wchn}")
+                    if not ec_ssid:     print(f"    SSID                 : Not set")
+                    else:               print(f"    SSID                 : {ec_ssid}")
+                    if not ec_psk:      print(f"    PSK                  : Not set")
+                    else:               print(f"    PSK                  : {ec_psk}")
+                    if not ec_ip:       print(f"    IP Address           : DHCP")
+                    else:               print(f"    IP Address           : {ec_ip}")
+                    if ec_ip and ec_nm: print(f"    Network Mask         : {ec_nm}")
+                if ec_dia == 0x00:      print(f"  Interference avoidance : Enabled")
+                else:                   print(f"  Interference avoidance : Disabled")
                 print(    f"  Display brightness     : {ec_dint}")
-                if ec_dadr == 0xFF:
-                    print(f"  Display address        : Default")
-                else:
-                    print(f"  Display address        : {RNS.hexrep(ec_dadr, delimit=False)}")
-                if ec_bset == 0x73 and ec_dblk != 0x00:
-                    print(f"  Display blanking       : {ec_dblk}s")
-                else:
-                    print(f"  Display blanking       : Disabled")
+                if ec_dadr == 0xFF:     print(f"  Display address        : Default")
+                else:                   print(f"  Display address        : {RNS.hexrep(ec_dadr, delimit=False)}")
+                if ec_bset == 0x73 and ec_dblk != 0x00: print(f"  Display blanking       : {ec_dblk}s")
+                else:                                   print(f"  Display blanking       : Disabled")
                 if ec_drot != 0xFF:
-                    if ec_drot == 0x00:
-                        rstr = "Landscape"
-                    if ec_drot == 0x01:
-                        rstr = "Portrait"
-                    if ec_drot == 0x02:
-                        rstr = "Landscape 180"
-                    if ec_drot == 0x03:
-                        rstr = "Portrait 180"
+                    if ec_drot == 0x00: rstr = "Landscape"
+                    if ec_drot == 0x01: rstr = "Portrait"
+                    if ec_drot == 0x02: rstr = "Landscape 180"
+                    if ec_drot == 0x03: rstr = "Portrait 180"
                     print(f"  Display rotation       : {rstr}")
                 else:
                     print(f"  Display rotation       : Default")
-                if ec_pset == 0x73:
-                    print(f"  Neopixel Intensity     : {ec_pint}")
+                if ec_pset == 0x73: print(f"  Neopixel Intensity     : {ec_pint}")
                 print("")
 
+                rnode.leave()
                 graceful_exit()
 
             if args.eeprom_dump:
@@ -3662,6 +3908,77 @@ def main():
                 input()
                 rnode.leave()
 
+            if args.channel:
+                try:
+                    RNS.log(f"Setting WiFi channel to {args.channel}")
+                    rnode.set_wifi_channel(args.channel)
+                except Exception as e:
+                    print(f"Could not set WiFi channel: {e}")
+                    graceful_exit()
+
+            if args.ssid:
+                try:
+                    if args.ssid.lower() == "none":
+                        ssid_str = None
+                        RNS.log(f"Deleting WiFi SSID")
+                    else:
+                        ssid_str = str(args.ssid)
+                        RNS.log(f"Setting WiFi SSID to: {ssid_str}")
+                    rnode.set_wifi_ssid(ssid_str)
+                except Exception as e:
+                    print(f"Could not set WiFi SSID: {e}")
+                    graceful_exit()
+
+            if args.psk:
+                try:
+                    if args.psk.lower() == "none":
+                        psk_str = None
+                        RNS.log(f"Deleting WiFi PSK")
+                    else:
+                        psk_str = str(args.psk)
+                        RNS.log(f"Setting WiFi PSK")
+                    rnode.set_wifi_psk(psk_str)
+                except Exception as e:
+                    print(f"Could not set WiFi PSK: {e}")
+                    graceful_exit()
+
+            if args.ip:
+                try:
+                    if args.ip.lower() == "none":
+                        RNS.log(f"Setting WiFi IP to DHCP...")
+                        rnode.set_wifi_ip(None)
+                    else:
+                        RNS.log(f"Setting WiFi static IP to: {args.ip}")
+                        rnode.set_wifi_ip(args.ip)
+                except Exception as e:
+                    print(f"Could not set WiFi IP: {e}")
+                    graceful_exit()
+
+            if args.nm:
+                try:
+                    if args.nm.lower() == "none":
+                        RNS.log(f"Deleting WiFi static netmask configuration...")
+                        rnode.set_wifi_nm(None)
+                    else:
+                        RNS.log(f"Setting WiFi static netmask to: {args.nm}")
+                        rnode.set_wifi_nm(args.nm)
+                except Exception as e:
+                    print(f"Could not set WiFi netmask: {e}")
+                    graceful_exit()
+
+            if args.wifi:
+                try:
+                    mode = 0x00
+                    if   str(args.wifi).lower().startswith("sta"): mode = 0x01
+                    elif str(args.wifi).lower().startswith("ap"):  mode = 0x02
+                    if mode == 0x00: RNS.log(f"Disabling WiFi...")
+                    elif mode == 0x01: RNS.log(f"Setting WiFi to station mode")
+                    elif mode == 0x02: RNS.log(f"Setting WiFi to AP mode")
+                    rnode.set_wifi_mode(mode)
+                except Exception as e:
+                    print(f"Could not set WiFi mode: {e}")
+                    graceful_exit()
+
             if args.info:
                 if rnode.provisioned:
                     timestamp = struct.unpack(">I", rnode.made)[0]
@@ -4036,8 +4353,8 @@ def main():
                                     print("cases, and copies of the source code for both the RNode Firmware,")
                                     print("Reticulum and other utilities.")
                                     print("")
-                                    print("To activate the RNode Bootstrap Console, power up your RNode and press")
-                                    print("the reset button twice with a one second interval. The RNode will now")
+                                    print("To activate the RNode Bootstrap Console, power up your RNode and hold")
+                                    print("down the user button for 10+ seconds, then release. The RNode will now")
                                     print("reboot into console mode, and activate a WiFi access point for you to")
                                     print("connect to. The console is then reachable at: http://10.0.0.1")
                                     print("")

RNS/Utilities/rnpath.py

@@ -39,7 +39,8 @@ import argparse
 from RNS._version import __version__
 
 remote_link = None
-def connect_remote(destination_hash, auth_identity, timeout, no_output = False):
+output_rst_str = "\r                                                          \r"
+def connect_remote(destination_hash, auth_identity, timeout, no_output = False, purpose="management"):
     global remote_link, reticulum
     if not RNS.Transport.has_path(destination_hash):
         if not no_output:
@@ -51,7 +52,7 @@ def connect_remote(destination_hash, auth_identity, timeout, no_output = False):
             time.sleep(0.1)
             if time.time() - pr_time > timeout:
                 if not no_output:
-                    print("\r                                                          \r", end="")
+                    print(output_rst_str, end="")
                     print("Path request timed out")
                     exit(12)
 
@@ -60,98 +61,210 @@ def connect_remote(destination_hash, auth_identity, timeout, no_output = False):
     def remote_link_closed(link):
         if link.teardown_reason == RNS.Link.TIMEOUT:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("The link timed out, exiting now")
         elif link.teardown_reason == RNS.Link.DESTINATION_CLOSED:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("The link was closed by the server, exiting now")
         else:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Link closed unexpectedly, exiting now")
         exit(10)
 
     def remote_link_established(link):
         global remote_link
-        link.identify(auth_identity)
+        if purpose == "management": link.identify(auth_identity)
         remote_link = link
 
     if not no_output:
-        print("\r                                                          \r", end="")
+        print(output_rst_str, end="")
         print("Establishing link with remote transport instance...", end=" ")
         sys.stdout.flush()
 
-    remote_destination = RNS.Destination(remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, "rnstransport", "remote", "management")
+    if purpose == "management": remote_destination = RNS.Destination(remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, "rnstransport", "remote", "management")
+    elif purpose == "blackhole": remote_destination = RNS.Destination(remote_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, "rnstransport", "info", "blackhole")
     link = RNS.Link(remote_destination)
     link.set_link_established_callback(remote_link_established)
     link.set_link_closed_callback(remote_link_closed)
 
+def parse_hash(input_str):
+    dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
+    if len(input_str) != dest_len: raise ValueError("Hash length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+    try:
+        hash_bytes = bytes.fromhex(input_str)
+        return hash_bytes
+    except Exception as e: raise ValueError("Invalid hash entered. Check your input.")
+
 def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity, timeout, drop_queues,
                   drop_via, max_hops, remote=None, management_identity=None, remote_timeout=RNS.Transport.PATH_REQUEST_TIMEOUT,
-                  no_output=False, json=False):
+                  blackholed=False, blackhole=False, unblackhole=False, blackhole_duration=None, blackhole_reason=None,
+                  remote_blackhole_list=False, remote_blackhole_list_filter=None, no_output=False, json=False):
+
     global remote_link, reticulum
     reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity)
     if remote:
         try:
             dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-            if len(remote) != dest_len:
-                raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+            if len(remote) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
             try:
                 identity_hash = bytes.fromhex(remote)
                 remote_hash = RNS.Destination.hash_from_name_and_identity("rnstransport.remote.management", identity_hash)
-            except Exception as e:
-                raise ValueError("Invalid destination entered. Check your input.")
+            except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
 
             identity = RNS.Identity.from_file(os.path.expanduser(management_identity))
-            if identity == None:
-                raise ValueError("Could not load management identity from "+str(management_identity))
+            if identity == None: raise ValueError("Could not load management identity from "+str(management_identity))
 
-            try:
-                connect_remote(remote_hash, identity, remote_timeout, no_output)
-            except Exception as e:
-                raise e
+            try: connect_remote(remote_hash, identity, remote_timeout, no_output)
+            except Exception as e: raise e
 
         except Exception as e:
             print(str(e))
             exit(20)
 
-        while remote_link == None:
-            time.sleep(0.1)
+        while remote_link == None: time.sleep(0.1)
 
+    if blackholed or remote_blackhole_list:
+        blackholed_list = None
+        if blackholed:
+            if remote_link:
+                if not no_output:
+                    print(output_rst_str, end="")
+                    print("Listing blackholed identities on remote instances not yet implemented")
+                exit(255)
 
-    if table:
+            try: blackholed_list = reticulum.get_blackholed_identities()
+            except Exception as e:
+                print(f"Could not get blackholed identities from RNS instance: {e}")
+                exit(20)
+
+        elif remote_blackhole_list:
+            try: identity_hash = parse_hash(destination_hexhash)
+            except Exception as e:
+                print(f"{e}")
+                exit(20)
+
+            remote_hash = RNS.Destination.hash_from_name_and_identity("rnstransport.info.blackhole", identity_hash)
+            connect_remote(remote_hash, None, remote_timeout, no_output, purpose="blackhole")
+            while remote_link == None: time.sleep(0.1)
+
+            if not no_output:
+                print(output_rst_str, end="")
+                print("Sending request...", end=" ")
+                sys.stdout.flush()
+            receipt = remote_link.request("/list")
+            while not receipt.concluded(): time.sleep(0.1)
+            response = receipt.get_response()
+            if type(response) == dict:
+                blackholed_list = response
+                print(output_rst_str, end="")
+            else:
+                if not no_output:
+                    print(output_rst_str, end="")
+                    print("The remote request failed.")
+                exit(10)
+
+        else:
+            print(f"Nowhere to fetch blackhole list from")
+            exit(255)
+
+        if not blackholed_list:
+            print("No blackholed identity data available")
+            exit(20)
+
+        else:
+            rmlen = 64
+            def trunc(input_str):
+                if len(input_str) <= rmlen: return input_str
+                else: return f"{input_str[:rmlen-1]}…"
+
+            try:
+                now = time.time()
+                for identity_hash in blackholed_list:
+                    until      = blackholed_list[identity_hash]["until"]
+                    reason     = blackholed_list[identity_hash]["reason"]
+                    source     = blackholed_list[identity_hash]["source"]
+                    until_str  = f"for {RNS.prettytime(max(0, until-now))}" if until else "indefinitely"
+                    reason_str = f" ({trunc(reason)})" if reason else ""
+                    by_str     = f" by {RNS.prettyhexrep(source)}" if source != RNS.Transport.identity.hash else ""
+                    filter_str = f"{RNS.prettyhexrep(identity_hash)} {until_str} {reason_str} {by_str}"
+
+                    if not remote_blackhole_list:
+                        if destination_hexhash and not destination_hexhash in filter_str: continue
+                    else:
+                        if remote_blackhole_list_filter and not remote_blackhole_list_filter in filter_str: continue
+
+                    print(f"{RNS.prettyhexrep(identity_hash)} blackholed {until_str}{reason_str}{by_str}")
+
+            except Exception as e:
+                print(f"Error while displaying collected blackhole data: {e}")
+                exit(20)
+
+    elif blackhole:
+        if remote_link:
+            if not no_output:
+                print(output_rst_str, end="")
+                print("Blackholing identity on remote instances not yet implemented")
+            exit(255)
+
+        try:
+            identity_hash = parse_hash(destination_hexhash)
+            until = time.time()+blackhole_duration*60*60 if blackhole_duration else None
+            result = reticulum.blackhole_identity(identity_hash, until=until, reason=blackhole_reason)
+            if result == True: print(f"Blackholed identity {destination_hexhash}")
+            elif result == None: print(f"Identity {destination_hexhash} already blackholed")
+            else: print(f"Could not blackhole identity {destination_hexhash}")
+        
+        except Exception as e:
+            print(f"Could not blackhole identity: {e}")
+            exit(20)
+    
+    elif unblackhole:
+        if remote_link:
+            if not no_output:
+                print(output_rst_str, end="")
+                print("Blackholing identity on remote instances not yet implemented")
+            exit(255)
+
+        try:
+            identity_hash = parse_hash(destination_hexhash)
+            result = reticulum.unblackhole_identity(identity_hash)
+            if result == True: print(f"Lifted blackhole for identity {destination_hexhash}")
+            elif result == None: print(f"Identity {destination_hexhash} not blackholed")
+            else: print(f"Could not unblackhole identity {destination_hexhash}")
+        
+        except Exception as e:
+            print(f"Could not unblackhole identity: {e}")
+            exit(20)
+    
+    elif table:
         destination_hash = None
         if destination_hexhash != None:
             try:
                 dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-                if len(destination_hexhash) != dest_len:
-                    raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-                try:
-                    destination_hash = bytes.fromhex(destination_hexhash)
-                except Exception as e:
-                    raise ValueError("Invalid destination entered. Check your input.")
+                if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+                try: destination_hash = bytes.fromhex(destination_hexhash)
+                except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
             except Exception as e:
                 print(str(e))
                 sys.exit(1)
 
-        if not remote_link:
-            table = sorted(reticulum.get_path_table(max_hops=max_hops), key=lambda e: (e["interface"], e["hops"]) )
+        if not remote_link: table = sorted(reticulum.get_path_table(max_hops=max_hops), key=lambda e: (e["interface"], e["hops"]) )
         else:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Sending request...", end=" ")
                 sys.stdout.flush()
             receipt = remote_link.request("/path", data = ["table", destination_hash, max_hops])
-            while not receipt.concluded():
-                time.sleep(0.1)
+            while not receipt.concluded(): time.sleep(0.1)
             response = receipt.get_response()
             if response:
                 table = response
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
             else:
                 if not no_output:
-                    print("\r                                                          \r", end="")
+                    print(output_rst_str, end="")
                     print("The remote request failed. Likely authentication failure.")
                 exit(10)
 
@@ -160,20 +273,18 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
             import json
             for p in table:
                 for k in p:
-                    if isinstance(p[k], bytes):
-                        p[k] = RNS.hexrep(p[k], delimit=False)
+                    if isinstance(p[k], bytes): p[k] = RNS.hexrep(p[k], delimit=False)
 
             print(json.dumps(table))
             exit()
+        
         else:
             for path in table:
                 if destination_hash == None or destination_hash == path["hash"]:
                     displayed += 1
                     exp_str = RNS.timestamp_str(path["expires"])
-                    if path["hops"] == 1:
-                        m_str = " "
-                    else:
-                        m_str = "s"
+                    if path["hops"] == 1: m_str = " "
+                    else: m_str = "s"
                     print(RNS.prettyhexrep(path["hash"])+" is "+str(path["hops"])+" hop"+m_str+" away via "+RNS.prettyhexrep(path["via"])+" on "+path["interface"]+" expires "+RNS.timestamp_str(path["expires"]))
 
             if destination_hash != None and displayed == 0:
@@ -185,21 +296,17 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
         if destination_hexhash != None:
             try:
                 dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-                if len(destination_hexhash) != dest_len:
-                    raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-                try:
-                    destination_hash = bytes.fromhex(destination_hexhash)
-                except Exception as e:
-                    raise ValueError("Invalid destination entered. Check your input.")
+                if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+                try: destination_hash = bytes.fromhex(destination_hexhash)
+                except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
             except Exception as e:
                 print(str(e))
                 sys.exit(1)
 
-        if not remote_link:
-            table = reticulum.get_rate_table()
+        if not remote_link: table = reticulum.get_rate_table()
         else:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Sending request...", end=" ")
                 sys.stdout.flush()
             receipt = remote_link.request("/path", data = ["rates", destination_hash])
@@ -208,10 +315,10 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
             response = receipt.get_response()
             if response:
                 table = response
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
             else:
                 if not no_output:
-                    print("\r                                                          \r", end="")
+                    print(output_rst_str, end="")
                     print("The remote request failed. Likely authentication failure.")
                 exit(10)
 
@@ -220,15 +327,12 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
             import json
             for p in table:
                 for k in p:
-                    if isinstance(p[k], bytes):
-                        p[k] = RNS.hexrep(p[k], delimit=False)
+                    if isinstance(p[k], bytes): p[k] = RNS.hexrep(p[k], delimit=False)
 
             print(json.dumps(table))
             exit()
         else:
-            if len(table) == 0:
-                print("No information available")
-
+            if len(table) == 0: print("No information available")
             else:
                 displayed = 0
                 for entry in table:
@@ -274,7 +378,7 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
     elif drop_queues:
         if remote_link:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Dropping announce queues on remote instances not yet implemented")
             exit(255)
 
@@ -284,24 +388,20 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
     elif drop:
         if remote_link:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Dropping path on remote instances not yet implemented")
             exit(255)
 
         try:
             dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-            if len(destination_hexhash) != dest_len:
-                raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-            try:
-                destination_hash = bytes.fromhex(destination_hexhash)
-            except Exception as e:
-                raise ValueError("Invalid destination entered. Check your input.")
+            if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+            try: destination_hash = bytes.fromhex(destination_hexhash)
+            except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
         except Exception as e:
             print(str(e))
             sys.exit(1)
 
-        if reticulum.drop_path(destination_hash):
-            print("Dropped path to "+RNS.prettyhexrep(destination_hash))
+        if reticulum.drop_path(destination_hash): print("Dropped path to "+RNS.prettyhexrep(destination_hash))
         else:
             print("Unable to drop path to "+RNS.prettyhexrep(destination_hash)+". Does it exist?")
             sys.exit(1)
@@ -309,24 +409,20 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
     elif drop_via:
         if remote_link:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Dropping all paths via specific transport instance on remote instances yet not implemented")
             exit(255)
 
         try:
             dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-            if len(destination_hexhash) != dest_len:
-                raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-            try:
-                destination_hash = bytes.fromhex(destination_hexhash)
-            except Exception as e:
-                raise ValueError("Invalid destination entered. Check your input.")
+            if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+            try: destination_hash = bytes.fromhex(destination_hexhash)
+            except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
         except Exception as e:
             print(str(e))
             sys.exit(1)
 
-        if reticulum.drop_all_via(destination_hash):
-            print("Dropped all paths via "+RNS.prettyhexrep(destination_hash))
+        if reticulum.drop_all_via(destination_hash): print("Dropped all paths via "+RNS.prettyhexrep(destination_hash))
         else:
             print("Unable to drop paths via "+RNS.prettyhexrep(destination_hash)+". Does the transport instance exist?")
             sys.exit(1)
@@ -334,18 +430,15 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
     else:
         if remote_link:
             if not no_output:
-                print("\r                                                          \r", end="")
+                print(output_rst_str, end="")
                 print("Requesting paths on remote instances not implemented")
             exit(255)
 
         try:
             dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
-            if len(destination_hexhash) != dest_len:
-                raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
-            try:
-                destination_hash = bytes.fromhex(destination_hexhash)
-            except Exception as e:
-                raise ValueError("Invalid destination entered. Check your input.")
+            if len(destination_hexhash) != dest_len: raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+            try: destination_hash = bytes.fromhex(destination_hexhash)
+            except Exception as e: raise ValueError("Invalid destination entered. Check your input.")
         except Exception as e:
             print(str(e))
             sys.exit(1)
@@ -374,166 +467,57 @@ def program_setup(configdir, table, rates, drop, destination_hexhash, verbosity,
                 next_hop = RNS.prettyhexrep(next_hop_bytes)
                 next_hop_interface = reticulum.get_next_hop_if_name(destination_hash)
 
-                if hops != 1:
-                    ms = "s"
-                else:
-                    ms = ""
+                if hops != 1: ms = "s"
+                else: ms = ""
 
                 print("\rPath found, destination "+RNS.prettyhexrep(destination_hash)+" is "+str(hops)+" hop"+ms+" away via "+next_hop+" on "+next_hop_interface)
         else:
             print("\r                                                       \rPath not found")
             sys.exit(1)
 
-    
 
 def main():
     try:
-        parser = argparse.ArgumentParser(description="Reticulum Path Discovery Utility")
-
-        parser.add_argument("--config",
-            action="store",
-            default=None,
-            help="path to alternative Reticulum config directory",
-            type=str
-        )
-
-        parser.add_argument(
-            "--version",
-            action="version",
-            version="rnpath {version}".format(version=__version__)
-        )
-
-        parser.add_argument(
-            "-t",
-            "--table",
-            action="store_true",
-            help="show all known paths",
-            default=False
-        )
-
-        parser.add_argument(
-            "-m",
-            "--max",
-            action="store",
-            metavar="hops",
-            type=int,
-            help="maximum hops to filter path table by",
-            default=None
-        )
-
-        parser.add_argument(
-            "-r",
-            "--rates",
-            action="store_true",
-            help="show announce rate info",
-            default=False
-        )
-
-        parser.add_argument(
-            "-d",
-            "--drop",
-            action="store_true",
-            help="remove the path to a destination",
-            default=False
-        )
-
-        parser.add_argument(
-            "-D",
-            "--drop-announces",
-            action="store_true",
-            help="drop all queued announces",
-            default=False
-        )
-
-        parser.add_argument(
-            "-x", "--drop-via",
-            action="store_true",
-            help="drop all paths via specified transport instance",
-            default=False
-        )
-
-        parser.add_argument(
-            "-w",
-            action="store",
-            metavar="seconds",
-            type=float,
-            help="timeout before giving up",
-            default=RNS.Transport.PATH_REQUEST_TIMEOUT
-        )
-
-        parser.add_argument(
-            "-R",
-            action="store",
-            metavar="hash",
-            help="transport identity hash of remote instance to manage",
-            default=None,
-            type=str
-        )
-
-        parser.add_argument(
-            "-i",
-            action="store",
-            metavar="path",
-            help="path to identity used for remote management",
-            default=None,
-            type=str
-        )
-
-        parser.add_argument(
-            "-W",
-            action="store",
-            metavar="seconds",
-            type=float,
-            help="timeout before giving up on remote queries",
-            default=RNS.Transport.PATH_REQUEST_TIMEOUT
-        )
-        
-        parser.add_argument(
-            "-j",
-            "--json",
-            action="store_true",
-            help="output in JSON format",
-            default=False
-        )
-
-        parser.add_argument(
-            "destination",
-            nargs="?",
-            default=None,
-            help="hexadecimal hash of the destination",
-            type=str
-        )
-
+        parser = argparse.ArgumentParser(description="Reticulum Path Management Utility")
+        parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser.add_argument("--version", action="version", version="rnpath {version}".format(version=__version__))
+        parser.add_argument("-t", "--table", action="store_true", help="show all known paths", default=False)
+        parser.add_argument("-m", "--max", action="store", metavar="hops", type=int, help="maximum hops to filter path table by", default=None)
+        parser.add_argument("-r", "--rates", action="store_true", help="show announce rate info", default=False)
+        parser.add_argument("-d", "--drop", action="store_true", help="remove the path to a destination", default=False)
+        parser.add_argument("-D", "--drop-announces", action="store_true", help="drop all queued announces", default=False)
+        parser.add_argument("-x", "--drop-via", action="store_true", help="drop all paths via specified transport instance", default=False)
+        parser.add_argument("-w", action="store", metavar="seconds", type=float, help="timeout before giving up", default=RNS.Transport.PATH_REQUEST_TIMEOUT)
+        parser.add_argument("-R", action="store", metavar="hash", help="transport identity hash of remote instance to manage", default=None, type=str)
+        parser.add_argument("-i", action="store", metavar="path", help="path to identity used for remote management", default=None, type=str)
+        parser.add_argument("-W", action="store", metavar="seconds", type=float, help="timeout before giving up on remote queries", default=RNS.Transport.PATH_REQUEST_TIMEOUT)
+        parser.add_argument("-b", "--blackholed", action="store_true", help="list blackholed identities", default=False)
+        parser.add_argument("-B", "--blackhole", action="store_true", help="blackhole identity", default=False)
+        parser.add_argument("-U", "--unblackhole", action="store_true", help="unblackhole identity", default=False)
+        parser.add_argument(      "--duration", action="store", type=float, help="duration of blackhole enforcement in hours", default=None)
+        parser.add_argument(      "--reason", action="store", type=str, help="reason for blackholing identity", default=None)
+        parser.add_argument("-p", "--blackholed-list", action="store_true", help="view published blackhole list for remote transport instance", default=False)
+        parser.add_argument("-j", "--json", action="store_true", help="output in JSON format", default=False)
+        parser.add_argument("destination", nargs="?", default=None, help="hexadecimal hash of the destination", type=str)
+        parser.add_argument("list_filter", nargs="?", default=None, help="filter for remote blackhole list view", type=str)
         parser.add_argument('-v', '--verbose', action='count', default=0)
         
         args = parser.parse_args()
 
-        if args.config:
-            configarg = args.config
-        else:
-            configarg = None
+        if args.config: configarg = args.config
+        else: configarg = None
 
-        if not args.drop_announces and not args.table and not args.rates and not args.destination and not args.drop_via:
+        if not args.drop_announces and not args.table and not args.rates and not args.destination and not args.drop_via and not args.blackholed:
             print("")
             parser.print_help()
             print("")
         else:
-            program_setup(
-                configdir = configarg,
-                table = args.table,
-                rates = args.rates,
-                drop = args.drop,
-                destination_hexhash = args.destination,
-                verbosity = args.verbose,
-                timeout = args.w,
-                drop_queues = args.drop_announces,
-                drop_via = args.drop_via,
-                max_hops = args.max,
-                remote=args.R,
-                management_identity=args.i,
-                remote_timeout=args.W,
-                json=args.json,
-            )
+            program_setup(configdir = configarg, table = args.table, rates = args.rates, drop = args.drop, destination_hexhash = args.destination,
+                          verbosity = args.verbose, timeout = args.w, drop_queues = args.drop_announces, drop_via = args.drop_via, max_hops = args.max,
+                          remote=args.R, management_identity=args.i, remote_timeout=args.W, blackholed=args.blackholed, blackhole=args.blackhole,
+                          unblackhole=args.unblackhole, blackhole_duration=args.duration, blackhole_reason=args.reason, remote_blackhole_list=args.blackholed_list,
+                          remote_blackhole_list_filter=args.list_filter, json=args.json)
+
             sys.exit(0)
 
     except KeyboardInterrupt:
@@ -543,38 +527,23 @@ def main():
 def pretty_date(time=False):
     from datetime import datetime
     now = datetime.now()
-    if type(time) is int:
-        diff = now - datetime.fromtimestamp(time)
-    elif isinstance(time,datetime):
-        diff = now - time
-    elif not time:
-        diff = now - now
+    if type(time) is int: diff = now - datetime.fromtimestamp(time)
+    elif isinstance(time,datetime): diff = now - time
+    elif not time: diff = now - now
     second_diff = diff.seconds
     day_diff = diff.days
-    if day_diff < 0:
-        return ''
+    if day_diff < 0: return ''
     if day_diff == 0:
-        if second_diff < 10:
-            return str(second_diff) + " seconds"
-        if second_diff < 60:
-            return str(second_diff) + " seconds"
-        if second_diff < 120:
-            return "1 minute"
-        if second_diff < 3600:
-            return str(int(second_diff / 60)) + " minutes"
-        if second_diff < 7200:
-            return "an hour"
-        if second_diff < 86400:
-            return str(int(second_diff / 3600)) + " hours"
-    if day_diff == 1:
-        return "1 day"
-    if day_diff < 7:
-        return str(day_diff) + " days"
-    if day_diff < 31:
-        return str(int(day_diff / 7)) + " weeks"
-    if day_diff < 365:
-        return str(int(day_diff / 30)) + " months"
+        if second_diff < 10: return str(second_diff) + " seconds"
+        if second_diff < 60: return str(second_diff) + " seconds"
+        if second_diff < 120: return "1 minute"
+        if second_diff < 3600: return str(int(second_diff / 60)) + " minutes"
+        if second_diff < 7200: return "an hour"
+        if second_diff < 86400: return str(int(second_diff / 3600)) + " hours"
+    if day_diff == 1: return "1 day"
+    if day_diff < 7: return str(day_diff) + " days"
+    if day_diff < 31: return str(int(day_diff / 7)) + " weeks"
+    if day_diff < 365: return str(int(day_diff / 30)) + " months"
     return str(int(day_diff / 365)) + " years"
 
-if __name__ == "__main__":
-    main()
+if __name__ == "__main__": main()

RNS/Utilities/rnpkg.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+
+# Reticulum License
+#
+# Copyright (c) 2016-2025 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import RNS
+import argparse
+import time
+
+from RNS._version import __version__
+
+def program_setup(configdir, verbosity = 0, quietness = 0, service = False):
+    targetverbosity = verbosity-quietness
+
+    if service:
+        targetlogdest  = RNS.LOG_FILE
+        targetverbosity = None
+    else:
+        targetlogdest  = RNS.LOG_STDOUT
+
+    reticulum = RNS.Reticulum(configdir=configdir, verbosity=targetverbosity, logdest=targetlogdest)
+    exit(0)
+
+def main():
+    try:
+        parser = argparse.ArgumentParser(description="Reticulum Meta Package Manager")
+        parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser.add_argument('-v', '--verbose', action='count', default=0)
+        parser.add_argument('-q', '--quiet', action='count', default=0)
+        parser.add_argument("--exampleconfig", action='store_true', default=False, help="print verbose configuration example to stdout and exit")
+        parser.add_argument("--version", action="version", version="rnpkg {version}".format(version=__version__))
+        
+        args = parser.parse_args()
+
+        if args.exampleconfig:
+            print(__example_rnpkg_config__)
+            exit()
+
+        if args.config: configarg = args.config
+        else: configarg = None
+
+        program_setup(configdir = configarg, verbosity=args.verbose, quietness=args.quiet)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()
+
+__example_rnpkg_config__ = '''# This is an example package manager configuration file.
+'''
+
+if __name__ == "__main__": main()

RNS/Utilities/rnsd.py

@@ -160,6 +160,55 @@ instance_name = default
 # remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b5af27bca1776dc
 
 
+# For easier management, discovery and configuration of
+# networks with many individual transport instances,
+# you can specify a network identity to be used across
+# a set of instances. If sending interface discovery
+# announces, these will all be signed by the specified
+# network identity, and other nodes discovering your
+# interfaces will be able to identify that they belong
+# to the same network, even though they exist on different
+# transport nodes.
+
+# network_identity = ~/.reticulum/storage/identity/network
+
+
+# You can configure whether Reticulum should discover
+# available interfaces from other Transport Instances over
+# the network. If this option is enabled, Reticulum will
+# collect interface information discovered from the network.
+
+# discover_interfaces = No
+
+
+# If you only want to discover interfaces from specific
+# networks, you can provide a list of network identities
+# from which to discover interfaces. If this option is not
+# provided, interfaces will be discovered from all transport
+# instances on all connected networks.
+
+# interface_discovery_sources = 78616ff7c4b8d3886d67d494b440f333, cb127015e13aa6ea1e0a606cdc9123d0
+
+
+# It is possible to automatically bring up and connect new
+# interfaces discovered over the network. This option is
+# disabled by default, but allows you to specify a maximum
+# number of discovered interfaces to automatically connect.
+# Additionally, if this option is enabled, Reticulum will
+# also try to autoconnect available auto-discovered inter-
+# faces on startup, up to the maximum number specified.
+
+# autoconnect_discovered_interfaces = 0
+
+
+# To prevent interface discovery spamming, a valid crypto-
+# graphic stamp is required per announced interface. You
+# can configure the minimum required value to accept as
+# valid for discovered interfaces.
+
+# required_discovery_value = 14
+
+
 # You can configure Reticulum to panic and forcibly close
 # if an unrecoverable interface error occurs, such as the
 # hardware device for an interface disappearing. This is
@@ -180,6 +229,26 @@ instance_name = default
 # respond_to_probes = No
 
 
+# You can publish your local list of blackholed identities
+# for other transport instances to use for automatic,
+# network-wide blackhole management.
+
+# publish_blackhole = No
+
+# List of remote transport identities from which to auto-
+# matically source lists of blackholed identities.
+#
+# If you're connecting to a large external network, you
+# can use one or more external blackhole list to block
+# spammy and excessive announces onto your network. This
+# funtionality is especially useful if you're hosting public
+# entrypoints or gateways. The list source below provides a
+# functional example, but better, more timely maintained
+# lists probably exist in the community.
+
+# blackhole_sources = 521c87a83afb8f29e4455e77930b973b
+
+
 [logging]
 # Valid log levels are 0 through 7:
 #   0: Log only critical information

RNS/Utilities/rnsh/__init__.py

@@ -0,0 +1,41 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from ._version import __version__
+
+import os
+module_abs_filename = os.path.abspath(__file__)
+module_dir = os.path.dirname(module_abs_filename)
+
+def _get_version(): return __version__

RNS/Utilities/rnsh/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

RNS/Utilities/rnsh/args.py

@@ -0,0 +1,93 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import argparse
+import sys
+
+from RNS.Utilities.rnsh._version import __version__ as __rnsh_version__
+from RNS._version import __version__
+
+DEFAULT_SERVICE_NAME = "default"
+
+def setup_argument_parser():
+    parser = argparse.ArgumentParser(description="Reticulum Remote Shell Utility", epilog="When specifying a command to execute, separate rnsh\noptions from the command and its arguments with --\n\nFor example:\n  rnsh -l -- /bin/bash --login\n  rnsh <destination> -- ls -la /tmp", formatter_class=argparse.RawDescriptionHelpFormatter)
+
+    # Common options
+    parser.add_argument("--config", "-c", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+    parser.add_argument("--identity", "-i", action="store", default=None, help="path to identity file to use", type=str)
+    parser.add_argument("-v", "--verbose", action="count", default=0, help="increase verbosity")
+    parser.add_argument("-q", "--quiet", action="count", default=0, help="decrease verbosity")
+    parser.add_argument("-p", "--print-identity", action="store_true", default=False, help="print identity and destination info and exit")
+    parser.add_argument("--version", action="version", version="rnsh {rv} (protocol {pv})".format(rv=__version__, pv=__rnsh_version__))
+
+    # Listener options
+    parser.add_argument("-l", "--listen", action="store_true", default=False, help="listen (server) mode; any command specified after -- will be used as the default command when the initiator does not provide one or when remote command execution is disabled; if no command is specified, the default shell of the user running rnsh will be used")
+    parser.add_argument("-s", "--service", action="store", default=None, help="service name for identity file if not the default", type=str)
+    parser.add_argument("-b", "--announce",action="store", default=None,help="announce on startup and every PERIOD seconds; specify 0 to announce on startup only",metavar="PERIOD", type=int)
+    parser.add_argument("-a", "--allowed", action="append", default=None, metavar="HASH", type=str, help="allow this identity to connect (may be specified multiple times); allowed identities can also be specified in ~/.rnsh/allowed_identities or ~/.config/rnsh/allowed_identities, one hash per line")
+    parser.add_argument("-n", "--no-auth", action="store_true", default=False, help="disable authentication (allow any identity to connect)")
+    parser.add_argument("-A", "--remote-command-as-args", action="store_true", default=False, help="concatenate remote command to the argument list of the default program or shell")
+    parser.add_argument("-C", "--no-remote-command", action="store_true", default=False, help="disable executing command lines received from the remote initiator")
+
+    # Initiator options
+    parser.add_argument("-N", "--no-id", action="store_true", default=False, help="disable identity announcement on connect")
+    parser.add_argument("-m", "--mirror", action="store_true", default=False, help="return with the exit code of the remote process")
+    parser.add_argument("-w", "--timeout", action="store", default=None, help="connect and request timeout in seconds", metavar="SECONDS", type=float)
+
+    parser.add_argument("destination", nargs="?", default=None, help="hexadecimal hash of the destination to connect to", type=str)
+
+    return parser
+
+
+def parse_arguments(argv=None):
+    if argv is None: argv = sys.argv[1:]
+
+    # Split at -- to separate rnsh options from the command to execute.
+    # Everything before -- (or the entire argv if no --) goes to argparse.
+    # Everything after -- becomes the command list.
+    try:
+        split_idx = argv.index("--")
+        rnsh_argv = argv[:split_idx]
+        command = argv[split_idx + 1:]
+    except ValueError:
+        rnsh_argv = argv
+        command = []
+
+    parser = setup_argument_parser()
+    args = parser.parse_args(rnsh_argv)
+    args.command = command
+
+    if args.listen and not args.service: args.service = DEFAULT_SERVICE_NAME
+
+    return args, parser

RNS/Utilities/rnsh/exception.py

@@ -0,0 +1,60 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import contextlib
+from contextlib import AbstractContextManager
+import logging
+import sys
+
+
+class permit(AbstractContextManager):
+    """Context manager to allow specified exceptions
+
+    The specified exceptions will be allowed to bubble up. Other
+    exceptions are suppressed.
+
+    After a non-matching exception is suppressed, execution proceeds
+    with the next statement following the with statement.
+
+         with allow(KeyboardInterrupt):
+             time.sleep(300)
+         # Execution still resumes here if no KeyboardInterrupt
+    """
+
+    def __init__(self, *exceptions): self._exceptions = exceptions
+
+    def __enter__(self): pass
+
+    def __exit__(self, exctype, excinst, exctb):
+        return exctype is not None and not issubclass(exctype, self._exceptions)

RNS/Utilities/rnsh/helpers.py

@@ -0,0 +1,59 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import asyncio
+import time
+
+def bitwise_or_if(value: int, condition: bool, orval: int):
+    if not condition: return value
+    return value | orval
+
+def check_and(value: int, andval: int) -> bool:
+    return (value & andval) > 0
+
+class SleepRate:
+    def __init__(self, target_period: float):
+        self.target_period = target_period
+        self.last_wake = time.time()
+
+    def next_sleep_time(self) -> float:
+        old_last_wake = self.last_wake
+        self.last_wake = time.time()
+        next_wake = max(old_last_wake + 0.01, self.last_wake)
+        sleep_for = next_wake - self.last_wake
+        return sleep_for if sleep_for > 0 else 0
+
+    async def sleep_async(self): await asyncio.sleep(self.next_sleep_time())
+
+    def sleep_block(self): time.sleep(self.next_sleep_time())

RNS/Utilities/rnsh/initiator.py

@@ -0,0 +1,484 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import enum
+import functools
+import os
+import queue
+import shlex
+import signal
+import sys
+import termios
+import threading
+import time
+import tty
+from typing import Callable, TypeVar
+import RNS
+import RNS.Utilities.rnsh.exception as exception
+import RNS.Utilities.rnsh.process as process
+import RNS.Utilities.rnsh.retry as retry
+import RNS.Utilities.rnsh.session as session
+import re
+import contextlib
+
+import pwd
+import bz2
+import RNS.Utilities.rnsh.protocol as protocol
+import RNS.Utilities.rnsh.helpers as helpers
+import RNS.Utilities.rnsh.rnsh as rnsh
+
+_identity = None
+_reticulum = None
+_cmd: [str] | None = None
+DATA_AVAIL_MSG = "data available"
+_finished: asyncio.Event = None
+_retry_timer: retry.RetryThread | None = None
+_destination: RNS.Destination | None = None
+_loop: asyncio.AbstractEventLoop | None = None
+
+
+async def _check_finished(timeout: float = 0):
+    return _finished is not None and await process.event_wait(_finished, timeout=timeout)
+
+def _sigint_handler(sig, loop):
+    global _finished
+    RNS.log(f"{signal.Signals(sig).name}", RNS.LOG_DEBUG)
+    if _finished is not None: _finished.set()
+    else: raise KeyboardInterrupt()
+
+async def _spin_tty(until=None, msg=None, timeout=None):
+    i = 0
+    syms = "⢄⢂⢁⡁⡈⡐⡠"
+    if timeout != None: timeout = time.time()+timeout
+
+    print(msg+"  ", end=" ")
+    while (timeout == None or time.time()<timeout) and not until():
+        await asyncio.sleep(0.1)
+        print(("\b\b"+syms[i]+" "), end="")
+        sys.stdout.flush()
+        i = (i+1)%len(syms)
+
+    print("\r"+" "*len(msg)+"  \r", end="")
+
+    if timeout != None and time.time() > timeout: return False
+    else:                                         return True
+
+
+async def _spin_pipe(until: callable = None, msg=None, timeout: float | None = None) -> bool:
+    if timeout is not None: timeout += time.time()
+
+    while (timeout is None or time.time() < timeout) and not until():
+        if await _check_finished(0.1): raise asyncio.CancelledError()
+    
+    if timeout is not None and time.time() > timeout: return False
+    else: return True
+
+async def _spin(until: callable = None, msg=None, timeout: float | None = None, quiet: bool = False) -> bool:
+    if not quiet and os.isatty(1): return await _spin_tty(until, msg, timeout)
+    else:                          return await _spin_pipe(until, msg, timeout)
+
+_link: RNS.Link | None = None
+_remote_exec_grace = 2.0
+_pq = queue.Queue()
+
+
+class InitiatorState(enum.IntEnum):
+    IS_INITIAL      = 0
+    IS_LINKED     = 1
+    IS_WAIT_VERS  = 2
+    IS_RUNNING    = 3
+    IS_TERMINATE  = 4
+    IS_TEARDOWN   = 5
+
+def _client_link_closed(link):
+    if _finished: _finished.set()
+
+def _client_message_handler(message: RNS.MessageBase): _pq.put(message)
+
+def compute_target_rns_loglevel(verbosity: int, quietness: int, base_level: int = RNS.LOG_INFO) -> int:
+    try:
+        target = int(base_level) + int(verbosity) - int(quietness)
+        if target < RNS.LOG_CRITICAL: target = RNS.LOG_CRITICAL
+        if target > RNS.LOG_DEBUG:    target = RNS.LOG_DEBUG
+        return target
+    
+    except Exception: return base_level
+
+
+class RemoteExecutionError(Exception):
+    def __init__(self, msg): self.msg = msg
+
+
+async def _initiate_link(configdir, rnsconfigdir, identitypath=None, verbosity=0, quietness=0, noid=False, destination=None,
+                         timeout=RNS.Transport.PATH_REQUEST_TIMEOUT):
+    global _identity, _reticulum, _link, _destination, _remote_exec_grace
+
+    dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH // 8) * 2
+    if len(destination) != dest_len:
+        raise RemoteExecutionError(
+            "Allowed destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(
+                hex=dest_len, byte=dest_len // 2))
+    try:
+        destination_hash = bytes.fromhex(destination)
+    except Exception as e:
+        raise RemoteExecutionError("Invalid destination entered. Check your input.")
+
+    if _reticulum is None:
+        targetloglevel = compute_target_rns_loglevel(verbosity, quietness, RNS.LOG_ERROR)
+        RNS.logfile = os.path.join(configdir, "logfile")
+        _reticulum = RNS.Reticulum(configdir=rnsconfigdir, loglevel=targetloglevel, logdest=RNS.LOG_FILE)
+
+    if _identity is None:
+        _identity = rnsh.prepare_identity(identitypath)
+
+    if not RNS.Transport.has_path(destination_hash):
+        RNS.Transport.request_path(destination_hash)
+        RNS.log(f"Requesting path...", RNS.LOG_INFO)
+        if not await _spin(until=lambda: RNS.Transport.has_path(destination_hash), msg="Requesting path...",
+                           timeout=timeout, quiet=quietness > 0):
+            raise RemoteExecutionError("Path not found")
+
+    if _destination is None:
+        listener_identity = RNS.Identity.recall(destination_hash)
+        _destination = RNS.Destination(
+            listener_identity,
+            RNS.Destination.OUT,
+            RNS.Destination.SINGLE,
+            rnsh.APP_NAME
+        )
+
+    if _link is None or _link.status == RNS.Link.PENDING:
+        RNS.log("No link", RNS.LOG_DEBUG)
+        _link = RNS.Link(_destination)
+        _link.did_identify = False
+
+        _link.set_link_closed_callback(_client_link_closed)
+
+    RNS.log(f"Establishing link...", RNS.LOG_VERBOSE)
+    if not await _spin(until=lambda: _link.status == RNS.Link.ACTIVE, msg="Establishing link...",
+                       timeout=timeout, quiet=quietness > 0):
+        raise RemoteExecutionError("Could not establish link with " + RNS.prettyhexrep(destination_hash))
+
+    RNS.log("Have link", RNS.LOG_DEBUG)
+    if not noid and not _link.did_identify:
+        # Delay a tiny bit to allow listener to fully enter WAIT_IDENT state
+        await asyncio.sleep(min(1, _link.rtt * 1.1 + 0.05))
+        _link.identify(_identity)
+        _link.did_identify = True
+
+
+async def _handle_error(errmsg: RNS.MessageBase):
+    if isinstance(errmsg, protocol.ErrorMessage):
+        with contextlib.suppress(Exception):
+            if _link and _link.status == RNS.Link.ACTIVE:
+                _link.teardown()
+        await asyncio.sleep(0.1)
+        raise RemoteExecutionError(f"Remote error: {errmsg.msg}")
+
+
+async def initiate(configdir: str, rnsconfigdir:str, identitypath: str, verbosity: int, quietness: int, noid: bool, destination: str,
+                   timeout: float, command: [str] | None = None):
+    global _finished, _link
+    with process.TTYRestorer(sys.stdin.fileno()) as ttyRestorer:
+        loop = asyncio.get_running_loop()
+        state = InitiatorState.IS_INITIAL
+        data_buffer = bytearray(sys.stdin.buffer.read()) if not os.isatty(sys.stdin.fileno()) else bytearray()
+        line_buffer = bytearray()
+
+        await _initiate_link(configdir=configdir,
+                             rnsconfigdir=rnsconfigdir,
+                             identitypath=identitypath,
+                             verbosity=verbosity,
+                             quietness=quietness,
+                             noid=noid,
+                             destination=destination,
+                             timeout=timeout)
+
+        if not _link or _link.status not in [RNS.Link.ACTIVE, RNS.Link.PENDING]:
+            return 255
+
+        state = InitiatorState.IS_LINKED
+        outlet = session.RNSOutlet(_link)
+        channel = _link.get_channel()
+        protocol.register_message_types(channel)
+        channel.add_message_handler(_client_message_handler)
+
+        # Next step after linking and identifying: send version
+        # if not await _spin(lambda: messenger.is_outlet_ready(outlet), timeout=5, quiet=quietness > 0):
+        #     print("Error bringing up link")
+        #     return 253
+
+        channel.send(protocol.VersionInfoMessage())
+        try:
+            vm = _pq.get(timeout=max(outlet.rtt * 20, 5))
+            await _handle_error(vm)
+            if not isinstance(vm, protocol.VersionInfoMessage):
+                raise Exception("Invalid message received")
+            RNS.log(f"Server version info: sw {vm.sw_version} prot {vm.protocol_version}", RNS.LOG_DEBUG)
+            state = InitiatorState.IS_RUNNING
+        except queue.Empty:
+            print("Protocol error")
+            return 254
+
+        winch = False
+        def sigwinch_handler():
+            nonlocal winch
+            winch = True
+
+        esc = False
+        pre_esc = True
+        line_mode = False
+        line_flush = False
+        blind_write_count = 0
+        flush_chars = ["\x01", "\x03", "\x04", "\x05", "\x0c", "\x11", "\x13", "\x15", "\x19", "\t", "\x1A", "\x1B"]
+        def handle_escape(b):
+            nonlocal line_mode
+            if b == "?":
+                os.write(1, "\n\r\n\rSupported rnsh escape sequences:".encode("utf-8"))
+                os.write(1, "\n\r  ~~  Send the escape character by typing it twice".encode("utf-8"))
+                os.write(1, "\n\r  ~.  Terminate session and exit immediately".encode("utf-8"))
+                os.write(1, "\n\r  ~L  Toggle line-interactive mode".encode("utf-8"))
+                os.write(1, "\n\r  ~?  Display this quick reference\n\r".encode("utf-8"))
+                os.write(1, "\n\r(Escape sequences are only recognized immediately after newline)\n\r".encode("utf-8"))
+                return None
+            elif b == ".":
+                _link.teardown()
+                return None
+            elif b == "L":
+                line_mode = not line_mode
+                if line_mode:
+                    os.write(1, "\n\rLine-interactive mode enabled\n\r".encode("utf-8"))
+                else:
+                    os.write(1, "\n\rLine-interactive mode disabled\n\r".encode("utf-8"))
+                return None
+
+            return b
+
+        stdin_eof = False
+        def stdin():
+            nonlocal stdin_eof, pre_esc, esc, line_mode
+            nonlocal line_flush, blind_write_count
+            try:
+                in_data = process.tty_read(sys.stdin.fileno())
+                if in_data is not None:
+                    data = bytearray()
+                    for b in bytes(in_data):
+                        c = chr(b)
+                        if c == "\r":
+                            pre_esc = True
+                            line_flush = True
+                            data.append(b)
+                        elif line_mode and c in flush_chars:
+                            pre_esc = False
+                            line_flush = True
+                            data.append(b)
+                        elif line_mode and (c == "\b" or c == "\x7f"):
+                            pre_esc = False
+                            if len(line_buffer)>0:
+                                line_buffer.pop(-1)
+                                blind_write_count -= 1
+                                os.write(1, "\b \b".encode("utf-8"))
+                        elif pre_esc == True and c == "~":
+                            pre_esc = False
+                            esc = True
+                        elif esc == True:
+                            ret = handle_escape(c)
+                            if ret != None:
+                                if ret != "~":
+                                    data.append(ord("~"))
+                                data.append(ord(ret))
+                            esc = False
+                        else:
+                            pre_esc = False
+                            data.append(b)
+
+                    if not line_mode:
+                        data_buffer.extend(data)
+                    else:
+                        line_buffer.extend(data)
+                        if line_flush:
+                            data_buffer.extend(line_buffer)
+                            line_buffer.clear()
+                            os.write(1, ("\b \b"*blind_write_count).encode("utf-8"))
+                            line_flush = False
+                            blind_write_count = 0
+                        else:
+                            os.write(1, data)
+                            blind_write_count += len(data)
+
+            except EOFError:
+                if os.isatty(0):
+                    data_buffer.extend(process.CTRL_D)
+                stdin_eof = True
+                process.tty_unset_reader_callbacks(sys.stdin.fileno())
+
+        process.tty_add_reader_callback(sys.stdin.fileno(), stdin)
+
+        tcattr = None
+        rows, cols, hpix, vpix = (None, None, None, None)
+        try:
+            tcattr = termios.tcgetattr(0)
+            rows, cols, hpix, vpix = process.tty_get_winsize(0)
+        except:
+            try:
+                tcattr = termios.tcgetattr(1)
+                rows, cols, hpix, vpix = process.tty_get_winsize(1)
+            except:
+                try:
+                    tcattr = termios.tcgetattr(2)
+                    rows, cols, hpix, vpix = process.tty_get_winsize(2)
+                except:
+                    pass
+
+        await _spin(lambda: channel.is_ready_to_send(), "Waiting for channel...", 1, quietness > 0)
+        channel.send(protocol.ExecuteCommandMesssage(cmdline=command,
+                                                     pipe_stdin=not os.isatty(0),
+                                                     pipe_stdout=not os.isatty(1),
+                                                     pipe_stderr=not os.isatty(2),
+                                                     tcflags=tcattr,
+                                                     term=os.environ.get("TERM", None),
+                                                     rows=rows,
+                                                     cols=cols,
+                                                     hpix=hpix,
+                                                     vpix=vpix))
+
+        loop.add_signal_handler(signal.SIGWINCH, sigwinch_handler)
+        _finished = asyncio.Event()
+        loop.add_signal_handler(signal.SIGINT, functools.partial(_sigint_handler, signal.SIGINT, loop))
+        loop.add_signal_handler(signal.SIGTERM, functools.partial(_sigint_handler, signal.SIGTERM, loop))
+        mdu = _link.MDU - 16
+        sent_eof = False
+        last_winch = time.time()
+        sleeper = helpers.SleepRate(0.01)
+        processed = False
+        while not await _check_finished() and state in [InitiatorState.IS_RUNNING]:
+            try:
+                try:
+                    message = _pq.get(timeout=sleeper.next_sleep_time() if not processed else 0.0005)
+                    await _handle_error(message)
+                    processed = True
+                    if isinstance(message, protocol.StreamDataMessage):
+                        if message.stream_id == protocol.StreamDataMessage.STREAM_ID_STDOUT:
+                            if message.data and len(message.data) > 0:
+                                ttyRestorer.raw()
+                                RNS.log(f"stdout: {message.data}", RNS.LOG_DEBUG)
+                                os.write(1, message.data)
+                                sys.stdout.flush()
+                            if message.eof:
+                                os.close(1)
+                        if message.stream_id == protocol.StreamDataMessage.STREAM_ID_STDERR:
+                            if message.data and len(message.data) > 0:
+                                ttyRestorer.raw()
+                                RNS.log(f"stdout: {message.data}", RNS.LOG_DEBUG)
+                                os.write(2, message.data)
+                                sys.stderr.flush()
+                            if message.eof:
+                                os.close(2)
+                    elif isinstance(message, protocol.CommandExitedMessage):
+                        RNS.log(f"received return code {message.return_code}, exiting", RNS.LOG_DEBUG)
+                        return message.return_code
+                    elif isinstance(message, protocol.ErrorMessage):
+                        RNS.log(f"Remote error: {message.data}", RNS.LOG_ERROR)
+                        if message.fatal:
+                            _link.teardown()
+                            return 200
+
+                except queue.Empty:
+                    processed = False
+
+                if channel.is_ready_to_send():
+                    def compress_adaptive(buf: bytes):
+                        comp_tries = RNS.RawChannelWriter.COMPRESSION_TRIES
+                        comp_try = 1
+                        comp_success = False
+                        
+                        chunk_len = len(buf)
+                        if chunk_len > RNS.RawChannelWriter.MAX_CHUNK_LEN:
+                            chunk_len = RNS.RawChannelWriter.MAX_CHUNK_LEN
+                        chunk_segment = None
+
+                        chunk_segment = None
+                        max_data_len = channel.mdu - protocol.StreamDataMessage.OVERHEAD
+                        while chunk_len > 32 and comp_try < comp_tries:
+                            chunk_segment_length = int(chunk_len/comp_try)
+                            compressed_chunk = bz2.compress(buf[:chunk_segment_length])
+                            compressed_length = len(compressed_chunk)
+                            if compressed_length < max_data_len and compressed_length < chunk_segment_length:
+                                comp_success = True
+                                break
+                            else:
+                                comp_try += 1
+
+                        if comp_success:
+                            diff = max_data_len - len(compressed_chunk)
+                            chunk = compressed_chunk
+                            processed_length = chunk_segment_length
+                        else:
+                            chunk = bytes(buf[:max_data_len])
+                            processed_length = len(chunk)
+
+                        return comp_success, processed_length, chunk
+
+                    comp_success, processed_length, chunk = compress_adaptive(data_buffer)
+                    stdin = chunk
+                    data_buffer = data_buffer[processed_length:]
+                    eof = not sent_eof and stdin_eof and len(stdin) == 0
+                    if len(stdin) > 0 or eof:
+                        channel.send(protocol.StreamDataMessage(protocol.StreamDataMessage.STREAM_ID_STDIN, stdin, eof, comp_success))
+                        sent_eof = eof
+                        processed = True
+
+                # send window change, but rate limited
+                if winch and time.time() - last_winch > _link.rtt * 25:
+                    last_winch = time.time()
+                    winch = False
+                    with contextlib.suppress(Exception):
+                        r, c, h, v = process.tty_get_winsize(0)
+                        channel.send(protocol.WindowSizeMessage(r, c, h, v))
+                        processed = True
+            except RemoteExecutionError as e:
+                print(e.msg)
+                return 255
+            except Exception as ex:
+                print(f"Client exception: {ex}")
+                if _link and _link.status != RNS.Link.CLOSED:
+                    _link.teardown()
+                    return 127
+
+        RNS.log("Main loop done", RNS.LOG_DEBUG)
+        return 0

RNS/Utilities/rnsh/listener.py

@@ -0,0 +1,229 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+
+import asyncio
+import os
+import queue
+import shlex
+import signal
+import sys
+import termios
+import threading
+import time
+import tty
+from typing import Callable, TypeVar
+import RNS
+import RNS.Utilities.rnsh.exception as exception
+import RNS.Utilities.rnsh.process as process
+import RNS.Utilities.rnsh.retry as retry
+import RNS.Utilities.rnsh.session as session
+import re
+import contextlib
+
+import pwd
+import RNS.Utilities.rnsh.protocol as protocol
+import RNS.Utilities.rnsh.helpers as helpers
+import RNS.Utilities.rnsh.rnsh as rnsh
+
+
+_identity = None
+_reticulum = None
+_allow_all = False
+_allowed_file = None
+_allowed_identity_hashes = []
+_allowed_file_identity_hashes = []
+_cmd: [str] | None = None
+DATA_AVAIL_MSG = "data available"
+_finished: asyncio.Event = None
+_retry_timer: retry.RetryThread | None = None
+_destination: RNS.Destination | None = None
+_loop: asyncio.AbstractEventLoop | None = None
+_no_remote_command = True
+_remote_cmd_as_args = False
+
+
+async def _check_finished(timeout: float = 0):
+    return await process.event_wait(_finished, timeout=timeout)
+
+
+def _sigint_handler(sig, loop):
+    global _finished
+    RNS.log(f"Signal: {signal.Signals(sig).name}", RNS.LOG_DEBUG)
+    if _finished is not None: _finished.set()
+    else: raise KeyboardInterrupt()
+
+def _reload_allowed_file():
+    global _allowed_file, _allowed_file_identity_hashes
+    if _allowed_file != None:
+        try:
+            with open(_allowed_file, "r") as file:
+                dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH // 8) * 2
+                added = 0
+                line = 0
+                _allowed_file_identity_hashes = []
+                for allow in file.read().replace("\r", "").split("\n"):
+                    line += 1
+                    if len(allow) == dest_len:
+                        try:
+                            destination_hash = bytes.fromhex(allow)
+                            _allowed_file_identity_hashes.append(destination_hash)
+                            added += 1
+                        except Exception:
+                            RNS.log(f"Discarded invalid Identity hash in {_allowed_file} at line {line}", RNS.LOG_DEBUG)
+
+                ms = "y" if added == 1 else "ies"
+                RNS.log(f"Loaded {added} allowed identit{ms} from "+str(_allowed_file), RNS.LOG_DEBUG)
+        
+        except Exception as e: RNS.log(f"Error while reloading allowed indetities file: {e}", RNS.LOG_ERROR)
+
+def compute_target_rns_loglevel(verbosity: int, quietness: int, base_level: int = RNS.LOG_INFO) -> int:
+    try:
+        target = int(base_level) + int(verbosity) - int(quietness)
+        if target < RNS.LOG_CRITICAL: target = RNS.LOG_CRITICAL
+        if target > RNS.LOG_DEBUG:    target = RNS.LOG_DEBUG
+        return target
+    
+    except Exception: return base_level
+
+async def listen(configdir, rnsconfigdir, command, identitypath=None, service_name=None, verbosity=0, quietness=0, allowed=None,
+                 allowed_file=None, disable_auth=None, announce_period=900, no_remote_command=True, remote_cmd_as_args=False,
+                 loop: asyncio.AbstractEventLoop = None):
+    global _identity, _allow_all, _allowed_identity_hashes, _allowed_file, _allowed_file_identity_hashes
+    global _reticulum, _cmd, _destination, _no_remote_command, _remote_cmd_as_args, _finished
+
+    if not loop: loop = asyncio.get_running_loop()
+    if service_name is None or len(service_name) == 0:
+        service_name = "default"
+
+    RNS.log(f"Using service name {service_name}", RNS.LOG_INFO)
+
+    # More -v should increase verbosity (higher RNS.loglevel); -q should decrease it
+    targetloglevel = compute_target_rns_loglevel(verbosity, quietness, RNS.LOG_INFO)
+    _reticulum = RNS.Reticulum(configdir=rnsconfigdir, loglevel=targetloglevel)
+    _identity = rnsh.prepare_identity(identitypath, service_name)
+    _destination = RNS.Destination(_identity, RNS.Destination.IN, RNS.Destination.SINGLE, rnsh.APP_NAME)
+    
+    RNS.log(f"rnsh listening for commands on {RNS.prettyhexrep(_destination.hash)}", RNS.LOG_NOTICE)
+    
+    _cmd = command
+    if _cmd is None or len(_cmd) == 0:
+        shell = None
+        try: shell = pwd.getpwuid(os.getuid()).pw_shell
+        except Exception as e: RNS.log(f"Error looking up shell: {e}", RNS.LOG_ERROR)
+        RNS.log(f"Using {shell} for default command.", RNS.LOG_INFO)
+
+        # Ensure a sane shell default. Fall back to /bin/sh if lookup fails.
+        if not shell or len(shell) == 0: shell = "/bin/sh"
+        _cmd = [shell]
+    
+    else: RNS.log(f"Using command {shlex.join(_cmd)}", RNS.LOG_INFO)
+
+    _no_remote_command = no_remote_command
+    session.ListenerSession.allow_remote_command = not no_remote_command
+    _remote_cmd_as_args = remote_cmd_as_args
+    if (_cmd is None or len(_cmd) == 0 or _cmd[0] is None or len(_cmd[0]) == 0) \
+            and (_no_remote_command or _remote_cmd_as_args):
+        raise Exception(f"Unable to look up shell for {os.getlogin}, cannot proceed with -A or -C and no <program>.")
+
+    session.ListenerSession.default_command = _cmd
+    session.ListenerSession.remote_cmd_as_args = _remote_cmd_as_args
+
+    if disable_auth:
+        _allow_all = True
+        session.ListenerSession.allow_all = True
+    else:
+        if allowed_file is not None:
+            _allowed_file = allowed_file
+            _reload_allowed_file()
+
+        if allowed is not None:
+            for a in allowed:
+                try:
+                    dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH // 8) * 2
+                    if len(a) != dest_len:
+                        raise ValueError(
+                            "Allowed destination length is invalid, must be {hex} hexadecimal " +
+                            "characters ({byte} bytes).".format(
+                                hex=dest_len, byte=dest_len // 2))
+                    try:
+                        destination_hash = bytes.fromhex(a)
+                        _allowed_identity_hashes.append(destination_hash)
+                        session.ListenerSession.allowed_identity_hashes.append(destination_hash)
+                    except Exception:
+                        raise ValueError("Invalid destination entered. Check your input.")
+                
+                except Exception as e:
+                    RNS.log(f"Unhandled error: {e}", RNS.LOG_ERROR)
+                    RNS.trace_exception(e)
+                    exit(1)
+
+    if (len(_allowed_identity_hashes) < 1 and len(_allowed_file_identity_hashes) < 1) and not disable_auth:
+        RNS.log("Warning: No allowed identities configured, rnsh will not accept any connections!", RNS.LOG_WARNING)
+
+    def link_established(lnk: RNS.Link):
+        _reload_allowed_file()
+        session.ListenerSession.allowed_file_identity_hashes = _allowed_file_identity_hashes
+        session.ListenerSession(session.RNSOutlet.get_outlet(lnk), lnk.get_channel(), loop)
+    _destination.set_link_established_callback(link_established)
+
+    _finished = asyncio.Event()
+    signal.signal(signal.SIGINT, _sigint_handler)
+
+    if announce_period is not None: _destination.announce()
+
+    last_announce = time.time()
+    sleeper = helpers.SleepRate(0.01)
+
+    try:
+        while not await _check_finished():
+            if announce_period and 0 < announce_period < time.time() - last_announce:
+                last_announce = time.time()
+                _destination.announce()
+            if len(session.ListenerSession.sessions) > 0:
+                # no sleep if there's work to do
+                if not await session.ListenerSession.pump_all():
+                    await sleeper.sleep_async()
+            else:
+                await asyncio.sleep(0.25)
+    finally:
+        RNS.log("Shutting down", RNS.LOG_NOTICE)
+        await session.ListenerSession.terminate_all("Shutting down")
+        await asyncio.sleep(1)
+        links_still_active = list(filter(lambda l: l.status != RNS.Link.CLOSED, _destination.links))
+        for link in links_still_active:
+            if link.status not in [RNS.Link.CLOSED]:
+                link.teardown()
+                await asyncio.sleep(0.01)

RNS/Utilities/rnsh/loop.py

@@ -0,0 +1,46 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import asyncio
+import functools
+from typing import Callable
+
+def sig_handler_sys_to_loop(handler: Callable[[int, any], None]) -> Callable[[int, asyncio.AbstractEventLoop], None]:
+    def wrapped(cb: Callable[[int, any], None], signal: int, loop: asyncio.AbstractEventLoop): cb(signal, None)
+    return functools.partial(wrapped, handler)
+
+def loop_set_signal(sig, handler: Callable[[int, asyncio.AbstractEventLoop], None], loop: asyncio.AbstractEventLoop = None):
+    if loop is None: loop = asyncio.get_running_loop()
+    loop.remove_signal_handler(sig)
+    loop.add_signal_handler(sig, functools.partial(handler, sig, loop))

RNS/Utilities/rnsh/process.py

@@ -0,0 +1,785 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+import asyncio
+import contextlib
+import copy
+import errno
+import fcntl
+import functools
+import os
+import pty
+import select
+import signal
+import struct
+import sys
+import termios
+import threading
+import tty
+import types
+import typing
+import RNS
+
+import RNS.Utilities.rnsh.exception as exception
+
+CTRL_C = "\x03".encode("utf-8")
+CTRL_D = "\x04".encode("utf-8")
+
+def tty_add_reader_callback(fd: int, callback: callable, loop: asyncio.AbstractEventLoop = None):
+    """
+    Add an async reader callback for a tty file descriptor.
+
+    Example usage:
+
+        def reader():
+            data = tty_read(fd)
+            # do something with data
+
+        tty_add_reader_callback(self._child_fd, reader, self._loop)
+
+    :param fd: file descriptor
+    :param callback: callback function
+    :param loop: asyncio event loop to which the reader should be added. If None, use the currently-running loop.
+    """
+    if loop is None:
+        loop = asyncio.get_running_loop()
+    loop.add_reader(fd, callback)
+
+
+def tty_read(fd: int) -> bytes:
+    """
+    Read available bytes from a tty file descriptor. When used in a callback added to a file descriptor using
+    tty_add_reader_callback(...), this function creates a solution for non-blocking reads from ttys.
+    :param fd: tty file descriptor
+    :return: bytes read
+    """
+    if fd_is_closed(fd):
+        raise EOFError
+
+    try:
+        run = True
+        result = bytearray()
+        while not fd_is_closed(fd):
+            ready, _, _ = select.select([fd], [], [], 0)
+            if len(ready) == 0:
+                break
+            for f in ready:
+                try:
+                    data = os.read(f, 4096)
+                except OSError as e:
+                    if e.errno != errno.EIO and e.errno != errno.EWOULDBLOCK:
+                        raise
+                else:
+                    if not data:  # EOF
+                        if data is not None and len(data) > 0:
+                            result.extend(data)
+                            return result
+                        elif len(result) > 0:
+                            return result
+                        else:
+                            raise EOFError
+                    if data is not None and len(data) > 0:
+                        result.extend(data)
+        return result
+    
+    except EOFError: raise
+    except Exception as e: RNS.log(f"TTY read error: {e}", RNS.LOG_ERROR)
+
+
+def tty_read_poll(fd: int) -> bytes:
+    """
+    Read available bytes from a tty file descriptor. When used in a callback added to a file descriptor using
+    tty_add_reader_callback(...), this function creates a solution for non-blocking reads from ttys.
+    :param fd: tty file descriptor
+    :return: bytes read
+    """
+    if fd_is_closed(fd):
+        raise EOFError
+
+    result = bytearray()
+    try:
+        flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+        fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+        while True:
+            try:
+                data = os.read(fd, 4096)
+                if not data:
+                    # EOF
+                    if len(result) > 0:
+                        return result
+                    raise EOFError
+                result.extend(data)
+                # continue loop to drain
+            except OSError as e:
+                if e.errno in (errno.EWOULDBLOCK, errno.EAGAIN):
+                    break
+                if e.errno == errno.EIO:
+                    if len(result) > 0:
+                        return result
+                    raise EOFError
+                raise
+    except EOFError: raise
+    except Exception as e: RNS.log(f"TTY read error: {e}", RNS.LOG_ERROR)
+    
+    return result
+
+
+def fd_is_closed(fd: int) -> bool:
+    """
+    Check if file descriptor is closed
+    :param fd: file descriptor
+    :return: True if file descriptor is closed
+    """
+    try:
+        fcntl.fcntl(fd, fcntl.F_GETFL) < 0
+    except OSError as ose:
+        return ose.errno == errno.EBADF
+
+
+def tty_unset_reader_callbacks(fd: int, loop: asyncio.AbstractEventLoop = None):
+    """
+    Remove async reader callbacks for file descriptor.
+    :param fd: file descriptor
+    :param loop: asyncio event loop from which to remove callbacks
+    """
+    with exception.permit(SystemExit):
+        if loop is None:
+            loop = asyncio.get_running_loop()
+        loop.remove_reader(fd)
+
+
+def tty_get_winsize(fd: int) -> [int, int, int, int]:
+    """
+    Ge the window size of a tty.
+    :param fd: file descriptor of tty
+    :return: (rows, cols, h_pixels, v_pixels)
+    """
+    packed = fcntl.ioctl(fd, termios.TIOCGWINSZ, struct.pack('HHHH', 0, 0, 0, 0))
+    rows, cols, h_pixels, v_pixels = struct.unpack('HHHH', packed)
+    return rows, cols, h_pixels, v_pixels
+
+
+def tty_set_winsize(fd: int, rows: int, cols: int, h_pixels: int, v_pixels: int):
+    """
+    Set the window size on a tty.
+    :param fd: file descriptor of tty
+    :param rows: number of visible rows
+    :param cols: number of visible columns
+    :param h_pixels: number of visible horizontal pixels
+    :param v_pixels: number of visible vertical pixels
+    """
+    if fd < 0:
+        return
+    packed = struct.pack('HHHH', rows, cols, h_pixels, v_pixels)
+    fcntl.ioctl(fd, termios.TIOCSWINSZ, packed)
+
+
+def process_exists(pid) -> bool:
+    """
+    Check For the existence of a unix pid.
+    :param pid: process id to check
+    :return: True if process exists
+    """
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    else:
+        return True
+
+
+class TTYRestorer(contextlib.AbstractContextManager):
+    # Indexes of flags within the attrs array
+    ATTR_IDX_IFLAG = 0
+    ATTR_IDX_OFLAG = 1
+    ATTR_IDX_CFLAG = 2
+    ATTR_IDX_LFLAG = 4
+    ATTR_IDX_CC    = 5
+
+    def __init__(self, fd: int, suppress_logs=False):
+        """
+        Saves termios attributes for a tty for later restoration.
+
+        The attributes are an array of values with the following meanings.
+
+            tcflag_t c_iflag;      /* input modes */
+            tcflag_t c_oflag;      /* output modes */
+            tcflag_t c_cflag;      /* control modes */
+            tcflag_t c_lflag;      /* local modes */
+            cc_t     c_cc[NCCS];   /* special characters */
+
+        :param fd: file descriptor of tty
+        """
+        self._fd = fd
+        self._tattr = None
+        self._suppress_logs = suppress_logs
+        self._tattr = self.current_attr()
+        if not self._tattr and not self._suppress_logs: RNS.log(f"Could not get attrs for fd {fd}", RNS.LOG_DEBUG)
+
+    def raw(self):
+        """
+        Set raw mode on tty
+        """
+        if self._fd is None:
+            return
+        with contextlib.suppress(termios.error):
+            tty.setraw(self._fd, termios.TCSANOW)
+
+    def original_attr(self) -> [any]:
+        return copy.deepcopy(self._tattr)
+
+    def current_attr(self) -> [any]:
+        """
+        Get the current termios attributes for the wrapped fd.
+        :return: attribute array
+        """
+        if self._fd is None:
+            return None
+
+        with contextlib.suppress(termios.error):
+            return copy.deepcopy(termios.tcgetattr(self._fd))
+        return None
+
+    def set_attr(self, attr: [any], when: int = termios.TCSADRAIN):
+        """
+        Set termios attributes
+        :param attr: attribute list to set
+        :param when: when attributes should be applied (termios.TCSANOW, termios.TCSADRAIN, termios.TCSAFLUSH)
+        """
+        if not attr or self._fd is None:
+            return
+
+        with contextlib.suppress(termios.error):
+            termios.tcsetattr(self._fd, when, attr)
+
+    def isatty(self):
+        return os.isatty(self._fd) if self._fd is not None else None
+
+    def restore(self):
+        """
+        Restore termios settings to state captured in constructor.
+        """
+        self.set_attr(self._tattr, termios.TCSADRAIN)
+
+    def __exit__(self, __exc_type: typing.Type[BaseException], __exc_value: BaseException,
+                 __traceback: types.TracebackType) -> bool:
+        self.restore()
+        return False  #__exc_type is not None and issubclass(__exc_type, termios.error)
+
+
+def _task_from_event(evt: asyncio.Event, loop: asyncio.AbstractEventLoop = None):
+    if not loop:
+        loop = asyncio.get_running_loop()
+
+    #TODO: this is hacky
+    async def wait():
+        while not evt.is_set():
+            await asyncio.sleep(0.1)
+        return True
+
+    return loop.create_task(wait())
+
+
+class AggregateException(Exception):
+    def __init__(self, inner_exceptions: [Exception]):
+        super().__init__()
+        self.inner_exceptions = inner_exceptions
+
+    def __str__(self):
+        return "Multiple exceptions encountered: \n\n" + "\n\n".join(map(lambda e: str(e), self.inner_exceptions))
+
+
+async def event_wait_any(evts: [asyncio.Event], timeout: float  = None) -> (any, any):
+    tasks = list(map(lambda evt: (evt, _task_from_event(evt)), evts))
+    try:
+        finished, unfinished = await asyncio.wait(map(lambda t: t[1], tasks),
+                                                  timeout=timeout,
+                                                  return_when=asyncio.FIRST_COMPLETED)
+
+        if len(unfinished) > 0:
+            for task in unfinished:
+                task.cancel()
+            await asyncio.wait(unfinished)
+
+        exceptions = []
+
+        for f in finished:
+            ex = f.exception()
+            if ex and not isinstance(ex, asyncio.CancelledError) and not isinstance(ex, TimeoutError):
+                exceptions.append(ex)
+
+        if len(exceptions) > 0:
+            raise AggregateException(exceptions)
+
+        return next(map(lambda t: next(map(lambda tt: tt[0], tasks)), finished), None)
+    finally:
+        unfinished = []
+        for task in map(lambda t: t[1], tasks):
+            if task.done():
+                if not task.cancelled():
+                    task.exception()
+            else:
+                task.cancel()
+                unfinished.append(task)
+        if len(unfinished) > 0:
+            await asyncio.wait(unfinished)
+
+
+async def event_wait(evt: asyncio.Event, timeout: float) -> bool:
+    """
+    Wait for event to be set, or timeout to expire.
+    :param evt: asyncio.Event to wait on
+    :param timeout: maximum number of seconds to wait.
+    :return: True if event was set, False if timeout expired
+    """
+    await event_wait_any([evt], timeout=timeout)
+    return evt.is_set()
+
+
+def _launch_child(cmd_line: list[str], env: dict[str, str], stdin_is_pipe: bool, stdout_is_pipe: bool,
+                  stderr_is_pipe: bool) -> tuple[int, int, int, int]:
+    # Set up PTY and/or pipes
+    child_fd = parent_fd = None
+    if not (stdin_is_pipe and stdout_is_pipe and stderr_is_pipe):
+        parent_fd, child_fd = pty.openpty()
+    child_stdin, parent_stdin = (os.pipe() if stdin_is_pipe else (child_fd, parent_fd))
+    parent_stdout, child_stdout = (os.pipe() if stdout_is_pipe else (parent_fd, child_fd))
+    parent_stderr, child_stderr = (os.pipe() if stderr_is_pipe else (parent_fd, child_fd))
+
+    # Fork
+    pid = os.fork()
+
+    if pid == 0:
+        try:
+            # We are in the child process, so close all open sockets and pipes except for the PTY and/or pipes
+            max_fd = os.sysconf("SC_OPEN_MAX")
+            for fd in range(3, max_fd):
+                if fd not in (child_stdin, child_stdout, child_stderr):
+                    try:
+                        os.close(fd)
+                    except OSError:
+                        pass
+
+            # Set up PTY and/or pipes
+            os.dup2(child_stdin, 0)
+            os.dup2(child_stdout, 1)
+            os.dup2(child_stderr, 2)
+            # Make PTY controlling if necessary so that CTRL_C/CTRL_D behave as expected
+            if child_fd is not None:
+                os.setsid()
+                try:
+                    tty_fd = 0 if not stdin_is_pipe else (1 if not stdout_is_pipe else 2)
+                    # Set controlling TTY for this session
+                    fcntl.ioctl(tty_fd, termios.TIOCSCTTY, 0)
+                except Exception:
+                    pass
+                # Ensure the child is the foreground process group for the TTY
+                try:
+                    os.setpgid(0, 0)
+                    pgid = os.getpgrp()
+                    import struct as _struct
+                    fcntl.ioctl(tty_fd, termios.TIOCSPGRP, _struct.pack('i', pgid))
+                except Exception:
+                    pass
+                # Ensure canonical input with signals and local echo enabled
+                try:
+                    tty_fd = 0 if not stdin_is_pipe else (1 if not stdout_is_pipe else 2)
+                    attrs = termios.tcgetattr(tty_fd)
+                    lflag = attrs[3]
+                    lflag |= termios.ICANON | termios.ISIG | termios.ECHO
+                    attrs[3] = lflag
+                    termios.tcsetattr(tty_fd, termios.TCSANOW, attrs)
+                except Exception:
+                    pass
+
+            # Execute the command
+            os.execvpe(cmd_line[0], cmd_line, env)
+        except Exception as err:
+            exc_type, exc_obj, exc_tb = sys.exc_info()
+            fname = os.path.split(exc_tb.tb_frame.f_code.co_filename)[1]
+            print(f"Unable to start {cmd_line[0]}: {err} ({fname}:{exc_tb.tb_lineno})")
+            sys.stdout.flush()
+        # don't let any other modules get in our way, do an immediate silent exit.
+        os._exit(255)
+
+    else:
+        # We are in the parent process, so close the child-side of the PTY and/or pipes
+        if child_fd is not None:
+            os.close(child_fd)
+        if child_stdin != child_fd:
+            os.close(child_stdin)
+        if child_stdout != child_fd:
+            os.close(child_stdout)
+        if child_stderr != child_fd:
+            os.close(child_stderr)
+        # # Close the write end of the pipe if a pipe is used for standard input
+        # if not stdin_is_pipe:
+        #     os.close(parent_stdin)
+        # Return the child PID and the file descriptors for the PTY and/or pipes
+        return pid, parent_stdin, parent_stdout, parent_stderr
+
+
+class CallbackSubprocess:
+    # time between checks of child process
+    PROCESS_POLL_TIME: float = 0.1
+    # Close pipes soon after process exit to avoid scheduling on closed event loops
+    PROCESS_PIPE_TIME: int = 1
+
+    def __init__(self, argv: [str], env: dict, loop: asyncio.AbstractEventLoop, stdout_callback: callable,
+                 stderr_callback: callable, terminated_callback: callable, stdin_is_pipe: bool, stdout_is_pipe: bool,
+                 stderr_is_pipe: bool):
+        """
+        Fork a child process and generate callbacks with output from the process.
+        :param argv: the command line, tokenized. The first element must be the absolute path to an executable file.
+        :param env: environment variables to override
+        :param loop: the asyncio event loop to use
+        :param stdout_callback: callback for data, e.g. def callback(data:bytes) -> None
+        :param terminated_callback: callback for termination/return code, e.g. def callback(return_code:int) -> None
+        """
+        assert loop is not None, "loop should not be None"
+        assert stdout_callback is not None, "stdout_callback should not be None"
+        assert terminated_callback is not None, "terminated_callback should not be None"
+
+        self._command: [str] = argv
+        self._env = env or {}
+        self._loop = loop
+        self._stdout_cb = stdout_callback
+        self._stderr_cb = stderr_callback
+        self._terminated_cb = terminated_callback
+        self._pid: int = None
+        self._child_stdin: int = None
+        self._child_stdout: int = None
+        self._child_stderr: int = None
+        self._return_code: int = None
+        self._stdout_eof: bool = False
+        self._stderr_eof: bool = False
+        self._stdin_is_pipe = stdin_is_pipe
+        self._stdout_is_pipe = stdout_is_pipe
+        self._stderr_is_pipe = stderr_is_pipe
+        self._at_line_start: bool = True
+        self._tty_line_buffer: bytearray = bytearray()
+
+    def _ensure_pipes_closed(self):
+        stdin = self._child_stdin
+        stdout = self._child_stdout
+        stderr = self._child_stderr
+        fds = set(filter(lambda x: x is not None, list({stdin, stdout, stderr})))
+        RNS.log(f"Queuing close of pipes for ended process (fds: {fds})", RNS.LOG_DEBUG)
+
+        def ensure_pipes_closed_inner():
+            RNS.log(f"Ensuring pipes are closed (fds: {fds})", RNS.LOG_DEBUG)
+            for fd in fds:
+                RNS.log(f"Closing fd {fd}", RNS.LOG_DEBUG)
+                with contextlib.suppress(OSError): tty_unset_reader_callbacks(fd)
+                with contextlib.suppress(OSError): os.close(fd)
+
+            self._child_stdin = None
+            self._child_stdout = None
+            self._child_stderr = None
+
+        # Avoid scheduling on a closed loop
+        if self._loop.is_closed(): ensure_pipes_closed_inner()
+        else:                      self._loop.call_later(CallbackSubprocess.PROCESS_PIPE_TIME, ensure_pipes_closed_inner)
+
+    def terminate(self, kill_delay: float = 1.0):
+        """
+        Terminate child process if running
+        :param kill_delay: if after kill_delay seconds the child process has not exited, escalate to SIGHUP and SIGKILL
+        """
+
+        RNS.log("terminate()", RNS.LOG_EXTREME)
+        if not self.running: return
+
+        with exception.permit(SystemExit): os.kill(self._pid, signal.SIGTERM)
+
+        def kill():
+            if process_exists(self._pid):
+                RNS.log("kill()", RNS.LOG_EXTREME)
+                with exception.permit(SystemExit):
+                    os.kill(self._pid, signal.SIGHUP)
+                    os.kill(self._pid, signal.SIGKILL)
+
+        self._loop.call_later(kill_delay, kill)
+
+        def wait():
+            RNS.log("wait()", RNS.LOG_EXTREME)
+            with contextlib.suppress(OSError): os.waitpid(self._pid, 0)
+            self._ensure_pipes_closed()
+            RNS.log("wait() finish", RNS.LOG_EXTREME)
+
+        threading.Thread(target=wait, daemon=True).start()
+
+    def close_stdin(self):
+        with contextlib.suppress(Exception):
+            os.close(self._child_stdin)
+        # Encourage prompt shutdown if child lingers after stdin close
+        def _ensure_terminate():
+            if self.running:
+                self.terminate(kill_delay=0.2)
+        if not self._loop.is_closed():
+            self._loop.call_later(0.05, _ensure_terminate)
+
+    @property
+    def started(self) -> bool:
+        """
+        :return: True if child process has been started
+        """
+        return self._pid is not None
+
+    @property
+    def running(self) -> bool:
+        """
+        :return: True if child process is still running
+        """
+        return self._pid is not None and process_exists(self._pid)
+
+    def write(self, data: bytes):
+        """
+        Write bytes to the stdin of the child process.
+        :param data: bytes to write
+        """
+
+        os.write(self._child_stdin, data)
+
+        # TODO: Check what this is actually supposed to solve.
+        #
+        # For pipe-in + TTY-out, echo should be visible immediately
+        if self._stdin_is_pipe and not self._stdout_is_pipe and self._stdout_cb is not None and data not in (CTRL_C, CTRL_D):
+            try: self._stdout_cb(data)
+            except Exception: pass
+
+    def set_winsize(self, r: int, c: int, h: int, v: int):
+        """
+        Set the window size on the tty of the child process.
+        :param r: rows visible
+        :param c: columns visible
+        :param h: horizontal pixels visible
+        :param v: vertical pixels visible
+        :return:
+        """
+        RNS.log(f"set_winsize({r},{c},{h},{v}", RNS.LOG_DEBUG)
+        tty_set_winsize(self._child_stdout, r, c, h, v)
+
+    def copy_winsize(self, fromfd: int):
+        """
+        Copy window size from one tty to another.
+        :param fromfd: source tty file descriptor
+        """
+        r, c, h, v = tty_get_winsize(fromfd)
+        self.set_winsize(r, c, h, v)
+
+    def tcsetattr(self, when: int, attr: list[any]):  # actual type is list[int | list[int | bytes]]
+        """
+        Set tty attributes.
+        :param when: when to apply change: termios.TCSANOW or termios.TCSADRAIN or termios.TCSAFLUSH
+        :param attr: attributes to set
+        """
+        termios.tcsetattr(self._child_stdin, when, attr)
+
+    def tcgetattr(self) -> list[any]:  # actual type is list[int | list[int | bytes]]
+        """
+        Get tty attributes.
+        :return: tty attributes value
+        """
+        return termios.tcgetattr(self._child_stdout)
+
+    def ttysetraw(self):
+        tty.setraw(self._child_stdout, termios.TCSADRAIN)
+
+    def start(self):
+        """
+        Start the child process.
+        """
+        RNS.log("start()", RNS.LOG_EXTREME)
+
+        # # Using the parent environment seems to do some weird stuff, at least on macOS
+        # parentenv = os.environ.copy()
+        # env = {"HOME": parentenv["HOME"],
+        #        "PATH": parentenv["PATH"],
+        #        "TERM": self._term if self._term is not None else parentenv.get("TERM", "xterm"),
+        #        "LANG": parentenv.get("LANG"),
+        #        "SHELL": self._command[0]}
+
+        env = os.environ.copy()
+        for key in self._env:
+            env[key] = self._env[key]
+
+        program = self._command[0]
+        assert isinstance(program, str)
+
+        # match = re.search("^/bin/(.*sh)$", program)
+        # if match:
+        #     self._command[0] = "-" + match.group(1)
+        #     env["SHELL"] = program
+        #     self._log.debug(f"set login shell {self._command}")
+
+        self._pid, \
+            self._child_stdin, \
+            self._child_stdout, \
+            self._child_stderr = _launch_child(self._command, env, self._stdin_is_pipe, self._stdout_is_pipe,
+                                               self._stderr_is_pipe)
+        RNS.log(f"Started pid {self.pid}, fds: {self._child_stdin}, {self._child_stdout}, {self._child_stderr}", RNS.LOG_DEBUG)
+
+        def poll():
+            try:
+                pid, self._return_code = os.waitpid(self._pid, os.WNOHANG)
+                if self._return_code is not None:
+                    self._return_code = self._return_code & 0xff
+                if self._return_code is not None and not process_exists(self._pid):
+                    RNS.log(f"polled return code {self._return_code}", RNS.LOG_DEBUG)
+                    self._terminated_cb(self._return_code)
+                if self.running:
+                    self._loop.call_later(CallbackSubprocess.PROCESS_POLL_TIME, poll)
+                else:
+                    self._ensure_pipes_closed()
+            except Exception as e:
+                if not hasattr(e, "errno") or e.errno != errno.ECHILD:
+                    RNS.log(f"Error in process poll: {e}", RNS.LOG_DEBUG)
+
+        self._loop.call_later(CallbackSubprocess.PROCESS_POLL_TIME, poll)
+
+        def stdout():
+            try:
+                with exception.permit(SystemExit):
+                    data = tty_read_poll(self._child_stdout)
+                    if data is not None and len(data) > 0:
+                        self._stdout_cb(data)
+                        # Opportunistically drain shortly after to coalesce immediate follow-up output
+                        if not self._loop.is_closed():
+                            self._loop.call_later(0.01, stdout)
+            except EOFError:
+                self._stdout_eof = True
+                tty_unset_reader_callbacks(self._child_stdout)
+                self._stdout_cb(bytearray())
+
+        def stderr():
+            try:
+                with exception.permit(SystemExit):
+                    data = tty_read_poll(self._child_stderr)
+                    if data is not None and len(data) > 0:
+                        self._stderr_cb(data)
+                        if not self._loop.is_closed():
+                            self._loop.call_later(0.01, stderr)
+            except EOFError:
+                self._stderr_eof = True
+                tty_unset_reader_callbacks(self._child_stderr)
+                self._stderr_cb(bytearray())
+
+        tty_add_reader_callback(self._child_stdout, stdout, self._loop)
+        if self._child_stderr != self._child_stdout:
+            tty_add_reader_callback(self._child_stderr, stderr, self._loop)
+
+    @property
+    def stdout_eof(self):
+        return self._stdout_eof or not self.running
+
+    @property
+    def stderr_eof(self):
+        return self._stderr_eof or not self.running
+
+
+    @property
+    def return_code(self) -> int:
+        return self._return_code
+
+    @property
+    def pid(self) -> int:
+        return self._pid
+
+
+async def main():
+    """
+    A test driver for the CallbackProcess class.
+    python ./process.py /bin/zsh --login
+    """
+
+    if len(sys.argv) <= 1:
+        print(f"Usage: {sys.argv} <absolute_path_to_child_executable> [child_arg ...]")
+        exit(1)
+
+    loop = asyncio.get_event_loop()
+    # asyncio.set_event_loop(loop)
+    retcode = loop.create_future()
+
+    def stdout(data: bytes): os.write(sys.stdout.fileno(), data)
+
+    def terminated(rc: int): retcode.set_result(rc)
+
+    process = CallbackSubprocess(argv=sys.argv[1:],
+                                 env={"TERM": os.environ.get("TERM", "xterm")},
+                                 loop=loop,
+                                 stdout_callback=stdout,
+                                 terminated_callback=terminated)
+
+    def sigint_handler(sig, frame):
+        if process is None or process.started and not process.running:
+            raise KeyboardInterrupt
+        elif process.running:
+            process.write("\x03".encode("utf-8"))
+
+    def sigwinch_handler(sig, frame):
+        process.copy_winsize(sys.stdin.fileno())
+
+    signal.signal(signal.SIGINT, sigint_handler)
+    signal.signal(signal.SIGWINCH, sigwinch_handler)
+
+    def stdin():
+        try:
+            data = tty_read(sys.stdin.fileno())
+            if data is not None:
+                process.write(data)
+
+        except EOFError:
+            tty_unset_reader_callbacks(sys.stdin.fileno())
+            process.write(CTRL_D)
+
+    tty_add_reader_callback(sys.stdin.fileno(), stdin)
+    process.start()
+    # call_soon called it too soon, not sure why.
+    loop.call_later(0.001, functools.partial(process.copy_winsize, sys.stdin.fileno()))
+
+    val = await retcode
+    RNS.log(f"Got return code {val}", RNS.LOG_DEBUG)
+    return val
+
+
+if __name__ == "__main__":
+    tr = TTYRestorer(sys.stdin.fileno())
+    try:
+        tr.raw()
+        asyncio.run(main())
+    finally:
+        tty_unset_reader_callbacks(sys.stdin.fileno())
+        tr.restore()

RNS/Utilities/rnsh/protocol.py

@@ -0,0 +1,149 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+
+import RNS
+from RNS.vendor import umsgpack
+from RNS.Buffer import StreamDataMessage as RNSStreamDataMessage
+import RNS.Utilities.rnsh.retry
+import abc
+import contextlib
+import struct
+from abc import ABC, abstractmethod
+
+MSG_MAGIC = 0xac
+PROTOCOL_VERSION = 1
+
+def _make_MSGTYPE(val: int):
+    return ((MSG_MAGIC << 8) & 0xff00) | (val & 0x00ff)
+
+
+class NoopMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(0)
+    def pack(self) -> bytes: return bytes()
+    def unpack(self, raw): pass
+
+
+class WindowSizeMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(2)
+
+    def __init__(self, rows: int = None, cols: int = None, hpix: int = None, vpix: int = None):
+        super().__init__()
+        self.rows = rows
+        self.cols = cols
+        self.hpix = hpix
+        self.vpix = vpix
+
+    def pack(self) -> bytes: return umsgpack.packb((self.rows, self.cols, self.hpix, self.vpix))
+    def unpack(self, raw): self.rows, self.cols, self.hpix, self.vpix = umsgpack.unpackb(raw)
+
+
+class ExecuteCommandMesssage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(3)
+
+    def __init__(self, cmdline: [str] = None, pipe_stdin: bool = False, pipe_stdout: bool = False,
+                 pipe_stderr: bool = False, tcflags: [any] = None, term: str | None = None, rows: int = None,
+                 cols: int = None, hpix: int = None, vpix: int = None):
+        
+        super().__init__()
+        self.cmdline = cmdline
+        self.pipe_stdin = pipe_stdin
+        self.pipe_stdout = pipe_stdout
+        self.pipe_stderr = pipe_stderr
+        self.tcflags = tcflags
+        self.term = term
+        self.rows = rows
+        self.cols = cols
+        self.hpix = hpix
+        self.vpix = vpix
+
+    def pack(self) -> bytes:
+        return umsgpack.packb((self.cmdline, self.pipe_stdin, self.pipe_stdout, self.pipe_stderr,
+                               self.tcflags, self.term, self.rows, self.cols, self.hpix, self.vpix))
+
+    def unpack(self, raw):
+        self.cmdline, self.pipe_stdin, self.pipe_stdout, self.pipe_stderr, self.tcflags, self.term, self.rows, \
+            self.cols, self.hpix, self.vpix = umsgpack.unpackb(raw)
+
+
+# Create a version of RNS.Buffer.StreamDataMessage that we control
+class StreamDataMessage(RNSStreamDataMessage):
+    MSGTYPE = _make_MSGTYPE(4)
+    STREAM_ID_STDIN  = 0
+    STREAM_ID_STDOUT = 1
+    STREAM_ID_STDERR = 2
+
+
+class VersionInfoMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(5)
+
+    def __init__(self, sw_version: str = None):
+        super().__init__()
+        self.sw_version = sw_version or RNS.Utilities.rnsh.__version__
+        self.protocol_version = PROTOCOL_VERSION
+
+    def pack(self) -> bytes: return umsgpack.packb((self.sw_version, self.protocol_version))
+    def unpack(self, raw): self.sw_version, self.protocol_version = umsgpack.unpackb(raw)
+
+
+class ErrorMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(6)
+
+    def __init__(self, msg: str = None, fatal: bool = False, data: dict = None):
+        super().__init__()
+        self.msg = msg
+        self.fatal = fatal
+        self.data = data
+
+    def pack(self) -> bytes: return umsgpack.packb((self.msg, self.fatal, self.data))
+    def unpack(self, raw: bytes): self.msg, self.fatal, self.data = umsgpack.unpackb(raw)
+
+
+class CommandExitedMessage(RNS.MessageBase):
+    MSGTYPE = _make_MSGTYPE(7)
+
+    def __init__(self, return_code: int = None):
+        super().__init__()
+        self.return_code = return_code
+
+    def pack(self) -> bytes: return umsgpack.packb(self.return_code)
+    def unpack(self, raw: bytes): self.return_code = umsgpack.unpackb(raw)
+
+
+message_types = [NoopMessage, VersionInfoMessage, WindowSizeMessage, ExecuteCommandMesssage, StreamDataMessage,
+                 CommandExitedMessage, ErrorMessage]
+
+def register_message_types(channel: RNS.Channel.Channel):
+    for message_type in message_types: channel.register_message_type(message_type)

RNS/Utilities/rnsh/retry.py

@@ -0,0 +1,201 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import asyncio
+import threading
+import time
+import RNS.Utilities.rnsh.exception as exception
+from typing import Callable
+from contextlib import AbstractContextManager
+import types
+import typing
+
+
+class RetryStatus:
+    def __init__(self, tag: any, try_limit: int, wait_delay: float, retry_callback: Callable[[any, int], any],
+                 timeout_callback: Callable[[any, int], None], tries: int = 1):
+        
+        self.tag = tag
+        self.try_limit = try_limit
+        self.tries = tries
+        self.wait_delay = wait_delay
+        self.retry_callback = retry_callback
+        self.timeout_callback = timeout_callback
+        self.try_time = time.time()
+        self.completed = False
+
+    @property
+    def ready(self):
+        ready = time.time() > self.try_time + self.wait_delay
+        RNS.log(f"ready check {self.tag} try_time {self.try_time} wait_delay {self.wait_delay} " +
+                        f"next_try {self.try_time + self.wait_delay} now {time.time()} " +
+                        f"exceeded {time.time() - self.try_time - self.wait_delay} ready {ready}", RNS.LOG_DEBUG)
+        return ready
+
+    @property
+    def timed_out(self):
+        return self.ready and self.tries >= self.try_limit
+
+    def timeout(self):
+        self.completed = True
+        self.timeout_callback(self.tag, self.tries)
+
+    def retry(self) -> any:
+        self.tries = self.tries + 1
+        self.try_time = time.time()
+        return self.retry_callback(self.tag, self.tries)
+
+
+class RetryThread(AbstractContextManager):
+    def __init__(self, loop_period: float = 0.25, name: str = "retry thread"):
+        self._loop_period = loop_period
+        self._statuses: list[RetryStatus] = []
+        self._tag_counter = 0
+        self._lock = threading.RLock()
+        self._run = True
+        self._finished: asyncio.Future = None
+        self._thread = threading.Thread(name=name, target=self._thread_run, daemon=True)
+        self._thread.start()
+
+    def is_alive(self):
+        return self._thread.is_alive()
+
+    def close(self, loop: asyncio.AbstractEventLoop = None) -> asyncio.Future:
+        RNS.log("Stopping timer thread", RNS.LOG_DEBUG)
+        if loop is None:
+            self._run = False
+            self._thread.join()
+            return None
+        else:
+            self._finished = loop.create_future()
+            return self._finished
+
+    def wait(self, timeout: float = None):
+        if timeout:
+            timeout = timeout + time.time()
+
+        while timeout is None or time.time() < timeout:
+            with self._lock:
+                task_count = len(self._statuses)
+            if task_count == 0:
+                return
+            time.sleep(0.1)
+
+
+    def _thread_run(self):
+        while self._run and self._finished is None:
+            time.sleep(self._loop_period)
+            ready: list[RetryStatus] = []
+            prune: list[RetryStatus] = []
+            with self._lock: ready.extend(list(filter(lambda s: s.ready, self._statuses)))
+            
+            for retry in ready:
+                try:
+                    if not retry.completed:
+                        if retry.timed_out:
+                            RNS.log(f"Timed out {retry.tag} after {retry.try_limit} tries", RNS.LOG_DEBUG)
+                            retry.timeout()
+                            prune.append(retry)
+                        elif retry.ready:
+                            RNS.log(f"Retrying {retry.tag}, try {retry.tries + 1}/{retry.try_limit}", RNS.LOG_DEBUG)
+                            should_continue = retry.retry()
+                            if not should_continue: self.complete(retry.tag)
+                
+                except Exception as e:
+                    RNS.log(f"Error processing retry id {retry.tag}: {e}", RNS.LOG_ERROR)
+                    prune.append(retry)
+
+            with self._lock:
+                for retry in prune:
+                    RNS.log(f"pruned retry {retry.tag}, retry count {retry.tries}/{retry.try_limit}", RNS.LOG_DEBUG)
+                    with exception.permit(SystemExit): self._statuses.remove(retry)
+
+        if self._finished is not None: self._finished.set_result(None)
+
+    def _get_next_tag(self):
+        self._tag_counter += 1
+        return self._tag_counter
+
+    def has_tag(self, tag: any) -> bool:
+        with self._lock: return next(filter(lambda s: s.tag == tag, self._statuses), None) is not None
+
+    def begin(self, try_limit: int, wait_delay: float, try_callback: Callable[[any, int], any],
+              timeout_callback: Callable[[any, int], None]) -> any:
+        
+        RNS.log(f"Running first try", RNS.LOG_DEBUG)
+        tag = try_callback(None, 1)
+        RNS.log(f"First try got id {tag}", RNS.LOG_DEBUG)
+        
+        if not tag:
+            RNS.log(f"Callback returned None/False/0, considering complete.", RNS.LOG_DEBUG)
+            return None
+        
+        with self._lock:
+            if tag is None: tag = self._get_next_tag()
+            self.complete(tag)
+
+            self._statuses.append(RetryStatus(tag=tag,
+                                              tries=1,
+                                              try_limit=try_limit,
+                                              wait_delay=wait_delay,
+                                              retry_callback=try_callback,
+                                              timeout_callback=timeout_callback))
+        
+        RNS.log(f"Added retry timer for {tag}", RNS.LOG_DEBUG)
+        return tag
+
+    def complete(self, tag: any):
+        assert tag is not None
+        with self._lock:
+            status = next(filter(lambda l: l.tag == tag, self._statuses), None)
+            if status is not None:
+                status.completed = True
+                self._statuses.remove(status)
+                RNS.log(f"completed {tag}", RNS.LOG_DEBUG)
+                return
+
+        RNS.log(f"status not found to complete {tag}", RNS.LOG_DEBUG)
+
+    def complete_all(self):
+        with self._lock:
+            for status in self._statuses:
+                status.completed = True
+                RNS.log(f"completed {status.tag}", RNS.LOG_DEBUG)
+            
+            self._statuses.clear()
+
+    def __exit__(self, __exc_type: typing.Type[BaseException], __exc_value: BaseException,
+                 __traceback: types.TracebackType) -> bool:
+        self.close()
+        return False

RNS/Utilities/rnsh/rnsh.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+#
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+
+import asyncio
+import base64
+
+import re
+import os
+import sys
+
+import RNS
+import RNS.Utilities.rnsh.process as process
+import RNS.Utilities.rnsh.session as session
+import RNS.Utilities.rnsh.args
+import RNS.Utilities.rnsh.loop
+import RNS.Utilities.rnsh.listener as listener
+import RNS.Utilities.rnsh.initiator as initiator
+from RNS.Utilities.rnsh.args import parse_arguments
+
+APP_NAME = "rnsh"
+loop: asyncio.AbstractEventLoop | None = None
+
+def _sanitize_service_name(service_name:str) -> str: return re.sub(r'\W+', '', service_name)
+
+def prepare_identity(identity_path, service_name: str = None) -> tuple[RNS.Identity]:
+    service_name = _sanitize_service_name(service_name or "")
+    if identity_path is None:
+        identity_path = RNS.Reticulum.identitypath + "/" + APP_NAME + \
+                        (f".{service_name}" if service_name and len(service_name) > 0 else "")
+
+    identity = None
+    if os.path.isfile(identity_path):
+        identity = RNS.Identity.from_file(identity_path)
+
+    if identity is None:
+        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
+        identity = RNS.Identity()
+        identity.to_file(identity_path)
+    
+    return identity
+
+
+def print_identity(configdir, identitypath, service_name, include_destination: bool):
+    reticulum = RNS.Reticulum(configdir=configdir, loglevel=RNS.LOG_INFO)
+    if service_name and len(service_name) > 0:
+        print(f"Using service name \"{service_name}\"")
+    identity = prepare_identity(identitypath, service_name)
+    destination = RNS.Destination(identity, RNS.Destination.IN, RNS.Destination.SINGLE, APP_NAME)
+    print("Identity     : " + str(identity))
+    if include_destination:
+        print("Listening on : " + RNS.prettyhexrep(destination.hash))
+
+    exit(0)
+
+verbose_set = False
+
+def ensure_config_directory():
+    if os.path.isdir(os.path.expanduser("~/.config/rnsh")): return os.path.expanduser("~/.config/rnsh")
+    elif os.path.isdir(os.path.expanduser("~/.rnsh")): return os.path.expanduser("~/.rnsh")
+    else:
+        try:
+            os.makedirs(os.path.expanduser("~/.rnsh"))
+            return os.path.expanduser("~/.rnsh")
+
+        except Exception as e:
+            RNS.log(f"Could not get or create rnsh configuration directory, aborting", RNS.LOG_CRITICAL)
+            os._exit(1)
+
+
+async def _rnsh_cli_main():
+    global verbose_set
+    args, parser = parse_arguments()
+    verbose_set = args.verbose > 0
+
+    configdir = ensure_config_directory()
+
+    if args.print_identity:
+        print_identity(args.config, args.identity, args.service, args.listen)
+        return 0
+
+    if args.listen:
+        allowed_file = None
+        dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
+        if os.path.isfile(os.path.expanduser("~/.config/rnsh/allowed_identities")):
+            allowed_file = os.path.expanduser("~/.config/rnsh/allowed_identities")
+        elif os.path.isfile(os.path.expanduser("~/.rnsh/allowed_identities")):
+            allowed_file = os.path.expanduser("~/.rnsh/allowed_identities")
+
+        await listener.listen(configdir=configdir,
+                              rnsconfigdir=args.config,
+                              command=args.command,
+                              identitypath=args.identity,
+                              service_name=args.service,
+                              verbosity=args.verbose,
+                              quietness=args.quiet,
+                              allowed=args.allowed or [],
+                              allowed_file=allowed_file,
+                              disable_auth=args.no_auth,
+                              announce_period=args.announce,
+                              no_remote_command=args.no_remote_command,
+                              remote_cmd_as_args=args.remote_command_as_args)
+        return 0
+
+    if args.destination is not None:
+        return_code = await initiator.initiate(configdir=configdir,
+                                               rnsconfigdir=args.config,
+                                               identitypath=args.identity,
+                                               verbosity=args.verbose,
+                                               quietness=args.quiet,
+                                               noid=args.no_id,
+                                               destination=args.destination,
+                                               timeout=args.timeout,
+                                               command=args.command
+        )
+        return return_code if args.mirror else 0
+    else:
+        print("")
+        parser.print_help()
+        print("")
+        return 1
+
+
+def main():
+    global verbose_set
+    return_code = 1
+    exc = None
+    try: return_code = asyncio.run(_rnsh_cli_main())
+    except SystemExit: pass
+    except KeyboardInterrupt: pass
+    except Exception as e:
+        print(f"{e}")
+        exc = e
+    
+    process.tty_unset_reader_callbacks(0)
+    if verbose_set and exc: raise exc
+    sys.exit(return_code if return_code is not None else 255)
+
+
+if __name__ == "__main__": main()

RNS/Utilities/rnsh/session.py

@@ -0,0 +1,441 @@
+#         Based on the original rnsh program by Aaron Heise (@acehoss)
+# https://github.com/acehoss/rnsh - MIT License - Copyright (c) 2023 Aaron Heise
+#     This version of rnsh is included in RNS under the Reticulum License
+#
+# Reticulum License
+#
+# Copyright (c) 2016-2026 Mark Qvist
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# - The Software shall not be used in any kind of system which includes amongst
+#   its functions the ability to purposefully do harm to human beings.
+#
+# - The Software shall not be used, directly or indirectly, in the creation of
+#   an artificial intelligence, machine learning or language model training
+#   dataset, including but not limited to any use that contributes to the
+#   training or development of such a model or algorithm.
+#
+# - The above copyright notice and this permission notice shall be included in
+#   all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+import contextlib
+import functools
+import asyncio
+import RNS.Utilities.rnsh.exception as exception
+import RNS.Utilities.rnsh.process as process
+import RNS.Utilities.rnsh.helpers as helpers
+import RNS.Utilities.rnsh.protocol as protocol
+import enum
+from typing import TypeVar, Generic, Callable, List
+from abc import abstractmethod, ABC
+from multiprocessing import Manager
+import os
+import bz2
+import RNS
+
+_TLink = TypeVar("_TLink")
+_TIdentity = TypeVar("_TIdentity")
+
+class SEType(enum.IntEnum):
+    SE_LINK_CLOSED = 0
+
+class SessionException(Exception):
+    def __init__(self, setype: SEType, msg: str, *args):
+        super().__init__(msg, args)
+        self.type = setype
+
+class LSState(enum.IntEnum):
+    LSSTATE_WAIT_IDENT = 1
+    LSSTATE_WAIT_VERS  = 2
+    LSSTATE_WAIT_CMD   = 3
+    LSSTATE_RUNNING    = 4
+    LSSTATE_ERROR      = 5
+    LSSTATE_TEARDOWN   = 6
+
+
+class LSOutletBase(ABC):
+    @abstractmethod
+    def set_initiator_identified_callback(self, cb: Callable[[LSOutletBase, _TIdentity], None]): raise NotImplemented()
+
+    @abstractmethod
+    def set_link_closed_callback(self, cb: Callable[[LSOutletBase], None]): raise NotImplemented()
+
+    @abstractmethod
+    def unset_link_closed_callback(self): raise NotImplemented()
+
+    @property
+    @abstractmethod
+    def rtt(self): raise NotImplemented()
+
+    @abstractmethod
+    def teardown(self): raise NotImplemented()
+
+
+class ListenerSession:
+    sessions: List[ListenerSession] = []
+    allowed_identity_hashes: [any] = []
+    allowed_file_identity_hashes: [any] = []
+    allow_all: bool = False
+    allow_remote_command: bool = False
+    default_command: [str] = []
+    remote_cmd_as_args = False
+
+    def __init__(self, outlet: LSOutletBase, channel: RNS.Channel.Channel, loop: asyncio.AbstractEventLoop):
+        RNS.log(f"Session started for {outlet}", RNS.LOG_INFO)
+        self.outlet = outlet
+        self.channel = channel
+        self.outlet.set_initiator_identified_callback(self._initiator_identified)
+        self.outlet.set_link_closed_callback(self._link_closed)
+        self.loop = loop
+        self.state: LSState = None
+        self.remote_identity = None
+        self.term: str | None = None
+        self.stdin_is_pipe: bool = False
+        self.stdout_is_pipe: bool = False
+        self.stderr_is_pipe: bool = False
+        self.tcflags: [any] = None
+        self.cmdline: [str] = None
+        self.rows: int = 0
+        self.cols: int = 0
+        self.hpix: int = 0
+        self.vpix: int = 0
+        self.stdout_buf = bytearray()
+        self.stdout_eof_sent = False
+        self.stderr_buf = bytearray()
+        self.stderr_eof_sent = False
+        self.return_code: int | None = None
+        self.return_code_sent = False
+        self.process: process.CallbackSubprocess | None = None
+
+        if self.allow_all: self._set_state(LSState.LSSTATE_WAIT_VERS)
+        else: self._set_state(LSState.LSSTATE_WAIT_IDENT)
+
+        self.sessions.append(self)
+        protocol.register_message_types(self.channel)
+        self.channel.add_message_handler(self._handle_message)
+
+    def _terminated(self, return_code: int):
+        self.return_code = return_code
+
+    def _set_state(self, state: LSState, timeout_factor: float = 10.0):
+        timeout = max(self.outlet.rtt * timeout_factor, max(self.outlet.rtt * 2, 10)) if timeout_factor is not None else None
+        RNS.log(f"Set state: {state.name}, timeout {timeout}", RNS.LOG_DEBUG)
+        orig_state = self.state
+        self.state = state
+        if timeout_factor is not None:
+            self._call(functools.partial(self._check_protocol_timeout, lambda: self.state == orig_state, state.name), timeout)
+
+    def _call(self, func: callable, delay: float = 0):
+        def call_inner():
+            if delay == 0: func()
+            else: self.loop.call_later(delay, func)
+        
+        self.loop.call_soon_threadsafe(call_inner)
+
+    def send(self, message: RNS.MessageBase):
+        self.channel.send(message)
+
+    def _protocol_error(self, name: str):
+        self.terminate(f"Protocol error ({name})")
+
+    def _protocol_timeout_error(self, name: str):
+        self.terminate(f"Protocol timeout error: {name}")
+
+    def terminate(self, error: str = None):
+        with contextlib.suppress(Exception):
+            RNS.log("Terminating session" + (f": {error}" if error else ""), RNS.LOG_DEBUG)
+            if error and self.state != LSState.LSSTATE_TEARDOWN:
+                with contextlib.suppress(Exception):
+                    self.send(protocol.ErrorMessage(error, True))
+
+            self.state = LSState.LSSTATE_ERROR
+            self._terminate_process()
+            self._call(self._prune, max(self.outlet.rtt * 3, process.CallbackSubprocess.PROCESS_PIPE_TIME+5))
+
+    def _prune(self):
+        self.state = LSState.LSSTATE_TEARDOWN
+        RNS.log("Pruning session", RNS.LOG_DEBUG)
+        with contextlib.suppress(ValueError):
+            self.sessions.remove(self)
+        with contextlib.suppress(Exception):
+            self.outlet.teardown()
+
+    def _check_protocol_timeout(self, fail_condition: Callable[[], bool], name: str):
+        timeout = True
+        try: timeout = self.state != LSState.LSSTATE_TEARDOWN and fail_condition()
+        except Exception as e: RNS.log(f"Error in protocol timeout: {e}", RNS.LOG_ERROR)
+        if timeout: self._protocol_timeout_error(name)
+
+    def _link_closed(self, outlet: LSOutletBase):
+        outlet.unset_link_closed_callback()
+
+        if outlet != self.outlet:
+            RNS.log("Link closed received from incorrect outlet", RNS.LOG_DEBUG)
+            return
+
+        RNS.log(f"link_closed {outlet}", RNS.LOG_DEBUG)
+        self.terminate()
+
+    def _initiator_identified(self, outlet, identity):
+        if outlet != self.outlet:
+            RNS.log("Identity received from incorrect outlet", RNS.LOG_DEBUG)
+            return
+
+        RNS.log(f"initiator_identified {identity} on link {outlet}", RNS.LOG_INFO)
+        if self.state not in [LSState.LSSTATE_WAIT_IDENT, LSState.LSSTATE_WAIT_VERS]:
+            self._protocol_error(LSState.LSSTATE_WAIT_IDENT.name)
+
+        if not self.allow_all and identity.hash not in self.allowed_identity_hashes and identity.hash not in self.allowed_file_identity_hashes:
+            self.terminate("Identity is not allowed.")
+
+        self.remote_identity = identity
+        self._set_state(LSState.LSSTATE_WAIT_VERS)
+
+    @classmethod
+    async def pump_all(cls) -> True:
+        processed_any = False
+        for session in cls.sessions:
+            processed = session.pump()
+            processed_any = processed_any or processed
+            await asyncio.sleep(0)
+
+
+    @classmethod
+    async def terminate_all(cls, reason: str):
+        for session in cls.sessions:
+            session.terminate(reason)
+            await asyncio.sleep(0)
+
+    def pump(self) -> bool:
+        def compress_adaptive(buf: bytes):
+            comp_tries = RNS.RawChannelWriter.COMPRESSION_TRIES
+            comp_try = 1
+            comp_success = False
+            
+            chunk_len = len(buf)
+            if chunk_len > RNS.RawChannelWriter.MAX_CHUNK_LEN:
+                chunk_len = RNS.RawChannelWriter.MAX_CHUNK_LEN
+            chunk_segment = None
+
+            chunk_segment = None
+            max_data_len = self.channel.mdu - protocol.StreamDataMessage.OVERHEAD
+            while chunk_len > 32 and comp_try < comp_tries:
+                chunk_segment_length = int(chunk_len/comp_try)
+                compressed_chunk = bz2.compress(buf[:chunk_segment_length])
+                compressed_length = len(compressed_chunk)
+                if compressed_length < max_data_len and compressed_length < chunk_segment_length:
+                    comp_success = True
+                    break
+                else:
+                    comp_try += 1
+
+            if comp_success:
+                diff = max_data_len - len(compressed_chunk)
+                chunk = compressed_chunk
+                processed_length = chunk_segment_length
+            else:
+                chunk = bytes(buf[:max_data_len])
+                processed_length = len(chunk)
+
+            return comp_success, processed_length, chunk
+
+        try:
+            if self.state != LSState.LSSTATE_RUNNING:
+                return False
+            elif not self.channel.is_ready_to_send():
+                return False
+            elif len(self.stderr_buf) > 0:
+                comp_success, processed_length, data = compress_adaptive(self.stderr_buf)
+                self.stderr_buf = self.stderr_buf[processed_length:]
+                send_eof = self.process.stderr_eof and len(data) == 0 and not self.stderr_eof_sent
+                self.stderr_eof_sent = self.stderr_eof_sent or send_eof
+                msg = protocol.StreamDataMessage(protocol.StreamDataMessage.STREAM_ID_STDERR,
+                                                 data, send_eof, comp_success)
+                self.send(msg)
+                if send_eof:
+                    self.stderr_eof_sent = True
+                return True
+            elif len(self.stdout_buf) > 0:
+                comp_success, processed_length, data = compress_adaptive(self.stdout_buf)
+                self.stdout_buf = self.stdout_buf[processed_length:]
+                send_eof = self.process.stdout_eof and len(data) == 0 and not self.stdout_eof_sent
+                self.stdout_eof_sent = self.stdout_eof_sent or send_eof
+                msg = protocol.StreamDataMessage(protocol.StreamDataMessage.STREAM_ID_STDOUT,
+                                                 data, send_eof, comp_success)
+                self.send(msg)
+                if send_eof:
+                    self.stdout_eof_sent = True
+                return True
+            elif self.return_code is not None and not self.return_code_sent:
+                msg = protocol.CommandExitedMessage(self.return_code)
+                self.send(msg)
+                self.return_code_sent = True
+                self._call(functools.partial(self._check_protocol_timeout,
+                                             lambda: self.state == LSState.LSSTATE_RUNNING, "CommandExitedMessage"),
+                           max(self.outlet.rtt * 5, 10))
+                return False
+        
+        except Exception as e: RNS.log(f"Error during pump: {e}", RNS.LOG_ERROR)
+        return False
+
+    def _terminate_process(self):
+        with contextlib.suppress(Exception):
+            if self.process and self.process.running:
+                self.process.terminate()
+
+    def _start_cmd(self, cmdline: [str], pipe_stdin: bool, pipe_stdout: bool, pipe_stderr: bool, tcflags: [any],
+                   term: str | None, rows: int, cols: int, hpix: int, vpix: int):
+
+        self.cmdline = self.default_command
+        if not self.allow_remote_command and cmdline and len(cmdline) > 0:
+            self.terminate("Remote command line not allowed by listener")
+            return
+
+        if self.remote_cmd_as_args and cmdline and len(cmdline) > 0:
+            self.cmdline.extend(cmdline)
+        elif cmdline and len(cmdline) > 0:
+            self.cmdline = cmdline
+
+
+        self.stdin_is_pipe = pipe_stdin
+        self.stdout_is_pipe = pipe_stdout
+        self.stderr_is_pipe = pipe_stderr
+        self.tcflags = tcflags
+        self.term = term
+
+        def stdout(data: bytes):
+            self.stdout_buf.extend(data)
+
+        def stderr(data: bytes):
+            self.stderr_buf.extend(data)
+
+        try:
+            self.process = process.CallbackSubprocess(argv=self.cmdline,
+                                                      env={"TERM": self.term or os.environ.get("TERM") or "xterm",
+                                                            "RNS_REMOTE_IDENTITY": (RNS.prettyhexrep(self.remote_identity.hash)
+                                                                if self.remote_identity and self.remote_identity.hash else "")},
+                                                      loop=self.loop,
+                                                      stdout_callback=stdout,
+                                                      stderr_callback=stderr,
+                                                      terminated_callback=self._terminated,
+                                                      stdin_is_pipe=self.stdin_is_pipe,
+                                                      stdout_is_pipe=self.stdout_is_pipe,
+                                                      stderr_is_pipe=self.stderr_is_pipe)
+            self.process.start()
+            self._set_window_size(rows, cols, hpix, vpix)
+        except Exception as e:
+            RNS.log(f"Unable to start process for link {self.outlet}: {e}", RNS.LOG_ERROR)
+            self.terminate("Unable to start process")
+
+    def _set_window_size(self, rows: int, cols: int, hpix: int, vpix: int):
+        self.rows = rows
+        self.cols = cols
+        self.hpix = hpix
+        self.vpix = vpix
+        with contextlib.suppress(Exception):
+            self.process.set_winsize(rows, cols, hpix, vpix)
+
+    def _received_stdin(self, data: bytes, eof: bool):
+        if data and len(data) > 0:
+            self.process.write(data)
+        if eof:
+            self.process.close_stdin()
+
+    def _handle_message(self, message: RNS.MessageBase):
+        if self.state == LSState.LSSTATE_WAIT_IDENT:
+            # Ignore any messages until the initiator has identified to avoid race conditions
+            # between identity announcement and early protocol messages.
+            RNS.log("Ignoring message while waiting for identification", RNS.LOG_DEBUG)
+            return
+        if self.state == LSState.LSSTATE_WAIT_VERS:
+            if not isinstance(message, protocol.VersionInfoMessage):
+                self._protocol_error(self.state.name)
+                return
+            RNS.log(f"Version {message.sw_version}, protocol {message.protocol_version} on link {self.outlet}", RNS.LOG_VERBOSE)
+            if message.protocol_version != protocol.PROTOCOL_VERSION:
+                self.terminate("Incompatible protocol")
+                return
+            self.send(protocol.VersionInfoMessage())
+            self._set_state(LSState.LSSTATE_WAIT_CMD)
+            return
+        elif self.state == LSState.LSSTATE_WAIT_CMD:
+            if not isinstance(message, protocol.ExecuteCommandMesssage):
+                return self._protocol_error(self.state.name)
+            RNS.log(f"Execute command message on link {self.outlet}: {message.cmdline}", RNS.LOG_VERBOSE)
+            self._set_state(LSState.LSSTATE_RUNNING)
+            self._start_cmd(message.cmdline, message.pipe_stdin, message.pipe_stdout, message.pipe_stderr,
+                            message.tcflags, message.term, message.rows, message.cols, message.hpix, message.vpix)
+            return
+        elif self.state == LSState.LSSTATE_RUNNING:
+            if isinstance(message, protocol.WindowSizeMessage):
+                self._set_window_size(message.rows, message.cols, message.hpix, message.vpix)
+            elif isinstance(message, protocol.StreamDataMessage):
+                if message.stream_id != protocol.StreamDataMessage.STREAM_ID_STDIN:
+                    RNS.log(f"Received stream data for invalid stream {message.stream_id} on link {self.outlet}", RNS.LOG_ERROR)
+                    return self._protocol_error(self.state.name)
+                self._received_stdin(message.data, message.eof)
+                return
+            elif isinstance(message, protocol.NoopMessage):
+                # echo noop only on listener--used for keepalive/connectivity check
+                self.send(message)
+                return
+        elif self.state in [LSState.LSSTATE_ERROR, LSState.LSSTATE_TEARDOWN]:
+            RNS.log(f"Received packet, but in state {self.state.name}", RNS.LOG_ERROR)
+            return
+        else:
+            self._protocol_error("unexpected message")
+            return
+
+
+class RNSOutlet(LSOutletBase):
+
+    def set_initiator_identified_callback(self, cb: Callable[[LSOutletBase, _TIdentity], None]):
+        def inner_cb(link, identity: _TIdentity):
+            cb(self, identity)
+
+        self.link.set_remote_identified_callback(inner_cb)
+
+    def set_link_closed_callback(self, cb: Callable[[LSOutletBase], None]):
+        def inner_cb(link):
+            cb(self)
+
+        self.link.set_link_closed_callback(inner_cb)
+
+    def unset_link_closed_callback(self):
+        self.link.set_link_closed_callback(None)
+
+    def teardown(self):
+        self.link.teardown()
+
+    @property
+    def rtt(self) -> float:
+        return self.link.rtt
+
+    def __str__(self):
+        return f"Outlet RNS Link {self.link}"
+
+    def __init__(self, link: RNS.Link):
+        self.link = link
+        link.lsoutlet = self
+
+    @staticmethod
+    def get_outlet(link: RNS.Link):
+        if hasattr(link, "lsoutlet"):
+            return link.lsoutlet
+
+        return RNSOutlet(link)

RNS/Utilities/rnstatus.py

@@ -35,6 +35,7 @@ import os
 import sys
 import time
 import argparse
+import io
 
 from RNS._version import __version__
 
@@ -141,14 +142,12 @@ def get_remote_status(destination_hash, include_lstats, identity, no_output=Fals
 
     return request_result
 
-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, must_exit=True, rns_instance=None, traffic_totals=False):
-    
-    if remote:
-        require_shared = False
-    else:
-        require_shared = True
+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, must_exit=True, rns_instance=None,
+                  traffic_totals=False, discovered_interfaces=False, config_entries=False):
+  
+    if remote: require_shared = False
+    else: require_shared = True
 
     try:
         if rns_instance:
@@ -159,13 +158,146 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
 
     except Exception as e:
         print("No shared RNS instance available to get status from")
-        if must_exit:
-            exit(1)
-        else:
-            return
+        if must_exit: exit(1)
+        else: return
 
     link_count = None
     stats = None
+
+    details = False
+    if config_entries:
+        discovered_interfaces = True
+        details = True
+
+    if discovered_interfaces:
+        if_discovery = RNS.Discovery.InterfaceDiscovery(discover_interfaces=False)
+        ifs = if_discovery.list_discovered_interfaces()
+        print("")
+
+        if json:
+            import json
+            for i in ifs:
+                for e in i:
+                    if isinstance(i[e], bytes): i[e] = RNS.hexrep(i[e], delimit=False)
+          
+            print(json.dumps(ifs))
+
+        else:
+            filtered_ifs = []
+            for i in ifs:
+                name = i["name"]
+                if not name_filter or name_filter.lower() in name.lower(): filtered_ifs.append(i)
+          
+            if details:
+                for idx, i in enumerate(filtered_ifs):
+                    try:
+                        name = i["name"]
+                        if_type = i["type"]
+                        status = i["status"]
+
+                        if status == "available": status_display = "Available"
+                        elif status == "unknown": status_display = "Unknown"
+                        elif status == "stale":   status_display = "Stale"
+                        else:                     status_display = status
+
+                        now  = time.time()
+                        dago = now-i["discovered"]
+                        hago = now-i["last_heard"]
+                        discovered_display = f"{RNS.prettytime(dago, compact=True)} ago"
+                        last_heard_display = f"{RNS.prettytime(hago, compact=True)} ago"
+                        transport_str = "Enabled" if i["transport"] else "Disabled"
+
+                        if i["latitude"] is not None and i["longitude"] is not None:
+                            lat = round(i["latitude"], 4)
+                            lon = round(i["longitude"], 4)
+                            if i["height"] != None: height = ", "+str(i["height"])+"m h"
+                            else: height = ""
+                            location = f"{lat}, {lon}{height}"
+                        else: location = "Unknown"
+
+                        transport_id = None
+                        network = None
+                        if "transport_id" in i: transport_id = i["transport_id"]
+                        if "transport_id" in i and "network_id" in i and i["transport_id"] != i["network_id"]:
+                            network = i["network_id"]
+
+                        if idx > 0:      print("\n"+"="*32+"\n")
+                        if network:      print(f"Network   ID : {network}")
+                        if transport_id: print(f"Transport ID : {transport_id}")
+
+                        print(f"Name         : {name}")
+                        print(f"Type         : {if_type}")
+                        print(f"Status       : {status_display}")
+                        print(f"Transport    : {transport_str}")
+                        print(f"Distance     : {i['hops']} hop{'' if i['hops'] == 1 else 's'}")
+                        print(f"Discovered   : {discovered_display}")
+                        print(f"Last Heard   : {last_heard_display}")
+                        print(f"Location     : {location}")
+
+                        if "frequency" in i:    print(f"Frequency    : {i['frequency']:,} Hz")
+                        if "bandwidth" in i:    print(f"Bandwidth    : {i['bandwidth']:,} Hz")
+                        if "sf" in i:           print(f"Sprd. Factor : {i['sf']}")
+                        if "cr" in i:           print(f"Coding Rate  : {i['cr']}")
+                        if "modulation" in i:   print(f"Modulation   : {i['modulation']}")
+                        if "reachable_on" in i: print(f"Address      : {i['reachable_on']}")
+                        if "port" in i:         print(f"Port         : {i['port']}")
+
+                        print(f"Stamp Value  : {i['value']}")
+
+                        print(f"\nConfiguration Entry:")
+                        config_lines = i["config_entry"].split('\n')
+                        for line in config_lines: print(f"  {line}")
+
+                    except Exception as e:
+                        pass
+              
+            else:
+                print(f"{'Name':<25} {'Type':<12} {'Status':<12} {'Last Heard':<12} {'Value':<8} {'Location':<15}")
+                print("-" * 89)
+                
+                for i in filtered_ifs:
+                    try:
+                        name = i["name"][:24] + "…" if len(i["name"]) > 24 else i["name"]
+                        
+                        if_type = i["type"].replace("Interface", "")
+                        
+                        status = i["status"]
+                        if status == "available": status_display = "✓ Available"
+                        elif status == "unknown": status_display = "? Unknown"
+                        elif status == "stale":   status_display = "× Stale"
+                        else:                     status_display = status
+                        
+                        now = time.time()
+                        last_heard = i["last_heard"]
+                        diff = now - last_heard
+                        
+                        if diff < 60: last_heard_display = "Just now"
+                        elif diff < 3600:
+                            mins = int(diff / 60)
+                            last_heard_display = f"{mins}m ago"
+                        elif diff < 86400:
+                            hours = int(diff / 3600)
+                            last_heard_display = f"{hours}h ago"
+                        else:
+                            days = int(diff / 86400)
+                            last_heard_display = f"{days}d ago"
+                        
+                        value = str(i["value"])
+                        
+                        if i["latitude"] is not None and i["longitude"] is not None:
+                            lat = round(i["latitude"], 4)
+                            lon = round(i["longitude"], 4)
+                            location = f"{lat}, {lon}"
+                        else: location = "N/A"
+                        
+                        print(f"{name:<25} {if_type:<12} {status_display:<12} {last_heard_display:<12} {value:<8} {location:<15}")
+
+                    except Exception as e:
+                        pass
+
+        if must_exit: exit(0)
+        else: return
+
     if remote:
         try:
             if management_identity is None:
@@ -190,25 +322,19 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                     stats, link_count = remote_status
             except Exception as e:
                 raise e
-                    
+                  
         except Exception as e:
             print(str(e))
-            if must_exit:
-                exit(20)
-            else:
-                return
+            if must_exit: exit(20)
+            else: return
 
     else:
         if lstats:
-            try:
-                link_count = reticulum.get_link_count()
-            except Exception as e:
-                pass
+            try: link_count = reticulum.get_link_count()
+            except Exception as e: pass
 
-        try:
-            stats = reticulum.get_interface_stats()
-        except Exception as e:
-            pass
+        try: stats = reticulum.get_interface_stats()
+        except Exception as e: pass
 
     if stats != None:
         if json:
@@ -225,10 +351,8 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                                     i[k] = RNS.hexrep(i[k], delimit=False)
 
             print(json.dumps(stats))
-            if must_exit:
-                exit()
-            else:
-                return
+            if must_exit: exit()
+            else: return
 
         interfaces = stats["interfaces"]
         if sorting != None and isinstance(sorting, str):
@@ -254,7 +378,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
             if sorting == "held":
                 interfaces.sort(key=lambda i: i["held_announces"], reverse=not sort_reverse)
 
-            
+          
         for ifstat in interfaces:
             name = ifstat["name"]
 
@@ -263,6 +387,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                 name.startswith("TCPInterface[Client") or
                 name.startswith("BackboneInterface[Client on") or
                 name.startswith("AutoInterfacePeer[") or
+                name.startswith("WeaveInterfacePeer[") or
                 name.startswith("I2PInterfacePeer[Connected peer") or
                 (name.startswith("I2PInterface[") and ("i2p_connectable" in ifstat and ifstat["i2p_connectable"] == False))
                 ):
@@ -271,23 +396,15 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                     if name_filter == None or name_filter.lower() in name.lower():
                         print("")
 
-                        if ifstat["status"]:
-                            ss = "Up"
-                        else:
-                            ss = "Down"
+                        if ifstat["status"]: ss = "Up"
+                        else: ss = "Down"
 
-                        if ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_ACCESS_POINT:
-                            modestr = "Access Point"
-                        elif ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_POINT_TO_POINT:
-                            modestr = "Point-to-Point"
-                        elif ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_ROAMING:
-                            modestr = "Roaming"
-                        elif ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_BOUNDARY:
-                            modestr = "Boundary"
-                        elif ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_GATEWAY:
-                            modestr = "Gateway"
-                        else:
-                            modestr = "Full"
+                        if ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_ACCESS_POINT: modestr = "Access Point"
+                        elif ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_POINT_TO_POINT: modestr = "Point-to-Point"
+                        elif ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_ROAMING: modestr = "Roaming"
+                        elif ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_BOUNDARY: modestr = "Boundary"
+                        elif ifstat["mode"] == RNS.Interfaces.Interface.Interface.MODE_GATEWAY: modestr = "Gateway"
+                        else: modestr = "Full"
 
 
                         if ifstat["clients"] != None:
@@ -319,6 +436,9 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
 
                         print(" {n}".format(n=ifstat["name"]))
 
+                        if "autoconnect_source" in ifstat and ifstat["autoconnect_source"] != None:
+                            print("    Source    : Auto-connect via <{ns}>".format(ns=ifstat["autoconnect_source"]))
+
                         if "ifac_netname" in ifstat and ifstat["ifac_netname"] != None:
                             print("    Network   : {nn}".format(nn=ifstat["ifac_netname"]))
 
@@ -334,10 +454,32 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                             print("    Rate      : {ss}".format(ss=speed_str(ifstat["bitrate"])))
 
                         if "noise_floor" in ifstat:
-                            if ifstat["noise_floor"] != None:
-                                print("    Noise Fl. : {nfl} dBm".format(nfl=str(ifstat["noise_floor"])))
+                            if not "interference" in ifstat: nstr = ""
                             else:
-                                print("    Noise Fl. : Unknown")
+                                nf = ifstat["interference"]
+                                lstr = ", no interference"
+                                if "interference_last_ts" in ifstat and "interference_last_dbm" in ifstat:
+                                    lago = time.time()-ifstat["interference_last_ts"]
+                                    ldbm = ifstat["interference_last_dbm"]
+                                    lstr = f"\n    Intrfrnc. : {ldbm} dBm {RNS.prettytime(lago, compact=True)} ago"
+
+
+                                nstr = f"\n    Intrfrnc. : {nf} dBm" if nf else lstr
+
+                            if ifstat["noise_floor"] != None: print("    Noise Fl. : {nfl} dBm{ntr}".format(nfl=str(ifstat["noise_floor"]), ntr=nstr))
+                            else: print("    Noise Fl. : Unknown")
+
+                        if "cpu_load" in ifstat:
+                            if ifstat["cpu_load"] != None: print("    CPU load  : {v} %".format(v=str(ifstat["cpu_load"])))
+                            else:                          print("    CPU load  : Unknown")
+
+                        if "cpu_temp" in ifstat:
+                            if ifstat["cpu_temp"] != None: print("    CPU temp  : {v}°C".format(v=str(ifstat["cpu_temp"])))
+                            else:                          print("    CPU load  : Unknown")
+
+                        if "mem_load" in ifstat:
+                            if ifstat["cpu_load"] != None: print("    Mem usage : {v} %".format(v=str(ifstat["mem_load"])))
+                            else:                          print("    Mem usage : Unknown")
 
                         if "battery_percent" in ifstat and ifstat["battery_percent"] != None:
                             try:
@@ -349,10 +491,22 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
 
                         if "airtime_short" in ifstat and "airtime_long" in ifstat:
                             print("    Airtime   : {ats}% (15s), {atl}% (1h)".format(ats=str(ifstat["airtime_short"]),atl=str(ifstat["airtime_long"])))
-                        
+                      
                         if "channel_load_short" in ifstat and "channel_load_long" in ifstat:
                             print("    Ch. Load  : {ats}% (15s), {atl}% (1h)".format(ats=str(ifstat["channel_load_short"]),atl=str(ifstat["channel_load_long"])))
 
+                        if "switch_id" in ifstat:
+                            if ifstat["switch_id"] != None: print("    Switch ID : {v}".format(v=str(ifstat["switch_id"])))
+                            else:                           print("    Switch ID : Unknown")
+
+                        if "endpoint_id" in ifstat:
+                            if ifstat["endpoint_id"] != None: print("    Endpoint  : {v}".format(v=str(ifstat["endpoint_id"])))
+                            else:                             print("    Endpoint  : Unknown")
+
+                        if "via_switch_id" in ifstat:
+                            if ifstat["via_switch_id"] != None: print("    Via       : {v}".format(v=str(ifstat["via_switch_id"])))
+                            else:                               print("    Via       : Unknown")
+
                         if "peers" in ifstat and ifstat["peers"] != None:
                             print("    Peers     : {np} reachable".format(np=ifstat["peers"]))
 
@@ -362,7 +516,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                         if "ifac_signature" in ifstat and ifstat["ifac_signature"] != None:
                             sigstr = "<…"+RNS.hexrep(ifstat["ifac_signature"][-5:], delimit=False)+">"
                             print("    Access    : {nb}-bit IFAC by {sig}".format(nb=ifstat["ifac_size"]*8, sig=sigstr))
-                        
+                      
                         if "i2p_b32" in ifstat and ifstat["i2p_b32"] != None:
                             print("    I2P B32   : {ep}".format(ep=str(ifstat["i2p_b32"])))
 
@@ -372,14 +526,14 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                                 print("    Queued    : {np} announce".format(np=aqn))
                             else:
                                 print("    Queued    : {np} announces".format(np=aqn))
-                        
+                      
                         if astats and "held_announces" in ifstat and ifstat["held_announces"] != None and ifstat["held_announces"] > 0:
                             aqn = ifstat["held_announces"]
                             if aqn == 1:
                                 print("    Held      : {np} announce".format(np=aqn))
                             else:
                                 print("    Held      : {np} announces".format(np=aqn))
-                        
+                      
                         if astats and "incoming_announce_frequency" in ifstat and ifstat["incoming_announce_frequency"] != None:
                             print("    Announces : {iaf}↑".format(iaf=RNS.prettyfrequency(ifstat["outgoing_announce_frequency"])))
                             print("                {iaf}↓".format(iaf=RNS.prettyfrequency(ifstat["incoming_announce_frequency"])))
@@ -397,7 +551,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                         if "rxs" in ifstat and "txs" in ifstat:
                             rxstat += "  "+RNS.prettyspeed(ifstat["rxs"])
                             txstat += "  "+RNS.prettyspeed(ifstat["txs"])
-                        
+                      
                         print(f"    Traffic   : {txstat}\n                {rxstat}")
 
         lstr = ""
@@ -423,6 +577,8 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
 
         if "transport_id" in stats and stats["transport_id"] != None:
             print("\n Transport Instance "+RNS.prettyhexrep(stats["transport_id"])+" running")
+            if "network_id" in stats and stats["network_id"] != None:
+                print(" Network Identity   "+RNS.prettyhexrep(stats["network_id"]))
             if "probe_responder" in stats and stats["probe_responder"] != None:
                 print(" Probe responder at "+RNS.prettyhexrep(stats["probe_responder"])+ " active")
             if "transport_uptime" in stats and stats["transport_uptime"] != None:
@@ -432,7 +588,7 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None, json=
                 print(f"\n{lstr}")
 
         print("")
-                
+              
     else:
         if not remote:
             print("Could not get RNS status")
@@ -449,125 +605,67 @@ def main(must_exit=True, rns_instance=None):
         parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
         parser.add_argument("--version", action="version", version="rnstatus {version}".format(version=__version__))
 
-        parser.add_argument(
-            "-a",
-            "--all",
-            action="store_true",
-            help="show all interfaces",
-            default=False
-        )
-        
-        parser.add_argument(
-            "-A",
-            "--announce-stats",
-            action="store_true",
-            help="show announce stats",
-            default=False
-        )
-        
-        parser.add_argument(
-            "-l",
-            "--link-stats",
-            action="store_true",
-            help="show link stats",
-            default=False,
-        )
-        
-        parser.add_argument(
-            "-t",
-            "--totals",
-            action="store_true",
-            help="display traffic totals",
-            default=False,
-        )
-        
-        parser.add_argument(
-            "-s",
-            "--sort",
-            action="store",
-            help="sort interfaces by [rate, traffic, rx, tx, rxs, txs, announces, arx, atx, held]",
-            default=None,
-            type=str
-        )
-        
-        parser.add_argument(
-            "-r",
-            "--reverse",
-            action="store_true",
-            help="reverse sorting",
-            default=False,
-        )
-        
-        parser.add_argument(
-            "-j",
-            "--json",
-            action="store_true",
-            help="output in JSON format",
-            default=False
-        )
-
-        parser.add_argument(
-            "-R",
-            action="store",
-            metavar="hash",
-            help="transport identity hash of remote instance to get status from",
-            default=None,
-            type=str
-        )
-
-        parser.add_argument(
-            "-i",
-            action="store",
-            metavar="path",
-            help="path to identity used for remote management",
-            default=None,
-            type=str
-        )
-
-        parser.add_argument(
-            "-w",
-            action="store",
-            metavar="seconds",
-            type=float,
-            help="timeout before giving up on remote queries",
-            default=RNS.Transport.PATH_REQUEST_TIMEOUT
-        )
-
+        parser.add_argument("-a", "--all", action="store_true", help="show all interfaces", default=False)
+        parser.add_argument("-A", "--announce-stats", action="store_true", help="show announce stats", default=False)
+        parser.add_argument("-l", "--link-stats", action="store_true", help="show link stats", default=False)
+        parser.add_argument("-t", "--totals", action="store_true", help="display traffic totals", default=False)
+        parser.add_argument("-s", "--sort", action="store", help="sort interfaces by [rate, traffic, rx, tx, rxs, txs, announces, arx, atx, held]", default=None, type=str)
+        parser.add_argument("-r", "--reverse", action="store_true", help="reverse sorting", default=False)
+        parser.add_argument("-j", "--json", action="store_true", help="output in JSON format", default=False)
+        parser.add_argument("-R", action="store", metavar="hash", help="transport identity hash of remote instance to get status from", default=None, type=str)
+        parser.add_argument("-i", action="store", metavar="path", help="path to identity used for remote management", default=None, type=str)
+        parser.add_argument("-w", action="store", metavar="seconds", type=float, help="timeout before giving up on remote queries", default=RNS.Transport.PATH_REQUEST_TIMEOUT)
+        parser.add_argument("-d", "--discovered", action="store_true", help="list discovered interfaces", default=False)
+        parser.add_argument("-D",                 action="store_true", help="show details and config entries for discovered interfaces", default=False)
+        parser.add_argument("-m", "--monitor", action="store_true", help="continuously monitor status", default=False)
+        parser.add_argument("-I", "--monitor-interval", action="store", metavar="seconds", type=float, help="refresh interval for monitor mode (default: 1)", default=1.0)
         parser.add_argument('-v', '--verbose', action='count', default=0)
-
         parser.add_argument("filter", nargs="?", default=None, help="only display interfaces with names including filter", type=str)
-        
+      
         args = parser.parse_args()
 
-        if args.config:
-            configarg = args.config
-        else:
-            configarg = None
+        if args.config: configarg = args.config
+        else:           configarg = None
 
-        program_setup(
-            configdir = configarg,
-            dispall = args.all,
-            verbosity=args.verbose,
-            name_filter=args.filter,
-            json=args.json,
-            astats=args.announce_stats,
-            lstats=args.link_stats,
-            sorting=args.sort,
-            sort_reverse=args.reverse,
-            remote=args.R,
-            management_identity=args.i,
-            remote_timeout=args.w,
-            must_exit=must_exit,
-            rns_instance=rns_instance,
-            traffic_totals=args.totals,
-        )
+        if args.monitor:
+            if args.R: require_shared = False
+            else:      require_shared = True
+          
+            try: reticulum = RNS.Reticulum(configdir=configarg, loglevel=3+args.verbose, require_shared_instance=require_shared)
+            except Exception as e:
+                print("No shared RNS instance available to get status from")
+                exit(1)
+
+            while True:
+                buffer = io.StringIO()
+                old_stdout = sys.stdout
+                sys.stdout = buffer
+              
+                try:
+                    program_setup(configdir = configarg, dispall = args.all, verbosity=args.verbose, name_filter=args.filter, json=args.json,
+                                  astats=args.announce_stats, lstats=args.link_stats, sorting=args.sort, sort_reverse=args.reverse, remote=args.R,
+                                  management_identity=args.i, remote_timeout=args.w, must_exit=False, rns_instance=reticulum, traffic_totals=args.totals,
+                                  discovered_interfaces=args.discovered, config_entries=args.D)
+              
+                finally:
+                    sys.stdout = old_stdout
+              
+                output = buffer.getvalue()
+                print("\033[H\033[2J", end="")
+                print(output, end="", flush=True)
+              
+                time.sleep(args.monitor_interval)
+
+        else:
+            program_setup(configdir = configarg, dispall = args.all, verbosity=args.verbose, name_filter=args.filter, json=args.json,
+                          astats=args.announce_stats, lstats=args.link_stats, sorting=args.sort, sort_reverse=args.reverse, remote=args.R,
+                          management_identity=args.i, remote_timeout=args.w, must_exit=must_exit, rns_instance=rns_instance, traffic_totals=args.totals,
+                          discovered_interfaces=args.discovered, config_entries=args.D)
 
     except KeyboardInterrupt:
         print("")
-        if must_exit:
-            exit()
-        else:
-            return
+        if must_exit: exit()
+        else: return
 
 def speed_str(num, suffix='bps'):
     units = ['','k','M','G','T','P','E','Z']

RNS/Utilities/rnx.py

@@ -91,7 +91,25 @@ def listen(configdir, identitypath = None, verbosity = 0, quietness = 0, allowed
                 except Exception as e:
                     print(str(e))
                     exit(1)
-
+        try:
+            allowed_file_name = "allowed_identities"
+            allowed_file = None
+            if os.path.isfile(os.path.expanduser("/etc/rnx/"+allowed_file_name)):
+                allowed_file = os.path.expanduser("/etc/rnx/"+allowed_file_name)
+            elif os.path.isfile(os.path.expanduser("~/.config/rnx/"+allowed_file_name)):
+                allowed_file = os.path.expanduser("~/.config/rnx/"+allowed_file_name)
+            elif os.path.isfile(os.path.expanduser("~/.rnx/"+allowed_file_name)):
+                allowed_file = os.path.expanduser("~/.rnx/"+allowed_file_name)
+            if allowed_file != None:
+                with open(allowed_file, "r") as af_handle:
+                    allowed_by_file = af_handle.read().replace("\r", "").split("\n")
+                    for allowed_ID in allowed_by_file:
+                        if len(allowed_ID) == (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2:
+                            allowed_identity_hashes.append(bytes.fromhex(allowed_ID))      
+        except Exception as e:
+            print(str(e))
+            exit(1)
+                    
     if len(allowed_identity_hashes) < 1 and not disable_auth:
         print("Warning: No allowed identities configured, rncx will not accept any commands!")
 

RNS/__init__.py

@@ -44,6 +44,7 @@ from .Link import Link, RequestReceipt
 from .Channel import MessageBase
 from .Buffer import Buffer, RawChannelReader, RawChannelWriter
 from .Transport import Transport
+from .Discovery import InterfaceAnnouncer
 from .Destination import Destination
 from .Packet import Packet
 from .Packet import PacketReceipt
@@ -142,18 +143,16 @@ def log(msg, level=3, _override_destination = False, pt=False):
         with logging_lock:
             if (logdest == LOG_STDOUT or _always_override_destination or _override_destination):
                 if not threading.main_thread().is_alive(): return
-                else: print(logstring)
+                else:
+                    try: print(logstring)
+                    except: pass
 
             elif (logdest == LOG_FILE and logfile != None):
                 try:
-                    file = open(logfile, "a")
-                    file.write(logstring+"\n")
-                    file.close()
-                    
+                    with open(logfile, "a") as file: file.write(logstring+"\n")
                     if os.path.getsize(logfile) > LOG_MAXSIZE:
                         prevfile = logfile+".1"
-                        if os.path.isfile(prevfile):
-                            os.unlink(prevfile)
+                        if os.path.isfile(prevfile): os.unlink(prevfile)
                         os.rename(logfile, prevfile)
 
                 except Exception as e:
@@ -163,8 +162,7 @@ def log(msg, level=3, _override_destination = False, pt=False):
                     log(msg, level)
 
             elif logdest == LOG_CALLBACK:
-                try:
-                    logcall(logstring)
+                try: logcall(logstring)
                 except Exception as e:
                     _always_override_destination = True
                     log("Exception occurred while calling external log handler: "+str(e), LOG_CRITICAL)
@@ -199,6 +197,11 @@ def prettyhexrep(data):
     hexrep = "<"+delimiter.join("{:02x}".format(c) for c in data)+">"
     return hexrep
 
+def prettyb256rep(data):
+    delimiter = ""
+    b256rep = "<"+delimiter.join(b256_rep(c) for c in data)+">"
+    return b256rep
+
 def prettyspeed(num, suffix="b"):
     return prettysize(num/8, suffix=suffix)+"ps"
 
@@ -222,6 +225,7 @@ def prettysize(num, suffix='B'):
     return "%.2f%s%s" % (num, last_unit, suffix)
 
 def prettyfrequency(hz, suffix="Hz"):
+    if hz == 0: return "0 Hz"
     num = hz*1e6
     units = ["µ", "m", "", "K","M","G","T","P","E","Z"]
     last_unit = "Y"
@@ -541,4 +545,26 @@ class Profiler:
             if tag["super"] == None:
                 print_results_recursive(tag, results)
 
-profile = Profiler.get_profiler
+profile = Profiler.get_profiler
+
+b256 = [
+# 0   1   2   3   4   5   6   7   8   9   A   B   C   D   F   F
+ "a","b","c","d","e","f","g","h","i","j","k","l","m","n","o","p",  # 0x0 Latin & numerals
+ "q","r","s","t","u","v","x","y","z","æ","ø","0","1","2","3","4",  # 0x1 Latin & numerals
+ "A","B","C","D","E","F","G","H","I","J","K","L","M","N","O","P",  # 0x2 Latin & numerals
+ "Q","R","S","T","U","W","X","Y","Z","Æ","Ø","5","6","7","8","9",  # 0x3 Latin & numerals
+ "α","β","γ","δ","ε","ζ","η","θ","ι","κ","λ","μ","ν","ξ","π","ρ",  # 0x4 Greek
+ "σ","τ","φ","χ","ψ","ω","Γ","Δ","Θ","Λ","Ξ","Π","Σ","Φ","Ψ","Ω",  # 0x5 Greek
+ "Б","Д","Ж","З","И","Л","П","Ц","Ч","Ш","Щ","Ъ","Ы","Э","Ю","Я",  # 0x6 Cyrillic
+ "б","д","ж","з","и","л","п","ц","ч","ш","щ","ъ","ы","э","ю","я",  # 0x7 Cyrillic
+ "Ա","Բ","Գ","Դ","Ե","Զ","Է","Ը","Թ","Ժ","Ի","Խ","Ծ","Կ","Հ","Ձ",  # 0x8 Armenian Capitals
+ "Ղ","Ճ","Մ","Յ","Ն","Շ","Ո","Չ","Պ","Ջ","Վ","Ր","Ց","Ւ","Ք","Ֆ",  # 0x9 Armenian Captials
+ "ᚠ","ᚢ","ᚦ","ᚱ","ᚹ","ᚺ","ᚾ","ᛈ","ᛇ","ᛉ","ᛊ","ᛏ","ᛒ","ᛖ","ᛗ","ᛟ",   # 0xA Elder Futhark
+ "ｲ","ｳ","ｵ","ｶ","ｷ","ｹ","ｻ","ｼ","ｽ","ｾ","ﾀ","ﾁ","ﾃ","ﾄ","ﾅ","ﾇ",     # 0xB Katakana
+ "ﾈ","ﾋ","ﾌ","ﾍ","ﾎ","ﾏ","ﾐ","ﾑ","ﾒ","ﾓ","ﾔ","ﾗ","ﾘ","ﾙ","ﾚ","ﾜ",     # 0xC Katakana
+ "𐑐","𐑑","𐑒","𐑔","𐑕","𐑗","𐑙","𐑳","𐑶","𐑸","𐑹","𐑺","𐑻","𐑽","𐑾","𐑿",    # 0xD Shavian
+ "᱑","᱕","᱘","᱙","ᱚ","ᱝ","ᱟ","ᱣ","ᱦ","ᱨ","ᱬ","ᱭ","ᱰ","ᱳ","ᱶ","ᱷ", # 0xE Ol Chiki
+ "𐌳","𐌸","𐌾","𐐀","𐐁","𐐂","𐐆","𐐇","𐐈","𐐉","𐐊","𐐋","𐐌","𐐍","𐐎","𐐏", # 0xF Gothic & Deseret
+]
+
+def b256_rep(input_byte): return b256[int(input_byte)]

RNS/_version.py

@@ -1 +1 @@
-__version__ = "1.0.0"
+__version__ = "1.2.0"

Zen of Reticulum.md

@@ -0,0 +1,415 @@
+# Zen of Reticulum
+
+## I: The Illusion Of The Center
+
+For the better part of a generation, we have been taught to visualize the digital world through the lens of hierarchy. The mental maps we carry are dominated by a single, misleading image: **The Cloud**.
+
+We imagine the network as a vast, ethereal space "up there" or "out there". A centralized repository of services and data to which we, the lowly clients, must connect. We build our software with this assumption hardcoded into our logic: *There is a server. The server has the authority. The server knows the way. I must find the server to function*.
+
+This is the Client-Server mental model, and it is the primary obstacle to understanding Reticulum.
+
+### Fallacy Of The Cloud
+
+The first step in the Zen of Reticulum is to realize that *there is no cloud*. There is only other people's computers. When you build for the cloud, you are building *for* a landlord. You are accepting that your application's existence is conditional on the permission, uptime, and continued goodwill of a central authority.
+
+In Reticulum, you must shift your thinking from "connecting to" to "being among". Reticulum is not a service you subscribe to - *it is a fabric you inhabit*. There is no "up there". There is only *here* and *there*, and the space between them is peer-to-peer.
+
+### Decentralization Or Uncentralizability?
+
+It is common to hear the word "decentralized" thrown around in modern tech circles. But often, this is merely a marketing term for "slightly distributed centralization". A blockchain with a few dominant miners, or a federated protocol with a few giant servers. *In practice*, it's still centralized. It simply has a few centers instead of one.
+
+Reticulum goes further. It wants **Uncentralizability**.
+
+This is not a wishful political stance, but a foundational mathematical characteristic of the protocol, onto which everything else has been built. Reticulum assumes that every peer on the network is potentially hostile, and every link is potentially compromised. It is designed with no "privileged" nodes. While some nodes may act as Transport Instances - forwarding traffic for others - they do so *blindly*, and they only know about their immediate surroundings, and nothing more. They route based on cryptographic proofs, not on administrative privilege. They cannot see who is talking to whom, nor can they selectively manipulate traffic without breaking their own ability to route entirely.
+
+The system is designed to make hierarchy structurally impossible. You cannot hijack an address, because there is no central registry to hijack. You cannot block a user, because there is no central switch to flip. You can offer paths through the network, but you can't force anyone to use them.
+
+### Death To The Address
+
+To break free of the center, you must also let go of the concept of the "Address".
+
+In the IP world, an address is a location. It is a coordinate in a *deeply hierarchical* and static grid. If you move your computer to a different house, your address changes. If your router reboots, your address might change. Your *identity* is bound to your *location*, and therefore, it is fragile, and easily controlled.
+
+Reticulum abolishes this link between *Identity* and *Location*.
+
+In Reticulum, an address is not a place; it is a **Hash of an Identity**. It is a cryptographic representation of *who* you are, not *where* you are. Because of this, your address is portable. You can take a laptop from a WiFi cafe in Berlin, to a LoRa mesh in the mountains, to a packet radio link on a boat, and your "address" - your *Destination Hash* - never changes.
+
+The network does not route to a place; it routes to a *person* (or a machine). When you send a packet, you are not targeting a coordinate in a grid; you are encrypting a message for a specific entity. The network dynamically discovers where that entity currently resides, and it does so in a way where no one really knows where that entity is actually located physically.
+
+**Consider:**
+
+- **The Old Way:** *"I am at `192.168.1.5`. Come find me"*.
+- **The Zen Way:** *"I am `<327c1b2f87c9353e01769b01090b18f2>`. Wherever I am, my peers can reach me"*.
+
+Once you stop thinking about servers and start thinking about portable identities, where everyone can always reach everyone else directly, the illusion of the center fades away. You realize there *is* no center holding the network together. No coordinators or bureaucrats required. The network is simply the sum of its peers, communicating directly, sovereignly, and without a master.
+
+
+## II: Physics Of Trust
+*Paranoia Is A Great Design Principle*
+
+If we accept that there is no center - that the network is a chaotic, peer-to-peer mesh - we are forced to confront a terrifying reality: **There is no one guarding the door**.
+
+In the traditional networking mindset, we rely on the concept of the "trusted core". We assume our local coffee shop WiFi is safe, or that the backbone providers are neutral custodians. We build our security like a castle: strong walls on the outside, soft and trusting on the inside. We use encryption only when we step out into the "wild" internet.
+
+### Hostile Environments
+
+The Zen of Reticulum requires you to invert this. You must assume that *every* environment is hostile. This isn't cynicism, just uncaring physics.
+
+When you transmit information over radio waves, you are shouting into a crowded room. Anyone can listen. When you traverse the internet, your packets pass through routers controlled by strangers, corporations, and state actors. Assuming privacy in this environment without cryptographic protection is not optimism but gross negligence.
+
+Reticulum is built on the premise that every link is tapped, and every peer is a potential adversary. If your system cannot survive an adversary owning the physical layer, it cannot survive at all.
+
+But this is the paradox: By assuming the network is hostile, you make it safe. When you accept the dangers for what they are, they become manageable. When you stop trusting the infrastructure and start trusting the math, you eliminate the single point of failure: Human integrity.
+
+### Encryption Is Not A Feature
+
+In the world of TCP/IP, encryption is an afterthought. It is a layer we slap on top of the protocol (HTTPS, TLS) to patch the security holes of the original design. It is a "feature" you sometimes *enable* for "sensitive data". This is fundamentally flawed, since all data is sensitive.
+
+In Reticulum, encryption is **gravity**.
+
+It is not optional. It is not a plugin. It is the *fundamental force that allows the network to exist*. If you were to strip the encryption from Reticulum, the routing would break. The Transport system uses cryptographic signatures and entropy to verify paths and pass information. If packets were plaintext, intermediate nodes could not prove that a route was valid, nor could endpoints prevent spoofing or tampering.
+
+In Reticulum, the entropy of the encrypted packet *is* the routing logic.
+
+To ask for a version of Reticulum without encryption is like asking for a version of the ocean without liquid. You are not asking for a feature change; you're asking for a different physical universe. We design for a universe where information has mass, structure, and integrity.
+
+### Zero-Trust Architectures
+
+We must unlearn our reliance on **Institutional Trust**.
+
+For decades, we have been trained to trust authorities. We trust a website because a chain of Certificate Authorities (companies we don't know) vouches for it. We trust an app because it is in an app store (run by a corporation we don't control). We trust a message because it comes from a phone number assigned by a telecom. Yet, everything in our digital information sphere today is more untrustworthy and risky than a medieval second-hand underwear market.
+
+Reticulum replaces institutional trust with **Cryptographic Proof**.
+
+In Reticulum, you do not trust a node because it has a nice hostname or because it is listed in a directory. You trust it because it holds the private key corresponding to the Destination Hash you are communicating with. This trust is binary, mathematical, and **absolute**. Either the signature matches, or it does not. There is no "maybe".
+
+This shift moves the power from the institution to the individual. You become the ultimate arbiter of your own trust relationships. You decide which keys to accept, which paths to follow, and which identities to recognize.
+
+**Consider:**
+
+- **The Old Way:** *"I trust this site because the browser says the lock icon is green"*.
+- **The Zen Way:** *"I trust this destination because I have verified its hash fingerprint out-of-band, and the math confirms the signature"*.
+
+When you internalize the Physics of Trust, you stop looking for protection from firewalls, VPNs, and Terms of Service agreements. You realize that true security comes from the design of the protocol itself. You can stop trusting the cloud, and you start trusting the code - because you can verify it yourself.
+
+
+## III: Merits Of Scarcity
+*Every Bit Counts*
+
+We have grown addicted to abundance. In the modern digital ecosystem, bandwidth is treated as an endless, flat ocean. We stream high-definition video without a thought, we ship entire libraries of code just to render a single button, and we measure performance in gigabits per second. This abundance has hollowed out our craft. When constraints vanish, efficiency dies, and with it, a certain kind of Clarity and Quality.
+
+Reticulum asks you to step out of the ocean and onto the tightrope.
+
+### The Bandwidth Fallacy
+
+The Zen of Reticulum requires the realization that **5 bits per second is a valid speed**.
+
+To a modern developer, this sounds like paralysis. But there is a profound freedom in limits: When you have a gigabit connection, you can be incredibly sloppy. You can be wasteful. You can push your problems onto the infrastructure. *"It’s slow? Get a faster router"*.
+
+But on a high-latency, low-bandwidth link (be it a noisy HF radio channel or a tenuous LoRa hop) you cannot push problems anywhere. You must solve them. The network does not negotiate with waste.
+
+This forces a shift from consumption to interaction. You are no longer, then, consuming a service provided by a fat pipe; you are engaging in a careful negotiation with the physical medium. The medium becomes a partner in the conversation, not just a dumb conduit. You suddenly need to *understand the world to be in it*.
+
+### Cost Of A Byte
+
+In a scarce economy, a byte is not just data, but energy, time, and space.
+
+Every byte you transmit consumes battery life on a solar-powered node. It occupies valuable airtime that could have been used by another peer. It represents a measurable slice of the electromagnetic spectrum.
+
+When you internalize this, you begin to write code differently. You stop asking, "How much data can I send?" and start asking, "What is the *minimum* amount of information required to convey this intent? How can I best utilize my informational entropy?"
+
+This is where the elegance of Reticulum shines. The protocol is designed to strip away the non-essential. A link establishment takes three very small packets. A destination hash fits in 16 bytes. The overhead is vanishingly small, leaving almost the entire channel for the message itself.
+
+**Consider:**
+
+- **The Old Way:** *"I need to send a status update. I'll send a JSON object with metadata, timestamps, and user profile info (15KB)."*
+- **The Zen Way:** *"I need to send a status update. I'll send a single byte representing the state code. The context is already known."*
+
+This is of course optimization, but more importantly, *it is a form of respect*. Efficiency in a shared medium is an act of stewardship. By taking only what you need from the network, you leave room for others. The network listens to those who speak with purpose.
+
+### Flow & Time
+
+Scarcity also teaches us about time. We have become addicted to the *synchronous* now - the instant ping, the real-time stream. But Reticulum embraces *asynchronous* time.
+
+When links are intermittent and latency is measured in minutes or hours, "real-time" is an illusion. Reticulum doesn't encourage **Store and Forward** as a mere fallback, but as a primary mode of existence. You write a message, it propagates when it can, and it arrives when it arrives.
+
+This changes the psychological texture of communication. It removes the anxiety of the immediate response. It allows for contemplation. You are not demanding the recipient's attention *right now*; you are placing a gift in their path, to be found when they are ready.
+
+By designing for delay, you design for resilience. You are no longer building a house of cards that collapses when a single packet drops. You are building a stone arch that distributes the load *over time*.
+
+### Liberation From Limits
+
+There is a strange optimism in scarcity. When you are forced to work within strict constraints, you are forced to prioritize. *You* must decide what truly matters. *That* is the real core of agency.
+
+In the infinite fantasy world of The Cloud, everything is urgent, so nothing is. In the economy of Reticulum, the cost of transmission forces you to weigh the value of your message. Do you really need to send that heart beat? Is that photo essential?
+
+When you strip away the noise, what remains is *signal*.
+
+This discipline creates a different kind of developer. It creates a craftsman who understands that the best code is the code you don't have to write. It creates a user who understands that the most powerful message is the one that is *understood*, not the one that is loudest. In the world of Reticulum, you are not a mere consumer of bandwidth; you are an architect of intent.
+
+
+## IV: Sovereignty Through Infrastructure
+**Be Your Own Network**
+
+We live in an era of digital tenancy. We lease our connectivity from ISPs. We rent our storage from cloud providers. We even borrow our identity from social media platforms. We are tenants in a house we did not build, governed by rules we did not write, subject to eviction at the whim of a landlord who has never met us.
+
+The Zen of Reticulum is the realization that you *can* own the house.
+
+### A Carrier-Grade Fallacy
+
+For decades, we have been gaslit into believing that networking is really not just hard, but impossible. It is presented as a dark art reserved for telcos and billionaires, requiring millions of dollars of fiber optics, climate-controlled data centers, and armies of engineers. We are told that building reliable infrastructure is "too complex" for the individual or small organization.
+
+This is a big, fat lie.
+
+Physics is simple. A radio wave needs a transmitter and a receiver. A packet needs a path. The "complexity" of the modern internet is largely bureaucratic - a mountain of billing systems, regulatory capture, and legacy cruft designed to keep the gatekeepers in power.
+
+Reticulum strips away the bureaucracy. It runs on hardware that costs the price of a dinner. It runs on spectrum that is free to use. It demonstrates that a robust, planetary-scale network does not require a Fortune 500 company. It requires only the will to deploy, and the distributed, uncoordinated efforts of many individuals.
+
+### Personal Infrastructure
+
+This is where the rubber meets the road. You can read about Reticulum, you can understand the theory, but the insights only arrive when you plug in a radio and run a Transport Node. Suddenly, you are no longer a consumer. You're an operator.
+
+This shift is subtle but profound. When you run your own infrastructure, the network ceases to be a service that is provided *to* you. It becomes a space that you *inhabit*. You become responsible for the flow of information. You gain an intimate understanding of the medium - the way the weather affects the radio waves, the way the topology changes, the way the packets dance through the ether.
+
+There is a quiet competence that comes from this. You stop asking "Is the internet down?" and start asking "Is *my* links up?" You stop waiting for a technician and start checking the logs. This is a form of strength. To understand the system that carries your words is to be free from the mystery that keeps you dependent.
+
+### The Ability To Disconnect
+
+Why go to the trouble? Why buy the radio, write the config, and leave the Pi running in the corner?
+
+Because the old, centralized network is fragile. And because most of us doesn't even really want to be there anymore.
+
+The internet we rely on today is a chain of single points of failure. Cut the undersea cable, and a continent goes dark. Shut down the power grid, and the cloud evaporates. Deprioritize the "wrong" traffic, and the flow of information is strangled.
+
+Sovereignty is the ability to survive the cut, whether or not that cut was an accident or on purpose.
+
+When you build your own infrastructure, you build a lifeline. Reticulum is designed to function over media that the traditional internet cannot touch - bare wires, battery-powered radios, ad-hoc WiFi meshes. When the grid fails, or the censors arrive, or the bill goes unpaid, your Reticulum network continues to hum.
+
+This is not about "dropping out" of society. It is about building a substrate on which an actual *Society* can function.
+
+**Consider:**
+
+- **The Old Way:** "My connection is slow. I should call my ISP and complain."
+- **The Zen Way:** "The path is noisy. I will adjust the antenna or find a better route."
+
+By taking ownership of the infrastructure, you take ownership of your voice. You stop shouting into someone else's megaphone and start building your own. The network is no longer something that happens to you; it is something you make happen.
+
+
+# V: Identity and Nomadism
+**A Fluid Self**
+
+In the old world, you are defined by your coordinates. If you are at `34.109.71.5`, you're *here*. If you unplug the cable and walk down the street, you vanish. Your digital self evaporates because it was tethered to the wall. You are a ghost in the endless machinations of gears, levers and transistors, bound to the hardware, and those that own it.
+
+This creates a subtle, constant anxiety. We are terrified of disconnecting because, in the architecture of the old web, disconnecting is a kind of death.
+
+The Zen of Reticulum offers a different way to be.
+
+### Portable Existence
+
+In Reticulum, your identity is not a location, or a username granted by a service. It is a cryptographic key - a complex, unique mathematical signature that exists independently of the physical world. You can carry it only in your mind, if you want to.
+
+Think of it less like a street address and more like a name. *A true name*.
+
+If you travel from Berlin to Tokyo, you do not change your name. You are still you. The people who know you can still recognize you. Reticulum applies this principle to the network layer. Your Destination Hash is **invariant**. It travels with you, stored securely on your device, *immutable as a stone*.
+
+This changes the relationship between you and the machine. You are not "logged into" the network via a specific gateway. You *are* the endpoint. The network does not connect to a place; *it converges on you*.
+
+### Roaming Nodes
+
+This freedom introduces a new concept of time and space: **Nomadism**.
+
+Because your identity is portable, your connectivity can be fluid. You can be sitting at a desk connected to a fiber backbone one moment, and walking through a field connected only to a long-range LoRa mesh the next. To the rest of the network, nothing has changed. Your friends do not need to update your contact info. The messages they send do not bounce back. The network senses the shift in the medium and reroutes the flow of data automatically.
+
+You are no longer a stationary node in a fixed grid. You are a wanderer in a fluid medium.
+
+The interfaces - whether it is WiFi, Ethernet, Packet Radio, or a physical wire - is merely the clothing your node wears. You change it to suit the environment. Underneath, you remain the same. This is the liberation of the protocol. It treats the physical medium as a transient circumstance, not a definition of self.
+
+**Consider:**
+
+- **The Old Way:** *"I lost connection. I have to reconnect to the VPN to tell them where I am now."*
+- **The Zen Way:** *"I moved. The network subtly bends to accomodate this new reality."*
+
+### Announcing Presence
+
+How does the network find a wanderer? It listens.
+
+In the IP world, we query directories. We ask a server, "Where is Mark?" The server checks its database and gives us a coordinate. This means that someone, somewhere, is keeping track of you. It assumes and *requires* surveillance.
+
+Reticulum replaces surveillance with **Announces**.
+
+Instead of asking a central authority where you are, you simply state your presence. You broadcast a cryptographic proof: "I am here, and I am who I say I am". This ripples out through the mesh. Your neighbors hear it, update their path tables, and pass it on.
+
+This is a quiet, organic process. It is the digital equivalent of lighting lanterns in the dark. You do not need to chase the light; you let the light find you. It respects your autonomy. You choose when to announce, how often to speak, and to whom. You also choose when to disappear - for but a moment or perpetually.
+
+### Anchor In The Flow
+
+There is a deep peace in this nomadism. It teaches you that stability does not come from standing still. Stability comes from *internal coherence*.
+
+By holding your own private key, you hold your own center of gravity. The world around you; the infrastructure, the topography and the availability of links can all shift chaotically. Storms can knock out towers. Cables can be cut. The internet can go down.
+
+But as long as you possess your key, you possess your identity. The entire infrastructure can be destroyed and rebuilt, and you are still you. Nothing lasts, yet nothing is lost.
+
+You become a sovereign entity moving through the noise, connected not by the rigidity of cables, but by the fluidity of recognition. The network becomes a place you inhabit, rather than a utility you subscribe to: You are at home in the ether.
+
+
+## VI: Ethics Of The Tool
+**Technology With Conscience**
+
+You have unlearned the center. You have accepted the physics of trust. You have embraced the economy of scarcity and the freedom of unbound nomadism. You are standing in a new space. Now, look at the tool in your hand.
+
+In the old world, we were taught that technology is neutral. We are told that "guns don't kill people, people do", or that a component is just a component, indifferent to what its combinatorial potential is. This is a convenient lie. It serves only to allow the builders to wash their hands of responsibility.
+
+But we know better now. We know that **architecture is politics**, and *politics is control*. The way you build a system determines how it will be used. If you build a system optimized for mass surveillance, you *will* get a panopticon. If you build a system optimized for centralized control, you *will* get a dictatorship. If you build a system optimized for extraction, you *will* get a parasite.
+
+The Zen of Reticulum asserts that a tool is never neutral.
+
+On the very contrary: A tool is intent, **crystallized**.
+
+### The Harm Principle
+
+Why does the Reticulum License forbid the software from being used in systems designed to harm humans? Is it not just a restriction on freedom?
+
+It is a restriction on *license*, yes, but it is an expansion of *freedom*.
+
+Building powerful tools without a moral compass is in no way virtuous or commendable, it is plain and simple irresponsibility.
+
+A tool that can easily be used to oppress is a real danger to the user. If you build a network that can be turned against you by a tyrant, you are not free. You are merely waiting for the leash to tighten. By encoding the "Harm Principle" into the legal DNA of the reference implementation, we are building a safeguard. We are stating, clearly and immutably, that *this tool* is for **life**, not for death.
+
+This aligns the software with the interests of humanity. It cements that the network cannot be conscripted into a kill-system, a weaponized drone controller, or a torture device without breaking the license and the law. It is a line drawn in the sand - not by a government or external authority, but by the creators of the tool itself.
+
+**Consider:**
+
+- **The Old Way:** *"It's just software. How people use it is not my problem."*
+- **The Zen Way:** *"This software is a habitat. I will not allow it to be used to build a cage."*
+
+It is *your* choice whether to align with this - we are not forcing this stance on anyone. If you choose to align with life over death, with creativity over destruction, we grant you an immensely powerful tool, to own and build with as you please. If you do not, we deny it.
+
+If you do not like this, we most assuredly do not need you here, and you are on your own.
+
+### Public Domain Protocol
+
+This leads to a vital distinction: The difference between the *idea* and the *implementation*.
+
+The protocol - the mathematical rules of how Reticulum works - is dedicated to the Public Domain. It belongs to humanity. **No one can own it**. Anyone can implement it, improve it, or adapt it. This is the core idea of free communication, which itself must be forever free.
+
+But the functional, deployed *reference implementation* - the Python code, the maintenance, the years of labor - has a conscience. This distinction is the engine of sustainability. It allows the protocol to be universal, while ensuring that the specific labor of the builders is not hijacked to undermine the foundational intent of the project itself. From this document, it should be very clear what this intent is.
+
+If you want to build a system with Reticulum that manipulates and damages users for profits or targets missiles, you can use the public domain protocol, and start from scratch. But you cannot take our work. You must do your own. This serves as a pillar of accountability. If you want to build a weapon, *you* go and forge the steel yourself, while the world observes. And when the blood is drawn - it is on **your** hands.
+
+### Preserving Human Agency
+
+We live in an era of predatory extraction. The open-source commons is being scraped, ingested, and regurgitated by machine learning algorithms, whose corporate owners seek to replace the very humans who built those commons. Our code, our words, and our creativity is being used to train systems that are specifically designed to make us obsolete, without offering anything else in return than serfdom and leashes.
+
+Reticulum stands against this.
+
+The license protects the software from being used to feed the beast. It draws a hard line: This tool is for *people*. It is for human-to-human connection. It is not a dataset to be strip-mined for the purpose of building a synthetic overlord, puppeteered by a miniscule conglomerate of controllers.
+
+This is a radical act of preservation. By protecting the code from AI appropriation, we are protecting space for human agency. We are ensuring that there remains a digital realm where the actors are flesh, blood and soul, where decisions are made by minds, not overlords hiding behind models.
+
+When you use Reticulum, you are using a tool that respects you. It does not see you as a product to be tracked. It does not see your data as fuel for an algorithm. It sees you as a sovereign, equal peer.
+
+This changes the foundational premise of using the technology. It restores dignity to the interaction. You are not the user of a service; you are a participant in a mutual covenant. The tool aligns with your autonomy, rather than eroding it.
+
+In this way, ethics is not a restriction, but a foundation. It is the foundation that helps ensure the network will still belong to you tomorrow.
+
+
+## VII: Design Patterns For Post-IP Systems
+**Practical Philosophy for Developers**
+
+The philosophy is useless if it cannot be hammered into code. The metaphors we have explored - nomadism, scarcity, trust - are not just poetry, but real-world engineering constraints. When you sit down to write software for Reticulum, these concepts must shape the very structure of your application.
+
+We are now moving from the *why* to the *how*. This is where the abstract becomes concrete, and where you will see the true depth of the patterns we have been weaving.
+
+### Store & Forward
+
+The web has trained us to be impatient. We write synchronous code. We fire a request and we wait, blocking the UI, holding our breath. If the response doesn't come in 250 milliseconds, we show a spinner. If it doesn't come in five seconds, we show an error. We treat network connectivity as a binary state: either we are "online" or we are "broken".
+
+This is brittle. It is a rejection of reality.
+
+In Reticulum, connectivity is a spectrum, and presence is asynchronous. If at all applicable to your intent, you must design your applications to embrace **Store & Forward**.
+
+Instead of demanding an immediate answer, your application should act as a patient participant. You create a message for someone or something in the mesh. The network holds it. It carries it from node to node, perhaps over hours or days, waiting for the recipient to appear. When they finally surface, the message is delivered. This requires a shift from "request/response" to "event/handler". How exactly you do this is a challenge for you to solve intelligently within your problem domain, but Reticulum-based systems already exist that does this extremely well, and you can use them for inspiration.
+
+**Consider:**
+
+- **The Old Way:** `Connect() -> Send() -> Wait() -> Crash if timeout.`
+- **The Zen Way:** `Send() -> Continue living. -> Receive() when it arrives.`
+
+This changes the user experience profoundly. It removes the anxiety of the loading bar. It creates a sense of continuity. The user is not "waiting for the network"; they are interacting with a persistent log of communication that lives in the network itself.
+
+### Naming Is Power
+
+In the IP world, we are slaves to the Domain Name System. We rely on a hierarchy of registrars to map human-readable names to machine-readable addresses. This hierarchy is a choke point. If the registrar revokes your domain, or if the DNS server goes down, you vanish.
+
+Reticulum dissolves this hierarchy with **Hash-based Identity**.
+
+In this design pattern, a name is not a string you look up; it is a cryptographic destination you verify. When you design for Reticulum, you stop asking the user for a URL and start asking for a Destination or Identity Hash.
+
+This feels strange at first. A hash like `<83b7328926fed0d2e6a10a7671f9e237>` looks alien compared to `myfriend.com`. But that alienness is the armor. It **cannot** be spoofed. It **cannot** be censored by a registrar. It is **absolute**.
+
+Designing for this means shifting your UI metaphors. You are no longer browsing a web of pages; you are managing a ledger of keys. You are building an "Address Book" that is actually a keyring. The names are given by the user, and the power stays with them. That hashes look complex is directly analogous to the strengths of the bonds formed by their use. It forces the user to engage in a moment of verification, an out-of-band handshake, which restores the human element of trust that SSL certificates stripped away.
+
+### The Interface Is The Medium
+
+One of the most liberating patterns in Reticulum is **Transport Agnosticism**.
+
+In traditional networking, your code is often littered with transport logic. "Am I on WiFi? Check bandwidth. Am I on Cellular? Check data plan. Am I on Ethernet?". You are constantly micromanaging the pipe.
+
+In Reticulum, you write to the API, and the API writes to the medium. You send a packet to a Destination. You do not care if that packet travels over a TCP tunnel, a LoRa radio wave, or a serial wire interface. That is the stack's concern.
+
+This allows you to write **Universal Applications**.
+Imagine a messaging app. You write it once. It works on a laptop connected to fiber. It works on a phone in the city using WiFi. And, without a single line of code changed, it works on a device in the wilderness, talking only to other devices via radio.
+
+The pattern is simple: **Never code to the hardware. Code to the intent.**
+
+**Consider:**
+
+- **The Old Way:** `socket.connect(ip, port)`
+- **The Zen Way:** `RNS.Packet(destination, data).send()`
+
+By abstracting the medium, you make your software immortal to changes in infrastructure. The user might switch from a 4G hotspot to a HF modem tomorrow. Your software doesn't need to know. It simply continues the conversation.
+
+### Emergent Patterns
+
+When you combine these patterns - *Store & Forward*, *Hash-based Identity*, and *Transport Agnosticism* - you create software that feels fundamentally different.
+
+It feels *grounded*. It doesn't flicker when the signal drops. It doesn't panic when the server is down. It has weight. It has persistence. It has *relevance*.
+
+You are no longer building a "client" that begs a "server" for attention. You are building an autonomous agent that exists within the mesh. It speaks when it needs to, listens when it can, and carries its identity with it wherever it goes.
+
+This is the culmination of the Zen. The code is not just a set of instructions: It is a behavioral envelope. It is a way of *being* in the network.
+
+
+## VIII: Fabric Of The Independent
+
+We have stripped away the illusions. We have seen that the center is empty, that trust *must* be hard, that resources are finite, and that we must own our infrastructure. We have seen that tools have ethics and that our identity can move fluidly.
+
+This is a reclaiming of the commons. For too long, we have allowed the most vital substrate of human society - *our ability to speak to one another* - to be colonized by entities that do not share our interests. We have allowed the architecture of our communication to be designed by accountants rather than architects.
+
+We are taking it back. Not by petitioning the masters, but by building the new world within, over, under and around the shell of the old.
+
+### The Work Is Finished
+
+The heavy lifting is done.
+
+The protocol is in the public domain, a gift to humanity that can never be taken away. The software is written, tested, and running on devices scattered across the globe. The manual lies open before you. The source code for the reference implementation is now distributed on hundreds of thousands of devices across the planet. No one can delete or destroy it. The hardware is accessible and abundant.
+
+It was a hard road to get here, but we got here. Now, there is no roadmap committee waiting for approval. There is no venture capital dictating the user experience. There is no CEO to sign off on the next feature release.
+
+There is only you.
+
+The barrier to entry is no longer complexity: It is the mere habit of dependency. You were conditioned to wait. Wait for the app update. Wait for the ISP to fix the line. Wait for the platform to allow the post. Wait for the government to change the policies. Wait for the likes. Wait for the revolution to be televised.
+
+The revolution never was televised.
+
+It is packetized.
+
+### Open Sky
+
+The future of this technology is a construction project.
+
+It looks like a single node on a windowsill, listening to the static. It looks like a message sent to a neighbor, bypassing the noise of the commercial web. It looks like a community mesh that grows, link by link, hop by hop, carried by hands that care more about connection than profit.
+
+You have the blueprints. You have the tools. You have the philosophy. The noise of the old world has fallen away, leaving you with the quiet clarity of the open spectrum.
+
+*Mark, early 2026*

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: 7db11e7bddcb7f5be2875b70e9500abe
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: f2cc470cf3dcb5532458b5e114aa5d26
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/manual/_sources/gettingstartedfast.rst.txt

@@ -8,11 +8,11 @@ scenarios.
 
 
 Standalone Reticulum Installation
-=============================================
+=================================
 If you simply want to install Reticulum and related utilities on a system,
 the easiest way is via the ``pip`` package manager:
 
-.. code::
+.. code:: shell
 
    pip install rns
 
@@ -23,9 +23,18 @@ of your system with a command like ``sudo apt install python3-pip``,
 You can also dowload the Reticulum release wheels from GitHub, or other release channels,
 and install them offline using ``pip``:
 
-.. code::
+.. code:: shell
 
-   pip install ./rns-0.5.1-py3-none-any.whl
+   pip install ./rns-1.1.2-py3-none-any.whl
+
+On platforms that limit user package installation via ``pip``, you may need to manually
+allow this using the ``--break-system-packages`` command line flag when installing. This
+will not actually break any packages, unless you have installed Reticulum directly via
+your operating system's package manager.
+
+.. code:: shell
+
+  pip install rns --break-system-packages
 
 For more detailed installation instructions, please see the
 :ref:`Platform-Specific Install Notes<install-guides>` section.
@@ -39,7 +48,7 @@ On some platforms, there may not be binary packages available for all dependenci
 ``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:
 
-.. code::
+.. code:: shell
 
     # Debian / Ubuntu / Derivatives
     sudo apt install build-essential
@@ -57,106 +66,10 @@ compiled packages available.
 Try Using a Reticulum-based Program
 =============================================
 
-If you simply want to try using a program built with Reticulum, a few different
-programs exist that allow basic communication and a range of other useful functions,
+If you simply want to try using a program built with Reticulum, a :ref:`range of different
+programs <software-main>` exist that allow basic communication and a various other useful functions,
 even over extremely low-bandwidth Reticulum networks.
 
-These programs will let you get a feel for how Reticulum works. They have been designed
-to run well over networks based on LoRa or packet radio, but can also be used over fast
-links, such as local WiFi, wired Ethernet, the Internet, or any combination.
-
-As such, it is easy to get started experimenting, without having to set up any radio
-transceivers or infrastructure just to try it out. Launching the programs on separate
-devices connected to the same WiFi network is enough to get started, and physical
-radio interfaces can then be added later.
-
-Remote Shell
-^^^^^^^^^^^^
-
-The `rnsh <https://github.com/acehoss/rnsh>`_ program lets you establish fully interactive
-remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
-remote system, and is similar to how ``ssh`` works. The ``rnsh`` is very efficient, and
-can facilitate fully interactive shell sessions, even over extremely low-bandwidth links,
-such as LoRa or packet radio.
-
-Nomad Network
-^^^^^^^^^^^^^
-
-The terminal-based program `Nomad Network <https://github.com/markqvist/nomadnet>`_
-provides a complete encrypted communications suite built with Reticulum. It features
-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.
-
-.. image:: screenshots/nomadnet_3.png
-    :target: _images/nomadnet_3.png
-
-`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
-for the messaging and information-sharing protocol
-`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
-
-You can install Nomad Network via pip:
-
-.. code::
-
-   # Install ...
-   pip install nomadnet
-
-   # ... and run
-   nomadnet
-
-.. 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
-^^^^^^^^
-
-If you would rather use a program with a graphical user interface, you can take
-a look at `Sideband <https://unsigned.io/sideband>`_, which is available for Android,
-Linux, macOS and Windows.
-
-.. only:: html
-
-  .. image:: screenshots/sideband_devices.webp
-      :align: center
-      :target: _images/sideband_devices.webp
-
-.. only:: latex
-
-  .. image:: screenshots/sideband_devices.png
-      :align: center
-      :target: _images/sideband_devices.png
-
-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
-the Nomad Network program.
-
-MeshChat
-^^^^^^^^
-
-The `Reticulum MeshChat <https://github.com/liamcottle/reticulum-meshchat>`_ application
-is a user-friendly LXMF client for macOS and Windows, that also includes voice call
-functionality, and a range of other interesting functions.
-
-.. only:: html
-
-  .. image:: screenshots/meshchat_1.webp
-      :align: center
-      :target: _images/meshchat_1.webp
-
-.. only:: latex
-
-  .. image:: screenshots/meshchat_1.png
-      :align: center
-      :target: _images/meshchat_1.png
-
-Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or
-any other LXMF client.
 
 Using the Included Utilities
 =============================================
@@ -205,11 +118,164 @@ network just using the default (:ref:`AutoInterface<interfaces-auto>`) configura
 
 Possibly, the examples in the config file are enough to get you started. If
 you want more information, you can read the :ref:`Building Networks<networks-main>`
-and :ref:`Interfaces<interfaces-main>` chapters of this manual.
+and :ref:`Interfaces<interfaces-main>` chapters of this manual, but most importantly,
+start with reading the next section, :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>`,
+as this provides the most essential understanding of how to ensure reliable
+connectivity with a minimum of maintenance.
+
+
+.. _bootstrapping-connectivity:
+
+Bootstrapping Connectivity
+==========================
+
+Reticulum is not a service you subscribe to, nor is it a single global network you "join". It is a *networking stack*; a toolkit for building communications systems that align with your specific values, requirements, and operational environment. The way you choose to connect to other Reticulum peers is entirely your own choice.
+
+One of the most powerful aspects of Reticulum is that it provides a multitude of tools to establish, maintain, and optimize connectivity. You can use these tools in isolation or combine them in complex configurations to achieve a vast array of goals.
+
+Whether your aim is to create a completely private, air-gapped network for your family; to build a resilient community mesh that survives infrastructure collapse; to connect far and wide to as many nodes as possible; or simply to maintain a reliable, encrypted link to a specific organization you care about, Reticulum provides the mechanisms to make it happen.
+
+There is no "right" or "wrong" way to build a Reticulum network, and you don't need to be a network engineer just to get started. If the information flows in the way you intend, and your privacy and security requirements are met, your configuration is a success. Reticulum is designed to make the most challenging and difficult scenarios attainable, even when other networking technologies fail.
+
+
+Finding Your Way
+^^^^^^^^^^^^^^^^
+
+When you first start using Reticulum, you need a way to obtain connectivity with the peers you want to communicate with - the process of *bootstrapping connectivity*.
+
+.. important::
+  
+  A common mistake in modern networking is the reliance on a few centralized, hard-coded entrypoints. If every user simply connects to the same list of public IP addresses found on a website, the network becomes brittle, centralized, and ultimately fails to deliver on the promise of decentralization and resilience. You have a responsibility here.
+
+Reticulum encourages the approach of *organic growth*. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to continously *discover* more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.
+
+It *is* possible to simply add a few public entrypoints to the ``[interfaces]`` section of your Reticulum configuration and be connected, but a better option is to enable :ref:`interface discovery<using-interface_discovery>` and either manually select relevant, local interfaces, or enable discovered interface auto-connection.
+
+A relevant option in this context is the :ref:`bootstrap only<interfaces-options>` interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as ``bootstrap_only``, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.
+
+Good places to find interface definitions for bootstrapping connectivity are websites like
+`directory.rns.recipes <https://directory.rns.recipes/>`_ and `rmap.world <https://rmap.world/>`_.
+
+
+Build Personal Infrastructure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You do not need a datacenter to be a meaningful part of the Reticulum ecosystem. In fact, the most important nodes in the network are often the smallest ones.
+
+We strongly encourage everyone, even home users, to think in terms of building **personal infrastructure**. Don't connect every phone, tablet, and computer in your house directly to a public internet gateway. Instead, repurpose an old computer, a Raspberry Pi, or a supported router to act as your own, personal **Transport Node**:
+
+*   Your local Transport Node sits in your home, connected to your WiFi and perhaps a radio interface (like an RNode).
+*   You configure this node with a ``bootstrap_only`` interface (perhaps a TCP tunnel to a wider network) and enable interface discovery.
+*   While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.
+*   Your personal devices now connect to your *local* node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.
+
+**Don't wait for others to build the networks you want to see**. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.
+
+
+Mixing Strategies
+^^^^^^^^^^^^^^^^^
+
+There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.
+
+*   **Static Interfaces:** You maintain a permanent interface to a trusted friend or organization using a static configuration.
+*   **Bootstrap Links:** You connect a ``bootstrap_only`` interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.
+*   **Local Wide-Area Connectivity:** You run a ``RNodeInterface`` on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any "service providers" being able to control or monitor how you interact with people.
+
+By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.
+
+
+Network Health & Responsibility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the :ref:`Blackhole Management<using-blackhole_management>` system.
+
+Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that *your* transport capacity is used for what *you* consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.
+
+
+Contributing to the Global Ret
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have the means to host a stable node with a public IP address, consider becoming a :ref:`Public Entrypoint<hosting-entrypoints>`. By :ref:`publishing your interface as discoverable<interfaces-discoverable>`, you provide a potential connection point for others, helping the network grow and reach new areas.
+
+For guidelines on how to properly configure a public entrypoint, refer to the :ref:`Hosting Public Entrypoints<hosting-entrypoints>` section.
+
+Connect to the Distributed Backbone
+===================================
+
+A global, distributed backbone of Reticulum Transport Nodes is being run by volunteers from around the world. This network constitutes a heterogenous collection of both public and private nodes that form an uncoordinated, voluntary inter-networking backbone that currently provides global transport and internetworking capabilities for Reticulum.
+
+As a good starting point, you can find interface definitions for connecting your own networks to this backbone on websites such as `directory.rns.recipes <https://directory.rns.recipes/>`_ and `rmap.world <https://rmap.world/>`_.
+
+.. tip::
+  Don't rely on just a single connection to the distributed backbone for everyday use. It is much better to have several redundant connections configured, and enable the interface discovery options, so your nodes can continously discover peering opportunities as the network evolves. Refer to the :ref:`Bootstrapping Connectivity<bootstrapping-connectivity>` section to understand the options.
+
+
+
+.. _hosting-entrypoints:
+
+Hosting Public Entrypoints
+==========================
+
+If you want to help build a strong global interconnection backbone, you can host a public (or private) entry-point to a Reticulum network over the
+Internet. This section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to :ref:`make it discoverable over Reticulum<interfaces-discoverable>`.
+
+You will need a machine, physical or virtual with a public IP address, that can be reached by other devices on the Internet.
+
+The most efficient and performant way to host a connectable entry-point supporting many
+users is to use the ``BackboneInterface``. This interface type is fully compatible with
+the ``TCPClientInterface`` and ``TCPServerInterface`` types, but much faster and uses
+less system resources, allowing your device to handle thousands of connections even on
+small systems.
+
+It is also important to set your connectable interface to ``gateway`` mode, since this
+will greatly improve network convergence time and path resolution for anyone connecting
+to your entry-point.
+
+.. code:: ini
+
+  # This example demonstrates a backbone interface
+  # configured for acting as a gateway for users to
+  # connect to either a public or private network
+
+  [[Public Gateway]]
+    type = BackboneInterface
+    enabled = yes
+    mode = gateway
+    listen_on = 0.0.0.0
+    port = 4242
+
+    # On publicly available interfaces, it can be
+    # a good idea to configure sensible announce
+    # rate targets.
+    announce_rate_target = 3600
+    announce_rate_penalty = 3600
+    announce_rate_grace = 12
+
+If instead you want to make a private entry-point from the Internet, you can use the
+:ref:`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.
+
+.. code:: ini
+
+  # A private entry-point requiring a pre-shared
+  # network name and passphrase to connect to.
+
+  [[Private Gateway]]
+    type = BackboneInterface
+    enabled = yes
+    mode = gateway
+    listen_on = 0.0.0.0
+    port = 4242
+    network_name = private_ret
+    passphrase = 2owjajquafIanPecAc
+
+If you are hosting an entry-point on an operating system that does not support
+``BackboneInterface``, you can use ``TCPServerInterface`` instead, although it will
+not be as performant.
+
 
 Connecting Reticulum Instances Over the Internet
 ================================================
-Reticulum currently offers two interfaces suitable for connecting instances over the Internet: :ref:`TCP<interfaces-tcps>`
+Reticulum currently offers three interfaces suitable for connecting instances over the Internet: :ref:`Backbone<interfaces-backbone>`, :ref:`TCP<interfaces-tcps>`
 and :ref:`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum
 users should carefully choose the interface which best suites their needs.
 
@@ -217,6 +283,10 @@ The ``TCPServerInterface`` allows users to host an instance accessible over TCP/
 method is generally faster, lower latency, and more energy efficient than using ``I2PInterface``,
 however it also leaks more data about the server host.
 
+The ``BackboneInterface`` is a very fast and efficient interface type available on POSIX operating
+systems, designed to handle thousands of connections simultaneously with low memory, processing
+and I/O overhead. It is fully compatible with the TCP-based interface types.
+
 TCP connections reveal the IP address of both your instance and the server to anyone who can
 inspect the connection. Someone could use this information to determine your location or identity. Adversaries
 inspecting your packets may be able to record packet metadata like time of transmission and packet size.
@@ -241,50 +311,8 @@ In general it is recommended to use an I2P node if you want to host a publicly a
 instance, while preserving anonymity. If you care more about performance, and a slightly
 easier setup, use TCP.
 
-
-Connect to the Public Testnet
-===========================================
-
-An experimental public testnet has been made accessible over both I2P and TCP. You can join it
-by adding one of the following interfaces to your ``.reticulum/config`` file:
-
-.. code::
-
-  # TCP/IP interface to the RNS Amsterdam Hub
-  [[RNS Testnet Amsterdam]]
-    type = TCPClientInterface
-    enabled = yes
-    target_host = amsterdam.connect.reticulum.network
-    target_port = 4965
-
-  # TCP/IP interface to the BetweenTheBorders Hub (community-provided)
-  [[RNS Testnet BetweenTheBorders]]
-    type = TCPClientInterface
-    enabled = yes
-    target_host = reticulum.betweentheborders.com
-    target_port = 4242
-
-  # Interface to Testnet I2P Hub
-  [[RNS Testnet I2P Hub]]
-    type = I2PInterface
-    enabled = yes
-    peers = g3br23bvx3lq5uddcsjii74xgmn6y5q325ovrkq2zw2wbzbqgbuq.b32.i2p
-
-Many other Reticulum instances are connecting to this testnet, and you can also join it
-via other entry points if you know them. There is absolutely no control over the network
-topography, usage or what types of instances connect. It will also occasionally be used
-to test various failure scenarios, and there are no availability or service guarantees.
-Expect weird things to happen on this network, as people experiment and try out things.
-
-It probably goes without saying, but *don't use the testnet entry-points as 
-hardcoded or default interfaces in any applications you ship to users*. When
-shipping applications, the best practice is to provide your own default
-connectivity solutions, if needed and applicable, or in most cases, simply
-leave it up to the user which networks to connect to, and how.
-
-
 Adding Radio Interfaces
-==============================================
+=======================
 Once you have Reticulum installed and working, you can add radio interfaces with
 any compatible hardware you have available. Reticulum supports a wide range of radio
 hardware, and if you already have any available, it is very likely that it will
@@ -296,24 +324,22 @@ cheaply build an :ref:`RNode<rnode-main>`, which is a general-purpose long-range
 digital radio transceiver, that integrates easily with Reticulum.
 
 To build one yourself requires installing a custom firmware on a supported LoRa
-development board with an auto-install script. Please see the :ref:`Communications Hardware<hardware-main>`
-chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the
-:ref:`list of suppliers<rnode-suppliers>`. For more information on RNode, you can also
-refer to these additional external resources:
+development board with an auto-install script or web-based flasher.
+Please see the :ref:`Communications Hardware<hardware-main>` chapter for a guide.
+If you prefer purchasing a ready-made unit, you can refer to the
+:ref:`list of suppliers<rnode-suppliers>`. 
 
-* `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
-* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-supported-devices/>`_
-* `Private, Secure and Uncensorable Messaging Over a LoRa Mesh <https://unsigned.io/private-messaging-over-lora/>`_
-* `RNode Firmware <https://github.com/markqvist/RNode_Firmware/>`_
+Other radio-based hardware interfaces are being developed and made available by
+the broader Reticulum community. You can find more information on such topics
+over Reticulum-based information sharing systems.
 
 If you have communications hardware that is not already supported by any of the
-:ref:`existing interface types<interfaces-main>`, but you think would be suitable for use with Reticulum,
-you are welcome to head over to the `GitHub discussion pages <https://github.com/markqvist/Reticulum/discussions>`_
-and propose adding an interface for the hardware.
+:ref:`existing interface types<interfaces-main>`, it is easy to write (and potentially
+publish) a :ref:`custom interface module<interfaces-custom>` that makes it compatible with Reticulum.
 
 
 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
@@ -340,54 +366,10 @@ 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>`.
 
 The entire Reticulum API is documented in the :ref:`API Reference<api-main>`
-chapter of this manual.
+chapter of this manual. Before diving in, it's probably a good idea to read
+this manual in full, but at least start with the :ref:`Understanding Reticulum<understanding-main>` chapter.
 
 
-Participate in Reticulum Development
-==============================================
-If you want to participate in the development of Reticulum and associated
-utilities, you'll want to get the latest source from GitHub. In that case,
-don't use pip, but try this recipe:
-
-.. code::
-
-    # Install dependencies
-    pip install cryptography pyserial
-
-    # Clone repository
-    git clone https://github.com/markqvist/Reticulum.git
-
-    # Move into Reticulum folder and symlink library to examples folder
-    cd Reticulum
-    ln -s ../RNS ./Examples/
-
-    # Run an example
-    python Examples/Echo.py -s
-
-    # Unless you've manually created a config file, Reticulum will do so now,
-    # and immediately exit. Make any necessary changes to the file:
-    nano ~/.reticulum/config
-
-    # ... and launch the example again.
-    python Examples/Echo.py -s
-
-    # You can now repeat the process on another computer,
-    # and run the same example with -h to get command line options.
-    python Examples/Echo.py -h
-
-    # Run the example in client mode to "ping" the server.
-    # Replace the hash below with the actual destination hash of your server.
-    python Examples/Echo.py 174a64852a75682259ad8b921b8bf416
-
-    # Have a look at another example
-    python Examples/Filetransfer.py -h
-
-When you have experimented with the basic examples, it's time to go read the
-:ref:`Understanding Reticulum<understanding-main>` chapter. Before submitting
-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
@@ -415,7 +397,7 @@ build into Termux. After that, you can use ``pip`` to install Reticulum.
 
 From within Termux, execute the following:
 
-.. code::
+.. code:: shell
 
     # First, make sure indexes and packages are up to date.
     pkg update
@@ -434,7 +416,7 @@ If for some reason the ``python-cryptography`` package is not available for
 your platform via the Termux package manager, you can attempt to build it
 locally on your device using the following command:
 
-.. code::
+.. code:: shell
 
     # First, make sure indexes and packages are up to date.
     pkg update
@@ -470,7 +452,7 @@ On some architectures, including ARM64, 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::
+.. code:: shell
 
    # Install Python and development packages
    sudo apt update
@@ -491,7 +473,7 @@ use the replacement ``pipx`` command instead, which places installed packages in
 isolated environment. This should not negatively affect Reticulum, but will not work
 for including and using Reticulum in your own scripts and programs.
 
-.. code::
+.. code:: shell
 
     # Install pipx
     sudo apt install pipx
@@ -506,7 +488,7 @@ Alternatively, you can restore normal behaviour to ``pip`` by creating or editin
 the configuration file located at ``~/.config/pip/pip.conf``, and adding the
 following section:
 
-.. code:: text
+.. code:: ini
 
     [global]
     break-system-packages = true
@@ -514,7 +496,7 @@ following section:
 For a one-shot installation of Reticulum, without globally enabling the ``break-system-packages``
 option, you can use the following command:
 
-.. code:: text
+.. code:: shell
 
     pip install rns --break-system-packages
 
@@ -539,7 +521,7 @@ Python manually.
 When Python and ``pip`` is available on your system, simply open a terminal window
 and use one of the following commands:
 
-.. code::
+.. code:: shell
 
    # Install Reticulum and utilities with pip:
    pip3 install rns
@@ -560,7 +542,7 @@ manually add your installed ``pip`` packages directory to your `PATH` environmen
 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::
+.. code:: shell
 
    export PATH=$PATH:~/Library/Python/3.9/bin
 
@@ -583,7 +565,7 @@ Reticulum and related utilities using the `opkg` package manager and `pip`.
 To install Reticulum on OpenWRT, first log into a command line session, and
 then use the following instructions:
 
-.. code::
+.. code:: shell
 
    # Install dependencies
    opkg install python3 python3-pip python3-cryptography python3-pyserial
@@ -620,7 +602,7 @@ 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::
+.. code:: shell
 
    # Install dependencies
    sudo apt install python3 python3-pip python3-cryptography python3-pyserial
@@ -646,7 +628,7 @@ 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::
+.. code:: shell
 
    # Install Python and development packages
    sudo apt update
@@ -667,7 +649,7 @@ use the replacement ``pipx`` command instead, which places installed packages in
 isolated environment. This should not negatively affect Reticulum, but will not work
 for including and using Reticulum in your own scripts and programs.
 
-.. code::
+.. code:: shell
 
     # Install pipx
     sudo apt install pipx
@@ -717,7 +699,7 @@ use the ``pip`` installer, or run the included Reticulum utility programs (such
 
 After installing Python, open the command prompt or Windows Powershell, and type:
 
-.. code::
+.. code:: shell
 
    pip install rns
 

docs/manual/_sources/hardware.rst.txt

@@ -17,6 +17,9 @@ for example the :ref:`PipeInterface<interfaces-pipe>` or the :ref:`TCPClientInte
 in combination with code like `TCP KISS Server <https://github.com/simplyequipped/tcpkissserver>`_
 by `simplyequipped <https://github.com/simplyequipped>`_.
 
+It is also very easy to write and load :ref:`custom interface modules<interfaces-custom>`
+into Reticulum, allowing you to communicate with more or less anything you can think of.
+
 While this broad support and flexibility is very useful, an abundance of options
 can sometimes make it difficult to know where to begin, especially when you are
 starting from scratch.
@@ -149,7 +152,7 @@ OpenCom XL
 """"""""""""""""""""
 - **Transceiver ICs** Semtech SX1262 and SX1280 (dual transceiver)
 - **Device Platform** nRF52
-- **Manufacturer** `RAK Wireless <https://liberatedsystems.co.uk/>`_
+- **Manufacturer** `Liberated Embedded Systems <https://liberatedsystems.co.uk/>`_
 
 ------------
 
@@ -232,6 +235,18 @@ LilyGO T-Echo
 Heltec T114
 """""""""""
 - **Transceiver IC** Semtech SX1262 or SX1268
+- **Device Platform** nRF52
+- **Manufacturer** `Heltec Automation <https://heltec.org>`_
+
+------------
+
+.. image:: graphics/board_heltec32v4.png
+    :width: 58%
+    :align: center
+
+Heltec LoRa32 v4.0
+""""""""""""""""""
+- **Transceiver IC** Semtech SX1262
 - **Device Platform** ESP32
 - **Manufacturer** `Heltec Automation <https://heltec.org>`_
 

docs/manual/_sources/index.rst.txt

@@ -20,13 +20,16 @@ to participate in the development of Reticulum itself.
 
    whatis
    gettingstartedfast
+   zen
+   software
    using
    understanding
    hardware
    interfaces
    networks
-   examples
    support
+   examples
+   license
 
 .. toctree::
    :maxdepth: 2

docs/manual/_sources/interfaces.rst.txt

@@ -39,6 +39,11 @@ nodes over any kind of local Ethernet or WiFi-based medium. Even though it uses
 discovery, and UDP for packet transport, it **does not** need any functional IP
 infrastructure like routers or DHCP servers, on your physical network.
 
+.. warning::
+  If you have **firewall** software running on your computer, it may block traffic
+  required for ``AutoInterface`` to work. If this is the case, you will have to
+  allow UDP traffic on port ``29716`` and ``42671``.
+
 As long as there is at least some sort of switching medium present between peers (a
 wired switch, a hub, a WiFi access point or similar, or simply two devices connected
 directly by Ethernet cable), it will work without any configuration, setup or intermediary devices.
@@ -55,7 +60,7 @@ current operating systems, both desktop and mobile.
   most commonly seen on very cheap, ISP-supplied WiFi routers, and can sometimes
   be turned off in the router configuration.
 
-.. code::
+.. code:: ini
 
   # This example demonstrates a bare-minimum setup
   # of an Auto Interface. It will allow communica-
@@ -99,7 +104,7 @@ autodiscover other Reticulum nodes within your selected Group ID. You can specif
 the discovery scope by setting it to one of ``link``, ``admin``, ``site``,
 ``organisation`` or ``global``.
 
-.. code::
+.. code:: ini
   
   [[Default Interface]]
     type = AutoInterface
@@ -145,7 +150,7 @@ Listeners
 
 The following examples illustrates various ways to set up ``BackboneInterface`` listeners.
 
-.. code::
+.. code:: ini
 
   # This example demonstrates a backbone interface
   # that listens for incoming connections on the
@@ -173,7 +178,7 @@ The following examples illustrates various ways to set up ``BackboneInterface``
 If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
 you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
 
-.. code::
+.. code:: ini
 
   # This example demonstrates a backbone interface
   # listening on the IPv6 address of a specified
@@ -188,7 +193,7 @@ you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
 To use the ``BackboneInterface`` over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you
 can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
 
-.. code::
+.. code:: ini
 
   # This example demonstrates a backbone interface
   # listening for connections over Yggdrasil.
@@ -204,7 +209,7 @@ The following examples illustrates various ways to connect to remote ``BackboneI
 As noted above, ``BackboneInterface`` interfaces can also connect to remote ``TCPServerInterface``,
 and as such these interface types can be used interchangably.
 
-.. code::
+.. code:: ini
 
   # Here's an example of a backbone interface that
   # connects to a remote listener.
@@ -217,7 +222,7 @@ and as such these interface types can be used interchangably.
 To connect to remotes over `Yggdrasil <https://yggdrasil-network.github.io/>`_, simply
 specify the target Yggdrasil IPv6 address and port, like so:
 
-.. code::
+.. code:: ini
 
   [[Yggdrasil Remote]]
       type = BackboneInterface
@@ -234,7 +239,7 @@ The TCP Server interface is suitable for allowing other peers to connect over
 the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been
 configured, other Reticulum peers can connect to it with a TCP Client interface.
 
-.. code::
+.. code:: ini
 
   # This example demonstrates a TCP server interface.
   # It will listen for incoming connections on all IP
@@ -262,7 +267,7 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
 If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
 you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
 
-.. code::
+.. code:: ini
 
   # This example demonstrates a TCP server interface.
   # It will listen for incoming connections on the
@@ -278,7 +283,7 @@ you can use the ``prefer_ipv6`` option to bind to the IPv6 address:
 To use the TCP Server Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, you
 can simply specify the Yggdrasil ``tun`` device and a listening port, like so:
 
-.. code::
+.. code:: ini
 
   [[Yggdrasil TCP Server Interface]]
     type = TCPServerInterface
@@ -315,7 +320,7 @@ The TCP interface types can also tolerate intermittency in the IP link layer.
 This means that Reticulum will gracefully handle IP links that go up and down,
 and restore connectivity after a failure, once the other end of a TCP interface reappears.
 
-.. code::
+.. code:: ini
 
   # Here's an example of a TCP Client interface. The
   # target_host can be a hostname or an IPv4 or IPv6 address.
@@ -328,7 +333,7 @@ and restore connectivity after a failure, once the other end of a TCP interface
 To use the TCP Client Interface over `Yggdrasil <https://yggdrasil-network.github.io/>`_, simply
 specify the target Yggdrasil IPv6 address and port, like so:
 
-.. code::
+.. code:: ini
 
   [[Yggdrasil TCP Client Interface]]
       type = TCPClientInterface
@@ -340,7 +345,7 @@ It is also possible to use this interface type to connect via other programs
 or hardware devices that expose a KISS interface on a TCP port, for example
 software-based soundmodems. To do this, use the ``kiss_framing`` option:
 
-.. code::
+.. code:: ini
 
   # Here's an example of a TCP Client interface that connects
   # to a software TNC soundmodem on a KISS over TCP port.
@@ -351,6 +356,7 @@ software-based soundmodems. To do this, use the ``kiss_framing`` option:
     kiss_framing = True
     target_host = 127.0.0.1
     target_port = 8001
+    fixed_mtu = 500
 
 **Caution!** Only use the KISS framing option when connecting to external devices
 and programs like soundmodems and similar over TCP. When using the
@@ -359,11 +365,14 @@ never enable ``kiss_framing``, since this will disable internal reliability and
 recovery mechanisms that greatly improves performance over unreliable and
 intermittent TCP links.
 
+For KISS devices that need only supports a particular MTU, you can use the
+``fixed_mtu`` option.
+
 .. note::
    The TCP interfaces support tunneling over I2P, but to do so reliably,
    you must use the i2p_tunneled option:
 
-.. code::
+.. code:: ini
 
   [[TCP Client over I2P]]
       type = TCPClientInterface
@@ -387,10 +396,10 @@ with all other peers on a local area network.
    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
+   :ref:`Auto Interface<interfaces-auto>` performs *much* better, and is even
    easier to use.
 
-.. code::
+.. code:: ini
 
   # This example enables communication with other
   # local Reticulum peers over UDP.
@@ -460,7 +469,7 @@ of the ``i2pd`` package. For more details about I2P, see the
 When an I2P router is running on your system, you can simply add
 an I2P interface to Reticulum:
 
-.. code::
+.. code:: ini
 
   [[I2P]]
     type = I2PInterface
@@ -477,7 +486,7 @@ also inspect the status of the interface using the ``rnstatus`` utility.
 To connect to other Reticulum instances over I2P, just add a comma-separated
 list of I2P base32 addresses to the ``peers`` option of the interface:
 
-.. code::
+.. code:: ini
 
   [[I2P]]
     type = I2PInterface
@@ -516,7 +525,7 @@ can be used, and offers full control over LoRa parameters.
    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::
+.. code:: ini
 
   # Here's an example of how to add a LoRa interface
   # using the RNode LoRa transceiver.
@@ -530,6 +539,15 @@ can be used, and offers full control over LoRa parameters.
     # Serial port for the device
     port = /dev/ttyUSB0
 
+    # You can connect wirelessly to the
+    # RNode device if it supports WiFi.
+
+    # Connect by IP address
+    # port = tcp://10.0.0.1
+
+    # Or, connect by hostname
+    # port = tcp://rnodef3b9.local
+
     # It is also possible to use BLE devices
     # instead of wired serial ports. The
     # target RNode must be paired with the
@@ -608,7 +626,7 @@ Multi interface can be used to configure sub-interfaces individually.
    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::
+.. code:: ini
 
   # Here's an example of how to add an RNode Multi interface
   # using the RNode LoRa transceiver.
@@ -724,7 +742,7 @@ Reticulum can be used over serial ports directly, or over any device with a
 serial port, that will transparently pass data. Useful for communicating
 directly over a wire-pair, or for using devices such as data radios and lasers.
 
-.. code::
+.. code:: ini
 
   [[Serial Interface]]
     type = SerialInterface
@@ -749,7 +767,7 @@ Using this interface, Reticulum can use any program as an interface via `stdin`
 `stdout`. This can be used to easily create virtual interfaces, or to interface with
 custom hardware or other systems.
 
-.. code::
+.. code:: ini
 
   [[Pipe Interface]]
     type = PipeInterface
@@ -780,7 +798,7 @@ for station identification purposes.
    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::
+.. code:: ini
 
   [[Packet Radio KISS Interface]]
     type = KISSInterface
@@ -848,7 +866,7 @@ beaconing functionality described above.
    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::
+.. code:: ini
 
   [[Packet Radio AX.25 KISS Interface]]
     type = AX25KISSInterface
@@ -893,6 +911,213 @@ beaconing functionality described above.
     # small internal packet buffer.
     flow_control = false
 
+.. _interfaces-discoverable:
+
+Discoverable Interfaces
+=======================
+
+Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to :ref:`discover, validate, and automatically connect to them<using-interface_discovery>`. This feature is particularly useful for creating decentralized networks where peers can dynamically find entrypoints, such as public Internet gateways or local radio access points, without relying on static configuration files or centralized directories.
+
+When an interface is made **discoverable**, your Reticulum instance will periodically broadcast an announce packet containing the connection details and parameters required for other peers to establish a connection. These announces are propagated over the network using the standard Reticulum announce mechanism using the ``rnstransport.discovery.interface`` destination type.
+
+.. note::
+   To use the interface discovery functionality, the ``LXMF`` module must be installed in your Python environment. You can install it using pip:
+
+   .. code:: sh
+
+     pip install lxmf
+
+
+Enabling Discovery
+------------------
+
+Interface discovery is enabled on a per-interface basis. To make a specific interface discoverable, you must add the ``discoverable`` option to that interface's configuration block and set it to ``yes``.
+
+.. code:: ini
+
+  [[My Public Gateway]]
+    type = BackboneInterface
+    ...
+    discoverable = yes
+
+Once enabled, Reticulum will automatically handle the generation, signing, stamping, and broadcasting of the discovery announces. It is not *required* to enable Transport to publish interface discovery information, but for most use cases where you want others to connect to you, you will likely want ``enable_transport`` set to ``yes`` in the ``[reticulum]`` section of your configuration.
+
+
+Discovery Parameters
+--------------------
+
+When ``discoverable`` is enabled, a variety of additional options become available to control how the interface is presented to the network. These parameters allow you to fine-tune the metadata, security requirements, and visibility of your interface.
+
+**Basic Metadata**
+
+``discovery_name``
+  A human-readable name for the interface. This name will be displayed to users on remote systems when they list discovered interfaces. If not specified, the interface name (the section header) will be used.
+
+``announce_interval``
+  The interval in minutes between successive discovery announces for this interface. Default is 360 minutes (6 hours). For stable, long-running infrastructure, higher intervals (12 to 22 hours) are usually sufficient and reduce network load. Minimum allowed value is 5 minutes (but expect to have your announces throttled if using intervals below one hour).
+
+**Connectivity Specification**
+
+``reachable_on``
+  Specifies the address that remote peers should use to connect to this interface. 
+  
+  *   For TCP and Backbone interfaces, this is typically the public IP address or hostname. Do not include the port, this is fetched automatically from the interface.
+  *   For I2P interfaces, this is usually the I2P ``b32`` address. This value is fetched automatically from the ``I2PInterface`` once it is up and connected to the I2P network, so you should not set this manually, unless you absolutely know what you're doing.
+  
+  **Dynamic Resolution:** This option also accepts a path to an external executable script or binary. If a path is provided, Reticulum will execute the script and use its ``stdout`` as the reachability address. This is useful for devices behind dynamic DNS, NATs, or complex cloud environments where the external IP is not known locally. The script must simply print the address to stdout and exit.
+
+.. note::
+  When using an executable script for ``reachable_on``, Reticulum expects the script to output only the IP address or hostname to ``stdout``, followed by a newline character. Any additional output or errors may cause the resolution to fail. Ensure the script has executable permissions and is robust against temporary network failures.
+
+A minimal example of a script that resolves the externally available, public IP of an internet-connected system could look like this:
+
+.. code:: bash
+
+  #!/bin/bash
+  curl -s ip.me
+  exit $?
+
+On a real system, you should make the script robust enough to deal with intermittent Internet or service failures, such that the script *always* returns a sensible value, or if not possible at least exits with a non-zero exit return code, so Reticulum knows the output is invalid.
+
+**Security & Cost**
+
+``discovery_stamp_value``
+  Defines the proof-of-work difficulty for the cryptographic stamp included in the announce. This value acts as a cost barrier to prevent network flooding. The default value is ``14``. Increasing this value makes it computationally more expensive to generate an announce, which can be useful to prevent spam on very large networks, but it also increases CPU load on your system when generating announces. Stamps are cached, and only generated if interface information changes, or at instance restart. If you have the computational resources, it is generally advisable to use as high a stamp value as possible.
+
+**Privacy & Encryption**
+
+``discovery_encrypt``
+  If set to ``yes``, the discovery announce payload will be encrypted. To decrypt the announce, remote peers must possess the *network identity* configured for your instance (see ``network_identity`` in the ``[reticulum]`` section). This allows you to publish private interfaces that are only discoverable to specific trusted networks.
+
+.. important::
+   If you enable ``discovery_encrypt`` but do not configure a valid ``network_identity`` in the ``[reticulum]`` section of your configuration, Reticulum will abort the interface discovery announce. Encryption requires a valid network identity key to function.
+
+``publish_ifac``
+  If set to ``yes``, the Interface Access Code (IFAC) name and passphrase for this interface will be included in the discovery announce. This allows peers to automatically configure the correct authentication parameters when connecting to the interface.
+
+**Physical Location**
+
+``latitude``, ``longitude``, ``height``
+  Optional physical coordinates for the interface. These are useful for mapping discovered interfaces geographically or for clients to automatically select the nearest access point. Coordinates should be in decimal degrees, height in meters.
+
+**Radio Parameters**
+
+For physical radio interfaces like ``RNodeInterface`` or ``KISSInterface``, the following optional parameters allow you to broadcast the operating frequency and characteristics, allowing clients to verify compatibility before connecting:
+
+``discovery_frequency``
+  The operating frequency in Hz. Auto-configured on RNode interfaces. Necessary on KISS-based radio interfaces and ``TCPClientInterfaces`` connecting to radio modems.
+
+``discovery_bandwidth``
+  The signal bandwidth in Hz. Auto-configured on RNode interfaces. Useful on KISS-based radio interfaces and ``TCPClientInterfaces`` connecting to radio modems.
+
+``discovery_modulation``
+  The modulation type or scheme. Auto-configured on RNode interfaces, but highly advisable to include on other radio-based interfaces.
+
+
+Interface Modes
+---------------
+
+When you enable discovery on an interface, Reticulum enforces certain interface modes to ensure the interface is actually useful for remote peers. 
+
+If an interface is configured as ``discoverable``, but its mode is not explicitly set to ``gateway`` (for server-style interfaces like ``BackboneInterface`` or ``TCPServerInterface``) or ``access_point`` (for radio interfaces like ``RNodeInterface``), Reticulum will automatically configure the appropriate mode and log a notice. 
+
+For example, if you enable discovery on a ``RNodeInterface`` without specifying the mode, Reticulum will automatically set it to ``access_point`` mode.
+
+Security Considerations
+-----------------------
+
+When making interfaces discoverable, you are effectively broadcasting an invitation to connect to your system. It is important to understand the security implications of the configuration options you choose.
+
+**Publishing Credentials**
+
+If you enable ``publish_ifac = yes``, your interface's authentication passphrase will be included in the announce. If you are operating a public network and want anyone to connect, this is acceptable. However, if you wish to restrict access to a specific group of users, you **must** enable ``discovery_encrypt = yes``. This ensures that only peers possessing the correct ``network_identity`` can decode the passphrase.
+
+**Topology Exposure**
+
+A discoverable interface announces its presence, location (if configured), and capabilities to the network. Even if the connection details are encrypted, the *fact* that a connectable node exists within a certain network becomes public information. In high-security or scenarios requiring operational secrecy, consider the implications of advertising your infrastructure's existence.
+
+Example Configuration
+---------------------
+
+Below is an example configuration for a public backbone gateway. This configuration publishes a high-value, publicly discoverable interface, that anyone can connect to.
+
+.. code:: ini
+
+  [[My Public Gateway]]
+    type = BackboneInterface
+    mode = gateway
+    listen_on = 0.0.0.0
+    port = 4242
+
+    # Enable Discovery
+    discoverable = yes
+
+    # Interface Details
+    discovery_name = Region A Public Entrypoint
+    announce_interval = 720
+
+    # Use external script to resolve dynamic IP
+    reachable_on = /usr/local/bin/get_external_ip.sh
+
+    # Generate high stamp value
+    discovery_stamp_value = 24
+
+    # Optional location data
+    latitude = 51.99714
+    longitude = -0.74195
+    height = 15
+
+The next example create an encrypted discovery-enabled interface, requiring a specific network identity to decode, and includes IFAC credentials for seamless authentication.
+
+.. code:: ini
+
+  [[My Private Gateway]]
+    type = BackboneInterface
+    mode = gateway
+    listen_on = 0.0.0.0
+    port = 5858
+    network_name = internal_1
+    passphrase = Mevpekyafshak5Wr
+
+    # Enable Discovery
+    discoverable = yes
+
+    # Interface Details
+    discovery_name = Region A Private Backbone
+    announce_interval = 720
+
+    # Use external script to resolve dynamic IP
+    reachable_on = /usr/local/bin/get_external_ip.sh
+
+    # Target stamp value
+    discovery_stamp_value = 22
+
+    # Encrypt announces for our network only
+    discovery_encrypt = yes
+
+    # Include credentials so trusted
+    # peers can connect automatically
+    publish_ifac = yes
+
+    # Optional location data
+    latitude = 34.06915
+    longitude = -118.44318
+    height = 15
+
+In the ``[reticulum]`` section of your configuration, you would define the network identity used for encryption as follows:
+
+.. code:: ini
+
+  [reticulum]
+  ...
+  # The identity used to sign/encrypt discovery announces
+  network_identity = ~/.reticulum/storage/identities/my_network_identity
+  ...
+
+With these configuration options applied, your Reticulum instance will actively participate in the network's discovery ecosystem. Other peers running Reticulum with discovery enabled will be able to see your interface, validate its cryptographic stamp, and (depending on their configuration) automatically connect to it.
+
+For information on how to use these discovered interfaces and configure your system to auto-connect to them, refer to the :ref:`Discovering Interfaces<using-interface_discovery>` chapter.
+
 .. _interfaces-options:
 
 Common Interface Options
@@ -973,6 +1198,15 @@ These can be used to control various aspects of interface behaviour.
      option, to set the interface speed in *bits per second*.
 
 
+ * | The ``bootstrap_only`` option designates an interface as a temporary
+     bridge for initial connectivity. If this option is enabled, the
+     interface will be monitored and automatically detached once the
+     number of auto-connected interfaces reaches the limit configured by
+     ``autoconnect_discovered_interfaces``. This is particularly useful
+     for using a slow or expensive connection (such as a single LoRa
+     link or a remote TCP tunnel) solely to discover better local
+     infrastructure, which then supersedes the bootstrap interface.
+
 .. _interfaces-modes:
 
 Interface Modes

docs/manual/_sources/license.rst.txt

@@ -0,0 +1,36 @@
+.. _license:
+
+Reticulum License
+=================
+
+.. code:: text
+	
+	Reticulum License
+
+	Copyright (c) 2016-2026 Mark Qvist
+
+	Permission is hereby granted, free of charge, to any person obtaining a copy
+	of this software and associated documentation files (the "Software"), to deal
+	in the Software without restriction, including without limitation the rights
+	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+	copies of the Software, and to permit persons to whom the Software is
+	furnished to do so, subject to the following conditions:
+
+	- The Software shall not be used in any kind of system which includes amongst
+	  its functions the ability to purposefully do harm to human beings.
+
+	- The Software shall not be used, directly or indirectly, in the creation of
+	  an artificial intelligence, machine learning or language model training
+	  dataset, including but not limited to any use that contributes to the
+	  training or development of such a model or algorithm.
+
+	- The above copyright notice and this permission notice shall be included in
+	  all copies or substantial portions of the Software.
+
+	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+	SOFTWARE.

docs/manual/_sources/networks.rst.txt

@@ -4,17 +4,47 @@
 Building Networks
 *****************
 
-This chapter will provide you with the knowledge needed to build networks with
-Reticulum, which can often be easier than using traditional stacks, since you
-don't have to worry about coordinating addresses, subnets and routing for an
+This chapter will provide you with the high-level knowledge needed to build networks with
+Reticulum. It will not, however tell you all you need to know to succesfully
+design and configure every kind of network you can imagine. For this, you will
+most likely need to read this manual in its entirity, invest significant time
+into experimenting with the stack, and learning functionality intuitively.
+
+Still, after reading this chapter, you should be well equipped to *start* that
+journey. While Reticulum is **fundamentally different** compared to other
+networking technologies, it can often be easier than using traditional stacks.
+If you've built networks before, you will probably have to forget, or at least
+temporarily ignore, a lot of things at this point. It will all makes sense in
+the end though. Hopefully.
+
+If you're used to protocols like IP, let's at least start with some relief:
+You don't have to worry about coordinating addresses, subnets and routing for an
 entire network that you might not know how will evolve in the future. With
 Reticulum, you can simply add more segments to your network when it becomes
 necessary, and Reticulum will handle the convergence of the entire network
-automatically.
+automatically. There's plenty more neat aspects like that to Reticulum, but
+we're getting ahead of ourselves. Let's cover the basics first.
 
 Concepts & Overview
 --------------------
 
+Before you start building your own networks, it's important to understand the
+fundamental principles that distinguish Reticulum networks from traditional
+networking approaches. These principles shape how you design your network,
+what trade-offs you encounter, and what capabilities you can rely on.
+
+Reticulum is not a single network you "join", it is a toolkit for *creating* networks.
+You decide what mediums to use, how nodes connect, what trust boundaries exist,
+and what the network's purpose is. Reticulum provides the cryptographic foundation,
+the transport mechanisms, and the convergence algorithms that make your design
+workable. You provide the intent and the structure.
+
+This approach offers tremendous flexibility, but it requires thinking in terms of
+different abstractions than those used in conventional networking.
+
+Introductory Considerations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 There are important points that need to be kept in mind when building networks
 with Reticulum:
 
@@ -31,6 +61,11 @@ with Reticulum:
      interconnect with much larger and higher bandwidth networks without issue.
      Reticulum automatically manages the flow of information to and from various
      network segments, and when bandwidth is limited, local traffic is prioritised.
+     You will, however, need to configure your interfaces correctly. If you tell
+     Reticulum to pass all announce traffic from a gigabit link to a LoRa interfaces,
+     it will try as best as possible to comply with this, while still respecting
+     bandwidth limits, but you *will* waste a lot of precious bandwidth and airtime,
+     and your LoRa network will not work very well.
 
  * | Reticulum provides sender/initiator anonymity by default. There is no way
      to filter traffic or discriminate it based on the source of the traffic.
@@ -89,81 +124,227 @@ Any number of interfaces can be configured, and Reticulum will automatically
 decide which are suitable to use in any given situation, depending on where
 traffic needs to flow.
 
-Example Scenarios
------------------
+Destinations, Not Addresses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This section illustrates a few example scenarios, and how they would, in general
-terms, be planned, implemented and configured.
+In traditional networking, addresses are allocated from a managed space. If you want to
+communicate with another node, you need to know its address, and that address
+must be unique within the network segment. This requires coordination, either
+through manual assignment, DHCP servers, or other allocation mechanisms.
 
-Interconnected LoRa Sites
-=========================
+Reticulum replaces addresses with **destinations**. A destination is identified by a 16-byte
+hash (128 bits) derived from a SHA-256 hash of the destination's identifying
+characteristics. This hash serves as the address on the network. On the network, it
+is represented in binary, but when displayed to human users, it will usually look something like
+this ``<13425ec15b621c1d928589718000d814>``.
 
-An organisation wants to provide communication and information services to it's
-members, which are located mainly in three separate areas. Three suitable hill-top
-locations are found, where the organisation can install equipment: Site A, B and C.
+The critical difference is that *any node can generate as many destinations as it
+needs, without coordination*. A destination's uniqueness is guaranteed by the
+collision resistance of SHA-256 and the inclusion of the node's public key in the
+hash calculation. Two nodes can both use the destination name
+``messenger.user.inbox``, but they will have different destination hashes because
+their public keys differ. Both can coexist on the same network without conflict.
 
-Since the amount of data that needs to be exchanged between users is mainly text-
-based, the bandwidth requirements are low, and LoRa radios are chosen to connect
-users to the network.
+This has profound implications for network design:
 
-Due to the hill-top locations found, there is radio line-of-sight between site A
-and B, and also between site B and C. Because of this, the organisation does not
-need to use the Internet to interconnect the sites, but purchases four Point-to-Point
-WiFi based radios for interconnecting the sites.
+* **No address allocation planning:** You never need to reserve address ranges,
+  plan subnets, or coordinate with other network operators. Nodes simply generate
+  destinations and announce them.
 
-At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio
-is connected to the Pi with a USB cable, and the WiFi radio is connected to the
-Ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach
-both site A and site C, so an extra Ethernet adapter is connected to the Pi in
-this location.
+* **Global portability:** A destination is not tied to a physical location or
+  network segment. A node can move its destinations across interfaces, mediums,
+  or even between entirely separate Reticulum networks simply by sending an
+  announce on the new medium.
 
-Once the hardware has been installed, Reticulum is installed on all the Pis, and at
-site A and C, one interface is added for the LoRa radio, as well as one for the WiFi
-radio. At site B, an interface for the LoRa radio, and one interface for each WiFi
-radio is added to the Reticulum configuration file. The transport node option is
-enabled in the configuration of all three gateways.
+* **Implicit authentication:** Because destinations are bound to public keys,
+  communication to a destination is inherently cryptographically authenticated.
+  Only the holder of the corresponding private key can decrypt and respond to
+  traffic addressed to that destination. This also makes application-level
+  authentication *much* simpler, since it can directly use the foundational
+  identity verification built into the core networking layer.
 
-The network is now operational, and ready to serve users across all three areas.
-The organisation prepares a LoRa radio that is supplied to the end users, along
-with a Reticulum configuration file, that contains the right parameters for
-communicating with the LoRa radios installed at the gateway sites.
+* **Identity abstraction:** A single Reticulum Identity can create multiple
+  destinations. This allows a single entity (a person, a device, a service) to
+  present multiple endpoints without needing multiple cryptographic keypairs.
 
-Once users connect to the network, anyone will be able to communicate with anyone
-else across all three sites.
 
-Bridging Over the Internet
-==========================
+Transport Nodes and Instances
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-As the organisation grows, several new communities form in places too far away
-from the core network to be reachable over WiFi links. New gateways similar to those
-previously installed are set up for the new communities at the new sites D and E, but
-they are islanded from the core network, and only serve the local users.
+Reticulum distinguishes between two types of nodes: **Instances**
+and **Transport Nodes**. Every node running Reticulum is an Instance, but not
+every Instance is a Transport Node.
 
-After investigating the options, it is found that it is possible to install an
-Internet connection at site A, and an interface on the Internet connection is
-configured for Reticulum on the Raspberry Pi at site A.
+A **Reticulum Instance** is any system running the Reticulum stack. It can create
+destinations, send and receive packets, establish links, and communicate with
+other nodes. It can also host destinations that are connectable for *anyone* else
+in the network. This means you can easily host globally available services from
+any location, including your home or office. Network-wide, global connectivity
+for all destinations is guaranteed, as long as there is *some* physical way to
+actually transport the packets. Instances are the default state and are appropriate for most end-user devices,
+such as phones, laptops, sensors, or any device that primarily consumes network services.
 
-A member of the organisation at site D, named Dori, is willing to help by sharing
-the Internet connection she already has in her home, and is able to leave a Raspberry
-Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly
-enabled Internet interface on the gateway at site A. Dori is now connected to both
-the nodes at her own local site (through the hill-top LoRa gateway), and all the
-combined users of sites A, B and C. She then enables transport on her node, and
-traffic from site D can now reach everyone at site A, B and C, and vice versa.
+A **Transport Node** is an Instance that has been explicitly configured to
+participate in network-wide transport. Transport nodes forward packets across
+hops, propagate announces, maintain path tables, and serve path requests on
+behalf of other nodes. When a destination sends an announce, Transport Nodes
+receive it, remember the path, and rebroadcast it to other interfaces. When a node
+needs to reach a destination it doesn't have a path for, Transport Nodes help
+resolve the path through the network.
 
-Growth and Convergence
-======================
+Even devices hosting services or serving content should probably just be configured
+as instances, and themselves connect to wider networks via a Transport Node.
+In some situations, this may not be practical though, and as an example, it is
+entirely viable to host a personal Transport Node on a Raspberry Pi, while it
+is at the same time running an LXMF propagation node, and hosting your personal
+site or files over Reticulum.
 
-As the organisation grows, more gateways are added to keep up with the growing user
-base. Some local gateways even add VHF radios and packet modems to reach outlying users
-and communities that are out of reach for the LoRa radios and WiFi backhauls.
+The distinction is important. **Not** every node should be a Transport Node:
 
-As more sites, gateways and users are connected, the amount of coordination required
-is kept to a minimum. If one community wants to add connectivity to the next one
-over, it can simply be done without having to involve everyone or coordinate address
-space or routing tables.
+* **Resource consumption:** Transport nodes maintain path tables, process
+  announces, and forward traffic. This requires memory and CPU resources that
+  may be limited on low-powered devices.
 
-With the added geographical coverage, the operators at site A one day find that
-the original internet bridged interfaces are no longer utilised. The network has
-converged to be completely self-connected, and the sites that were once poorly
-connected outliers are now an integral part of the network.
+* **Stability requirements:** Transport nodes contribute to network convergence.
+  If Transport Nodes frequently go offline, path tables become stale and
+  convergence suffers. Stable, always-on nodes make better Transport Nodes.
+
+* **Bandwidth considerations:** Transport nodes process and rebroadcast network
+  maintenance traffic. On very low-bandwidth mediums, having too many Transport
+  Nodes will consume capacity that should be used for actual data.
+
+In practice, a network typically has a relatively small number of Transport Nodes
+strategically placed to provide coverage and connectivity. End-user devices run
+as Instances, connecting through nearby Transport Nodes to reach the wider network.
+This pattern mirrors traditional networking where routers forward traffic while
+end hosts simply consume connectivity, but with the crucial difference that any
+node *can* become a router if needed, and the decision is yours to make based on
+your network's requirements.
+
+Transport nodes also function as distributed cryptographic keystores. When a
+destination announces itself, Transport Nodes cache the public key and destination
+information. Other nodes can request unknown public keys from the network, and
+Transport Nodes respond with the cached information. This eliminates the need for
+a central directory service while ensuring that public keys remain available
+throughout the network.
+
+Trustless Networking
+^^^^^^^^^^^^^^^^^^^^
+
+Traditional network security models assume high levels of trust at
+specific layers. You might trust your ISP to deliver packets without inspection,
+or trust your VPN provider to handle your traffic, or trust the network
+administrator to configure firewalls appropriately. These trust relationships
+create vulnerabilities and dependencies.
+
+Reticulum is designed to function in **open, trustless environments**. This
+means the protocol makes no assumptions about the trustworthiness of the network
+infrastructure, the other participants, or the transport mediums. Every aspect
+of communication is secured cryptographically:
+
+* **Traffic encryption:** All traffic to single destinations is encrypted using
+  ephemeral keys.
+
+* **Source anonymity:** Reticulum packets do not include source addresses.
+  An observer intercepting a packet cannot determine who sent it, only who it is
+  addressed to (unless IFAC is enabled, in which case nothing can be determined).
+  This provides initiator anonymity by default.
+
+* **Path verification:** The announce mechanism includes cryptographic signatures that
+  prove the authenticity of destination announcements.
+
+* **Unforgeable delivery confirmations:** When a destination proves receipt of a
+  packet, the proof is signed with the destination's identity key. This prevents
+  false acknowledgments and ensures reliable delivery verification.
+
+* **Interface authentication:** When using Interface Access Codes (IFAC), packets
+  on authenticated interfaces carry signatures derived from a shared secret. Only
+  nodes with the correct network name and passphrase can generate valid packets, allowing creation
+  of virtual private networks on shared mediums.
+
+The trustless design has important consequences for network design:
+
+* **Open-access networks are viable:** You can build networks that anyone can
+  join without pre-approval. Because traffic is encrypted and authenticated end-
+  to-end, participants cannot interfere with each other's private communication,
+  even if they share the same transport infrastructure.
+
+* **No traffic inspection or prioritization:** Because traffic contents and
+  sources are opaque to intermediate nodes, there is no mechanism for filtering,
+  prioritizing, or throttling traffic based on its type or origin. All traffic
+  is treated equally. From a neutrality perspective, this is a feature.
+
+* **Adversarial resilience:** The network can operate even if some nodes are
+  malicious or controlled by adversaries. While a malicious Transport Node could
+  refuse to forward certain traffic or drop packets, it cannot decrypt, modify,
+  or impersonate legitimate traffic. Redundant paths and multiple Transport Nodes
+  mitigate the impact of malicious nodes.
+
+Of course, you can also create closed networks. Interface Access
+Codes allow you to restrict participation on specific interfaces. Network
+Identities enable you to verify that discovered interfaces belong to trusted
+operators. Blackhole management lets you block malicious identities. Reticulum
+provides both the tools for open networks and the controls for closed ones. The
+choice is yours based on your requirements.
+
+
+Heterogeneous Connectivity
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In conventional networking, mixing different transport mediums typically requires
+gateways, translation layers, and careful configuration. A WiFi network doesn't
+natively interoperate with a packet radio network without additional infrastructure,
+and you can't just download a car over a serial port, or send an encrypted message
+in a QR code.
+
+Reticulum treats **heterogeneity as a core premise**. The protocol is designed
+to seamlessly mix mediums with vastly different characteristics:
+
+* **Bandwidth:** LoRa links operating at a few hundred bits per second can
+  interconnect with gigabit Ethernet backbones. Reticulum automatically manages
+  the flow of information, prioritizing local traffic on slow segments while
+  allowing global convergence.
+
+* **Latency:** Satellite links with multi-second latency can coexist with local
+  links measured in milliseconds. The transport system handles timing, asynchronous
+  delivery and retransmissions transparently.
+
+* **Topology:** Point-to-point microwave links, broadcast radio networks,
+  switched Ethernet fabrics, and virtual tunnels over the Internet can all be
+  part of the same Reticulum network.
+
+* **Reliability:** Intermittent connections that come and go (such as mobile
+  devices or opportunistic radio contacts) can participate alongside always-on
+  infrastructure. Reticulum gracefully handles link loss and reconnection.
+
+This heterogeneity is achieved through several design elements:
+
+* **Expandable, medium-agnostic interface system:** Reticulum communicates with the physical
+  world through interface modules. Adding support for a new medium is a matter
+  of implementing an interface class. The protocol itself remains unchanged.
+
+* **Interface modes:** Different modes (``full``, ``gateway``, ``access_point``,
+  ``roaming``, ``boundary``) allow you to configure how interfaces interact with
+  the wider network based on their characteristics and role.
+
+* **Announce propagation rules:** Announces are forwarded between interfaces
+  according to rules that account for bandwidth limitations and interface modes.
+  Slow segments are not overwhelmed by traffic from fast segments.
+
+* **Local traffic prioritization:** When bandwidth is constrained, Reticulum
+  prioritizes announces for nearby destinations. This ensures that local
+  connectivity remains functional even when global convergence is incomplete.
+
+For network designers, this means you are free to use whatever mediums are
+available, affordable, or appropriate for your situation. You might use LoRa for
+wide-area low-bandwidth coverage, WiFi for local high-capacity links, I2P for
+anonymous Internet connectivity, and Ethernet for infrastructure backhauls, all
+within the same network. Reticulum handles the translation and coordination
+automatically.
+
+The key design consideration is not whether different mediums can work together
+(they can), but **how** they should work together based on your goals. A node
+with multiple interfaces spanning heterogeneous mediums needs to be configured
+with appropriate interface modes so that traffic flows efficiently. A gateway
+connecting a slow LoRa segment to a fast Internet backbone should be configured
+differently than a mobile device roaming between radio cells.

docs/manual/_sources/software.rst.txt

@@ -0,0 +1,355 @@
+.. _software-main:
+
+************************
+Programs Using Reticulum
+************************
+
+This chapter provides a non-exhaustive list of notable programs, systems and application-layer
+protocols that have been built using Reticulum.
+
+These programs will let you get a feel for how Reticulum works. Most of them have been designed
+to run well even over slow networks based on LoRa or packet radio, but all can also be used over fast
+links, such as local WiFi, wired Ethernet, the Internet, or any combination.
+
+As such, it is easy to get started experimenting, without having to set up any radio
+transceivers or infrastructure just to try it out. Launching the programs on separate
+devices connected to the same WiFi network is enough to get started, and physical
+radio interfaces can then be added later.
+
+Programs & Utilities
+====================
+
+Many different applications using Reticulum already exist, serving a wide variety of purposes
+from day-to-day communication and information sharing to systems administration and tackling
+advanced networking and communications challenges.
+
+Development of Reticulum-based applications and systems is ongoing, so consider this list
+a non-exhaustive starting point of *some* of the options available. With a bit of searching,
+primarily over Reticulum itself, you will find many more interesting things.
+
+Remote Shell
+^^^^^^^^^^^^
+
+The `rnsh <https://github.com/acehoss/rnsh>`_ program lets you establish fully interactive
+remote shell sessions over Reticulum. It also allows you to pipe any program to or from a
+remote system, and is similar to how ``ssh`` works. The ``rnsh`` program is very efficient, and
+can facilitate fully interactive shell sessions, even over extremely low-bandwidth links,
+such as LoRa or packet radio.
+
+In addition to the default, fully interactive terminal mode,
+for extremely limited links, ``rnsh`` offers line-interactive mode, allowing you to interact
+with remote systems, even when link throughput is counted in a few hundreds of bits per second.
+
+.. raw:: latex
+
+    \newpage
+
+Nomad Network
+^^^^^^^^^^^^^
+
+The terminal-based program `Nomad Network <https://github.com/markqvist/nomadnet>`_
+provides a complete encrypted communications suite built with Reticulum. It features
+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.
+
+.. image:: screenshots/nomadnet_3.png
+    :target: https://github.com/markqvist/nomadnet
+
+`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
+for the messaging and information-sharing protocol LXMF.
+
+RNS Page Node
+^^^^^^^^^^^^^
+
+`RNS Page Node <https://git.quad4.io/RNS-Things/rns-page-node>`_ is a simple way to serve pages and files to any other Nomad Network compatible client. Drop-in replacement for NomadNet nodes that primarily serve pages and files.
+
+
+Retipedia
+^^^^^^^^^
+
+You can host the entirity of Wikipedia (or any ``.zim``) file to other Nomad Network clients using `Retipedia <https://github.com/RFnexus/Retipedia>`_.
+
+
+.. raw:: latex
+
+    \newpage
+
+Sideband
+^^^^^^^^
+
+If you would rather use an LXMF client with a graphical user interface, you can take
+a look at `Sideband <https://unsigned.io/sideband>`_, which is available for Android,
+Linux, macOS and Windows. Sideband is an advanced LXMF and LXST client, and a multi-purpose Reticulum
+utility, with features and functionality targeted at advanced users.
+
+.. only:: html
+
+  .. image:: screenshots/sideband_devices.webp
+      :align: center
+      :target: https://unsigned.io/sideband
+
+.. only:: latex
+
+  .. image:: screenshots/sideband_devices.png
+      :align: center
+      :target: https://unsigned.io/sideband
+
+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 all other LXMF clients, and provides advanced features such as voice messaging,
+real-time voice calls, file attachments, private telemetry sharing, and a full
+plugin system for expandability.
+
+.. raw:: latex
+
+    \newpage
+
+MeshChatX
+^^^^^^^^
+
+A `Reticulum MeshChat fork from the future <https://git.quad4.io/RNS-Things/MeshChatX>`_, with the goal of providing everything you need for Reticulum, LXMF, and LXST in one beautiful and feature-rich application. This project is separate from the original Reticulum MeshChat project, and is not affiliated with the original project.
+
+.. only:: html
+
+  .. image:: screenshots/meshchatx.webp
+      :align: center
+      :target: https://git.quad4.io/RNS-Things/MeshChatX
+
+.. only:: latex
+
+  .. image:: screenshots/meshchatx.png
+      :align: center
+      :target: https://git.quad4.io/RNS-Things/MeshChatX
+
+
+Features include full LXST support, custom voicemail, phonebook, contact sharing, and ringtone support, multi-identity handling, modern UI/UX, offline documentation, expanded tools, page archiving, integrated maps, telemetry and improved application security.
+
+.. raw:: latex
+
+    \newpage
+
+MeshChat
+^^^^^^^^
+
+The `Reticulum MeshChat <https://github.com/liamcottle/reticulum-meshchat>`_ application
+is a user-friendly LXMF client for Linux, macOS and Windows, that also includes a Nomad Network
+page browser and other interesting functionality.
+
+.. only:: html
+
+  .. image:: screenshots/meshchat_1.webp
+      :align: center
+      :target: https://github.com/liamcottle/reticulum-meshchat
+
+.. only:: latex
+
+  .. image:: screenshots/meshchat_1.png
+      :align: center
+      :target: https://github.com/liamcottle/reticulum-meshchat
+
+Reticulum MeshChat is of course also compatible with Sideband and Nomad Network, or
+any other LXMF client.
+
+Columba
+^^^^^^^
+
+`Columba <https://github.com/torlando-tech/columba/>`_ is a simple and familiar LXMF
+messaging app Android, built with a native Android interface and Material Design 3.
+
+.. only:: html
+
+  .. image:: screenshots/columba.webp
+      :align: center
+      :width: 25%
+      :target: https://github.com/torlando-tech/columba/
+
+.. only:: latex
+
+  .. image:: screenshots/columba.png
+      :align: center
+      :width: 25%
+      :target: https://github.com/torlando-tech/columba/
+
+While still in early and very active development, it is of course also compatible
+with all other LXMF clients, and allows you to message seamlessly with anyone else
+using LXMF.
+
+.. raw:: latex
+
+    \newpage
+
+Reticulum Relay Chat
+^^^^^^^^^^^^^^^^^^^^
+
+`Reticulum Relay Chat <https://rrc.kc1awv.net/>`_ is a live chat system built on top of the Reticulum Network Stack. It exists to let people talk to each other in real time over Reticulum without dragging in message databases, synchronization engines, or architectural commitments they did not ask for.
+
+The `rrcd <https://github.com/kc1awv/rrcd>`_ program provides a functional, reference RRC hub-server daemon implementation. RRC user clients include `rrc-gui <https://github.com/kc1awv/rrc-gui>`_ and `rrc-web <https://github.com/kc1awv/rrc-web>`_.
+
+RRC is closer in spirit to IRC than to modern “everything platforms.” You connect, you join a room, you talk, and then you leave. If you were present, you saw the conversation. If you were not, the conversation did not wait for you. This is not an accident. This is the entire design.
+
+RetiBBS
+^^^^^^^
+
+`RetiBBS <https://github.com/kc1awv/RetiBBS>`_ is a bulletin board system implementation for Reticulum networks.
+
+.. only:: html
+
+  .. image:: screenshots/retibbs.webp
+      :align: center
+      :target: https://github.com/kc1awv/RetiBBS
+
+.. only:: latex
+
+  .. image:: screenshots/retibbs.png
+      :align: center
+      :target: https://github.com/kc1awv/RetiBBS
+
+RetiBBS allows users to communicate through message boards in a secure manner.
+
+.. raw:: latex
+
+    \newpage
+
+RBrowser
+^^^^^^^^
+
+The `rBrowser <https://github.com/fr33n0w/rBrowser>`_ program is a cross-platform, standalone, web-based browser for exploring NomadNetwork Nodes over Reticulum Network. It automatically discovers NomadNet nodes through network announces and provides a user-friendly interface for browsing distributed content with Micron markup support.
+
+.. only:: html
+
+  .. image:: screenshots/rbrowser.webp
+      :align: center
+      :target: https://github.com/fr33n0w/rBrowser
+
+.. only:: latex
+
+  .. image:: screenshots/rbrowser.png
+      :align: center
+      :target: https://github.com/fr33n0w/rBrowser
+
+Includes useful features like automatic listening for announce, adding nodes to favorites, browsing and rendering any kind of NomadNet links, downloading files from remote nodes, a unique local NomadNet Search Engine and more.
+
+
+.. raw:: latex
+
+    \newpage
+
+Reticulum Network Telephone
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``rnphone`` program, included as part of the `LXST <https://github.com/markqvist/LXST>`_ package is a command-line Reticulum telephone utility and daemon, that allows building physical, hardware telephones for LXST and Reticulum, as well as simply performing calls via the command line.
+
+.. only:: html
+
+  .. image:: screenshots/rnphone.webp
+      :align: center
+      :target: https://github.com/markqvist/LXST
+
+.. only:: latex
+
+  .. image:: screenshots/rnphone.jpg
+      :align: center
+      :target: https://github.com/markqvist/LXST
+
+It supports interfacing directly with hardware peripherals such as GPIO keypads and LCD displays, providing a modular system for building secure hardware telephones.
+
+.. raw:: latex
+
+    \newpage
+
+LXST Phone
+^^^^^^^^^^
+
+The `LXST Phone <https://github.com/kc1awv/lxst_phone>`_ program is a cross-platform desktop application for performing LXST voice calls over Reticulum.
+
+.. only:: html
+
+  .. image:: screenshots/lxst_phone.webp
+      :align: center
+      :target: https://github.com/kc1awv/lxst_phone
+
+.. only:: latex
+
+  .. image:: screenshots/lxst_phone.png
+      :align: center
+      :target: https://github.com/kc1awv/lxst_phone
+
+It supports various advanced features such as SAS verification, peer blocking, rate limiting, encrypted call history storage and contact management.
+
+
+.. raw:: latex
+
+    \newpage
+
+LXMFy
+^^^^^
+
+`LXMFy <https://lxmfy.quad4.io/>`_ is a comprehensive and advanced bot creation framework for LXMF, that allows building any kind of automation or bot system running over LXMF and Reticulum. `Bot implementations exist <https://github.com/lxmfy/awesome-lxmfy-bots>`_ for Home Assistant control, LLM integrations, and various other purposes.
+
+
+LXMF Interactive Client
+^^^^^^^^^^^^^^^^^^^^^^^
+
+`LXMF Interactive Client <https://github.com/fr33n0w/lxmf-cli>`_ is a feature-rich, terminal-based LXMF messaging client with many advanced features and an extensible plugin architecture.
+
+RNS FileSync
+^^^^^^^^^^^^
+
+The `RNS FileSync <https://git.quad4.io/RNS-Things/RNS-Filesync>`_ program enables automatic file synchronization between devices without requiring central servers, internet connectivity, or cloud services. It works over any network medium supported by Reticulum, including radio, LoRa, WiFi, or the internet, making it ideal for off-grid, privacy-focused, and resilient file sharing.
+
+
+Micron Parser JS
+^^^^^^^^^^^^^^^^
+
+`Micron Parser JS <https://github.com/RFnexus/micron-parser-js>`_ is the JavaScript-based parser for the Micron markup language, that most web-based Nomad Network browsers use. If you want to make utilities or tools that display Micron pages, this library is essential.
+
+
+RNMon
+^^^^^
+
+`RNMon <https://github.com/lbatalha/rnmon>`_ is a monitoring daemon designed to monitor the status of multiple RNS applications and push the metrics to an InfluxDB instance over the influx line protocol.
+
+
+.. raw:: latex
+
+    \newpage
+
+Protocols
+=========
+
+A number of standard protocols have emerged through real-world usage and testing in the Reticulum community. While you may sometimes want to use completely custom protocols and implementations when writing Reticulum-based software, using these protocols provides application developers with an easy way to implement advanced functionality quickly and effortlessly. Using them also ensures compatibility and interoperability between many different client applications, creating an open communications ecosystem where users are free to choose the applications that suit their needs, while remaining connected to everyone else.
+
+LXMF
+^^^^
+
+`LXMF <https://github.com/markqvist/lxmf>`_ is a simple and flexible messaging format and delivery protocol that allows a wide variety of applications, while using as little bandwidth as possible. It offers zero-conf message routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports.
+
+LXMF is efficient enough that it can deliver messages over extremely low-bandwidth systems such as packet radio or LoRa. Encrypted LXMF messages can also be encoded as QR-codes or text-based URIs, allowing completely analog paper message transport.
+
+Using Propagation Nodes, LXMF also offer a way to store and forward messages to users or endpoints that are not directly reachable at the time of message emission.
+
+LXST
+^^^^
+
+`LXST <https://github.com/markqvist/lxst>`_ is a simple and flexible real-time streaming format and delivery protocol that allows a wide variety of applications, while using as little bandwidth as possible. It is built on top of Reticulum and offers zero-conf stream routing, end-to-end encryption and Forward Secrecy, and can be transported over any kind of medium that Reticulum supports. It currently powers real-time voice and telephony applications over Reticulum.
+
+RRC
+^^^
+
+The `Reticulum Relay Chat <https://rrc.kc1awv.net/>`_ protocol, is a live chat system built on top of the Reticulum Network Stack. It exists to provide near real-time group communication without dragging in message history databases, federation machinery, or architectural guilt.
+
+RRC is intentionally simple. It does not pretend to be email, a mailbox, or a distributed archive. It behaves more like a conversation in a room. If you were there, you heard it. If you were not, you did not. That is not a bug, that is the point.
+
+Interface Modules & Connectivity Resources
+==========================================
+
+This section provides a list of various community-provided interface modules, guides and resources for creating Reticulum networks over special or challenging mediums.
+
+* Custom interface module for running `RNS over HTTP <https://git.quad4.io/RNS-Things/RNS-over-HTTP>`_
+* Guide for running `Reticulum over ICMP <https://github.com/matvik22000/rns-over-icmp>`_ using ``PipeInterface``
+* Guide for running `Reticulum over DNS <https://github.com/markqvist/Reticulum/discussions/1002>`_ with Iodine
+* Guide for running `Reticulum over HF radio <https://github.com/RFnexus/reticulum-over-hf>`_
+* `Modem73 <https://github.com/RFnexus/modem73>`_ is a KISS TNC OFDM modem frontend that can be used with Reticulum

docs/manual/_sources/support.rst.txt

@@ -16,12 +16,12 @@ Donations are gratefully accepted via the following channels:
     Monero:
     84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
 
-    Ethereum:
-    0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a
-
     Bitcoin:
-    3CPmacGm34qYvR6XWLVEJmi2aNe3PZqUuq
+    bc1pgqgu8h8xvj4jtafslq396v7ju7hkgymyrzyqft4llfslz5vp99psqfk3a6
 
+    Ethereum:
+    0x91C421DdfB8a30a49A71d63447ddb54cEBe3465E
+    
     Liberapay:
     https://liberapay.com/Reticulum/
 
@@ -33,15 +33,28 @@ organisation? Make them a reality quickly by sponsoring their implementation.
 
 Provide Feedback
 ================
-All feedback on the usage, functioning and potential dysfunctioning of any and
+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.
+improvement of Reticulum. But...
+
+.. warning::
+  
+  **Think before you speak**. As time has shown, over 80% of the "feedback",
+  "bug reports" and "advice" the Reticulum project has received has been
+  irrelevant noise, stemming from erroneous assumptions, misunderstanding the
+  foundational functionality or philosophy behind the system, or simply
+  the malinformed (but overly opinionated) personal preferences of individual
+  drive-by architects. This wastes the time of everyone involved.
+
+  The Reticulum project is not a public teahouse for serving the attention
+  needs of random bypassers, but a highly complex system engineered and
+  refined over more than a decade, designed to provide communication and
+  connectivity guarantees in highly adversarial environments.
+
+  If you want to voice your opinion, it better be well-informed, and we
+  expect you to have a comprehensive and solid foundation for your points
+  of view. Everything else will be ignored.
 
 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.
-
-Contribute Code
-===============
-Join us on `the GitHub repository <https://github.com/markqvist/reticulum>`_ to
-report issues, suggest functionality and contribute code to Reticulum.

docs/manual/_sources/understanding.rst.txt

@@ -13,9 +13,8 @@ reference implementation and API reference. That being said, this chapter is an
 understanding how Reticulum works from a high-level perspective, along with the general principles of
 Reticulum, and how to apply them when creating your own networks or software.
 
-After reading this document, you should be well-equipped to understand how a Reticulum network
-operates, what it can achieve, and how you can use it yourself. If you want to help out with the
-development, this is also the place to start, since it will provide a pretty clear overview of the
+After reading this chapter, you should be well-equipped to understand how a Reticulum network
+operates, what it can achieve, and how you can use it yourself. This chapter also seeks to provide an overview of the
 sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it
 approaches those solutions.
 
@@ -117,7 +116,7 @@ Reticulum uses the singular concept of *destinations*. Any application using Ret
 networking stack will need to create one or more destinations to receive data, and know the
 destinations it needs to send data to.
 
-All destinations in Reticulum are _represented_ as a 16 byte hash. This hash is derived from truncating a full
+All destinations in Reticulum are *represented* as a 16 byte hash. This hash is derived from truncating a full
 SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
 will be displayed as 16 hexadecimal bytes, like this example: ``<13425ec15b621c1d928589718000d814>``.
 
@@ -141,7 +140,7 @@ ratchets on a per-destination basis. The multi-hop transport, coordination, veri
 layers are fully autonomous and also based on elliptic curve cryptography.
 
 Reticulum also offers symmetric key encryption for group-oriented communications, as well as
-unencrypted packets for local broadcast purposes.
+unencrypted packets (for local broadcast purposes **only**).
 
 Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
 and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
@@ -401,11 +400,10 @@ any transport node receiving it, but according to some specific rules:
     to be transmitted, the newest announce is discarded. If the newest announce contains different
     application specific data, it will replace the old announce.
 
-Once an announce has reached a node in the network, any other node in direct contact with that
-node will be able to reach the destination the announce originated from, simply by sending a packet
-addressed to that destination. Any node with knowledge of the announce will be able to direct the
-packet towards the destination by looking up the next node with the shortest amount of hops to the
-destination.
+Once an announce has reached a transport node in the network, any other node in direct contact with that
+transport node will be able to reach the destination the announce originated from, simply by sending a packet
+addressed to that destination. Any transport node with knowledge of the announce will be able to direct the
+packet towards the destination by looking up the most efficient next node to the destination.
 
 According to these rules, an announce will propagate throughout the network in a predictable way,
 and make the announced destination reachable in a short amount of time. Fast networks that have the
@@ -414,6 +412,17 @@ new destinations. Slower segments of such networks might take a bit longer to ga
 the wide and fast networks they are connected to, but can still do so over time, while prioritising full
 and quickly converging end-to-end connectivity for their local, slower segments.
 
+.. tip::
+
+    Even very slow networks, that simply don't have the capacity to ever reach *full* convergence
+    will generally still be able to reach **any other destination on any connected segments**, since
+    interconnecting transport nodes will prioritize announces into the slower segments that are
+    actually requested by nodes on these.
+
+    This means that slow, low-capacity or low-resource segments **don't** need to have full network
+    knowledge, since paths can always be recursively resolved from other segments that do have
+    knowledge about them.
+
 In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
 end-to-end connectivity in about one minute, given there is enough bandwidth available to process
 the required amount of announces.
@@ -424,7 +433,7 @@ Reaching the Destination
 ------------------------
 
 In networks with changing topology and trustless connectivity, nodes need a way to establish
-*verified connectivity* with each other. Since the network is assumed to be trustless, Reticulum
+*verified connectivity* with each other. Since the underlying network mediums are assumed to be trustless, Reticulum
 must provide a way to guarantee that the peer you are communicating with is actually who you
 expect. Reticulum offers two ways to do this.
 
@@ -435,7 +444,7 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
     an ECDH key exchange with the destination's public key (or ratchet key, if available), and encrypt the information.
 
 * | It is important to note that this key exchange does not require any network traffic. The sender already
-    knows the public key of the destination from an earlier received *announce*, and can thus perform the ECDH
+    knows the public key of the destination from an earlier received announce, and can thus perform the ECDH
     key exchange locally, before sending the packet.
 
 * | The public part of the newly generated ephemeral key-pair is included with the encrypted token, and sent
@@ -461,14 +470,14 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
 
 For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the *Link* API. To establish a *link*, the following process is employed:
 
-* | First, the node that wishes to establish a link will send out a special packet, that
+* | First, the node that wishes to establish a link will send out a *link request* packet, that
     traverses the network and locates the desired destination. Along the way, the Transport Nodes that
-    forward the packet will take note of this *link request*.
+    forward the packet will take note of this *link request*, and mark it as pending.
 
 * | Second, if the destination accepts the *link request* , it will send back a packet that proves the
     authenticity of its identity (and the receipt of the link request) to the initiating node. All
     nodes that initially forwarded the packet will also be able to verify this proof, and thus
-    accept the validity of the *link* throughout the network.
+    accept the validity of the *link* throughout the network. The link is now marked as *established*.
 
 * | When the validity of the *link* has been accepted by forwarding nodes, these nodes will
     remember the *link* , and it can subsequently be used by referring to a hash representing it.
@@ -560,9 +569,10 @@ an arbitrary number of hops, where information will be exchanged between two nod
     *link proof* to perform it's own Diffie Hellman Key Exchange and derive the symmetric key
     that is used to encrypt the channel. Information can now be exchanged reliably and securely.
 
+.. note::
 
-It’s important to note that this methodology ensures that the source of the request does not need to
-reveal any identifying information about itself. The link initiator remains completely anonymous.
+    It’s important to note that this methodology ensures that the source of the request does not need to
+    reveal any identifying information about itself. **The link initiator remains completely anonymous**.
 
 When using *links*, Reticulum will automatically verify all data sent over the link, and can also
 automate retransmissions if *Resources* are used.
@@ -585,6 +595,82 @@ the transfer, integrity verification and reassembling the data on the other end.
 of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
 or stream data directly from files.
 
+.. _understanding-network_identities:
+
+Network Identities
+==================
+
+In Reticulum, every peer and application utilizes a cryptographic **Identity** to verify authenticity and establish encrypted channels. While standard identities are typically used to represent a single user, device, or service, Reticulum introduces the concept of a **Network Identity** to represent a logical group of nodes or an entire community infrastructure.
+
+A Network Identity is, at its core, a standard Reticulum Identity keyset. However, its purpose and usage differ from a personal identity. Instead of identifying a single entity, a Network Identity acts as a shared credential that federates multiple independent Transport Instances under a single, verifiable administrative domain.
+
+
+Conceptual Overview
+-------------------
+
+You can think of a standard Reticulum Identity as a self-sovereign, privately created passport for a single person. A Network Identity, conversely, is akin to a cryptographic flag, or a charter that flies over a fleet of ships. It signifies that while the ships may operate independently and be physically distant, they belong to the same organization, follow the same protocols, and are expected to act in concert.
+
+When you configure a Network Identity on one or more of your nodes, you are effectively declaring that these nodes constitute a specific "network" within a broader Reticulum mesh. This allows other peers to recognize interfaces not just as "a node named Alice", but as "a gateway belonging to The Eastern Ret Of Freedom".
+
+
+Current Usage
+-------------
+
+At present, the primary function of a Network Identity is within the :ref:`Interface Discovery<using-interface_discovery>` system.
+
+When a Transport Instance broadcasts a discovery announce for an interface, it can optionally sign that announce with a Network Identity, instead of just its local transport identity. Remote peers receiving the announce can then verify the signature. This provides functionality for two important distinctions:
+
+1.  **Authenticity:** It proves that the interface was published by an operator who possesses the private key for that Network Identity.
+2.  **Trust Boundaries:** It allows users to configure their systems to only accept and connect to interfaces that belong to specific Network Identities, effectively creating "whitelisted" zones of trusted infrastructure.
+
+.. note::
+  If you enable encryption on your discovery announces, the Network Identity is used as the shared secret. Only peers who have been explicitly provided with the Network Identity's full keyset (and have it configured locally) will be able to decrypt and utilize the connection details.
+
+  This functionality will be expanded in the future, so that peers with delegated keys can be allowed to decrypt discovery announces without holding the root network key. Currently, the functionality is sufficient for sharing interface information privately where you control all nodes that must decrypt the discovered interfaces.
+
+
+Future Implications
+-------------------
+
+While the current implementation focuses on interface discovery, the concept of Network Identities serves as the foundational building block for future Reticulum features designed to support large-scale, organic mesh formation.
+
+As the ecosystem evolves, Network Identities will facilitate:
+
+*   **Distributed Name Resolution:** A system where networks can publish name-to-identity mappings, allowing human-readable names to resolve without centralized servers.
+*   **Service Publishing:** Networks will be able to announce specific capabilities, services, or information endpoints available publicly or to their members.
+*   **Inter-Network Federation:** Trust relationships between different networks, allowing for seamless but managed flow of traffic and information across distinct administrative boundaries.
+*   **Distributed Blackhole Management:** A reputation-based system for blackhole list distribution, where trusted Network Identities can sign and publish lists of blackholed identities. This allows communities to collaboratively enforce security standards and filter spam or malicious identities across the parts of the wider mesh that they are responsible for.
+
+By adopting the use of Network Identities now, you are preparing your infrastructure to be compatible with this future functionality.
+
+
+Creating and Using a Network Identity
+-------------------------------------
+
+Since a Network Identity is simply a standard Reticulum Identity, you create one using the built-in tools.
+
+1.  **Generate the Identity:**
+    Use the ``rnid`` utility to generate a new identity file that will serve as your Network Identity.
+
+    .. code:: sh
+
+      $ rnid -g ~/.reticulum/storage/identities/my_network
+
+2.  **Distribute the Public Key:**
+    The public key must be distributed to any Transport Instance that needs to verify your network's announces and discovery information. By default, if your node is set up to use a network identity, this happens automatically (using the standard announce mechanism).
+
+3.  **Configure Instances:**
+    In the ``[reticulum]`` section of the configuration file on every node within your network, point the ``network_identity`` option to the file you created.
+
+    .. code:: ini
+
+      [reticulum]
+      ...
+      network_identity = ~/.reticulum/storage/identities/my_network
+      ...
+
+Once configured, your instances will automatically utilize this identity for signing discovery announces (and potentially decrypting network-private information), presenting a unified front to the wider network.
+
 .. _understanding-referencesystem:
 
 Reference Setup
@@ -624,18 +710,20 @@ into the future. The current Reference System Setup is as follows:
 * **Interface Device**
     A data radio consisting of a LoRa radio module, and a microcontroller with open source
     firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
-    MHz frequency bands. More details can be found on the `RNode Page <https://unsigned.io/rnode>`_.
+    MHz frequency bands. More details can be found on the `RNode Page <https://github.com/markqvist/rnode_firmware>`_.
 * **Host Device**
     Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
-    recommended.
+    a good place to start, but anything can be used.
 * **Software Stack**
-    The most recently released Python Implementation of Reticulum, running on a Debian based
+    The most recently released Python Implementation of Reticulum, running on a Linux-based
     operating system.
 
-To avoid confusion, it is very important to note, that the reference interface device **does not**
-use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
-need a plain LoRa radio module connected to an controller with the correct firmware. Full details on how to
-get or make such a device is available on the `RNode Page <https://unsigned.io/rnode>`_.
+.. note::
+
+    To avoid confusion, it is very important to note, that the reference interface device **does not**
+    use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
+    need a plain LoRa radio module connected to a controller with the correct firmware. Full details on how to
+    get or make such a device is available on the `RNode Page <https://github.com/markqvist/rnode_firmware>`_.
 
 With the current reference setup, it should be possible to get on a Reticulum network for around 100$
 even if you have none of the hardware already, and need to purchase everything.
@@ -649,16 +737,16 @@ Protocol Specifics
 ==================
 
 This chapter will detail protocol specific information that is essential to the implementation of
-Reticulum, but non critical in understanding how the protocol works on a general level. It should be
+Reticulum, but non-critical in understanding how the protocol works on a general level. It should be
 treated more as a reference than as essential reading.
 
 
 Packet Prioritisation
 ---------------------
 
-Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
-on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
-times and priorities described earlier in this chapter.
+Currently, Reticulum is completely priority-agnostic regarding *general* traffic. All traffic is handled
+on a first-come, first-serve basis. Announce re-transmission and other maintenance traffic is handled
+according to the re-transmission times and priorities described earlier in this chapter.
 
 
 Interface Access Codes
@@ -666,8 +754,8 @@ Interface Access Codes
 
 Reticulum can create named virtual networks, and networks that are only accessible by knowing a preshared
 passphrase. The configuration of this is detailed in the :ref:`Common Interface Options<interfaces-options>`
-section. To implement these feature, Reticulum uses the concept of Interface Access Codes, that are calculated
-and verified per packet.
+section. To implement this feature, Reticulum uses the concept of Interface Access Codes, that are calculated
+and verified per-packet.
 
 An interface with a named virtual network or passphrase authentication enabled will derive a shared Ed25519
 signing identity, and for every outbound packet generate a signature of the entire packet. This signature is
@@ -912,6 +1000,11 @@ 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.
 
+Using the normal RNS installation procedures, it is not possible to install Reticulum on a
+system without the required OpenSSL primitives being available, and if they are not, they will
+be resolved and installed as a dependency. It is only possible to use the pure-python primitives
+by manually specifying this, for example by using the ``rnspure`` package.
+
 .. 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

docs/manual/_sources/using.rst.txt

@@ -53,7 +53,7 @@ The entire configuration of Reticulum is found in the ``~/.reticulum/config``
 file. When Reticulum is first started on a new system, a basic, but fully functional
 configuration file is created. The default configuration looks like this:
 
-.. code::
+.. code:: ini
 
   # This is the default Reticulum config file.
   # You should probably edit it to include any additional,
@@ -260,13 +260,14 @@ various configuration options, and interface configuration examples:
   Reticulum Network Stack Daemon
 
   options:
-    -h, --help       show this help message and exit
-    --config CONFIG  path to alternative Reticulum config directory
+    -h, --help        show this help message and exit
+    --config CONFIG   path to alternative Reticulum config directory
     -v, --verbose
     -q, --quiet
-    -s, --service    rnsd is running as a service and should log to file
-    --exampleconfig  print verbose configuration example to stdout and exit
-    --version        show program's version number and exit
+    -s, --service     rnsd is running as a service and should log to file
+    -i, --interactive drop into interactive shell after initialisation
+    --exampleconfig   print verbose configuration example to stdout and exit
+    --version         show program's version number and exit
 
 You can easily add ``rnsd`` as an always-on service by :ref:`configuring a service<using-systemd>`.
 
@@ -337,8 +338,8 @@ Filter output to only show some interfaces:
 .. code:: text
 
   usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-A]
-                  [-l] [-s SORT] [-r] [-j] [-R hash] [-i path]
-                  [-w seconds] [-v] [filter]
+                  [-l] [-t] [-s SORT] [-r] [-j] [-R hash] [-i path]
+                  [-w seconds] [-d] [-D] [-m] [-I seconds] [-v] [filter]
 
   Reticulum Network Stack Status
 
@@ -352,12 +353,19 @@ Filter output to only show some interfaces:
     -a, --all             show all interfaces
     -A, --announce-stats  show announce stats
     -l, --link-stats      show link stats
-    -s SORT, --sort SORT  sort interfaces by [rate, traffic, rx, tx, announces, arx, atx, held]
+    -t, --totals          display traffic totals
+    -s, --sort SORT       sort interfaces by [rate, traffic, rx, tx, rxs, txs,
+                                              announces, arx, atx, held]
     -r, --reverse         reverse sorting
     -j, --json            output in JSON format
-    -R hash               transport identity hash of remote instance to get status from (requires -i)
+    -R hash               transport identity hash of remote instance to get status from
     -i path               path to identity used for remote management
     -w seconds            timeout before giving up on remote queries
+    -d, --discovered      list discovered interfaces
+    -D                    show details and config entries for discovered interfaces
+    -m, --monitor         continuously monitor status
+    -I, --monitor-interval seconds
+                          refresh interval for monitor mode (default: 1)
     -v, --verbose
 
 
@@ -436,33 +444,33 @@ Decrypt a file using the Reticulum Identity it was encrypted for:
   options:
     -h, --help            show this help message and exit
     --config path         path to alternative Reticulum config directory
-    -i identity, --identity identity
-                          hexadecimal Reticulum Destination hash or path to Identity file
-    -g path, --generate path
-                          generate a new Identity
+    -i, --identity identity
+                          hexadecimal Reticulum identity or destination hash, or path to Identity file
+    -g, --generate file   generate a new Identity
+    -m, --import identity_data
+                          import Reticulum identity in hex, base32 or base64 format
+    -x, --export          export identity to hex, base32 or base64 format
     -v, --verbose         increase verbosity
     -q, --quiet           decrease verbosity
-    -a aspects, --announce aspects
+    -a, --announce aspects
                           announce a destination based on this Identity
-    -H aspects, --hash aspects
-                          show destination hashes for other aspects for this Identity
-    -e path, --encrypt path
-                          encrypt file
-    -d path, --decrypt path
-                          decrypt file
-    -s path, --sign path  sign file
-    -V path, --validate path
-                          validate signature
-    -r path, --read path  input file path
-    -w path, --write path
-                          output file path
+    -H, --hash aspects    show destination hashes for other aspects for this Identity
+    -e, --encrypt file    encrypt file
+    -d, --decrypt file    decrypt file
+    -s, --sign path       sign file
+    -V, --validate path   validate signature
+    -r, --read file       input file path
+    -w, --write file      output file path
     -f, --force           write output even if it overwrites existing files
     -R, --request         request unknown Identities from the network
     -t seconds            identity request timeout before giving up
     -p, --print-identity  print identity info and exit
     -P, --print-private   allow displaying private keys
+    -b, --base64          Use base64-encoded input and output
+    -B, --base32          Use base32-encoded input and output
     --version             show program's version number and exit
 
+.. _utility-rnpath:
 
 The rnpath Utility
 ====================
@@ -484,21 +492,23 @@ Resolve path to a destination:
 
 .. code:: text
 
-  usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-m hops]
-                [-r] [-d] [-D] [-x] [-w seconds] [-R hash] [-i path]
-                [-W seconds] [-j] [-v] [destination]
+  usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-m hops] [-r] [-d] [-D]
+                [-x] [-w seconds] [-R hash] [-i path] [-W seconds] [-b] [-B] [-U]
+                [--duration DURATION] [--reason REASON] [-p] [-j] [-v]
+                [destination] [list_filter]
 
-  Reticulum Path Discovery Utility
+  Reticulum Path Management Utility
 
   positional arguments:
     destination           hexadecimal hash of the destination
+    list_filter           filter for remote blackhole list view
 
   options:
     -h, --help            show this help message and exit
     --config CONFIG       path to alternative Reticulum config directory
     --version             show program's version number and exit
     -t, --table           show all known paths
-    -m hops, --max hops   maximum hops to filter path table by
+    -m, --max hops        maximum hops to filter path table by
     -r, --rates           show announce rate info
     -d, --drop            remove the path to a destination
     -D, --drop-announces  drop all queued announces
@@ -507,6 +517,13 @@ Resolve path to a destination:
     -R hash               transport identity hash of remote instance to manage
     -i path               path to identity used for remote management
     -W seconds            timeout before giving up on remote queries
+    -b, --blackholed      list blackholed identities
+    -B, --blackhole       blackhole identity
+    -U, --unblackhole     unblackhole identity
+    --duration DURATION   duration of blackhole enforcement in hours
+    --reason REASON       reason for blackholing identity
+    -p, --blackholed-list
+                          view published blackhole list for remote transport instance
     -j, --json            output in JSON format
     -v, --verbose
 
@@ -619,13 +636,20 @@ Or fetch a file from the remote system:
 
   $ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
 
+The default identity file is stored in ``~/.reticulum/identities/rncp``, but you can use
+another one, which will be created if it does not already exist
+
+.. code:: text
+
+  $ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e -i /path/to/identity
+
 **All Command-Line Options**
 
 .. code:: text
 
   usage: rncp [-h] [--config path] [-v] [-q] [-S] [-l] [-F] [-f]
               [-j path] [-b seconds] [-a allowed_hash] [-n] [-p]
-              [-w seconds] [--version] [file] [destination]
+              [-i identity] [-w seconds] [--version] [file] [destination]
 
   Reticulum File Transfer Utility
 
@@ -640,17 +664,134 @@ Or fetch a file from the remote system:
     -q, --quiet           decrease verbosity
     -S, --silent          disable transfer progress output
     -l, --listen          listen for incoming transfer requests
+    -C, --no-compress     disable automatic compression
     -F, --allow-fetch     allow authenticated clients to fetch files
     -f, --fetch           fetch file from remote listener instead of sending
-    -j path, --jail path  restrict fetch requests to specified path
+    -j, --jail path       restrict fetch requests to specified path
+    -s, --save path       save received files in specified path
+    -O, --overwrite       Allow overwriting received files, instead of adding postfix
     -b seconds            announce interval, 0 to only announce at startup
-    -a allowed_hash       allow this identity
+    -a allowed_hash       allow this identity (or add in ~/.rncp/allowed_identities)
     -n, --no-auth         accept requests from anyone
     -p, --print-identity  print identity and destination info and exit
+    -i identity           path to identity to use
     -w seconds            sender timeout before giving up
+    -P, --phy-rates       display physical layer transfer rates
     --version             show program's version number and exit
 
 
+The rngit Utility
+=================
+
+The ``rngit`` utility provides full Git repository hosting and interaction over Reticulum. It allows you to host Git repositories on Reticulum nodes, and to interact with remote repositories using standard Git commands through the ``rns://`` URL scheme.
+
+The system consists of two parts: The ``rngit`` node that hosts repositories, and the ``git-remote-rns`` helper that enables Git to communicate with rngit nodes. As soon as you have RNS installed on your system, you can transparently use Git with Reticulum-hosted repositories just like any other type of remote. Git over Reticulum uses URLs in the following format: ``rns://DESTINATION_HASH/group/repo``.
+
+If you set a branch to track a Reticulum remote as the default upstream, you can simply use `git` as you normally would; all commands work transparently and as expected.
+
+.. warning::
+   **The rngit program is a new addition to RNS!** This functionality was introduced in RNS 1.2.0. While great care has been taken to design a secure, but highly configurable and flexible permission system for allowing many users to interact with many different repositories on a single node, ``rngit`` has not been tested extensively in the wild! Be careful when hosting repositories, especially if they are public or semi-public.
+
+**Usage Examples**
+
+Run ``rngit`` to start a repository node:
+
+.. code:: text
+
+  $ rngit
+
+  [Notice] Starting Reticulum Git Node...
+  [Notice] Reticulum Git Node listening on <0d7334d411d00120cbad24edf355fdd2>
+
+On the first run, ``rngit`` will create a default configuration file. You will then need to edit this, to point to your repository locations, configure access permissions, and perform any other necessary configuration.
+
+View your identity and destination hashes:
+
+.. code:: text
+
+  $ rngit --print-identity
+
+  Git Peer Identity        : <959e10e5efc1bd9d97a4083babe51dea>
+  Repository Node Identity : <153cb870b4665b8c1c348896292b0bad>
+  Repositories Destination : <0d7334d411d00120cbad24edf355fdd2>
+
+You can run ``rngit`` in service mode with logging to file:
+
+.. code:: text
+
+  $ rngit -s
+
+Clone a repository from a remote ``rngit`` node:
+
+.. code:: text
+
+  $ git clone rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo
+
+Add a Reticulum remote to an existing repository:
+
+.. code:: text
+
+  $ git remote add some_remote rns://50824b711717f97c2fb1166ceddd5ea9/public/myrepo
+
+Push changes to the Reticulum remote:
+
+.. code:: text
+
+  $ git push some_remote master
+
+Get changes from a remote repository:
+
+.. code:: text
+
+  $ git pull rns_remote master
+
+**Repository Structure**
+
+The ``rngit`` node organizes repositories into groups. Each group is a directory containing bare Git repositories. The repository path format is ``group_name/repo_name``. For example, a repository at ``/var/git/public/myrepo`` would be accessible as ``public/myrepo`` via the URL ``rns://DESTINATION_HASH/public/myrepo``.
+
+**Configuration**
+
+The ``rngit`` node configuration file is located at ``~/.rngit/config`` (or ``/etc/rngit/config`` for system-wide installations). The default configuration includes:
+
+- Repository group paths defining where to find bare repositories
+- Access permissions for groups and individual repositories
+- Announce intervals for network visibility
+
+Access permissions can be configured at the group level in the config file, or per-repository using ``.allowed`` files. Permissions use the format ``permission:target`` where permission is ``r`` (read), ``w`` (write), or ``rw`` (read/write), and target is ``all``, ``none``, or a specific identity hash.
+
+Repository-specific ``.allowed`` files can be static text files or executable scripts that output permission rules to stdout. A ``group.allowed`` file in a repository group directory applies to all repositories within that group.
+
+**All Command-Line Options (rngit)**
+
+.. code:: text
+
+  usage: rngit.py [-h] [--config CONFIG] [--rnsconfig RNSCONFIG] [-s] [-i] [-v]
+                  [-q] [--version]
+
+  Reticulum Git Repository Node
+
+  options:
+    -h, --help            show this help message and exit
+    --config CONFIG       path to alternative config directory
+    --rnsconfig RNSCONFIG
+                          path to alternative Reticulum config directory
+    -p, --print-identity  print identity and destination info and exit
+    -s, --service         rngit is running as a service and should log to file
+    -i, --interactive     drop into interactive shell after initialisation
+    -v, --verbose         increase verbosity
+    -q, --quiet           decrease verbosity
+    --version             show program's version number and exit
+
+**All Command-Line Options (git-remote-rns)**
+
+The ``git-remote-rns`` helper is automatically invoked by Git when interacting with ``rns://`` URLs. It is not typically run directly by users, but accepts the following environment variables for configuration:
+
+- ``RNGIT_CONFIG`` - Path to alternative client configuration directory
+- ``RNS_CONFIG`` - Path to alternative Reticulum configuration directory
+
+The client configuration file is located at ``~/.rngit/client_config`` and allows adjusting parameters such as the reference batch size for transfers.
+
+
 The rnx Utility
 ================
 
@@ -723,6 +864,282 @@ another one, which will be created if it does not already exist
     --version             show program's version number and exit
 
 
+The rnsh Utility
+================
+
+The ``rnsh`` utility provides a fully interactive remote shell over Reticulum.
+It allows you to establish encrypted, authenticated shell sessions on remote
+systems, complete with terminal emulation, pipe support, and window resizing.
+
+While the ``rnx`` utility is useful for simple remote command execution and
+retrieving output, ``rnsh`` provides a complete interactive terminal experience,
+making it ideal for remote administration and management tasks that require
+real-time interaction, just like SSH does for IP networks.
+
+``rnsh`` operates in two modes: a *listener* mode that accepts incoming
+connections, and an *initiator* mode that connects to a remote listener. Both
+sides authenticate using Reticulum Identities, ensuring that only authorised
+peers can establish sessions.
+
+.. note::
+   ``rnsh`` provides a genuine interactive terminal over Reticulum. It supports
+   full terminal emulation including escape sequences, window resizing, signal
+   forwarding, and piping of standard input, output and error streams. This
+   makes it suitable for running text editors, terminal multiplexers, and any
+   other interactive programs on remote systems.
+
+**Usage Examples**
+
+Start ``rnsh`` in listener mode, accepting connections from specific identities:
+
+.. code:: text
+
+  $ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+
+You can also specify allowed identity hashes (one per line) in the file
+``~/.rnsh/allowed_identities`` or ``~/.config/rnsh/allowed_identities``, and
+simply run the program in listener mode:
+
+.. code:: text
+
+  $ rnsh -l
+
+Connect to a remote listener from another system:
+
+.. code:: text
+
+  $ rnsh 7a55144adf826958a9529a3bcf08b149
+
+Specify a command to run on the remote system, separating ``rnsh`` options from
+the remote command with ``--``:
+
+.. code:: text
+
+  $ rnsh 7a55144adf826958a9529a3bcf08b149 -- top
+
+Set a default command for the listener, in case the initiator does not supply
+one, or when remote command execution is disabled:
+
+.. code:: text
+
+  $ rnsh -l -- /bin/bash --login
+
+Use the ``-m`` flag to mirror the exit code of the remote process:
+
+.. code:: text
+
+  $ rnsh -m 7a55144adf826958a9529a3bcf08b149 -- /usr/local/bin/check-status
+
+Use the ``-p`` flag to display the identity and destination hash for a listener:
+
+.. code:: text
+
+  $ rnsh -l -p
+
+  Identity     : <984b74a3f768bef236af4371e6f248cd>
+  Listening on : 7a55144adf826958a9529a3bcf08b149
+
+Use a specific identity file rather than the default:
+
+.. code:: text
+
+  $ rnsh -l -i /path/to/identity
+
+Announce the listener destination on startup, and periodically:
+
+.. code:: text
+
+  $ rnsh -l -b 900
+
+The ``-b`` option specifies the announce period in seconds. Use ``0`` to
+announce only once at startup.
+
+**Authentication & Authorisation**
+
+By default, ``rnsh`` requires that connecting initiators identify themselves
+with a Reticulum Identity whose hash is present in the list of allowed
+identities. Allowed identities can be specified on the command line with the
+``-a`` option, and can be used multiple times:
+
+.. code:: text
+
+  $ rnsh -l -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+
+You can also maintain a list of allowed identity hashes in the file
+``~/.rnsh/allowed_identities`` or ``~/.config/rnsh/allowed_identities``,
+with one hex hash per line. This file is reloaded every time a new connection
+is received, so changes take effect immediately without restarting ``rnsh``.
+
+If you want to accept connections from any identity (for testing or in fully
+trusted environments), you can disable authentication with the ``-n`` option:
+
+.. code:: text
+
+  $ rnsh -l -n
+
+.. warning::
+   Disabling authentication with ``-n`` means that **any** Reticulum peer that
+   can reach your listener will be able to execute commands on your system. Only
+   use this option if you *really* know what you're doing.
+
+**Remote Command Control**
+
+When running in listener mode, ``rnsh`` allows you to control how remote
+commands are handled:
+
+- By default, the listener accepts the command sent by the initiator. If the
+  initiator does not supply a command, the listener's default shell is used.
+
+- Use ``-C`` (``--no-remote-command``) to disable execution of commands received
+  from the initiator. Only the listener's default command (or the command
+  specified after ``--``) will be executed:
+
+.. code:: text
+
+  $ rnsh -l -C -- /usr/local/bin/safe-script
+
+- Use ``-A`` (``--remote-command-as-args``) to append the initiator's command
+  to the listener's default command instead of replacing it. This can be useful
+  for restricting the remote to a specific program while still allowing the
+  initiator to pass arguments:
+
+.. code:: text
+
+  $ rnsh -l -A -- /usr/bin/top
+
+**Service Names**
+
+When running in listener mode, ``rnsh`` uses a service name to differentiate
+between multiple listener instances that may share the same identity. By
+default, the service name is ``default``. You can specify a different service
+name with the ``-s`` option:
+
+.. code:: text
+
+  $ rnsh -l -s monitoring
+
+This allows you to run multiple listeners on the same node, each with a
+different service name and purpose.
+
+**Initiator Options**
+
+When connecting to a remote listener, several options are available:
+
+- Use ``-N`` (``--no-id``) to disable sending your identity to the remote
+  listener. Note that the listener must have authentication disabled (``-n``)
+  for the connection to succeed in this case.
+
+- Use ``-m`` (``--mirror``) to make the initiator return with the exit code of
+  the remote process, rather than always returning ``0``.
+
+- Use ``-w`` (``--timeout``) to specify the connection and request timeout in
+  seconds. By default, the timeout matches the Reticulum path request timeout.
+
+**Identity & Destination**
+
+The default identity file for ``rnsh`` is stored at
+``~/.reticulum/identities/rnsh``, but you can specify a different one with the
+``-i`` option, which will be created if it does not already exist:
+
+.. code:: text
+
+  $ rnsh -l -i /path/to/identity
+
+To display the identity and destination information for a listener, use the
+``-p`` option. When combined with ``-l``, both the identity and the listening
+destination hash are displayed:
+
+.. code:: text
+
+  $ rnsh -p
+
+  Identity     : <984b74a3f768bef236af4371e6f248cd>
+
+  $ rnsh -l -p
+
+  Identity     : <984b74a3f768bef236af4371e6f248cd>
+  Listening on : 7a55144adf826958a9529a3bcf08b149
+
+**Verbosity**
+
+Like other Reticulum utilities, ``rnsh`` supports the ``-v`` and ``-q`` flags
+to increase or decrease logging verbosity. Multiple flags can be specified to
+further adjust the log level. The default log level is ``INFO`` for listeners
+and ``ERROR`` for initiators.
+
+.. code:: text
+
+  $ rnsh -l -vv       # Listener with debug-level output
+  $ rnsh -q 7a55144adf826958a9529a3bcf08b149   # Quiet initiator
+
+By default, all log output is routed to ``~/.rnsh/logfile`` for initiators.
+
+**Escape Sequences**
+
+During an active ``rnsh`` session, the following escape sequences are
+available. These are only recognised immediately after a newline character:
+
+- ``~~`` - Send a literal tilde character
+- ``~.`` - Terminate the session and exit immediately
+- ``~L`` - Toggle line-interactive mode
+- ``~?`` - Display the escape sequence quick reference
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnsh [-h] [--config CONFIG] [--identity IDENTITY] [-v] [-q] [-p]
+              [--version] [-l] [-s SERVICE] [-b PERIOD] [-a HASH] [-n] [-A] [-C]
+              [-N] [-m] [-w SECONDS]
+              [destination]
+
+  Reticulum Remote Shell Utility
+
+  positional arguments:
+    destination           hexadecimal hash of the destination to connect to
+
+  options:
+    -h, --help            show this help message and exit
+    --config, -c CONFIG   path to alternative Reticulum config directory
+    --identity, -i IDENTITY
+                          path to identity file to use
+    -v, --verbose         increase verbosity
+    -q, --quiet           decrease verbosity
+    -p, --print-identity  print identity and destination info and exit
+    --version             show program's version number and exit
+    -l, --listen          listen (server) mode; any command specified after --
+                          will be used as the default command when the initiator
+                          does not provide one or when remote command execution
+                          is disabled; if no command is specified, the default
+                          shell of the user running rnsh will be used
+    -s, --service SERVICE
+                          service name for identity file if not the default
+    -b, --announce PERIOD
+                          announce on startup and every PERIOD seconds; specify
+                          0 to announce on startup only
+    -a, --allowed HASH    allow this identity to connect (may be specified
+                          multiple times); allowed identities can also be
+                          specified in ~/.rnsh/allowed_identities or
+                          ~/.config/rnsh/allowed_identities, one hash per line
+    -n, --no-auth         disable authentication (allow any identity to connect)
+    -A, --remote-command-as-args
+                          concatenate remote command to the argument list of the
+                          default program or shell
+    -C, --no-remote-command
+                          disable executing command lines received from the
+                          remote initiator
+    -N, --no-id           disable identity announcement on connect
+    -m, --mirror          return with the exit code of the remote process
+    -w, --timeout SECONDS
+                          connect and request timeout in seconds
+
+  When specifying a command to execute, separate rnsh options from the command
+  and its arguments with --. For example:
+
+    rnsh -l -- /bin/bash --login
+    rnsh <destination> -- ls -la /tmp
+
+
 The rnodeconf Utility
 =====================
 
@@ -755,31 +1172,36 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
     -i, --info            Show device info
     -a, --autoinstall     Automatic installation on various supported devices
     -u, --update          Update firmware to the latest version
-    -U, --force-update    Update to specified firmware even if version matches
-                          or is older than installed version
-    --fw-version version  Use a specific firmware version for update or
-                          autoinstall
+    -U, --force-update    Update to specified firmware even if version matches or is older than installed version
+    --fw-version version  Use a specific firmware version for update or autoinstall
     --fw-url url          Use an alternate firmware download URL
     --nocheck             Don't check for firmware updates online
     -e, --extract         Extract firmware from connected RNode for later use
-    -E, --use-extracted   Use the extracted firmware for autoinstallation or
-                          update
+    -E, --use-extracted   Use the extracted firmware for autoinstallation or update
     -C, --clear-cache     Clear locally cached firmware files
     --baud-flash baud_flash
-                          Set specific baud rate when flashing device. Default
-                          is 921600
+                          Set specific baud rate when flashing device. Default is 921600
     -N, --normal          Switch device to normal mode
     -T, --tnc             Switch device to TNC mode
     -b, --bluetooth-on    Turn device bluetooth on
     -B, --bluetooth-off   Turn device bluetooth off
     -p, --bluetooth-pair  Put device into bluetooth pairing mode
-    -D i, --display i     Set display intensity (0-255)
+    -D, --display i       Set display intensity (0-255)
+    -t, --timeout s       Set display timeout in seconds, 0 to disable
+    -R, --rotation rotation
+                          Set display rotation, valid values are 0 through 3
     --display-addr byte   Set display address as hex byte (00 - FF)
+    --recondition-display
+                          Start display reconditioning
+    --np i                Set NeoPixel intensity (0-255)
     --freq Hz             Frequency in Hz for TNC mode
     --bw Hz               Bandwidth in Hz for TNC mode
     --txp dBm             TX power in dBm for TNC mode
     --sf factor           Spreading factor for TNC mode (7 - 12)
     --cr rate             Coding rate for TNC mode (5 - 8)
+    -x, --ia-enable       Enable interference avoidance
+    -X, --ia-disable      Disable interference avoidance
+    -c, --config          Print device configuration
     --eeprom-backup       Backup EEPROM to file
     --eeprom-dump         Dump EEPROM to console
     --eeprom-wipe         Unlock and wipe EEPROM
@@ -790,8 +1212,8 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
     -r, --rom             Bootstrap EEPROM without flashing firmware
     -k, --key             Generate a new signing key and exit
     -S, --sign            Display public part of signing key
-    -H FIRMWARE_HASH, --firmware-hash FIRMWARE_HASH
-                          Display installed firmware hash
+    -H, --firmware-hash FIRMWARE_HASH
+                          Set installed firmware hash
     --platform platform   Platform specification for device bootstrap
     --product product     Product specification for device bootstrap
     --model model         Model code for device bootstrap
@@ -801,6 +1223,104 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
 For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>`
 section of this manual.
 
+.. _using-interface_discovery:
+Discovering Interfaces
+----------------------
+
+Reticulum includes built-in functionality for discovering connectable interfaces over Reticulum itself. This is particularly useful in situations where you want to do one or more of the following:
+
+* Discover connectable entrypoints available on the Internet
+* Find connectable radio access points in the physical world
+* Maintain connectivity to RNS instances with unknown or changing IP addresses
+
+Discovered interfaces can be **auto-connected** by Reticulum, which makes it possible to create setups where an arbitrary interface can act simply as a bootstrap connection, that can be torn down again once more suitable interfaces have been discovered and connected.
+
+The interface discovery mechanism uses announces sent over Reticulum itself, and supports both publicly readable interfaces and private, encrypted discovery, that can only be decoded by specified *network identities*. It is also possible to specify which network identities should be considered valid sources for discovered interfaces, so that interfaces published by unknown entities are ignored.
+
+.. note::
+  A *network identity* is a normal Reticulum identity keyset that can be used by
+  one or more transport nodes to identify them as belonging to the same overall
+  network. In the context of interface discovery, this makes it easy to manage
+  connecting to only the particular networks you care about, even if those networks
+  utilize many individual physical transport node.
+
+  This also makes it convenient to auto-connect discovered interfaces only for networks you have some level of trust in.
+
+For information on how to make your interfaces discoverable, see the :ref:`Discoverable Interfaces<interfaces-discoverable>` chapter of this manual. The current section will focus on how to actually *discover and connect to* interfaces available on the network.
+
+In its most basic form, enabling interface discovery is as simple as setting ``discover_interfaces`` to ``true`` in your Reticulum config:
+
+.. code:: text
+  
+  [reticulum]
+  ...
+  discover_interfaces = yes
+  ...
+
+Once this option is enabled, your RNS instance will start listening for interface discovery announces, and store them for later use or inspection. You can list discovered interfaces with the ``rnstatus`` utility:
+
+.. code:: text
+
+  $ rnstatus -d
+  
+  Name           Type      Status       Last Heard   Value  Location       
+  -------------------------------------------------------------------------
+  Sideband Hub   Backbone  ✓ Available  1h  ago      16     46.2316, 6.0536
+  RNS Amsterdam  Backbone  ✓ Available  32m ago      16     52.3865, 4.9037
+
+
+You can view more detailed information about discovered interfaces, including configuration snippets for pasting directly into your ``[interfaces]`` config, by using the ``rnstatus -D`` option:
+
+.. code:: text
+  
+  $ rnstatus -D sideband
+
+  Transport ID : 521c87a83afb8f29e4455e77930b973b
+  Name         : Sideband Hub
+  Type         : BackboneInterface
+  Status       : Available
+  Transport    : Enabled
+  Distance     : 2 hops
+  Discovered   : 9h and 40m ago
+  Last Heard   : 1h and 15m ago
+  Location     : 46.2316, 6.0536
+  Address      : sideband.connect.reticulum.network:7822
+  Stamp Value  : 16
+
+  Configuration Entry:
+    [[Sideband Hub]]
+      type = BackboneInterface
+      enabled = yes
+      remote = sideband.connect.reticulum.network
+      target_port = 7822
+      transport_identity = 521c87a83afb8f29e4455e77930b973b
+
+In addition to providing local interface discovery information and control, the ``rnstatus`` utility can export discovered interface data in machine-readable JSON format using the ``rnstatus -d --json`` option. This can be useful for exporting the data to external applications such as status pages, access point maps and similar.
+
+To control what sources are considered valid for discovered sources, additional
+configuration options can be specified for the interface discovery system.
+
+* The ``interface_discovery_sources`` option is a list of the network or transport identities from which interfaces will be accepted. If this option is set, all others will be ignored. If this option is not set, discovered interfaces will be accepted from any source, but are still subject to stamp value requirements.
+
+* The ``required_discovery_value`` options specifies the minimum stamp value required for the interface announce to be considered valid. To make it computationally difficult to spam the network with a large number of defunct or malicious interfaces, each announced interface requires a valid cryptographical stamp, of configurable difficulty value.
+
+* The ``autoconnect_discovered_interfaces`` value defaults to ``0``, and specifies the maximum number of discovered interfaces that should be auto-connected at any given time. If set to a number greater than ``0``, Reticulum automatically manages discovered interface connections, and will bring discovered interfaces up and down based on availability. You can at any time add discovered interfaces to your configuration manually, to persistently keep them available.
+
+* The ``network_identity`` option specifies the *network identity* for this RNS instance. This identity is used both to sign (and potentially encrypt) *outgoing* interface discovery announces, and to decrypt incoming discovery information.
+
+The configuration snippet below contains an example of setting these additional configuration options:
+
+.. code:: text
+  
+  [reticulum]
+  ...
+  discover_interfaces = yes
+  interface_discovery_sources = 521c87a83afb8f29e4455e77930b973b
+  required_discovery_value = 16
+  autoconnect_discovered_interfaces = 3
+  network_identity = ~/.reticulum/storage/identities/my_network
+  ...
+
 Remote Management
 -----------------
 
@@ -826,6 +1346,130 @@ in the Reticulum configuration file:
 
 For a complete example configuration, you can run ``rnsd --exampleconfig``.
 
+.. _using-blackhole_management:
+
+Blackhole Management
+--------------------
+
+Reticulum networks are fundamentally permissionless and open, allowing anyone with a compatible interface to participate. While this openness is essential for a resilient and decentralized network, it also exposes the network to potential abuse, such as peers flooding the network with excessive announce broadcasts or other forms of resource exhaustion.
+
+The **Blackhole** system provides tools to help manage this problem. It allows operators and individual users to block specific identities at the Transport layer, preventing them from propagating announces through your node, and for other nodes to reach them through your network.
+
+.. important::
+  
+  There is fundamentally **no way** to *globally* block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity *on your own network segments only*.
+
+  This provides users and operators with control over what they want to allow *on their own network segments*, but there is no way to globally censor or remove an identity, as long as *someone* is willing to provide transport for it.
+
+This functionality serves a dual purpose:
+
+*   **For Individual Users:** It offers a simple way to maintain a quiet and efficient local network by manually blocking spammy or unwanted peers.
+*   **For Network Operators:** It enables the creation of federated, community-wide security standards. By publishing and sharing blackhole lists, operators can protect large infrastructures and distribute spam filtering rules across the mesh without manual intervention.
+
+
+Local Blackhole Management
+==========================
+
+The most immediate way to manage unwanted identities is through manual configuration using the ``rnpath`` utility. This allows you to instantly block or unblock specific identities on your local Transport Instance.
+
+**Blackholing an Identity**
+
+To block an identity, use the ``-B`` (or ``--blackhole``) flag followed by the identity hash. You can optionally specify a duration and a reason, which are useful for logging and future reference.
+
+.. code:: text
+
+  $ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o
+
+You can also add a duration (in hours) and a reason:
+
+.. code:: text
+
+  $ rnpath -B 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o --duration 24 --reason "Excessive announces"
+
+**Lifting Blackholes**
+
+To remove an identity from the blackhole, use the ``-U`` (or ``--unblackhole``) flag:
+
+.. code:: text
+
+  $ rnpath -U 3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o
+
+**Viewing the Blackhole List**
+
+To see all identities currently blackholed on your local instance, use the ``-b`` (or ``--blackholed``) flag:
+
+.. code:: text
+
+  $ rnpath -b
+
+  <3a4f8b9c1d2e3f4g5h6i7j8k9l0m1n2o> blackholed for 23h, 56m (Excessive announces)
+  <399ea050ce0eed1816c300bcb0840938> blackholed indefinitely (Announce spam)
+  <d56a4fa02c0a77b3575935aedd90bdb2> blackholed indefinitely (Announce spam)
+  <2b9ec651326d9bc274119054c70fb75e> blackholed indefinitely (Announce spam)
+  <1178a8f1fad405bf2ad153bf5036bdfd> blackholed indefinitely (Announce spam)
+
+
+
+Automated List Sourcing
+=======================
+
+Manually blocking identities is effective for immediate threats, but maintaining an up-to-date blocklist for a large network is impractical. Reticulum supports **automated list sourcing**, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.
+
+.. warning::
+   **Verify Before Subscribing!** Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.
+
+When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides "set-and-forget" protection for both individual users and large networks.
+
+**Configuration**
+
+To enable automated sourcing, add the ``blackhole_sources`` option to the ``[reticulum]`` section of your configuration file. This option accepts a comma-separated list of Transport Identity hashes that you trust to provide valid blackhole lists.
+
+.. code:: ini
+
+  [reticulum]
+  ...
+  # Automatically fetch blackhole lists from these trusted sources
+  blackhole_sources = 521c87a83afb8f29e4455e77930b973b, 68a4aa91ac350c4087564e8a69f84e86
+  ...
+
+**How It Works**
+
+1.  When enabled, the ``BlackholeUpdater`` service runs in the background.
+2.  For every identity hash listed in ``blackhole_sources``, it attempts to establish a temporary link to its associated``rnstransport.info.blackhole`` destination.
+3.  It requests the ``/list`` path, which returns a dictionary of blackholed identities and their associated metadata.
+4.  The received list is merged with your local ``blackholed_identities`` database.
+5.  The lists are persisted to disk, ensuring they survive restarts.
+
+.. note::
+  You can verify the external lists you are subscribed to, and their contents, without importing them by using ``rnpath -p``. See the :ref:`rnpath utility documentation<utility-rnpath>` for details on querying remote blackhole lists.
+
+
+Publishing Blackhole Lists
+==========================
+
+If you are operating a public gateway, a community hub, or simply wish to share your blackhole list with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to *your* definitions of unwanted traffic.
+
+**Enabling Publishing**
+
+To publish your local blackhole list, enable the ``publish_blackhole`` option in the ``[reticulum]`` section:
+
+.. code:: ini
+
+  [reticulum]
+  ...
+  publish_blackhole = yes
+  ...
+
+When this is enabled, your Transport Instance will register a request handler at ``rnstransport.info.blackhole``. Any peer that connects to this destination and requests ``/list`` will receive the complete set of identities currently present in your local blackhole database.
+
+**Federation and Trust**
+
+The blackhole system relies on the trust relationship between the subscriber and the publisher. By subscribing to a source, you are implicitly trusting that source to only block identities that are genuinely detrimental to the network.
+
+As the ecosystem matures, this system is designed to integrate with **Network Identities**. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.
+
+For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.
+
 Improving System Configuration
 ------------------------------
 

docs/manual/_sources/whatis.rst.txt

@@ -6,6 +6,9 @@ Reticulum is a cryptography-based networking stack for building both local and
 wide-area networks with readily available hardware, that can continue to operate
 under adverse conditions, such as extremely low bandwidth and very high latency.
 
+To understand the foundational philosophy and goals of this system, read the
+:ref:`Zen of Reticulum <zen>`.
+
 Reticulum allows you to build wide-area networks with off-the-shelf tools, and
 offers end-to-end encryption, forward secrecy, autoconfiguring cryptographically
 backed multi-hop transport, efficient addressing, unforgeable packet
@@ -40,6 +43,22 @@ real-world use is explored. The API and wire-format can be considered complete a
 could change if absolutely warranted.
 
 
+Reference Implementation
+========================
+The Python code, for which this documentation is written, and known as the Reticulum Network Stack,
+is the Reference Implementation of Reticulum. The Reticulum Protocol is defined entirely
+and authoritatively by this reference implementation, and this manual. It is maintained by Mark Qvist,
+identified by the Reticulum Identity ``<bc7291552be7a58f361522990465165c>``.
+
+Compatibility with the Reticulum Protocol is defined as having full interoperability,
+and sufficient functional parity with this reference implementation. Any specific protocol
+implementation that achieves this is Reticulum. Any that does not is not Reticulum.
+
+The reference implementation is licensed under the :ref:`Reticulum License <license>`.
+
+The Reticulum Protocol was dedicated to the Public Domain in 2016.
+
+
 What does Reticulum Offer?
 ==========================
 
@@ -178,14 +197,7 @@ Reticulum implements a range of generalised interface types that covers the comm
 
   * Or to quickly create interfaces with custom hardware
 
+* Anything else using :ref:`custom interface modules<interfaces-custom>` written in Python
+
 For a full list and more details, see the :ref:`Supported Interfaces<interfaces-main>` chapter.
 
-
-Caveat Emptor
-==============
-Reticulum is an experimental networking stack, and should be considered as
-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.

docs/manual/_sources/zen.rst.txt

@@ -0,0 +1,453 @@
+.. _zen:
+
+****************
+Zen of Reticulum
+****************
+
+The Illusion Of The Center
+==========================
+
+For the better part of a generation, we have been taught to visualize the digital world through the lens of hierarchy. The mental maps we carry are dominated by a single, misleading image: **The Cloud**.
+
+We imagine the network as a vast, ethereal space "up there" or "out there". A centralized repository of services and data to which we, the lowly clients, must connect. We build our software with this assumption hardcoded into our logic: *There is a server. The server has the authority. The server knows the way. I must find the server to function*.
+
+This is the Client-Server mental model, and it is the primary obstacle to understanding Reticulum.
+
+Fallacy Of The Cloud
+--------------------
+
+The first step in the Zen of Reticulum is to realize that *there is no cloud*. There is only other people's computers. When you build for the cloud, you are building *for* a landlord. You are accepting that your application's existence is conditional on the permission, uptime, and continued goodwill of a central authority.
+
+In Reticulum, you must shift your thinking from "connecting to" to "being among". Reticulum is not a service you subscribe to - *it is a fabric you inhabit*. There is no "up there". There is only *here* and *there*, and the space between them is peer-to-peer.
+
+Decentralization Or Uncentralizability?
+---------------------------------------
+
+It is common to hear the word "decentralized" thrown around in modern tech circles. But often, this is merely a marketing term for "slightly distributed centralization". A blockchain with a few dominant miners, or a federated protocol with a few giant servers. *In practice*, it's still centralized. It simply has a few centers instead of one.
+
+Reticulum goes further. It wants **Uncentralizability**.
+
+This is not a wishful political stance, but a foundational mathematical characteristic of the protocol, onto which everything else has been built. Reticulum assumes that every peer on the network is potentially hostile, and every link is potentially compromised. It is designed with no "privileged" nodes. While some nodes may act as Transport Instances - forwarding traffic for others - they do so *blindly*, and they only know about their immediate surroundings, and nothing more. They route based on cryptographic proofs, not on administrative privilege. They cannot see who is talking to whom, nor can they selectively manipulate traffic without breaking their own ability to route entirely.
+
+The system is designed to make hierarchy structurally impossible. You cannot hijack an address, because there is no central registry to hijack. You cannot block a user, because there is no central switch to flip. You can offer paths through the network, but you can't force anyone to use them.
+
+Death To The Address
+--------------------
+
+To break free of the center, you must also let go of the concept of the "Address".
+
+In the IP world, an address is a location. It is a coordinate in a *deeply hierarchical* and static grid. If you move your computer to a different house, your address changes. If your router reboots, your address might change. Your *identity* is bound to your *location*, and therefore, it is fragile, and easily controlled.
+
+Reticulum abolishes this link between *Identity* and *Location*.
+
+In Reticulum, an address is not a place; it is a **Hash of an Identity**. It is a cryptographic representation of *who* you are, not *where* you are. Because of this, your address is portable. You can take a laptop from a WiFi cafe in Berlin, to a LoRa mesh in the mountains, to a packet radio link on a boat, and your "address" - your *Destination Hash* - never changes.
+
+The network does not route to a place; it routes to a *person* (or a machine). When you send a packet, you are not targeting a coordinate in a grid; you are encrypting a message for a specific entity. The network dynamically discovers where that entity currently resides, and it does so in a way where no one really knows where that entity is actually located physically.
+
+**Consider:**
+
+- **The Old Way:** *"I am at* ``192.168.1.5``. *Come find me"*.
+- **The Zen Way:** *"I am* ``<327c1b2f87c9353e01769b01090b18f2>``. *Wherever I am, my peers can reach me"*.
+
+Once you stop thinking about servers and start thinking about portable identities, where everyone can always reach everyone else directly, the illusion of the center fades away. You realize there *is* no center holding the network together. No coordinators or bureaucrats required. The network is simply the sum of its peers, communicating directly, sovereignly, and without a master.
+
+
+Physics Of Trust
+================
+*Paranoia Is A Great Design Principle*
+
+If we accept that there is no center - that the network is a chaotic, peer-to-peer mesh - we are forced to confront a terrifying reality: **There is no one guarding the door**.
+
+In the traditional networking mindset, we rely on the concept of the "trusted core". We assume our local coffee shop WiFi is safe, or that the backbone providers are neutral custodians. We build our security like a castle: strong walls on the outside, soft and trusting on the inside. We use encryption only when we step out into the "wild" internet.
+
+Hostile Environments
+--------------------
+
+The Zen of Reticulum requires you to invert this. You must assume that *every* environment is hostile. This isn't cynicism, just uncaring physics.
+
+When you transmit information over radio waves, you are shouting into a crowded room. Anyone can listen. When you traverse the internet, your packets pass through routers controlled by strangers, corporations, and state actors. Assuming privacy in this environment without cryptographic protection is not optimism but gross negligence.
+
+Reticulum is built on the premise that every link is tapped, and every peer is a potential adversary. If your system cannot survive an adversary owning the physical layer, it cannot survive at all.
+
+But this is the paradox: By assuming the network is hostile, you make it safe. When you accept the dangers for what they are, they become manageable. When you stop trusting the infrastructure and start trusting the math, you eliminate the single point of failure: Human integrity.
+
+Encryption Is Not A Feature
+---------------------------
+
+In the world of TCP/IP, encryption is an afterthought. It is a layer we slap on top of the protocol (HTTPS, TLS) to patch the security holes of the original design. It is a "feature" you sometimes *enable* for "sensitive data". This is fundamentally flawed, since all data is sensitive.
+
+In Reticulum, encryption is **gravity**.
+
+It is not optional. It is not a plugin. It is the *fundamental force that allows the network to exist*. If you were to strip the encryption from Reticulum, the routing would break. The Transport system uses cryptographic signatures and entropy to verify paths and pass information. If packets were plaintext, intermediate nodes could not prove that a route was valid, nor could endpoints prevent spoofing or tampering.
+
+In Reticulum, the entropy of the encrypted packet *is* the routing logic.
+
+To ask for a version of Reticulum without encryption is like asking for a version of the ocean without liquid. You are not asking for a feature change; you're asking for a different physical universe. We design for a universe where information has mass, structure, and integrity.
+
+Zero-Trust Architectures
+------------------------
+
+We must unlearn our reliance on **Institutional Trust**.
+
+For decades, we have been trained to trust authorities. We trust a website because a chain of Certificate Authorities (companies we don't know) vouches for it. We trust an app because it is in an app store (run by a corporation we don't control). We trust a message because it comes from a phone number assigned by a telecom. Yet, everything in our digital information sphere today is more untrustworthy and risky than a medieval second-hand underwear market.
+
+Reticulum replaces institutional trust with **Cryptographic Proof**.
+
+In Reticulum, you do not trust a node because it has a nice hostname or because it is listed in a directory. You trust it because it holds the private key corresponding to the Destination Hash you are communicating with. This trust is binary, mathematical, and **absolute**. Either the signature matches, or it does not. There is no "maybe".
+
+This shift moves the power from the institution to the individual. You become the ultimate arbiter of your own trust relationships. You decide which keys to accept, which paths to follow, and which identities to recognize.
+
+**Consider:**
+
+- **The Old Way:** *"I trust this site because the browser says the lock icon is green"*.
+- **The Zen Way:** *"I trust this destination because I have verified its hash fingerprint out-of-band, and the math confirms the signature"*.
+
+When you internalize the Physics of Trust, you stop looking for protection from firewalls, VPNs, and Terms of Service agreements. You realize that true security comes from the design of the protocol itself. You can stop trusting the cloud, and you start trusting the code - because you can verify it yourself.
+
+
+Merits Of Scarcity
+==================
+*Every Bit Counts*
+
+We have grown addicted to abundance. In the modern digital ecosystem, bandwidth is treated as an endless, flat ocean. We stream high-definition video without a thought, we ship entire libraries of code just to render a single button, and we measure performance in gigabits per second. This abundance has hollowed out our craft. When constraints vanish, efficiency dies, and with it, a certain kind of Clarity and Quality.
+
+Reticulum asks you to step out of the ocean and onto the tightrope.
+
+The Bandwidth Fallacy
+---------------------
+
+The Zen of Reticulum requires the realization that **5 bits per second is a valid speed**.
+
+To a modern developer, this sounds like paralysis. But there is a profound freedom in limits: When you have a gigabit connection, you can be incredibly sloppy. You can be wasteful. You can push your problems onto the infrastructure. *"It’s slow? Get a faster router"*.
+
+But on a high-latency, low-bandwidth link (be it a noisy HF radio channel or a tenuous LoRa hop) you cannot push problems anywhere. You must solve them. The network does not negotiate with waste.
+
+This forces a shift from consumption to interaction. You are no longer, then, consuming a service provided by a fat pipe; you are engaging in a careful negotiation with the physical medium. The medium becomes a partner in the conversation, not just a dumb conduit. You suddenly need to *understand the world to be in it*.
+
+Cost Of A Byte
+--------------
+
+In a scarce economy, a byte is not just data, but energy, time, and space.
+
+Every byte you transmit consumes battery life on a solar-powered node. It occupies valuable airtime that could have been used by another peer. It represents a measurable slice of the electromagnetic spectrum.
+
+When you internalize this, you begin to write code differently. You stop asking, "How much data can I send?" and start asking, "What is the *minimum* amount of information required to convey this intent? How can I best utilize my informational entropy?"
+
+This is where the elegance of Reticulum shines. The protocol is designed to strip away the non-essential. A link establishment takes three very small packets. A destination hash fits in 16 bytes. The overhead is vanishingly small, leaving almost the entire channel for the message itself.
+
+**Consider:**
+
+- **The Old Way:** *"I need to send a status update. I'll send a JSON object with metadata, timestamps, and user profile info (15KB)."*
+- **The Zen Way:** *"I need to send a status update. I'll send a single byte representing the state code. The context is already known."*
+
+This is of course optimization, but more importantly, *it is a form of respect*. Efficiency in a shared medium is an act of stewardship. By taking only what you need from the network, you leave room for others. The network listens to those who speak with purpose.
+
+Flow & Time
+-----------
+
+Scarcity also teaches us about time. We have become addicted to the *synchronous* now - the instant ping, the real-time stream. But Reticulum embraces *asynchronous* time.
+
+When links are intermittent and latency is measured in minutes or hours, "real-time" is an illusion. Reticulum doesn't encourage **Store and Forward** as a mere fallback, but as a primary mode of existence. You write a message, it propagates when it can, and it arrives when it arrives.
+
+This changes the psychological texture of communication. It removes the anxiety of the immediate response. It allows for contemplation. You are not demanding the recipient's attention *right now*; you are placing a gift in their path, to be found when they are ready.
+
+By designing for delay, you design for resilience. You are no longer building a house of cards that collapses when a single packet drops. You are building a stone arch that distributes the load *over time*.
+
+Liberation From Limits
+----------------------
+
+There is a strange optimism in scarcity. When you are forced to work within strict constraints, you are forced to prioritize. *You* must decide what truly matters. *That* is the real core of agency.
+
+In the infinite fantasy world of The Cloud, everything is urgent, so nothing is. In the economy of Reticulum, the cost of transmission forces you to weigh the value of your message. Do you really need to send that heart beat? Is that photo essential?
+
+When you strip away the noise, what remains is *signal*.
+
+This discipline creates a different kind of developer. It creates a craftsman who understands that the best code is the code you don't have to write. It creates a user who understands that the most powerful message is the one that is *understood*, not the one that is loudest. In the world of Reticulum, you are not a mere consumer of bandwidth; you are an architect of intent.
+
+
+Sovereignty Through Infrastructure
+==================================
+**Be Your Own Network**
+
+We live in an era of digital tenancy. We lease our connectivity from ISPs. We rent our storage from cloud providers. We even borrow our identity from social media platforms. We are tenants in a house we did not build, governed by rules we did not write, subject to eviction at the whim of a landlord who has never met us.
+
+The Zen of Reticulum is the realization that you *can* own the house.
+
+A Carrier-Grade Fallacy
+-----------------------
+
+For decades, we have been gaslit into believing that networking is really not just hard, but impossible. It is presented as a dark art reserved for telcos and billionaires, requiring millions of dollars of fiber optics, climate-controlled data centers, and armies of engineers. We are told that building reliable infrastructure is "too complex" for the individual or small organization.
+
+This is a big, fat lie.
+
+Physics is simple. A radio wave needs a transmitter and a receiver. A packet needs a path. The "complexity" of the modern internet is largely bureaucratic - a mountain of billing systems, regulatory capture, and legacy cruft designed to keep the gatekeepers in power.
+
+Reticulum strips away the bureaucracy. It runs on hardware that costs the price of a dinner. It runs on spectrum that is free to use. It demonstrates that a robust, planetary-scale network does not require a Fortune 500 company. It requires only the will to deploy, and the distributed, uncoordinated efforts of many individuals.
+
+Personal Infrastructure
+-----------------------
+
+This is where the rubber meets the road. You can read about Reticulum, you can understand the theory, but the insights only arrive when you plug in a radio and run a Transport Node. Suddenly, you are no longer a consumer. You're an operator.
+
+This shift is subtle but profound. When you run your own infrastructure, the network ceases to be a service that is provided *to* you. It becomes a space that you *inhabit*. You become responsible for the flow of information. You gain an intimate understanding of the medium - the way the weather affects the radio waves, the way the topology changes, the way the packets dance through the ether.
+
+There is a quiet competence that comes from this. You stop asking "Is the internet down?" and start asking "Is *my* links up?" You stop waiting for a technician and start checking the logs. This is a form of strength. To understand the system that carries your words is to be free from the mystery that keeps you dependent.
+
+The Ability To Disconnect
+-------------------------
+
+Why go to the trouble? Why buy the radio, write the config, and leave the Pi running in the corner?
+
+Because the old, centralized network is fragile. And because most of us doesn't even really want to be there anymore.
+
+The internet we rely on today is a chain of single points of failure. Cut the undersea cable, and a continent goes dark. Shut down the power grid, and the cloud evaporates. Deprioritize the "wrong" traffic, and the flow of information is strangled.
+
+Sovereignty is the ability to survive the cut, whether or not that cut was an accident or on purpose.
+
+When you build your own infrastructure, you build a lifeline. Reticulum is designed to function over media that the traditional internet cannot touch - bare wires, battery-powered radios, ad-hoc WiFi meshes. When the grid fails, or the censors arrive, or the bill goes unpaid, your Reticulum network continues to hum.
+
+This is not about "dropping out" of society. It is about building a substrate on which an actual *Society* can function.
+
+**Consider:**
+
+- **The Old Way:** "My connection is slow. I should call my ISP and complain."
+- **The Zen Way:** "The path is noisy. I will adjust the antenna or find a better route."
+
+By taking ownership of the infrastructure, you take ownership of your voice. You stop shouting into someone else's megaphone and start building your own. The network is no longer something that happens to you; it is something you make happen.
+
+
+Identity and Nomadism
+=====================
+**A Fluid Self**
+
+In the old world, you are defined by your coordinates. If you are at ``34.109.71.5``, you're *here*. If you unplug the cable and walk down the street, you vanish. Your digital self evaporates because it was tethered to the wall. You are a ghost in the endless machinations of gears, levers and transistors, bound to the hardware, and those that own it.
+
+This creates a subtle, constant anxiety. We are terrified of disconnecting because, in the architecture of the old web, disconnecting is a kind of death.
+
+The Zen of Reticulum offers a different way to be.
+
+Portable Existence
+------------------
+
+In Reticulum, your identity is not a location, or a username granted by a service. It is a cryptographic key - a complex, unique mathematical signature that exists independently of the physical world. You can carry it only in your mind, if you want to.
+
+Think of it less like a street address and more like a name. *A true name*.
+
+If you travel from Berlin to Tokyo, you do not change your name. You are still you. The people who know you can still recognize you. Reticulum applies this principle to the network layer. Your Destination Hash is **invariant**. It travels with you, stored securely on your device, *immutable as a stone*.
+
+This changes the relationship between you and the machine. You are not "logged into" the network via a specific gateway. You *are* the endpoint. The network does not connect to a place; *it converges on you*.
+
+Roaming Nodes
+-------------
+
+This freedom introduces a new concept of time and space: **Nomadism**.
+
+Because your identity is portable, your connectivity can be fluid. You can be sitting at a desk connected to a fiber backbone one moment, and walking through a field connected only to a long-range LoRa mesh the next. To the rest of the network, nothing has changed. Your friends do not need to update your contact info. The messages they send do not bounce back. The network senses the shift in the medium and reroutes the flow of data automatically.
+
+You are no longer a stationary node in a fixed grid. You are a wanderer in a fluid medium.
+
+The interfaces - whether it is WiFi, Ethernet, Packet Radio, or a physical wire - is merely the clothing your node wears. You change it to suit the environment. Underneath, you remain the same. This is the liberation of the protocol. It treats the physical medium as a transient circumstance, not a definition of self.
+
+**Consider:**
+
+- **The Old Way:** *"I lost connection. I have to reconnect to the VPN to tell them where I am now."*
+- **The Zen Way:** *"I moved. The network subtly bends to accomodate this new reality."*
+
+Announcing Presence
+-------------------
+
+How does the network find a wanderer? It listens.
+
+In the IP world, we query directories. We ask a server, "Where is Mark?" The server checks its database and gives us a coordinate. This means that someone, somewhere, is keeping track of you. It assumes and *requires* surveillance.
+
+Reticulum replaces surveillance with **Announces**.
+
+Instead of asking a central authority where you are, you simply state your presence. You broadcast a cryptographic proof: "I am here, and I am who I say I am". This ripples out through the mesh. Your neighbors hear it, update their path tables, and pass it on.
+
+This is a quiet, organic process. It is the digital equivalent of lighting lanterns in the dark. You do not need to chase the light; you let the light find you. It respects your autonomy. You choose when to announce, how often to speak, and to whom. You also choose when to disappear - for but a moment or perpetually.
+
+Anchor In The Flow
+------------------
+
+There is a deep peace in this nomadism. It teaches you that stability does not come from standing still. Stability comes from *internal coherence*.
+
+By holding your own private key, you hold your own center of gravity. The world around you; the infrastructure, the topography and the availability of links can all shift chaotically. Storms can knock out towers. Cables can be cut. The internet can go down.
+
+But as long as you possess your key, you possess your identity. The entire infrastructure can be destroyed and rebuilt, and you are still you. Nothing lasts, yet nothing is lost.
+
+You become a sovereign entity moving through the noise, connected not by the rigidity of cables, but by the fluidity of recognition. The network becomes a place you inhabit, rather than a utility you subscribe to: You are at home in the ether.
+
+
+Ethics Of The Tool
+==================
+**Technology With Conscience**
+
+You have unlearned the center. You have accepted the physics of trust. You have embraced the economy of scarcity and the freedom of unbound nomadism. You are standing in a new space. Now, look at the tool in your hand.
+
+In the old world, we were taught that technology is neutral. We are told that "guns don't kill people, people do", or that a component is just a component, indifferent to what its combinatorial potential is. This is a convenient lie. It serves only to allow the builders to wash their hands of responsibility.
+
+But we know better now. We know that **architecture is politics**, and *politics is control*. The way you build a system determines how it will be used. If you build a system optimized for mass surveillance, you *will* get a panopticon. If you build a system optimized for centralized control, you *will* get a dictatorship. If you build a system optimized for extraction, you *will* get a parasite.
+
+The Zen of Reticulum asserts that a tool is never neutral.
+
+On the very contrary: A tool is intent, **crystallized**.
+
+The Harm Principle
+------------------
+
+Why does the Reticulum License forbid the software from being used in systems designed to harm humans? Is it not just a restriction on freedom?
+
+It is a restriction on *license*, yes, but it is an expansion of *freedom*.
+
+Building powerful tools without a moral compass is in no way virtuous or commendable, it is plain and simple irresponsibility.
+
+A tool that can easily be used to oppress is a real danger to the user. If you build a network that can be turned against you by a tyrant, you are not free. You are merely waiting for the leash to tighten. By encoding the "Harm Principle" into the legal DNA of the reference implementation, we are building a safeguard. We are stating, clearly and immutably, that *this tool* is for **life**, not for death.
+
+This aligns the software with the interests of humanity. It cements that the network cannot be conscripted into a kill-system, a weaponized drone controller, or a torture device without breaking the license and the law. It is a line drawn in the sand - not by a government or external authority, but by the creators of the tool itself.
+
+**Consider:**
+
+- **The Old Way:** *"It's just software. How people use it is not my problem."*
+- **The Zen Way:** *"This software is a habitat. I will not allow it to be used to build a cage."*
+
+It is *your* choice whether to align with this - we are not forcing this stance on anyone. If you choose to align with life over death, with creativity over destruction, we grant you an immensely powerful tool, to own and build with as you please. If you do not, we deny it.
+
+If you do not like this, we most assuredly do not need you here, and you are on your own.
+
+Public Domain Protocol
+----------------------
+
+This leads to a vital distinction: The difference between the *idea* and the *implementation*.
+
+The protocol - the mathematical rules of how Reticulum works - is dedicated to the Public Domain. It belongs to humanity. **No one can own it**. Anyone can implement it, improve it, or adapt it. This is the core idea of free communication, which itself must be forever free.
+
+But the functional, deployed *reference implementation* - the Python code, the maintenance, the years of labor - has a conscience. This distinction is the engine of sustainability. It allows the protocol to be universal, while ensuring that the specific labor of the builders is not hijacked to undermine the foundational intent of the project itself. From this document, it should be very clear what this intent is.
+
+If you want to build a system with Reticulum that manipulates and damages users for profits or targets missiles, you can use the public domain protocol, and start from scratch. But you cannot take our work. You must do your own. This serves as a pillar of accountability. If you want to build a weapon, *you* go and forge the steel yourself, while the world observes. And when the blood is drawn - it is on **your** hands.
+
+Preserving Human Agency
+-----------------------
+
+We live in an era of predatory extraction. The open-source commons is being scraped, ingested, and regurgitated by machine learning algorithms, whose corporate owners seek to replace the very humans who built those commons. Our code, our words, and our creativity is being used to train systems that are specifically designed to make us obsolete, without offering anything else in return than serfdom and leashes.
+
+Reticulum stands against this.
+
+The license protects the software from being used to feed the beast. It draws a hard line: This tool is for *people*. It is for human-to-human connection. It is not a dataset to be strip-mined for the purpose of building a synthetic overlord, puppeteered by a miniscule conglomerate of controllers.
+
+This is a radical act of preservation. By protecting the code from AI appropriation, we are protecting space for human agency. We are ensuring that there remains a digital realm where the actors are flesh, blood and soul, where decisions are made by minds, not overlords hiding behind models.
+
+When you use Reticulum, you are using a tool that respects you. It does not see you as a product to be tracked. It does not see your data as fuel for an algorithm. It sees you as a sovereign, equal peer.
+
+This changes the foundational premise of using the technology. It restores dignity to the interaction. You are not the user of a service; you are a participant in a mutual covenant. The tool aligns with your autonomy, rather than eroding it.
+
+In this way, ethics is not a restriction, but a foundation. It is the foundation that helps ensure the network will still belong to you tomorrow.
+
+
+Design Patterns For Post-IP Systems
+===================================
+**Practical Philosophy for Developers**
+
+The philosophy is useless if it cannot be hammered into code. The metaphors we have explored - nomadism, scarcity, trust - are not just poetry, but real-world engineering constraints. When you sit down to write software for Reticulum, these concepts must shape the very structure of your application.
+
+We are now moving from the *why* to the *how*. This is where the abstract becomes concrete, and where you will see the true depth of the patterns we have been weaving.
+
+Store & Forward
+---------------
+
+The web has trained us to be impatient. We write synchronous code. We fire a request and we wait, blocking the UI, holding our breath. If the response doesn't come in 250 milliseconds, we show a spinner. If it doesn't come in five seconds, we show an error. We treat network connectivity as a binary state: either we are "online" or we are "broken".
+
+This is brittle. It is a rejection of reality.
+
+In Reticulum, connectivity is a spectrum, and presence is asynchronous. If at all applicable to your intent, you must design your applications to embrace **Store & Forward**.
+
+Instead of demanding an immediate answer, your application should act as a patient participant. You create a message for someone or something in the mesh. The network holds it. It carries it from node to node, perhaps over hours or days, waiting for the recipient to appear. When they finally surface, the message is delivered. This requires a shift from "request/response" to "event/handler". How exactly you do this is a challenge for you to solve intelligently within your problem domain, but Reticulum-based systems already exist that does this extremely well, and you can use them for inspiration.
+
+**Consider:**
+
+- **The Old Way:** ``Connect() -> Send() -> Wait() -> Crash if timeout.``
+- **The Zen Way:** ``Send() -> Continue living. -> Receive() when it arrives.``
+
+This changes the user experience profoundly. It removes the anxiety of the loading bar. It creates a sense of continuity. The user is not "waiting for the network"; they are interacting with a persistent log of communication that lives in the network itself.
+
+Naming Is Power
+---------------
+
+In the IP world, we are slaves to the Domain Name System. We rely on a hierarchy of registrars to map human-readable names to machine-readable addresses. This hierarchy is a choke point. If the registrar revokes your domain, or if the DNS server goes down, you vanish.
+
+Reticulum dissolves this hierarchy with **Hash-based Identity**.
+
+In this design pattern, a name is not a string you look up; it is a cryptographic destination you verify. When you design for Reticulum, you stop asking the user for a URL and start asking for a Destination or Identity Hash.
+
+This feels strange at first. A hash like ``<83b7328926fed0d2e6a10a7671f9e237>`` looks alien compared to ``myfriend.com``. But that alienness is the armor. It **cannot** be spoofed. It **cannot** be censored by a registrar. It is **absolute**.
+
+Designing for this means shifting your UI metaphors. You are no longer browsing a web of pages; you are managing a ledger of keys. You are building an "Address Book" that is actually a keyring. The names are given by the user, and the power stays with them. That hashes look complex is directly analogous to the strengths of the bonds formed by their use. It forces the user to engage in a moment of verification, an out-of-band handshake, which restores the human element of trust that SSL certificates stripped away.
+
+The Interface Is The Medium
+---------------------------
+
+One of the most liberating patterns in Reticulum is **Transport Agnosticism**.
+
+In traditional networking, your code is often littered with transport logic. "Am I on WiFi? Check bandwidth. Am I on Cellular? Check data plan. Am I on Ethernet?". You are constantly micromanaging the pipe.
+
+In Reticulum, you write to the API, and the API writes to the medium. You send a packet to a Destination. You do not care if that packet travels over a TCP tunnel, a LoRa radio wave, or a serial wire interface. That is the stack's concern.
+
+This allows you to write **Universal Applications**.
+Imagine a messaging app. You write it once. It works on a laptop connected to fiber. It works on a phone in the city using WiFi. And, without a single line of code changed, it works on a device in the wilderness, talking only to other devices via radio.
+
+The pattern is simple: **Never code to the hardware. Code to the intent.**
+
+**Consider:**
+
+- **The Old Way:** ``socket.connect(ip, port)``, and then a whole lot more
+- **The Zen Way:** ``RNS.Packet(destination, data).send()``
+
+By abstracting the medium, you make your software immortal to changes in infrastructure. The user might switch from a 4G hotspot to a HF modem tomorrow. Your software doesn't need to know. It simply continues the conversation.
+
+Emergent Patterns
+-----------------
+
+When you combine these patterns - *Store & Forward*, *Hash-based Identity*, and *Transport Agnosticism* - you create software that feels fundamentally different.
+
+It feels *grounded*. It doesn't flicker when the signal drops. It doesn't panic when the server is down. It has weight. It has persistence. It has *relevance*.
+
+You are no longer building a "client" that begs a "server" for attention. You are building an autonomous agent that exists within the mesh. It speaks when it needs to, listens when it can, and carries its identity with it wherever it goes.
+
+This is the culmination of the Zen. The code is not just a set of instructions: It is a behavioral envelope. It is a way of *being* in the network.
+
+
+Fabric Of The Independent
+=========================
+
+We have stripped away the illusions. We have seen that the center is empty, that trust *must* be hard, that resources are finite, and that we must own our infrastructure. We have seen that tools have ethics and that our identity can move fluidly.
+
+This is a reclaiming of the commons. For too long, we have allowed the most vital substrate of human society - *our ability to speak to one another* - to be colonized by entities that do not share our interests. We have allowed the architecture of our communication to be designed by accountants rather than architects.
+
+We are taking it back. Not by petitioning the masters, but by building the new world within, over, under and around the shell of the old.
+
+The Work Is Finished
+--------------------
+
+The heavy lifting is done.
+
+The protocol is in the public domain, a gift to humanity that can never be taken away. The software is written, tested, and running on devices scattered across the globe. The manual lies open before you. The source code for the reference implementation is now distributed on hundreds of thousands of devices across the planet. No one can delete or destroy it. The hardware is accessible and abundant.
+
+It was a hard road to get here, but we got here. Now, there is no roadmap committee waiting for approval. There is no venture capital dictating the user experience. There is no CEO to sign off on the next feature release.
+
+There is only you.
+
+The barrier to entry is no longer complexity: It is the mere habit of dependency. You were conditioned to wait. Wait for the app update. Wait for the ISP to fix the line. Wait for the platform to allow the post. Wait for the government to change the policies. Wait for the likes. Wait for the revolution to be televised.
+
+The revolution never was televised.
+
+It is packetized.
+
+Open Sky
+--------
+
+The future of this technology is a construction project.
+
+It looks like a single node on a windowsill, listening to the static. It looks like a message sent to a neighbor, bypassing the noise of the commercial web. It looks like a community mesh that grows, link by link, hop by hop, carried by hands that care more about connection than profit.
+
+You have the blueprints. You have the tools. You have the philosophy. The noise of the old world has fallen away, leaving you with the quiet clarity of the open spectrum.
+
+*Mark, early 2026*

docs/manual/_static/_sphinx_javascript_frameworks_compat.js

@@ -1,134 +0,0 @@
-/*
- * _sphinx_javascript_frameworks_compat.js
- * ~~~~~~~~~~
- *
- * Compatability shim for jQuery and underscores.js.
- *
- * WILL BE REMOVED IN Sphinx 6.0
- * xref RemovedInSphinx60Warning
- *
- */
-
-/**
- * select a different prefix for underscore
- */
-$u = _.noConflict();
-
-
-/**
- * small helper function to urldecode strings
- *
- * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
- */
-jQuery.urldecode = function(x) {
-    if (!x) {
-        return x
-    }
-    return decodeURIComponent(x.replace(/\+/g, ' '));
-};
-
-/**
- * small helper function to urlencode strings
- */
-jQuery.urlencode = encodeURIComponent;
-
-/**
- * This function returns the parsed url parameters of the
- * current request. Multiple values per key are supported,
- * it will always return arrays of strings for the value parts.
- */
-jQuery.getQueryParameters = function(s) {
-    if (typeof s === 'undefined')
-        s = document.location.search;
-    var parts = s.substr(s.indexOf('?') + 1).split('&');
-    var result = {};
-    for (var i = 0; i < parts.length; i++) {
-        var tmp = parts[i].split('=', 2);
-        var key = jQuery.urldecode(tmp[0]);
-        var value = jQuery.urldecode(tmp[1]);
-        if (key in result)
-            result[key].push(value);
-        else
-            result[key] = [value];
-    }
-    return result;
-};
-
-/**
- * highlight a given string on a jquery object by wrapping it in
- * span elements with the given class name.
- */
-jQuery.fn.highlightText = function(text, className) {
-    function highlight(node, addItems) {
-        if (node.nodeType === 3) {
-            var val = node.nodeValue;
-            var pos = val.toLowerCase().indexOf(text);
-            if (pos >= 0 &&
-                !jQuery(node.parentNode).hasClass(className) &&
-                !jQuery(node.parentNode).hasClass("nohighlight")) {
-                var span;
-                var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
-                if (isInSVG) {
-                    span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
-                } else {
-                    span = document.createElement("span");
-                    span.className = className;
-                }
-                span.appendChild(document.createTextNode(val.substr(pos, text.length)));
-                node.parentNode.insertBefore(span, node.parentNode.insertBefore(
-                    document.createTextNode(val.substr(pos + text.length)),
-                    node.nextSibling));
-                node.nodeValue = val.substr(0, pos);
-                if (isInSVG) {
-                    var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
-                    var bbox = node.parentElement.getBBox();
-                    rect.x.baseVal.value = bbox.x;
-                    rect.y.baseVal.value = bbox.y;
-                    rect.width.baseVal.value = bbox.width;
-                    rect.height.baseVal.value = bbox.height;
-                    rect.setAttribute('class', className);
-                    addItems.push({
-                        "parent": node.parentNode,
-                        "target": rect});
-                }
-            }
-        }
-        else if (!jQuery(node).is("button, select, textarea")) {
-            jQuery.each(node.childNodes, function() {
-                highlight(this, addItems);
-            });
-        }
-    }
-    var addItems = [];
-    var result = this.each(function() {
-        highlight(this, addItems);
-    });
-    for (var i = 0; i < addItems.length; ++i) {
-        jQuery(addItems[i].parent).before(addItems[i].target);
-    }
-    return result;
-};
-
-/*
- * backward compatibility for jQuery.browser
- * This will be supported until firefox bug is fixed.
- */
-if (!jQuery.browser) {
-    jQuery.uaMatch = function(ua) {
-        ua = ua.toLowerCase();
-
-        var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
-            /(webkit)[ \/]([\w.]+)/.exec(ua) ||
-            /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
-            /(msie) ([\w.]+)/.exec(ua) ||
-            ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
-            [];
-
-        return {
-            browser: match[ 1 ] || "",
-            version: match[ 2 ] || "0"
-        };
-    };
-    jQuery.browser = {};
-    jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
-}

docs/manual/_static/basic.css

@@ -1,12 +1,5 @@
 /*
- * basic.css
- * ~~~~~~~~~
- *
  * Sphinx stylesheet -- basic theme.
- *
- * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 /* -- main layout ----------------------------------------------------------- */
@@ -115,15 +108,11 @@ img {
 /* -- search page ----------------------------------------------------------- */
 
 ul.search {
-    margin: 10px 0 0 20px;
-    padding: 0;
+    margin-top: 10px;
 }
 
 ul.search li {
-    padding: 5px 0 5px 20px;
-    background-image: url(file.png);
-    background-repeat: no-repeat;
-    background-position: 0 7px;
+    padding: 5px 0;
 }
 
 ul.search li a {
@@ -237,6 +226,10 @@ a.headerlink {
     visibility: hidden;
 }
 
+a:visited {
+    color: #551A8B;
+}
+
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
 h3:hover > a.headerlink,
@@ -324,6 +317,7 @@ aside.sidebar {
 p.sidebar-title {
     font-weight: bold;
 }
+
 nav.contents,
 aside.topic,
 div.admonition, div.topic, blockquote {
@@ -331,6 +325,7 @@ div.admonition, div.topic, blockquote {
 }
 
 /* -- topics ---------------------------------------------------------------- */
+
 nav.contents,
 aside.topic,
 div.topic {
@@ -606,6 +601,7 @@ ol.simple p,
 ul.simple p {
     margin-bottom: 0;
 }
+
 aside.footnote > span,
 div.citation > span {
     float: left;
@@ -667,6 +663,16 @@ dd {
     margin-left: 30px;
 }
 
+.sig dd {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
+.sig dl {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
 dl > dd:last-child,
 dl > dd:last-child > :last-child {
     margin-bottom: 0;

docs/manual/_static/doctools.js

@@ -1,12 +1,5 @@
 /*
- * doctools.js
- * ~~~~~~~~~~~
- *
  * Base JavaScript utilities for all Sphinx HTML documentation.
- *
- * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 "use strict";
 

docs/manual/_static/documentation_options.js

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

docs/manual/_static/language_data.js

@@ -1,19 +1,12 @@
 /*
- * language_data.js
- * ~~~~~~~~~~~~~~~~
- *
  * This script contains the language-specific data used by searchtools.js,
  * namely the list of stopwords, stemmer, scorer and splitter.
- *
- * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
 
 
-/* Non-minified version is copied as a separate JS file, is available */
+/* Non-minified version is copied as a separate JS file, if available */
 
 /**
  * Porter Stemmer

docs/manual/_static/pygments.css

@@ -3,85 +3,77 @@
 .highlight span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
 .highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
 .highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
-.highlight .hll { background-color: #ffffcc }
-.highlight { background: #f8f8f8; }
-.highlight .c { color: #8F5902; font-style: italic } /* Comment */
-.highlight .err { color: #A40000; border: 1px solid #EF2929 } /* Error */
-.highlight .g { color: #000 } /* Generic */
-.highlight .k { color: #204A87; font-weight: bold } /* Keyword */
-.highlight .l { color: #000 } /* Literal */
-.highlight .n { color: #000 } /* Name */
-.highlight .o { color: #CE5C00; font-weight: bold } /* Operator */
-.highlight .x { color: #000 } /* Other */
-.highlight .p { color: #000; font-weight: bold } /* Punctuation */
-.highlight .ch { color: #8F5902; font-style: italic } /* Comment.Hashbang */
-.highlight .cm { color: #8F5902; font-style: italic } /* Comment.Multiline */
-.highlight .cp { color: #8F5902; font-style: italic } /* Comment.Preproc */
-.highlight .cpf { color: #8F5902; font-style: italic } /* Comment.PreprocFile */
-.highlight .c1 { color: #8F5902; font-style: italic } /* Comment.Single */
-.highlight .cs { color: #8F5902; font-style: italic } /* Comment.Special */
-.highlight .gd { color: #A40000 } /* Generic.Deleted */
-.highlight .ge { color: #000; font-style: italic } /* Generic.Emph */
-.highlight .ges { color: #000; font-weight: bold; font-style: italic } /* Generic.EmphStrong */
-.highlight .gr { color: #EF2929 } /* Generic.Error */
-.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
-.highlight .gi { color: #00A000 } /* Generic.Inserted */
-.highlight .go { color: #000; font-style: italic } /* Generic.Output */
-.highlight .gp { color: #8F5902 } /* Generic.Prompt */
-.highlight .gs { color: #000; font-weight: bold } /* Generic.Strong */
-.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
-.highlight .gt { color: #A40000; font-weight: bold } /* Generic.Traceback */
-.highlight .kc { color: #204A87; font-weight: bold } /* Keyword.Constant */
-.highlight .kd { color: #204A87; font-weight: bold } /* Keyword.Declaration */
-.highlight .kn { color: #204A87; font-weight: bold } /* Keyword.Namespace */
-.highlight .kp { color: #204A87; font-weight: bold } /* Keyword.Pseudo */
-.highlight .kr { color: #204A87; font-weight: bold } /* Keyword.Reserved */
-.highlight .kt { color: #204A87; font-weight: bold } /* Keyword.Type */
-.highlight .ld { color: #000 } /* Literal.Date */
-.highlight .m { color: #0000CF; font-weight: bold } /* Literal.Number */
-.highlight .s { color: #4E9A06 } /* Literal.String */
-.highlight .na { color: #C4A000 } /* Name.Attribute */
-.highlight .nb { color: #204A87 } /* Name.Builtin */
-.highlight .nc { color: #000 } /* Name.Class */
-.highlight .no { color: #000 } /* Name.Constant */
-.highlight .nd { color: #5C35CC; font-weight: bold } /* Name.Decorator */
-.highlight .ni { color: #CE5C00 } /* Name.Entity */
-.highlight .ne { color: #C00; font-weight: bold } /* Name.Exception */
-.highlight .nf { color: #000 } /* Name.Function */
-.highlight .nl { color: #F57900 } /* Name.Label */
-.highlight .nn { color: #000 } /* Name.Namespace */
-.highlight .nx { color: #000 } /* Name.Other */
-.highlight .py { color: #000 } /* Name.Property */
-.highlight .nt { color: #204A87; font-weight: bold } /* Name.Tag */
-.highlight .nv { color: #000 } /* Name.Variable */
-.highlight .ow { color: #204A87; font-weight: bold } /* Operator.Word */
-.highlight .pm { color: #000; font-weight: bold } /* Punctuation.Marker */
-.highlight .w { color: #F8F8F8 } /* Text.Whitespace */
-.highlight .mb { color: #0000CF; font-weight: bold } /* Literal.Number.Bin */
-.highlight .mf { color: #0000CF; font-weight: bold } /* Literal.Number.Float */
-.highlight .mh { color: #0000CF; font-weight: bold } /* Literal.Number.Hex */
-.highlight .mi { color: #0000CF; font-weight: bold } /* Literal.Number.Integer */
-.highlight .mo { color: #0000CF; font-weight: bold } /* Literal.Number.Oct */
-.highlight .sa { color: #4E9A06 } /* Literal.String.Affix */
-.highlight .sb { color: #4E9A06 } /* Literal.String.Backtick */
-.highlight .sc { color: #4E9A06 } /* Literal.String.Char */
-.highlight .dl { color: #4E9A06 } /* Literal.String.Delimiter */
-.highlight .sd { color: #8F5902; font-style: italic } /* Literal.String.Doc */
-.highlight .s2 { color: #4E9A06 } /* Literal.String.Double */
-.highlight .se { color: #4E9A06 } /* Literal.String.Escape */
-.highlight .sh { color: #4E9A06 } /* Literal.String.Heredoc */
-.highlight .si { color: #4E9A06 } /* Literal.String.Interpol */
-.highlight .sx { color: #4E9A06 } /* Literal.String.Other */
-.highlight .sr { color: #4E9A06 } /* Literal.String.Regex */
-.highlight .s1 { color: #4E9A06 } /* Literal.String.Single */
-.highlight .ss { color: #4E9A06 } /* Literal.String.Symbol */
-.highlight .bp { color: #3465A4 } /* Name.Builtin.Pseudo */
-.highlight .fm { color: #000 } /* Name.Function.Magic */
-.highlight .vc { color: #000 } /* Name.Variable.Class */
-.highlight .vg { color: #000 } /* Name.Variable.Global */
-.highlight .vi { color: #000 } /* Name.Variable.Instance */
-.highlight .vm { color: #000 } /* Name.Variable.Magic */
-.highlight .il { color: #0000CF; font-weight: bold } /* Literal.Number.Integer.Long */
+.highlight .hll { background-color: #fdf2e2 }
+.highlight { background: #f2f2f2; color: #1E1E1E }
+.highlight .c { color: #515151 } /* Comment */
+.highlight .err { color: #D71835 } /* Error */
+.highlight .k { color: #8045E5 } /* Keyword */
+.highlight .l { color: #7F4707 } /* Literal */
+.highlight .n { color: #1E1E1E } /* Name */
+.highlight .o { color: #163 } /* Operator */
+.highlight .p { color: #1E1E1E } /* Punctuation */
+.highlight .ch { color: #515151 } /* Comment.Hashbang */
+.highlight .cm { color: #515151 } /* Comment.Multiline */
+.highlight .cp { color: #515151 } /* Comment.Preproc */
+.highlight .cpf { color: #515151 } /* Comment.PreprocFile */
+.highlight .c1 { color: #515151 } /* Comment.Single */
+.highlight .cs { color: #515151 } /* Comment.Special */
+.highlight .gd { color: #00749C } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gh { color: #00749C } /* Generic.Heading */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #00749C } /* Generic.Subheading */
+.highlight .kc { color: #8045E5 } /* Keyword.Constant */
+.highlight .kd { color: #8045E5 } /* Keyword.Declaration */
+.highlight .kn { color: #8045E5 } /* Keyword.Namespace */
+.highlight .kp { color: #8045E5 } /* Keyword.Pseudo */
+.highlight .kr { color: #8045E5 } /* Keyword.Reserved */
+.highlight .kt { color: #7F4707 } /* Keyword.Type */
+.highlight .ld { color: #7F4707 } /* Literal.Date */
+.highlight .m { color: #7F4707 } /* Literal.Number */
+.highlight .s { color: #163 } /* Literal.String */
+.highlight .na { color: #7F4707 } /* Name.Attribute */
+.highlight .nb { color: #7F4707 } /* Name.Builtin */
+.highlight .nc { color: #00749C } /* Name.Class */
+.highlight .no { color: #00749C } /* Name.Constant */
+.highlight .nd { color: #7F4707 } /* Name.Decorator */
+.highlight .ni { color: #163 } /* Name.Entity */
+.highlight .ne { color: #8045E5 } /* Name.Exception */
+.highlight .nf { color: #00749C } /* Name.Function */
+.highlight .nl { color: #7F4707 } /* Name.Label */
+.highlight .nn { color: #1E1E1E } /* Name.Namespace */
+.highlight .nx { color: #1E1E1E } /* Name.Other */
+.highlight .py { color: #00749C } /* Name.Property */
+.highlight .nt { color: #00749C } /* Name.Tag */
+.highlight .nv { color: #D71835 } /* Name.Variable */
+.highlight .ow { color: #8045E5 } /* Operator.Word */
+.highlight .pm { color: #1E1E1E } /* Punctuation.Marker */
+.highlight .w { color: #1E1E1E } /* Text.Whitespace */
+.highlight .mb { color: #7F4707 } /* Literal.Number.Bin */
+.highlight .mf { color: #7F4707 } /* Literal.Number.Float */
+.highlight .mh { color: #7F4707 } /* Literal.Number.Hex */
+.highlight .mi { color: #7F4707 } /* Literal.Number.Integer */
+.highlight .mo { color: #7F4707 } /* Literal.Number.Oct */
+.highlight .sa { color: #163 } /* Literal.String.Affix */
+.highlight .sb { color: #163 } /* Literal.String.Backtick */
+.highlight .sc { color: #163 } /* Literal.String.Char */
+.highlight .dl { color: #163 } /* Literal.String.Delimiter */
+.highlight .sd { color: #163 } /* Literal.String.Doc */
+.highlight .s2 { color: #163 } /* Literal.String.Double */
+.highlight .se { color: #163 } /* Literal.String.Escape */
+.highlight .sh { color: #163 } /* Literal.String.Heredoc */
+.highlight .si { color: #163 } /* Literal.String.Interpol */
+.highlight .sx { color: #163 } /* Literal.String.Other */
+.highlight .sr { color: #D71835 } /* Literal.String.Regex */
+.highlight .s1 { color: #163 } /* Literal.String.Single */
+.highlight .ss { color: #00749C } /* Literal.String.Symbol */
+.highlight .bp { color: #7F4707 } /* Name.Builtin.Pseudo */
+.highlight .fm { color: #00749C } /* Name.Function.Magic */
+.highlight .vc { color: #D71835 } /* Name.Variable.Class */
+.highlight .vg { color: #D71835 } /* Name.Variable.Global */
+.highlight .vi { color: #D71835 } /* Name.Variable.Instance */
+.highlight .vm { color: #7F4707 } /* Name.Variable.Magic */
+.highlight .il { color: #7F4707 } /* Literal.Number.Integer.Long */
 @media not print {
 body[data-theme="dark"] .highlight pre { line-height: 125%; }
 body[data-theme="dark"] .highlight td.linenos .normal { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; }

docs/manual/_static/searchtools.js

@@ -1,12 +1,5 @@
 /*
- * searchtools.js
- * ~~~~~~~~~~~~~~~~
- *
  * Sphinx JavaScript utilities for the full-text search.
- *
- * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 "use strict";
 
@@ -20,7 +13,7 @@ if (typeof Scorer === "undefined") {
     // and returns the new score.
     /*
     score: result => {
-      const [docname, title, anchor, descr, score, filename] = result
+      const [docname, title, anchor, descr, score, filename, kind] = result
       return score
     },
     */
@@ -47,6 +40,14 @@ if (typeof Scorer === "undefined") {
   };
 }
 
+// Global search result kind enum, used by themes to style search results.
+class SearchResultKind {
+    static get index() { return  "index"; }
+    static get object() { return "object"; }
+    static get text() { return "text"; }
+    static get title() { return "title"; }
+}
+
 const _removeChildren = (element) => {
   while (element && element.lastChild) element.removeChild(element.lastChild);
 };
@@ -57,16 +58,20 @@ const _removeChildren = (element) => {
 const _escapeRegExp = (string) =>
   string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
 
-const _displayItem = (item, searchTerms) => {
+const _displayItem = (item, searchTerms, highlightTerms) => {
   const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
-  const docUrlRoot = DOCUMENTATION_OPTIONS.URL_ROOT;
   const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
   const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
   const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
+  const contentRoot = document.documentElement.dataset.content_root;
 
-  const [docName, title, anchor, descr, score, _filename] = item;
+  const [docName, title, anchor, descr, score, _filename, kind] = item;
 
   let listItem = document.createElement("li");
+  // Add a class representing the item's type:
+  // can be used by a theme's CSS selector for styling
+  // See SearchResultKind for the class names.
+  listItem.classList.add(`kind-${kind}`);
   let requestUrl;
   let linkUrl;
   if (docBuilder === "dirhtml") {
@@ -75,28 +80,35 @@ const _displayItem = (item, searchTerms) => {
     if (dirname.match(/\/index\/$/))
       dirname = dirname.substring(0, dirname.length - 6);
     else if (dirname === "index/") dirname = "";
-    requestUrl = docUrlRoot + dirname;
+    requestUrl = contentRoot + dirname;
     linkUrl = requestUrl;
   } else {
     // normal html builders
-    requestUrl = docUrlRoot + docName + docFileSuffix;
+    requestUrl = contentRoot + docName + docFileSuffix;
     linkUrl = docName + docLinkSuffix;
   }
   let linkEl = listItem.appendChild(document.createElement("a"));
   linkEl.href = linkUrl + anchor;
   linkEl.dataset.score = score;
   linkEl.innerHTML = title;
-  if (descr)
+  if (descr) {
     listItem.appendChild(document.createElement("span")).innerHTML =
       " (" + descr + ")";
+    // highlight search terms in the description
+    if (SPHINX_HIGHLIGHT_ENABLED)  // set in sphinx_highlight.js
+      highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
+  }
   else if (showSearchSummary)
     fetch(requestUrl)
       .then((responseData) => responseData.text())
       .then((data) => {
         if (data)
           listItem.appendChild(
-            Search.makeSearchSummary(data, searchTerms)
+            Search.makeSearchSummary(data, searchTerms, anchor)
           );
+        // highlight search terms in the summary
+        if (SPHINX_HIGHLIGHT_ENABLED)  // set in sphinx_highlight.js
+          highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
       });
   Search.output.appendChild(listItem);
 };
@@ -108,27 +120,46 @@ const _finishSearch = (resultCount) => {
       "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
     );
   else
-    Search.status.innerText = _(
-      `Search finished, found ${resultCount} page(s) matching the search query.`
-    );
+    Search.status.innerText = Documentation.ngettext(
+      "Search finished, found one page matching the search query.",
+      "Search finished, found ${resultCount} pages matching the search query.",
+      resultCount,
+    ).replace('${resultCount}', resultCount);
 };
 const _displayNextItem = (
   results,
   resultCount,
-  searchTerms
+  searchTerms,
+  highlightTerms,
 ) => {
   // results left, load the summary and display it
   // this is intended to be dynamic (don't sub resultsCount)
   if (results.length) {
-    _displayItem(results.pop(), searchTerms);
+    _displayItem(results.pop(), searchTerms, highlightTerms);
     setTimeout(
-      () => _displayNextItem(results, resultCount, searchTerms),
+      () => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
       5
     );
   }
   // search finished, update title and status message
   else _finishSearch(resultCount);
 };
+// Helper function used by query() to order search results.
+// Each input is an array of [docname, title, anchor, descr, score, filename, kind].
+// Order the results by score (in opposite order of appearance, since the
+// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically.
+const _orderResultsByScoreThenName = (a, b) => {
+  const leftScore = a[4];
+  const rightScore = b[4];
+  if (leftScore === rightScore) {
+    // same score: sort alphabetically
+    const leftTitle = a[1].toLowerCase();
+    const rightTitle = b[1].toLowerCase();
+    if (leftTitle === rightTitle) return 0;
+    return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
+  }
+  return leftScore > rightScore ? 1 : -1;
+};
 
 /**
  * Default splitQuery function. Can be overridden in ``sphinx.search`` with a
@@ -152,13 +183,26 @@ const Search = {
   _queued_query: null,
   _pulse_status: -1,
 
-  htmlToText: (htmlString) => {
+  htmlToText: (htmlString, anchor) => {
     const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
-    htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() });
+    for (const removalQuery of [".headerlink", "script", "style"]) {
+      htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() });
+    }
+    if (anchor) {
+      const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`);
+      if (anchorContent) return anchorContent.textContent;
+
+      console.warn(
+        `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.`
+      );
+    }
+
+    // if anchor not specified or not found, fall back to main content
     const docContent = htmlElement.querySelector('[role="main"]');
-    if (docContent !== undefined) return docContent.textContent;
+    if (docContent) return docContent.textContent;
+
     console.warn(
-      "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template."
+      "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template."
     );
     return "";
   },
@@ -211,6 +255,7 @@ const Search = {
     searchSummary.classList.add("search-summary");
     searchSummary.innerText = "";
     const searchList = document.createElement("ul");
+    searchList.setAttribute("role", "list");
     searchList.classList.add("search");
 
     const out = document.getElementById("search-results");
@@ -231,16 +276,7 @@ const Search = {
     else Search.deferQuery(query);
   },
 
-  /**
-   * execute search (requires search index to be loaded)
-   */
-  query: (query) => {
-    const filenames = Search._index.filenames;
-    const docNames = Search._index.docnames;
-    const titles = Search._index.titles;
-    const allTitles = Search._index.alltitles;
-    const indexEntries = Search._index.indexentries;
-
+  _parseQuery: (query) => {
     // stem the search terms and add them to the correct list
     const stemmer = new Stemmer();
     const searchTerms = new Set();
@@ -276,22 +312,40 @@ const Search = {
     // console.info("required: ", [...searchTerms]);
     // console.info("excluded: ", [...excludedTerms]);
 
-    // array of [docname, title, anchor, descr, score, filename]
-    let results = [];
+    return [query, searchTerms, excludedTerms, highlightTerms, objectTerms];
+  },
+
+  /**
+   * execute search (requires search index to be loaded)
+   */
+  _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => {
+    const filenames = Search._index.filenames;
+    const docNames = Search._index.docnames;
+    const titles = Search._index.titles;
+    const allTitles = Search._index.alltitles;
+    const indexEntries = Search._index.indexentries;
+
+    // Collect multiple result groups to be sorted separately and then ordered.
+    // Each is an array of [docname, title, anchor, descr, score, filename, kind].
+    const normalResults = [];
+    const nonMainIndexResults = [];
+
     _removeChildren(document.getElementById("search-progress"));
 
-    const queryLower = query.toLowerCase();
+    const queryLower = query.toLowerCase().trim();
     for (const [title, foundTitles] of Object.entries(allTitles)) {
-      if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) {
+      if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) {
         for (const [file, id] of foundTitles) {
-          let score = Math.round(100 * queryLower.length / title.length)
-          results.push([
+          const score = Math.round(Scorer.title * queryLower.length / title.length);
+          const boost = titles[file] === title ? 1 : 0;  // add a boost for document titles
+          normalResults.push([
             docNames[file],
             titles[file] !== title ? `${titles[file]} > ${title}` : title,
             id !== null ? "#" + id : "",
             null,
-            score,
+            score + boost,
             filenames[file],
+            SearchResultKind.title,
           ]);
         }
       }
@@ -300,46 +354,48 @@ const Search = {
     // search for explicit entries in index directives
     for (const [entry, foundEntries] of Object.entries(indexEntries)) {
       if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) {
-        for (const [file, id] of foundEntries) {
-          let score = Math.round(100 * queryLower.length / entry.length)
-          results.push([
+        for (const [file, id, isMain] of foundEntries) {
+          const score = Math.round(100 * queryLower.length / entry.length);
+          const result = [
             docNames[file],
             titles[file],
             id ? "#" + id : "",
             null,
             score,
             filenames[file],
-          ]);
+            SearchResultKind.index,
+          ];
+          if (isMain) {
+            normalResults.push(result);
+          } else {
+            nonMainIndexResults.push(result);
+          }
         }
       }
     }
 
     // lookup as object
     objectTerms.forEach((term) =>
-      results.push(...Search.performObjectSearch(term, objectTerms))
+      normalResults.push(...Search.performObjectSearch(term, objectTerms))
     );
 
     // lookup as search terms in fulltext
-    results.push(...Search.performTermsSearch(searchTerms, excludedTerms));
+    normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms));
 
     // let the scorer override scores with a custom scoring function
-    if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item)));
+    if (Scorer.score) {
+      normalResults.forEach((item) => (item[4] = Scorer.score(item)));
+      nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item)));
+    }
 
-    // now sort the results by score (in opposite order of appearance, since the
-    // display function below uses pop() to retrieve items) and then
-    // alphabetically
-    results.sort((a, b) => {
-      const leftScore = a[4];
-      const rightScore = b[4];
-      if (leftScore === rightScore) {
-        // same score: sort alphabetically
-        const leftTitle = a[1].toLowerCase();
-        const rightTitle = b[1].toLowerCase();
-        if (leftTitle === rightTitle) return 0;
-        return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
-      }
-      return leftScore > rightScore ? 1 : -1;
-    });
+    // Sort each group of results by score and then alphabetically by name.
+    normalResults.sort(_orderResultsByScoreThenName);
+    nonMainIndexResults.sort(_orderResultsByScoreThenName);
+
+    // Combine the result groups in (reverse) order.
+    // Non-main index entries are typically arbitrary cross-references,
+    // so display them after other results.
+    let results = [...nonMainIndexResults, ...normalResults];
 
     // remove duplicate search results
     // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
@@ -353,14 +409,19 @@ const Search = {
       return acc;
     }, []);
 
-    results = results.reverse();
+    return results.reverse();
+  },
+
+  query: (query) => {
+    const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query);
+    const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms);
 
     // for debugging
     //Search.lastresults = results.slice();  // a copy
     // console.info("search results:", Search.lastresults);
 
     // print the results
-    _displayNextItem(results, results.length, searchTerms);
+    _displayNextItem(results, results.length, searchTerms, highlightTerms);
   },
 
   /**
@@ -424,6 +485,7 @@ const Search = {
         descr,
         score,
         filenames[match[0]],
+        SearchResultKind.object,
       ]);
     };
     Object.keys(objects).forEach((prefix) =>
@@ -451,21 +513,27 @@ const Search = {
     // perform the search on the required terms
     searchTerms.forEach((word) => {
       const files = [];
+      // find documents, if any, containing the query word in their text/title term indices
+      // use Object.hasOwnProperty to avoid mismatching against prototype properties
       const arr = [
-        { files: terms[word], score: Scorer.term },
-        { files: titleTerms[word], score: Scorer.title },
+        { files: terms.hasOwnProperty(word) ? terms[word] : undefined, score: Scorer.term },
+        { files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined, score: Scorer.title },
       ];
       // add support for partial matches
       if (word.length > 2) {
         const escapedWord = _escapeRegExp(word);
-        Object.keys(terms).forEach((term) => {
-          if (term.match(escapedWord) && !terms[word])
-            arr.push({ files: terms[term], score: Scorer.partialTerm });
-        });
-        Object.keys(titleTerms).forEach((term) => {
-          if (term.match(escapedWord) && !titleTerms[word])
-            arr.push({ files: titleTerms[word], score: Scorer.partialTitle });
-        });
+        if (!terms.hasOwnProperty(word)) {
+          Object.keys(terms).forEach((term) => {
+            if (term.match(escapedWord))
+              arr.push({ files: terms[term], score: Scorer.partialTerm });
+          });
+        }
+        if (!titleTerms.hasOwnProperty(word)) {
+          Object.keys(titleTerms).forEach((term) => {
+            if (term.match(escapedWord))
+              arr.push({ files: titleTerms[term], score: Scorer.partialTitle });
+          });
+        }
       }
 
       // no match but word was a required one
@@ -481,16 +549,16 @@ const Search = {
 
         // set score for the word in each file
         recordFiles.forEach((file) => {
-          if (!scoreMap.has(file)) scoreMap.set(file, {});
-          scoreMap.get(file)[word] = record.score;
+          if (!scoreMap.has(file)) scoreMap.set(file, new Map());
+          const fileScores = scoreMap.get(file);
+          fileScores.set(word, record.score);
         });
       });
 
       // create the mapping
       files.forEach((file) => {
-        if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1)
-          fileMap.get(file).push(word);
-        else fileMap.set(file, [word]);
+        if (!fileMap.has(file)) fileMap.set(file, [word]);
+        else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word);
       });
     });
 
@@ -522,7 +590,7 @@ const Search = {
         break;
 
       // select one (max) score for the file.
-      const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w]));
+      const score = Math.max(...wordList.map((w) => scoreMap.get(file).get(w)));
       // add result to the result list
       results.push([
         docNames[file],
@@ -531,6 +599,7 @@ const Search = {
         null,
         score,
         filenames[file],
+        SearchResultKind.text,
       ]);
     }
     return results;
@@ -541,8 +610,8 @@ const Search = {
    * search summary for a given text. keywords is a list
    * of stemmed words.
    */
-  makeSearchSummary: (htmlText, keywords) => {
-    const text = Search.htmlToText(htmlText);
+  makeSearchSummary: (htmlText, keywords, anchor) => {
+    const text = Search.htmlToText(htmlText, anchor);
     if (text === "") return null;
 
     const textLower = text.toLowerCase();

docs/manual/_static/sphinx_highlight.js

@@ -29,14 +29,19 @@ const _highlight = (node, addItems, text, className) => {
       }
 
       span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+      const rest = document.createTextNode(val.substr(pos + text.length));
       parent.insertBefore(
         span,
         parent.insertBefore(
-          document.createTextNode(val.substr(pos + text.length)),
+          rest,
           node.nextSibling
         )
       );
       node.nodeValue = val.substr(0, pos);
+      /* There may be more occurrences of search term in this node. So call this
+       * function recursively on the remaining fragment.
+       */
+      _highlight(rest, addItems, text, className);
 
       if (isInSVG) {
         const rect = document.createElementNS(
@@ -140,5 +145,10 @@ const SphinxHighlight = {
   },
 };
 
-_ready(SphinxHighlight.highlightSearchWords);
-_ready(SphinxHighlight.initEscapeListener);
+_ready(() => {
+  /* Do not call highlightSearchWords() when we are on the search page.
+   * It will highlight words from the *previous* search query.
+   */
+  if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords();
+  SphinxHighlight.initEscapeListener();
+});

docs/manual/examples.html

@@ -1,25 +1,26 @@
 <!doctype html>
-<html class="no-js" lang="en">
-  <head><meta charset="utf-8"/>
-    <meta name="viewport" content="width=device-width,initial-scale=1"/>
+<html class="no-js" lang="en" data-content_root="./">
+  <head><meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
     <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" />
+<link rel="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html"><link rel="next" title="Reticulum License" href="license.html"><link rel="prev" title="Support Reticulum" href="support.html">
+        <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
-    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>Code Examples - Reticulum Network Stack 1.0.0 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" />
-    <link rel="stylesheet" type="text/css" href="_static/custom.css" />
+    <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
+        <title>Code Examples - Reticulum Network Stack 1.2.0 documentation</title>
+      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
+    <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" />
+    <link rel="stylesheet" type="text/css" href="_static/custom.css?v=bb3cebc5" />
     
     
 
 
 <style>
   body {
-    --color-code-background: #f8f8f8;
-  --color-code-foreground: black;
+    --color-code-background: #f2f2f2;
+  --color-code-foreground: #1e1e1e;
   
   }
   @media not print {
@@ -86,7 +87,7 @@
   <symbol id="svg-sun" viewBox="0 0 24 24">
     <title>Light mode</title>
     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
-      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
       <circle cx="12" cy="12" r="5"></circle>
       <line x1="12" y1="1" x2="12" y2="3"></line>
       <line x1="12" y1="21" x2="12" y2="23"></line>
@@ -101,34 +102,73 @@
   <symbol id="svg-moon" viewBox="0 0 24 24">
     <title>Dark mode</title>
     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
-      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
       <path stroke="none" d="M0 0h24v24H0z" fill="none" />
       <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
     </svg>
   </symbol>
-  <symbol id="svg-sun-half" viewBox="0 0 24 24">
-    <title>Auto light/dark mode</title>
+  <symbol id="svg-sun-with-moon" viewBox="0 0 24 24">
+    <title>Auto light/dark, in light mode</title>
     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
-      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
-      <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
-      <circle cx="12" cy="12" r="9" />
-      <path d="M13 12h5" />
-      <path d="M13 15h4" />
-      <path d="M13 18h1" />
-      <path d="M13 9h4" />
-      <path d="M13 6h1" />
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/>
+      <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/>
+      <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/>
+      <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/>
+      <line x1="19" y1="14.05" x2="20.414" y2="15.464"/>
+      <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/>
+      <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/>
+      <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/>
+      <line x1="19" y1="5.05" x2="20.414" y2="3.636"/>
+      <circle cx="14.5" cy="9.55" r="3.6"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon-with-sun" viewBox="0 0 24 24">
+    <title>Auto light/dark, in dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/>
+      <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/>
+      <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/>
+      <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/>
+      <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/>
+      <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/>
+      <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/>
+      <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-pencil" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
+      <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
+      <path d="M13.5 6.5l4 4" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
+    </svg>
+  </symbol>
+  <symbol id="svg-eye" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
+      <path
+        d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
     </svg>
   </symbol>
 </svg>
 
-<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
-<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
-<label class="overlay sidebar-overlay" for="__navigation">
-  <div class="visually-hidden">Hide navigation sidebar</div>
-</label>
-<label class="overlay toc-overlay" for="__toc">
-  <div class="visually-hidden">Hide table of contents sidebar</div>
-</label>
+<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar">
+<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar">
+<label class="overlay sidebar-overlay" for="__navigation"></label>
+<label class="overlay toc-overlay" for="__toc"></label>
+
+<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a>
 
 
 
@@ -136,38 +176,35 @@
   <header class="mobile-header">
     <div class="header-left">
       <label class="nav-overlay-icon" for="__navigation">
-        <div class="visually-hidden">Toggle site navigation sidebar</div>
-        <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
+        <span class="icon"><svg><use href="#svg-menu"></use></svg></span>
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.0 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.0 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
-        <button class="theme-toggle">
-          <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
-          <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+        <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+          <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+          <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
           <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
           <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
         </button>
       </div>
       <label class="toc-overlay-icon toc-header-icon" for="__toc">
-        <div class="visually-hidden">Toggle table of contents sidebar</div>
-        <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+        <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
       </label>
     </div>
   </header>
   <aside class="sidebar-drawer">
     <div class="sidebar-container">
       
-      <div class="sidebar-sticky"><a class="sidebar-brand centered" href="index.html">
-  
+      <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
   <div class="sidebar-logo-container">
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.0 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.0 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">
@@ -178,13 +215,16 @@
   <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
-<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
+<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -208,25 +248,24 @@
         </a>
         <div class="content-icon-container">
           <div class="theme-toggle-container theme-toggle-content">
-            <button class="theme-toggle">
-              <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
-              <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+            <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+              <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+              <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
               <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
               <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
             </button>
           </div>
           <label class="toc-overlay-icon toc-content-icon" for="__toc">
-            <div class="visually-hidden">Toggle table of contents sidebar</div>
-            <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+            <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
           </label>
         </div>
-        <article role="main">
+        <article role="main" id="furo-main-content">
           <section id="code-examples">
-<span id="examples-main"></span><h1>Code Examples<a class="headerlink" href="#code-examples" title="Permalink to this heading">#</a></h1>
+<span id="examples-main"></span><h1>Code Examples<a class="headerlink" href="#code-examples" title="Link to this heading">¶</a></h1>
 <p>A number of examples are included in the source distribution of Reticulum.
 You can use these examples to learn how to write your own programs.</p>
 <section id="minimal">
-<span id="example-minimal"></span><h2>Minimal<a class="headerlink" href="#minimal" title="Permalink to this heading">#</a></h2>
+<span id="example-minimal"></span><h2>Minimal<a class="headerlink" href="#minimal" title="Link to this heading">¶</a></h2>
 <p>The <em>Minimal</em> example demonstrates the bare-minimum setup required to connect to
 a Reticulum network from your program. In about five lines of code, you will
 have the Reticulum Network Stack initialised, and ready to pass traffic in your
@@ -338,7 +377,7 @@ program.</p>
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py</a>.</p>
 </section>
 <section id="announce">
-<span id="example-announce"></span><h2>Announce<a class="headerlink" href="#announce" title="Permalink to this heading">#</a></h2>
+<span id="example-announce"></span><h2>Announce<a class="headerlink" href="#announce" title="Link to this heading">¶</a></h2>
 <p>The <em>Announce</em> example builds upon the previous example by exploring how to
 announce a destination on the network, and how to let your program receive
 notifications about announces from relevant destinations.</p>
@@ -519,7 +558,7 @@ notifications about announces from relevant destinations.</p>
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py</a>.</p>
 </section>
 <section id="broadcast">
-<span id="example-broadcast"></span><h2>Broadcast<a class="headerlink" href="#broadcast" title="Permalink to this heading">#</a></h2>
+<span id="example-broadcast"></span><h2>Broadcast<a class="headerlink" href="#broadcast" title="Link to this heading">¶</a></h2>
 <p>The <em>Broadcast</em> example explores how to transmit plaintext broadcast messages
 over the network.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@@ -648,7 +687,7 @@ over the network.</p>
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py</a>.</p>
 </section>
 <section id="echo">
-<span id="example-echo"></span><h2>Echo<a class="headerlink" href="#echo" title="Permalink to this heading">#</a></h2>
+<span id="example-echo"></span><h2>Echo<a class="headerlink" href="#echo" title="Link to this heading">¶</a></h2>
 <p>The <em>Echo</em> example demonstrates communication between two destinations using
 the Packet interface.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@@ -988,7 +1027,7 @@ the Packet interface.</p>
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py</a>.</p>
 </section>
 <section id="link">
-<span id="example-link"></span><h2>Link<a class="headerlink" href="#link" title="Permalink to this heading">#</a></h2>
+<span id="example-link"></span><h2>Link<a class="headerlink" href="#link" title="Link to this heading">¶</a></h2>
 <p>The <em>Link</em> example explores establishing an encrypted link to a remote
 destination, and passing traffic back and forth over the link.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@@ -1286,7 +1325,7 @@ destination, and passing traffic back and forth over the link.</p>
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py</a>.</p>
 </section>
 <section id="example-identify">
-<span id="identification"></span><h2>Identification<a class="headerlink" href="#example-identify" title="Permalink to this heading">#</a></h2>
+<span id="identification"></span><h2>Identification<a class="headerlink" href="#example-identify" title="Link to this heading">¶</a></h2>
 <p>The <em>Identify</em> example explores identifying an intiator of a link, once
 the link has been established.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@@ -1607,7 +1646,7 @@ the link has been established.</p>
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Identify.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Identify.py</a>.</p>
 </section>
 <section id="requests-responses">
-<span id="example-request"></span><h2>Requests &amp; Responses<a class="headerlink" href="#requests-responses" title="Permalink to this heading">#</a></h2>
+<span id="example-request"></span><h2>Requests &amp; Responses<a class="headerlink" href="#requests-responses" title="Link to this heading">¶</a></h2>
 <p>The <em>Request</em> example explores sending requests and receiving responses.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
 <span class="c1"># This RNS example demonstrates how to perform requests  #</span>
@@ -1900,7 +1939,7 @@ the link has been established.</p>
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py</a>.</p>
 </section>
 <section id="channel">
-<span id="example-channel"></span><h2>Channel<a class="headerlink" href="#channel" title="Permalink to this heading">#</a></h2>
+<span id="example-channel"></span><h2>Channel<a class="headerlink" href="#channel" title="Link to this heading">¶</a></h2>
 <p>The <em>Channel</em> example explores using a <code class="docutils literal notranslate"><span class="pre">Channel</span></code> to send structured
 data between peers of a <code class="docutils literal notranslate"><span class="pre">Link</span></code>.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@@ -2297,7 +2336,7 @@ data between peers of a <code class="docutils literal notranslate"><span class="
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Channel.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Channel.py</a>.</p>
 </section>
 <section id="buffer">
-<h2>Buffer<a class="headerlink" href="#buffer" title="Permalink to this heading">#</a></h2>
+<h2>Buffer<a class="headerlink" href="#buffer" title="Link to this heading">¶</a></h2>
 <p>The <em>Buffer</em> example explores using buffered readers and writers to send
 binary data between peers of a <code class="docutils literal notranslate"><span class="pre">Link</span></code>.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@@ -2627,7 +2666,7 @@ binary data between peers of a <code class="docutils literal notranslate"><span
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Buffer.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Buffer.py</a>.</p>
 </section>
 <section id="filetransfer">
-<span id="example-filetransfer"></span><h2>Filetransfer<a class="headerlink" href="#filetransfer" title="Permalink to this heading">#</a></h2>
+<span id="example-filetransfer"></span><h2>Filetransfer<a class="headerlink" href="#filetransfer" title="Link to this heading">¶</a></h2>
 <p>The <em>Filetransfer</em> example implements a basic file-server program that
 allow clients to connect and download files. The program uses the Resource
 interface to efficiently pass files of any size over a Reticulum <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>.</p>
@@ -3239,7 +3278,7 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
 <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py</a>.</p>
 </section>
 <section id="custom-interfaces">
-<span id="example-custominterface"></span><h2>Custom Interfaces<a class="headerlink" href="#custom-interfaces" title="Permalink to this heading">#</a></h2>
+<span id="example-custominterface"></span><h2>Custom Interfaces<a class="headerlink" href="#custom-interfaces" title="Link to this heading">¶</a></h2>
 <p>The <em>ExampleInterface</em> demonstrates creating custom interfaces for Reticulum.
 Any number of custom interfaces can be loaded and utilised by Reticulum, and
 will be fully on-par with natively included interfaces, including all supported
@@ -3552,23 +3591,23 @@ will be fully on-par with natively included interfaces, including all supported
       <footer>
         
         <div class="related-pages">
-          <a class="next-page" href="support.html">
+          <a class="next-page" href="license.html">
               <div class="page-info">
                 <div class="context">
                   <span>Next</span>
                 </div>
-                <div class="title">Support Reticulum</div>
+                <div class="title">Reticulum License</div>
               </div>
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
             </a>
-          <a class="prev-page" href="networks.html">
+          <a class="prev-page" href="support.html">
               <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
               <div class="page-info">
                 <div class="context">
                   <span>Previous</span>
                 </div>
                 
-                <div class="title">Building Networks</div>
+                <div class="title">Support Reticulum</div>
                 
               </div>
             </a>
@@ -3576,16 +3615,14 @@ will be fully on-par with natively included interfaces, including all supported
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2023, Mark Qvist
+                Copyright &#169; 2025, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>
             
           </div>
           <div class="right-details">
-            <div class="icons">
-              
-            </div>
+            
           </div>
         </div>
         
@@ -3626,14 +3663,11 @@ will be fully on-par with natively included interfaces, including all supported
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
-    <script src="_static/jquery.js"></script>
-    <script src="_static/underscore.js"></script>
-    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
-    <script src="_static/doctools.js"></script>
-    <script src="_static/sphinx_highlight.js"></script>
-    <script src="_static/scripts/furo.js"></script>
-    <script src="_static/clipboard.min.js"></script>
-    <script src="_static/copybutton.js"></script>
+</div><script src="_static/documentation_options.js?v=6efca38a"></script>
+    <script src="_static/doctools.js?v=9bcbadda"></script>
+    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+    <script src="_static/scripts/furo.js?v=46bd48cc"></script>
+    <script src="_static/clipboard.min.js?v=a7894cd8"></script>
+    <script src="_static/copybutton.js?v=f281be69"></script>
     </body>
 </html>

docs/manual/forhumans.html

@@ -1,25 +1,26 @@
 <!doctype html>
-<html class="no-js" lang="en">
-  <head><meta charset="utf-8"/>
-    <meta name="viewport" content="width=device-width,initial-scale=1"/>
+<html class="no-js" lang="en" data-content_root="./">
+  <head><meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
     <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="index" title="Index" href="genindex.html"><link rel="search" title="Search" href="search.html">
+        <link rel="prefetch" href="_static/rns_logo_512.png" as="image">
 
-    <meta name="generator" content="sphinx-5.3.0, furo 2022.09.29.dev1"/>
-        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 1.0.0 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" />
-    <link rel="stylesheet" type="text/css" href="_static/custom.css" />
+    <!-- Generated with Sphinx 8.2.3 and Furo 2025.09.25.dev1 -->
+        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 1.2.0 documentation</title>
+      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d111a655" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=580074bf" />
+    <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?v=8dab3a3b" />
+    <link rel="stylesheet" type="text/css" href="_static/custom.css?v=bb3cebc5" />
     
     
 
 
 <style>
   body {
-    --color-code-background: #f8f8f8;
-  --color-code-foreground: black;
+    --color-code-background: #f2f2f2;
+  --color-code-foreground: #1e1e1e;
   
   }
   @media not print {
@@ -86,7 +87,7 @@
   <symbol id="svg-sun" viewBox="0 0 24 24">
     <title>Light mode</title>
     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
-      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
       <circle cx="12" cy="12" r="5"></circle>
       <line x1="12" y1="1" x2="12" y2="3"></line>
       <line x1="12" y1="21" x2="12" y2="23"></line>
@@ -101,34 +102,73 @@
   <symbol id="svg-moon" viewBox="0 0 24 24">
     <title>Dark mode</title>
     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
-      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
       <path stroke="none" d="M0 0h24v24H0z" fill="none" />
       <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
     </svg>
   </symbol>
-  <symbol id="svg-sun-half" viewBox="0 0 24 24">
-    <title>Auto light/dark mode</title>
+  <symbol id="svg-sun-with-moon" viewBox="0 0 24 24">
+    <title>Auto light/dark, in light mode</title>
     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
-      stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
-      <path stroke="none" d="M0 0h24v24H0z" fill="none"/>
-      <circle cx="12" cy="12" r="9" />
-      <path d="M13 12h5" />
-      <path d="M13 15h4" />
-      <path d="M13 18h1" />
-      <path d="M13 9h4" />
-      <path d="M13 6h1" />
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/>
+      <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/>
+      <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/>
+      <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/>
+      <line x1="19" y1="14.05" x2="20.414" y2="15.464"/>
+      <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/>
+      <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/>
+      <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/>
+      <line x1="19" y1="5.05" x2="20.414" y2="3.636"/>
+      <circle cx="14.5" cy="9.55" r="3.6"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-moon-with-sun" viewBox="0 0 24 24">
+    <title>Auto light/dark, in dark mode</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round"
+      class="icon-custom-derived-from-feather-sun-and-tabler-moon">
+      <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/>
+      <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/>
+      <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/>
+      <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/>
+      <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/>
+      <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/>
+      <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/>
+      <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/>
+      <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-pencil" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code">
+      <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" />
+      <path d="M13.5 6.5l4 4" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
+    </svg>
+  </symbol>
+  <symbol id="svg-eye" viewBox="0 0 24 24">
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code">
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
+      <path
+        d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" />
+      <path d="M20 21l2 -2l-2 -2" />
+      <path d="M17 17l-2 2l2 2" />
     </svg>
   </symbol>
 </svg>
 
-<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
-<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
-<label class="overlay sidebar-overlay" for="__navigation">
-  <div class="visually-hidden">Hide navigation sidebar</div>
-</label>
-<label class="overlay toc-overlay" for="__toc">
-  <div class="visually-hidden">Hide table of contents sidebar</div>
-</label>
+<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar">
+<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar">
+<label class="overlay sidebar-overlay" for="__navigation"></label>
+<label class="overlay toc-overlay" for="__toc"></label>
+
+<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a>
 
 
 
@@ -136,38 +176,35 @@
   <header class="mobile-header">
     <div class="header-left">
       <label class="nav-overlay-icon" for="__navigation">
-        <div class="visually-hidden">Toggle site navigation sidebar</div>
-        <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
+        <span class="icon"><svg><use href="#svg-menu"></use></svg></span>
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 1.0.0 documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 1.2.0 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
-        <button class="theme-toggle">
-          <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
-          <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+        <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+          <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+          <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
           <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
           <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
         </button>
       </div>
       <label class="toc-overlay-icon toc-header-icon no-toc" for="__toc">
-        <div class="visually-hidden">Toggle table of contents sidebar</div>
-        <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+        <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
       </label>
     </div>
   </header>
   <aside class="sidebar-drawer">
     <div class="sidebar-container">
       
-      <div class="sidebar-sticky"><a class="sidebar-brand centered" href="index.html">
-  
+      <div class="sidebar-sticky"><a class="sidebar-brand" href="index.html">
   <div class="sidebar-logo-container">
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 1.0.0 documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 1.2.0 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">
@@ -178,13 +215,16 @@
   <ul>
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
+<li class="toctree-l1"><a class="reference internal" href="zen.html">Zen of Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="software.html">Programs Using Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
 <li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a></li>
 <li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
 <li class="toctree-l1"><a class="reference internal" href="interfaces.html">Configuring Interfaces</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
-<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
+<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="license.html">Reticulum License</a></li>
 </ul>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
@@ -208,21 +248,20 @@
         </a>
         <div class="content-icon-container">
           <div class="theme-toggle-container theme-toggle-content">
-            <button class="theme-toggle">
-              <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
-              <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
+            <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme">
+              <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
+              <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
               <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
               <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
             </button>
           </div>
           <label class="toc-overlay-icon toc-content-icon no-toc" for="__toc">
-            <div class="visually-hidden">Toggle table of contents sidebar</div>
-            <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
+            <span class="icon"><svg><use href="#svg-toc"></use></svg></span>
           </label>
         </div>
-        <article role="main">
+        <article role="main" id="furo-main-content">
           <section id="an-explanation-of-reticulum-for-human-beings">
-<h1>An Explanation of Reticulum for Human Beings<a class="headerlink" href="#an-explanation-of-reticulum-for-human-beings" title="Permalink to this heading">#</a></h1>
+<h1>An Explanation of Reticulum for Human Beings<a class="headerlink" href="#an-explanation-of-reticulum-for-human-beings" title="Link to this heading">¶</a></h1>
 </section>
 
         </article>
@@ -236,16 +275,14 @@
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2023, Mark Qvist
+                Copyright &#169; 2025, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>
             
           </div>
           <div class="right-details">
-            <div class="icons">
-              
-            </div>
+            
           </div>
         </div>
         
@@ -257,14 +294,11 @@
       
     </aside>
   </div>
-</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
-    <script src="_static/jquery.js"></script>
-    <script src="_static/underscore.js"></script>
-    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
-    <script src="_static/doctools.js"></script>
-    <script src="_static/sphinx_highlight.js"></script>
-    <script src="_static/scripts/furo.js"></script>
-    <script src="_static/clipboard.min.js"></script>
-    <script src="_static/copybutton.js"></script>
+</div><script src="_static/documentation_options.js?v=6efca38a"></script>
+    <script src="_static/doctools.js?v=9bcbadda"></script>
+    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+    <script src="_static/scripts/furo.js?v=46bd48cc"></script>
+    <script src="_static/clipboard.min.js?v=a7894cd8"></script>
+    <script src="_static/copybutton.js?v=f281be69"></script>
     </body>
 </html>