Updated manual

Bugfix: buffer missing segments

Changelog.md

@@ -0,0 +1,723 @@
+### 2023-03-08: RNS β 0.5.0
+
+This release brings two major new additions to the Reticulum API: The Channel and Buffer classes, that provides reliable delivery, and streams over Reticulum. Thanks to @acehoss, @erethon, @gdt and @faragher, who contributed to this release!
+
+**Changes**
+- Added the Buffer class to the API
+- Added the Channel class to the API
+- Improved error messages for offline RNode flashing
+- Improved RNode reconnection when serial device disappears
+- Fixed embedded scope identifier handling for AutoInterface on BSD
+- Fixed AutoInterface not ignoring lo0 on BSD
+- Fixed a bug causing JSON output from rnstatus to fail
+- Fixed invalid installation of test suite into root module path
+- Added EPUB version of the documentation
+- Updated documentation
+
+**Release Hashes**
+```
+0aaf8c0b0b58f07071de5ecd432f4d9cc176b9614419c828b81ad71aa7151624 rns-0.5.0-py3-none-any.whl
+f310a5192c2df7665339c5998ae13815a647283af75b95ad7acbee8c20989954 rnspure-0.5.0-py3-none-any.whl
+```
+
+### 2023-02-17: RNS β 0.4.9
+
+This maintenance release contains a number of bugfixes and minor improvements, along with a few additions to the API.
+
+**Changes**
+- Added JSON output mode to rnstatus
+- Added Link ID to response_generator callback
+- Added Link establishment rate calculation
+- Added get_establishment_rate call to Link API
+- Fixed a number of typos in programs and documentation
+- Fixed some broken links in documentation
+
+**Release Hashes**
+```
+b44eaed796dcd194bec7a541aaeeb1685b07b2ffce068ca268841e6a8661717f rns-0.4.9-py3-none-any.whl
+a15f965a27d208493485724486eb6bc6268d699f2a22ae4fb816bb9b979330fc rnspure-0.4.9-py3-none-any.whl
+```
+
+### 2023-02-04: RNS β 0.4.8
+
+This release introduces the useful `rnid` utility, which makes it possible to use Reticulum Identities for offline file encryption, decryption, signing and validation. The IFAC system has also been significantly improved, and several outdated parts of the documentation was updated and fixed. Thanks to @Erethon and @jooray who contributed to this release!
+
+**Changes**
+- Added header and payload masking to the IFAC system
+- Added `rnid` utility for encrypting, decrypting, signing and validating with Reticulum Identities
+- Added Bluetooth pairing PIN output to `rnodeconf` utility
+- Fixed a bug in announce callback handling
+- Fixed a inconsistency in header flag handling since IFACs were introduced
+- Updated documentation and manual
+
+**Release Hashes**
+```
+fbbd55ee43a68c18491f5deabed51085c46fadca7e1bda823ad455c2f7c95a51 rns-0.4.8-py3-none-any.whl
+335b0d5dd1d2aacd0d8810191aa09567ecf5d3aa990c446f3e3b1bbf7fce1387 rnspure-0.4.8-py3-none-any.whl
+```
+
+### 2023-01-14: RNS β 0.4.7
+
+This maintenance release adds support for using the `rnodeconf` utility to replicate RNode devices, and bootstrap device creation using only tools and software packages obtained from an RNode Bootstrap Console.
+
+**Changes**
+- Added the ability to use rnodeconf to bootstrap RNode creation without needing a connection to the Internet
+- Added ability for rnodeconf to extract firmwares from existing RNodes
+- Added ability for rnodeconf to use extracted firmwares for autoinstaller and updates
+- Updated documentation and manual
+
+**Release Hashes**
+```
+7ea22be8f4cc9504d8a612c5589132351cc0c6b474899204afd71367ab3fb226 rns-0.4.7-py3-none-any.whl
+3dc337b80df37c247abc9cee06c3ecba0f908449005d0eb365c2a9577d689e57 rnspure-0.4.7-py3-none-any.whl
+```
+
+### 2022-12-23: RNS β 0.4.6
+
+This maintenance release brings two bugfixes.
+
+**Changes**
+- Fixed missing path invalidation on failed link establishments made from a shared instance client
+- Fixed a memory leak in link handling
+
+**Release Hashes**
+```
+7f1b0b254dce5bb1bacc336b026dab2dda5859b43cb0f4ceed3f70ba825f8873 rns-0.4.6-py3-none-any.whl
+775c1b9b5bdf202524e50e58dc7c7bad9262ca3c16471cbfc6fb3a528e732460 rnspure-0.4.6-py3-none-any.whl
+```
+
+### 2022-12-22: RNS β 0.4.5
+
+This maintenance release significantly improves path rediscovery on roaming devices with multiple interfaces, and adds a few tweaks to interface handling, that are especially relevant on Android.
+
+**Changes**
+- Faster roaming path recovery for multiple interface non-transport instances
+- Fixed AutoInterface multicast echoes failing on interfaces with rolling MAC addresses on every re-connect
+- Added carrier change detection flag to AutoInterface
+- Adjusted loglevels for some items
+
+**Release Hashes**
+```
+6757d5d815d4d96c45c181daf321447914c0e90892d43e142f2bd3fffacda9d9 rns-0.4.5-py3-none-any.whl
+11669065091d67e3abaddb0096e5c92fc48080692b5644559226b2e2e6721060 rnspure-0.4.5-py3-none-any.whl
+```
+
+### 2022-12-22: RNS β 0.4.4
+
+This maintenance release improves path response handling and log output.
+
+**Release Hashes**
+```
+b0b59c25910151db0c2085d812bcc3d06cb930ddb8cd1e281b40cb592c1427eb rns-0.4.4-py3-none-any.whl
+fe29ce3eb9e55f6953312c8db8c350bd58a7777e8c8dffd5491b840254426332 rnspure-0.4.4-py3-none-any.whl
+```
+
+### 2022-12-22: RNS β 0.4.3
+
+This maintenance release brings faster path rediscovery and improves hardware support on Android, along with a few other minor tweaks and bugfixes.
+
+**Changes**
+- Added automatic path rediscovery on failed link establishments
+- Added signature validation for link request proof packets for every transport hop
+- Improved RNode hotplug support over Bluetooth on Android
+- Improved Resource transfer sequencing and retry handling
+- Fixed driver initialisation for Qinheng CH34x serial chips on Android
+- Updates to documentation
+
+**Release Hashes**
+```
+c035c2e21b8b207b00937ad57e947c7b4f17a02fe4f253d6e1fcc000479019b7 rns-0.4.3-py3-none-any.whl
+e367576893bada72329ad195ebaa1e295bbca8897241f258428e1957d2da9a55 rnspure-0.4.3-py3-none-any.whl
+```
+
+### 2022-11-24: RNS β 0.4.2
+
+This maintenance release brings a number of minor improvements, and fixes a few bugs related to hardware support on Android.
+
+**Changes**
+- Fixed AutoInterface roaming not working on Android devices that rotate Ethernet and WiFi MAC addresses on every physical connection change
+- Fixed RNode interface not working over Bluetooth on Android versions 10 and below
+- Greatly improved startup time for programs connecting to a shared Reticulum instance on slow or resource-limited systems
+- Improvements to internal utility-functions and logging
+- Added a public development roadmap
+- Updates and fixes to the documentation
+
+**Release Hashes**
+```
+ba541ead4194e7ae3e295bf2c84b609041e4dc82e1b5bfce0885396ee090e37f rns-0.4.2-py3-none-any.whl
+a352cb8d0862a1a23e66bda08357bf7e725b540bbdd3bb3b32914f3c0bb99a05 rnspure-0.4.2-py3-none-any.whl
+```
+
+### 2022-11-03: RNS β 0.4.1
+
+This maintenance release fixes few bugs, and improves I2P interface recovery on unresponsive I2P tunnels.
+
+**Changes**
+- Added better I2P tunnel state visibility to rnstatus util
+- Improved I2P recovery time on unresponsive tunnels
+- Improved I2P tunnel state detection
+- Fixed missing IFAC identity init on spawned TCP clients
+- Fixed missing IFAC identity init on spawned I2P interfaces
+- Fixed missing check for socket state on I2P interfaces
+
+**Release Hashes**
+```
+e28643a7396c3a41d859eb7d3a14f166e648003da36fc49094561fbf49c04b7e rns-0.4.1-py3-none-any.whl
+feaa326545c928f3d5dc7b6fdb31975517af15da0751927491c4ac23dac36edc rnspure-0.4.1-py3-none-any.whl
+```
+
+### 2022-11-03: RNS β 0.4.0
+
+This maintenance release fixes minor bug in the rnodeconf utility.
+
+**Changes**
+- Fixed incorrect storage location for local firmware cache in the rnodeconf utility
+
+**Release Hashes**
+```
+16dda7b087cff0c21b7b0460798cb433fc96f27d058eb7d50e38898a1a1e49c4 rns-0.4.0-py3-none-any.whl
+5f137cfd42ee9d9e7ae43b25d25849bd087145b7edf2c29ffdfd93d57ab34284 rnspure-0.4.0-py3-none-any.whl
+```
+
+### 2022-11-03: RNS β 0.3.19
+
+This release adds support for Bluetooth-connected RNode interfaces, and includes a few improvements to the rnodeconf utility.
+
+**Changes**
+- Added support for RNode interfaces connected over Bluetooth on Linux and Android
+- Improved rnodeconf install and update timing, which fixes installs sometimes failing on T-Beam devices
+
+**Release Hashes**
+```
+9d5bee8eb9b2160dab985017bfa3e3db9c35033cfae97653a9fa8faa6064f228 rns-0.3.19-py3-none-any.whl
+0f0996b5e401ca5d4e91080df3d6de326fc591164c9e6932a2eb79f1d2b8d375 rnspure-0.3.19-py3-none-any.whl
+```
+
+### 2022-11-03: RNS β 0.3.18
+
+This maintenance release includes the `rnodeconf` utility directly in the `rns` package, and brings a few improvements to interface handling and hardware interfacing.
+
+**Important!** The minimum supported RNode firmware version for this release is `1.51`, and the firmware will needs to be updated with `rnodeconf` version `2.0.0` or greater, since earlier versions won't be able to fetch the new release files.
+
+**Changes**
+- Added `rnodeconf` utility
+- Added more options for controlling log output
+- Added ability to write to the external framebuffer of RNode devices
+- Improved teardown handling on RNode interfaces
+
+**Release Hashes**
+```
+dc0c56950b85be763270695faf441029f7e6c31cdc44447c6c470e09c734aa45 rns-0.3.18-1-py3-none-any.whl
+760bfc52419a8c45a420df41c40a1bf96bd494dabd7efe461c7907b152bbf39c rnspure-0.3.18-1-py3-none-any.whl
+```
+
+### 2022-11-03: RNS β 0.3.17
+
+This maintenance release fixes a regression in the 0.3.16 release.
+
+**Changes**
+- Fixed an incorrect import that inadverdently caused Android-specific interfaces to be used on non Android operating systems.
+
+**Release Hashes**
+```
+SHA256 0e8327461e2d39f859059cc14e94fb33f21e1186c422bb766950f42ca1387656 rns-0.3.17-py3-none-any.whl
+SHA256 9e31160cc38e0d5531460d5eca7b3f6e6d8c3b2a7afb04338ee72cc488a2ba18 rnspure-0.3.17-py3-none-any.whl
+```
+
+### 2022-10-20: RNS β 0.3.16
+
+This maintenance release fixes a single bug that prevented running RNS in Termux (and similar) on Android.
+
+**Changes**
+- Fixed missing imports and module checks for API-limited environments on Android
+
+**Release Hashes**
+```
+SHA256 dc4202302b1f1503a0f1c8fef7123b31f7d5d7131ae5b9f988064ebe22e29ed8 rns-0.3.16-py3-none-any.whl
+SHA256 127624d2592745602d4a056c347fa6f5989f049275a5b8bfa97c296af9bc497f rnspure-0.3.16-py3-none-any.whl
+```
+
+### 2022-10-20: RNS β 0.3.15
+
+This maintenance release primarily adds support for external hardware interfaces on Android. A number of bugs have also been fixed, and improvements made to logging output consistency.
+
+**Changes**
+- Added support for RNode interfaces on Android
+- Added support for KISS interfaces on Android
+- Added support for Serial interfaces on Android
+- Added AutoInterface support for kernel network devices that rotate MAC addresses on roaming and/or reconnects
+- Updated various helper functions
+- Minor log output cleanup and fixes
+- Fixed missing lookup for locally running destinations in Identity.recall() when running as a shared transport instance
+- Fixed missing announce cap property on hot-plugged interfaces
+- Fixed incorrect behaviour in announce processing for instance-local destinations to roaming- or boundary-mode interfaces
+
+**Release Hashes**
+```
+SHA256 c56f32dbfd10fae1b5d2dddafe7d2a0f2127908827a71fce9e43fd051ea453bc rns-0.3.15-py3-none-any.whl
+SHA256 597d6df05b3586eaa1515c0215cec30d7a018a209e7900634345c39514efcd18 rnspure-0.3.15-py3-none-any.whl
+```
+
+### 2022-10-07: RNS β 0.3.14
+
+This maintenance release brings a few improvements, including optimised announce packet structure and updated documentation.
+
+**Please note!** While this is a small maintenance release, it includes changes to packe structure that breaks backwards compatibility with all previous RNS versions.
+
+**Changes**
+- Optimised announce packet structure
+- Reject mismatching public keys on hash collision.
+- Minor updates to documentation
+
+**Release Hashes**
+```
+SHA256 b761efc24d20c5719817bfefbbe8ce69f7c91d65bb8273cb02578f77d6f88bc5 rns-0.3.14-py3-none-any.whl
+SHA256 cc24a1f010431c8f193ec0ffc6dccade614a5be40c47ac12e3e9ae60b52f046e rnspure-0.3.14-py3-none-any.whl
+```
+
+### 2022-10-04: RNS β 0.3.13
+
+This maintenance release includes a single but important bugfix.
+
+**Changes**
+- Fixed missing hash construction step in announce emission and validation
+
+**Release Hashes**
+```
+SHA256 d6c8a7cb8ea7edc99800df92abff246e8159f2d9c9f1a2b57672385d49647c90 rns-0.3.13-py3-none-any.whl
+SHA256 c07c28942e374342c4e807a0b6e81d831737b87cf59651670b8c1c191030a326 rnspure-0.3.13-py3-none-any.whl
+```
+
+### 2022-09-30: RNS β 0.3.12
+
+This maintenance release includes a fix to the [serious security flaw discussed here](https://github.com/markqvist/Reticulum/discussions/103). **Please Note!** Updating to RNS 0.3.12 will intentionally break backwards compatibility with all previous verstions for link establishment. It is recommended to upgrade all your systems to 0.3.12 as soon as possible.
+
+Additionally, this release brings a range of small, but very useful improvements to reliability and user experience, along with a significant update to the documentation material.
+
+**Changes**
+- Fixed a [serious security flaw](https://github.com/markqvist/Reticulum/discussions/103) in link establishment key exchanges
+- Allow hot-plug of RNode devices
+- Better detachment handler for TCP clients on shutdown
+- Implemented better config directory path handling
+- Clarifications and improvements to various documentation chapters
+- Improved writing quality of documentation, courtesy of @huyndao
+- Improved overall presentation of documentation and manual
+- Improved reliability of data persistence in case of unexpected shutdowns or hardware crashes
+- Added rnsd warning on start as client
+- Fixed a rendering bug in the rnpath utility
+- Added initial connection timeout configuration option to TCP Client interfaces
+- Brought deprecated native python API calls up to date
+
+**Release Hashes**
+```
+SHA256 74a4881ebf8d805bffb43efef91769b1cbb87affe56ac630355946c7484cffbf rns-0.3.12-py3-none-any.whl
+SHA256 03429122b3b4133667632ba2404df7bbf57ea5df1b9c815d7608b1d59cd29a76 rnspure-0.3.12-py3-none-any.whl
+```
+
+### 2022-07-09: RNS β 0.3.11
+
+This maintenance release contains a single but important bug fix in resource transfers.
+
+**Changes**
+- Fixed a an incorrect size calculation for resource advertisements, that would lead to resources of specific sizes failing with an MTU error.
+
+**Release Hashes**
+```
+SHA256 7c03a003326bcd127226414b08cf48f87bcc6b88a7279c52e28415315668543c rns-0.3.11-py3-none-any.whl
+SHA256 1a6aaa3ba370ece28cc975ba94b0461c61497cf0797f92662472e0ec20576cb1 rnspure-0.3.11-py3-none-any.whl
+```
+
+### 2022-07-08: RNS β 0.3.10
+
+This maintenance release contains a single but important bug fix for systems running Reticulum Transport Instances.
+
+**Changes**
+- Fixed a potential race condition in link establishment flow, that could lead to links not being established over hops with very low latency.
+
+**Release Hashes**
+```
+SHA256 1c9fb56b967aed507694e6b5d5fca7a89b022cad9fa2058d248e359dc150fba7 rns-0.3.10-py3-none-any.whl
+SHA256 8eae07f9e6241ea1f3778430456225dee3ef73bb1c4df5e5362dd00226404628 rnspure-0.3.10-py3-none-any.whl
+```
+
+### 2022-07-05: RNS β 0.3.9
+
+This release expands the address space of Reticulum to 128 bits, and brings improvements to the documentation, along with a few bugfixes and updates.
+
+**Changes**
+- Expanded address space to 128 bits
+- Updated documentation
+- Improved rnx interactive mode
+- Improved readme file
+- Added reticulum.network website
+- Added periodic cache cleaning
+- Fixed a bug in the --no-auth option in rncp
+
+**Release Hashes**
+```
+SHA256 892005e95fc9eda4c4c5d9f94dd33cdc27d3ac6e228d1b0b2519e35069951b86 rns-0.3.9-1-py3-none-any.whl
+SHA256 cb7d873c51c746ecdb8963a6a7a0e8d010fb6c61ee785c5e97376d3779a7bae8 rnspure-0.3.9-1-py3-none-any.whl
+```
+
+### 2022-06-22: RNS β 0.3.8
+
+This release brings big improvements to compatibility with various system types, along with several convenient new features, and a lot of tuning, optimisation and stability improvements. In a continued effort, the documentation has also been updated, restructured, and had several new and informative sections added.
+
+**Changes**
+- Added ability to install and run RNS without any dependencies
+- Added backend abstraction for cryptographic primitives
+- Added pure-python implementations of all cryptographic primitives
+- Added accept option to Link API
+- Added several undocumented API calls to the documentation
+- Added option to filter interfaces to rnstatus utility
+- Added "Communications Hardware" chapter to the documentation
+- Improved multiple chapters and restructured documentation
+- Improved efficiency of Transport instances
+- Improved performance of Resource transfers
+- Improved Resource handling strategies over different physical link types
+- Improved link capacity and speed estimation calculations
+- Improved I2P interface error handling and stability
+- Tuned Resource and Link timeouts
+- Tuned TCP socket options for better reliability over intermittent links
+- Tuned I2P interface timeouts for better reliability over intermittent links
+- Fixed a missing check for zero-length packets on IFAC-enabled interfaces
+- Fixed a socket allocation leak in I2P interfaces
+- Added unit tests
+- Added performance profiling tools
+- Improved build system
+
+Release SHA-256 for `rns-0.3.8-py3-none-any.whl` is `fdb53aba14840edf3d71dde1a745f319e7f60d6993851b7651bf8ba3d5c53ba7`
+Release SHA-256 for `rnspure-0.3.8-py3-none-any.whl` is `b0eb004c3725bc20496b1c855e7d22729d8a39fd0cde957ab95aa8c7e13ee3a4`
+
+### 2022-05-29: RNS β 0.3.7
+
+This release comes with a big upgrade to reliability and resilience, with lots of small bug fixes and improvements, along with some significant new additions and features. The documentation and API reference has also seen several improvements for clarity.
+
+Users of I2P interfaces will see big improvements in reliability with better handling of errors from the I2P SAM API, and much better automatic recovery when I2P connectivity is intermittent.
+
+Reticulum is now able to perform network-wide discovery of unknown paths, using the new Gateway interface mode. The stability of established links has also been improved by using a better timeout calculation method.
+
+It is also worth mentioning the addition of the two new utilities, `rncp` and `rnx`, that allow you to transfer files to remote systems, and perform remote command execution.
+
+*Please Note!* For using 64-bit IFACs on RNode hardware, your RNodes must be running at least firmware version 1.28.
+
+**Changes**
+- Added gateway interface mode
+- Added `rncp` utility for transferring files to remote destinations
+- Added `rnx` utility for remotely executing commands and returning output
+- Implemented unknown path discovery
+- Implemented recursive path request loop avoidance
+- Implemented bandwidth cap for recursive path requests
+- Improved Link authentication callbacks
+- Improved Link stale time calculations and process
+- Improved error detection and handling in I2P interfaces
+- Improved automatic recovery and reliability on intermittent I2P interfaces
+- Added request size to receipts, and updated relevant API documentation
+- Added default identity storage folder
+- Fixed deprecated options in libi2p's asyncio calls
+- Fixed I2P controller startup when event loop is not immediately ready
+- Fixed bug in conditional resource acceptance callback
+- Fixed an invalid interface mode check
+- Fixed missing recursive progress callback allocation in segmented resource transfer
+- Fixed expired AP and Roaming interface mode paths not being removed at the correct time
+- Fixed announce rate targets not being set on I2PInterface peers
+- Fixed naming conflict in resource advertisements
+- Fixed link stale time calculation on newly created links without any actual traffic
+- Fixed a bug that caused large packets (over 492 bytes) with IFAC enabled to be dropped on RNode hardware
+- Improved output of `rnstatus` utility
+- Improved Destination and Link API documentation
+- Updated documentation and readme
+
+Release SHA-256 for Python Wheel is `2cd9a584d6b13bb478a43b49b7de3f2a8270c4b8979666b1ca40cd81daacbf42`
+
+### 2022-05-17: RNS β 0.3.6
+
+This release adds a number of improvements, a new interface type, and some very useful new interface modes.
+
+**Changes**
+- Added PipeInterface, create interfaces with any program over stdio
+- Added "roaming" and "boundary" interface modes
+- Added per-interface announce rate control
+- Added ability to drop announce queues to rnpath utility
+- Added announce rate information output to rnpath utility
+- Improved announce queue processing
+- Improved several documentation chapters
+- Improved logging output
+
+### 2022-04-28: RNS β 0.3.5
+
+This release brings major improvements and upgrades to Reticulum, along with better documentation and improved usability of the bundled utilities.
+
+**Changes**
+- Greatly improved convergence time. Even on huge networks, newly created destinations become globally reachable in less than a minute.
+- New announce propagation mechanism allows flexible scalability. Extremely slow network segments can now interconnect seamlessly with huge, high-bandwidth networks while still prioritising end-to-end connectivity for local nodes.
+- Reticulum can now scale to huge and complex networks with up to 128 hops, and billions of active endpoints.
+- Added virtual network segmentation for running multiple virtual networks over the same physical channel.
+- Added interface authentication for creating private access network interfaces and access points.
+- Updated documentation in accordance with current implementation of announce propagation mechanism.
+- Updated several outdated documentation chapters.
+- Added documentation for new interface features.
+- The output display of the rnstatus utility has been greatly improved.
+- Added ability to drop paths to the rnpath utility.
+- Added path table display to rnpath utility.
+- Added interface rate determination and estimation.
+- Added configurable bandwidth allocation for announce traffic.
+- Improved and cleaned logging output.
+- Various Transport optimisations.
+- Improved AutoInterface peering timing.
+- Updated manual in accordance with release.
+- Fixed a possible race condition in Transport startup when a local shared instance was restarted and apps reconnected.
+
+### 2022-03-28: RNS β 0.3.4
+
+This is a small maintenance release with a bugfix and some documentation and reliability improvements.
+
+**Changes**
+- Fixed https://github.com/markqvist/Reticulum/issues/18 that could potentially cause a routing loop if the API was used in an unintended way
+- Improved cryptography API compatibility
+- Improved documentation
+
+### 2022-02-26: RNS β 0.3.3
+
+This release adds major new functionality to Reticulum, including new connectivity options, improves stability, simplifies configuration and fixes a few bugs.
+
+**Improvements**
+ - Added the I2P Interface to Reticulum
+ - Added I2P tunneling support for TCP interfaces
+ - Improved recovery of AutoInterface on underlying medium carrier loss
+ - Improved AutoInterface timeouts and timing
+ - Enabled the "outbound" interface option as on by default
+ - Added the "Access Point" interface mode
+ - Simplified default configuration
+ - Added verbose configuration example to the "rnsd" program
+ - Improved documentation and manual
+ - Fixed a potential race condition in resource assembly
+ - Fixed a reference error in TCP interfaces
+ - Fixed a configuration keyword error
+
+### 2022-01-28: RNS β 0.3.2
+
+This maintenance release adds support for using a much wider range of devices as RNode LoRa interfaces with Reticulum, and also contains a few bugfixes and improvements.
+
+**Important!** From this release, RNodes used with Reticulum must have at least firmware version 1.26 installed, due to the new multiplatform RNode support.
+
+**Improvements**
+ - Added full support for RNodes based on ESP32 and ATmega2560 boards
+ - Fixed a bug in TCP interfaces on macOS
+ - Updated documentation and manual
+
+### 2022-01-26: RNS β 0.3.1
+
+This is a small maintenance and update release of Reticulum, including a few improvements. It also adds support for using ESP32-based T-Beam devices.
+
+Improvements:
+ - Added support for using T-Beam devices using the RNodeInterface
+ - Improved AutoInterface on Android
+ - Improved platform handling
+ - Improved malformed packet handling
+
+### 2021-12-11: RNS β 0.3.0
+
+This is a major release of Reticulum, including a range of stability and performance improvements, along with important new features, expanding the connectivity of Reticulum.
+
+An important improvement in this release is the addition of the AutoInterface, that will now be configured as the default interface on new installs. This interface automatically meshes with other Reticulum peers over any available system network devices, and doesn't require any existing IP infrastructure like a DHCP server or a router. For more information, consult the relevant section of the manual.
+
+**Improvements**
+ - Added new AutoInterface as default interface for new installs
+ - Serial port interfaces now automatically attempt to reconnect devices that are unplugged and replugged
+ - Added support for KISS over TCP in the TCPClientInterface
+ - Added support for running Reticulum as a systemd service
+ - Initial support for the Android operating system
+ - Added documentation for installing Reticulum on Android in Termux
+ - Improved documentation and manual
+ - Better path request handling for shared instances
+ - Better shutdown handling on external interrupts
+ - Many small stability and reliability improvements
+ - Fine-tuned various timing parameters for different link types
+
+### 2021-10-15: RNS β 0.2.9
+
+This beta release adds the fundamentals of RSSI and SNR functionality. It also implements timing improvements, allowing Reticulum to function on even lower bitrate physical links.
+
+**Improvements**
+ - Added RSSI and SNR reporting on supported interfaces
+ - Added RSSI and SNR to rnprobe utility
+ - Added RSSI and SNR to Echo example
+ - Support for physical layer throughput down to 500 bits per second.
+ - Improved callback handling
+
+### 2021-10-10: RNS β 0.2.8
+
+This beta release brings a single, but important improvement. Paths are now updated much more fluidly for peers moving around the network.
+
+Since updates were made to how tunnels and path table entries are represented in this release, it is recommended to delete the following files on Transport Nodes:
+
+~/.reticulum/storage/destination_table
+~/.reticulum/storage/packet_hashlist
+~/.reticulum/storage/tunnels
+~/.reticulum/storage/cache/*
+
+The files will be recreated when Reticulum is started.
+
+**Improvements**
+ - Improved path updates for peers moving around the network
+
+### 2021-10-08: RNS β 0.2.7
+
+This beta release brings a range of stability improvements and one bugfix.
+
+**Improvements**
+ - Improved output of the rnstatus utility
+ - Improved shared instance and local client handling
+ - Improved documentation
+ - Improved path restoration on tunnels
+ - Added log rotation
+
+**Fixed bugs**
+ - Fixed incorrect interface detachment on TCP client interfaces
+
+### 2021-09-25: RNS β 0.2.6
+
+This beta release brings a range of improvements and a few bugfixes.
+
+**Improvements**
+ - Added the "rnsd" utility for running Reticulum as a service
+ - Added the "rnstatus" utility for viewing interface status
+ - Added the "rnpath" utility for path lookups
+ - Added the "rnprobe" utility for testing connectivity
+ - Documentation has been improved and expanded
+ - Improved shutdown handling for shared instances
+ - Improved default configuration
+ - Improved recovery of TCP interfaces over unreliable links
+
+**Fixed bugs**
+ - Fixed a bug in reverse table culling
+ - Fixed a regression in TCP interface client spawner
+
+### 2021-09-18: RNS β 0.2.5
+
+This beta release brings a range of improvements and bugfixes.
+
+**Improvements**
+ - Added endpoint tunneling for path restoration over intermittent or roving link layer connections.
+ - Added ability for TCP client interfaces to automatically reconnect if TCP socket drops.
+ - Improved link teardown handling.
+ - Improved interface error handling on non-recoverable / hardware errors.
+
+**Fixed bugs**
+ - Fixed a bug that could cause path table entries to be culled two times in rare cases.
+ - Fixed a bug that could lead to the "outgoing" directive of interface configuration entries not being parsed correctly.
+
+### 2021-09-11: RNS β 0.2.4
+
+This beta release brings a range of improvements and bugfixes.
+
+**Improvements**
+ - Increased link MDU from 415 to 431 bytes by optimising transfer of Fernet tokens.
+ - All data lengths are now calculated dynamically from Reticulums base MTU, laying the groundwork for dynamic MTU interoperability.
+ - Disabled option to allow unencrypted links.
+ - Improved documentation.
+ - Improved request timeouts and handling.
+ - Improved link establishment.
+ - Improved resource transfer timing. 
+
+**Fixed bugs**
+ - Fixed a race condition in inbound proof handling.
+ - Fixed sequencing errors caused by duplicate HMU/request packets not being filtered.
+
+### 2021-08-29: RNS β 0.2.3
+
+This beta release brings a range of improvements and bugfixes.
+
+**Improvements**
+ - Improved resource handling.
+ - Improved timeout calculation for packets, links, resources and requests.
+ - Improved announce handling for shared instances.
+ - Improved default configuration template.
+ - Added example "Speedtest".
+
+**Fixed bugs**
+ - Fixed an issue that caused request timeout even though response had occurred.
+ - Fixed an issue that caused identity files to be written incorrectly.
+ - Fixed resource sequencing errors not being handled gracefully.
+
+### 2021-08-21: RNS β 0.2.2
+
+This beta release brings several new features to Reticulum along with two bugfixes.
+
+IMPORTANT! This version breaks wire-format compatibility with all previous versions of Reticulum. You must update *all* of your nodes at the same time.
+
+**New features**
+ - Link initiators can now identify to the remote peer over the link, once it has been set up. This can be used for authentication, amongst other things.
+ - Requests and responses of arbitrary sizes can now be carried out over links.
+ - UDP and TCP interfaces can now be bound to network device names (eth0, wlan0, etc.) instead of manually specifying listen IPs.
+
+**Fixed bugs**
+ - Fixed a race condition in outbound transport packet filtering.
+ - Fixed an issue where local UDP broadcast echoes could get processed as inbound packets.
+
+### 2021-05-20: RNS β 0.2.1
+
+This beta release sees significant improvements to bandwidth utilization and efficiency, while improving security by dropping RSA and moving completely to Curve25519.
+
+- All asymmetric cryptography migrated to X25519/Ed25519. This has greatly improved efficiency and reduced protocol overhead significantly.
+- Work has continued on the documentation, and the "Understanding Reticulum" chapters have been improved significantly in this release.
+- Class methods dealing with setting callbacks have been renamed to be more intuitive.
+
+As a few examples of the improved efficiency, a complete link establishment now only costs 240 bytes, down from 409 in the previous RSA version. An announce takes up 151 bytes vs 323.
+
+### 2021-05-18: RNS β 0.2.0
+
+This is the first beta release of RNS. This release also marks the publication of the Reticulum documentation, manual, and API documentation. All core features of Reticulum are now implemented, functional and ready to use in external programs. The wire-format and API will only change if there is a very good reason, though internals are still likely to be altered and optimised, and features are likely to be added.
+
+### 2021-05-13: RNS α 0.1.9
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-08-13: RNS α 0.1.8
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-08-13: RNS α 0.1.7
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-06-10: RNS α 0.1.6
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-06-09: RNS α 0.1.5
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-05-29: RNS α 0.1.4
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-05-21: RNS α 0.1.3
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-05-15: RNS α 0.1.2
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-05-14: RNS α 0.1.1
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-05-12: RNS α 0.1.0
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-04-28: RNS α 0.0.9
+
+This was a pre-release alpha version. No changelog available.
+
+### 2020-04-28: RNS α 0.0.8
+
+This was the first publicly available pre-release alpha of Reticulum.
+
+### 2016-05-29: Inintial Repository Commit
+
+The first commit to the Reticulum reference implementation was 9a9630cfd29e11ace3f12716ddb4dff0e5419b4b, which occurred on Sunday, the 22nd of May 2016.

Contributing.md

@@ -0,0 +1,23 @@
+# Contributing to Reticulum
+
+Welcome, and thank you for your interest in contributing to Reticulum!
+
+Apart from writing code, there are many ways in which you can contribute. Before getting started, please read these guidelines.
+
+## Asking Questions
+
+If you want to ask a question, do not open an issue.
+
+Instead, ask away on the [discussions](https://github.com/markqvist/Reticulum/discussions) or on the [Reticulum Matrix channel](https://unsigned.io/contact.html#reticulum:matrix.org) at `#reticulum:matrix.org`
+
+## Providing Feedback
+
+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://unsigned.io/contact.html#reticulum:matrix.org) at `#reticulum:matrix.org`
+
+## Reporting Issues
+
+If you have found a bug or issue in Reticulum, please report it on the [issue tracker](https://github.com/markqvist/Reticulum/issues).
+
+## Writing Code
+
+If you are interested in contributing code, fixing open issues or adding features, please coordinate the effort with the maintainer or one of the main developers first, to ensure your efforts are in alignment with the [Roadmap](./Roadmap.md) and current development focus.

Examples/Buffer.py

@@ -0,0 +1,323 @@
+##########################################################
+# This RNS example demonstrates how to set up a link to  #
+# a destination, and pass binary data over it using a    #
+# channel buffer.                                        #
+##########################################################
+from __future__ import annotations
+import os
+import sys
+import time
+import argparse
+from datetime import datetime
+
+import RNS
+from RNS.vendor import umsgpack
+
+# Let's define an app name. We'll use this for all
+# destinations we create. Since this echo example
+# is part of a range of example utilities, we'll put
+# them all within the app namespace "example_utilities"
+APP_NAME = "example_utilities"
+
+
+##########################################################
+#### Server Part #########################################
+##########################################################
+
+# A reference to the latest client link that connected
+latest_client_link = None
+
+# A reference to the latest buffer object
+latest_buffer = None
+
+# This initialisation is executed when the users chooses
+# to run as a server
+def server(configpath):
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
+    
+    # Randomly create a new identity for our example
+    server_identity = RNS.Identity()
+
+    # We create a destination that clients can connect to. We
+    # want clients to create links to this destination, so we
+    # need to create a "single" destination type.
+    server_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.IN,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "bufferexample"
+    )
+
+    # We configure a function that will get called every time
+    # a new client creates a link to this destination.
+    server_destination.set_link_established_callback(client_connected)
+
+    # Everything's ready!
+    # Let's Wait for client requests or user input
+    server_loop(server_destination)
+
+def server_loop(destination):
+    # Let the user know that everything is ready
+    RNS.log(
+        "Link buffer example "+
+        RNS.prettyhexrep(destination.hash)+
+        " running, waiting for a connection."
+    )
+
+    RNS.log("Hit enter to manually send an announce (Ctrl-C to quit)")
+
+    # We enter a loop that runs until the users exits.
+    # If the user hits enter, we will announce our server
+    # destination on the network, which will let clients
+    # know how to create messages directed towards it.
+    while True:
+        entered = input()
+        destination.announce()
+        RNS.log("Sent announce from "+RNS.prettyhexrep(destination.hash))
+
+# When a client establishes a link to our server
+# destination, this function will be called with
+# a reference to the link.
+def client_connected(link):
+    global latest_client_link, latest_buffer
+    latest_client_link = link
+
+    RNS.log("Client connected")
+    link.set_link_closed_callback(client_disconnected)
+
+    # If a new connection is received, the old reader
+    # needs to be disconnected.
+    if latest_buffer:
+        latest_buffer.close()
+
+
+    # Create buffer objects.
+    #   The stream_id parameter to these functions is
+    #   a bit like a file descriptor, except that it
+    #   is unique to the *receiver*.
+    #
+    #   In this example, both the reader and the writer
+    #   use stream_id = 0, but there are actually two
+    #   separate unidirectional streams flowing in
+    #   opposite directions.
+    #
+    channel = link.get_channel()
+    latest_buffer = RNS.Buffer.create_bidirectional_buffer(0, 0, channel, server_buffer_ready)
+
+def client_disconnected(link):
+    RNS.log("Client disconnected")
+
+def server_buffer_ready(ready_bytes: int):
+    """
+    Callback from buffer when buffer has data available
+
+    :param ready_bytes: The number of bytes ready to read
+    """
+    global latest_buffer
+
+    data = latest_buffer.read(ready_bytes)
+    data = data.decode("utf-8")
+
+    RNS.log("Received data over the buffer: " + data)
+
+    reply_message = "I received \""+data+"\" over the buffer"
+    reply_message = reply_message.encode("utf-8")
+    latest_buffer.write(reply_message)
+    latest_buffer.flush()
+
+
+
+
+##########################################################
+#### Client Part #########################################
+##########################################################
+
+# A reference to the server link
+server_link = None
+
+# A reference to the buffer object, needed to share the
+# object from the link connected callback to the client
+# loop.
+buffer = None
+
+# This initialisation is executed when the users chooses
+# to run as a client
+def client(destination_hexhash, configpath):
+    # We need a binary representation of the destination
+    # hash that was entered on the command line
+    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)
+            )
+            
+        destination_hash = bytes.fromhex(destination_hexhash)
+    except:
+        RNS.log("Invalid destination entered. Check your input!\n")
+        exit()
+
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
+
+    # Check if we know a path to the destination
+    if not RNS.Transport.has_path(destination_hash):
+        RNS.log("Destination is not yet known. Requesting path and waiting for announce to arrive...")
+        RNS.Transport.request_path(destination_hash)
+        while not RNS.Transport.has_path(destination_hash):
+            time.sleep(0.1)
+
+    # Recall the server identity
+    server_identity = RNS.Identity.recall(destination_hash)
+
+    # Inform the user that we'll begin connecting
+    RNS.log("Establishing link with server...")
+
+    # When the server identity is known, we set
+    # up a destination
+    server_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.OUT,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "bufferexample"
+    )
+
+    # And create a link
+    link = RNS.Link(server_destination)
+
+    # We'll also set up functions to inform the
+    # user when the link is established or closed
+    link.set_link_established_callback(link_established)
+    link.set_link_closed_callback(link_closed)
+
+    # Everything is set up, so let's enter a loop
+    # for the user to interact with the example
+    client_loop()
+
+def client_loop():
+    global server_link
+
+    # Wait for the link to become active
+    while not server_link:
+        time.sleep(0.1)
+
+    should_quit = False
+    while not should_quit:
+        try:
+            print("> ", end=" ")
+            text = input()
+
+            # Check if we should quit the example
+            if text == "quit" or text == "q" or text == "exit":
+                should_quit = True
+                server_link.teardown()
+            else:
+                # Otherwise, encode the text and write it to the buffer.
+                text = text.encode("utf-8")
+                buffer.write(text)
+                # Flush the buffer to force the data to be sent.
+                buffer.flush()
+
+
+        except Exception as e:
+            RNS.log("Error while sending data over the link buffer: "+str(e))
+            should_quit = True
+            server_link.teardown()
+
+# This function is called when a link
+# has been established with the server
+def link_established(link):
+    # We store a reference to the link
+    # instance for later use
+    global server_link, buffer
+    server_link = link
+
+    # Create buffer, see server_client_connected() for
+    # more detail about setting up the buffer.
+    channel = link.get_channel()
+    buffer = RNS.Buffer.create_bidirectional_buffer(0, 0, channel, client_buffer_ready)
+
+    # Inform the user that the server is
+    # connected
+    RNS.log("Link established with server, enter some text to send, or \"quit\" to quit")
+
+# When a link is closed, we'll inform the
+# user, and exit the program
+def link_closed(link):
+    if link.teardown_reason == RNS.Link.TIMEOUT:
+        RNS.log("The link timed out, exiting now")
+    elif link.teardown_reason == RNS.Link.DESTINATION_CLOSED:
+        RNS.log("The link was closed by the server, exiting now")
+    else:
+        RNS.log("Link closed, exiting now")
+    
+    RNS.Reticulum.exit_handler()
+    time.sleep(1.5)
+    os._exit(0)
+
+# When the buffer has new data, read it and write it to the terminal.
+def client_buffer_ready(ready_bytes: int):
+    global buffer
+    data = buffer.read(ready_bytes)
+    RNS.log("Received data over the link buffer: " + data.decode("utf-8"))
+    print("> ", end=" ")
+    sys.stdout.flush()
+
+
+##########################################################
+#### Program Startup #####################################
+##########################################################
+
+# This part of the program runs at startup,
+# and parses input of from the user, and then
+# starts up the desired program mode.
+if __name__ == "__main__":
+    try:
+        parser = argparse.ArgumentParser(description="Simple buffer example")
+
+        parser.add_argument(
+            "-s",
+            "--server",
+            action="store_true",
+            help="wait for incoming link requests from clients"
+        )
+
+        parser.add_argument(
+            "--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
+
+        parser.add_argument(
+            "destination",
+            nargs="?",
+            default=None,
+            help="hexadecimal hash of the server destination",
+            type=str
+        )
+
+        args = parser.parse_args()
+
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        if args.server:
+            server(configarg)
+        else:
+            if (args.destination == None):
+                print("")
+                parser.print_help()
+                print("")
+            else:
+                client(args.destination, configarg)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()

Examples/Channel.py

@@ -0,0 +1,390 @@
+##########################################################
+# This RNS example demonstrates how to set up a link to  #
+# a destination, and pass structured messages over it    #
+# using a channel.                                       #
+##########################################################
+
+import os
+import sys
+import time
+import argparse
+from datetime import datetime
+
+import RNS
+from RNS.vendor import umsgpack
+
+# Let's define an app name. We'll use this for all
+# destinations we create. Since this echo example
+# is part of a range of example utilities, we'll put
+# them all within the app namespace "example_utilities"
+APP_NAME = "example_utilities"
+
+##########################################################
+#### Shared Objects ######################################
+##########################################################
+
+# Channel data must be structured in a subclass of
+# MessageBase. This ensures that the channel will be able
+# to serialize and deserialize the object and multiplex it
+# with other objects. Both ends of a link will need the
+# same object definitions to be able to communicate over
+# a channel.
+#
+# Note: The objects we wish to use over the channel must
+# be registered with the channel, and each link has a
+# different channel instance. See the client_connected
+# and link_established functions in this example to see
+# how message types are registered.
+
+# Let's make a simple message class called StringMessage
+# that will convey a string with a timestamp.
+
+class StringMessage(RNS.MessageBase):
+    # The MSGTYPE class variable needs to be assigned a
+    # 2 byte integer value. This identifier allows the
+    # channel to look up your message's constructor when a
+    # message arrives over the channel.
+    #
+    # MSGTYPE must be unique across all message types we
+    # register with the channel. MSGTYPEs >= 0xf000 are
+    # reserved for the system.
+    MSGTYPE = 0x0101
+
+    # The constructor of our object must be callable with
+    # no arguments. We can have parameters, but they must
+    # have a default assignment.
+    #
+    # This is needed so the channel can create an empty
+    # version of our message into which the incoming
+    # message can be unpacked.
+    def __init__(self, data=None):
+        self.data = data
+        self.timestamp = datetime.now()
+
+    # Finally, our message needs to implement functions
+    # the channel can call to pack and unpack our message
+    # to/from the raw packet payload. We'll use the
+    # umsgpack package bundled with RNS. We could also use
+    # the struct package bundled with Python if we wanted
+    # more control over the structure of the packed bytes.
+    #
+    # Also note that packed message objects must fit
+    # entirely in one packet. The number of bytes
+    # available for message payloads can be queried from
+    # the channel using the Channel.MDU property. The
+    # channel MDU is slightly less than the link MDU due
+    # to encoding the message header.
+
+    # The pack function encodes the message contents into
+    # a byte stream.
+    def pack(self) -> bytes:
+        return umsgpack.packb((self.data, self.timestamp))
+
+    # And the unpack function decodes a byte stream into
+    # the message contents.
+    def unpack(self, raw):
+        self.data, self.timestamp = umsgpack.unpackb(raw)
+
+
+##########################################################
+#### Server Part #########################################
+##########################################################
+
+# A reference to the latest client link that connected
+latest_client_link = None
+
+# This initialisation is executed when the users chooses
+# to run as a server
+def server(configpath):
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
+    
+    # Randomly create a new identity for our link example
+    server_identity = RNS.Identity()
+
+    # We create a destination that clients can connect to. We
+    # want clients to create links to this destination, so we
+    # need to create a "single" destination type.
+    server_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.IN,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "channelexample"
+    )
+
+    # We configure a function that will get called every time
+    # a new client creates a link to this destination.
+    server_destination.set_link_established_callback(client_connected)
+
+    # Everything's ready!
+    # Let's Wait for client requests or user input
+    server_loop(server_destination)
+
+def server_loop(destination):
+    # Let the user know that everything is ready
+    RNS.log(
+        "Link example "+
+        RNS.prettyhexrep(destination.hash)+
+        " running, waiting for a connection."
+    )
+
+    RNS.log("Hit enter to manually send an announce (Ctrl-C to quit)")
+
+    # We enter a loop that runs until the users exits.
+    # If the user hits enter, we will announce our server
+    # destination on the network, which will let clients
+    # know how to create messages directed towards it.
+    while True:
+        entered = input()
+        destination.announce()
+        RNS.log("Sent announce from "+RNS.prettyhexrep(destination.hash))
+
+# When a client establishes a link to our server
+# destination, this function will be called with
+# a reference to the link.
+def client_connected(link):
+    global latest_client_link
+    latest_client_link = link
+
+    RNS.log("Client connected")
+    link.set_link_closed_callback(client_disconnected)
+
+    # Register message types and add callback to channel
+    channel = link.get_channel()
+    channel.register_message_type(StringMessage)
+    channel.add_message_handler(server_message_received)
+
+def client_disconnected(link):
+    RNS.log("Client disconnected")
+
+def server_message_received(message):
+    """
+    A message handler
+    @param message: An instance of a subclass of MessageBase
+    @return: True if message was handled
+    """
+    global latest_client_link
+    # When a message is received over any active link,
+    # the replies will all be directed to the last client
+    # that connected.
+
+    # In a message handler, any deserializable message
+    # that arrives over the link's channel will be passed
+    # to all message handlers, unless a preceding handler indicates it
+    # has handled the message.
+    #
+    #
+    if isinstance(message, StringMessage):
+        RNS.log("Received data on the link: " + message.data + " (message created at " + str(message.timestamp) + ")")
+
+        reply_message = StringMessage("I received \""+message.data+"\" over the link")
+        latest_client_link.get_channel().send(reply_message)
+
+        # Incoming messages are sent to each message
+        # handler added to the channel, in the order they
+        # were added.
+        # If any message handler returns True, the message
+        # is considered handled and any subsequent
+        # handlers are skipped.
+        return True
+
+
+##########################################################
+#### Client Part #########################################
+##########################################################
+
+# A reference to the server link
+server_link = None
+
+# This initialisation is executed when the users chooses
+# to run as a client
+def client(destination_hexhash, configpath):
+    # We need a binary representation of the destination
+    # hash that was entered on the command line
+    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)
+            )
+            
+        destination_hash = bytes.fromhex(destination_hexhash)
+    except:
+        RNS.log("Invalid destination entered. Check your input!\n")
+        exit()
+
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
+
+    # Check if we know a path to the destination
+    if not RNS.Transport.has_path(destination_hash):
+        RNS.log("Destination is not yet known. Requesting path and waiting for announce to arrive...")
+        RNS.Transport.request_path(destination_hash)
+        while not RNS.Transport.has_path(destination_hash):
+            time.sleep(0.1)
+
+    # Recall the server identity
+    server_identity = RNS.Identity.recall(destination_hash)
+
+    # Inform the user that we'll begin connecting
+    RNS.log("Establishing link with server...")
+
+    # When the server identity is known, we set
+    # up a destination
+    server_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.OUT,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "channelexample"
+    )
+
+    # And create a link
+    link = RNS.Link(server_destination)
+
+    # We'll also set up functions to inform the
+    # user when the link is established or closed
+    link.set_link_established_callback(link_established)
+    link.set_link_closed_callback(link_closed)
+
+    # Everything is set up, so let's enter a loop
+    # for the user to interact with the example
+    client_loop()
+
+def client_loop():
+    global server_link
+
+    # Wait for the link to become active
+    while not server_link:
+        time.sleep(0.1)
+
+    should_quit = False
+    while not should_quit:
+        try:
+            print("> ", end=" ")
+            text = input()
+
+            # Check if we should quit the example
+            if text == "quit" or text == "q" or text == "exit":
+                should_quit = True
+                server_link.teardown()
+
+            # If not, send the entered text over the link
+            if text != "":
+                message = StringMessage(text)
+                packed_size = len(message.pack())
+                channel = server_link.get_channel()
+                if channel.is_ready_to_send():
+                    if packed_size <= channel.MDU:
+                        channel.send(message)
+                    else:
+                        RNS.log(
+                            "Cannot send this packet, the data size of "+
+                            str(packed_size)+" bytes exceeds the link packet MDU of "+
+                            str(channel.MDU)+" bytes",
+                            RNS.LOG_ERROR
+                        )
+                else:
+                    RNS.log("Channel is not ready to send, please wait for " +
+                            "pending messages to complete.", RNS.LOG_ERROR)
+
+        except Exception as e:
+            RNS.log("Error while sending data over the link: "+str(e))
+            should_quit = True
+            server_link.teardown()
+
+# This function is called when a link
+# has been established with the server
+def link_established(link):
+    # We store a reference to the link
+    # instance for later use
+    global server_link
+    server_link = link
+
+    # Register messages and add handler to channel
+    channel = link.get_channel()
+    channel.register_message_type(StringMessage)
+    channel.add_message_handler(client_message_received)
+
+    # Inform the user that the server is
+    # connected
+    RNS.log("Link established with server, enter some text to send, or \"quit\" to quit")
+
+# When a link is closed, we'll inform the
+# user, and exit the program
+def link_closed(link):
+    if link.teardown_reason == RNS.Link.TIMEOUT:
+        RNS.log("The link timed out, exiting now")
+    elif link.teardown_reason == RNS.Link.DESTINATION_CLOSED:
+        RNS.log("The link was closed by the server, exiting now")
+    else:
+        RNS.log("Link closed, exiting now")
+    
+    RNS.Reticulum.exit_handler()
+    time.sleep(1.5)
+    os._exit(0)
+
+# When a packet is received over the channel, we
+# simply print out the data.
+def client_message_received(message):
+    if isinstance(message, StringMessage):
+        RNS.log("Received data on the link: " + message.data + " (message created at " + str(message.timestamp) + ")")
+        print("> ", end=" ")
+        sys.stdout.flush()
+
+
+##########################################################
+#### Program Startup #####################################
+##########################################################
+
+# This part of the program runs at startup,
+# and parses input of from the user, and then
+# starts up the desired program mode.
+if __name__ == "__main__":
+    try:
+        parser = argparse.ArgumentParser(description="Simple channel example")
+
+        parser.add_argument(
+            "-s",
+            "--server",
+            action="store_true",
+            help="wait for incoming link requests from clients"
+        )
+
+        parser.add_argument(
+            "--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
+
+        parser.add_argument(
+            "destination",
+            nargs="?",
+            default=None,
+            help="hexadecimal hash of the server destination",
+            type=str
+        )
+
+        args = parser.parse_args()
+
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        if args.server:
+            server(configarg)
+        else:
+            if (args.destination == None):
+                print("")
+                parser.print_help()
+                print("")
+            else:
+                client(args.destination, configarg)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()

Examples/Echo.py

@@ -210,6 +210,7 @@ def client(destination_hexhash, configpath, timeout=None):
             # If we do not know this destination, tell the
             # user to wait for an announce to arrive.
             RNS.log("Destination is not yet known. Requesting path...")
+            RNS.log("Hit enter to manually retry once an announce is received.")
             RNS.Transport.request_path(destination_hash)
 
 # This function is called when our reply destination

Examples/Request.py

@@ -23,8 +23,8 @@ APP_NAME = "example_utilities"
 # A reference to the latest client link that connected
 latest_client_link = None
 
-def random_text_generator(path, data, request_id, remote_identity, requested_at):
-    RNS.log("Generating response to request "+RNS.prettyhexrep(request_id))
+def random_text_generator(path, data, request_id, link_id, remote_identity, requested_at):
+    RNS.log("Generating response to request "+RNS.prettyhexrep(request_id)+" on link "+RNS.prettyhexrep(link_id))
     texts = ["They looked up", "On each full moon", "Becky was upset", "I’ll stay away from it", "The pet shop stocks everything"]
     return texts[random.randint(0, len(texts)-1)]
 

Makefile

@@ -47,7 +47,7 @@ documentation:
 	make -C docs html
 
 manual:
-	make -C docs latexpdf
+	make -C docs latexpdf epub
 
 release: test remove_symlinks build_wheel build_pure_wheel documentation manual create_symlinks
 

README.md

@@ -37,7 +37,7 @@ The full documentation for Reticulum is available at [markqvist.github.io/Reticu
 
 You can also [download the Reticulum manual as a PDF](https://github.com/markqvist/Reticulum/raw/master/docs/Reticulum%20Manual.pdf)
 
-For more info, see [unsigned.io/projects/reticulum](https://unsigned.io/projects/reticulum/)
+For more info, see [reticulum.network](https://reticulum.network/)
 
 ## Notable Features
 - Coordination-less globally unique addressing and identification
@@ -62,10 +62,16 @@ For more info, see [unsigned.io/projects/reticulum](https://unsigned.io/projects
   - Total bandwidth cost of setting up an encrypted link is 3 packets totaling 297 bytes
   - Low cost of keeping links open at only 0.44 bits per second
 
+## 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.
+
+To learn more about the direction and future of Reticulum, please see the [Development Roadmap](./Roadmap.md).
+
 ## Examples of Reticulum Applications
 If you want to quickly get an idea of what Reticulum can do, take a look at the
 following resources.
 
+- You can use the [rnsh](https://github.com/acehoss/rnsh) program to establish remote shell sessions over Reticulum.
 - For an off-grid, encrypted and resilient mesh communications platform, see [Nomad Network](https://github.com/markqvist/NomadNet)
 - The Android, Linux and macOS app [Sideband](https://github.com/markqvist/Sideband) has a graphical interface and focuses on ease of use.
 - [LXMF](https://github.com/markqvist/lxmf) is a distributed, delay and disruption tolerant message transfer protocol built on Reticulum
@@ -151,7 +157,7 @@ useful.
 Currently, the following interfaces are supported:
 
 - Any Ethernet device
-- LoRa using [RNode](https://unsigned.io/projects/rnode/)
+- LoRa using [RNode](https://unsigned.io/rnode/)
 - Packet Radio TNCs (with or without AX.25)
 - KISS-compatible hardware and software modems
 - Any device with a serial port
@@ -177,37 +183,6 @@ features are implemented and functioning, but additions will probably occur as
 real-world use is explored. There will be bugs. The API and wire-format can be
 considered relatively stable at the moment, but could change if warranted.
 
-## Development Roadmap
-- Improving [the manual](https://markqvist.github.io/Reticulum/manual/) with sections specifically for beginners
-- Performance and memory optimisations
-- Utilities for managing identities, signing and encryption
-- User friendly interface configuration tool
-- More interface types for even broader compatibility
-  - Plain ESP32 devices (ESP-Now, WiFi, Bluetooth, etc.)
-  - More LoRa transceivers
-  - IR Transceivers
-- OpenWRT support
-- Metric-based path selection
-- Distributed Destination Naming System
-- Network-wide path balancing
-- Globally routable multicast
-- Bindings for other programming languages
-- Multiple paths in path table for quick recovery on link failures
-- A portable Reticulum implementation in C, see [#21](https://github.com/markqvist/Reticulum/discussions/21)
-- Easy way to share interface configurations, see [#19](https://github.com/markqvist/Reticulum/discussions/19)
-- More interface types
-  - AT-compatible modems
-  - Optical mediums
-  - AWDL / OWL
-  - HF Modems
-  - CAN-bus
-  - ZeroMQ
-  - MQTT
-  - XBee
-  - SPI
-  - i²c
-  - Tor
-
 ## Dependencies
 The installation of the default `rns` package requires the dependencies listed
 below. Almost all systems and distributions have readily available packages for
@@ -271,7 +246,7 @@ file:
   [[RNS Testnet I2P Hub A]]
     type = I2PInterface
     enabled = yes
-    peers = mrwqlsioq4hoo2lmeeud7dkfscnm7yxak7dmiyvsrnpfag3z5tsq.b32.i2p
+    peers = pmlm3l5rpympihoy2o5ago43kluei2jjjzsalcuiuylbve3mwi2a.b32.i2p
 
 # Interface to I2P Hub B
   [[RNS Testnet I2P Hub B]]

RNS/Buffer.py

@@ -0,0 +1,291 @@
+from __future__ import annotations
+import sys
+import threading
+from threading import RLock
+import struct
+from RNS.Channel import Channel, MessageBase, SystemMessageTypes
+import RNS
+from io import RawIOBase, BufferedRWPair, BufferedReader, BufferedWriter
+from typing import Callable
+from contextlib import AbstractContextManager
+
+
+class StreamDataMessage(MessageBase):
+    MSGTYPE = SystemMessageTypes.SMT_STREAM_DATA
+    """
+    Message type for ``Channel``. ``StreamDataMessage``
+    uses a system-reserved message type.
+    """
+
+    STREAM_ID_MAX = 0x7fff  # 32767
+    """
+    The stream id is limited to 2 bytes - 1 bit
+    """
+
+    MAX_DATA_LEN = RNS.Link.MDU - 2 - 6  # 2 for stream data message header, 6 for channel envelope
+    """
+    When the Buffer package is imported, this value is
+    calculcated based on the value of OVERHEAD
+    """
+
+    def __init__(self, stream_id: int = None, data: bytes = None, eof: bool = False):
+        """
+        This class is used to encapsulate binary stream
+        data to be sent over a ``Channel``.
+
+        :param stream_id: id of stream relative to receiver
+        :param data: binary data
+        :param eof: set to True if signalling End of File
+        """
+        super().__init__()
+        if stream_id is not None and stream_id > self.STREAM_ID_MAX:
+            raise ValueError("stream_id must be 0-32767")
+        self.stream_id = stream_id
+        self.data = data or bytes()
+        self.eof = eof
+
+    def pack(self) -> bytes:
+        if self.stream_id is None:
+            raise ValueError("stream_id")
+        header_val = (0x7fff & self.stream_id) | (0x8000 if self.eof else 0x0000)
+        return bytes(struct.pack(">H", header_val) + (self.data if self.data else bytes()))
+
+    def unpack(self, raw):
+        self.stream_id = struct.unpack(">H", raw[:2])[0]
+        self.eof = (0x8000 & self.stream_id) > 0
+        self.stream_id = self.stream_id & 0x7fff
+        self.data = raw[2:]
+
+
+class RawChannelReader(RawIOBase, AbstractContextManager):
+    """
+    An implementation of RawIOBase that receives
+    binary stream data sent over a ``Channel``.
+
+      This class generally need not be instantiated directly.
+      Use :func:`RNS.Buffer.create_reader`,
+      :func:`RNS.Buffer.create_writer`, and
+      :func:`RNS.Buffer.create_bidirectional_buffer` functions
+      to create buffered streams with optional callbacks.
+
+      For additional information on the API of this
+      object, see the Python documentation for
+      ``RawIOBase``.
+    """
+    def __init__(self, stream_id: int, channel: Channel):
+        """
+        Create a raw channel reader.
+
+        :param stream_id: local stream id to receive at
+        :param channel: ``Channel`` object to receive from
+        """
+        self._stream_id = stream_id
+        self._channel = channel
+        self._lock = RLock()
+        self._buffer = bytearray()
+        self._eof = False
+        self._channel._register_message_type(StreamDataMessage, is_system_type=True)
+        self._channel.add_message_handler(self._handle_message)
+        self._listeners: [Callable[[int], None]] = []
+
+    def add_ready_callback(self, cb: Callable[[int], None]):
+        """
+        Add a function to be called when new data is available.
+        The function should have the signature ``(ready_bytes: int) -> None``
+
+        :param cb: function to call
+        """
+        with self._lock:
+            self._listeners.append(cb)
+
+    def remove_ready_callback(self, cb: Callable[[int], None]):
+        """
+        Remove a function added with :func:`RNS.RawChannelReader.add_ready_callback()`
+
+        :param cb: function to remove
+        """
+        with self._lock:
+            self._listeners.remove(cb)
+
+    def _handle_message(self, message: MessageBase):
+        if isinstance(message, StreamDataMessage):
+            if message.stream_id == self._stream_id:
+                with self._lock:
+                    if message.data is not None:
+                        self._buffer.extend(message.data)
+                    if message.eof:
+                        self._eof = True
+                    for listener in self._listeners:
+                        try:
+                            listener(len(self._buffer))
+                        except Exception as ex:
+                            RNS.log("Error calling RawChannelReader(" + str(self._stream_id) + ") callback: " + str(ex))
+                    return True
+        return False
+
+    def _read(self, __size: int) -> bytes | None:
+        with self._lock:
+            result = self._buffer[:__size]
+            self._buffer = self._buffer[__size:]
+            return result if len(result) > 0 or self._eof else None
+
+    def readinto(self, __buffer: bytearray) -> int | None:
+        ready = self._read(len(__buffer))
+        if ready is not None:
+            __buffer[:len(ready)] = ready
+        return len(ready) if ready is not None else None
+
+    def writable(self) -> bool:
+        return False
+
+    def seekable(self) -> bool:
+        return False
+
+    def readable(self) -> bool:
+        return True
+
+    def close(self):
+        with self._lock:
+            self._channel.remove_message_handler(self._handle_message)
+            self._listeners.clear()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+
+class RawChannelWriter(RawIOBase, AbstractContextManager):
+    """
+    An implementation of RawIOBase that receives
+    binary stream data sent over a channel.
+
+      This class generally need not be instantiated directly.
+      Use :func:`RNS.Buffer.create_reader`,
+      :func:`RNS.Buffer.create_writer`, and
+      :func:`RNS.Buffer.create_bidirectional_buffer` functions
+      to create buffered streams with optional callbacks.
+
+      For additional information on the API of this
+      object, see the Python documentation for
+      ``RawIOBase``.
+    """
+    def __init__(self, stream_id: int, channel: Channel):
+        """
+        Create a raw channel writer.
+
+        :param stream_id: remote stream id to sent do
+        :param channel: ``Channel`` object to send on
+        """
+        self._stream_id = stream_id
+        self._channel = channel
+        self._eof = False
+
+    def write(self, __b: bytes) -> int | None:
+        try:
+            chunk = bytes(__b[:StreamDataMessage.MAX_DATA_LEN])
+            message = StreamDataMessage(self._stream_id, chunk, self._eof)
+            self._channel.send(message)
+            return len(chunk)
+        except RNS.Channel.ChannelException as cex:
+            if cex.type != RNS.Channel.CEType.ME_LINK_NOT_READY:
+                raise
+        return 0
+
+    def close(self):
+        self._eof = True
+        self.write(bytes())
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+    def seekable(self) -> bool:
+        return False
+
+    def readable(self) -> bool:
+        return False
+
+    def writable(self) -> bool:
+        return True
+
+class Buffer:
+    """
+    Static functions for creating buffered streams that send
+    and receive over a ``Channel``.
+
+    These functions use ``BufferedReader``, ``BufferedWriter``,
+    and ``BufferedRWPair`` to add buffering to
+    ``RawChannelReader`` and ``RawChannelWriter``.
+    """
+    @staticmethod
+    def create_reader(stream_id: int, channel: Channel,
+                      ready_callback: Callable[[int], None] | None = None) -> BufferedReader:
+        """
+        Create a buffered reader that reads binary data sent
+        over a ``Channel``, with an optional callback when
+        new data is available.
+
+        Callback signature: ``(ready_bytes: int) -> None``
+
+        For more information on the reader-specific functions
+        of this object, see the Python documentation for
+        ``BufferedReader``
+
+        :param stream_id: the local stream id to receive from
+        :param channel: the channel to receive on
+        :param ready_callback: function to call when new data is available
+        :return: a BufferedReader object
+        """
+        reader = RawChannelReader(stream_id, channel)
+        if ready_callback:
+            reader.add_ready_callback(ready_callback)
+        return BufferedReader(reader)
+
+    @staticmethod
+    def create_writer(stream_id: int, channel: Channel) -> BufferedWriter:
+        """
+        Create a buffered writer that writes binary data over
+        a ``Channel``.
+
+        For more information on the writer-specific functions
+        of this object, see the Python documentation for
+        ``BufferedWriter``
+
+        :param stream_id: the remote stream id to send to
+        :param channel: the channel to send on
+        :return: a BufferedWriter object
+        """
+        writer = RawChannelWriter(stream_id, channel)
+        return BufferedWriter(writer)
+
+    @staticmethod
+    def create_bidirectional_buffer(receive_stream_id: int, send_stream_id: int, channel: Channel,
+                                    ready_callback: Callable[[int], None] | None = None) -> BufferedRWPair:
+        """
+        Create a buffered reader/writer pair that reads and
+        writes binary data over a ``Channel``, with an
+        optional callback when new data is available.
+
+        Callback signature: ``(ready_bytes: int) -> None``
+
+        For more information on the reader-specific functions
+        of this object, see the Python documentation for
+        ``BufferedRWPair``
+
+        :param receive_stream_id: the local stream id to receive at
+        :param send_stream_id:  the remote stream id to send to
+        :param channel: the channel to send and receive on
+        :param ready_callback: function to call when new data is available
+        :return: a BufferedRWPair object
+        """
+        reader = RawChannelReader(receive_stream_id, channel)
+        if ready_callback:
+            reader.add_ready_callback(ready_callback)
+        writer = RawChannelWriter(send_stream_id, channel)
+        return BufferedRWPair(reader, writer)

RNS/Channel.py

@@ -0,0 +1,541 @@
+# MIT License
+#
+# Copyright (c) 2016-2023 Mark Qvist / unsigned.io and contributors.
+#
+# 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 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 collections
+import enum
+import threading
+import time
+from types import TracebackType
+from typing import Type, Callable, TypeVar, Generic, NewType
+import abc
+import contextlib
+import struct
+import RNS
+from abc import ABC, abstractmethod
+TPacket = TypeVar("TPacket")
+
+class SystemMessageTypes(enum.IntEnum):
+    SMT_STREAM_DATA = 0xff00
+
+class ChannelOutletBase(ABC, Generic[TPacket]):
+    """
+    An abstract transport layer interface used by Channel.
+
+    DEPRECATED: This was created for testing; eventually
+    Channel will use Link or a LinkBase interface
+    directly.
+    """
+    @abstractmethod
+    def send(self, raw: bytes) -> TPacket:
+        raise NotImplemented()
+
+    @abstractmethod
+    def resend(self, packet: TPacket) -> TPacket:
+        raise NotImplemented()
+
+    @property
+    @abstractmethod
+    def mdu(self):
+        raise NotImplemented()
+
+    @property
+    @abstractmethod
+    def rtt(self):
+        raise NotImplemented()
+
+    @property
+    @abstractmethod
+    def is_usable(self):
+        raise NotImplemented()
+
+    @abstractmethod
+    def get_packet_state(self, packet: TPacket) -> MessageState:
+        raise NotImplemented()
+
+    @abstractmethod
+    def timed_out(self):
+        raise NotImplemented()
+
+    @abstractmethod
+    def __str__(self):
+        raise NotImplemented()
+
+    @abstractmethod
+    def set_packet_timeout_callback(self, packet: TPacket, callback: Callable[[TPacket], None] | None,
+                                    timeout: float | None = None):
+        raise NotImplemented()
+
+    @abstractmethod
+    def set_packet_delivered_callback(self, packet: TPacket, callback: Callable[[TPacket], None] | None):
+        raise NotImplemented()
+
+    @abstractmethod
+    def get_packet_id(self, packet: TPacket) -> any:
+        raise NotImplemented()
+
+
+class CEType(enum.IntEnum):
+    """
+    ChannelException type codes
+    """
+    ME_NO_MSG_TYPE      = 0
+    ME_INVALID_MSG_TYPE = 1
+    ME_NOT_REGISTERED   = 2
+    ME_LINK_NOT_READY   = 3
+    ME_ALREADY_SENT     = 4
+    ME_TOO_BIG          = 5
+
+
+class ChannelException(Exception):
+    """
+    An exception thrown by Channel, with a type code.
+    """
+    def __init__(self, ce_type: CEType, *args):
+        super().__init__(args)
+        self.type = ce_type
+
+
+class MessageState(enum.IntEnum):
+    """
+    Set of possible states for a Message
+    """
+    MSGSTATE_NEW       = 0
+    MSGSTATE_SENT      = 1
+    MSGSTATE_DELIVERED = 2
+    MSGSTATE_FAILED    = 3
+
+
+class MessageBase(abc.ABC):
+    """
+    Base type for any messages sent or received on a Channel.
+    Subclasses must define the two abstract methods as well as
+    the ``MSGTYPE`` class variable.
+    """
+    # MSGTYPE must be unique within all classes sent over a
+    # channel. Additionally, MSGTYPE > 0xf000 are reserved.
+    MSGTYPE = None
+    """
+    Defines a unique identifier for a message class.
+    
+    * Must be unique within all classes registered with a ``Channel``
+    * Must be less than ``0xf000``. Values greater than or equal to ``0xf000`` are reserved.
+    """
+
+    @abstractmethod
+    def pack(self) -> bytes:
+        """
+        Create and return the binary representation of the message
+
+        :return: binary representation of message
+        """
+        raise NotImplemented()
+
+    @abstractmethod
+    def unpack(self, raw: bytes):
+        """
+        Populate message from binary representation
+
+        :param raw: binary representation
+        """
+        raise NotImplemented()
+
+
+MessageCallbackType = NewType("MessageCallbackType", Callable[[MessageBase], bool])
+
+
+class Envelope:
+    """
+    Internal wrapper used to transport messages over a channel and
+    track its state within the channel framework.
+    """
+    def unpack(self, message_factories: dict[int, Type]) -> MessageBase:
+        msgtype, self.sequence, length = struct.unpack(">HHH", self.raw[:6])
+        raw = self.raw[6:]
+        ctor = message_factories.get(msgtype, None)
+        if ctor is None:
+            raise ChannelException(CEType.ME_NOT_REGISTERED, f"Unable to find constructor for Channel MSGTYPE {hex(msgtype)}")
+        message = ctor()
+        message.unpack(raw)
+        return message
+
+    def pack(self) -> bytes:
+        if self.message.__class__.MSGTYPE is None:
+            raise ChannelException(CEType.ME_NO_MSG_TYPE, f"{self.message.__class__} lacks MSGTYPE")
+        data = self.message.pack()
+        self.raw = struct.pack(">HHH", self.message.MSGTYPE, self.sequence, len(data)) + data
+        return self.raw
+
+    def __init__(self, outlet: ChannelOutletBase, message: MessageBase = None, raw: bytes = None, sequence: int = None):
+        self.ts = time.time()
+        self.id = id(self)
+        self.message = message
+        self.raw = raw
+        self.packet: TPacket = None
+        self.sequence = sequence
+        self.outlet = outlet
+        self.tries = 0
+        self.tracked = False
+
+
+class Channel(contextlib.AbstractContextManager):
+    """
+    Provides reliable delivery of messages over
+    a link.
+
+    ``Channel`` differs from ``Request`` and
+    ``Resource`` in some important ways:
+
+     **Continuous**
+        Messages can be sent or received as long as
+        the ``Link`` is open.
+     **Bi-directional**
+        Messages can be sent in either direction on
+        the ``Link``; neither end is the client or
+        server.
+     **Size-constrained**
+        Messages must be encoded into a single packet.
+
+    ``Channel`` is similar to ``Packet``, except that it
+    provides reliable delivery (automatic retries) as well
+    as a structure for exchanging several types of
+    messages over the ``Link``.
+
+    ``Channel`` is not instantiated directly, but rather
+    obtained from a ``Link`` with ``get_channel()``.
+    """
+    def __init__(self, outlet: ChannelOutletBase):
+        """
+
+        @param outlet:
+        """
+        self._outlet = outlet
+        self._lock = threading.RLock()
+        self._tx_ring: collections.deque[Envelope] = collections.deque()
+        self._rx_ring: collections.deque[Envelope] = collections.deque()
+        self._message_callbacks: [MessageCallbackType] = []
+        self._next_sequence = 0
+        self._message_factories: dict[int, Type[MessageBase]] = {}
+        self._max_tries = 5
+
+    def __enter__(self) -> Channel:
+        return self
+
+    def __exit__(self, __exc_type: Type[BaseException] | None, __exc_value: BaseException | None,
+                 __traceback: TracebackType | None) -> bool | None:
+        self._shutdown()
+        return False
+
+    def register_message_type(self, message_class: Type[MessageBase]):
+        """
+        Register a message class for reception over a ``Channel``.
+
+        Message classes must extend ``MessageBase``.
+
+        :param message_class: Class to register
+        """
+        self._register_message_type(message_class, is_system_type=False)
+
+    def _register_message_type(self, message_class: Type[MessageBase], *, is_system_type: bool = False):
+        with self._lock:
+            if not issubclass(message_class, MessageBase):
+                raise ChannelException(CEType.ME_INVALID_MSG_TYPE,
+                                       f"{message_class} is not a subclass of {MessageBase}.")
+            if message_class.MSGTYPE is None:
+                raise ChannelException(CEType.ME_INVALID_MSG_TYPE,
+                                       f"{message_class} has invalid MSGTYPE class attribute.")
+            if message_class.MSGTYPE >= 0xf000 and not is_system_type:
+                raise ChannelException(CEType.ME_INVALID_MSG_TYPE,
+                                       f"{message_class} has system-reserved message type.")
+            try:
+                message_class()
+            except Exception as ex:
+                raise ChannelException(CEType.ME_INVALID_MSG_TYPE,
+                                       f"{message_class} raised an exception when constructed with no arguments: {ex}")
+
+            self._message_factories[message_class.MSGTYPE] = message_class
+
+    def add_message_handler(self, callback: MessageCallbackType):
+        """
+        Add a handler for incoming messages. A handler
+        has the following signature:
+
+        ``(message: MessageBase) -> bool``
+
+        Handlers are processed in the order they are
+        added. If any handler returns True, processing
+        of the message stops; handlers after the
+        returning handler will not be called.
+
+        :param callback: Function to call
+        """
+        with self._lock:
+            if callback not in self._message_callbacks:
+                self._message_callbacks.append(callback)
+
+    def remove_message_handler(self, callback: MessageCallbackType):
+        """
+        Remove a handler added with ``add_message_handler``.
+
+        :param callback: handler to remove
+        """
+        with self._lock:
+            if callback in self._message_callbacks:
+                self._message_callbacks.remove(callback)
+
+    def _shutdown(self):
+        with self._lock:
+            self._message_callbacks.clear()
+            self._clear_rings()
+
+    def _clear_rings(self):
+        with self._lock:
+            for envelope in self._tx_ring:
+                if envelope.packet is not None:
+                    self._outlet.set_packet_timeout_callback(envelope.packet, None)
+                    self._outlet.set_packet_delivered_callback(envelope.packet, None)
+            self._tx_ring.clear()
+            self._rx_ring.clear()
+
+    def _emplace_envelope(self, envelope: Envelope, ring: collections.deque[Envelope]) -> bool:
+        with self._lock:
+            i = 0
+            for existing in ring:
+                if existing.sequence > envelope.sequence \
+                   and not existing.sequence // 2 > envelope.sequence:  # account for overflow
+                    ring.insert(i, envelope)
+                    return True
+                if existing.sequence == envelope.sequence:
+                    RNS.log(f"Envelope: Emplacement of duplicate envelope sequence.", RNS.LOG_EXTREME)
+                    return False
+                i += 1
+            envelope.tracked = True
+            ring.append(envelope)
+            return True
+
+    def _prune_rx_ring(self):
+        with self._lock:
+            # Implementation for fixed window = 1
+            stale = list(sorted(self._rx_ring, key=lambda env: env.sequence, reverse=True))[1:]
+            for env in stale:
+                env.tracked = False
+                self._rx_ring.remove(env)
+
+    def _run_callbacks(self, message: MessageBase):
+        with self._lock:
+            cbs = self._message_callbacks.copy()
+
+        for cb in cbs:
+            try:
+                if cb(message):
+                    return
+            except Exception as ex:
+                RNS.log(f"Channel: Error running message callback: {ex}", RNS.LOG_ERROR)
+
+    def _receive(self, raw: bytes):
+        try:
+            envelope = Envelope(outlet=self._outlet, raw=raw)
+            with self._lock:
+                message = envelope.unpack(self._message_factories)
+                prev_env = self._rx_ring[0] if len(self._rx_ring) > 0 else None
+                if prev_env and envelope.sequence != (prev_env.sequence + 1) % 0x10000:
+                    RNS.log("Channel: Out of order packet received", RNS.LOG_DEBUG)
+                    return
+                is_new = self._emplace_envelope(envelope, self._rx_ring)
+                self._prune_rx_ring()
+            if not is_new:
+                RNS.log("Channel: Duplicate message received", RNS.LOG_DEBUG)
+                return
+            RNS.log(f"Message received: {message}", RNS.LOG_DEBUG)
+            threading.Thread(target=self._run_callbacks, name="Message Callback", args=[message], daemon=True).start()
+        except Exception as ex:
+            RNS.log(f"Channel: Error receiving data: {ex}")
+
+    def is_ready_to_send(self) -> bool:
+        """
+        Check if ``Channel`` is ready to send.
+
+        :return: True if ready
+        """
+        if not self._outlet.is_usable:
+            RNS.log("Channel: Link is not usable.", RNS.LOG_EXTREME)
+            return False
+
+        with self._lock:
+            for envelope in self._tx_ring:
+                if envelope.outlet == self._outlet and (not envelope.packet
+                                                        or self._outlet.get_packet_state(envelope.packet) == MessageState.MSGSTATE_SENT):
+                    # TODO: Check if this should be enabled with some kind of
+                    # rate limiting, since it currently floods log output when
+                    # messages are waiting.
+                    # RNS.log("Channel: Link has a pending message.", RNS.LOG_EXTREME)
+                    return False
+        return True
+
+    def _packet_tx_op(self, packet: TPacket, op: Callable[[TPacket], bool]):
+        with self._lock:
+            envelope = next(filter(lambda e: self._outlet.get_packet_id(e.packet) == self._outlet.get_packet_id(packet),
+                                   self._tx_ring), None)
+            if envelope and op(envelope):
+                envelope.tracked = False
+                if envelope in self._tx_ring:
+                    self._tx_ring.remove(envelope)
+                else:
+                    RNS.log("Channel: Envelope not found in TX ring", RNS.LOG_DEBUG)
+        if not envelope:
+            RNS.log("Channel: Spurious message received.", RNS.LOG_EXTREME)
+
+    def _packet_delivered(self, packet: TPacket):
+        self._packet_tx_op(packet, lambda env: True)
+
+    def _get_packet_timeout_time(self, tries: int) -> float:
+        return pow(2, tries - 1) * max(self._outlet.rtt, 0.01) * 5
+
+    def _packet_timeout(self, packet: TPacket):
+        def retry_envelope(envelope: Envelope) -> bool:
+            if envelope.tries >= self._max_tries:
+                RNS.log("Channel: Retry count exceeded, tearing down Link.", RNS.LOG_ERROR)
+                self._shutdown()  # start on separate thread?
+                self._outlet.timed_out()
+                return True
+            envelope.tries += 1
+            self._outlet.resend(envelope.packet)
+            self._outlet.set_packet_timeout_callback(envelope.packet, self._packet_timeout, self._get_packet_timeout_time(envelope.tries))
+            return False
+
+        if self._outlet.get_packet_state(packet) != MessageState.MSGSTATE_DELIVERED:
+            self._packet_tx_op(packet, retry_envelope)
+
+    def send(self, message: MessageBase) -> Envelope:
+        """
+        Send a message. If a message send is attempted and
+        ``Channel`` is not ready, an exception is thrown.
+
+        :param message: an instance of a ``MessageBase`` subclass
+        """
+        envelope: Envelope | None = None
+        with self._lock:
+            if not self.is_ready_to_send():
+                raise ChannelException(CEType.ME_LINK_NOT_READY, f"Link is not ready")
+            envelope = Envelope(self._outlet, message=message, sequence=self._next_sequence)
+            self._next_sequence = (self._next_sequence + 1) % 0x10000
+            self._emplace_envelope(envelope, self._tx_ring)
+        if envelope is None:
+            raise BlockingIOError()
+
+        envelope.pack()
+        if len(envelope.raw) > self._outlet.mdu:
+            raise ChannelException(CEType.ME_TOO_BIG, f"Packed message too big for packet: {len(envelope.raw)} > {self._outlet.mdu}")
+        envelope.packet = self._outlet.send(envelope.raw)
+        envelope.tries += 1
+        self._outlet.set_packet_delivered_callback(envelope.packet, self._packet_delivered)
+        self._outlet.set_packet_timeout_callback(envelope.packet, self._packet_timeout, self._get_packet_timeout_time(envelope.tries))
+        return envelope
+
+    @property
+    def MDU(self):
+        """
+        Maximum Data Unit: the number of bytes available
+        for a message to consume in a single send. This
+        value is adjusted from the ``Link`` MDU to accommodate
+        message header information.
+
+        :return: number of bytes available
+        """
+        return self._outlet.mdu - 6  # sizeof(msgtype) + sizeof(length) + sizeof(sequence)
+
+
+class LinkChannelOutlet(ChannelOutletBase):
+    """
+    An implementation of ChannelOutletBase for RNS.Link.
+    Allows Channel to send packets over an RNS Link with
+    Packets.
+
+    :param link: RNS Link to wrap
+    """
+    def __init__(self, link: RNS.Link):
+        self.link = link
+
+    def send(self, raw: bytes) -> RNS.Packet:
+        packet = RNS.Packet(self.link, raw, context=RNS.Packet.CHANNEL)
+        if self.link.status == RNS.Link.ACTIVE:
+            packet.send()
+        return packet
+
+    def resend(self, packet: RNS.Packet) -> RNS.Packet:
+        RNS.log("Resending packet " + RNS.prettyhexrep(packet.packet_hash), RNS.LOG_DEBUG)
+        if not packet.resend():
+            RNS.log("Failed to resend packet", RNS.LOG_ERROR)
+        return packet
+
+    @property
+    def mdu(self):
+        return self.link.MDU
+
+    @property
+    def rtt(self):
+        return self.link.rtt
+
+    @property
+    def is_usable(self):
+        return True  # had issues looking at Link.status
+
+    def get_packet_state(self, packet: TPacket) -> MessageState:
+        if packet.receipt == None:
+            return MessageState.MSGSTATE_FAILED
+
+        status = packet.receipt.get_status()
+        if status == RNS.PacketReceipt.SENT:
+            return MessageState.MSGSTATE_SENT
+        if status == RNS.PacketReceipt.DELIVERED:
+            return MessageState.MSGSTATE_DELIVERED
+        if status == RNS.PacketReceipt.FAILED:
+            return MessageState.MSGSTATE_FAILED
+        else:
+            raise Exception(f"Unexpected receipt state: {status}")
+
+    def timed_out(self):
+        self.link.teardown()
+
+    def __str__(self):
+        return f"{self.__class__.__name__}({self.link})"
+
+    def set_packet_timeout_callback(self, packet: RNS.Packet, callback: Callable[[RNS.Packet], None] | None,
+                                    timeout: float | None = None):
+        if timeout and packet.receipt:
+            packet.receipt.set_timeout(timeout)
+
+        def inner(receipt: RNS.PacketReceipt):
+            callback(packet)
+
+        if packet and packet.receipt:
+            packet.receipt.set_timeout_callback(inner if callback else None)
+
+    def set_packet_delivered_callback(self, packet: RNS.Packet, callback: Callable[[RNS.Packet], None] | None):
+        def inner(receipt: RNS.PacketReceipt):
+            callback(packet)
+
+        if packet and packet.receipt:
+            packet.receipt.set_delivery_callback(inner if callback else None)
+
+    def get_packet_id(self, packet: RNS.Packet) -> any:
+        return packet.get_hash()

RNS/Cryptography/HKDF.py

@@ -33,15 +33,12 @@ def hkdf(length=None, derive_from=None, salt=None, context=None):
     if length == None or length < 1:
         raise ValueError("Invalid output key length")
 
-    if derive_from == "None" or derive_from == "":
+    if derive_from == None or derive_from == "":
         raise ValueError("Cannot derive key from empty input material")
 
     if salt == None or len(salt) == 0:
         salt = bytes([0] * hash_len)
 
-    if salt == None:
-        salt = b""
-
     if context == None:
         context = b""
 
@@ -54,4 +51,4 @@ def hkdf(length=None, derive_from=None, salt=None, context=None):
         block = hmac_sha256(pseudorandom_key, block + context + bytes([i + 1]))
         derived += block
 
-    return derived[:length]
+    return derived[:length]

RNS/Destination.py

@@ -69,6 +69,8 @@ class Destination:
     OUT        = 0x12;
     directions = [IN, OUT]
 
+    PR_TAG_WINDOW = 30
+
     @staticmethod
     def expand_name(identity, app_name, *aspects):
         """
@@ -132,6 +134,7 @@ class Destination:
         self.proof_strategy = Destination.PROVE_NONE
         self.mtu = 0
 
+        self.path_responses = {}
         self.links = []
 
         if identity == None and direction == Destination.IN and self.type != Destination.PLAIN:
@@ -163,7 +166,7 @@ class Destination:
         return "<"+self.name+"/"+self.hexhash+">"
 
 
-    def announce(self, app_data=None, path_response=False, send=True):
+    def announce(self, app_data=None, path_response=False, attached_interface=None, tag=None, send=True):
         """
         Creates an announce packet for this destination and broadcasts it on all
         relevant interfaces. Application specific data can be added to the announce.
@@ -173,35 +176,60 @@ class Destination:
         """
         if self.type != Destination.SINGLE:
             raise TypeError("Only SINGLE destination types can be announced")
-            
-        destination_hash = self.hash
-        random_hash = RNS.Identity.get_random_hash()[0:5]+int(time.time()).to_bytes(5, "big")
-
-        if app_data == None and self.default_app_data != None:
-            if isinstance(self.default_app_data, bytes):
-                app_data = self.default_app_data
-            elif callable(self.default_app_data):
-                returned_app_data = self.default_app_data()
-                if isinstance(returned_app_data, bytes):
-                    app_data = returned_app_data
         
-        signed_data = self.hash+self.identity.get_public_key()+self.name_hash+random_hash
-        if app_data != None:
-            signed_data += app_data
+        now = time.time()
+        stale_responses = []
+        for entry_tag in self.path_responses:
+            entry = self.path_responses[entry_tag]
+            if now > entry[0]+Destination.PR_TAG_WINDOW:
+                stale_responses.append(entry_tag)
 
-        signature = self.identity.sign(signed_data)
+        for entry_tag in stale_responses:
+            self.path_responses.pop(entry_tag)
 
-        announce_data = self.identity.get_public_key()+self.name_hash+random_hash+signature
+        if (path_response == True and tag != None) and tag in self.path_responses:
+            # This code is currently not used, since Transport will block duplicate
+            # path requests based on tags. When multi-path support is implemented in
+            # Transport, this will allow Transport to detect redundant paths to the
+            # same destination, and select the best one based on chosen criteria,
+            # since it will be able to detect that a single emitted announce was
+            # received via multiple paths. The difference in reception time will
+            # potentially also be useful in determining characteristics of the
+            # multiple available paths, and to choose the best one.
+            RNS.log("Using cached announce data for answering path request with tag "+RNS.prettyhexrep(tag), RNS.LOG_EXTREME)
+            announce_data = self.path_responses[tag][1]
+        
+        else:
+            destination_hash = self.hash
+            random_hash = RNS.Identity.get_random_hash()[0:5]+int(time.time()).to_bytes(5, "big")
 
-        if app_data != None:
-            announce_data += app_data
+            if app_data == None and self.default_app_data != None:
+                if isinstance(self.default_app_data, bytes):
+                    app_data = self.default_app_data
+                elif callable(self.default_app_data):
+                    returned_app_data = self.default_app_data()
+                    if isinstance(returned_app_data, bytes):
+                        app_data = returned_app_data
+            
+            signed_data = self.hash+self.identity.get_public_key()+self.name_hash+random_hash
+            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+signature
+
+            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
 
-        announce_packet = RNS.Packet(self, announce_data, RNS.Packet.ANNOUNCE, context = announce_context)
+        announce_packet = RNS.Packet(self, announce_data, RNS.Packet.ANNOUNCE, context = announce_context, attached_interface = attached_interface)
 
         if send:
             announce_packet.send()
@@ -268,7 +296,7 @@ class Destination:
         Registers a request handler.
 
         :param path: The path for the request handler to be registered.
-        :param response_generator: A function or method with the signature *response_generator(path, data, request_id, remote_identity, requested_at)* to be called. Whatever this funcion returns will be sent as a response to the requester. If the function returns ``None``, no response will be sent.
+        :param response_generator: A function or method with the signature *response_generator(path, data, request_id, link_id, remote_identity, requested_at)* to be called. Whatever this funcion returns will be sent as a response to the requester. If the function returns ``None``, no response will be sent.
         :param allow: One of ``RNS.Destination.ALLOW_NONE``, ``RNS.Destination.ALLOW_ALL`` or ``RNS.Destination.ALLOW_LIST``. If ``RNS.Destination.ALLOW_LIST`` is set, the request handler will only respond to requests for identified peers in the supplied list.
         :param allowed_list: A list of *bytes-like* :ref:`RNS.Identity<api-identity>` hashes.
         :raises: ``ValueError`` if any of the supplied arguments are invalid.

RNS/Identity.py

@@ -255,10 +255,22 @@ class Identity:
                         RNS.Identity.remember(packet.get_hash(), destination_hash, public_key, app_data)
                         del announced_identity
 
-                        if hasattr(packet, "transport_id") and packet.transport_id != None:
-                            RNS.log("Valid announce for "+RNS.prettyhexrep(destination_hash)+" "+str(packet.hops)+" hops away, received via "+RNS.prettyhexrep(packet.transport_id)+" on "+str(packet.receiving_interface), RNS.LOG_EXTREME)
+                        if packet.rssi != None or packet.snr != None:
+                            signal_str = " ["
+                            if packet.rssi != None:
+                                signal_str += "RSSI "+str(packet.rssi)+"dBm"
+                                if packet.snr != None:
+                                    signal_str += ", "
+                            if packet.snr != None:
+                                signal_str += "SNR "+str(packet.snr)+"dB"
+                            signal_str += "]"
                         else:
-                            RNS.log("Valid announce for "+RNS.prettyhexrep(destination_hash)+" "+str(packet.hops)+" hops away, received on "+str(packet.receiving_interface), RNS.LOG_EXTREME)
+                            signal_str = ""
+
+                        if hasattr(packet, "transport_id") and packet.transport_id != None:
+                            RNS.log("Valid announce for "+RNS.prettyhexrep(destination_hash)+" "+str(packet.hops)+" hops away, received via "+RNS.prettyhexrep(packet.transport_id)+" on "+str(packet.receiving_interface)+signal_str, RNS.LOG_EXTREME)
+                        else:
+                            RNS.log("Valid announce for "+RNS.prettyhexrep(destination_hash)+" "+str(packet.hops)+" hops away, received on "+str(packet.receiving_interface)+signal_str, RNS.LOG_EXTREME)
 
                         return True
 

RNS/Interfaces/Android/RNodeInterface.py

@@ -193,7 +193,12 @@ class AndroidBluetoothManager():
             if self.connected and self.rfcomm_reader != None:
                 available = self.rfcomm_reader.available()
                 if available > 0:
-                    return self.rfcomm_reader.readNBytes(available)
+                    if hasattr(self.rfcomm_reader, "readNBytes"):
+                        return self.rfcomm_reader.readNBytes(available)
+                    else:
+                        # Compatibility mode for older android versions lacking readNBytes
+                        rb = self.rfcomm_reader.read().to_bytes(1, "big")
+                        return rb
                 else:
                     return bytes([])
             else:
@@ -249,13 +254,14 @@ class RNodeInterface(Interface):
 
                     # Driver overrides for speficic chips
                     from usbserial4a import serial4a as pyserial
+                    proxy = pyserial.get_serial_port
                     if vid == 0x1A86 and pid == 0x55D4:
                         # Force CDC driver for Qinheng CH34x
                         RNS.log("Using CDC driver for "+RNS.hexrep(vid)+":"+RNS.hexrep(pid), RNS.LOG_DEBUG)
                         from usbserial4a.cdcacmserial4a import CdcAcmSerial
                         proxy = CdcAcmSerial
 
-                    serial = pyserial.get_serial_port(
+                    serial = proxy(
                         port,
                         baudrate = 115200,
                         bytesize = 8,
@@ -276,7 +282,7 @@ class RNodeInterface(Interface):
                         serial.timeout = 0.1
                     elif vid == 0x10C4:
                         # Hardware parameters for SiLabs CP210x @ 115200 baud
-                        serial.DEFAULT_READ_BUFFER_SIZE = 64 
+                        serial.DEFAULT_READ_BUFFER_SIZE = 64
                         serial.USB_READ_TIMEOUT_MILLIS = 12
                         serial.timeout = 0.012
                     elif vid == 0x1A86 and pid == 0x55D4:
@@ -323,11 +329,13 @@ class RNodeInterface(Interface):
                 from usbserial4a import serial4a as serial
                 self.parity = "N"
 
+                self.bt_target_device_name = target_device_name
+                self.bt_target_device_address = target_device_address
                 if allow_bluetooth:
                     self.bt_manager = AndroidBluetoothManager(
                         owner = self,
-                        target_device_name = target_device_name,
-                        target_device_address = target_device_address
+                        target_device_name = self.bt_target_device_name,
+                        target_device_address = self.bt_target_device_address
                     )
 
                 else:
@@ -538,6 +546,13 @@ class RNodeInterface(Interface):
                 RNS.log(str(self)+" USB write timeout set to "+str(self.serial.USB_WRITE_TIMEOUT_MILLIS)+"ms", RNS.LOG_DEBUG)
 
         elif self.allow_bluetooth:
+            if self.bt_manager == None:
+                self.bt_manager = AndroidBluetoothManager(
+                    owner = self,
+                    target_device_name = self.bt_target_device_name,
+                    target_device_address = self.bt_target_device_address
+                )
+
             if self.bt_manager != None:
                 self.bt_manager.connect_any_device()
 
@@ -549,7 +564,7 @@ class RNodeInterface(Interface):
         thread.start()
 
         self.detect()
-        sleep(0.4)
+        sleep(0.5)
 
         if not self.detected:
             raise IOError("Could not detect device")
@@ -587,22 +602,22 @@ class RNodeInterface(Interface):
 
     def initRadio(self):
         self.setFrequency()
-        time.sleep(0.1)
+        time.sleep(0.15)
 
         self.setBandwidth()
-        time.sleep(0.1)
+        time.sleep(0.15)
         
         self.setTXPower()
-        time.sleep(0.1)
+        time.sleep(0.15)
         
         self.setSpreadingFactor()
-        time.sleep(0.1)
+        time.sleep(0.15)
         
         self.setCodingRate()
-        time.sleep(0.1)
+        time.sleep(0.15)
         
         self.setRadioState(KISS.RADIO_STATE_ON)
-        time.sleep(0.1)
+        time.sleep(0.15)
 
     def detect(self):
         kiss_command = bytes([KISS.FEND, KISS.CMD_DETECT, KISS.DETECT_REQ, KISS.FEND, KISS.CMD_FW_VERSION, 0x00, KISS.FEND, KISS.CMD_PLATFORM, 0x00, KISS.FEND, KISS.CMD_MCU, 0x00, KISS.FEND])
@@ -1057,10 +1072,10 @@ class RNodeInterface(Interface):
             try:
                 time.sleep(self.reconnect_w)
                 if self.serial != None and self.port != None:
-                    RNS.log("Attempting to reconnect serial port "+str(self.port)+" for "+str(self)+"...", RNS.LOG_VERBOSE)
+                    RNS.log("Attempting to reconnect serial port "+str(self.port)+" for "+str(self)+"...", RNS.LOG_EXTREME)
 
                 if self.bt_manager != None:
-                    RNS.log("Attempting to reconnect Bluetooth device for "+str(self)+"...", RNS.LOG_VERBOSE)
+                    RNS.log("Attempting to reconnect Bluetooth device for "+str(self)+"...", RNS.LOG_EXTREME)
 
                 self.open_port()
 

RNS/Interfaces/AutoInterface.py

@@ -23,6 +23,7 @@
 from .Interface import Interface
 import socketserver
 import threading
+import re
 import socket
 import struct
 import time
@@ -43,11 +44,24 @@ class AutoInterface(Interface):
 
     PEERING_TIMEOUT    = 7.5
 
+    ALL_IGNORE_IFS     = ["lo0"]
     DARWIN_IGNORE_IFS  = ["awdl0", "llw0", "lo0", "en5"]
     ANDROID_IGNORE_IFS = ["dummy0", "lo", "tun0"]
 
     BITRATE_GUESS      = 10*1000*1000
 
+    def handler_factory(self, callback):
+        def create_handler(*args, **keys):
+            return AutoInterfaceHandler(callback, *args, **keys)
+        return create_handler
+
+    def descope_linklocal(self, link_local_addr):
+        # Drop scope specifier expressd as %ifname (macOS)
+        link_local_addr = link_local_addr.split("%")[0]
+        # Drop embedded scope specifier (NetBSD, OpenBSD)
+        link_local_addr = re.sub(r"fe80:[0-9a-f]*::","fe80::", link_local_addr)
+        return link_local_addr
+
     def __init__(self, owner, name, group_id=None, discovery_scope=None, discovery_port=None, data_port=None, allowed_interfaces=None, ignored_interfaces=None, configured_bitrate=None):
         import importlib
         if importlib.util.find_spec('netifaces') != None:
@@ -70,8 +84,10 @@ class AutoInterface(Interface):
         self.peers = {}
         self.link_local_addresses = []
         self.adopted_interfaces = {}
+        self.interface_servers = {}
         self.multicast_echoes = {}
         self.timed_out_interfaces = {}
+        self.carrier_changed = False
 
         self.outbound_udp_socket = None
 
@@ -141,6 +157,8 @@ class AutoInterface(Interface):
                 RNS.log(str(self)+" skipping Android system interface "+str(ifname), RNS.LOG_EXTREME)
             elif ifname in self.ignored_interfaces:
                 RNS.log(str(self)+" ignoring disallowed interface "+str(ifname), RNS.LOG_EXTREME)
+            elif ifname in AutoInterface.ALL_IGNORE_IFS:
+                RNS.log(str(self)+" skipping interface "+str(ifname), RNS.LOG_EXTREME)
             else:
                 if len(self.allowed_interfaces) > 0 and not ifname in self.allowed_interfaces:
                     RNS.log(str(self)+" ignoring interface "+str(ifname)+" since it was not allowed", RNS.LOG_EXTREME)
@@ -151,9 +169,9 @@ class AutoInterface(Interface):
                         for address in addresses[self.netifaces.AF_INET6]:
                             if "addr" in address:
                                 if address["addr"].startswith("fe80:"):
-                                    link_local_addr = address["addr"]
-                                    self.link_local_addresses.append(link_local_addr.split("%")[0])
-                                    self.adopted_interfaces[ifname] = link_local_addr.split("%")[0]
+                                    link_local_addr = self.descope_linklocal(address["addr"])
+                                    self.link_local_addresses.append(link_local_addr)
+                                    self.adopted_interfaces[ifname] = link_local_addr
                                     self.multicast_echoes[ifname] = time.time()
                                     RNS.log(str(self)+" Selecting link-local address "+str(link_local_addr)+" for interface "+str(ifname), RNS.LOG_EXTREME)
 
@@ -199,11 +217,6 @@ class AutoInterface(Interface):
             peering_wait = self.announce_interval*1.2
             RNS.log(str(self)+" discovering peers for "+str(round(peering_wait, 2))+" seconds...", RNS.LOG_VERBOSE)
 
-            def handlerFactory(callback):
-                def createHandler(*args, **keys):
-                    return AutoInterfaceHandler(callback, *args, **keys)
-                return createHandler
-
             self.owner = owner
             socketserver.UDPServer.address_family = socket.AF_INET6
 
@@ -212,9 +225,10 @@ class AutoInterface(Interface):
                 addr_info = socket.getaddrinfo(local_addr, self.data_port, socket.AF_INET6, socket.SOCK_DGRAM)
                 address = addr_info[0][4]
 
-                self.server = socketserver.UDPServer(address, handlerFactory(self.processIncoming))
+                udp_server = socketserver.UDPServer(address, self.handler_factory(self.processIncoming))
+                self.interface_servers[ifname] = udp_server
                 
-                thread = threading.Thread(target=self.server.serve_forever)
+                thread = threading.Thread(target=udp_server.serve_forever)
                 thread.daemon = True
                 thread.start()
 
@@ -275,9 +289,35 @@ class AutoInterface(Interface):
                         for address in addresses[self.netifaces.AF_INET6]:
                             if "addr" in address:
                                 if address["addr"].startswith("fe80:"):
-                                    link_local_addr = address["addr"].split("%")[0]
+                                    link_local_addr = self.descope_linklocal(address["addr"])
                                     if link_local_addr != self.adopted_interfaces[ifname]:
+                                        old_link_local_address = self.adopted_interfaces[ifname]
+                                        RNS.log("Replacing link-local address "+str(old_link_local_address)+" for "+str(ifname)+" with "+str(link_local_addr), RNS.LOG_DEBUG)
                                         self.adopted_interfaces[ifname] = link_local_addr
+                                        self.link_local_addresses.append(link_local_addr)
+
+                                        if old_link_local_address in self.link_local_addresses:
+                                            self.link_local_addresses.remove(old_link_local_address)
+
+                                        local_addr = link_local_addr+"%"+ifname
+                                        addr_info = socket.getaddrinfo(local_addr, self.data_port, socket.AF_INET6, socket.SOCK_DGRAM)
+                                        listen_address = addr_info[0][4]
+
+                                        if ifname in self.interface_servers:
+                                            RNS.log("Shutting down previous UDP listener for "+str(self)+" "+str(ifname), RNS.LOG_DEBUG)
+                                            previous_server = self.interface_servers[ifname]
+                                            def shutdown_server():
+                                                previous_server.shutdown()
+                                            threading.Thread(target=shutdown_server, daemon=True).start()
+
+                                        RNS.log("Starting new UDP listener for "+str(self)+" "+str(ifname), RNS.LOG_DEBUG)
+
+                                        udp_server = socketserver.UDPServer(listen_address, self.handler_factory(self.processIncoming))
+                                        self.interface_servers[ifname] = udp_server
+
+                                        thread = threading.Thread(target=udp_server.serve_forever)
+                                        thread.daemon = True
+                                        thread.start()
 
                 except Exception as e:
                     RNS.log("Could not get device information while updating link-local addresses for "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -289,10 +329,12 @@ class AutoInterface(Interface):
 
                 if now - last_multicast_echo > self.multicast_echo_timeout:
                     if ifname in self.timed_out_interfaces and self.timed_out_interfaces[ifname] == False:
+                        self.carrier_changed = True
                         RNS.log("Multicast echo timeout for "+str(ifname)+". Carrier lost.", RNS.LOG_WARNING)
                     self.timed_out_interfaces[ifname] = True
                 else:
                     if ifname in self.timed_out_interfaces and self.timed_out_interfaces[ifname] == True:
+                        self.carrier_changed = True
                         RNS.log(str(self)+" Carrier recovered on "+str(ifname), RNS.LOG_WARNING)
                     self.timed_out_interfaces[ifname] = False
                 

RNS/Interfaces/I2PInterface.py

@@ -161,8 +161,6 @@ class I2PController:
                                 raise tn.status["exception"]
 
                             else:
-                                self.client_tunnels[i2p_destination] = True
-                                owner.awaiting_i2p_tunnel = False
                                 if owner.socket != None:
                                     if hasattr(owner.socket, "close"):
                                         if callable(owner.socket.close):
@@ -175,6 +173,8 @@ class I2PController:
                                                 owner.socket.close()
                                             except Exception as e:
                                                 RNS.log("Error while closing socket for "+str(owner)+": "+str(e))
+                                self.client_tunnels[i2p_destination] = True
+                                owner.awaiting_i2p_tunnel = False
 
                                 RNS.log(str(owner)+" tunnel setup complete", RNS.LOG_VERBOSE)
 
@@ -383,6 +383,11 @@ class I2PInterfacePeer(Interface):
     I2P_PROBE_AFTER = 10
     I2P_PROBE_INTERVAL = 9
     I2P_PROBES = 5
+    I2P_READ_TIMEOUT = (I2P_PROBE_INTERVAL * I2P_PROBES + I2P_PROBE_AFTER)*2
+
+    TUNNEL_STATE_INIT    = 0x00
+    TUNNEL_STATE_ACTIVE  = 0x01
+    TUNNEL_STATE_STALE   = 0x02
 
     def __init__(self, parent_interface, owner, name, target_i2p_dest=None, connected_socket=None, max_reconnect_tries=None):
         self.rxb = 0
@@ -409,6 +414,30 @@ class I2PInterfacePeer(Interface):
         self.i2p_tunnel_ready = False
         self.mode             = RNS.Interfaces.Interface.Interface.MODE_FULL
         self.bitrate          = I2PInterface.BITRATE_GUESS
+        self.last_read        = 0
+        self.last_write       = 0
+        self.wd_reset         = False
+        self.i2p_tunnel_state = I2PInterfacePeer.TUNNEL_STATE_INIT
+
+        self.ifac_size = self.parent_interface.ifac_size
+        self.ifac_netname = self.parent_interface.ifac_netname
+        self.ifac_netkey = self.parent_interface.ifac_netkey
+        if self.ifac_netname != None or self.ifac_netkey != None:
+            ifac_origin = b""
+            if self.ifac_netname != None:
+                ifac_origin += RNS.Identity.full_hash(self.ifac_netname.encode("utf-8"))
+            if self.ifac_netkey != None:
+                ifac_origin += RNS.Identity.full_hash(self.ifac_netkey.encode("utf-8"))
+
+            ifac_origin_hash = RNS.Identity.full_hash(ifac_origin)
+            self.ifac_key = RNS.Cryptography.hkdf(
+                length=64,
+                derive_from=ifac_origin_hash,
+                salt=RNS.Reticulum.IFAC_SALT,
+                context=None
+            )
+            self.ifac_identity = RNS.Identity.from_bytes(self.ifac_key)
+            self.ifac_signature = self.ifac_identity.sign(RNS.Identity.full_hash(self.ifac_key))
 
         self.announce_rate_target  = None
         self.announce_rate_grace   = None
@@ -454,7 +483,7 @@ class I2PInterfacePeer(Interface):
                         RNS.log("Error while while configuring "+str(self)+": "+str(e), RNS.LOG_ERROR)
                         RNS.log("Check that I2P is installed and running, and that SAM is enabled. Retrying tunnel setup later.", RNS.LOG_ERROR)
 
-                    time.sleep(15)
+                    time.sleep(8)
 
             thread = threading.Thread(target=tunnel_job)
             thread.daemon = True
@@ -463,6 +492,7 @@ class I2PInterfacePeer(Interface):
             def wait_job():
                 while self.awaiting_i2p_tunnel:
                     time.sleep(0.25)
+                time.sleep(2)
                 
                 if not self.kiss_framing:
                     self.wants_tunnel = True
@@ -482,18 +512,11 @@ class I2PInterfacePeer(Interface):
 
 
     def set_timeouts_linux(self):
-        if not self.i2p_tunneled:
-            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_USER_TIMEOUT, int(I2PInterfacePeer.TCP_USER_TIMEOUT * 1000))
-            self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
-            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, int(I2PInterfacePeer.TCP_PROBE_AFTER))
-            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, int(I2PInterfacePeer.TCP_PROBE_INTERVAL))
-            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, int(I2PInterfacePeer.TCP_PROBES))
-        else:
-            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_USER_TIMEOUT, int(I2PInterfacePeer.I2P_USER_TIMEOUT * 1000))
-            self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
-            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, int(I2PInterfacePeer.I2P_PROBE_AFTER))
-            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, int(I2PInterfacePeer.I2P_PROBE_INTERVAL))
-            self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, int(I2PInterfacePeer.I2P_PROBES))
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_USER_TIMEOUT, int(I2PInterfacePeer.I2P_USER_TIMEOUT * 1000))
+        self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, int(I2PInterfacePeer.I2P_PROBE_AFTER))
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, int(I2PInterfacePeer.I2P_PROBE_INTERVAL))
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, int(I2PInterfacePeer.I2P_PROBES))
 
     def set_timeouts_osx(self):
         if hasattr(socket, "TCP_KEEPALIVE"):
@@ -502,22 +525,19 @@ class I2PInterfacePeer(Interface):
             TCP_KEEPIDLE = 0x10
 
         self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
-        
-        if not self.i2p_tunneled:
-            self.socket.setsockopt(socket.IPPROTO_TCP, TCP_KEEPIDLE, int(I2PInterfacePeer.TCP_PROBE_AFTER))
-        else:
-            self.socket.setsockopt(socket.IPPROTO_TCP, TCP_KEEPIDLE, int(I2PInterfacePeer.I2P_PROBE_AFTER))
+        self.socket.setsockopt(socket.IPPROTO_TCP, TCP_KEEPIDLE, int(I2PInterfacePeer.I2P_PROBE_AFTER))
     
-    def shutdown_socket(self, socket):
-        if callable(socket.close):
-            
+    def shutdown_socket(self, target_socket):
+        if callable(target_socket.close):
             try:
-                socket.shutdown(socket.SHUT_RDWR)
+                if socket != None:
+                    target_socket.shutdown(socket.SHUT_RDWR)
             except Exception as e:
                 RNS.log("Error while shutting down socket for "+str(self)+": "+str(e))
 
             try:
-                socket.close()
+                if socket != None:
+                    target_socket.close()
             except Exception as e:
                 RNS.log("Error while closing socket for "+str(self)+": "+str(e))    
     
@@ -571,7 +591,6 @@ class I2PInterfacePeer(Interface):
 
         return True
 
-
     def reconnect(self):
         if self.initiator:
             if not self.reconnecting:
@@ -632,6 +651,7 @@ class I2PInterfacePeer(Interface):
                 self.socket.sendall(data)
                 self.writing = False
                 self.txb += len(data)
+                self.last_write = time.time()
                 
                 if hasattr(self, "parent_interface") and self.parent_interface != None and self.parent_count:
                     self.parent_interface.txb += len(data)
@@ -642,8 +662,59 @@ class I2PInterfacePeer(Interface):
                 self.teardown()
 
 
+    def read_watchdog(self):
+        while self.wd_reset:
+            time.sleep(0.25)
+
+        should_run = True
+        try:
+            while should_run and not self.wd_reset:
+                time.sleep(1)
+
+                if (time.time()-self.last_read > I2PInterfacePeer.I2P_PROBE_AFTER*2):
+                    if self.i2p_tunnel_state != I2PInterfacePeer.TUNNEL_STATE_STALE:
+                        RNS.log("I2P tunnel became unresponsive", RNS.LOG_DEBUG)
+
+                    self.i2p_tunnel_state = I2PInterfacePeer.TUNNEL_STATE_STALE
+                else:
+                    self.i2p_tunnel_state = I2PInterfacePeer.TUNNEL_STATE_ACTIVE
+
+                if (time.time()-self.last_write > I2PInterfacePeer.I2P_PROBE_AFTER*1):
+                    try:
+                        if self.socket != None:
+                            self.socket.sendall(bytes([HDLC.FLAG, HDLC.FLAG]))
+                    except Exception as e:
+                        RNS.log("An error ocurred while sending I2P keepalive. The contained exception was: "+str(e), RNS.LOG_ERROR)
+                        self.shutdown_socket(self.socket)
+                        should_run = False
+                
+                if (time.time()-self.last_read > I2PInterfacePeer.I2P_READ_TIMEOUT):
+                    RNS.log("I2P socket is unresponsive, restarting...", RNS.LOG_WARNING)
+                    if self.socket != None:
+                        try:
+                            self.socket.shutdown(socket.SHUT_RDWR)
+                        except Exception as e:
+                            RNS.log("Error while shutting down socket for "+str(self)+": "+str(e))
+
+                        try:
+                            self.socket.close()
+                        except Exception as e:
+                            RNS.log("Error while closing socket for "+str(self)+": "+str(e))
+
+                    should_run = False
+
+                self.wd_reset = False
+
+        finally:
+            self.wd_reset = False
+
     def read_loop(self):
         try:
+            self.last_read  = time.time()
+            self.last_write = time.time()
+
+            wd_thread = threading.Thread(target=self.read_watchdog, daemon=True).start()
+
             in_frame = False
             escape = False
             data_buffer = b""
@@ -653,6 +724,7 @@ class I2PInterfacePeer(Interface):
                 data_in = self.socket.recv(4096)
                 if len(data_in) > 0:
                     pointer = 0
+                    self.last_read = time.time()
                     while pointer < len(data_in):
                         byte = data_in[pointer]
                         pointer += 1
@@ -705,6 +777,11 @@ class I2PInterfacePeer(Interface):
                                     data_buffer = data_buffer+bytes([byte])
                 else:
                     self.online = False
+
+                    self.wd_reset = True
+                    time.sleep(2)
+                    self.wd_reset = False
+
                     if self.initiator and not self.detached:
                         RNS.log("Socket for "+str(self)+" was closed, attempting to reconnect...", RNS.LOG_WARNING)
                         self.reconnect()
@@ -754,7 +831,7 @@ class I2PInterfacePeer(Interface):
 class I2PInterface(Interface):
     BITRATE_GUESS      = 256*1000
 
-    def __init__(self, owner, name, rns_storagepath, peers, connectable = False):
+    def __init__(self, owner, name, rns_storagepath, peers, connectable = False, ifac_size = 16, ifac_netname = None, ifac_netkey = None):
         self.rxb = 0
         self.txb = 0
         
@@ -780,6 +857,9 @@ class I2PInterface(Interface):
         self.bind_port   = self.i2p.get_free_port()
         self.address = (self.bind_ip, self.bind_port)
         self.bitrate = I2PInterface.BITRATE_GUESS
+        self.ifac_size = ifac_size
+        self.ifac_netname = ifac_netname
+        self.ifac_netkey = ifac_netkey
 
         self.online = False
 
@@ -850,9 +930,27 @@ class I2PInterface(Interface):
         spawned_interface.parent_interface = self
         spawned_interface.online = True
         spawned_interface.bitrate = self.bitrate
+
         spawned_interface.ifac_size = self.ifac_size
         spawned_interface.ifac_netname = self.ifac_netname
         spawned_interface.ifac_netkey = self.ifac_netkey
+        if spawned_interface.ifac_netname != None or spawned_interface.ifac_netkey != None:
+            ifac_origin = b""
+            if spawned_interface.ifac_netname != None:
+                ifac_origin += RNS.Identity.full_hash(spawned_interface.ifac_netname.encode("utf-8"))
+            if spawned_interface.ifac_netkey != None:
+                ifac_origin += RNS.Identity.full_hash(spawned_interface.ifac_netkey.encode("utf-8"))
+
+            ifac_origin_hash = RNS.Identity.full_hash(ifac_origin)
+            spawned_interface.ifac_key = RNS.Cryptography.hkdf(
+                length=64,
+                derive_from=ifac_origin_hash,
+                salt=RNS.Reticulum.IFAC_SALT,
+                context=None
+            )
+            spawned_interface.ifac_identity = RNS.Identity.from_bytes(spawned_interface.ifac_key)
+            spawned_interface.ifac_signature = spawned_interface.ifac_identity.sign(RNS.Identity.full_hash(spawned_interface.ifac_key))
+
         spawned_interface.announce_rate_target = self.announce_rate_target
         spawned_interface.announce_rate_grace = self.announce_rate_grace
         spawned_interface.announce_rate_penalty = self.announce_rate_penalty

RNS/Interfaces/LocalInterface.py

@@ -86,6 +86,8 @@ class LocalClientInterface(Interface):
         self.online  = True
         self.writing = False
 
+        self._force_bitrate = False
+
         self.announce_rate_target  = None
         self.announce_rate_grace   = None
         self.announce_rate_penalty = None
@@ -137,6 +139,9 @@ class LocalClientInterface(Interface):
 
 
     def processIncoming(self, data):
+        if self._force_bitrate:
+            time.sleep(len(data) / self.bitrate * 8)
+
         self.rxb += len(data)
         if hasattr(self, "parent_interface") and self.parent_interface != None:
             self.parent_interface.rxb += len(data)
@@ -154,6 +159,8 @@ class LocalClientInterface(Interface):
         if self.online:
             try:
                 self.writing = True
+                if self._force_bitrate:
+                    time.sleep(len(data) / self.bitrate * 8)
                 data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
                 self.socket.sendall(data)
                 self.writing = False

RNS/Interfaces/RNodeInterface.py

@@ -125,6 +125,8 @@ class RNodeInterface(Interface):
         self.stopbits    = 1
         self.timeout     = 100
         self.online      = False
+        self.detached    = False
+        self.reconnecting= False
 
         self.frequency   = frequency
         self.bandwidth   = bandwidth
@@ -210,9 +212,10 @@ class RNodeInterface(Interface):
             RNS.log("Could not open serial port for interface "+str(self), RNS.LOG_ERROR)
             RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
             RNS.log("Reticulum will attempt to bring up this interface periodically", RNS.LOG_ERROR)
-            thread = threading.Thread(target=self.reconnect_port)
-            thread.daemon = True
-            thread.start()
+            if not self.detached and not self.reconnecting:
+                thread = threading.Thread(target=self.reconnect_port)
+                thread.daemon = True
+                thread.start()
 
 
     def open_port(self):
@@ -233,7 +236,15 @@ class RNodeInterface(Interface):
 
 
     def configure_device(self):
+        self.r_frequency = None
+        self.r_bandwidth = None
+        self.r_txpower   = None
+        self.r_sf        = None
+        self.r_cr        = None
+        self.r_state     = None
+        self.r_lock      = None
         sleep(2.0)
+
         thread = threading.Thread(target=self.readLoop)
         thread.daemon = True
         thread.start()
@@ -242,7 +253,8 @@ class RNodeInterface(Interface):
         sleep(0.2)
         
         if not self.detected:
-            raise IOError("Could not detect device")
+            RNS.log("Could not detect device for "+str(self), RNS.LOG_ERROR)
+            self.serial.close()
         else:
             if self.platform == KISS.PLATFORM_ESP32:
                 self.display = True
@@ -260,7 +272,6 @@ class RNodeInterface(Interface):
             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()
-            raise IOError("RNode interface did not pass configuration validation")
             
 
     def initRadio(self):
@@ -395,7 +406,7 @@ class RNodeInterface(Interface):
 
 
     def validateRadioState(self):
-        RNS.log("Wating for radio configuration validation for "+str(self)+"...", RNS.LOG_VERBOSE)
+        RNS.log("Waiting for radio configuration validation for "+str(self)+"...", RNS.LOG_VERBOSE)
         sleep(0.25);
 
         self.validcfg = True
@@ -668,11 +679,17 @@ class RNodeInterface(Interface):
             RNS.log("Reticulum will attempt to reconnect the interface periodically.", RNS.LOG_ERROR)
 
         self.online = False
-        self.serial.close()
-        self.reconnect_port()
+        try:
+            self.serial.close()
+        except Exception as e:
+            pass
+
+        if not self.detached and not self.reconnecting:
+            self.reconnect_port()
 
     def reconnect_port(self):
-        while not self.online:
+        self.reconnecting = True
+        while not self.online and not self.detached:
             try:
                 time.sleep(5)
                 RNS.log("Attempting to reconnect serial port "+str(self.port)+" for "+str(self)+"...", RNS.LOG_VERBOSE)
@@ -682,10 +699,12 @@ class RNodeInterface(Interface):
             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))
 
     def detach(self):
+        self.detached = True
         self.disable_external_framebuffer()
         self.setRadioState(KISS.RADIO_STATE_OFF)
         self.leave()

RNS/Interfaces/TCPInterface.py

@@ -483,9 +483,27 @@ class TCPServerInterface(Interface):
         spawned_interface.target_port = str(handler.client_address[1])
         spawned_interface.parent_interface = self
         spawned_interface.bitrate = self.bitrate
+        
         spawned_interface.ifac_size = self.ifac_size
         spawned_interface.ifac_netname = self.ifac_netname
         spawned_interface.ifac_netkey = self.ifac_netkey
+        if spawned_interface.ifac_netname != None or spawned_interface.ifac_netkey != None:
+            ifac_origin = b""
+            if spawned_interface.ifac_netname != None:
+                ifac_origin += RNS.Identity.full_hash(spawned_interface.ifac_netname.encode("utf-8"))
+            if spawned_interface.ifac_netkey != None:
+                ifac_origin += RNS.Identity.full_hash(spawned_interface.ifac_netkey.encode("utf-8"))
+
+            ifac_origin_hash = RNS.Identity.full_hash(ifac_origin)
+            spawned_interface.ifac_key = RNS.Cryptography.hkdf(
+                length=64,
+                derive_from=ifac_origin_hash,
+                salt=RNS.Reticulum.IFAC_SALT,
+                context=None
+            )
+            spawned_interface.ifac_identity = RNS.Identity.from_bytes(spawned_interface.ifac_key)
+            spawned_interface.ifac_signature = spawned_interface.ifac_identity.sign(RNS.Identity.full_hash(spawned_interface.ifac_key))
+
         spawned_interface.announce_rate_target = self.announce_rate_target
         spawned_interface.announce_rate_grace = self.announce_rate_grace
         spawned_interface.announce_rate_penalty = self.announce_rate_penalty

RNS/Link.py

@@ -22,10 +22,12 @@
 
 from RNS.Cryptography import X25519PrivateKey, X25519PublicKey, Ed25519PrivateKey, Ed25519PublicKey
 from RNS.Cryptography import Fernet
+from RNS.Channel import Channel, LinkChannelOutlet
 
 from time import sleep
 from .vendor import umsgpack as umsgpack
 import threading
+import inspect
 import math
 import time
 import RNS
@@ -162,6 +164,7 @@ class Link:
         self.destination = destination
         self.attached_interface = None
         self.__remote_identity = None
+        self._channel = None
         if self.destination == None:
             self.initiator = False
             self.prv     = X25519PrivateKey.generate()
@@ -272,15 +275,19 @@ class Link:
                     self.rtt = time.time() - self.request_time
                     self.attached_interface = packet.receiving_interface
                     self.__remote_identity = self.destination.identity
+                    self.status = Link.ACTIVE
+                    self.activated_at = time.time()
                     RNS.Transport.activate_link(self)
                     RNS.log("Link "+str(self)+" established with "+str(self.destination)+", RTT is "+str(round(self.rtt, 3))+"s", RNS.LOG_VERBOSE)
+                    
+                    if self.rtt != None and self.establishment_cost != None and self.rtt > 0 and self.establishment_cost > 0:
+                        self.establishment_rate = self.establishment_cost/self.rtt
+
                     rtt_data = umsgpack.packb(self.rtt)
                     rtt_packet = RNS.Packet(self, rtt_data, context=RNS.Packet.LRRTT)
                     rtt_packet.send()
                     self.had_outbound()
 
-                    self.status = Link.ACTIVE
-                    self.activated_at = time.time()
                     if self.callbacks.link_established != None:
                         thread = threading.Thread(target=self.callbacks.link_established, args=(self,))
                         thread.daemon = True
@@ -362,11 +369,6 @@ class Link:
 
     def rtt_packet(self, packet):
         try:
-            # TODO: This is crude, we should use the delta
-            # to model a more representative per-bit round
-            # trip time, and use that to set a sensible RTT
-            # expectancy for the link. This will have to do
-            # for now though.
             measured_rtt = time.time() - self.request_time
             plaintext = self.decrypt(packet.data)
             rtt = umsgpack.unpackb(plaintext)
@@ -374,13 +376,28 @@ class Link:
             self.status = Link.ACTIVE
             self.activated_at = time.time()
 
-            
-            if self.owner.callbacks.link_established != None:
-                    self.owner.callbacks.link_established(self)
+            if self.rtt != None and self.establishment_cost != None and self.rtt > 0 and self.establishment_cost > 0:
+                self.establishment_rate = self.establishment_cost/self.rtt
+
+            try:
+                if self.owner.callbacks.link_established != None:
+                        self.owner.callbacks.link_established(self)
+            except Exception as e:
+                RNS.log("Error occurred in external link establishment callback. The contained exception was: "+str(e), RNS.LOG_ERROR)
+
         except Exception as e:
             RNS.log("Error occurred while processing RTT packet, tearing down link. The contained exception was: "+str(e), RNS.LOG_ERROR)
             self.teardown()
 
+    def get_establishment_rate(self):
+        """
+        :returns: The data transfer rate at which the link establishment procedure ocurred, in bits per second.
+        """
+        if self.establishment_rate != None:
+            return self.establishment_rate*8
+        else:
+            return None
+
     def get_salt(self):
         return self.link_id
 
@@ -450,6 +467,8 @@ class Link:
             resource.cancel()
         for resource in self.outgoing_resources:
             resource.cancel()
+        if self._channel:
+            self._channel._shutdown()
             
         self.prv = None
         self.pub = None
@@ -568,7 +587,13 @@ class Link:
 
                 if allowed:
                     RNS.log("Handling request "+RNS.prettyhexrep(request_id)+" for: "+str(path), RNS.LOG_DEBUG)
-                    response = response_generator(path, request_data, request_id, self.__remote_identity, requested_at)
+                    if len(inspect.signature(response_generator).parameters) == 5:
+                        response = response_generator(path, request_data, request_id, self.__remote_identity, requested_at)
+                    elif len(inspect.signature(response_generator).parameters) == 6:
+                        response = response_generator(path, request_data, request_id, self.link_id, self.__remote_identity, requested_at)
+                    else:
+                        raise TypeError("Invalid signature for response generator callback")
+
                     if response != None:
                         packed_response = umsgpack.packb([request_id, response])
 
@@ -624,6 +649,16 @@ class Link:
                 if pending_request.request_id == resource.request_id:
                     pending_request.request_timed_out(None)
 
+    def get_channel(self):
+        """
+        Get the ``Channel`` for this link.
+
+        :return: ``Channel`` object
+        """
+        if self._channel is None:
+            self._channel = Channel(LinkChannelOutlet(self))
+        return self._channel
+
     def receive(self, packet):
         self.watchdog_lock = True
         if not self.status == Link.CLOSED and not (self.initiator and packet.context == RNS.Packet.KEEPALIVE and packet.data == bytes([0xFF])):
@@ -770,6 +805,14 @@ class Link:
                         for resource in self.incoming_resources:
                             resource.receive_part(packet)
 
+                    elif packet.context == RNS.Packet.CHANNEL:
+                        if not self._channel:
+                            RNS.log(f"Channel data received without open channel", RNS.LOG_DEBUG)
+                        else:
+                            packet.prove()
+                            plaintext = self.decrypt(packet.data)
+                            self._channel._receive(plaintext)
+
                 elif packet.packet_type == RNS.Packet.PROOF:
                     if packet.context == RNS.Packet.RESOURCE_PRF:
                         resource_hash = packet.data[0:RNS.Identity.HASHLENGTH//8]
@@ -900,6 +943,13 @@ class Link:
     def register_incoming_resource(self, resource):
         self.incoming_resources.append(resource)
 
+    def has_incoming_resource(self, resource):
+        for incoming_resource in self.incoming_resources:
+            if incoming_resource.hash == resource.hash:
+                return True
+
+        return False
+
     def cancel_outgoing_resource(self, resource):
         if resource in self.outgoing_resources:
             self.outgoing_resources.remove(resource)

RNS/Packet.py

@@ -58,9 +58,7 @@ class Packet:
     # Header types
     HEADER_1     = 0x00     # Normal header format
     HEADER_2     = 0x01     # Header format used for packets in transport
-    HEADER_3     = 0x02     # Reserved
-    HEADER_4     = 0x03     # Reserved
-    header_types = [HEADER_1, HEADER_2, HEADER_3, HEADER_4]
+    header_types = [HEADER_1, HEADER_2]
 
     # Packet context types
     NONE           = 0x00   # Generic data packet
@@ -77,6 +75,7 @@ class Packet:
     PATH_RESPONSE  = 0x0B   # Packet is a response to a path request
     COMMAND        = 0x0C   # Packet is a command
     COMMAND_STATUS = 0x0D   # Packet is a status of an executed command
+    CHANNEL        = 0x0E   # Packet contains link channel data
     KEEPALIVE      = 0xFA   # Packet is a keepalive packet
     LINKIDENTIFY   = 0xFB   # Packet is a link peer identification proof
     LINKCLOSE      = 0xFC   # Packet is a link close message
@@ -215,7 +214,7 @@ class Packet:
             self.flags = self.raw[0]
             self.hops  = self.raw[1]
 
-            self.header_type      = (self.flags & 0b11000000) >> 6
+            self.header_type      = (self.flags & 0b01000000) >> 6
             self.transport_type   = (self.flags & 0b00110000) >> 4
             self.destination_type = (self.flags & 0b00001100) >> 2
             self.packet_type      = (self.flags & 0b00000011)

RNS/Resource.py

@@ -172,20 +172,26 @@ class Resource:
 
             resource.consecutive_completed_height = 0
             
-            resource.link.register_incoming_resource(resource)
+            if not resource.link.has_incoming_resource(resource):
+                resource.link.register_incoming_resource(resource)
 
-            RNS.log("Accepting resource advertisement for "+RNS.prettyhexrep(resource.hash), RNS.LOG_DEBUG)
-            if resource.link.callbacks.resource_started != None:
-                try:
-                    resource.link.callbacks.resource_started(resource)
-                except Exception as e:
-                    RNS.log("Error while executing resource started callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
+                RNS.log("Accepting resource advertisement for "+RNS.prettyhexrep(resource.hash), RNS.LOG_DEBUG)
+                if resource.link.callbacks.resource_started != None:
+                    try:
+                        resource.link.callbacks.resource_started(resource)
+                    except Exception as e:
+                        RNS.log("Error while executing resource started callback from "+str(resource)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
-            resource.hashmap_update(0, resource.hashmap_raw)
+                resource.hashmap_update(0, resource.hashmap_raw)
 
-            resource.watchdog_job()
+                resource.watchdog_job()
+
+                return resource
+
+            else:
+                RNS.log("Ignoring resource advertisement for "+RNS.prettyhexrep(resource.hash)+", resource already transferring", RNS.LOG_DEBUG)
+                return None
 
-            return resource
         except Exception as e:
             RNS.log("Could not decode resource advertisement, dropping resource", RNS.LOG_DEBUG)
             return None
@@ -397,8 +403,7 @@ class Resource:
         thread.start()
 
     def __advertise_job(self):
-        data = ResourceAdvertisement(self).pack()
-        self.advertisement_packet = RNS.Packet(self.link, data, context=RNS.Packet.RESOURCE_ADV)
+        self.advertisement_packet = RNS.Packet(self.link, ResourceAdvertisement(self).pack(), context=RNS.Packet.RESOURCE_ADV)
         while not self.link.ready_for_new_resource():
             self.status = Resource.QUEUED
             sleep(0.25)
@@ -445,7 +450,8 @@ class Resource:
                         try:
                             RNS.log("No part requests received, retrying resource advertisement...", RNS.LOG_DEBUG)
                             self.retries_left -= 1
-                            self.advertisement_packet.resend()
+                            self.advertisement_packet = RNS.Packet(self.link, ResourceAdvertisement(self).pack(), context=RNS.Packet.RESOURCE_ADV)
+                            self.advertisement_packet.send()
                             self.last_activity = time.time()
                             self.adv_sent = self.last_activity
                             sleep_time = 0.001

RNS/Reticulum.py

@@ -117,7 +117,7 @@ class Reticulum:
     # from interface speed, but a better general approach would most
     # probably be to let Reticulum somehow continously build a map of
     # per-hop latencies and use this map for the timeout calculation. 
-    DEFAULT_PER_HOP_TIMEOUT = 5
+    DEFAULT_PER_HOP_TIMEOUT = 6
 
     # Length of truncated hashes in bits.
     TRUNCATED_HASHLENGTH = 128
@@ -631,12 +631,18 @@ class Reticulum:
                                     i2p_peers = c.as_list("peers") if "peers" in c else None
                                     connectable = c.as_bool("connectable") if "connectable" in c else False
 
+                                    if ifac_size == None:
+                                        ifac_size = 16
+
                                     interface = I2PInterface.I2PInterface(
                                         RNS.Transport,
                                         name,
                                         Reticulum.storagepath,
                                         i2p_peers,
                                         connectable = connectable,
+                                        ifac_size = ifac_size,
+                                        ifac_netname = ifac_netname,
+                                        ifac_netkey = ifac_netkey,
                                     )
 
                                     if "outgoing" in c and c.as_bool("outgoing") == False:
@@ -653,10 +659,6 @@ class Reticulum:
                                     interface.announce_cap = announce_cap
                                     if configured_bitrate:
                                         interface.bitrate = configured_bitrate
-                                    if ifac_size != None:
-                                        interface.ifac_size = ifac_size
-                                    else:
-                                        interface.ifac_size = 16
 
                                 if c["type"] == "SerialInterface":
                                     port = c["port"] if "port" in c else None
@@ -1071,6 +1073,19 @@ class Reticulum:
                     else:
                         ifstats["i2p_b32"] = None
 
+                if hasattr(interface, "i2p_tunnel_state"):
+                    if interface.i2p_tunnel_state != None:
+                        state_description = "Unknown State"
+                        if interface.i2p_tunnel_state == I2PInterface.I2PInterfacePeer.TUNNEL_STATE_ACTIVE:
+                            state_description = "Tunnel Active"
+                        elif interface.i2p_tunnel_state == I2PInterface.I2PInterfacePeer.TUNNEL_STATE_INIT:
+                            state_description = "Creating Tunnel"
+                        elif interface.i2p_tunnel_state == I2PInterface.I2PInterfacePeer.TUNNEL_STATE_STALE:
+                            state_description = "Tunnel Unresponsive"
+                        ifstats["tunnelstate"] = state_description
+                    else:
+                        ifstats["tunnelstate"] = None
+
                 if hasattr(interface, "bitrate"):
                     if interface.bitrate != None:
                         ifstats["bitrate"] = interface.bitrate

RNS/Transport.py

@@ -66,6 +66,7 @@ class Transport:
     PATH_REQUEST_TIMEOUT = 15           # Default timuout for client path requests in seconds
     PATH_REQUEST_GRACE   = 0.35         # Grace time before a path announcement is made, allows directly reachable peers to respond first
     PATH_REQUEST_RW      = 2            # Path request random window
+    PATH_REQUEST_MI      = 5            # Minimum interval in seconds for automated path requests
 
     LINK_TIMEOUT         = RNS.Link.STALE_TIME * 1.25
     REVERSE_TIMEOUT      = 30*60        # Reverse table entries are removed after 30 minutes
@@ -92,6 +93,7 @@ class Transport:
     announce_handlers    = []           # A table storing externally registered announce handlers
     tunnels              = {}           # A table storing tunnels to other transport instances
     announce_rate_table  = {}           # A table for keeping track of announce rates
+    path_requests        = {}           # A table for storing path request timestamps
     
     discovery_path_requests  = {}       # A table for keeping track of path requests on behalf of other nodes
     discovery_pr_tags        = []       # A table for keeping track of tagged path requests
@@ -116,6 +118,8 @@ class Transport:
     jobs_locked = False
     jobs_running = False
     job_interval = 0.250
+    links_last_checked       = 0.0
+    links_check_interval     = 1.0
     receipts_last_checked    = 0.0
     receipts_check_interval  = 1.0
     announces_last_checked   = 0.0
@@ -144,13 +148,14 @@ class Transport:
                 RNS.log("Loaded Transport Identity from storage", RNS.LOG_VERBOSE)
 
         packet_hashlist_path = RNS.Reticulum.storagepath+"/packet_hashlist"
-        if os.path.isfile(packet_hashlist_path):
-            try:
-                file = open(packet_hashlist_path, "rb")
-                Transport.packet_hashlist = umsgpack.unpackb(file.read())
-                file.close()
-            except Exception as e:
-                RNS.log("Could not load packet hashlist from storage, the contained exception was: "+str(e), RNS.LOG_ERROR)
+        if not Transport.owner.is_connected_to_shared_instance:
+            if os.path.isfile(packet_hashlist_path):
+                try:
+                    file = open(packet_hashlist_path, "rb")
+                    Transport.packet_hashlist = umsgpack.unpackb(file.read())
+                    file.close()
+                except Exception as e:
+                    RNS.log("Could not load packet hashlist from storage, the contained exception was: "+str(e), RNS.LOG_ERROR)
 
         # Create transport-specific destinations
         Transport.path_request_destination = RNS.Destination(None, RNS.Destination.IN, RNS.Destination.PLAIN, Transport.APP_NAME, "path", "request")
@@ -164,8 +169,7 @@ class Transport:
         Transport.control_hashes.append(Transport.tunnel_synthesize_destination.hash)
 
         Transport.jobs_running = False
-        thread = threading.Thread(target=Transport.jobloop)
-        thread.daemon = True
+        thread = threading.Thread(target=Transport.jobloop, daemon=True)
         thread.start()
 
         if RNS.Reticulum.transport_enabled():
@@ -265,8 +269,6 @@ class Transport:
                 except Exception as e:
                     RNS.log("Could not load tunnel table from storage, the contained exception was: "+str(e), RNS.LOG_ERROR)
 
-
-
             RNS.log("Transport instance "+str(Transport.identity)+" started", RNS.LOG_VERBOSE)
 
         # Synthesize tunnels for any interfaces wanting it
@@ -284,10 +286,44 @@ class Transport:
     @staticmethod
     def jobs():
         outgoing = []
+        path_requests = []
         Transport.jobs_running = True
 
         try:
             if not Transport.jobs_locked:
+
+                # Process active and pending link lists
+                if time.time() > Transport.links_last_checked+Transport.links_check_interval:
+
+                    for link in Transport.pending_links:
+                        if link.status == RNS.Link.CLOSED:
+                            # If we are not a Transport Instance, finding a pending link
+                            # that was never activated will trigger an expiry of the path
+                            # to the destination, and an attempt to rediscover the path.
+                            if not RNS.Reticulum.transport_enabled():
+                                Transport.expire_path(link.destination.hash)
+
+                                # If we are connected to a shared instance, it will take
+                                # care of sending out a new path request. If not, we will
+                                # send one directly.
+                                if not Transport.owner.is_connected_to_shared_instance:
+                                    last_path_request = 0
+                                    if link.destination.hash in Transport.path_requests:
+                                        last_path_request = Transport.path_requests[link.destination.hash]
+
+                                    if time.time() - last_path_request > Transport.PATH_REQUEST_MI:
+                                        RNS.log("Trying to rediscover path for "+RNS.prettyhexrep(link.destination.hash)+" since an attempted link was never established", RNS.LOG_DEBUG)
+                                        if not link.destination.hash in path_requests:
+                                            path_requests.append(link.destination.hash)
+
+                            Transport.pending_links.remove(link)
+
+                    for link in Transport.active_links:
+                        if link.status == RNS.Link.CLOSED:
+                            Transport.active_links.remove(link)
+
+                    Transport.links_last_checked = time.time()
+
                 # Process receipts list for timed-out packets
                 if time.time() > Transport.receipts_last_checked+Transport.receipts_check_interval:
                     while len(Transport.receipts) > Transport.MAX_RECEIPTS:
@@ -379,8 +415,32 @@ class Transport:
                     stale_links = []
                     for link_id in Transport.link_table:
                         link_entry = Transport.link_table[link_id]
-                        if time.time() > link_entry[0] + Transport.LINK_TIMEOUT:
-                            stale_links.append(link_id)
+
+                        if link_entry[7] == True:
+                            if time.time() > link_entry[0] + Transport.LINK_TIMEOUT:
+                                stale_links.append(link_id)
+                        else:
+                            if time.time() > link_entry[8]:
+                                stale_links.append(link_id)
+
+                                last_path_request = 0
+                                if link_entry[6] in Transport.path_requests:
+                                    last_path_request = Transport.path_requests[link_entry[6]]
+
+                                # If this link request was originated from a local client
+                                # attempt to rediscover a path to the destination, if this
+                                # has not already happened recently.
+                                lr_taken_hops = link_entry[5]
+                                if lr_taken_hops == 0 and time.time() - last_path_request > Transport.PATH_REQUEST_MI:
+                                    RNS.log("Trying to rediscover path for "+RNS.prettyhexrep(link_entry[6])+" since an attempted local client link was never established", RNS.LOG_DEBUG)
+                                    if not link_entry[6] in path_requests:
+                                        path_requests.append(link_entry[6])
+
+                                    if not RNS.Reticulum.transport_enabled():
+                                        # Drop current path if we are not a transport instance, to
+                                        # allow using higher-hop count paths or reused announces
+                                        # from newly adjacent transport instances.
+                                        Transport.expire_path(link_entry[6])
 
                     # Cull the path table
                     stale_paths = []
@@ -503,6 +563,10 @@ class Transport:
 
                     Transport.tables_last_culled = time.time()
 
+            else:
+                # Transport jobs were locked, do nothing
+                pass
+
         except Exception as e:
             RNS.log("An exception occurred while running Transport jobs.", RNS.LOG_ERROR)
             RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -512,19 +576,47 @@ class Transport:
         for packet in outgoing:
             packet.send()
 
+        for destination_hash in path_requests:
+            Transport.request_path(destination_hash)
+
     @staticmethod
     def transmit(interface, raw):
         try:
             if hasattr(interface, "ifac_identity") and interface.ifac_identity != None:
                 # Calculate packet access code
-                ifac       = interface.ifac_identity.sign(raw)[-interface.ifac_size:]
+                ifac = interface.ifac_identity.sign(raw)[-interface.ifac_size:]
+
+                # Generate mask
+                mask = RNS.Cryptography.hkdf(
+                    length=len(raw)+interface.ifac_size,
+                    derive_from=ifac,
+                    salt=interface.ifac_key,
+                    context=None,
+                )
 
                 # Set IFAC flag
                 new_header = bytes([raw[0] | 0x80, raw[1]])
 
-                # Assemble new payload with IFAC and send it
+                # Assemble new payload with IFAC
                 new_raw    = new_header+ifac+raw[2:]
-                interface.processOutgoing(new_raw)
+                
+                # Mask payload
+                i = 0; masked_raw = b""
+                for byte in new_raw:
+                    if i == 0:
+                        # Mask first header byte, but make sure the
+                        # IFAC flag is still set
+                        masked_raw += bytes([byte ^ mask[i] | 0x80])
+                    elif i == 1 or i > interface.ifac_size+1:
+                        # Mask second header byte and payload
+                        masked_raw += bytes([byte ^ mask[i]])
+                    else:
+                        # Don't mask the IFAC itself
+                        masked_raw += bytes([byte])
+                    i += 1
+
+                # Send it
+                interface.processOutgoing(masked_raw)
 
             else:
                 interface.processOutgoing(raw)
@@ -539,9 +631,6 @@ class Transport:
 
         Transport.jobs_locked = True
 
-        # TODO: This updateHash call might be redundant
-        # packet.update_hash()
-
         sent = False
         outbound_time = time.time()
 
@@ -793,6 +882,8 @@ class Transport:
             return True
         if packet.context == RNS.Packet.CACHE_REQUEST:
             return True
+        if packet.context == RNS.Packet.CHANNEL:
+            return True
 
         if packet.destination_type == RNS.Destination.PLAIN:
             if packet.packet_type != RNS.Packet.ANNOUNCE:
@@ -833,7 +924,7 @@ class Transport:
     def inbound(raw, interface=None):
         # If interface access codes are enabled,
         # we must authenticate each packet.
-        if len(raw) > 1:
+        if len(raw) > 2:
             if interface != None and hasattr(interface, "ifac_identity") and interface.ifac_identity != None:
                 # Check that IFAC flag is set
                 if raw[0] & 0x80 == 0x80:
@@ -841,6 +932,26 @@ class Transport:
                         # Extract IFAC
                         ifac = raw[2:2+interface.ifac_size]
 
+                        # Generate mask
+                        mask = RNS.Cryptography.hkdf(
+                            length=len(raw),
+                            derive_from=ifac,
+                            salt=interface.ifac_key,
+                            context=None,
+                        )
+
+                        # Unmask payload
+                        i = 0; unmasked_raw = b""
+                        for byte in raw:
+                            if i <= 1 or i > interface.ifac_size+1:
+                                # Unmask header bytes and payload
+                                unmasked_raw += bytes([byte ^ mask[i]])
+                            else:
+                                # Don't unmask IFAC itself
+                                unmasked_raw += bytes([byte])
+                            i += 1
+                        raw = unmasked_raw
+
                         # Unset IFAC flag
                         new_header = bytes([raw[0] & 0x7f, raw[1]])
 
@@ -871,6 +982,9 @@ class Transport:
                     # If the flag is set, drop the packet
                     return
 
+        else:
+            return
+
         while (Transport.jobs_running):
             sleep(0.0005)
 
@@ -994,15 +1108,19 @@ class Transport:
                             outbound_interface = Transport.destination_table[packet.destination_hash][5]
 
                             if packet.packet_type == RNS.Packet.LINKREQUEST:
+                                now = time.time()
+                                proof_timeout = now + RNS.Link.ESTABLISHMENT_TIMEOUT_PER_HOP * max(1, remaining_hops)
+
                                 # Entry format is
-                                link_entry = [  time.time(),                    # 0: Timestamp,
+                                link_entry = [  now,                            # 0: Timestamp,
                                                 next_hop,                       # 1: Next-hop transport ID
                                                 outbound_interface,             # 2: Next-hop interface
                                                 remaining_hops,                 # 3: Remaining hops
                                                 packet.receiving_interface,     # 4: Received on interface
                                                 packet.hops,                    # 5: Taken hops
                                                 packet.destination_hash,        # 6: Original destination hash
-                                                False]                          # 7: Validated
+                                                False,                          # 7: Validated
+                                                proof_timeout]                  # 8: Proof timeout timestamp
 
                                 Transport.link_table[packet.getTruncatedHash()] = link_entry
 
@@ -1202,9 +1320,9 @@ class Transport:
                             
                             retransmit_timeout = now + (RNS.rand() * Transport.PATHFINDER_RW)
 
-                            if packet.receiving_interface.mode == RNS.Interfaces.Interface.Interface.MODE_ACCESS_POINT:
+                            if hasattr(packet.receiving_interface, "mode") and packet.receiving_interface.mode == RNS.Interfaces.Interface.Interface.MODE_ACCESS_POINT:
                                 expires            = now + Transport.AP_PATH_TIME
-                            elif packet.receiving_interface.mode == RNS.Interfaces.Interface.Interface.MODE_ROAMING:
+                            elif hasattr(packet.receiving_interface, "mode") and packet.receiving_interface.mode == RNS.Interfaces.Interface.Interface.MODE_ROAMING:
                                 expires            = now + Transport.ROAMING_PATH_TIME
                             else:
                                 expires            = now + Transport.PATHFINDER_E
@@ -1356,12 +1474,12 @@ class Transport:
                                         # Check that the announced destination matches
                                         # the handlers aspect filter
                                         execute_callback = False
+                                        announce_identity = RNS.Identity.recall(packet.destination_hash)
                                         if handler.aspect_filter == None:
                                             # If the handlers aspect filter is set to
                                             # None, we execute the callback in all cases
                                             execute_callback = True
                                         else:
-                                            announce_identity = RNS.Identity.recall(packet.destination_hash)
                                             handler_expected_hash = RNS.Destination.hash_from_name_and_identity(handler.aspect_filter, announce_identity)
                                             if packet.destination_hash == handler_expected_hash:
                                                 execute_callback = True
@@ -1377,10 +1495,11 @@ class Transport:
 
             # Handling for linkrequests to local destinations
             elif packet.packet_type == RNS.Packet.LINKREQUEST:
-                for destination in Transport.destinations:
-                    if destination.hash == packet.destination_hash and destination.type == packet.destination_type:
-                        packet.destination = destination
-                        destination.receive(packet)
+                if packet.transport_id == None or packet.transport_id == Transport.identity.hash:
+                    for destination in Transport.destinations:
+                        if destination.hash == packet.destination_hash and destination.type == packet.destination_type:
+                            packet.destination = destination
+                            destination.receive(packet)
             
             # Handling for local data packets
             elif packet.packet_type == RNS.Packet.DATA:
@@ -1414,14 +1533,29 @@ class Transport:
                     if (RNS.Reticulum.transport_enabled() or for_local_client_link or from_local_client) and packet.destination_hash in Transport.link_table:
                         link_entry = Transport.link_table[packet.destination_hash]
                         if packet.receiving_interface == link_entry[2]:
-                            # TODO: Should we validate the LR proof at each transport
-                            # step before transporting it?
-                            # RNS.log("Link request proof received on correct interface, transporting it via "+str(link_entry[4]), RNS.LOG_EXTREME)
-                            new_raw = packet.raw[0:1]
-                            new_raw += struct.pack("!B", packet.hops)
-                            new_raw += packet.raw[2:]
-                            Transport.link_table[packet.destination_hash][7] = True
-                            Transport.transmit(link_entry[4], new_raw)
+                            try:
+                                if len(packet.data) == RNS.Identity.SIGLENGTH//8+RNS.Link.ECPUBSIZE//2:
+                                    peer_pub_bytes = packet.data[RNS.Identity.SIGLENGTH//8:RNS.Identity.SIGLENGTH//8+RNS.Link.ECPUBSIZE//2]
+                                    peer_identity = RNS.Identity.recall(link_entry[6])
+                                    peer_sig_pub_bytes = peer_identity.get_public_key()[RNS.Link.ECPUBSIZE//2:RNS.Link.ECPUBSIZE]
+
+                                    signed_data = packet.destination_hash+peer_pub_bytes+peer_sig_pub_bytes
+                                    signature = packet.data[:RNS.Identity.SIGLENGTH//8]
+
+                                    if peer_identity.validate(signature, signed_data):
+                                        RNS.log("Link request proof validated for transport via "+str(link_entry[4]), RNS.LOG_EXTREME)
+                                        new_raw = packet.raw[0:1]
+                                        new_raw += struct.pack("!B", packet.hops)
+                                        new_raw += packet.raw[2:]
+                                        Transport.link_table[packet.destination_hash][7] = True
+                                        Transport.transmit(link_entry[4], new_raw)
+
+                                    else:
+                                        RNS.log("Invalid link request proof in transport for link "+RNS.prettyhexrep(packet.destination_hash)+", dropping proof.", RNS.LOG_DEBUG)
+
+                            except Exception as e:
+                                RNS.log("Error while transporting link request proof. The contained exception was: "+str(e), RNS.LOG_ERROR)
+
                         else:
                             RNS.log("Link request proof received on wrong interface, not transporting it.", RNS.LOG_DEBUG)
                     else:
@@ -1596,7 +1730,7 @@ class Transport:
 
     @staticmethod
     def register_link(link):
-        RNS.log("Registering link "+str(link), RNS.LOG_DEBUG)
+        RNS.log("Registering link "+str(link), RNS.LOG_EXTREME)
         if link.initiator:
             Transport.pending_links.append(link)
         else:
@@ -1604,7 +1738,7 @@ class Transport:
 
     @staticmethod
     def activate_link(link):
-        RNS.log("Activating link "+str(link), RNS.LOG_DEBUG)
+        RNS.log("Activating link "+str(link), RNS.LOG_EXTREME)
         if link in Transport.pending_links:
             Transport.pending_links.remove(link)
             Transport.active_links.append(link)
@@ -1825,6 +1959,7 @@ class Transport:
                     on_interface.announce_allowed_at = now + wait_time
 
         packet.send()
+        Transport.path_requests[destination_hash] = time.time()
 
     @staticmethod
     def path_request_handler(data, packet):
@@ -1901,10 +2036,9 @@ class Transport:
         
         local_destination = next((d for d in Transport.destinations if d.hash == destination_hash), None)
         if local_destination != None:
-            local_destination.announce(path_response=True)
+            local_destination.announce(path_response=True, tag=tag, attached_interface=attached_interface)
             RNS.log("Answering path request for "+RNS.prettyhexrep(destination_hash)+interface_str+", destination is local to this system", RNS.LOG_DEBUG)
 
-
         elif (RNS.Reticulum.transport_enabled() or is_from_local_client) and (destination_hash in Transport.destination_table):
             packet = Transport.destination_table[destination_hash][6]
             next_hop = Transport.destination_table[destination_hash][1]
@@ -1949,9 +2083,10 @@ class Transport:
             # Forward path request on all interfaces
             # except the local client
             RNS.log("Forwarding path request from local client for "+RNS.prettyhexrep(destination_hash)+interface_str+" to all other interfaces", RNS.LOG_DEBUG)
+            request_tag = RNS.Identity.get_random_hash()
             for interface in Transport.interfaces:
                 if not interface == attached_interface:
-                    Transport.request_path(destination_hash, interface)
+                    Transport.request_path(destination_hash, interface, tag = request_tag)
 
         elif should_search_for_unknown:
             if destination_hash in Transport.discovery_path_requests:
@@ -2078,41 +2213,42 @@ class Transport:
 
     @staticmethod
     def save_packet_hashlist():
-        if hasattr(Transport, "saving_packet_hashlist"):
-            wait_interval = 0.2
-            wait_timeout = 5
-            wait_start = time.time()
-            while Transport.saving_packet_hashlist:
-                time.sleep(wait_interval)
-                if time.time() > wait_start+wait_timeout:
-                    RNS.log("Could not save packet hashlist to storage, waiting for previous save operation timed out.", RNS.LOG_ERROR)
-                    return False
+        if not Transport.owner.is_connected_to_shared_instance:
+            if hasattr(Transport, "saving_packet_hashlist"):
+                wait_interval = 0.2
+                wait_timeout = 5
+                wait_start = time.time()
+                while Transport.saving_packet_hashlist:
+                    time.sleep(wait_interval)
+                    if time.time() > wait_start+wait_timeout:
+                        RNS.log("Could not save packet hashlist to storage, waiting for previous save operation timed out.", RNS.LOG_ERROR)
+                        return False
 
-        try:
-            Transport.saving_packet_hashlist = True
-            save_start = time.time()
+            try:
+                Transport.saving_packet_hashlist = True
+                save_start = time.time()
 
-            if not RNS.Reticulum.transport_enabled():
-                Transport.packet_hashlist = []
-            else:
-                RNS.log("Saving packet hashlist to storage...", RNS.LOG_DEBUG)
+                if not RNS.Reticulum.transport_enabled():
+                    Transport.packet_hashlist = []
+                else:
+                    RNS.log("Saving packet hashlist to storage...", RNS.LOG_DEBUG)
 
-            packet_hashlist_path = RNS.Reticulum.storagepath+"/packet_hashlist"
-            file = open(packet_hashlist_path, "wb")
-            file.write(umsgpack.packb(Transport.packet_hashlist))
-            file.close()
+                packet_hashlist_path = RNS.Reticulum.storagepath+"/packet_hashlist"
+                file = open(packet_hashlist_path, "wb")
+                file.write(umsgpack.packb(Transport.packet_hashlist))
+                file.close()
 
-            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"
-            RNS.log("Saved packet hashlist in "+time_str, RNS.LOG_DEBUG)
+                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"
+                RNS.log("Saved packet hashlist in "+time_str, RNS.LOG_DEBUG)
 
-        except Exception as e:
-            RNS.log("Could not save packet hashlist to storage, the contained exception was: "+str(e), RNS.LOG_ERROR)
+            except Exception as e:
+                RNS.log("Could not save packet hashlist to storage, the contained exception was: "+str(e), RNS.LOG_ERROR)
 
-        Transport.saving_packet_hashlist = False
+            Transport.saving_packet_hashlist = False
 
 
     @staticmethod
@@ -2270,4 +2406,4 @@ class Transport:
     @staticmethod
     def exit_handler():
         if not Transport.owner.is_connected_to_shared_instance:
-            Transport.persist_data()
+            Transport.persist_data()

RNS/Utilities/rnid.py

@@ -0,0 +1,519 @@
+#!/usr/bin/env python3
+
+# MIT License
+#
+# Copyright (c) 2023 Mark Qvist / unsigned.io
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# 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 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
+import sys
+import os
+import base64
+
+from RNS._version import __version__
+
+APP_NAME = "rnid"
+
+SIG_EXT = "rsg"
+ENCRYPT_EXT = "rfe"
+CHUNK_SIZE = 16*1024*1024
+
+def spin(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():
+        time.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
+
+def main():
+    try:
+        parser = argparse.ArgumentParser(description="Reticulum Identity & Encryption Utility")
+        # parser.add_argument("file", nargs="?", default=None, help="input file path", type=str)
+
+        parser.add_argument("--config", metavar="path", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser.add_argument("-i", "--identity", metavar="identity", action="store", default=None, help="hexadecimal Reticulum Destination hash or path to Identity file", type=str)
+        parser.add_argument("-g", "--generate", metavar="path", action="store", default=None, help="generate a new Identity")
+        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("-a", "--announce", metavar="aspects", action="store", default=None, help="announce a destination based on this Identity")
+        parser.add_argument("-H", "--hash", metavar="aspects", action="store", default=None, help="show destination hash5s for other aspects for this Identity")
+        parser.add_argument("-e", "--encrypt", metavar="path", action="store", default=None, help="encrypt file")
+        parser.add_argument("-d", "--decrypt", metavar="path", action="store", default=None, help="decrypt file")
+        parser.add_argument("-s", "--sign", metavar="path", action="store", default=None, help="sign file")
+        parser.add_argument("-V", "--validate", metavar="path", action="store", default=None, help="validate signature")
+
+        parser.add_argument("-r", "--read", metavar="path", action="store", default=None, help="input file path", type=str)
+        parser.add_argument("-w", "--write", metavar="path", action="store", default=None, help="output file path", type=str)
+        parser.add_argument("-f", "--force", action="store_true", default=None, help="write output even if it overwrites existing files")
+        parser.add_argument("-I", "--stdin", action="store_true", default=False, help=argparse.SUPPRESS) # "read input from STDIN instead of file"
+        parser.add_argument("-O", "--stdout", action="store_true", default=False, help=argparse.SUPPRESS) # help="write output to STDOUT instead of file", 
+
+        parser.add_argument("-R", "--request", action="store_true", default=False, help="request unknown Identities from the network")
+        parser.add_argument("-t", action="store", metavar="seconds", type=float, help="identity request timeout before giving up", default=RNS.Transport.PATH_REQUEST_TIMEOUT)
+        parser.add_argument("-p", "--print-identity", action="store_true", default=False, help="print identity info and exit")
+        parser.add_argument("-P", "--print-private", action="store_true", default=False, help="allow displaying private keys")
+
+        parser.add_argument("-b", "--base64", action="store_true", default=False, help=argparse.SUPPRESS) # help="Use base64-encoded input and output")
+
+        parser.add_argument("--version", action="version", version="rncp {version}".format(version=__version__))
+        
+        args = parser.parse_args()
+
+        ops = 0;
+        for t in [args.encrypt, args.decrypt, args.validate, args.sign]:
+            if t:
+                ops += 1
+        
+        if ops > 1:
+            RNS.log("This utility currently only supports one of the encrypt, decrypt, sign or verify operations per invocation", RNS.LOG_ERROR)
+            exit(1)
+
+        if not args.read:
+            if args.encrypt:
+                args.read = args.encrypt
+            if args.decrypt:
+                args.read = args.decrypt
+            if args.sign:
+                args.read = args.sign
+
+        identity_str = args.identity
+        if not args.generate and not identity_str:
+            print("\nNo identity provided, cannot continue\n")
+            parser.print_help()
+            print("")
+            exit(2)
+
+        else:
+            targetloglevel = 4
+            verbosity = args.verbose
+            quietness = args.quiet
+            if verbosity != 0 or quietness != 0:
+                targetloglevel = targetloglevel+verbosity-quietness
+            
+            # Start Reticulum
+            reticulum = RNS.Reticulum(configdir=args.config, loglevel=targetloglevel)
+            RNS.compact_log_fmt = True
+            if args.stdout:
+                RNS.loglevel = -1
+
+            if args.generate:
+                identity = RNS.Identity()
+                if not args.force and os.path.isfile(args.generate):
+                    RNS.log("Identity file "+str(args.generate)+" already exists. Not overwriting.", RNS.LOG_ERROR)
+                    exit(3)
+                else:
+                    try:
+                        identity.to_file(args.generate)
+                        RNS.log("New identity written to "+str(args.generate))
+                        exit(0)
+                    except Exception as e:
+                        RNS.log("An error ocurred while saving the generated Identity.", RNS.LOG_ERROR)
+                        RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                        exit(4)
+
+            identity = None
+            if len(identity_str) == RNS.Reticulum.TRUNCATED_HASHLENGTH//8*2 and not os.path.isfile(identity_str):
+                # Try recalling Identity from hex-encoded hash
+                try:
+                    destination_hash = bytes.fromhex(identity_str)
+                    identity = RNS.Identity.recall(destination_hash)
+
+                    if identity == None:
+                        if not args.request:
+                            RNS.log("Could not recall Identity for "+RNS.prettyhexrep(destination_hash)+".", RNS.LOG_ERROR)
+                            RNS.log("You can query the network for unknown Identities with the -R option.", RNS.LOG_ERROR)
+                            exit(5)
+                        else:
+                            RNS.Transport.request_path(destination_hash)
+                            def spincheck():
+                                return RNS.Identity.recall(destination_hash) != None
+                            spin(spincheck, "Requesting unknown Identity for "+RNS.prettyhexrep(destination_hash), args.t)
+
+                            if not spincheck():
+                                RNS.log("Identity request timed out", RNS.LOG_ERROR)
+                                exit(6)
+                            else:
+                                RNS.log("Received Identity "+str(identity)+" for destination "+RNS.prettyhexrep(destination_hash)+" from the network")
+                                identity = RNS.Identity.recall(destination_hash)
+
+                    else:
+                        RNS.log("Recalled Identity "+str(identity)+" for destination "+RNS.prettyhexrep(destination_hash))
+
+
+                except Exception as e:
+                    RNS.log("Invalid hexadecimal hash provided", RNS.LOG_ERROR)
+                    exit(7)
+
+                
+            else:
+                # Try loading Identity from file
+                if not os.path.isfile(identity_str):
+                    RNS.log("Specified Identity file not found")
+                    exit(8)
+                else:
+                    try:
+                        identity = RNS.Identity.from_file(identity_str)
+                        RNS.log("Loaded Identity "+str(identity)+" from "+str(identity_str))
+
+                    except Exception as e:
+                        RNS.log("Could not decode Identity from specified file")
+                        exit(9)
+
+            if identity != None:
+                if args.hash:
+                    try:
+                        aspects = args.hash.split(".")
+                        if not len(aspects) > 1:
+                            RNS.log("Invalid destination aspects specified", RNS.LOG_ERROR)
+                            exit(32)
+                        else:
+                            app_name = aspects[0]
+                            aspects = aspects[1:]
+                            if identity.pub != None:
+                                destination = RNS.Destination(identity, RNS.Destination.OUT, RNS.Destination.SINGLE, app_name, *aspects)
+                                RNS.log("The "+str(args.hash)+" destination for this Identity is "+RNS.prettyhexrep(destination.hash))
+                                RNS.log("The full destination specifier is "+str(destination))
+                                time.sleep(0.25)
+                                exit(0)
+                            else:
+                                raise KeyError("No public key known")
+                    except Exception as e:
+                        RNS.log("An error ocurred while attempting to send the announce.", RNS.LOG_ERROR)
+                        RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+
+                    exit(0)
+
+                if args.announce:
+                    try:
+                        aspects = args.announce.split(".")
+                        if not len(aspects) > 1:
+                            RNS.log("Invalid destination aspects specified", RNS.LOG_ERROR)
+                            exit(32)
+                        else:
+                            app_name = aspects[0]
+                            aspects = aspects[1:]
+                            if identity.prv != None:
+                                destination = RNS.Destination(identity, RNS.Destination.IN, RNS.Destination.SINGLE, app_name, *aspects)
+                                RNS.log("Created destination "+str(destination))
+                                RNS.log("Announcing destination "+RNS.prettyhexrep(destination.hash))
+                                destination.announce()
+                                time.sleep(0.25)
+                                exit(0)
+                            else:
+                                destination = RNS.Destination(identity, RNS.Destination.OUT, RNS.Destination.SINGLE, app_name, *aspects)
+                                RNS.log("The "+str(args.announce)+" destination for this Identity is "+RNS.prettyhexrep(destination.hash))
+                                RNS.log("The full destination specifier is "+str(destination))
+                                RNS.log("Cannot announce this destination, since the private key is not held")
+                                time.sleep(0.25)
+                                exit(33)
+                    except Exception as e:
+                        RNS.log("An error ocurred while attempting to send the announce.", RNS.LOG_ERROR)
+                        RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+
+                    exit(0)
+
+                if args.print_identity:
+                    RNS.log("Public Key  : "+RNS.hexrep(identity.pub_bytes, delimit=False))
+                    if identity.prv:
+                        if args.print_private:
+                            RNS.log("Private Key : "+RNS.hexrep(identity.prv_bytes, delimit=False))
+                        else:
+                            RNS.log("Private Key : Hidden")
+                    exit(0)
+
+                if args.validate:
+                    if not args.read and args.validate.lower().endswith("."+SIG_EXT):
+                        args.read = str(args.validate).replace("."+SIG_EXT, "")
+
+                    if not os.path.isfile(args.validate):
+                        RNS.log("Signature file "+str(args.read)+" not found", RNS.LOG_ERROR)
+                        exit(10)
+
+                    if not os.path.isfile(args.read):
+                        RNS.log("Input file "+str(args.read)+" not found", RNS.LOG_ERROR)
+                        exit(11)
+
+                data_input = None
+                if args.read:
+                    if not os.path.isfile(args.read):
+                        RNS.log("Input file "+str(args.read)+" not found", RNS.LOG_ERROR)
+                        exit(12)
+                    else:
+                        try:
+                            data_input = open(args.read, "rb")
+                        except Exception as e:
+                            RNS.log("Could not open input file for reading", RNS.LOG_ERROR)
+                            RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                            exit(13)
+
+                # TODO: Actually expand this to a good solution
+                # probably need to create a wrapper that takes
+                # into account not closing stdin when done
+                # elif args.stdin:
+                #     data_input = sys.stdin
+
+                data_output = None
+                if args.encrypt and not args.write and not args.stdout and args.read:
+                    args.write = str(args.read)+"."+ENCRYPT_EXT
+
+                if args.decrypt and not args.write and not args.stdout and args.read and args.read.lower().endswith("."+ENCRYPT_EXT):
+                    args.write = str(args.read).replace("."+ENCRYPT_EXT, "")
+
+                if args.sign and identity.prv == None:
+                    RNS.log("Specified Identity does not hold a private key. Cannot sign.", RNS.LOG_ERROR)
+                    exit(14)
+
+                if args.sign and not args.write and not args.stdout and args.read:
+                    args.write = str(args.read)+"."+SIG_EXT
+
+                if args.write:
+                    if not args.force and os.path.isfile(args.write):
+                        RNS.log("Output file "+str(args.write)+" already exists. Not overwriting.", RNS.LOG_ERROR)
+                        exit(15)
+                    else:
+                        try:
+                            data_output = open(args.write, "wb")
+                        except Exception as e:
+                            RNS.log("Could not open output file for writing", RNS.LOG_ERROR)
+                            RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                            exit(15)
+                
+                # TODO: Actually expand this to a good solution
+                # probably need to create a wrapper that takes
+                # into account not closing stdout when done
+                # elif args.stdout:
+                #     data_output = sys.stdout
+
+                if args.sign:
+                    if identity.prv == None:
+                        RNS.log("Specified Identity does not hold a private key. Cannot sign.", RNS.LOG_ERROR)
+                        exit(16)
+
+                    if not data_input:
+                        if not args.stdout:
+                            RNS.log("Signing requested, but no input data specified", RNS.LOG_ERROR)
+                        exit(17)
+                    else:
+                        if not data_output:
+                            if not args.stdout:
+                                RNS.log("Signing requested, but no output specified", RNS.LOG_ERROR)
+                            exit(18)
+
+                        if not args.stdout:
+                            RNS.log("Signing "+str(args.read))
+                        
+                        try:
+                            data_output.write(identity.sign(data_input.read()))
+                            data_output.close()
+                            data_input.close()
+                            
+                            if not args.stdout:
+                                if args.read:
+                                    RNS.log("File "+str(args.read)+" signed with "+str(identity)+" to "+str(args.write))
+                                    exit(0)
+
+                        except Exception as e:
+                            if not args.stdout:
+                                RNS.log("An error ocurred while encrypting data.", RNS.LOG_ERROR)
+                                RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                            try:
+                                data_output.close()
+                            except:
+                                pass
+                            try:
+                                data_input.close()
+                            except:
+                                pass
+                            exit(19)
+
+                if args.validate:
+                    if not data_input:
+                        if not args.stdout:
+                            RNS.log("Signature verification requested, but no input data specified", RNS.LOG_ERROR)
+                        exit(20)
+                    else:
+                        # if not args.stdout:
+                        #     RNS.log("Verifying "+str(args.validate)+" for "+str(args.read))
+                        
+                        try:
+                            try:
+                                sig_input = open(args.validate, "rb")
+                            except Exception as e:
+                                RNS.log("An error ocurred while opening "+str(args.validate)+".", RNS.LOG_ERROR)
+                                RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                                exit(21)
+
+
+                            validated = identity.validate(sig_input.read(), data_input.read())
+                            sig_input.close()
+                            data_input.close()
+
+                            if not validated:
+                                if not args.stdout:
+                                    RNS.log("Signature "+str(args.validate)+" for file "+str(args.read)+" is invalid", RNS.LOG_ERROR)
+                                exit(22)
+                            else:
+                                if not args.stdout:
+                                    RNS.log("Signature "+str(args.validate)+" for file "+str(args.read)+" made by Identity "+str(identity)+" is valid")
+                                exit(0)
+
+                        except Exception as e:
+                            if not args.stdout:
+                                RNS.log("An error ocurred while validating signature.", RNS.LOG_ERROR)
+                                RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                            try:
+                                data_output.close()
+                            except:
+                                pass
+                            try:
+                                data_input.close()
+                            except:
+                                pass
+                            exit(23)
+
+                if args.encrypt:
+                    if not data_input:
+                        if not args.stdout:
+                            RNS.log("Encryption requested, but no input data specified", RNS.LOG_ERROR)
+                        exit(24)
+                    else:
+                        if not data_output:
+                            if not args.stdout:
+                                RNS.log("Encryption requested, but no output specified", RNS.LOG_ERROR)
+                            exit(25)
+
+                        if not args.stdout:
+                            RNS.log("Encrypting "+str(args.read))
+                        
+                        try:
+                            more_data = True
+                            while more_data:
+                                chunk = data_input.read(CHUNK_SIZE)
+                                if chunk:
+                                    data_output.write(identity.encrypt(chunk))
+                                else:
+                                    more_data = False
+                            data_output.close()
+                            data_input.close()
+                            if not args.stdout:
+                                if args.read:
+                                    RNS.log("File "+str(args.read)+" encrypted for "+str(identity)+" to "+str(args.write))
+                                    exit(0)
+
+                        except Exception as e:
+                            if not args.stdout:
+                                RNS.log("An error ocurred while encrypting data.", RNS.LOG_ERROR)
+                                RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                            try:
+                                data_output.close()
+                            except:
+                                pass
+                            try:
+                                data_input.close()
+                            except:
+                                pass
+                            exit(26)
+
+                if args.decrypt:
+                    if identity.prv == None:
+                        RNS.log("Specified Identity does not hold a private key. Cannot decrypt.", RNS.LOG_ERROR)
+                        exit(27)
+
+                    if not data_input:
+                        if not args.stdout:
+                            RNS.log("Decryption requested, but no input data specified", RNS.LOG_ERROR)
+                        exit(28)
+                    else:
+                        if not data_output:
+                            if not args.stdout:
+                                RNS.log("Decryption requested, but no output specified", RNS.LOG_ERROR)
+                            exit(29)
+
+                        if not args.stdout:
+                            RNS.log("Decrypting "+str(args.read)+"...")
+                        
+                        try:
+                            more_data = True
+                            while more_data:
+                                chunk = data_input.read(CHUNK_SIZE)
+                                if chunk:
+                                    plaintext = identity.decrypt(chunk)
+                                    if plaintext == None:
+                                        if not args.stdout:
+                                            RNS.log("Data could not be decrypted with the specified Identity")
+                                        exit(30)
+                                    else:
+                                        data_output.write(plaintext)
+                                else:
+                                    more_data = False
+                            data_output.close()
+                            data_input.close()
+                            if not args.stdout:
+                                if args.read:
+                                    RNS.log("File "+str(args.read)+" decrypted with "+str(identity)+" to "+str(args.write))
+                                    exit(0)
+
+                        except Exception as e:
+                            if not args.stdout:
+                                RNS.log("An error ocurred while decrypting data.", RNS.LOG_ERROR)
+                                RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                            try:
+                                data_output.close()
+                            except:
+                                pass
+                            try:
+                                data_input.close()
+                            except:
+                                pass
+                            exit(31)
+
+            if True:
+                pass
+
+            elif False:
+                pass
+
+            else:
+                print("")
+                parser.print_help()
+                print("")
+
+    except KeyboardInterrupt:
+        print("")
+        exit(255)
+
+if __name__ == "__main__":
+    main()

RNS/Utilities/rnstatus.py

@@ -46,7 +46,7 @@ def size_str(num, suffix='B'):
 
     return "%.2f%s%s" % (num, last_unit, suffix)
 
-def program_setup(configdir, dispall=False, verbosity=0, name_filter=None):
+def program_setup(configdir, dispall=False, verbosity=0, name_filter=None,json=False):
     reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity)
 
     stats = None
@@ -56,6 +56,21 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None):
         pass
 
     if stats != None:
+        if json:
+            import json
+            for s in stats:
+                if isinstance(stats[s], bytes):
+                    stats[s] = RNS.hexrep(stats[s], delimit=False)
+
+                for i in stats[s]:
+                    if isinstance(i, dict):
+                        for k in i:
+                            if isinstance(i[k], bytes):
+                                i[k] = RNS.hexrep(i[k], delimit=False)
+
+            print(json.dumps(stats))
+            exit()
+            
         for ifstat in stats["interfaces"]:
             name = ifstat["name"]
 
@@ -135,6 +150,9 @@ def program_setup(configdir, dispall=False, verbosity=0, name_filter=None):
                         if "peers" in ifstat and ifstat["peers"] != None:
                             print("    Peers   : {np} reachable".format(np=ifstat["peers"]))
 
+                        if "tunnelstate" in ifstat and ifstat["tunnelstate"] != None:
+                            print("    I2P     : {ts}".format(ts=ifstat["tunnelstate"]))
+
                         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))
@@ -172,6 +190,14 @@ def main():
             help="show all interfaces",
             default=False
         )
+        
+        parser.add_argument(
+            "-j",
+            "--json",
+            action="store_true",
+            help="output in JSON format",
+            default=False
+        )
 
         parser.add_argument('-v', '--verbose', action='count', default=0)
 
@@ -184,7 +210,7 @@ def main():
         else:
             configarg = None
 
-        program_setup(configdir = configarg, dispall = args.all, verbosity=args.verbose, name_filter=args.filter)
+        program_setup(configdir = configarg, dispall = args.all, verbosity=args.verbose, name_filter=args.filter, json=args.json)
 
     except KeyboardInterrupt:
         print("")

RNS/__init__.py

@@ -32,6 +32,8 @@ from ._version import __version__
 from .Reticulum import Reticulum
 from .Identity import Identity
 from .Link import Link, RequestReceipt
+from .Channel import MessageBase
+from .Buffer import Buffer, RawChannelReader, RawChannelWriter
 from .Transport import Transport
 from .Destination import Destination
 from .Packet import Packet
@@ -217,14 +219,17 @@ def prettytime(time, verbose=False):
 
         tstr += c
 
-    return tstr
+    if tstr == "":
+        return "0s"
+    else:
+        return tstr
 
 def phyparams():
     print("Required Physical Layer MTU : "+str(Reticulum.MTU)+" bytes")
     print("Plaintext Packet MDU        : "+str(Packet.PLAIN_MDU)+" bytes")
     print("Encrypted Packet MDU        : "+str(Packet.ENCRYPTED_MDU)+" bytes")
     print("Link Curve                  : "+str(Link.CURVE))
-    print("Link Packet MDU             : "+str(Packet.ENCRYPTED_MDU)+" bytes")
+    print("Link Packet MDU             : "+str(Link.MDU)+" bytes")
     print("Link Public Key Size        : "+str(Link.ECPUBSIZE*8)+" bits")
     print("Link Private Key Size       : "+str(Link.KEYSIZE*8)+" bits")
 

RNS/_version.py

@@ -1 +1 @@
-__version__ = "0.4.0"
+__version__ = "0.5.0"

Roadmap.md

@@ -0,0 +1,112 @@
+# Reticulum Development Roadmap
+This document outlines the currently established development roadmap for Reticulum.
+
+1. [Currently Active Work Areas](#currently-active-work-areas)
+2. [Primary Efforts](#primary-efforts)
+    - [Comprehensibility](#comprehensibility)
+    - [Universality](#universality)
+    - [Functionality](#functionality)
+    - [Usability & Utility](#usability--utility)
+    - [Interfaceability](#interfaceability)
+3. [Auxillary Efforts](#auxillary-efforts)
+4. [Release History](#release-history)
+
+## Currently Active Work Areas
+For each release cycle of Reticulum, improvements and additions from the five [Primary Efforts](#primary-efforts) are selected as active work areas, and can be expected to be included in the upcoming releases within that cycle. While not entirely set in stone for each release cycle, they serve as a pointer of what to expect in the near future.
+
+- The current `0.5.x` release cycle aims at completing
+  - [ ] Overhauling and updating the documentation
+  - [ ] Performance and memory optimisations of the Python reference implementation
+  - [ ] Fixing potential bugs
+  - [ ] Add automatic retries to all use cases of the `Request` API
+  - [ ] Improve performance and efficiency of the `Buffer` and `Channel` API
+
+## Primary Efforts
+The development path for Reticulum is currently laid out in five distinct areas: *Comprehensibility*, *Universality*, *Functionality*, *Usability & Utility* and *Interfaceability*. Conceptualising the development of Reticulum into these areas serves to advance the implementation and work towards the Foundational Goals & Values of Reticulum.
+
+### Comprehensibility
+These efforts are aimed at improving the ease of which Reticulum is understood, and lowering the barrier to entry for people who wish to start building systems on Reticulum.
+
+- Improving [the manual](https://markqvist.github.io/Reticulum/manual/) with tutorials specifically for beginners
+- Updating the documentation to reflect recent changes and improvements
+    - Update descriptions of protocol mechanics
+        - Update announce description
+        - Add in-depth explanation of the IFAC system
+    - Software
+        - Update Sideband screenshots
+        - Update Sideband description
+        - Update NomadNet screenshots
+        - Update Sideband screenshots
+    - Installation
+        - Install docs for fedora, needs `python3-netifaces`
+        - Add a *Reticulum On Raspberry Pi* section
+        - Update *Reticulum On Android* section if necessary
+        - Update Android install documentation.
+    - Communications hardware section
+        - Add information about RNode external displays.
+        - Packet radio modems.
+        - Possibly add other relevant types here as well.
+    - Setup *Best Practices For...* / *Installation Examples* section.
+        - Home or office (example)
+        - Vehicles (example)
+        - No-grid/solar/remote sites (example)
+
+### Universality
+These efforts seek to broaden the universality of the Reticulum software and hardware ecosystem by continously diversifying platform support, and by improving the overall availability and ease of deployment of the Reticulum stack.
+
+- OpenWRT support
+- Create a standalone RNS Daemon app for Android
+- A lightweight and portable C implementation for microcontrollers, µRNS
+- A portable, high-performance Reticulum implementation in C/C++, see [#21](https://github.com/markqvist/Reticulum/discussions/21)
+- Performance and memory optimisations of the Python implementation
+- Bindings for other programming languages
+
+### Functionality
+These efforts aim to expand and improve the core functionality and reliability of Reticulum.
+
+- Add automatic retries to all use cases of the `Request` API
+- Network-wide path balancing
+- Distributed Destination Naming System
+- Globally routable multicast
+- Destination proxying
+- [Metric-based path selection and multiple paths](https://github.com/markqvist/Reticulum/discussions/86)
+
+### Usability & Utility
+These effors seek to make Reticulum easier to use and operate, and to expand the utility of the stack on deployed systems.
+
+- Add bluetooth pairing code output to rnodeconf
+- Easy way to share interface configurations, see [#19](https://github.com/markqvist/Reticulum/discussions/19)
+- Transit traffic display in rnstatus
+- rnsconfig utility
+
+### Interfaceability
+These efforts aim to expand the types of physical and virtual interfaces that Reticulum can natively use to transport data.
+
+- Filesystem interface
+- Plain ESP32 devices (ESP-Now, WiFi, Bluetooth, etc.)
+- More LoRa transceivers
+- AT-compatible modems
+- Direct SDR Support
+- Optical mediums
+- IR Transceivers
+- AWDL / OWL
+- HF Modems
+- GNU Radio
+- CAN-bus
+- Raw SPI
+- Raw i²c
+- MQTT
+- XBee
+- Tor
+
+## Auxillary Efforts
+The Reticulum ecosystem is enriched by several other software and hardware projects, and the support and improvement of these, in symbiosis with the core Reticulum project helps expand the reach and utility of Reticulum itself.
+
+This section lists, in no particular order, various important efforts that would be beneficial to the goals of Reticulum.
+
+- The [RNode](https://unsigned.io/rnode/) project
+    - [ ] Create a WebUSB-based bootstrapping utility, and integrate this directly into the [RNode Bootstrap Console](#), both on-device, and on an Internet-reachable copy. This will make it much easier to create new RNodes for average users.
+
+## Release History
+
+Please see the [Changelog](./Changelog.md) for a complete release history and changelog of Reticulum.

docs/Makefile

@@ -30,3 +30,8 @@ help:
 		cp -r build/latex/reticulumnetworkstack.pdf ./Reticulum\ Manual.pdf; \
 		echo "PDF Manual Generated"; \
 	fi
+
+	@if [ $@ = "epub" ]; then \
+		cp -r build/epub/ReticulumNetworkStack.epub ./Reticulum\ Manual.epub; \
+		echo "EPUB Manual Generated"; \
+	fi

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: 8cba159fb1f90a14d69c2399fad83a44
+config: d8447d44585d036754ef13c1e3b2bcb2
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/manual/_sources/examples.rst.txt

@@ -92,6 +92,28 @@ The *Request* example explores sendig requests and receiving responses.
 
 This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py>`_.
 
+.. _example-channel:
+
+Channel
+=======
+
+The *Channel* example explores using a ``Channel`` to send structured
+data between peers of a ``Link``.
+
+.. literalinclude:: ../../Examples/Channel.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Channel.py>`_.
+
+Buffer
+======
+
+The *Buffer* example explores using buffered readers and writers to send
+binary data between peers of a ``Link``.
+
+.. literalinclude:: ../../Examples/Buffer.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Buffer.py>`_.
+
 .. _example-filetransfer:
 
 Filetransfer

docs/manual/_sources/forhumans.rst.txt

@@ -0,0 +1,4 @@
+********************************************
+An Explanation of Reticulum for Human Beings
+********************************************
+

docs/manual/_sources/gettingstartedfast.rst.txt

@@ -7,22 +7,48 @@ you want to do. This guide will outline sensible starting paths for different
 scenarios.
 
 
+Standalone Reticulum Installation
+=============================================
+If you simply want to install Reticulum and related utilities on a system,
+the easiest way is via ``pip``:
+
+.. code::
+
+   pip install rns
+
+If you no not already have pip installed, you can install it using the package manager
+of your system with a command like ``sudo apt install python3-pip``,
+``sudo pamac install python-pip`` or similar. You can also dowload the Reticulum release
+wheels from GitHub, or other release channels, and install them offline using ``pip``:
+
+.. code::
+
+   pip install ./rns-0.4.6-py3-none-any.whl
+
+
 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
-over even extremely low-bandwidth Reticulum networks.
+programs exist that allow basic communication and a range of 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 completely
-over local WiFi, wired Ethernet, the Internet, or any combination.
+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.
+
 Nomad Network
 ^^^^^^^^^^^^^
 
@@ -44,7 +70,7 @@ You can install Nomad Network via pip:
 .. code::
 
    # Install ...
-   pip3 install nomadnet
+   pip install nomadnet
 
    # ... and run
    nomadnet
@@ -61,12 +87,22 @@ 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 and macOS.
 
-.. image:: screenshots/sideband_1.png
-    :align: center
-    :target: _images/sideband_1.png
+.. only:: html
 
-Sideband is currently in the early stages of development, but already provides basic
-communication features, and interoperates with Nomad Network, or any other LXMF client.
+  .. image:: screenshots/sideband_devices.webp
+      :align: center
+      :target: _images/sideband_devices.webp
+
+.. only:: latexpdf
+
+  .. 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.
 
 Using the Included Utilities
 =============================================
@@ -86,8 +122,8 @@ Creating a Network With Reticulum
 =============================================
 To create a network, you will need to specify one or more *interfaces* for
 Reticulum to use. This is done in the Reticulum configuration file, which by
-default is located at ``~/.reticulum/config``. You can edit this file by hand,
-or use the interactive ``rnsconfig`` utility. 
+default is located at ``~/.reticulum/config``. You can get an example
+configuration file with all options via ``rnsd --exampleconfig``.
 
 When Reticulum is started for the first time, it will create a default
 configuration file, with one active interface. This default interface uses
@@ -168,7 +204,7 @@ by adding one of the following interfaces to your ``.reticulum/config`` file:
     target_port = 4965
 
   # TCP/IP interface to the Frankfurt hub
-  [[RNS Testnet Dublin]]
+  [[RNS Testnet Frankfurt]]
     type = TCPClientInterface
     enabled = yes
     target_host = frankfurt.connect.reticulum.network
@@ -205,7 +241,7 @@ chapter for a guide. If you prefer purchasing a ready-made unit, you can refer t
 refer to these additional external resources:
 
 * `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
-* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
+* `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/>`_
 
@@ -272,7 +308,7 @@ don't use pip, but try this recipe:
 
     # Run the example in client mode to "ping" the server.
     # Replace the hash below with the actual destination hash of your server.
-    python3 Examples/Echo.py 3e12fc71692f8ec47bc5
+    python3 Examples/Echo.py 174a64852a75682259ad8b921b8bf416
 
     # Have a look at another example
     python3 Examples/Filetransfer.py -h
@@ -287,7 +323,7 @@ or ask one of the developers or maintainers for a good place to start.
 Reticulum on ARM64
 ==============================================
 On some architectures, including ARM64, not all dependencies have precompiled
-binaries. On such systems, you will need to install ``python3-dev`` before
+binaries. On such systems, you may need to install ``python3-dev`` before
 installing Reticulum or programs that depend on Reticulum.
 
 .. code::
@@ -300,6 +336,12 @@ installing Reticulum or programs that depend on Reticulum.
    python3 -m pip install rns
 
 
+Reticulum on Raspberry Pi
+==============================================
+It is currently recommended to use a 64-bit version of the Raspberry Pi OS
+if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
+don't always have packages available for some dependencies.
+
 Reticulum on Android
 ==============================================
 Reticulum can be used on Android in different ways. The easiest way to get
@@ -313,12 +355,31 @@ Termux is a terminal emulator and Linux environment for Android based devices,
 which includes the ability to use many different programs and libraries,
 including Reticulum.
 
-Since the Python cryptography.io module does not offer pre-built wheels for
-Android, the standard one-line install of Reticulum does not work on Android,
-and a few extra commands are required.
+To use Reticulum within the Termux environment, you will need to install
+``python`` and the ``python-cryptography`` library using ``pkg``, the package-manager
+build into Termux. After that, you can use ``pip`` to install Reticulum.
 
 From within Termux, execute the following:
 
+.. code::
+
+    # First, make sure indexes and packages are up to date.
+    pkg update
+    pkg upgrade
+
+    # Then install python and the cryptography library.
+    pkg install python python-cryptography
+
+    # Make sure pip is up to date, and install the wheel module.
+    pip install wheel pip --upgrade
+
+    # Install Reticulum
+    pip install rns
+
+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::
 
     # First, make sure indexes and packages are up to date.
@@ -329,7 +390,7 @@ From within Termux, execute the following:
     pkg install python build-essential openssl libffi rust
 
     # Make sure pip is up to date, and install the wheel module.
-    pip3 install wheel pip --upgrade
+    pip install wheel pip --upgrade
 
     # To allow the installer to build the cryptography module,
     # we need to let it know what platform we are compiling for:
@@ -338,11 +399,11 @@ From within Termux, execute the following:
     # Start the install process for the cryptography module.
     # Depending on your device, this can take several minutes,
     # since the module must be compiled locally on your device.
-    pip3 install cryptography
+    pip install cryptography
 
     # If the above installation succeeds, you can now install
     # Reticulum and any related software
-    pip3 install rns
+    pip install rns
 
 It is also possible to include Reticulum in apps compiled and distributed as
 Android APKs. A detailed tutorial and example source code will be included
@@ -355,7 +416,8 @@ install one or more dependencies
 
 On more unusual systems, and in some rare cases, it might not be possible to
 install or even compile one or more of the above modules. In such situations,
-you can use the ``rnspure`` package instead of the ``rns`` package. The ``rnspure``
+you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip``
+with the ``--no-dependencies`` command-line option. The ``rnspure``
 package requires no external dependencies for installation. Please note that the
 actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*.
 The only difference is that the ``rnspure`` package lists no dependencies required

docs/manual/_sources/hardware.rst.txt

@@ -160,12 +160,13 @@ Installation
 
 Once you have obtained compatible boards, you can install the `RNode Firmware <https://github.com/markqvist/RNode_Firmware>`_
 using the `RNode Configuration Utility <https://github.com/markqvist/rnodeconfigutil>`_.
-Make sure that ``Python3`` and ``pip`` is installed on your system, and then install
-the config utility with ``pip``:
+If you have installed Reticulum on your system, the ``rnodeconf`` program will already be
+available. If not, make sure that ``Python3`` and ``pip`` is installed on your system, and
+then install Reticulum with with ``pip``:
 
 .. code::
 
-   pip3 install rnodeconf
+   pip install rns
 
 Once installation has completed, it is time to start installing the firmware on your
 devices. Run ``rnodeconf`` in auto-install mode like so:
@@ -176,12 +177,7 @@ devices. Run ``rnodeconf`` in auto-install mode like so:
 
 The utility will guide you through the installation process by asking a series of
 questions about your hardware. Simply follow the guide, and the utility will
-auto-install and configure your devices
-
-**Important Note!** It is currently recommended to use the v1.x line of the RNode firmware,
-even though the v2.x line is available for early testing. The v2.x line should still be
-considered an experimental pre-release. Only use the v2.x firmware line if you want to test
-out the absolutely newest version, and don't care about stability.
+auto-install and configure your devices.
 
 .. _rnode-usage:
 

docs/manual/_sources/index.rst.txt

@@ -5,6 +5,10 @@ This manual aims to provide you with all the information you need to
 understand Reticulum, build networks or develop programs using it, or
 to participate in the development of Reticulum itself.
 
+.. only:: html
+
+This manual is also available in `PDF <https://github.com/markqvist/Reticulum/releases/latest/download/Reticulum.Manual.pdf>`_ and `EPUB <https://github.com/markqvist/Reticulum/releases/latest/download/Reticulum.Manual.epub>`_ formats.
+
 .. only:: html
 
    Table Of Contents

docs/manual/_sources/reference.rst.txt

@@ -121,6 +121,76 @@ This chapter lists and explains all classes exposed by the Reticulum Network Sta
 .. autoclass:: RNS.Resource(data, link, advertise=True, auto_compress=True, callback=None, progress_callback=None, timeout=None)
    :members:
 
+.. _api-channel:
+
+.. only:: html
+
+   |start-h3| Channel |end-h3|
+
+.. only:: latex
+
+   Channel
+   -------
+
+.. autoclass:: RNS.Channel.Channel()
+   :members:
+
+.. _api-messsagebase:
+
+.. only:: html
+
+   |start-h3| MessageBase |end-h3|
+
+.. only:: latex
+
+   MessageBase
+   -----------
+
+.. autoclass:: RNS.MessageBase()
+   :members:
+
+.. _api-buffer:
+
+.. only:: html
+
+   |start-h3| Buffer |end-h3|
+
+.. only:: latex
+
+   Buffer
+   ------
+
+.. autoclass:: RNS.Buffer
+   :members:
+
+.. _api-rawchannelreader:
+
+.. only:: html
+
+   |start-h3| RawChannelReader |end-h3|
+
+.. only:: latex
+
+   RawChannelReader
+   ----------------
+
+.. autoclass:: RNS.RawChannelReader
+   :members: __init__, add_ready_callback, remove_ready_callback
+
+.. _api-rawchannelwriter:
+
+.. only:: html
+
+   |start-h3| RawChannelWriter |end-h3|
+
+.. only:: latex
+
+   RawChannelWriter
+   ----------------
+
+.. autoclass:: RNS.RawChannelWriter
+   :members: __init__
+
 .. _api-transport:
 
 .. only:: html

docs/manual/_sources/understanding.rst.txt

@@ -107,13 +107,13 @@ guide the design of Reticulum:
 Introduction & Basic Functionality
 ==================================
 
-Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
+Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at its
 core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint
 scenarios where all nodes are within range of each other, as well as scenarios where packets need
 to be transported over multiple hops in a complex network to reach the recipient.
 
 Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
-Reticulum uses the singular concept of *destinations*. Any application using Reticulum as it’s
+Reticulum uses the singular concept of *destinations*. Any application using Reticulum as its
 networking stack will need to create one or more destinations to receive data, and know the
 destinations it needs to send data to.
 
@@ -220,7 +220,7 @@ packet.
 
 In actual use of *single* destination naming, it is advisable not to use any uniquely identifying
 features in aspect naming. Aspect names should be general terms describing what kind of destination
-is represented. The uniquely identifying aspect is always achieved by the appending the public key,
+is represented. The uniquely identifying aspect is always achieved by appending the public key,
 which expands the destination into a uniquely identifiable one. Reticulum does this automatically.
 
 Any destination on a Reticulum network can be addressed and reached simply by knowing its
@@ -239,7 +239,7 @@ To recap, the different destination types should be used in the following situat
 * **Plain**
     When plain-text communication is desirable, for example when broadcasting information, or for local discovery purposes.
 
-To communicate with a *single* destination, you need to know it’s public key. Any method for
+To communicate with a *single* destination, you need to know its public key. Any method for
 obtaining the public key is valid, but Reticulum includes a simple mechanism for making other
 nodes aware of your destinations public key, called the *announce*. It is also possible to request
 an unknown public key from the network, as all transport instances serve as a distributed ledger
@@ -287,7 +287,7 @@ In Reticulum, destinations are allowed to move around the network at will. This
 protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
 This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography
 of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and
-still become reachable. To update it's reachability, a destination simply needs to send an announce on any
+still become reachable. To update its reachability, a destination simply needs to send an announce on any
 networks it is part of. After a short while, it will be globally reachable in the network.
 
 Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic.
@@ -368,7 +368,7 @@ If it is a *Transport Node*, it should be given the configuration directive ``en
 The Announce Mechanism in Detail
 --------------------------------
 
-When an *announce* for a destination is transmitted by from a Reticulum instance, it will be forwarded by
+When an *announce* for a destination is transmitted by a Reticulum instance, it will be forwarded by
 any transport node receiving it, but according to some specific rules:
 
 
@@ -385,7 +385,7 @@ any transport node receiving it, but according to some specific rules:
     announces is set at 2%, but can be configured on a per-interface basis.
 
 * | If any given interface does not have enough bandwidth available for retransmitting the announce,
-    the announce will be assigned a priority inversely proportional to it's hop count, and be inserted
+    the announce will be assigned a priority inversely proportional to its hop count, and be inserted
     into a queue managed by the interface.
 
 * | When the interface has bandwidth available for processing an announce, it will prioritise announces
@@ -431,7 +431,7 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
 
 * | A packet is always created with an associated destination and some payload data. When the packet is sent
     to a *single* destination type, Reticulum will automatically create an ephemeral encryption key, perform
-    an ECDH key exchange with the destinations public key, and encrypt the information.
+    an ECDH key exchange with the destination's public key, 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
@@ -447,8 +447,8 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
 
 * | Once the packet has been received and decrypted by the addressed destination, that destination can opt
     to *prove* its receipt of the packet. It does this by calculating the SHA-256 hash of the received packet,
-    and signing this hash with it's Ed25519 signing key. Transport nodes in the network can then direct this
-    *proof* back to the packets origin, where the signature can be verified against the destinations known
+    and signing this hash with its Ed25519 signing key. Transport nodes in the network can then direct this
+    *proof* back to the packets origin, where the signature can be verified against the destination's known
     public signing key.
 
 * | In case the packet is addressed to a *group* destination type, the packet will be encrypted with the
@@ -465,7 +465,7 @@ For exchanges of larger amounts of data, or when longer sessions of bidirectiona
     forward the packet will take note of this *link request*.
 
 * | Second, if the destination accepts the *link request* , it will send back a packet that proves the
-    authenticity of it’s identity (and the receipt of the link request) to the initiating node. All
+    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.
 
@@ -771,7 +771,7 @@ Wire Format
     |               | |               | |               | |    |
     00000000 00000111 [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
     || | | |    |
-    || | | |    +-- Hops             = 0
+    || | | |    +-- Hops             = 7
     || | | +------- Packet Type      = DATA
     || | +--------- Destination Type = SINGLE
     || +----------- Propagation Type = BROADCAST
@@ -786,7 +786,7 @@ Wire Format
     |               | |             | |               | |               | |    |
     10000000 00000111 [IFAC, N bytes] [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
     || | | |    |
-    || | | |    +-- Hops             = 0
+    || | | |    +-- Hops             = 7
     || | | +------- Packet Type      = DATA
     || | +--------- Destination Type = SINGLE
     || +----------- Propagation Type = BROADCAST

docs/manual/_sources/using.rst.txt

@@ -5,7 +5,9 @@ Using Reticulum on Your System
 ******************************
 
 Reticulum is not installed as a driver or kernel module, as one might expect
-of a networking stack. Instead, Reticulum is distributed as a Python module.
+of a networking stack. Instead, Reticulum is distributed as a Python module, 
+containing the networking core, and a set of utility and daemon programs.
+
 This means that no special privileges are required to install or use it. It
 is also very light-weight, and easy to transfer to, and install on new systems.
 
@@ -16,8 +18,8 @@ already running.
 In many cases, this approach is sufficient. When any program needs to use
 Reticulum, it is loaded, initialised, interfaces are brought up, and the
 program can now communicate over any Reticulum networks available. If another
-program starts up and also wants access to the same Reticulum network, the
-instance is simply shared. This works for any number of programs running
+program starts up and also wants access to the same Reticulum network, the already
+running instance is simply shared. This works for any number of programs running
 concurrently, and is very easy to use, but depending on your use case, there
 are other options.
 
@@ -375,7 +377,7 @@ output.
 
   # Run rnx on the listening system, specifying which identities
   # are allowed to execute commands
-  rncp --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+  rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
 
   # From another system, run a command 
   rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
@@ -425,6 +427,50 @@ You can specify as many allowed senders as needed, or completely disable authent
     --version             show program's version number and exit
 
 
+The rnodeconf Utility
+=====================
+
+The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and
+to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices.
+
+.. code:: text
+
+  usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-C] [-N] [-T] [-b] [-B] [-p] [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [--version] [port]
+
+  RNode Configuration and firmware utility. This program allows you to change various settings and startup modes of RNode. It can also install, flash and update the firmware on supported devices.
+
+  positional arguments:
+    port                  serial port where RNode is attached
+
+  options:
+    -h, --help            show this help message and exit
+    -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
+    --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
+    -C, --clear-cache     Clear locally cached firmware files
+    -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
+    --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)
+    --eeprom-backup       Backup EEPROM to file
+    --eeprom-dump         Dump EEPROM to console
+    --eeprom-wipe         Unlock and wipe EEPROM
+    --version             Print program version and exit
+
+For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>`
+section of this manual.
+
 Improving System Configuration
 ------------------------------
 
@@ -519,4 +565,4 @@ If you want to automatically start ``rnsd`` at boot, run:
 
 .. code:: text
 
-  sudo systemctl enable rnsd
+  sudo systemctl enable rnsd

docs/manual/_sources/whatis.rst.txt

@@ -162,7 +162,7 @@ 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 been externally security audited, and there could very well be
+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, or help sponsor an audit, please do get in touch.
+want to help out with this, or can help sponsor an audit, please do get in touch.

docs/manual/_static/documentation_options.js

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

docs/manual/examples.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Support Reticulum" href="support.html" /><link rel="prev" title="Building Networks" href="networks.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>Code Examples - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>Code Examples - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -861,6 +861,7 @@ the Packet interface.</p>
             <span class="c1"># If we do not know this destination, tell the</span>
             <span class="c1"># user to wait for an announce to arrive.</span>
             <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Destination is not yet known. Requesting path...&quot;</span><span class="p">)</span>
+            <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Hit enter to manually retry once an announce is received.&quot;</span><span class="p">)</span>
             <span class="n">RNS</span><span class="o">.</span><span class="n">Transport</span><span class="o">.</span><span class="n">request_path</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">)</span>
 
 <span class="c1"># This function is called when our reply destination</span>
@@ -1632,8 +1633,8 @@ the link has been established.</p>
 <span class="c1"># A reference to the latest client link that connected</span>
 <span class="n">latest_client_link</span> <span class="o">=</span> <span class="kc">None</span>
 
-<span class="k">def</span> <span class="nf">random_text_generator</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="n">request_id</span><span class="p">,</span> <span class="n">remote_identity</span><span class="p">,</span> <span class="n">requested_at</span><span class="p">):</span>
-    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Generating response to request &quot;</span><span class="o">+</span><span class="n">RNS</span><span class="o">.</span><span class="n">prettyhexrep</span><span class="p">(</span><span class="n">request_id</span><span class="p">))</span>
+<span class="k">def</span> <span class="nf">random_text_generator</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="n">request_id</span><span class="p">,</span> <span class="n">link_id</span><span class="p">,</span> <span class="n">remote_identity</span><span class="p">,</span> <span class="n">requested_at</span><span class="p">):</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Generating response to request &quot;</span><span class="o">+</span><span class="n">RNS</span><span class="o">.</span><span class="n">prettyhexrep</span><span class="p">(</span><span class="n">request_id</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot; on link &quot;</span><span class="o">+</span><span class="n">RNS</span><span class="o">.</span><span class="n">prettyhexrep</span><span class="p">(</span><span class="n">link_id</span><span class="p">))</span>
     <span class="n">texts</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;They looked up&quot;</span><span class="p">,</span> <span class="s2">&quot;On each full moon&quot;</span><span class="p">,</span> <span class="s2">&quot;Becky was upset&quot;</span><span class="p">,</span> <span class="s2">&quot;I’ll stay away from it&quot;</span><span class="p">,</span> <span class="s2">&quot;The pet shop stocks everything&quot;</span><span class="p">]</span>
     <span class="k">return</span> <span class="n">texts</span><span class="p">[</span><span class="n">random</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">texts</span><span class="p">)</span><span class="o">-</span><span class="mi">1</span><span class="p">)]</span>
 
@@ -1898,6 +1899,735 @@ the link has been established.</p>
 </div>
 <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>
+<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>
+<span class="c1"># This RNS example demonstrates how to set up a link to  #</span>
+<span class="c1"># a destination, and pass structured messages over it    #</span>
+<span class="c1"># using a channel.                                       #</span>
+<span class="c1">##########################################################</span>
+
+<span class="kn">import</span> <span class="nn">os</span>
+<span class="kn">import</span> <span class="nn">sys</span>
+<span class="kn">import</span> <span class="nn">time</span>
+<span class="kn">import</span> <span class="nn">argparse</span>
+<span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span>
+
+<span class="kn">import</span> <span class="nn">RNS</span>
+<span class="kn">from</span> <span class="nn">RNS.vendor</span> <span class="kn">import</span> <span class="n">umsgpack</span>
+
+<span class="c1"># Let&#39;s define an app name. We&#39;ll use this for all</span>
+<span class="c1"># destinations we create. Since this echo example</span>
+<span class="c1"># is part of a range of example utilities, we&#39;ll put</span>
+<span class="c1"># them all within the app namespace &quot;example_utilities&quot;</span>
+<span class="n">APP_NAME</span> <span class="o">=</span> <span class="s2">&quot;example_utilities&quot;</span>
+
+<span class="c1">##########################################################</span>
+<span class="c1">#### Shared Objects ######################################</span>
+<span class="c1">##########################################################</span>
+
+<span class="c1"># Channel data must be structured in a subclass of</span>
+<span class="c1"># MessageBase. This ensures that the channel will be able</span>
+<span class="c1"># to serialize and deserialize the object and multiplex it</span>
+<span class="c1"># with other objects. Both ends of a link will need the</span>
+<span class="c1"># same object definitions to be able to communicate over</span>
+<span class="c1"># a channel.</span>
+<span class="c1">#</span>
+<span class="c1"># Note: The objects we wish to use over the channel must</span>
+<span class="c1"># be registered with the channel, and each link has a</span>
+<span class="c1"># different channel instance. See the client_connected</span>
+<span class="c1"># and link_established functions in this example to see</span>
+<span class="c1"># how message types are registered.</span>
+
+<span class="c1"># Let&#39;s make a simple message class called StringMessage</span>
+<span class="c1"># that will convey a string with a timestamp.</span>
+
+<span class="k">class</span> <span class="nc">StringMessage</span><span class="p">(</span><span class="n">RNS</span><span class="o">.</span><span class="n">MessageBase</span><span class="p">):</span>
+    <span class="c1"># The MSGTYPE class variable needs to be assigned a</span>
+    <span class="c1"># 2 byte integer value. This identifier allows the</span>
+    <span class="c1"># channel to look up your message&#39;s constructor when a</span>
+    <span class="c1"># message arrives over the channel.</span>
+    <span class="c1">#</span>
+    <span class="c1"># MSGTYPE must be unique across all message types we</span>
+    <span class="c1"># register with the channel. MSGTYPEs &gt;= 0xf000 are</span>
+    <span class="c1"># reserved for the system.</span>
+    <span class="n">MSGTYPE</span> <span class="o">=</span> <span class="mh">0x0101</span>
+
+    <span class="c1"># The constructor of our object must be callable with</span>
+    <span class="c1"># no arguments. We can have parameters, but they must</span>
+    <span class="c1"># have a default assignment.</span>
+    <span class="c1">#</span>
+    <span class="c1"># This is needed so the channel can create an empty</span>
+    <span class="c1"># version of our message into which the incoming</span>
+    <span class="c1"># message can be unpacked.</span>
+    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">data</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">timestamp</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>
+
+    <span class="c1"># Finally, our message needs to implement functions</span>
+    <span class="c1"># the channel can call to pack and unpack our message</span>
+    <span class="c1"># to/from the raw packet payload. We&#39;ll use the</span>
+    <span class="c1"># umsgpack package bundled with RNS. We could also use</span>
+    <span class="c1"># the struct package bundled with Python if we wanted</span>
+    <span class="c1"># more control over the structure of the packed bytes.</span>
+    <span class="c1">#</span>
+    <span class="c1"># Also note that packed message objects must fit</span>
+    <span class="c1"># entirely in one packet. The number of bytes</span>
+    <span class="c1"># available for message payloads can be queried from</span>
+    <span class="c1"># the channel using the Channel.MDU property. The</span>
+    <span class="c1"># channel MDU is slightly less than the link MDU due</span>
+    <span class="c1"># to encoding the message header.</span>
+
+    <span class="c1"># The pack function encodes the message contents into</span>
+    <span class="c1"># a byte stream.</span>
+    <span class="k">def</span> <span class="nf">pack</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bytes</span><span class="p">:</span>
+        <span class="k">return</span> <span class="n">umsgpack</span><span class="o">.</span><span class="n">packb</span><span class="p">((</span><span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">timestamp</span><span class="p">))</span>
+
+    <span class="c1"># And the unpack function decodes a byte stream into</span>
+    <span class="c1"># the message contents.</span>
+    <span class="k">def</span> <span class="nf">unpack</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">raw</span><span class="p">):</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">data</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">timestamp</span> <span class="o">=</span> <span class="n">umsgpack</span><span class="o">.</span><span class="n">unpackb</span><span class="p">(</span><span class="n">raw</span><span class="p">)</span>
+
+
+<span class="c1">##########################################################</span>
+<span class="c1">#### Server Part #########################################</span>
+<span class="c1">##########################################################</span>
+
+<span class="c1"># A reference to the latest client link that connected</span>
+<span class="n">latest_client_link</span> <span class="o">=</span> <span class="kc">None</span>
+
+<span class="c1"># This initialisation is executed when the users chooses</span>
+<span class="c1"># to run as a server</span>
+<span class="k">def</span> <span class="nf">server</span><span class="p">(</span><span class="n">configpath</span><span class="p">):</span>
+    <span class="c1"># We must first initialise Reticulum</span>
+    <span class="n">reticulum</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="p">(</span><span class="n">configpath</span><span class="p">)</span>
+    
+    <span class="c1"># Randomly create a new identity for our link example</span>
+    <span class="n">server_identity</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="p">()</span>
+
+    <span class="c1"># We create a destination that clients can connect to. We</span>
+    <span class="c1"># want clients to create links to this destination, so we</span>
+    <span class="c1"># need to create a &quot;single&quot; destination type.</span>
+    <span class="n">server_destination</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="p">(</span>
+        <span class="n">server_identity</span><span class="p">,</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">IN</span><span class="p">,</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">SINGLE</span><span class="p">,</span>
+        <span class="n">APP_NAME</span><span class="p">,</span>
+        <span class="s2">&quot;channelexample&quot;</span>
+    <span class="p">)</span>
+
+    <span class="c1"># We configure a function that will get called every time</span>
+    <span class="c1"># a new client creates a link to this destination.</span>
+    <span class="n">server_destination</span><span class="o">.</span><span class="n">set_link_established_callback</span><span class="p">(</span><span class="n">client_connected</span><span class="p">)</span>
+
+    <span class="c1"># Everything&#39;s ready!</span>
+    <span class="c1"># Let&#39;s Wait for client requests or user input</span>
+    <span class="n">server_loop</span><span class="p">(</span><span class="n">server_destination</span><span class="p">)</span>
+
+<span class="k">def</span> <span class="nf">server_loop</span><span class="p">(</span><span class="n">destination</span><span class="p">):</span>
+    <span class="c1"># Let the user know that everything is ready</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span>
+        <span class="s2">&quot;Link example &quot;</span><span class="o">+</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">prettyhexrep</span><span class="p">(</span><span class="n">destination</span><span class="o">.</span><span class="n">hash</span><span class="p">)</span><span class="o">+</span>
+        <span class="s2">&quot; running, waiting for a connection.&quot;</span>
+    <span class="p">)</span>
+
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Hit enter to manually send an announce (Ctrl-C to quit)&quot;</span><span class="p">)</span>
+
+    <span class="c1"># We enter a loop that runs until the users exits.</span>
+    <span class="c1"># If the user hits enter, we will announce our server</span>
+    <span class="c1"># destination on the network, which will let clients</span>
+    <span class="c1"># know how to create messages directed towards it.</span>
+    <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
+        <span class="n">entered</span> <span class="o">=</span> <span class="nb">input</span><span class="p">()</span>
+        <span class="n">destination</span><span class="o">.</span><span class="n">announce</span><span class="p">()</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Sent announce from &quot;</span><span class="o">+</span><span class="n">RNS</span><span class="o">.</span><span class="n">prettyhexrep</span><span class="p">(</span><span class="n">destination</span><span class="o">.</span><span class="n">hash</span><span class="p">))</span>
+
+<span class="c1"># When a client establishes a link to our server</span>
+<span class="c1"># destination, this function will be called with</span>
+<span class="c1"># a reference to the link.</span>
+<span class="k">def</span> <span class="nf">client_connected</span><span class="p">(</span><span class="n">link</span><span class="p">):</span>
+    <span class="k">global</span> <span class="n">latest_client_link</span>
+    <span class="n">latest_client_link</span> <span class="o">=</span> <span class="n">link</span>
+
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Client connected&quot;</span><span class="p">)</span>
+    <span class="n">link</span><span class="o">.</span><span class="n">set_link_closed_callback</span><span class="p">(</span><span class="n">client_disconnected</span><span class="p">)</span>
+
+    <span class="c1"># Register message types and add callback to channel</span>
+    <span class="n">channel</span> <span class="o">=</span> <span class="n">link</span><span class="o">.</span><span class="n">get_channel</span><span class="p">()</span>
+    <span class="n">channel</span><span class="o">.</span><span class="n">register_message_type</span><span class="p">(</span><span class="n">StringMessage</span><span class="p">)</span>
+    <span class="n">channel</span><span class="o">.</span><span class="n">add_message_handler</span><span class="p">(</span><span class="n">server_message_received</span><span class="p">)</span>
+
+<span class="k">def</span> <span class="nf">client_disconnected</span><span class="p">(</span><span class="n">link</span><span class="p">):</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Client disconnected&quot;</span><span class="p">)</span>
+
+<span class="k">def</span> <span class="nf">server_message_received</span><span class="p">(</span><span class="n">message</span><span class="p">):</span>
+    <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    A message handler</span>
+<span class="sd">    @param message: An instance of a subclass of MessageBase</span>
+<span class="sd">    @return: True if message was handled</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">global</span> <span class="n">latest_client_link</span>
+    <span class="c1"># When a message is received over any active link,</span>
+    <span class="c1"># the replies will all be directed to the last client</span>
+    <span class="c1"># that connected.</span>
+
+    <span class="c1"># In a message handler, any deserializable message</span>
+    <span class="c1"># that arrives over the link&#39;s channel will be passed</span>
+    <span class="c1"># to all message handlers, unless a preceding handler indicates it</span>
+    <span class="c1"># has handled the message.</span>
+    <span class="c1">#</span>
+    <span class="c1">#</span>
+    <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">StringMessage</span><span class="p">):</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Received data on the link: &quot;</span> <span class="o">+</span> <span class="n">message</span><span class="o">.</span><span class="n">data</span> <span class="o">+</span> <span class="s2">&quot; (message created at &quot;</span> <span class="o">+</span> <span class="nb">str</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">timestamp</span><span class="p">)</span> <span class="o">+</span> <span class="s2">&quot;)&quot;</span><span class="p">)</span>
+
+        <span class="n">reply_message</span> <span class="o">=</span> <span class="n">StringMessage</span><span class="p">(</span><span class="s2">&quot;I received </span><span class="se">\&quot;</span><span class="s2">&quot;</span><span class="o">+</span><span class="n">message</span><span class="o">.</span><span class="n">data</span><span class="o">+</span><span class="s2">&quot;</span><span class="se">\&quot;</span><span class="s2"> over the link&quot;</span><span class="p">)</span>
+        <span class="n">latest_client_link</span><span class="o">.</span><span class="n">get_channel</span><span class="p">()</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">reply_message</span><span class="p">)</span>
+
+        <span class="c1"># Incoming messages are sent to each message</span>
+        <span class="c1"># handler added to the channel, in the order they</span>
+        <span class="c1"># were added.</span>
+        <span class="c1"># If any message handler returns True, the message</span>
+        <span class="c1"># is considered handled and any subsequent</span>
+        <span class="c1"># handlers are skipped.</span>
+        <span class="k">return</span> <span class="kc">True</span>
+
+
+<span class="c1">##########################################################</span>
+<span class="c1">#### Client Part #########################################</span>
+<span class="c1">##########################################################</span>
+
+<span class="c1"># A reference to the server link</span>
+<span class="n">server_link</span> <span class="o">=</span> <span class="kc">None</span>
+
+<span class="c1"># This initialisation is executed when the users chooses</span>
+<span class="c1"># to run as a client</span>
+<span class="k">def</span> <span class="nf">client</span><span class="p">(</span><span class="n">destination_hexhash</span><span class="p">,</span> <span class="n">configpath</span><span class="p">):</span>
+    <span class="c1"># We need a binary representation of the destination</span>
+    <span class="c1"># hash that was entered on the command line</span>
+    <span class="k">try</span><span class="p">:</span>
+        <span class="n">dest_len</span> <span class="o">=</span> <span class="p">(</span><span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">TRUNCATED_HASHLENGTH</span><span class="o">//</span><span class="mi">8</span><span class="p">)</span><span class="o">*</span><span class="mi">2</span>
+        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">destination_hexhash</span><span class="p">)</span> <span class="o">!=</span> <span class="n">dest_len</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
+                <span class="s2">&quot;Destination length is invalid, must be </span><span class="si">{hex}</span><span class="s2"> hexadecimal characters (</span><span class="si">{byte}</span><span class="s2"> bytes).&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="nb">hex</span><span class="o">=</span><span class="n">dest_len</span><span class="p">,</span> <span class="n">byte</span><span class="o">=</span><span class="n">dest_len</span><span class="o">//</span><span class="mi">2</span><span class="p">)</span>
+            <span class="p">)</span>
+            
+        <span class="n">destination_hash</span> <span class="o">=</span> <span class="nb">bytes</span><span class="o">.</span><span class="n">fromhex</span><span class="p">(</span><span class="n">destination_hexhash</span><span class="p">)</span>
+    <span class="k">except</span><span class="p">:</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Invalid destination entered. Check your input!</span><span class="se">\n</span><span class="s2">&quot;</span><span class="p">)</span>
+        <span class="n">exit</span><span class="p">()</span>
+
+    <span class="c1"># We must first initialise Reticulum</span>
+    <span class="n">reticulum</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="p">(</span><span class="n">configpath</span><span class="p">)</span>
+
+    <span class="c1"># Check if we know a path to the destination</span>
+    <span class="k">if</span> <span class="ow">not</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Transport</span><span class="o">.</span><span class="n">has_path</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">):</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Destination is not yet known. Requesting path and waiting for announce to arrive...&quot;</span><span class="p">)</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Transport</span><span class="o">.</span><span class="n">request_path</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">)</span>
+        <span class="k">while</span> <span class="ow">not</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Transport</span><span class="o">.</span><span class="n">has_path</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">):</span>
+            <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>
+
+    <span class="c1"># Recall the server identity</span>
+    <span class="n">server_identity</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="o">.</span><span class="n">recall</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">)</span>
+
+    <span class="c1"># Inform the user that we&#39;ll begin connecting</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Establishing link with server...&quot;</span><span class="p">)</span>
+
+    <span class="c1"># When the server identity is known, we set</span>
+    <span class="c1"># up a destination</span>
+    <span class="n">server_destination</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="p">(</span>
+        <span class="n">server_identity</span><span class="p">,</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">OUT</span><span class="p">,</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">SINGLE</span><span class="p">,</span>
+        <span class="n">APP_NAME</span><span class="p">,</span>
+        <span class="s2">&quot;channelexample&quot;</span>
+    <span class="p">)</span>
+
+    <span class="c1"># And create a link</span>
+    <span class="n">link</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Link</span><span class="p">(</span><span class="n">server_destination</span><span class="p">)</span>
+
+    <span class="c1"># We&#39;ll also set up functions to inform the</span>
+    <span class="c1"># user when the link is established or closed</span>
+    <span class="n">link</span><span class="o">.</span><span class="n">set_link_established_callback</span><span class="p">(</span><span class="n">link_established</span><span class="p">)</span>
+    <span class="n">link</span><span class="o">.</span><span class="n">set_link_closed_callback</span><span class="p">(</span><span class="n">link_closed</span><span class="p">)</span>
+
+    <span class="c1"># Everything is set up, so let&#39;s enter a loop</span>
+    <span class="c1"># for the user to interact with the example</span>
+    <span class="n">client_loop</span><span class="p">()</span>
+
+<span class="k">def</span> <span class="nf">client_loop</span><span class="p">():</span>
+    <span class="k">global</span> <span class="n">server_link</span>
+
+    <span class="c1"># Wait for the link to become active</span>
+    <span class="k">while</span> <span class="ow">not</span> <span class="n">server_link</span><span class="p">:</span>
+        <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>
+
+    <span class="n">should_quit</span> <span class="o">=</span> <span class="kc">False</span>
+    <span class="k">while</span> <span class="ow">not</span> <span class="n">should_quit</span><span class="p">:</span>
+        <span class="k">try</span><span class="p">:</span>
+            <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&gt; &quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot; &quot;</span><span class="p">)</span>
+            <span class="n">text</span> <span class="o">=</span> <span class="nb">input</span><span class="p">()</span>
+
+            <span class="c1"># Check if we should quit the example</span>
+            <span class="k">if</span> <span class="n">text</span> <span class="o">==</span> <span class="s2">&quot;quit&quot;</span> <span class="ow">or</span> <span class="n">text</span> <span class="o">==</span> <span class="s2">&quot;q&quot;</span> <span class="ow">or</span> <span class="n">text</span> <span class="o">==</span> <span class="s2">&quot;exit&quot;</span><span class="p">:</span>
+                <span class="n">should_quit</span> <span class="o">=</span> <span class="kc">True</span>
+                <span class="n">server_link</span><span class="o">.</span><span class="n">teardown</span><span class="p">()</span>
+
+            <span class="c1"># If not, send the entered text over the link</span>
+            <span class="k">if</span> <span class="n">text</span> <span class="o">!=</span> <span class="s2">&quot;&quot;</span><span class="p">:</span>
+                <span class="n">message</span> <span class="o">=</span> <span class="n">StringMessage</span><span class="p">(</span><span class="n">text</span><span class="p">)</span>
+                <span class="n">packed_size</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">pack</span><span class="p">())</span>
+                <span class="n">channel</span> <span class="o">=</span> <span class="n">server_link</span><span class="o">.</span><span class="n">get_channel</span><span class="p">()</span>
+                <span class="k">if</span> <span class="n">channel</span><span class="o">.</span><span class="n">is_ready_to_send</span><span class="p">():</span>
+                    <span class="k">if</span> <span class="n">packed_size</span> <span class="o">&lt;=</span> <span class="n">channel</span><span class="o">.</span><span class="n">MDU</span><span class="p">:</span>
+                        <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
+                    <span class="k">else</span><span class="p">:</span>
+                        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span>
+                            <span class="s2">&quot;Cannot send this packet, the data size of &quot;</span><span class="o">+</span>
+                            <span class="nb">str</span><span class="p">(</span><span class="n">packed_size</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot; bytes exceeds the link packet MDU of &quot;</span><span class="o">+</span>
+                            <span class="nb">str</span><span class="p">(</span><span class="n">channel</span><span class="o">.</span><span class="n">MDU</span><span class="p">)</span><span class="o">+</span><span class="s2">&quot; bytes&quot;</span><span class="p">,</span>
+                            <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_ERROR</span>
+                        <span class="p">)</span>
+                <span class="k">else</span><span class="p">:</span>
+                    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Channel is not ready to send, please wait for &quot;</span> <span class="o">+</span>
+                            <span class="s2">&quot;pending messages to complete.&quot;</span><span class="p">,</span> <span class="n">RNS</span><span class="o">.</span><span class="n">LOG_ERROR</span><span class="p">)</span>
+
+        <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+            <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Error while sending data over the link: &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
+            <span class="n">should_quit</span> <span class="o">=</span> <span class="kc">True</span>
+            <span class="n">server_link</span><span class="o">.</span><span class="n">teardown</span><span class="p">()</span>
+
+<span class="c1"># This function is called when a link</span>
+<span class="c1"># has been established with the server</span>
+<span class="k">def</span> <span class="nf">link_established</span><span class="p">(</span><span class="n">link</span><span class="p">):</span>
+    <span class="c1"># We store a reference to the link</span>
+    <span class="c1"># instance for later use</span>
+    <span class="k">global</span> <span class="n">server_link</span>
+    <span class="n">server_link</span> <span class="o">=</span> <span class="n">link</span>
+
+    <span class="c1"># Register messages and add handler to channel</span>
+    <span class="n">channel</span> <span class="o">=</span> <span class="n">link</span><span class="o">.</span><span class="n">get_channel</span><span class="p">()</span>
+    <span class="n">channel</span><span class="o">.</span><span class="n">register_message_type</span><span class="p">(</span><span class="n">StringMessage</span><span class="p">)</span>
+    <span class="n">channel</span><span class="o">.</span><span class="n">add_message_handler</span><span class="p">(</span><span class="n">client_message_received</span><span class="p">)</span>
+
+    <span class="c1"># Inform the user that the server is</span>
+    <span class="c1"># connected</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Link established with server, enter some text to send, or </span><span class="se">\&quot;</span><span class="s2">quit</span><span class="se">\&quot;</span><span class="s2"> to quit&quot;</span><span class="p">)</span>
+
+<span class="c1"># When a link is closed, we&#39;ll inform the</span>
+<span class="c1"># user, and exit the program</span>
+<span class="k">def</span> <span class="nf">link_closed</span><span class="p">(</span><span class="n">link</span><span class="p">):</span>
+    <span class="k">if</span> <span class="n">link</span><span class="o">.</span><span class="n">teardown_reason</span> <span class="o">==</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Link</span><span class="o">.</span><span class="n">TIMEOUT</span><span class="p">:</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;The link timed out, exiting now&quot;</span><span class="p">)</span>
+    <span class="k">elif</span> <span class="n">link</span><span class="o">.</span><span class="n">teardown_reason</span> <span class="o">==</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Link</span><span class="o">.</span><span class="n">DESTINATION_CLOSED</span><span class="p">:</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;The link was closed by the server, exiting now&quot;</span><span class="p">)</span>
+    <span class="k">else</span><span class="p">:</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Link closed, exiting now&quot;</span><span class="p">)</span>
+    
+    <span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">exit_handler</span><span class="p">()</span>
+    <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">1.5</span><span class="p">)</span>
+    <span class="n">os</span><span class="o">.</span><span class="n">_exit</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
+
+<span class="c1"># When a packet is received over the channel, we</span>
+<span class="c1"># simply print out the data.</span>
+<span class="k">def</span> <span class="nf">client_message_received</span><span class="p">(</span><span class="n">message</span><span class="p">):</span>
+    <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">StringMessage</span><span class="p">):</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Received data on the link: &quot;</span> <span class="o">+</span> <span class="n">message</span><span class="o">.</span><span class="n">data</span> <span class="o">+</span> <span class="s2">&quot; (message created at &quot;</span> <span class="o">+</span> <span class="nb">str</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">timestamp</span><span class="p">)</span> <span class="o">+</span> <span class="s2">&quot;)&quot;</span><span class="p">)</span>
+        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&gt; &quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot; &quot;</span><span class="p">)</span>
+        <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
+
+
+<span class="c1">##########################################################</span>
+<span class="c1">#### Program Startup #####################################</span>
+<span class="c1">##########################################################</span>
+
+<span class="c1"># This part of the program runs at startup,</span>
+<span class="c1"># and parses input of from the user, and then</span>
+<span class="c1"># starts up the desired program mode.</span>
+<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">&quot;__main__&quot;</span><span class="p">:</span>
+    <span class="k">try</span><span class="p">:</span>
+        <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">description</span><span class="o">=</span><span class="s2">&quot;Simple channel example&quot;</span><span class="p">)</span>
+
+        <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>
+            <span class="s2">&quot;-s&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;--server&quot;</span><span class="p">,</span>
+            <span class="n">action</span><span class="o">=</span><span class="s2">&quot;store_true&quot;</span><span class="p">,</span>
+            <span class="n">help</span><span class="o">=</span><span class="s2">&quot;wait for incoming link requests from clients&quot;</span>
+        <span class="p">)</span>
+
+        <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>
+            <span class="s2">&quot;--config&quot;</span><span class="p">,</span>
+            <span class="n">action</span><span class="o">=</span><span class="s2">&quot;store&quot;</span><span class="p">,</span>
+            <span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
+            <span class="n">help</span><span class="o">=</span><span class="s2">&quot;path to alternative Reticulum config directory&quot;</span><span class="p">,</span>
+            <span class="nb">type</span><span class="o">=</span><span class="nb">str</span>
+        <span class="p">)</span>
+
+        <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>
+            <span class="s2">&quot;destination&quot;</span><span class="p">,</span>
+            <span class="n">nargs</span><span class="o">=</span><span class="s2">&quot;?&quot;</span><span class="p">,</span>
+            <span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
+            <span class="n">help</span><span class="o">=</span><span class="s2">&quot;hexadecimal hash of the server destination&quot;</span><span class="p">,</span>
+            <span class="nb">type</span><span class="o">=</span><span class="nb">str</span>
+        <span class="p">)</span>
+
+        <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
+
+        <span class="k">if</span> <span class="n">args</span><span class="o">.</span><span class="n">config</span><span class="p">:</span>
+            <span class="n">configarg</span> <span class="o">=</span> <span class="n">args</span><span class="o">.</span><span class="n">config</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">configarg</span> <span class="o">=</span> <span class="kc">None</span>
+
+        <span class="k">if</span> <span class="n">args</span><span class="o">.</span><span class="n">server</span><span class="p">:</span>
+            <span class="n">server</span><span class="p">(</span><span class="n">configarg</span><span class="p">)</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="k">if</span> <span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">destination</span> <span class="o">==</span> <span class="kc">None</span><span class="p">):</span>
+                <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
+                <span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
+                <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">client</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">destination</span><span class="p">,</span> <span class="n">configarg</span><span class="p">)</span>
+
+    <span class="k">except</span> <span class="ne">KeyboardInterrupt</span><span class="p">:</span>
+        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
+        <span class="n">exit</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/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>
+<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>
+<span class="c1"># This RNS example demonstrates how to set up a link to  #</span>
+<span class="c1"># a destination, and pass binary data over it using a    #</span>
+<span class="c1"># channel buffer.                                        #</span>
+<span class="c1">##########################################################</span>
+<span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">annotations</span>
+<span class="kn">import</span> <span class="nn">os</span>
+<span class="kn">import</span> <span class="nn">sys</span>
+<span class="kn">import</span> <span class="nn">time</span>
+<span class="kn">import</span> <span class="nn">argparse</span>
+<span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span>
+
+<span class="kn">import</span> <span class="nn">RNS</span>
+<span class="kn">from</span> <span class="nn">RNS.vendor</span> <span class="kn">import</span> <span class="n">umsgpack</span>
+
+<span class="c1"># Let&#39;s define an app name. We&#39;ll use this for all</span>
+<span class="c1"># destinations we create. Since this echo example</span>
+<span class="c1"># is part of a range of example utilities, we&#39;ll put</span>
+<span class="c1"># them all within the app namespace &quot;example_utilities&quot;</span>
+<span class="n">APP_NAME</span> <span class="o">=</span> <span class="s2">&quot;example_utilities&quot;</span>
+
+
+<span class="c1">##########################################################</span>
+<span class="c1">#### Server Part #########################################</span>
+<span class="c1">##########################################################</span>
+
+<span class="c1"># A reference to the latest client link that connected</span>
+<span class="n">latest_client_link</span> <span class="o">=</span> <span class="kc">None</span>
+
+<span class="c1"># A reference to the latest buffer object</span>
+<span class="n">latest_buffer</span> <span class="o">=</span> <span class="kc">None</span>
+
+<span class="c1"># This initialisation is executed when the users chooses</span>
+<span class="c1"># to run as a server</span>
+<span class="k">def</span> <span class="nf">server</span><span class="p">(</span><span class="n">configpath</span><span class="p">):</span>
+    <span class="c1"># We must first initialise Reticulum</span>
+    <span class="n">reticulum</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="p">(</span><span class="n">configpath</span><span class="p">)</span>
+    
+    <span class="c1"># Randomly create a new identity for our example</span>
+    <span class="n">server_identity</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="p">()</span>
+
+    <span class="c1"># We create a destination that clients can connect to. We</span>
+    <span class="c1"># want clients to create links to this destination, so we</span>
+    <span class="c1"># need to create a &quot;single&quot; destination type.</span>
+    <span class="n">server_destination</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="p">(</span>
+        <span class="n">server_identity</span><span class="p">,</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">IN</span><span class="p">,</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">SINGLE</span><span class="p">,</span>
+        <span class="n">APP_NAME</span><span class="p">,</span>
+        <span class="s2">&quot;bufferexample&quot;</span>
+    <span class="p">)</span>
+
+    <span class="c1"># We configure a function that will get called every time</span>
+    <span class="c1"># a new client creates a link to this destination.</span>
+    <span class="n">server_destination</span><span class="o">.</span><span class="n">set_link_established_callback</span><span class="p">(</span><span class="n">client_connected</span><span class="p">)</span>
+
+    <span class="c1"># Everything&#39;s ready!</span>
+    <span class="c1"># Let&#39;s Wait for client requests or user input</span>
+    <span class="n">server_loop</span><span class="p">(</span><span class="n">server_destination</span><span class="p">)</span>
+
+<span class="k">def</span> <span class="nf">server_loop</span><span class="p">(</span><span class="n">destination</span><span class="p">):</span>
+    <span class="c1"># Let the user know that everything is ready</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span>
+        <span class="s2">&quot;Link buffer example &quot;</span><span class="o">+</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">prettyhexrep</span><span class="p">(</span><span class="n">destination</span><span class="o">.</span><span class="n">hash</span><span class="p">)</span><span class="o">+</span>
+        <span class="s2">&quot; running, waiting for a connection.&quot;</span>
+    <span class="p">)</span>
+
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Hit enter to manually send an announce (Ctrl-C to quit)&quot;</span><span class="p">)</span>
+
+    <span class="c1"># We enter a loop that runs until the users exits.</span>
+    <span class="c1"># If the user hits enter, we will announce our server</span>
+    <span class="c1"># destination on the network, which will let clients</span>
+    <span class="c1"># know how to create messages directed towards it.</span>
+    <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
+        <span class="n">entered</span> <span class="o">=</span> <span class="nb">input</span><span class="p">()</span>
+        <span class="n">destination</span><span class="o">.</span><span class="n">announce</span><span class="p">()</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Sent announce from &quot;</span><span class="o">+</span><span class="n">RNS</span><span class="o">.</span><span class="n">prettyhexrep</span><span class="p">(</span><span class="n">destination</span><span class="o">.</span><span class="n">hash</span><span class="p">))</span>
+
+<span class="c1"># When a client establishes a link to our server</span>
+<span class="c1"># destination, this function will be called with</span>
+<span class="c1"># a reference to the link.</span>
+<span class="k">def</span> <span class="nf">client_connected</span><span class="p">(</span><span class="n">link</span><span class="p">):</span>
+    <span class="k">global</span> <span class="n">latest_client_link</span><span class="p">,</span> <span class="n">latest_buffer</span>
+    <span class="n">latest_client_link</span> <span class="o">=</span> <span class="n">link</span>
+
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Client connected&quot;</span><span class="p">)</span>
+    <span class="n">link</span><span class="o">.</span><span class="n">set_link_closed_callback</span><span class="p">(</span><span class="n">client_disconnected</span><span class="p">)</span>
+
+    <span class="c1"># If a new connection is received, the old reader</span>
+    <span class="c1"># needs to be disconnected.</span>
+    <span class="k">if</span> <span class="n">latest_buffer</span><span class="p">:</span>
+        <span class="n">latest_buffer</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
+
+
+    <span class="c1"># Create buffer objects.</span>
+    <span class="c1">#   The stream_id parameter to these functions is</span>
+    <span class="c1">#   a bit like a file descriptor, except that it</span>
+    <span class="c1">#   is unique to the *receiver*.</span>
+    <span class="c1">#</span>
+    <span class="c1">#   In this example, both the reader and the writer</span>
+    <span class="c1">#   use stream_id = 0, but there are actually two</span>
+    <span class="c1">#   separate unidirectional streams flowing in</span>
+    <span class="c1">#   opposite directions.</span>
+    <span class="c1">#</span>
+    <span class="n">channel</span> <span class="o">=</span> <span class="n">link</span><span class="o">.</span><span class="n">get_channel</span><span class="p">()</span>
+    <span class="n">latest_buffer</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Buffer</span><span class="o">.</span><span class="n">create_bidirectional_buffer</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">channel</span><span class="p">,</span> <span class="n">server_buffer_ready</span><span class="p">)</span>
+
+<span class="k">def</span> <span class="nf">client_disconnected</span><span class="p">(</span><span class="n">link</span><span class="p">):</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Client disconnected&quot;</span><span class="p">)</span>
+
+<span class="k">def</span> <span class="nf">server_buffer_ready</span><span class="p">(</span><span class="n">ready_bytes</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>
+    <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    Callback from buffer when buffer has data available</span>
+
+<span class="sd">    :param ready_bytes: The number of bytes ready to read</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">global</span> <span class="n">latest_buffer</span>
+
+    <span class="n">data</span> <span class="o">=</span> <span class="n">latest_buffer</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">ready_bytes</span><span class="p">)</span>
+    <span class="n">data</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;utf-8&quot;</span><span class="p">)</span>
+
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Received data over the buffer: &quot;</span> <span class="o">+</span> <span class="n">data</span><span class="p">)</span>
+
+    <span class="n">reply_message</span> <span class="o">=</span> <span class="s2">&quot;I received </span><span class="se">\&quot;</span><span class="s2">&quot;</span><span class="o">+</span><span class="n">data</span><span class="o">+</span><span class="s2">&quot;</span><span class="se">\&quot;</span><span class="s2"> over the buffer&quot;</span>
+    <span class="n">reply_message</span> <span class="o">=</span> <span class="n">reply_message</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;utf-8&quot;</span><span class="p">)</span>
+    <span class="n">latest_buffer</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">reply_message</span><span class="p">)</span>
+    <span class="n">latest_buffer</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
+
+
+
+
+<span class="c1">##########################################################</span>
+<span class="c1">#### Client Part #########################################</span>
+<span class="c1">##########################################################</span>
+
+<span class="c1"># A reference to the server link</span>
+<span class="n">server_link</span> <span class="o">=</span> <span class="kc">None</span>
+
+<span class="c1"># A reference to the buffer object, needed to share the</span>
+<span class="c1"># object from the link connected callback to the client</span>
+<span class="c1"># loop.</span>
+<span class="n">buffer</span> <span class="o">=</span> <span class="kc">None</span>
+
+<span class="c1"># This initialisation is executed when the users chooses</span>
+<span class="c1"># to run as a client</span>
+<span class="k">def</span> <span class="nf">client</span><span class="p">(</span><span class="n">destination_hexhash</span><span class="p">,</span> <span class="n">configpath</span><span class="p">):</span>
+    <span class="c1"># We need a binary representation of the destination</span>
+    <span class="c1"># hash that was entered on the command line</span>
+    <span class="k">try</span><span class="p">:</span>
+        <span class="n">dest_len</span> <span class="o">=</span> <span class="p">(</span><span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">TRUNCATED_HASHLENGTH</span><span class="o">//</span><span class="mi">8</span><span class="p">)</span><span class="o">*</span><span class="mi">2</span>
+        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">destination_hexhash</span><span class="p">)</span> <span class="o">!=</span> <span class="n">dest_len</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
+                <span class="s2">&quot;Destination length is invalid, must be </span><span class="si">{hex}</span><span class="s2"> hexadecimal characters (</span><span class="si">{byte}</span><span class="s2"> bytes).&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="nb">hex</span><span class="o">=</span><span class="n">dest_len</span><span class="p">,</span> <span class="n">byte</span><span class="o">=</span><span class="n">dest_len</span><span class="o">//</span><span class="mi">2</span><span class="p">)</span>
+            <span class="p">)</span>
+            
+        <span class="n">destination_hash</span> <span class="o">=</span> <span class="nb">bytes</span><span class="o">.</span><span class="n">fromhex</span><span class="p">(</span><span class="n">destination_hexhash</span><span class="p">)</span>
+    <span class="k">except</span><span class="p">:</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Invalid destination entered. Check your input!</span><span class="se">\n</span><span class="s2">&quot;</span><span class="p">)</span>
+        <span class="n">exit</span><span class="p">()</span>
+
+    <span class="c1"># We must first initialise Reticulum</span>
+    <span class="n">reticulum</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="p">(</span><span class="n">configpath</span><span class="p">)</span>
+
+    <span class="c1"># Check if we know a path to the destination</span>
+    <span class="k">if</span> <span class="ow">not</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Transport</span><span class="o">.</span><span class="n">has_path</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">):</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Destination is not yet known. Requesting path and waiting for announce to arrive...&quot;</span><span class="p">)</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Transport</span><span class="o">.</span><span class="n">request_path</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">)</span>
+        <span class="k">while</span> <span class="ow">not</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Transport</span><span class="o">.</span><span class="n">has_path</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">):</span>
+            <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>
+
+    <span class="c1"># Recall the server identity</span>
+    <span class="n">server_identity</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Identity</span><span class="o">.</span><span class="n">recall</span><span class="p">(</span><span class="n">destination_hash</span><span class="p">)</span>
+
+    <span class="c1"># Inform the user that we&#39;ll begin connecting</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Establishing link with server...&quot;</span><span class="p">)</span>
+
+    <span class="c1"># When the server identity is known, we set</span>
+    <span class="c1"># up a destination</span>
+    <span class="n">server_destination</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="p">(</span>
+        <span class="n">server_identity</span><span class="p">,</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">OUT</span><span class="p">,</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">Destination</span><span class="o">.</span><span class="n">SINGLE</span><span class="p">,</span>
+        <span class="n">APP_NAME</span><span class="p">,</span>
+        <span class="s2">&quot;bufferexample&quot;</span>
+    <span class="p">)</span>
+
+    <span class="c1"># And create a link</span>
+    <span class="n">link</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Link</span><span class="p">(</span><span class="n">server_destination</span><span class="p">)</span>
+
+    <span class="c1"># We&#39;ll also set up functions to inform the</span>
+    <span class="c1"># user when the link is established or closed</span>
+    <span class="n">link</span><span class="o">.</span><span class="n">set_link_established_callback</span><span class="p">(</span><span class="n">link_established</span><span class="p">)</span>
+    <span class="n">link</span><span class="o">.</span><span class="n">set_link_closed_callback</span><span class="p">(</span><span class="n">link_closed</span><span class="p">)</span>
+
+    <span class="c1"># Everything is set up, so let&#39;s enter a loop</span>
+    <span class="c1"># for the user to interact with the example</span>
+    <span class="n">client_loop</span><span class="p">()</span>
+
+<span class="k">def</span> <span class="nf">client_loop</span><span class="p">():</span>
+    <span class="k">global</span> <span class="n">server_link</span>
+
+    <span class="c1"># Wait for the link to become active</span>
+    <span class="k">while</span> <span class="ow">not</span> <span class="n">server_link</span><span class="p">:</span>
+        <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span>
+
+    <span class="n">should_quit</span> <span class="o">=</span> <span class="kc">False</span>
+    <span class="k">while</span> <span class="ow">not</span> <span class="n">should_quit</span><span class="p">:</span>
+        <span class="k">try</span><span class="p">:</span>
+            <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&gt; &quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot; &quot;</span><span class="p">)</span>
+            <span class="n">text</span> <span class="o">=</span> <span class="nb">input</span><span class="p">()</span>
+
+            <span class="c1"># Check if we should quit the example</span>
+            <span class="k">if</span> <span class="n">text</span> <span class="o">==</span> <span class="s2">&quot;quit&quot;</span> <span class="ow">or</span> <span class="n">text</span> <span class="o">==</span> <span class="s2">&quot;q&quot;</span> <span class="ow">or</span> <span class="n">text</span> <span class="o">==</span> <span class="s2">&quot;exit&quot;</span><span class="p">:</span>
+                <span class="n">should_quit</span> <span class="o">=</span> <span class="kc">True</span>
+                <span class="n">server_link</span><span class="o">.</span><span class="n">teardown</span><span class="p">()</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="c1"># Otherwise, encode the text and write it to the buffer.</span>
+                <span class="n">text</span> <span class="o">=</span> <span class="n">text</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s2">&quot;utf-8&quot;</span><span class="p">)</span>
+                <span class="n">buffer</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">text</span><span class="p">)</span>
+                <span class="c1"># Flush the buffer to force the data to be sent.</span>
+                <span class="n">buffer</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
+
+
+        <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+            <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Error while sending data over the link buffer: &quot;</span><span class="o">+</span><span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
+            <span class="n">should_quit</span> <span class="o">=</span> <span class="kc">True</span>
+            <span class="n">server_link</span><span class="o">.</span><span class="n">teardown</span><span class="p">()</span>
+
+<span class="c1"># This function is called when a link</span>
+<span class="c1"># has been established with the server</span>
+<span class="k">def</span> <span class="nf">link_established</span><span class="p">(</span><span class="n">link</span><span class="p">):</span>
+    <span class="c1"># We store a reference to the link</span>
+    <span class="c1"># instance for later use</span>
+    <span class="k">global</span> <span class="n">server_link</span><span class="p">,</span> <span class="n">buffer</span>
+    <span class="n">server_link</span> <span class="o">=</span> <span class="n">link</span>
+
+    <span class="c1"># Create buffer, see server_client_connected() for</span>
+    <span class="c1"># more detail about setting up the buffer.</span>
+    <span class="n">channel</span> <span class="o">=</span> <span class="n">link</span><span class="o">.</span><span class="n">get_channel</span><span class="p">()</span>
+    <span class="n">buffer</span> <span class="o">=</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Buffer</span><span class="o">.</span><span class="n">create_bidirectional_buffer</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">channel</span><span class="p">,</span> <span class="n">client_buffer_ready</span><span class="p">)</span>
+
+    <span class="c1"># Inform the user that the server is</span>
+    <span class="c1"># connected</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Link established with server, enter some text to send, or </span><span class="se">\&quot;</span><span class="s2">quit</span><span class="se">\&quot;</span><span class="s2"> to quit&quot;</span><span class="p">)</span>
+
+<span class="c1"># When a link is closed, we&#39;ll inform the</span>
+<span class="c1"># user, and exit the program</span>
+<span class="k">def</span> <span class="nf">link_closed</span><span class="p">(</span><span class="n">link</span><span class="p">):</span>
+    <span class="k">if</span> <span class="n">link</span><span class="o">.</span><span class="n">teardown_reason</span> <span class="o">==</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Link</span><span class="o">.</span><span class="n">TIMEOUT</span><span class="p">:</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;The link timed out, exiting now&quot;</span><span class="p">)</span>
+    <span class="k">elif</span> <span class="n">link</span><span class="o">.</span><span class="n">teardown_reason</span> <span class="o">==</span> <span class="n">RNS</span><span class="o">.</span><span class="n">Link</span><span class="o">.</span><span class="n">DESTINATION_CLOSED</span><span class="p">:</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;The link was closed by the server, exiting now&quot;</span><span class="p">)</span>
+    <span class="k">else</span><span class="p">:</span>
+        <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Link closed, exiting now&quot;</span><span class="p">)</span>
+    
+    <span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">exit_handler</span><span class="p">()</span>
+    <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">1.5</span><span class="p">)</span>
+    <span class="n">os</span><span class="o">.</span><span class="n">_exit</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
+
+<span class="c1"># When the buffer has new data, read it and write it to the terminal.</span>
+<span class="k">def</span> <span class="nf">client_buffer_ready</span><span class="p">(</span><span class="n">ready_bytes</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>
+    <span class="k">global</span> <span class="n">buffer</span>
+    <span class="n">data</span> <span class="o">=</span> <span class="n">buffer</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">ready_bytes</span><span class="p">)</span>
+    <span class="n">RNS</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s2">&quot;Received data over the link buffer: &quot;</span> <span class="o">+</span> <span class="n">data</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s2">&quot;utf-8&quot;</span><span class="p">))</span>
+    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&gt; &quot;</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">&quot; &quot;</span><span class="p">)</span>
+    <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
+
+
+<span class="c1">##########################################################</span>
+<span class="c1">#### Program Startup #####################################</span>
+<span class="c1">##########################################################</span>
+
+<span class="c1"># This part of the program runs at startup,</span>
+<span class="c1"># and parses input of from the user, and then</span>
+<span class="c1"># starts up the desired program mode.</span>
+<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">&quot;__main__&quot;</span><span class="p">:</span>
+    <span class="k">try</span><span class="p">:</span>
+        <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">description</span><span class="o">=</span><span class="s2">&quot;Simple buffer example&quot;</span><span class="p">)</span>
+
+        <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>
+            <span class="s2">&quot;-s&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;--server&quot;</span><span class="p">,</span>
+            <span class="n">action</span><span class="o">=</span><span class="s2">&quot;store_true&quot;</span><span class="p">,</span>
+            <span class="n">help</span><span class="o">=</span><span class="s2">&quot;wait for incoming link requests from clients&quot;</span>
+        <span class="p">)</span>
+
+        <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>
+            <span class="s2">&quot;--config&quot;</span><span class="p">,</span>
+            <span class="n">action</span><span class="o">=</span><span class="s2">&quot;store&quot;</span><span class="p">,</span>
+            <span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
+            <span class="n">help</span><span class="o">=</span><span class="s2">&quot;path to alternative Reticulum config directory&quot;</span><span class="p">,</span>
+            <span class="nb">type</span><span class="o">=</span><span class="nb">str</span>
+        <span class="p">)</span>
+
+        <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>
+            <span class="s2">&quot;destination&quot;</span><span class="p">,</span>
+            <span class="n">nargs</span><span class="o">=</span><span class="s2">&quot;?&quot;</span><span class="p">,</span>
+            <span class="n">default</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
+            <span class="n">help</span><span class="o">=</span><span class="s2">&quot;hexadecimal hash of the server destination&quot;</span><span class="p">,</span>
+            <span class="nb">type</span><span class="o">=</span><span class="nb">str</span>
+        <span class="p">)</span>
+
+        <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
+
+        <span class="k">if</span> <span class="n">args</span><span class="o">.</span><span class="n">config</span><span class="p">:</span>
+            <span class="n">configarg</span> <span class="o">=</span> <span class="n">args</span><span class="o">.</span><span class="n">config</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">configarg</span> <span class="o">=</span> <span class="kc">None</span>
+
+        <span class="k">if</span> <span class="n">args</span><span class="o">.</span><span class="n">server</span><span class="p">:</span>
+            <span class="n">server</span><span class="p">(</span><span class="n">configarg</span><span class="p">)</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="k">if</span> <span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">destination</span> <span class="o">==</span> <span class="kc">None</span><span class="p">):</span>
+                <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
+                <span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
+                <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">client</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">destination</span><span class="p">,</span> <span class="n">configarg</span><span class="p">)</span>
+
+    <span class="k">except</span> <span class="ne">KeyboardInterrupt</span><span class="p">:</span>
+        <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
+        <span class="n">exit</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/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>
 <p>The <em>Filetransfer</em> example implements a basic file-server program that
@@ -2543,7 +3273,7 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>
@@ -2578,6 +3308,8 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
 <li><a class="reference internal" href="#link">Link</a></li>
 <li><a class="reference internal" href="#example-identify">Identification</a></li>
 <li><a class="reference internal" href="#requests-responses">Requests &amp; Responses</a></li>
+<li><a class="reference internal" href="#channel">Channel</a></li>
+<li><a class="reference internal" href="#buffer">Buffer</a></li>
 <li><a class="reference internal" href="#filetransfer">Filetransfer</a></li>
 </ul>
 </li>

docs/manual/forhumans.html

@@ -0,0 +1,270 @@
+<!doctype html>
+<html class="no-js" lang="en">
+  <head><meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width,initial-scale=1"/>
+    <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
+<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" />
+
+    <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
+        <title>An Explanation of Reticulum for Human Beings - Reticulum Network Stack 0.5.0 beta documentation</title>
+      <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
+    <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" />
+    
+    
+
+
+<style>
+  body {
+    --color-code-background: #f8f8f8;
+  --color-code-foreground: black;
+  
+  }
+  @media not print {
+    body[data-theme="dark"] {
+      --color-code-background: #202020;
+  --color-code-foreground: #d0d0d0;
+  --color-background-primary: #202b38;
+  --color-background-secondary: #161f27;
+  --color-foreground-primary: #dbdbdb;
+  --color-foreground-secondary: #a9b1ba;
+  --color-brand-primary: #41adff;
+  --color-background-hover: #161f27;
+  --color-api-name: #ffbe85;
+  --color-api-pre-name: #efae75;
+  
+    }
+    @media (prefers-color-scheme: dark) {
+      body:not([data-theme="light"]) {
+        --color-code-background: #202020;
+  --color-code-foreground: #d0d0d0;
+  --color-background-primary: #202b38;
+  --color-background-secondary: #161f27;
+  --color-foreground-primary: #dbdbdb;
+  --color-foreground-secondary: #a9b1ba;
+  --color-brand-primary: #41adff;
+  --color-background-hover: #161f27;
+  --color-api-name: #ffbe85;
+  --color-api-pre-name: #efae75;
+  
+      }
+    }
+  }
+</style></head>
+  <body>
+    
+    <script>
+      document.body.dataset.theme = localStorage.getItem("theme") || "auto";
+    </script>
+    
+
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+  <symbol id="svg-toc" viewBox="0 0 24 24">
+    <title>Contents</title>
+    <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
+      <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
+    </svg>
+  </symbol>
+  <symbol id="svg-menu" viewBox="0 0 24 24">
+    <title>Menu</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
+      <line x1="3" y1="12" x2="21" y2="12"></line>
+      <line x1="3" y1="6" x2="21" y2="6"></line>
+      <line x1="3" y1="18" x2="21" y2="18"></line>
+    </svg>
+  </symbol>
+  <symbol id="svg-arrow-right" viewBox="0 0 24 24">
+    <title>Expand</title>
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
+      <polyline points="9 18 15 12 9 6"></polyline>
+    </svg>
+  </symbol>
+  <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">
+      <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>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+      <line x1="1" y1="12" x2="3" y2="12"></line>
+      <line x1="21" y1="12" x2="23" y2="12"></line>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+    </svg>
+  </symbol>
+  <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">
+      <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>
+    <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" />
+    </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>
+
+
+
+<div class="page">
+  <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>
+      </label>
+    </div>
+    <div class="header-center">
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta 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>
+          <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>
+      </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-logo-container">
+    <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
+  </div>
+  
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
+  
+</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
+  <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
+  <input type="hidden" name="check_keywords" value="yes">
+  <input type="hidden" name="area" value="default">
+</form>
+<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
+  <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="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">Supported 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>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
+</ul>
+
+</div>
+</div>
+
+      </div>
+      
+    </div>
+  </aside>
+  <div class="main">
+    <div class="content">
+      <div class="article-container">
+        <a href="#" class="back-to-top muted-link">
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+            <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
+          </svg>
+          <span>Back to top</span>
+        </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>
+              <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>
+          </label>
+        </div>
+        <article role="main">
+          <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>
+</section>
+
+        </article>
+      </div>
+      <footer>
+        
+        <div class="related-pages">
+          
+          
+        </div>
+        <div class="bottom-of-page">
+          <div class="left-details">
+            <div class="copyright">
+                Copyright &#169; 2023, 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>
+        
+      </footer>
+    </div>
+    <aside class="toc-drawer no-toc">
+      
+      
+      
+    </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>
+    </body>
+</html>

docs/manual/genindex.html

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="#" /><link rel="search" title="Search" href="search.html" />
 
-    <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/><title>Index - Reticulum Network Stack 0.4.0 beta documentation</title>
+    <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/><title>Index - Reticulum Network Stack 0.5.0 beta documentation</title>
 <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -139,7 +139,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -165,7 +165,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -222,18 +222,36 @@
           
 <section class="genindex-section">
   <h1 id="index">Index</h1>
-  <div class="genindex-jumpbox"><a href="#A"><strong>A</strong></a> | <a href="#C"><strong>C</strong></a> | <a href="#D"><strong>D</strong></a> | <a href="#E"><strong>E</strong></a> | <a href="#F"><strong>F</strong></a> | <a href="#G"><strong>G</strong></a> | <a href="#H"><strong>H</strong></a> | <a href="#I"><strong>I</strong></a> | <a href="#K"><strong>K</strong></a> | <a href="#L"><strong>L</strong></a> | <a href="#M"><strong>M</strong></a> | <a href="#N"><strong>N</strong></a> | <a href="#P"><strong>P</strong></a> | <a href="#R"><strong>R</strong></a> | <a href="#S"><strong>S</strong></a> | <a href="#T"><strong>T</strong></a> | <a href="#V"><strong>V</strong></a></div>
+  <div class="genindex-jumpbox"><a href="#_"><strong>_</strong></a> | <a href="#A"><strong>A</strong></a> | <a href="#B"><strong>B</strong></a> | <a href="#C"><strong>C</strong></a> | <a href="#D"><strong>D</strong></a> | <a href="#E"><strong>E</strong></a> | <a href="#F"><strong>F</strong></a> | <a href="#G"><strong>G</strong></a> | <a href="#H"><strong>H</strong></a> | <a href="#I"><strong>I</strong></a> | <a href="#K"><strong>K</strong></a> | <a href="#L"><strong>L</strong></a> | <a href="#M"><strong>M</strong></a> | <a href="#N"><strong>N</strong></a> | <a href="#P"><strong>P</strong></a> | <a href="#R"><strong>R</strong></a> | <a href="#S"><strong>S</strong></a> | <a href="#T"><strong>T</strong></a> | <a href="#U"><strong>U</strong></a> | <a href="#V"><strong>V</strong></a></div>
 </section>
+<section id="_" class="genindex-section">
+  <h2>_</h2>
+  <table style="width: 100%" class="indextable genindextable"><tr>
+    <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.RawChannelReader.__init__">__init__() (RNS.RawChannelReader method)</a>
+
+        <ul>
+          <li><a href="reference.html#RNS.RawChannelWriter.__init__">(RNS.RawChannelWriter method)</a>
+</li>
+        </ul></li>
+    </ul></td>
+  </tr></table>
+</section>
+
 <section id="A" class="genindex-section">
   <h2>A</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
     <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.Destination.accepts_links">accepts_links() (RNS.Destination method)</a>
 </li>
-        <li><a href="reference.html#RNS.Resource.advertise">advertise() (RNS.Resource method)</a>
+        <li><a href="reference.html#RNS.Channel.Channel.add_message_handler">add_message_handler() (RNS.Channel.Channel method)</a>
+</li>
+        <li><a href="reference.html#RNS.RawChannelReader.add_ready_callback">add_ready_callback() (RNS.RawChannelReader method)</a>
 </li>
     </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.Resource.advertise">advertise() (RNS.Resource method)</a>
+</li>
         <li><a href="reference.html#RNS.Destination.announce">announce() (RNS.Destination method)</a>
 </li>
         <li><a href="reference.html#RNS.Reticulum.ANNOUNCE_CAP">ANNOUNCE_CAP (RNS.Reticulum attribute)</a>
@@ -244,17 +262,35 @@
   </tr></table>
 </section>
 
+<section id="B" class="genindex-section">
+  <h2>B</h2>
+  <table style="width: 100%" class="indextable genindextable"><tr>
+    <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.Buffer">Buffer (class in RNS)</a>
+</li>
+    </ul></td>
+  </tr></table>
+</section>
+
 <section id="C" class="genindex-section">
   <h2>C</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
     <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.Resource.cancel">cancel() (RNS.Resource method)</a>
+</li>
+        <li><a href="reference.html#RNS.Channel.Channel">Channel (class in RNS.Channel)</a>
 </li>
         <li><a href="reference.html#RNS.Destination.clear_default_app_data">clear_default_app_data() (RNS.Destination method)</a>
+</li>
+        <li><a href="reference.html#RNS.Buffer.create_bidirectional_buffer">create_bidirectional_buffer() (RNS.Buffer static method)</a>
 </li>
     </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="reference.html#RNS.Destination.create_keys">create_keys() (RNS.Destination method)</a>
+</li>
+        <li><a href="reference.html#RNS.Buffer.create_reader">create_reader() (RNS.Buffer static method)</a>
+</li>
+        <li><a href="reference.html#RNS.Buffer.create_writer">create_writer() (RNS.Buffer static method)</a>
 </li>
         <li><a href="reference.html#RNS.Identity.CURVE">CURVE (RNS.Identity attribute)</a>
 
@@ -330,7 +366,11 @@
   <h2>G</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
     <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.Link.get_channel">get_channel() (RNS.Link method)</a>
+</li>
         <li><a href="reference.html#RNS.Resource.get_data_size">get_data_size() (RNS.Resource method)</a>
+</li>
+        <li><a href="reference.html#RNS.Link.get_establishment_rate">get_establishment_rate() (RNS.Link method)</a>
 </li>
         <li><a href="reference.html#RNS.Resource.get_hash">get_hash() (RNS.Resource method)</a>
 </li>
@@ -349,11 +389,11 @@
 </li>
         </ul></li>
         <li><a href="reference.html#RNS.Identity.get_public_key">get_public_key() (RNS.Identity method)</a>
-</li>
-        <li><a href="reference.html#RNS.Identity.get_random_hash">get_random_hash() (RNS.Identity static method)</a>
 </li>
     </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.Identity.get_random_hash">get_random_hash() (RNS.Identity static method)</a>
+</li>
         <li><a href="reference.html#RNS.Link.get_remote_identity">get_remote_identity() (RNS.Link method)</a>
 </li>
         <li><a href="reference.html#RNS.RequestReceipt.get_request_id">get_request_id() (RNS.RequestReceipt method)</a>
@@ -409,6 +449,8 @@
         <li><a href="reference.html#RNS.Link.inactive_for">inactive_for() (RNS.Link method)</a>
 </li>
         <li><a href="reference.html#RNS.Resource.is_compressed">is_compressed() (RNS.Resource method)</a>
+</li>
+        <li><a href="reference.html#RNS.Channel.Channel.is_ready_to_send">is_ready_to_send() (RNS.Channel.Channel method)</a>
 </li>
     </ul></td>
   </tr></table>
@@ -454,6 +496,14 @@
   <h2>M</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
     <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.Channel.Channel.MDU">MDU (RNS.Channel.Channel property)</a>
+</li>
+        <li><a href="reference.html#RNS.MessageBase">MessageBase (class in RNS)</a>
+</li>
+    </ul></td>
+    <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.MessageBase.MSGTYPE">MSGTYPE (RNS.MessageBase attribute)</a>
+</li>
         <li><a href="reference.html#RNS.Reticulum.MTU">MTU (RNS.Reticulum attribute)</a>
 </li>
     </ul></td>
@@ -482,12 +532,14 @@
   <h2>P</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
     <td style="width: 33%; vertical-align: top;"><ul>
-        <li><a href="reference.html#RNS.Packet">Packet (class in RNS)</a>
+        <li><a href="reference.html#RNS.MessageBase.pack">pack() (RNS.MessageBase method)</a>
 </li>
-        <li><a href="reference.html#RNS.PacketReceipt">PacketReceipt (class in RNS)</a>
+        <li><a href="reference.html#RNS.Packet">Packet (class in RNS)</a>
 </li>
     </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.PacketReceipt">PacketReceipt (class in RNS)</a>
+</li>
         <li><a href="reference.html#RNS.Transport.PATHFINDER_M">PATHFINDER_M (RNS.Transport attribute)</a>
 </li>
         <li><a href="reference.html#RNS.Packet.PLAIN_MDU">PLAIN_MDU (RNS.Packet attribute)</a>
@@ -500,18 +552,28 @@
   <h2>R</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
     <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.RawChannelReader">RawChannelReader (class in RNS)</a>
+</li>
+        <li><a href="reference.html#RNS.RawChannelWriter">RawChannelWriter (class in RNS)</a>
+</li>
         <li><a href="reference.html#RNS.Identity.recall">recall() (RNS.Identity static method)</a>
 </li>
         <li><a href="reference.html#RNS.Identity.recall_app_data">recall_app_data() (RNS.Identity static method)</a>
 </li>
         <li><a href="reference.html#RNS.Transport.register_announce_handler">register_announce_handler() (RNS.Transport static method)</a>
 </li>
-        <li><a href="reference.html#RNS.Destination.register_request_handler">register_request_handler() (RNS.Destination method)</a>
+        <li><a href="reference.html#RNS.Channel.Channel.register_message_type">register_message_type() (RNS.Channel.Channel method)</a>
 </li>
-        <li><a href="reference.html#RNS.Link.request">request() (RNS.Link method)</a>
+        <li><a href="reference.html#RNS.Destination.register_request_handler">register_request_handler() (RNS.Destination method)</a>
 </li>
     </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.Channel.Channel.remove_message_handler">remove_message_handler() (RNS.Channel.Channel method)</a>
+</li>
+        <li><a href="reference.html#RNS.RawChannelReader.remove_ready_callback">remove_ready_callback() (RNS.RawChannelReader method)</a>
+</li>
+        <li><a href="reference.html#RNS.Link.request">request() (RNS.Link method)</a>
+</li>
         <li><a href="reference.html#RNS.Transport.request_path">request_path() (RNS.Transport static method)</a>
 </li>
         <li><a href="reference.html#RNS.RequestReceipt">RequestReceipt (class in RNS)</a>
@@ -530,8 +592,12 @@
   <h2>S</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
     <td style="width: 33%; vertical-align: top;"><ul>
-        <li><a href="reference.html#RNS.Packet.send">send() (RNS.Packet method)</a>
+        <li><a href="reference.html#RNS.Channel.Channel.send">send() (RNS.Channel.Channel method)</a>
+
+        <ul>
+          <li><a href="reference.html#RNS.Packet.send">(RNS.Packet method)</a>
 </li>
+        </ul></li>
         <li><a href="reference.html#RNS.Destination.set_default_app_data">set_default_app_data() (RNS.Destination method)</a>
 </li>
         <li><a href="reference.html#RNS.PacketReceipt.set_delivery_callback">set_delivery_callback() (RNS.PacketReceipt method)</a>
@@ -604,6 +670,16 @@
   </tr></table>
 </section>
 
+<section id="U" class="genindex-section">
+  <h2>U</h2>
+  <table style="width: 100%" class="indextable genindextable"><tr>
+    <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="reference.html#RNS.MessageBase.unpack">unpack() (RNS.MessageBase method)</a>
+</li>
+    </ul></td>
+  </tr></table>
+</section>
+
 <section id="V" class="genindex-section">
   <h2>V</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
@@ -626,7 +702,7 @@
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>

docs/manual/gettingstartedfast.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Using Reticulum on Your System" href="using.html" /><link rel="prev" title="What is Reticulum?" href="whatis.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>Getting Started Fast - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>Getting Started Fast - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -226,18 +226,39 @@
 <p>The best way to get started with the Reticulum Network Stack depends on what
 you want to do. This guide will outline sensible starting paths for different
 scenarios.</p>
+<section id="standalone-reticulum-installation">
+<h2>Standalone Reticulum Installation<a class="headerlink" href="#standalone-reticulum-installation" title="Permalink to this heading">#</a></h2>
+<p>If you simply want to install Reticulum and related utilities on a system,
+the easiest way is via <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
+</pre></div>
+</div>
+<p>If you no not already have pip installed, you can install it using the package manager
+of your system with a command like <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">install</span> <span class="pre">python3-pip</span></code>,
+<code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">pamac</span> <span class="pre">install</span> <span class="pre">python-pip</span></code> or similar. You can also dowload the Reticulum release
+wheels from GitHub, or other release channels, and install them offline using <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">./</span><span class="n">rns</span><span class="o">-</span><span class="mf">0.4.6</span><span class="o">-</span><span class="n">py3</span><span class="o">-</span><span class="n">none</span><span class="o">-</span><span class="nb">any</span><span class="o">.</span><span class="n">whl</span>
+</pre></div>
+</div>
+</section>
 <section id="try-using-a-reticulum-based-program">
 <h2>Try Using a Reticulum-based Program<a class="headerlink" href="#try-using-a-reticulum-based-program" title="Permalink to this heading">#</a></h2>
 <p>If you simply want to try using a program built with Reticulum, a few different
-programs exist that allow basic communication and a range of other useful functions
-over even extremely low-bandwidth Reticulum networks.</p>
+programs exist that allow basic communication and a range of other useful functions,
+even over extremely low-bandwidth Reticulum networks.</p>
 <p>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 completely
-over local WiFi, wired Ethernet, the Internet, or any combination.</p>
+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.</p>
 <p>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.</p>
+<section id="remote-shell">
+<h3>Remote Shell<a class="headerlink" href="#remote-shell" title="Permalink to this heading">#</a></h3>
+<p>The <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> 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 <code class="docutils literal notranslate"><span class="pre">ssh</span></code> works.</p>
+</section>
 <section id="nomad-network">
 <h3>Nomad Network<a class="headerlink" href="#nomad-network" title="Permalink to this heading">#</a></h3>
 <p>The terminal-based program <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a>
@@ -251,7 +272,7 @@ for the messaging and information-sharing protocol
 <a class="reference external" href="https://github.com/markqvist/lxmf">LXMF</a>, another project built with Reticulum.</p>
 <p>You can install Nomad Network via pip:</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install ...</span>
-<span class="n">pip3</span> <span class="n">install</span> <span class="n">nomadnet</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="n">nomadnet</span>
 
 <span class="c1"># ... and run</span>
 <span class="n">nomadnet</span>
@@ -267,9 +288,11 @@ program, reboot your system and try again.</p>
 <p>If you would rather use a program with a graphical user interface, you can take
 a look at <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>, which is available for Android,
 Linux and macOS.</p>
-<a class="reference external image-reference" href="_images/sideband_1.png"><img alt="_images/sideband_1.png" class="align-center" src="_images/sideband_1.png" /></a>
-<p>Sideband is currently in the early stages of development, but already provides basic
-communication features, and interoperates with Nomad Network, or any other LXMF client.</p>
+<a class="reference external image-reference" href="_images/sideband_devices.webp"><img alt="_images/sideband_devices.webp" class="align-center" src="_images/sideband_devices.webp" /></a>
+<p>Sideband allows you to communicate with other people or LXMF-compatible
+systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR
+Paper Messages, or anything else Reticulum supports. It also interoperates with
+the Nomad Network program.</p>
 </section>
 </section>
 <section id="using-the-included-utilities">
@@ -287,8 +310,8 @@ network status and connectivity.</p>
 <h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this heading">#</a></h2>
 <p>To create a network, you will need to specify one or more <em>interfaces</em> for
 Reticulum to use. This is done in the Reticulum configuration file, which by
-default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. You can edit this file by hand,
-or use the interactive <code class="docutils literal notranslate"><span class="pre">rnsconfig</span></code> utility.</p>
+default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. You can get an example
+configuration file with all options via <code class="docutils literal notranslate"><span class="pre">rnsd</span> <span class="pre">--exampleconfig</span></code>.</p>
 <p>When Reticulum is started for the first time, it will create a default
 configuration file, with one active interface. This default interface uses
 your existing Ethernet and WiFi networks (if any), and only allows you to
@@ -352,7 +375,7 @@ by adding one of the following interfaces to your <code class="docutils literal
   <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4965</span>
 
 <span class="c1"># TCP/IP interface to the Frankfurt hub</span>
-<span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">Dublin</span><span class="p">]]</span>
+<span class="p">[[</span><span class="n">RNS</span> <span class="n">Testnet</span> <span class="n">Frankfurt</span><span class="p">]]</span>
   <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
   <span class="n">enabled</span> <span class="o">=</span> <span class="n">yes</span>
   <span class="n">target_host</span> <span class="o">=</span> <span class="n">frankfurt</span><span class="o">.</span><span class="n">connect</span><span class="o">.</span><span class="n">reticulum</span><span class="o">.</span><span class="n">network</span>
@@ -387,7 +410,7 @@ chapter for a guide. If you prefer purchasing a ready-made unit, you can refer t
 refer to these additional external resources:</p>
 <ul class="simple">
 <li><p><a class="reference external" href="https://unsigned.io/how-to-make-your-own-rnodes/">How To Make Your Own RNodes</a></p></li>
-<li><p><a class="reference external" href="https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/">Installing RNode Firmware on Compatible LoRa Devices</a></p></li>
+<li><p><a class="reference external" href="https://unsigned.io/installing-rnode-firmware-on-supported-devices/">Installing RNode Firmware on Compatible LoRa Devices</a></p></li>
 <li><p><a class="reference external" href="https://unsigned.io/private-messaging-over-lora/">Private, Secure and Uncensorable Messaging Over a LoRa Mesh</a></p></li>
 <li><p><a class="reference external" href="https://github.com/markqvist/RNode_Firmware/">RNode Firmware</a></p></li>
 </ul>
@@ -443,7 +466,7 @@ don’t use pip, but try this recipe:</p>
 
 <span class="c1"># Run the example in client mode to &quot;ping&quot; the server.</span>
 <span class="c1"># Replace the hash below with the actual destination hash of your server.</span>
-<span class="n">python3</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="mf">3e12</span><span class="n">fc71692f8ec47bc5</span>
+<span class="n">python3</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Echo</span><span class="o">.</span><span class="n">py</span> <span class="mi">174</span><span class="n">a64852a75682259ad8b921b8bf416</span>
 
 <span class="c1"># Have a look at another example</span>
 <span class="n">python3</span> <span class="n">Examples</span><span class="o">/</span><span class="n">Filetransfer</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">h</span>
@@ -458,7 +481,7 @@ or ask one of the developers or maintainers for a good place to start.</p>
 <section id="reticulum-on-arm64">
 <h2>Reticulum on ARM64<a class="headerlink" href="#reticulum-on-arm64" title="Permalink to this heading">#</a></h2>
 <p>On some architectures, including ARM64, not all dependencies have precompiled
-binaries. On such systems, you will need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> before
+binaries. On such systems, you may need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> before
 installing Reticulum or programs that depend on Reticulum.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install Python and development packages</span>
 <span class="n">sudo</span> <span class="n">apt</span> <span class="n">update</span>
@@ -469,6 +492,12 @@ installing Reticulum or programs that depend on Reticulum.</p>
 </pre></div>
 </div>
 </section>
+<section id="reticulum-on-raspberry-pi">
+<h2>Reticulum on Raspberry Pi<a class="headerlink" href="#reticulum-on-raspberry-pi" title="Permalink to this heading">#</a></h2>
+<p>It is currently recommended to use a 64-bit version of the Raspberry Pi OS
+if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
+don’t always have packages available for some dependencies.</p>
+</section>
 <section id="reticulum-on-android">
 <h2>Reticulum on Android<a class="headerlink" href="#reticulum-on-android" title="Permalink to this heading">#</a></h2>
 <p>Reticulum can be used on Android in different ways. The easiest way to get
@@ -479,19 +508,36 @@ the <a class="reference external" href="https://termux.com/">Termux app</a>, at
 <p>Termux is a terminal emulator and Linux environment for Android based devices,
 which includes the ability to use many different programs and libraries,
 including Reticulum.</p>
-<p>Since the Python cryptography.io module does not offer pre-built wheels for
-Android, the standard one-line install of Reticulum does not work on Android,
-and a few extra commands are required.</p>
+<p>To use Reticulum within the Termux environment, you will need to install
+<code class="docutils literal notranslate"><span class="pre">python</span></code> and the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> library using <code class="docutils literal notranslate"><span class="pre">pkg</span></code>, the package-manager
+build into Termux. After that, you can use <code class="docutils literal notranslate"><span class="pre">pip</span></code> to install Reticulum.</p>
 <p>From within Termux, execute the following:</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># First, make sure indexes and packages are up to date.</span>
 <span class="n">pkg</span> <span class="n">update</span>
 <span class="n">pkg</span> <span class="n">upgrade</span>
 
+<span class="c1"># Then install python and the cryptography library.</span>
+<span class="n">pkg</span> <span class="n">install</span> <span class="n">python</span> <span class="n">python</span><span class="o">-</span><span class="n">cryptography</span>
+
+<span class="c1"># Make sure pip is up to date, and install the wheel module.</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="n">wheel</span> <span class="n">pip</span> <span class="o">--</span><span class="n">upgrade</span>
+
+<span class="c1"># Install Reticulum</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
+</pre></div>
+</div>
+<p>If for some reason the <code class="docutils literal notranslate"><span class="pre">python-cryptography</span></code> 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:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># First, make sure indexes and packages are up to date.</span>
+<span class="n">pkg</span> <span class="n">update</span>
+<span class="n">pkg</span> <span class="n">upgrade</span>
+
 <span class="c1"># Then install dependencies for the cryptography library.</span>
 <span class="n">pkg</span> <span class="n">install</span> <span class="n">python</span> <span class="n">build</span><span class="o">-</span><span class="n">essential</span> <span class="n">openssl</span> <span class="n">libffi</span> <span class="n">rust</span>
 
 <span class="c1"># Make sure pip is up to date, and install the wheel module.</span>
-<span class="n">pip3</span> <span class="n">install</span> <span class="n">wheel</span> <span class="n">pip</span> <span class="o">--</span><span class="n">upgrade</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="n">wheel</span> <span class="n">pip</span> <span class="o">--</span><span class="n">upgrade</span>
 
 <span class="c1"># To allow the installer to build the cryptography module,</span>
 <span class="c1"># we need to let it know what platform we are compiling for:</span>
@@ -500,11 +546,11 @@ and a few extra commands are required.</p>
 <span class="c1"># Start the install process for the cryptography module.</span>
 <span class="c1"># Depending on your device, this can take several minutes,</span>
 <span class="c1"># since the module must be compiled locally on your device.</span>
-<span class="n">pip3</span> <span class="n">install</span> <span class="n">cryptography</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span>
 
 <span class="c1"># If the above installation succeeds, you can now install</span>
 <span class="c1"># Reticulum and any related software</span>
-<span class="n">pip3</span> <span class="n">install</span> <span class="n">rns</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
 </pre></div>
 </div>
 <p>It is also possible to include Reticulum in apps compiled and distributed as
@@ -517,7 +563,8 @@ here at a later point. Until then you can use the <a class="reference external"
 install one or more dependencies</p>
 <p>On more unusual systems, and in some rare cases, it might not be possible to
 install or even compile one or more of the above modules. In such situations,
-you can use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package instead of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> package. The <code class="docutils literal notranslate"><span class="pre">rnspure</span></code>
+you can use the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package instead of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> package, or use <code class="docutils literal notranslate"><span class="pre">pip</span></code>
+with the <code class="docutils literal notranslate"><span class="pre">--no-dependencies</span></code> command-line option. The <code class="docutils literal notranslate"><span class="pre">rnspure</span></code>
 package requires no external dependencies for installation. Please note that the
 actual contents of the <code class="docutils literal notranslate"><span class="pre">rns</span></code> and <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> packages are <em>completely identical</em>.
 The only difference is that the <code class="docutils literal notranslate"><span class="pre">rnspure</span></code> package lists no dependencies required
@@ -563,7 +610,7 @@ section of this manual.</p>
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>
@@ -591,7 +638,9 @@ section of this manual.</p>
           <div class="toc-tree">
             <ul>
 <li><a class="reference internal" href="#">Getting Started Fast</a><ul>
+<li><a class="reference internal" href="#standalone-reticulum-installation">Standalone Reticulum Installation</a></li>
 <li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul>
+<li><a class="reference internal" href="#remote-shell">Remote Shell</a></li>
 <li><a class="reference internal" href="#nomad-network">Nomad Network</a></li>
 <li><a class="reference internal" href="#sideband">Sideband</a></li>
 </ul>
@@ -604,6 +653,7 @@ section of this manual.</p>
 <li><a class="reference internal" href="#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
 <li><a class="reference internal" href="#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
 <li><a class="reference internal" href="#reticulum-on-arm64">Reticulum on ARM64</a></li>
+<li><a class="reference internal" href="#reticulum-on-raspberry-pi">Reticulum on Raspberry Pi</a></li>
 <li><a class="reference internal" href="#reticulum-on-android">Reticulum on Android</a></li>
 <li><a class="reference internal" href="#pure-python-reticulum">Pure-Python Reticulum</a></li>
 </ul>

docs/manual/hardware.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Supported Interfaces" href="interfaces.html" /><link rel="prev" title="Understanding Reticulum" href="understanding.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>Communications Hardware - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>Communications Hardware - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -349,9 +349,10 @@ boards. The following boards are supported by the auto-installer.</p>
 <span id="rnode-installation"></span><h3>Installation<a class="headerlink" href="#installation" title="Permalink to this heading">#</a></h3>
 <p>Once you have obtained compatible boards, you can install the <a class="reference external" href="https://github.com/markqvist/RNode_Firmware">RNode Firmware</a>
 using the <a class="reference external" href="https://github.com/markqvist/rnodeconfigutil">RNode Configuration Utility</a>.
-Make sure that <code class="docutils literal notranslate"><span class="pre">Python3</span></code> and <code class="docutils literal notranslate"><span class="pre">pip</span></code> is installed on your system, and then install
-the config utility with <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip3</span> <span class="n">install</span> <span class="n">rnodeconf</span>
+If you have installed Reticulum on your system, the <code class="docutils literal notranslate"><span class="pre">rnodeconf</span></code> program will already be
+available. If not, make sure that <code class="docutils literal notranslate"><span class="pre">Python3</span></code> and <code class="docutils literal notranslate"><span class="pre">pip</span></code> is installed on your system, and
+then install Reticulum with with <code class="docutils literal notranslate"><span class="pre">pip</span></code>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
 </pre></div>
 </div>
 <p>Once installation has completed, it is time to start installing the firmware on your
@@ -361,11 +362,7 @@ devices. Run <code class="docutils literal notranslate"><span class="pre">rnodec
 </div>
 <p>The utility will guide you through the installation process by asking a series of
 questions about your hardware. Simply follow the guide, and the utility will
-auto-install and configure your devices</p>
-<p><strong>Important Note!</strong> It is currently recommended to use the v1.x line of the RNode firmware,
-even though the v2.x line is available for early testing. The v2.x line should still be
-considered an experimental pre-release. Only use the v2.x firmware line if you want to test
-out the absolutely newest version, and don’t care about stability.</p>
+auto-install and configure your devices.</p>
 </section>
 <section id="usage-with-reticulum">
 <span id="rnode-usage"></span><h3>Usage with Reticulum<a class="headerlink" href="#usage-with-reticulum" title="Permalink to this heading">#</a></h3>
@@ -445,7 +442,7 @@ connectivity for client devices.</p>
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>

docs/manual/index.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="What is Reticulum?" href="whatis.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="#"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="#"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -226,6 +226,7 @@
 <p>This manual aims to provide you with all the information you need to
 understand Reticulum, build networks or develop programs using it, or
 to participate in the development of Reticulum itself.</p>
+<p>This manual is also available in <a class="reference external" href="https://github.com/markqvist/Reticulum/releases/latest/download/Reticulum.Manual.pdf">PDF</a> and <a class="reference external" href="https://github.com/markqvist/Reticulum/releases/latest/download/Reticulum.Manual.epub">EPUB</a> formats.</p>
 <section id="table-of-contents">
 <h2>Table Of Contents<a class="headerlink" href="#table-of-contents" title="Permalink to this heading">#</a></h2>
 </section>
@@ -240,7 +241,9 @@ to participate in the development of Reticulum itself.</p>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#standalone-reticulum-installation">Standalone Reticulum Installation</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#remote-shell">Remote Shell</a></li>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#nomad-network">Nomad Network</a></li>
 <li class="toctree-l3"><a class="reference internal" href="gettingstartedfast.html#sideband">Sideband</a></li>
 </ul>
@@ -253,6 +256,7 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#reticulum-on-arm64">Reticulum on ARM64</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#reticulum-on-raspberry-pi">Reticulum on Raspberry Pi</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#reticulum-on-android">Reticulum on Android</a></li>
 <li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#pure-python-reticulum">Pure-Python Reticulum</a></li>
 </ul>
@@ -266,6 +270,7 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l3"><a class="reference internal" href="using.html#the-rnprobe-utility">The rnprobe Utility</a></li>
 <li class="toctree-l3"><a class="reference internal" href="using.html#the-rncp-utility">The rncp Utility</a></li>
 <li class="toctree-l3"><a class="reference internal" href="using.html#the-rnx-utility">The rnx Utility</a></li>
+<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnodeconf-utility">The rnodeconf Utility</a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="using.html#improving-system-configuration">Improving System Configuration</a><ul>
@@ -350,6 +355,8 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#link">Link</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#example-identify">Identification</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#requests-responses">Requests &amp; Responses</a></li>
+<li class="toctree-l2"><a class="reference internal" href="examples.html#channel">Channel</a></li>
+<li class="toctree-l2"><a class="reference internal" href="examples.html#buffer">Buffer</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#filetransfer">Filetransfer</a></li>
 </ul>
 </li>
@@ -372,6 +379,11 @@ to participate in the development of Reticulum itself.</p>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#RNS.Link"><code class="docutils literal notranslate"><span class="pre">Link</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#RNS.RequestReceipt"><code class="docutils literal notranslate"><span class="pre">RequestReceipt</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#RNS.Resource"><code class="docutils literal notranslate"><span class="pre">Resource</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference.html#RNS.Channel.Channel"><code class="docutils literal notranslate"><span class="pre">Channel</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference.html#RNS.MessageBase"><code class="docutils literal notranslate"><span class="pre">MessageBase</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference.html#RNS.Buffer"><code class="docutils literal notranslate"><span class="pre">Buffer</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference.html#RNS.RawChannelReader"><code class="docutils literal notranslate"><span class="pre">RawChannelReader</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference.html#RNS.RawChannelWriter"><code class="docutils literal notranslate"><span class="pre">RawChannelWriter</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#RNS.Transport"><code class="docutils literal notranslate"><span class="pre">Transport</span></code></a></li>
 </ul>
 </li>
@@ -405,7 +417,7 @@ to participate in the development of Reticulum itself.</p>
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>

docs/manual/interfaces.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Building Networks" href="networks.html" /><link rel="prev" title="Communications Hardware" href="hardware.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>Supported Interfaces - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>Supported Interfaces - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -954,7 +954,7 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>

docs/manual/networks.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Code Examples" href="examples.html" /><link rel="prev" title="Supported Interfaces" href="interfaces.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>Building Networks - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>Building Networks - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -421,7 +421,7 @@ connected outliers are now an integral part of the network.</p>
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>

docs/manual/reference.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="prev" title="Support Reticulum" href="support.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>API Reference - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>API Reference - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -637,7 +637,7 @@ encrypted communication with it.</p>
 
 <dl class="py method">
 <dt class="sig sig-object py" id="RNS.Destination.announce">
-<span class="sig-name descname"><span class="pre">announce</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">app_data</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">path_response</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">send</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Destination.announce" title="Permalink to this definition">#</a></dt>
+<span class="sig-name descname"><span class="pre">announce</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">app_data</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">path_response</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attached_interface</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">send</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Destination.announce" title="Permalink to this definition">#</a></dt>
 <dd><p>Creates an announce packet for this destination and broadcasts it on all
 relevant interfaces. Application specific data can be added to the announce.</p>
 <dl class="field-list simple">
@@ -720,7 +720,7 @@ proofs should be returned for received packets.</p>
 <dt class="field-odd">Parameters</dt>
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>path</strong> – The path for the request handler to be registered.</p></li>
-<li><p><strong>response_generator</strong> – A function or method with the signature <em>response_generator(path, data, request_id, remote_identity, requested_at)</em> to be called. Whatever this funcion returns will be sent as a response to the requester. If the function returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, no response will be sent.</p></li>
+<li><p><strong>response_generator</strong> – A function or method with the signature <em>response_generator(path, data, request_id, link_id, remote_identity, requested_at)</em> to be called. Whatever this funcion returns will be sent as a response to the requester. If the function returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, no response will be sent.</p></li>
 <li><p><strong>allow</strong> – One of <code class="docutils literal notranslate"><span class="pre">RNS.Destination.ALLOW_NONE</span></code>, <code class="docutils literal notranslate"><span class="pre">RNS.Destination.ALLOW_ALL</span></code> or <code class="docutils literal notranslate"><span class="pre">RNS.Destination.ALLOW_LIST</span></code>. If <code class="docutils literal notranslate"><span class="pre">RNS.Destination.ALLOW_LIST</span></code> is set, the request handler will only respond to requests for identified peers in the supplied list.</p></li>
 <li><p><strong>allowed_list</strong> – A list of <em>bytes-like</em> <a class="reference internal" href="#api-identity"><span class="std std-ref">RNS.Identity</span></a> hashes.</p></li>
 </ul>
@@ -991,7 +991,7 @@ and encrypted connectivity with the specified destination.</p>
 
 <dl class="py attribute">
 <dt class="sig sig-object py" id="RNS.Link.ESTABLISHMENT_TIMEOUT_PER_HOP">
-<span class="sig-name descname"><span class="pre">ESTABLISHMENT_TIMEOUT_PER_HOP</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">5</span></em><a class="headerlink" href="#RNS.Link.ESTABLISHMENT_TIMEOUT_PER_HOP" title="Permalink to this definition">#</a></dt>
+<span class="sig-name descname"><span class="pre">ESTABLISHMENT_TIMEOUT_PER_HOP</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">6</span></em><a class="headerlink" href="#RNS.Link.ESTABLISHMENT_TIMEOUT_PER_HOP" title="Permalink to this definition">#</a></dt>
 <dd><p>Timeout for link establishment in seconds per hop to destination.</p>
 </dd></dl>
 
@@ -1057,6 +1057,16 @@ thus preserved. This method can be used for authentication.</p>
 </dl>
 </dd></dl>
 
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Link.get_establishment_rate">
+<span class="sig-name descname"><span class="pre">get_establishment_rate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Link.get_establishment_rate" title="Permalink to this definition">#</a></dt>
+<dd><dl class="field-list simple">
+<dt class="field-odd">Returns</dt>
+<dd class="field-odd"><p>The data transfer rate at which the link establishment procedure ocurred, in bits per second.</p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="RNS.Link.no_inbound_for">
 <span class="sig-name descname"><span class="pre">no_inbound_for</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Link.no_inbound_for" title="Permalink to this definition">#</a></dt>
@@ -1104,6 +1114,17 @@ thus preserved. This method can be used for authentication.</p>
 be used if a new link to the same destination is established.</p>
 </dd></dl>
 
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Link.get_channel">
+<span class="sig-name descname"><span class="pre">get_channel</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Link.get_channel" title="Permalink to this definition">#</a></dt>
+<dd><p>Get the <code class="docutils literal notranslate"><span class="pre">Channel</span></code> for this link.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns</dt>
+<dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">Channel</span></code> object</p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="RNS.Link.set_link_closed_callback">
 <span class="sig-name descname"><span class="pre">set_link_closed_callback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">callback</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Link.set_link_closed_callback" title="Permalink to this definition">#</a></dt>
@@ -1357,6 +1378,321 @@ the resource advertisement it will begin transferring.</p>
 
 </dd></dl>
 
+<p id="api-channel"><h3> Channel </h3></p>
+<dl class="py class">
+<dt class="sig sig-object py" id="RNS.Channel.Channel">
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.Channel.</span></span><span class="sig-name descname"><span class="pre">Channel</span></span><a class="headerlink" href="#RNS.Channel.Channel" title="Permalink to this definition">#</a></dt>
+<dd><p>Provides reliable delivery of messages over
+a link.</p>
+<p><code class="docutils literal notranslate"><span class="pre">Channel</span></code> differs from <code class="docutils literal notranslate"><span class="pre">Request</span></code> and
+<code class="docutils literal notranslate"><span class="pre">Resource</span></code> in some important ways:</p>
+<blockquote>
+<div><dl class="simple">
+<dt><strong>Continuous</strong></dt><dd><p>Messages can be sent or received as long as
+the <code class="docutils literal notranslate"><span class="pre">Link</span></code> is open.</p>
+</dd>
+<dt><strong>Bi-directional</strong></dt><dd><p>Messages can be sent in either direction on
+the <code class="docutils literal notranslate"><span class="pre">Link</span></code>; neither end is the client or
+server.</p>
+</dd>
+<dt><strong>Size-constrained</strong></dt><dd><p>Messages must be encoded into a single packet.</p>
+</dd>
+</dl>
+</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">Channel</span></code> is similar to <code class="docutils literal notranslate"><span class="pre">Packet</span></code>, except that it
+provides reliable delivery (automatic retries) as well
+as a structure for exchanging several types of
+messages over the <code class="docutils literal notranslate"><span class="pre">Link</span></code>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">Channel</span></code> is not instantiated directly, but rather
+obtained from a <code class="docutils literal notranslate"><span class="pre">Link</span></code> with <code class="docutils literal notranslate"><span class="pre">get_channel()</span></code>.</p>
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Channel.Channel.register_message_type">
+<span class="sig-name descname"><span class="pre">register_message_type</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message_class</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Type</span><span class="p"><span class="pre">[</span></span><a class="reference internal" href="#RNS.MessageBase" title="RNS.Channel.MessageBase"><span class="pre">MessageBase</span></a><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Channel.Channel.register_message_type" title="Permalink to this definition">#</a></dt>
+<dd><p>Register a message class for reception over a <code class="docutils literal notranslate"><span class="pre">Channel</span></code>.</p>
+<p>Message classes must extend <code class="docutils literal notranslate"><span class="pre">MessageBase</span></code>.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>message_class</strong> – Class to register</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Channel.Channel.add_message_handler">
+<span class="sig-name descname"><span class="pre">add_message_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">callback</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">MessageCallbackType</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Channel.Channel.add_message_handler" title="Permalink to this definition">#</a></dt>
+<dd><p>Add a handler for incoming messages. A handler
+has the following signature:</p>
+<p><code class="docutils literal notranslate"><span class="pre">(message:</span> <span class="pre">MessageBase)</span> <span class="pre">-&gt;</span> <span class="pre">bool</span></code></p>
+<p>Handlers are processed in the order they are
+added. If any handler returns True, processing
+of the message stops; handlers after the
+returning handler will not be called.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>callback</strong> – Function to call</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Channel.Channel.remove_message_handler">
+<span class="sig-name descname"><span class="pre">remove_message_handler</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">callback</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">MessageCallbackType</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Channel.Channel.remove_message_handler" title="Permalink to this definition">#</a></dt>
+<dd><p>Remove a handler added with <code class="docutils literal notranslate"><span class="pre">add_message_handler</span></code>.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>callback</strong> – handler to remove</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Channel.Channel.is_ready_to_send">
+<span class="sig-name descname"><span class="pre">is_ready_to_send</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="headerlink" href="#RNS.Channel.Channel.is_ready_to_send" title="Permalink to this definition">#</a></dt>
+<dd><p>Check if <code class="docutils literal notranslate"><span class="pre">Channel</span></code> is ready to send.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns</dt>
+<dd class="field-odd"><p>True if ready</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Channel.Channel.send">
+<span class="sig-name descname"><span class="pre">send</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#RNS.MessageBase" title="RNS.Channel.MessageBase"><span class="pre">MessageBase</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Envelope</span></span></span><a class="headerlink" href="#RNS.Channel.Channel.send" title="Permalink to this definition">#</a></dt>
+<dd><p>Send a message. If a message send is attempted and
+<code class="docutils literal notranslate"><span class="pre">Channel</span></code> is not ready, an exception is thrown.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>message</strong> – an instance of a <code class="docutils literal notranslate"><span class="pre">MessageBase</span></code> subclass</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py property">
+<dt class="sig sig-object py" id="RNS.Channel.Channel.MDU">
+<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">MDU</span></span><a class="headerlink" href="#RNS.Channel.Channel.MDU" title="Permalink to this definition">#</a></dt>
+<dd><p>Maximum Data Unit: the number of bytes available
+for a message to consume in a single send. This
+value is adjusted from the <code class="docutils literal notranslate"><span class="pre">Link</span></code> MDU to accommodate
+message header information.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns</dt>
+<dd class="field-odd"><p>number of bytes available</p>
+</dd>
+</dl>
+</dd></dl>
+
+</dd></dl>
+
+<p id="api-messsagebase"><h3> MessageBase </h3></p>
+<dl class="py class">
+<dt class="sig sig-object py" id="RNS.MessageBase">
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">MessageBase</span></span><a class="headerlink" href="#RNS.MessageBase" title="Permalink to this definition">#</a></dt>
+<dd><p>Base type for any messages sent or received on a Channel.
+Subclasses must define the two abstract methods as well as
+the <code class="docutils literal notranslate"><span class="pre">MSGTYPE</span></code> class variable.</p>
+<dl class="py attribute">
+<dt class="sig sig-object py" id="RNS.MessageBase.MSGTYPE">
+<span class="sig-name descname"><span class="pre">MSGTYPE</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#RNS.MessageBase.MSGTYPE" title="Permalink to this definition">#</a></dt>
+<dd><p>Defines a unique identifier for a message class.</p>
+<ul class="simple">
+<li><p>Must be unique within all classes registered with a <code class="docutils literal notranslate"><span class="pre">Channel</span></code></p></li>
+<li><p>Must be less than <code class="docutils literal notranslate"><span class="pre">0xf000</span></code>. Values greater than or equal to <code class="docutils literal notranslate"><span class="pre">0xf000</span></code> are reserved.</p></li>
+</ul>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.MessageBase.pack">
+<em class="property"><span class="pre">abstract</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">pack</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bytes</span></span></span><a class="headerlink" href="#RNS.MessageBase.pack" title="Permalink to this definition">#</a></dt>
+<dd><p>Create and return the binary representation of the message</p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns</dt>
+<dd class="field-odd"><p>binary representation of message</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.MessageBase.unpack">
+<em class="property"><span class="pre">abstract</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">unpack</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">raw</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bytes</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.MessageBase.unpack" title="Permalink to this definition">#</a></dt>
+<dd><p>Populate message from binary representation</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>raw</strong> – binary representation</p>
+</dd>
+</dl>
+</dd></dl>
+
+</dd></dl>
+
+<p id="api-buffer"><h3> Buffer </h3></p>
+<dl class="py class">
+<dt class="sig sig-object py" id="RNS.Buffer">
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Buffer</span></span><a class="headerlink" href="#RNS.Buffer" title="Permalink to this definition">#</a></dt>
+<dd><p>Static functions for creating buffered streams that send
+and receive over a <code class="docutils literal notranslate"><span class="pre">Channel</span></code>.</p>
+<p>These functions use <code class="docutils literal notranslate"><span class="pre">BufferedReader</span></code>, <code class="docutils literal notranslate"><span class="pre">BufferedWriter</span></code>,
+and <code class="docutils literal notranslate"><span class="pre">BufferedRWPair</span></code> to add buffering to
+<code class="docutils literal notranslate"><span class="pre">RawChannelReader</span></code> and <code class="docutils literal notranslate"><span class="pre">RawChannelWriter</span></code>.</p>
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Buffer.create_reader">
+<em class="property"><span class="pre">static</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">create_reader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stream_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#RNS.Channel.Channel" title="RNS.Channel.Channel"><span class="pre">Channel</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">ready_callback</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">None</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">BufferedReader</span></span></span><a class="headerlink" href="#RNS.Buffer.create_reader" title="Permalink to this definition">#</a></dt>
+<dd><p>Create a buffered reader that reads binary data sent
+over a <code class="docutils literal notranslate"><span class="pre">Channel</span></code>, with an optional callback when
+new data is available.</p>
+<p>Callback signature: <code class="docutils literal notranslate"><span class="pre">(ready_bytes:</span> <span class="pre">int)</span> <span class="pre">-&gt;</span> <span class="pre">None</span></code></p>
+<p>For more information on the reader-specific functions
+of this object, see the Python documentation for
+<code class="docutils literal notranslate"><span class="pre">BufferedReader</span></code></p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>stream_id</strong> – the local stream id to receive from</p></li>
+<li><p><strong>channel</strong> – the channel to receive on</p></li>
+<li><p><strong>ready_callback</strong> – function to call when new data is available</p></li>
+</ul>
+</dd>
+<dt class="field-even">Returns</dt>
+<dd class="field-even"><p>a BufferedReader object</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Buffer.create_writer">
+<em class="property"><span class="pre">static</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">create_writer</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stream_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#RNS.Channel.Channel" title="RNS.Channel.Channel"><span class="pre">Channel</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">BufferedWriter</span></span></span><a class="headerlink" href="#RNS.Buffer.create_writer" title="Permalink to this definition">#</a></dt>
+<dd><p>Create a buffered writer that writes binary data over
+a <code class="docutils literal notranslate"><span class="pre">Channel</span></code>.</p>
+<p>For more information on the writer-specific functions
+of this object, see the Python documentation for
+<code class="docutils literal notranslate"><span class="pre">BufferedWriter</span></code></p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>stream_id</strong> – the remote stream id to send to</p></li>
+<li><p><strong>channel</strong> – the channel to send on</p></li>
+</ul>
+</dd>
+<dt class="field-even">Returns</dt>
+<dd class="field-even"><p>a BufferedWriter object</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.Buffer.create_bidirectional_buffer">
+<em class="property"><span class="pre">static</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">create_bidirectional_buffer</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">receive_stream_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">send_stream_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#RNS.Channel.Channel" title="RNS.Channel.Channel"><span class="pre">Channel</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">ready_callback</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">None</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">BufferedRWPair</span></span></span><a class="headerlink" href="#RNS.Buffer.create_bidirectional_buffer" title="Permalink to this definition">#</a></dt>
+<dd><p>Create a buffered reader/writer pair that reads and
+writes binary data over a <code class="docutils literal notranslate"><span class="pre">Channel</span></code>, with an
+optional callback when new data is available.</p>
+<p>Callback signature: <code class="docutils literal notranslate"><span class="pre">(ready_bytes:</span> <span class="pre">int)</span> <span class="pre">-&gt;</span> <span class="pre">None</span></code></p>
+<p>For more information on the reader-specific functions
+of this object, see the Python documentation for
+<code class="docutils literal notranslate"><span class="pre">BufferedRWPair</span></code></p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>receive_stream_id</strong> – the local stream id to receive at</p></li>
+<li><p><strong>send_stream_id</strong> – the remote stream id to send to</p></li>
+<li><p><strong>channel</strong> – the channel to send and receive on</p></li>
+<li><p><strong>ready_callback</strong> – function to call when new data is available</p></li>
+</ul>
+</dd>
+<dt class="field-even">Returns</dt>
+<dd class="field-even"><p>a BufferedRWPair object</p>
+</dd>
+</dl>
+</dd></dl>
+
+</dd></dl>
+
+<p id="api-rawchannelreader"><h3> RawChannelReader </h3></p>
+<dl class="py class">
+<dt class="sig sig-object py" id="RNS.RawChannelReader">
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">RawChannelReader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stream_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#RNS.Channel.Channel" title="RNS.Channel.Channel"><span class="pre">Channel</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.RawChannelReader" title="Permalink to this definition">#</a></dt>
+<dd><p>An implementation of RawIOBase that receives
+binary stream data sent over a <code class="docutils literal notranslate"><span class="pre">Channel</span></code>.</p>
+<blockquote>
+<div><p>This class generally need not be instantiated directly.
+Use <a class="reference internal" href="#RNS.Buffer.create_reader" title="RNS.Buffer.create_reader"><code class="xref py py-func docutils literal notranslate"><span class="pre">RNS.Buffer.create_reader()</span></code></a>,
+<a class="reference internal" href="#RNS.Buffer.create_writer" title="RNS.Buffer.create_writer"><code class="xref py py-func docutils literal notranslate"><span class="pre">RNS.Buffer.create_writer()</span></code></a>, and
+<a class="reference internal" href="#RNS.Buffer.create_bidirectional_buffer" title="RNS.Buffer.create_bidirectional_buffer"><code class="xref py py-func docutils literal notranslate"><span class="pre">RNS.Buffer.create_bidirectional_buffer()</span></code></a> functions
+to create buffered streams with optional callbacks.</p>
+<p>For additional information on the API of this
+object, see the Python documentation for
+<code class="docutils literal notranslate"><span class="pre">RawIOBase</span></code>.</p>
+</div></blockquote>
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.RawChannelReader.__init__">
+<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stream_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#RNS.Channel.Channel" title="RNS.Channel.Channel"><span class="pre">Channel</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.RawChannelReader.__init__" title="Permalink to this definition">#</a></dt>
+<dd><p>Create a raw channel reader.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>stream_id</strong> – local stream id to receive at</p></li>
+<li><p><strong>channel</strong> – <code class="docutils literal notranslate"><span class="pre">Channel</span></code> object to receive from</p></li>
+</ul>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.RawChannelReader.add_ready_callback">
+<span class="sig-name descname"><span class="pre">add_ready_callback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cb</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">None</span><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.RawChannelReader.add_ready_callback" title="Permalink to this definition">#</a></dt>
+<dd><p>Add a function to be called when new data is available.
+The function should have the signature <code class="docutils literal notranslate"><span class="pre">(ready_bytes:</span> <span class="pre">int)</span> <span class="pre">-&gt;</span> <span class="pre">None</span></code></p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>cb</strong> – function to call</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.RawChannelReader.remove_ready_callback">
+<span class="sig-name descname"><span class="pre">remove_ready_callback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cb</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Callable</span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">None</span><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.RawChannelReader.remove_ready_callback" title="Permalink to this definition">#</a></dt>
+<dd><p>Remove a function added with <a class="reference internal" href="#RNS.RawChannelReader.add_ready_callback" title="RNS.RawChannelReader.add_ready_callback"><code class="xref py py-func docutils literal notranslate"><span class="pre">RNS.RawChannelReader.add_ready_callback()</span></code></a></p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><p><strong>cb</strong> – function to remove</p>
+</dd>
+</dl>
+</dd></dl>
+
+</dd></dl>
+
+<p id="api-rawchannelwriter"><h3> RawChannelWriter </h3></p>
+<dl class="py class">
+<dt class="sig sig-object py" id="RNS.RawChannelWriter">
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">RawChannelWriter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stream_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#RNS.Channel.Channel" title="RNS.Channel.Channel"><span class="pre">Channel</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.RawChannelWriter" title="Permalink to this definition">#</a></dt>
+<dd><p>An implementation of RawIOBase that receives
+binary stream data sent over a channel.</p>
+<blockquote>
+<div><p>This class generally need not be instantiated directly.
+Use <a class="reference internal" href="#RNS.Buffer.create_reader" title="RNS.Buffer.create_reader"><code class="xref py py-func docutils literal notranslate"><span class="pre">RNS.Buffer.create_reader()</span></code></a>,
+<a class="reference internal" href="#RNS.Buffer.create_writer" title="RNS.Buffer.create_writer"><code class="xref py py-func docutils literal notranslate"><span class="pre">RNS.Buffer.create_writer()</span></code></a>, and
+<a class="reference internal" href="#RNS.Buffer.create_bidirectional_buffer" title="RNS.Buffer.create_bidirectional_buffer"><code class="xref py py-func docutils literal notranslate"><span class="pre">RNS.Buffer.create_bidirectional_buffer()</span></code></a> functions
+to create buffered streams with optional callbacks.</p>
+<p>For additional information on the API of this
+object, see the Python documentation for
+<code class="docutils literal notranslate"><span class="pre">RawIOBase</span></code>.</p>
+</div></blockquote>
+<dl class="py method">
+<dt class="sig sig-object py" id="RNS.RawChannelWriter.__init__">
+<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stream_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#RNS.Channel.Channel" title="RNS.Channel.Channel"><span class="pre">Channel</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.RawChannelWriter.__init__" title="Permalink to this definition">#</a></dt>
+<dd><p>Create a raw channel writer.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters</dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>stream_id</strong> – remote stream id to sent do</p></li>
+<li><p><strong>channel</strong> – <code class="docutils literal notranslate"><span class="pre">Channel</span></code> object to send on</p></li>
+</ul>
+</dd>
+</dl>
+</dd></dl>
+
+</dd></dl>
+
 <p id="api-transport"><h3> Transport </h3></p>
 <dl class="py class">
 <dt class="sig sig-object py" id="RNS.Transport">
@@ -1484,7 +1820,7 @@ will announce it.</p>
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>
@@ -1588,11 +1924,13 @@ will announce it.</p>
 <li><a class="reference internal" href="#RNS.Link.STALE_TIME"><code class="docutils literal notranslate"><span class="pre">STALE_TIME</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.identify"><code class="docutils literal notranslate"><span class="pre">identify()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.request"><code class="docutils literal notranslate"><span class="pre">request()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Link.get_establishment_rate"><code class="docutils literal notranslate"><span class="pre">get_establishment_rate()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.no_inbound_for"><code class="docutils literal notranslate"><span class="pre">no_inbound_for()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.no_outbound_for"><code class="docutils literal notranslate"><span class="pre">no_outbound_for()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.inactive_for"><code class="docutils literal notranslate"><span class="pre">inactive_for()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.get_remote_identity"><code class="docutils literal notranslate"><span class="pre">get_remote_identity()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.teardown"><code class="docutils literal notranslate"><span class="pre">teardown()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Link.get_channel"><code class="docutils literal notranslate"><span class="pre">get_channel()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.set_link_closed_callback"><code class="docutils literal notranslate"><span class="pre">set_link_closed_callback()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.set_packet_callback"><code class="docutils literal notranslate"><span class="pre">set_packet_callback()</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Link.set_resource_callback"><code class="docutils literal notranslate"><span class="pre">set_resource_callback()</span></code></a></li>
@@ -1622,6 +1960,37 @@ will announce it.</p>
 <li><a class="reference internal" href="#RNS.Resource.is_compressed"><code class="docutils literal notranslate"><span class="pre">is_compressed()</span></code></a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#RNS.Channel.Channel"><code class="docutils literal notranslate"><span class="pre">Channel</span></code></a><ul>
+<li><a class="reference internal" href="#RNS.Channel.Channel.register_message_type"><code class="docutils literal notranslate"><span class="pre">register_message_type()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Channel.Channel.add_message_handler"><code class="docutils literal notranslate"><span class="pre">add_message_handler()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Channel.Channel.remove_message_handler"><code class="docutils literal notranslate"><span class="pre">remove_message_handler()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Channel.Channel.is_ready_to_send"><code class="docutils literal notranslate"><span class="pre">is_ready_to_send()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Channel.Channel.send"><code class="docutils literal notranslate"><span class="pre">send()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Channel.Channel.MDU"><code class="docutils literal notranslate"><span class="pre">MDU</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#RNS.MessageBase"><code class="docutils literal notranslate"><span class="pre">MessageBase</span></code></a><ul>
+<li><a class="reference internal" href="#RNS.MessageBase.MSGTYPE"><code class="docutils literal notranslate"><span class="pre">MSGTYPE</span></code></a></li>
+<li><a class="reference internal" href="#RNS.MessageBase.pack"><code class="docutils literal notranslate"><span class="pre">pack()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.MessageBase.unpack"><code class="docutils literal notranslate"><span class="pre">unpack()</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#RNS.Buffer"><code class="docutils literal notranslate"><span class="pre">Buffer</span></code></a><ul>
+<li><a class="reference internal" href="#RNS.Buffer.create_reader"><code class="docutils literal notranslate"><span class="pre">create_reader()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Buffer.create_writer"><code class="docutils literal notranslate"><span class="pre">create_writer()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.Buffer.create_bidirectional_buffer"><code class="docutils literal notranslate"><span class="pre">create_bidirectional_buffer()</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#RNS.RawChannelReader"><code class="docutils literal notranslate"><span class="pre">RawChannelReader</span></code></a><ul>
+<li><a class="reference internal" href="#RNS.RawChannelReader.__init__"><code class="docutils literal notranslate"><span class="pre">__init__()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.RawChannelReader.add_ready_callback"><code class="docutils literal notranslate"><span class="pre">add_ready_callback()</span></code></a></li>
+<li><a class="reference internal" href="#RNS.RawChannelReader.remove_ready_callback"><code class="docutils literal notranslate"><span class="pre">remove_ready_callback()</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#RNS.RawChannelWriter"><code class="docutils literal notranslate"><span class="pre">RawChannelWriter</span></code></a><ul>
+<li><a class="reference internal" href="#RNS.RawChannelWriter.__init__"><code class="docutils literal notranslate"><span class="pre">__init__()</span></code></a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#RNS.Transport"><code class="docutils literal notranslate"><span class="pre">Transport</span></code></a><ul>
 <li><a class="reference internal" href="#RNS.Transport.PATHFINDER_M"><code class="docutils literal notranslate"><span class="pre">PATHFINDER_M</span></code></a></li>
 <li><a class="reference internal" href="#RNS.Transport.register_announce_handler"><code class="docutils literal notranslate"><span class="pre">register_announce_handler()</span></code></a></li>

docs/manual/search.html

@@ -4,7 +4,7 @@
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="#" />
 
-    <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/><title>Search - Reticulum Network Stack 0.4.0 beta documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/><title>Search - Reticulum Network Stack 0.5.0 beta documentation</title><link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
@@ -138,7 +138,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -164,7 +164,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="#" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -241,7 +241,7 @@
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>

docs/manual/support.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="API Reference" href="reference.html" /><link rel="prev" title="Code Examples" href="examples.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>Support Reticulum - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>Support Reticulum - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -288,7 +288,7 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>

docs/manual/understanding.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Communications Hardware" href="hardware.html" /><link rel="prev" title="Using Reticulum on Your System" href="using.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>Understanding Reticulum - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>Understanding Reticulum - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -337,12 +337,12 @@ needs to be purchased.</p>
 </section>
 <section id="introduction-basic-functionality">
 <span id="understanding-basicfunctionality"></span><h2>Introduction &amp; Basic Functionality<a class="headerlink" href="#introduction-basic-functionality" title="Permalink to this heading">#</a></h2>
-<p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
+<p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at its
 core a <em>message oriented</em> system. It is suited for both local point-to-point or point-to-multipoint
 scenarios where all nodes are within range of each other, as well as scenarios where packets need
 to be transported over multiple hops in a complex network to reach the recipient.</p>
 <p>Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
-Reticulum uses the singular concept of <em>destinations</em>. Any application using Reticulum as it’s
+Reticulum uses the singular concept of <em>destinations</em>. Any application using Reticulum as its
 networking stack will need to create one or more destinations to receive data, and know the
 destinations it needs to send data to.</p>
 <p>All destinations in Reticulum are _represented_ as a 16 byte hash. This hash is derived from truncating a full
@@ -442,7 +442,7 @@ addressable, because their public keys will differ.</p></li>
 </ul>
 <p>In actual use of <em>single</em> destination naming, it is advisable not to use any uniquely identifying
 features in aspect naming. Aspect names should be general terms describing what kind of destination
-is represented. The uniquely identifying aspect is always achieved by the appending the public key,
+is represented. The uniquely identifying aspect is always achieved by appending the public key,
 which expands the destination into a uniquely identifiable one. Reticulum does this automatically.</p>
 <p>Any destination on a Reticulum network can be addressed and reached simply by knowing its
 destination hash (and public key, but if the public key is not known, it can be requested from the
@@ -468,7 +468,7 @@ indirectly, but must first be established through a <em>single</em> destination.
 </dl>
 </li>
 </ul>
-<p>To communicate with a <em>single</em> destination, you need to know it’s public key. Any method for
+<p>To communicate with a <em>single</em> destination, you need to know its public key. Any method for
 obtaining the public key is valid, but Reticulum includes a simple mechanism for making other
 nodes aware of your destinations public key, called the <em>announce</em>. It is also possible to request
 an unknown public key from the network, as all transport instances serve as a distributed ledger
@@ -509,7 +509,7 @@ certain pattern. This will be detailed in the section
 protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
 This limitation does not exist in Reticulum, and any destination is <em>completely portable</em> over the entire topography
 of the network, and <em>can even be moved to other Reticulum networks</em> than the one it was created in, and
-still become reachable. To update it’s reachability, a destination simply needs to send an announce on any
+still become reachable. To update its reachability, a destination simply needs to send an announce on any
 networks it is part of. After a short while, it will be globally reachable in the network.</p>
 <p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p>
 </section>
@@ -565,7 +565,7 @@ is the default setting.</p>
 </section>
 <section id="the-announce-mechanism-in-detail">
 <span id="understanding-announce"></span><h3>The Announce Mechanism in Detail<a class="headerlink" href="#the-announce-mechanism-in-detail" title="Permalink to this heading">#</a></h3>
-<p>When an <em>announce</em> for a destination is transmitted by from a Reticulum instance, it will be forwarded by
+<p>When an <em>announce</em> for a destination is transmitted by a Reticulum instance, it will be forwarded by
 any transport node receiving it, but according to some specific rules:</p>
 <ul>
 <li><div class="line-block">
@@ -590,7 +590,7 @@ announces is set at 2%, but can be configured on a per-interface basis.</div>
 </li>
 <li><div class="line-block">
 <div class="line">If any given interface does not have enough bandwidth available for retransmitting the announce,
-the announce will be assigned a priority inversely proportional to it’s hop count, and be inserted
+the announce will be assigned a priority inversely proportional to its hop count, and be inserted
 into a queue managed by the interface.</div>
 </div>
 </li>
@@ -639,7 +639,7 @@ expect. Reticulum offers two ways to do this.</p>
 <li><div class="line-block">
 <div class="line">A packet is always created with an associated destination and some payload data. When the packet is sent
 to a <em>single</em> destination type, Reticulum will automatically create an ephemeral encryption key, perform
-an ECDH key exchange with the destinations public key, and encrypt the information.</div>
+an ECDH key exchange with the destination’s public key, and encrypt the information.</div>
 </div>
 </li>
 <li><div class="line-block">
@@ -665,8 +665,8 @@ packet.</div>
 <li><div class="line-block">
 <div class="line">Once the packet has been received and decrypted by the addressed destination, that destination can opt
 to <em>prove</em> its receipt of the packet. It does this by calculating the SHA-256 hash of the received packet,
-and signing this hash with it’s Ed25519 signing key. Transport nodes in the network can then direct this
-<em>proof</em> back to the packets origin, where the signature can be verified against the destinations known
+and signing this hash with its Ed25519 signing key. Transport nodes in the network can then direct this
+<em>proof</em> back to the packets origin, where the signature can be verified against the destination’s known
 public signing key.</div>
 </div>
 </li>
@@ -689,7 +689,7 @@ forward the packet will take note of this <em>link request</em>.</div>
 </li>
 <li><div class="line-block">
 <div class="line">Second, if the destination accepts the <em>link request</em> , it will send back a packet that proves the
-authenticity of it’s identity (and the receipt of the link request) to the initiating node. All
+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 <em>link</em> throughout the network.</div>
 </div>
@@ -1005,7 +1005,7 @@ proof           11
 |               | |               | |               | |    |
 00000000 00000111 [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
 || | | |    |
-|| | | |    +-- Hops             = 0
+|| | | |    +-- Hops             = 7
 || | | +------- Packet Type      = DATA
 || | +--------- Destination Type = SINGLE
 || +----------- Propagation Type = BROADCAST
@@ -1020,7 +1020,7 @@ proof           11
 |               | |             | |               | |               | |    |
 10000000 00000111 [IFAC, N bytes] [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
 || | | |    |
-|| | | |    +-- Hops             = 0
+|| | | |    +-- Hops             = 7
 || | | +------- Packet Type      = DATA
 || | +--------- Destination Type = SINGLE
 || +----------- Propagation Type = BROADCAST
@@ -1126,7 +1126,7 @@ those risks are acceptable to you.</p>
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>

docs/manual/using.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Understanding Reticulum" href="understanding.html" /><link rel="prev" title="Getting Started Fast" href="gettingstartedfast.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>Using Reticulum on Your System - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>Using Reticulum on Your System - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -224,8 +224,9 @@
           <section id="using-reticulum-on-your-system">
 <span id="using-main"></span><h1>Using Reticulum on Your System<a class="headerlink" href="#using-reticulum-on-your-system" title="Permalink to this heading">#</a></h1>
 <p>Reticulum is not installed as a driver or kernel module, as one might expect
-of a networking stack. Instead, Reticulum is distributed as a Python module.
-This means that no special privileges are required to install or use it. It
+of a networking stack. Instead, Reticulum is distributed as a Python module,
+containing the networking core, and a set of utility and daemon programs.</p>
+<p>This means that no special privileges are required to install or use it. It
 is also very light-weight, and easy to transfer to, and install on new systems.</p>
 <p>When you have Reticulum installed, any program or application that uses Reticulum
 will automatically load and initialise Reticulum when it starts, if it is not
@@ -233,8 +234,8 @@ already running.</p>
 <p>In many cases, this approach is sufficient. When any program needs to use
 Reticulum, it is loaded, initialised, interfaces are brought up, and the
 program can now communicate over any Reticulum networks available. If another
-program starts up and also wants access to the same Reticulum network, the
-instance is simply shared. This works for any number of programs running
+program starts up and also wants access to the same Reticulum network, the already
+running instance is simply shared. This works for any number of programs running
 concurrently, and is very easy to use, but depending on your use case, there
 are other options.</p>
 <section id="configuration-data">
@@ -556,7 +557,7 @@ execute commands on remote systems over Reticulum, and to view returned command
 output.</p>
 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnx on the listening system, specifying which identities
 # are allowed to execute commands
-rncp --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
 
 # From another system, run a command
 rnx 7a55144adf826958a9529a3bcf08b149 &quot;cat /proc/cpuinfo&quot;
@@ -605,6 +606,47 @@ optional arguments:
 </pre></div>
 </div>
 </section>
+<section id="the-rnodeconf-utility">
+<h3>The rnodeconf Utility<a class="headerlink" href="#the-rnodeconf-utility" title="Permalink to this heading">#</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">rnodeconf</span></code> utility allows you to inspect and configure existing <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a>, and
+to create and provision new <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a> from any supported hardware devices.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-C] [-N] [-T] [-b] [-B] [-p] [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [--version] [port]
+
+RNode Configuration and firmware utility. This program allows you to change various settings and startup modes of RNode. It can also install, flash and update the firmware on supported devices.
+
+positional arguments:
+  port                  serial port where RNode is attached
+
+options:
+  -h, --help            show this help message and exit
+  -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
+  --nocheck             Don&#39;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
+  -C, --clear-cache     Clear locally cached firmware files
+  -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
+  --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)
+  --eeprom-backup       Backup EEPROM to file
+  --eeprom-dump         Dump EEPROM to console
+  --eeprom-wipe         Unlock and wipe EEPROM
+  --version             Print program version and exit
+</pre></div>
+</div>
+<p>For more information on how to create your own RNodes, please read the <a class="reference internal" href="hardware.html#rnode-creating"><span class="std std-ref">Creating RNodes</span></a>
+section of this manual.</p>
+</section>
 </section>
 <section id="improving-system-configuration">
 <h2>Improving System Configuration<a class="headerlink" href="#improving-system-configuration" title="Permalink to this heading">#</a></h2>
@@ -715,7 +757,7 @@ WantedBy=multi-user.target
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>
@@ -751,6 +793,7 @@ WantedBy=multi-user.target
 <li><a class="reference internal" href="#the-rnprobe-utility">The rnprobe Utility</a></li>
 <li><a class="reference internal" href="#the-rncp-utility">The rncp Utility</a></li>
 <li><a class="reference internal" href="#the-rnx-utility">The rnx Utility</a></li>
+<li><a class="reference internal" href="#the-rnodeconf-utility">The rnodeconf Utility</a></li>
 </ul>
 </li>
 <li><a class="reference internal" href="#improving-system-configuration">Improving System Configuration</a><ul>

docs/manual/whatis.html

@@ -6,7 +6,7 @@
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Getting Started Fast" href="gettingstartedfast.html" /><link rel="prev" title="Reticulum Network Stack Manual" href="index.html" />
 
     <meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
-        <title>What is Reticulum? - Reticulum Network Stack 0.4.0 beta documentation</title>
+        <title>What is Reticulum? - Reticulum Network Stack 0.5.0 beta documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
     <link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
@@ -141,7 +141,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="index.html"><div class="brand">Reticulum Network Stack 0.4.0 beta documentation</div></a>
+      <a href="index.html"><div class="brand">Reticulum Network Stack 0.5.0 beta documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -167,7 +167,7 @@
     <img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
   </div>
   
-  <span class="sidebar-brand-text">Reticulum Network Stack 0.4.0 beta documentation</span>
+  <span class="sidebar-brand-text">Reticulum Network Stack 0.5.0 beta documentation</span>
   
 </a><form class="sidebar-search-container" method="get" action="search.html" role="search">
   <input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
@@ -354,10 +354,10 @@ network, and vice versa.</p>
 <h2>Caveat Emptor<a class="headerlink" href="#caveat-emptor" title="Permalink to this heading">#</a></h2>
 <p>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 been externally security audited, and there could very well be
+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, or help sponsor an audit, please do get in touch.</p>
+want to help out with this, or can help sponsor an audit, please do get in touch.</p>
 </section>
 </section>
 
@@ -390,7 +390,7 @@ want to help out, or help sponsor an audit, please do get in touch.</p>
         <div class="bottom-of-page">
           <div class="left-details">
             <div class="copyright">
-                Copyright &#169; 2022, Mark Qvist
+                Copyright &#169; 2023, Mark Qvist
             </div>
             Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 
             <a href="https://github.com/pradyunsg/furo">Furo</a>

docs/source/conf.py

@@ -10,7 +10,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 
 # -- Project information -----------------------------------------------------
 project = 'Reticulum Network Stack'
-copyright = '2022, Mark Qvist'
+copyright = '2023, Mark Qvist'
 author = 'Mark Qvist'
 
 # The full version, including alpha/beta/rc tags

docs/source/examples.rst

@@ -92,6 +92,28 @@ The *Request* example explores sendig requests and receiving responses.
 
 This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py>`_.
 
+.. _example-channel:
+
+Channel
+=======
+
+The *Channel* example explores using a ``Channel`` to send structured
+data between peers of a ``Link``.
+
+.. literalinclude:: ../../Examples/Channel.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Channel.py>`_.
+
+Buffer
+======
+
+The *Buffer* example explores using buffered readers and writers to send
+binary data between peers of a ``Link``.
+
+.. literalinclude:: ../../Examples/Buffer.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Buffer.py>`_.
+
 .. _example-filetransfer:
 
 Filetransfer

docs/source/forhumans.rst

@@ -0,0 +1,4 @@
+********************************************
+An Explanation of Reticulum for Human Beings
+********************************************
+

docs/source/gettingstartedfast.rst

@@ -7,22 +7,48 @@ you want to do. This guide will outline sensible starting paths for different
 scenarios.
 
 
+Standalone Reticulum Installation
+=============================================
+If you simply want to install Reticulum and related utilities on a system,
+the easiest way is via ``pip``:
+
+.. code::
+
+   pip install rns
+
+If you no not already have pip installed, you can install it using the package manager
+of your system with a command like ``sudo apt install python3-pip``,
+``sudo pamac install python-pip`` or similar. You can also dowload the Reticulum release
+wheels from GitHub, or other release channels, and install them offline using ``pip``:
+
+.. code::
+
+   pip install ./rns-0.4.6-py3-none-any.whl
+
+
 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
-over even extremely low-bandwidth Reticulum networks.
+programs exist that allow basic communication and a range of 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 completely
-over local WiFi, wired Ethernet, the Internet, or any combination.
+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.
+
 Nomad Network
 ^^^^^^^^^^^^^
 
@@ -44,7 +70,7 @@ You can install Nomad Network via pip:
 .. code::
 
    # Install ...
-   pip3 install nomadnet
+   pip install nomadnet
 
    # ... and run
    nomadnet
@@ -61,12 +87,22 @@ 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 and macOS.
 
-.. image:: screenshots/sideband_1.png
-    :align: center
-    :target: _images/sideband_1.png
+.. only:: html
 
-Sideband is currently in the early stages of development, but already provides basic
-communication features, and interoperates with Nomad Network, or any other LXMF client.
+  .. image:: screenshots/sideband_devices.webp
+      :align: center
+      :target: _images/sideband_devices.webp
+
+.. only:: latexpdf
+
+  .. 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.
 
 Using the Included Utilities
 =============================================
@@ -86,8 +122,8 @@ Creating a Network With Reticulum
 =============================================
 To create a network, you will need to specify one or more *interfaces* for
 Reticulum to use. This is done in the Reticulum configuration file, which by
-default is located at ``~/.reticulum/config``. You can edit this file by hand,
-or use the interactive ``rnsconfig`` utility. 
+default is located at ``~/.reticulum/config``. You can get an example
+configuration file with all options via ``rnsd --exampleconfig``.
 
 When Reticulum is started for the first time, it will create a default
 configuration file, with one active interface. This default interface uses
@@ -168,7 +204,7 @@ by adding one of the following interfaces to your ``.reticulum/config`` file:
     target_port = 4965
 
   # TCP/IP interface to the Frankfurt hub
-  [[RNS Testnet Dublin]]
+  [[RNS Testnet Frankfurt]]
     type = TCPClientInterface
     enabled = yes
     target_host = frankfurt.connect.reticulum.network
@@ -205,7 +241,7 @@ chapter for a guide. If you prefer purchasing a ready-made unit, you can refer t
 refer to these additional external resources:
 
 * `How To Make Your Own RNodes <https://unsigned.io/how-to-make-your-own-rnodes/>`_
-* `Installing RNode Firmware on Compatible LoRa Devices <https://unsigned.io/installing-rnode-firmware-on-t-beam-and-lora32-devices/>`_
+* `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/>`_
 
@@ -272,7 +308,7 @@ don't use pip, but try this recipe:
 
     # Run the example in client mode to "ping" the server.
     # Replace the hash below with the actual destination hash of your server.
-    python3 Examples/Echo.py 3e12fc71692f8ec47bc5
+    python3 Examples/Echo.py 174a64852a75682259ad8b921b8bf416
 
     # Have a look at another example
     python3 Examples/Filetransfer.py -h
@@ -287,7 +323,7 @@ or ask one of the developers or maintainers for a good place to start.
 Reticulum on ARM64
 ==============================================
 On some architectures, including ARM64, not all dependencies have precompiled
-binaries. On such systems, you will need to install ``python3-dev`` before
+binaries. On such systems, you may need to install ``python3-dev`` before
 installing Reticulum or programs that depend on Reticulum.
 
 .. code::
@@ -300,6 +336,12 @@ installing Reticulum or programs that depend on Reticulum.
    python3 -m pip install rns
 
 
+Reticulum on Raspberry Pi
+==============================================
+It is currently recommended to use a 64-bit version of the Raspberry Pi OS
+if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions
+don't always have packages available for some dependencies.
+
 Reticulum on Android
 ==============================================
 Reticulum can be used on Android in different ways. The easiest way to get
@@ -313,12 +355,31 @@ Termux is a terminal emulator and Linux environment for Android based devices,
 which includes the ability to use many different programs and libraries,
 including Reticulum.
 
-Since the Python cryptography.io module does not offer pre-built wheels for
-Android, the standard one-line install of Reticulum does not work on Android,
-and a few extra commands are required.
+To use Reticulum within the Termux environment, you will need to install
+``python`` and the ``python-cryptography`` library using ``pkg``, the package-manager
+build into Termux. After that, you can use ``pip`` to install Reticulum.
 
 From within Termux, execute the following:
 
+.. code::
+
+    # First, make sure indexes and packages are up to date.
+    pkg update
+    pkg upgrade
+
+    # Then install python and the cryptography library.
+    pkg install python python-cryptography
+
+    # Make sure pip is up to date, and install the wheel module.
+    pip install wheel pip --upgrade
+
+    # Install Reticulum
+    pip install rns
+
+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::
 
     # First, make sure indexes and packages are up to date.
@@ -329,7 +390,7 @@ From within Termux, execute the following:
     pkg install python build-essential openssl libffi rust
 
     # Make sure pip is up to date, and install the wheel module.
-    pip3 install wheel pip --upgrade
+    pip install wheel pip --upgrade
 
     # To allow the installer to build the cryptography module,
     # we need to let it know what platform we are compiling for:
@@ -338,11 +399,11 @@ From within Termux, execute the following:
     # Start the install process for the cryptography module.
     # Depending on your device, this can take several minutes,
     # since the module must be compiled locally on your device.
-    pip3 install cryptography
+    pip install cryptography
 
     # If the above installation succeeds, you can now install
     # Reticulum and any related software
-    pip3 install rns
+    pip install rns
 
 It is also possible to include Reticulum in apps compiled and distributed as
 Android APKs. A detailed tutorial and example source code will be included
@@ -355,7 +416,8 @@ install one or more dependencies
 
 On more unusual systems, and in some rare cases, it might not be possible to
 install or even compile one or more of the above modules. In such situations,
-you can use the ``rnspure`` package instead of the ``rns`` package. The ``rnspure``
+you can use the ``rnspure`` package instead of the ``rns`` package, or use ``pip``
+with the ``--no-dependencies`` command-line option. The ``rnspure``
 package requires no external dependencies for installation. Please note that the
 actual contents of the ``rns`` and ``rnspure`` packages are *completely identical*.
 The only difference is that the ``rnspure`` package lists no dependencies required

docs/source/hardware.rst

@@ -160,12 +160,13 @@ Installation
 
 Once you have obtained compatible boards, you can install the `RNode Firmware <https://github.com/markqvist/RNode_Firmware>`_
 using the `RNode Configuration Utility <https://github.com/markqvist/rnodeconfigutil>`_.
-Make sure that ``Python3`` and ``pip`` is installed on your system, and then install
-the config utility with ``pip``:
+If you have installed Reticulum on your system, the ``rnodeconf`` program will already be
+available. If not, make sure that ``Python3`` and ``pip`` is installed on your system, and
+then install Reticulum with with ``pip``:
 
 .. code::
 
-   pip3 install rnodeconf
+   pip install rns
 
 Once installation has completed, it is time to start installing the firmware on your
 devices. Run ``rnodeconf`` in auto-install mode like so:
@@ -176,12 +177,7 @@ devices. Run ``rnodeconf`` in auto-install mode like so:
 
 The utility will guide you through the installation process by asking a series of
 questions about your hardware. Simply follow the guide, and the utility will
-auto-install and configure your devices
-
-**Important Note!** It is currently recommended to use the v1.x line of the RNode firmware,
-even though the v2.x line is available for early testing. The v2.x line should still be
-considered an experimental pre-release. Only use the v2.x firmware line if you want to test
-out the absolutely newest version, and don't care about stability.
+auto-install and configure your devices.
 
 .. _rnode-usage:
 

docs/source/index.rst

@@ -5,6 +5,10 @@ This manual aims to provide you with all the information you need to
 understand Reticulum, build networks or develop programs using it, or
 to participate in the development of Reticulum itself.
 
+.. only:: html
+
+This manual is also available in `PDF <https://github.com/markqvist/Reticulum/releases/latest/download/Reticulum.Manual.pdf>`_ and `EPUB <https://github.com/markqvist/Reticulum/releases/latest/download/Reticulum.Manual.epub>`_ formats.
+
 .. only:: html
 
    Table Of Contents

docs/source/reference.rst

@@ -121,6 +121,76 @@ This chapter lists and explains all classes exposed by the Reticulum Network Sta
 .. autoclass:: RNS.Resource(data, link, advertise=True, auto_compress=True, callback=None, progress_callback=None, timeout=None)
    :members:
 
+.. _api-channel:
+
+.. only:: html
+
+   |start-h3| Channel |end-h3|
+
+.. only:: latex
+
+   Channel
+   -------
+
+.. autoclass:: RNS.Channel.Channel()
+   :members:
+
+.. _api-messsagebase:
+
+.. only:: html
+
+   |start-h3| MessageBase |end-h3|
+
+.. only:: latex
+
+   MessageBase
+   -----------
+
+.. autoclass:: RNS.MessageBase()
+   :members:
+
+.. _api-buffer:
+
+.. only:: html
+
+   |start-h3| Buffer |end-h3|
+
+.. only:: latex
+
+   Buffer
+   ------
+
+.. autoclass:: RNS.Buffer
+   :members:
+
+.. _api-rawchannelreader:
+
+.. only:: html
+
+   |start-h3| RawChannelReader |end-h3|
+
+.. only:: latex
+
+   RawChannelReader
+   ----------------
+
+.. autoclass:: RNS.RawChannelReader
+   :members: __init__, add_ready_callback, remove_ready_callback
+
+.. _api-rawchannelwriter:
+
+.. only:: html
+
+   |start-h3| RawChannelWriter |end-h3|
+
+.. only:: latex
+
+   RawChannelWriter
+   ----------------
+
+.. autoclass:: RNS.RawChannelWriter
+   :members: __init__
+
 .. _api-transport:
 
 .. only:: html

docs/source/understanding.rst

@@ -107,13 +107,13 @@ guide the design of Reticulum:
 Introduction & Basic Functionality
 ==================================
 
-Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
+Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at its
 core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint
 scenarios where all nodes are within range of each other, as well as scenarios where packets need
 to be transported over multiple hops in a complex network to reach the recipient.
 
 Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
-Reticulum uses the singular concept of *destinations*. Any application using Reticulum as it’s
+Reticulum uses the singular concept of *destinations*. Any application using Reticulum as its
 networking stack will need to create one or more destinations to receive data, and know the
 destinations it needs to send data to.
 
@@ -220,7 +220,7 @@ packet.
 
 In actual use of *single* destination naming, it is advisable not to use any uniquely identifying
 features in aspect naming. Aspect names should be general terms describing what kind of destination
-is represented. The uniquely identifying aspect is always achieved by the appending the public key,
+is represented. The uniquely identifying aspect is always achieved by appending the public key,
 which expands the destination into a uniquely identifiable one. Reticulum does this automatically.
 
 Any destination on a Reticulum network can be addressed and reached simply by knowing its
@@ -239,7 +239,7 @@ To recap, the different destination types should be used in the following situat
 * **Plain**
     When plain-text communication is desirable, for example when broadcasting information, or for local discovery purposes.
 
-To communicate with a *single* destination, you need to know it’s public key. Any method for
+To communicate with a *single* destination, you need to know its public key. Any method for
 obtaining the public key is valid, but Reticulum includes a simple mechanism for making other
 nodes aware of your destinations public key, called the *announce*. It is also possible to request
 an unknown public key from the network, as all transport instances serve as a distributed ledger
@@ -287,7 +287,7 @@ In Reticulum, destinations are allowed to move around the network at will. This
 protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
 This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography
 of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and
-still become reachable. To update it's reachability, a destination simply needs to send an announce on any
+still become reachable. To update its reachability, a destination simply needs to send an announce on any
 networks it is part of. After a short while, it will be globally reachable in the network.
 
 Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic.
@@ -368,7 +368,7 @@ If it is a *Transport Node*, it should be given the configuration directive ``en
 The Announce Mechanism in Detail
 --------------------------------
 
-When an *announce* for a destination is transmitted by from a Reticulum instance, it will be forwarded by
+When an *announce* for a destination is transmitted by a Reticulum instance, it will be forwarded by
 any transport node receiving it, but according to some specific rules:
 
 
@@ -385,7 +385,7 @@ any transport node receiving it, but according to some specific rules:
     announces is set at 2%, but can be configured on a per-interface basis.
 
 * | If any given interface does not have enough bandwidth available for retransmitting the announce,
-    the announce will be assigned a priority inversely proportional to it's hop count, and be inserted
+    the announce will be assigned a priority inversely proportional to its hop count, and be inserted
     into a queue managed by the interface.
 
 * | When the interface has bandwidth available for processing an announce, it will prioritise announces
@@ -431,7 +431,7 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
 
 * | A packet is always created with an associated destination and some payload data. When the packet is sent
     to a *single* destination type, Reticulum will automatically create an ephemeral encryption key, perform
-    an ECDH key exchange with the destinations public key, and encrypt the information.
+    an ECDH key exchange with the destination's public key, 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
@@ -447,8 +447,8 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
 
 * | Once the packet has been received and decrypted by the addressed destination, that destination can opt
     to *prove* its receipt of the packet. It does this by calculating the SHA-256 hash of the received packet,
-    and signing this hash with it's Ed25519 signing key. Transport nodes in the network can then direct this
-    *proof* back to the packets origin, where the signature can be verified against the destinations known
+    and signing this hash with its Ed25519 signing key. Transport nodes in the network can then direct this
+    *proof* back to the packets origin, where the signature can be verified against the destination's known
     public signing key.
 
 * | In case the packet is addressed to a *group* destination type, the packet will be encrypted with the
@@ -465,7 +465,7 @@ For exchanges of larger amounts of data, or when longer sessions of bidirectiona
     forward the packet will take note of this *link request*.
 
 * | Second, if the destination accepts the *link request* , it will send back a packet that proves the
-    authenticity of it’s identity (and the receipt of the link request) to the initiating node. All
+    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.
 
@@ -771,7 +771,7 @@ Wire Format
     |               | |               | |               | |    |
     00000000 00000111 [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
     || | | |    |
-    || | | |    +-- Hops             = 0
+    || | | |    +-- Hops             = 7
     || | | +------- Packet Type      = DATA
     || | +--------- Destination Type = SINGLE
     || +----------- Propagation Type = BROADCAST
@@ -786,7 +786,7 @@ Wire Format
     |               | |             | |               | |               | |    |
     10000000 00000111 [IFAC, N bytes] [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
     || | | |    |
-    || | | |    +-- Hops             = 0
+    || | | |    +-- Hops             = 7
     || | | +------- Packet Type      = DATA
     || | +--------- Destination Type = SINGLE
     || +----------- Propagation Type = BROADCAST

docs/source/using.rst

@@ -5,7 +5,9 @@ Using Reticulum on Your System
 ******************************
 
 Reticulum is not installed as a driver or kernel module, as one might expect
-of a networking stack. Instead, Reticulum is distributed as a Python module.
+of a networking stack. Instead, Reticulum is distributed as a Python module, 
+containing the networking core, and a set of utility and daemon programs.
+
 This means that no special privileges are required to install or use it. It
 is also very light-weight, and easy to transfer to, and install on new systems.
 
@@ -16,8 +18,8 @@ already running.
 In many cases, this approach is sufficient. When any program needs to use
 Reticulum, it is loaded, initialised, interfaces are brought up, and the
 program can now communicate over any Reticulum networks available. If another
-program starts up and also wants access to the same Reticulum network, the
-instance is simply shared. This works for any number of programs running
+program starts up and also wants access to the same Reticulum network, the already
+running instance is simply shared. This works for any number of programs running
 concurrently, and is very easy to use, but depending on your use case, there
 are other options.
 
@@ -375,7 +377,7 @@ output.
 
   # Run rnx on the listening system, specifying which identities
   # are allowed to execute commands
-  rncp --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+  rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
 
   # From another system, run a command 
   rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
@@ -425,6 +427,50 @@ You can specify as many allowed senders as needed, or completely disable authent
     --version             show program's version number and exit
 
 
+The rnodeconf Utility
+=====================
+
+The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and
+to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices.
+
+.. code:: text
+
+  usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-C] [-N] [-T] [-b] [-B] [-p] [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [--version] [port]
+
+  RNode Configuration and firmware utility. This program allows you to change various settings and startup modes of RNode. It can also install, flash and update the firmware on supported devices.
+
+  positional arguments:
+    port                  serial port where RNode is attached
+
+  options:
+    -h, --help            show this help message and exit
+    -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
+    --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
+    -C, --clear-cache     Clear locally cached firmware files
+    -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
+    --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)
+    --eeprom-backup       Backup EEPROM to file
+    --eeprom-dump         Dump EEPROM to console
+    --eeprom-wipe         Unlock and wipe EEPROM
+    --version             Print program version and exit
+
+For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>`
+section of this manual.
+
 Improving System Configuration
 ------------------------------
 
@@ -519,4 +565,4 @@ If you want to automatically start ``rnsd`` at boot, run:
 
 .. code:: text
 
-  sudo systemctl enable rnsd
+  sudo systemctl enable rnsd

docs/source/whatis.rst

@@ -162,7 +162,7 @@ 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 been externally security audited, and there could very well be
+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, or help sponsor an audit, please do get in touch.
+want to help out with this, or can help sponsor an audit, please do get in touch.

setup.py

@@ -22,6 +22,9 @@ else:
     pkg_name = "rns"
     requirements = ['cryptography>=3.4.7', 'pyserial>=3.5', 'netifaces']
 
+excluded_modules = exclude=["tests.*", "tests"]
+packages = setuptools.find_packages(exclude=excluded_modules)
+
 setuptools.setup(
     name=pkg_name,
     version=__version__,
@@ -31,7 +34,7 @@ setuptools.setup(
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://reticulum.network/",
-    packages=setuptools.find_packages(),
+    packages=packages,
     classifiers=[
         "Programming Language :: Python :: 3",
         "License :: OSI Approved :: MIT License",
@@ -43,6 +46,7 @@ setuptools.setup(
             'rnstatus=RNS.Utilities.rnstatus:main',
             'rnprobe=RNS.Utilities.rnprobe:main',
             'rnpath=RNS.Utilities.rnpath:main',
+            'rnid=RNS.Utilities.rnid:main',
             'rncp=RNS.Utilities.rncp:main',
             'rnx=RNS.Utilities.rnx:main',
             'rnodeconf=RNS.Utilities.rnodeconf:main',

tests/all.py

@@ -4,6 +4,7 @@ from .hashes import TestSHA256
 from .hashes import TestSHA512
 from .identity import TestIdentity
 from .link import TestLink
+from .channel import TestChannel
 
 if __name__ == '__main__':
     unittest.main(verbosity=2)

tests/channel.py

@@ -0,0 +1,503 @@
+from __future__ import annotations
+import threading
+import RNS
+from RNS.Channel import MessageState, ChannelOutletBase, Channel, MessageBase
+import RNS.Buffer
+from RNS.vendor import umsgpack
+from typing import Callable
+import contextlib
+import typing
+import types
+import time
+import uuid
+import unittest
+
+
+class Packet:
+    timeout = 1.0
+
+    def __init__(self, raw: bytes):
+        self.state = MessageState.MSGSTATE_NEW
+        self.raw = raw
+        self.packet_id = uuid.uuid4()
+        self.tries = 0
+        self.timeout_id = None
+        self.lock = threading.RLock()
+        self.instances = 0
+        self.timeout_callback: Callable[[Packet], None] | None = None
+        self.delivered_callback: Callable[[Packet], None] | None = None
+
+    def set_timeout(self, callback: Callable[[Packet], None] | None, timeout: float):
+        with self.lock:
+            if timeout is not None:
+                self.timeout = timeout
+            self.timeout_callback = callback
+
+
+    def send(self):
+        self.tries += 1
+        self.state = MessageState.MSGSTATE_SENT
+
+        def elapsed(timeout: float, timeout_id: uuid.uuid4):
+            with self.lock:
+                self.instances += 1
+            try:
+                time.sleep(timeout)
+                with self.lock:
+                    if self.timeout_id == timeout_id:
+                        self.timeout_id = None
+                        self.state = MessageState.MSGSTATE_FAILED
+                        if self.timeout_callback:
+                            self.timeout_callback(self)
+            finally:
+                with self.lock:
+                    self.instances -= 1
+
+        self.timeout_id = uuid.uuid4()
+        threading.Thread(target=elapsed, name="Packet Timeout", args=[self.timeout, self.timeout_id],
+                         daemon=True).start()
+
+    def clear_timeout(self):
+        self.timeout_id = None
+
+    def set_delivered_callback(self, callback: Callable[[Packet], None]):
+        self.delivered_callback = callback
+        
+    def delivered(self):
+        with self.lock:
+            self.state = MessageState.MSGSTATE_DELIVERED
+            self.timeout_id = None
+        if self.delivered_callback:
+            self.delivered_callback(self)
+
+
+class ChannelOutletTest(ChannelOutletBase):
+    def get_packet_state(self, packet: Packet) -> MessageState:
+        return packet.state
+
+    def set_packet_timeout_callback(self, packet: Packet, callback: Callable[[Packet], None] | None,
+                                    timeout: float | None = None):
+        packet.set_timeout(callback, timeout)
+
+    def set_packet_delivered_callback(self, packet: Packet, callback: Callable[[Packet], None] | None):
+        packet.set_delivered_callback(callback)
+
+    def get_packet_id(self, packet: Packet) -> any:
+        return packet.packet_id
+
+    def __init__(self, mdu: int, rtt: float):
+        self.link_id = uuid.uuid4()
+        self.timeout_callbacks = 0
+        self._mdu = mdu
+        self._rtt = rtt
+        self._usable = True
+        self.packets = []
+        self.lock = threading.RLock()
+        self.packet_callback: Callable[[ChannelOutletBase, bytes], None] | None = None
+
+    def send(self, raw: bytes) -> Packet:
+        with self.lock:
+            packet = Packet(raw)
+            packet.send()
+            self.packets.append(packet)
+            return packet
+
+    def resend(self, packet: Packet) -> Packet:
+        with self.lock:
+            packet.send()
+            return packet
+
+    @property
+    def mdu(self):
+        return self._mdu
+
+    @property
+    def rtt(self):
+        return self._rtt
+
+    @property
+    def is_usable(self):
+        return self._usable
+
+    def timed_out(self):
+        self.timeout_callbacks += 1
+
+    def __str__(self):
+        return str(self.link_id)
+
+
+class MessageTest(MessageBase):
+    MSGTYPE = 0xabcd
+
+    def __init__(self):
+        self.id = str(uuid.uuid4())
+        self.data = "test"
+        self.not_serialized = str(uuid.uuid4())
+
+    def pack(self) -> bytes:
+        return umsgpack.packb((self.id, self.data))
+
+    def unpack(self, raw):
+        self.id, self.data = umsgpack.unpackb(raw)
+
+
+class SystemMessage(MessageBase):
+    MSGTYPE = 0xf000
+
+    def pack(self) -> bytes:
+        return bytes()
+
+    def unpack(self, raw):
+        pass
+
+
+class ProtocolHarness(contextlib.AbstractContextManager):
+    def __init__(self, rtt: float):
+        self.outlet = ChannelOutletTest(mdu=500, rtt=rtt)
+        self.channel = Channel(self.outlet)
+        Packet.timeout = self.channel._get_packet_timeout_time(1)
+
+    def cleanup(self):
+        self.channel._shutdown()
+
+    def __exit__(self, __exc_type: typing.Type[BaseException], __exc_value: BaseException,
+                 __traceback: types.TracebackType) -> bool:
+        # self._log.debug(f"__exit__({__exc_type}, {__exc_value}, {__traceback})")
+        self.cleanup()
+        return False
+
+
+class TestChannel(unittest.TestCase):
+    def setUp(self) -> None:
+        print("")
+        self.rtt = 0.01
+        self.h = ProtocolHarness(self.rtt)
+
+    def tearDown(self) -> None:
+        self.h.cleanup()
+
+    def test_send_one_retry(self):
+        print("Channel test one retry")
+        message = MessageTest()
+
+        self.assertEqual(0, len(self.h.outlet.packets))
+
+        envelope = self.h.channel.send(message)
+
+        self.assertIsNotNone(envelope)
+        self.assertIsNotNone(envelope.raw)
+        self.assertEqual(1, len(self.h.outlet.packets))
+        self.assertIsNotNone(envelope.packet)
+        self.assertTrue(envelope in self.h.channel._tx_ring)
+        self.assertTrue(envelope.tracked)
+
+        packet = self.h.outlet.packets[0]
+
+        self.assertEqual(envelope.packet, packet)
+        self.assertEqual(1, envelope.tries)
+        self.assertEqual(1, packet.tries)
+        self.assertEqual(1, packet.instances)
+        self.assertEqual(MessageState.MSGSTATE_SENT, packet.state)
+        self.assertEqual(envelope.raw, packet.raw)
+
+        time.sleep(self.h.channel._get_packet_timeout_time(1) * 1.1)
+
+        self.assertEqual(1, len(self.h.outlet.packets))
+        self.assertEqual(2, envelope.tries)
+        self.assertEqual(2, packet.tries)
+        self.assertEqual(1, packet.instances)
+
+        time.sleep(self.h.channel._get_packet_timeout_time(2) * 1.1)
+
+        self.assertEqual(1, len(self.h.outlet.packets))
+        self.assertEqual(self.h.outlet.packets[0], packet)
+        self.assertEqual(3, envelope.tries)
+        self.assertEqual(3, packet.tries)
+        self.assertEqual(1, packet.instances)
+        self.assertEqual(MessageState.MSGSTATE_SENT, packet.state)
+
+        packet.delivered()
+
+        self.assertEqual(MessageState.MSGSTATE_DELIVERED, packet.state)
+
+        time.sleep(self.h.channel._get_packet_timeout_time(3) * 1.1)
+
+        self.assertEqual(1, len(self.h.outlet.packets))
+        self.assertEqual(3, envelope.tries)
+        self.assertEqual(3, packet.tries)
+        self.assertEqual(0, packet.instances)
+        self.assertFalse(envelope.tracked)
+
+    def test_send_timeout(self):
+        print("Channel test retry count exceeded")
+        message = MessageTest()
+
+        self.assertEqual(0, len(self.h.outlet.packets))
+
+        envelope = self.h.channel.send(message)
+
+        self.assertIsNotNone(envelope)
+        self.assertIsNotNone(envelope.raw)
+        self.assertEqual(1, len(self.h.outlet.packets))
+        self.assertIsNotNone(envelope.packet)
+        self.assertTrue(envelope in self.h.channel._tx_ring)
+        self.assertTrue(envelope.tracked)
+
+        packet = self.h.outlet.packets[0]
+
+        self.assertEqual(envelope.packet, packet)
+        self.assertEqual(1, envelope.tries)
+        self.assertEqual(1, packet.tries)
+        self.assertEqual(1, packet.instances)
+        self.assertEqual(MessageState.MSGSTATE_SENT, packet.state)
+        self.assertEqual(envelope.raw, packet.raw)
+
+        time.sleep(self.h.channel._get_packet_timeout_time(1))
+        time.sleep(self.h.channel._get_packet_timeout_time(2))
+        time.sleep(self.h.channel._get_packet_timeout_time(3))
+        time.sleep(self.h.channel._get_packet_timeout_time(4))
+        time.sleep(self.h.channel._get_packet_timeout_time(5) * 1.1)
+
+        self.assertEqual(1, len(self.h.outlet.packets))
+        self.assertEqual(5, envelope.tries)
+        self.assertEqual(5, packet.tries)
+        self.assertEqual(0, packet.instances)
+        self.assertEqual(MessageState.MSGSTATE_FAILED, packet.state)
+        self.assertFalse(envelope.tracked)
+
+    def test_multiple_handler(self):
+        print("Channel test multiple handler short circuit")
+
+        handler1_called = 0
+        handler1_return = True
+        handler2_called = 0
+
+        def handler1(msg: MessageBase):
+            nonlocal handler1_called, handler1_return
+            self.assertIsInstance(msg, MessageTest)
+            handler1_called += 1
+            return handler1_return
+
+        def handler2(msg: MessageBase):
+            nonlocal handler2_called
+            self.assertIsInstance(msg, MessageTest)
+            handler2_called += 1
+
+        message = MessageTest()
+        self.h.channel.register_message_type(MessageTest)
+        self.h.channel.add_message_handler(handler1)
+        self.h.channel.add_message_handler(handler2)
+        envelope = RNS.Channel.Envelope(self.h.outlet, message, sequence=0)
+        raw = envelope.pack()
+        self.h.channel._receive(raw)
+
+        self.assertEqual(1, handler1_called)
+        self.assertEqual(0, handler2_called)
+
+        handler1_return = False
+        envelope = RNS.Channel.Envelope(self.h.outlet, message, sequence=1)
+        raw = envelope.pack()
+        self.h.channel._receive(raw)
+
+        self.assertEqual(2, handler1_called)
+        self.assertEqual(1, handler2_called)
+
+    def test_system_message_check(self):
+        print("Channel test register system message")
+        with self.assertRaises(RNS.Channel.ChannelException):
+            self.h.channel.register_message_type(SystemMessage)
+        self.h.channel._register_message_type(SystemMessage, is_system_type=True)
+
+
+    def eat_own_dog_food(self, message: MessageBase, checker: typing.Callable[[MessageBase], None]):
+        decoded: [MessageBase] = []
+
+        def handle_message(message: MessageBase):
+            decoded.append(message)
+
+        self.h.channel.register_message_type(message.__class__)
+        self.h.channel.add_message_handler(handle_message)
+        self.assertEqual(len(self.h.outlet.packets), 0)
+
+        envelope = self.h.channel.send(message)
+        time.sleep(self.h.channel._get_packet_timeout_time(1) * 0.5)
+
+        self.assertIsNotNone(envelope)
+        self.assertIsNotNone(envelope.raw)
+        self.assertEqual(1, len(self.h.outlet.packets))
+        self.assertIsNotNone(envelope.packet)
+        self.assertTrue(envelope in self.h.channel._tx_ring)
+        self.assertTrue(envelope.tracked)
+
+        packet = self.h.outlet.packets[0]
+
+        self.assertEqual(envelope.packet, packet)
+        self.assertEqual(1, envelope.tries)
+        self.assertEqual(1, packet.tries)
+        self.assertEqual(1, packet.instances)
+        self.assertEqual(MessageState.MSGSTATE_SENT, packet.state)
+        self.assertEqual(envelope.raw, packet.raw)
+
+        packet.delivered()
+
+        self.assertEqual(MessageState.MSGSTATE_DELIVERED, packet.state)
+
+        time.sleep(self.h.channel._get_packet_timeout_time(1))
+
+        self.assertEqual(1, len(self.h.outlet.packets))
+        self.assertEqual(1, envelope.tries)
+        self.assertEqual(1, packet.tries)
+        self.assertEqual(0, packet.instances)
+        self.assertFalse(envelope.tracked)
+
+        self.assertEqual(len(self.h.outlet.packets), 1)
+        self.assertEqual(MessageState.MSGSTATE_DELIVERED, packet.state)
+        self.assertFalse(envelope.tracked)
+        self.assertEqual(0, len(decoded))
+
+        self.h.channel._receive(packet.raw)
+
+        self.assertEqual(1, len(decoded))
+
+        rx_message = decoded[0]
+
+        self.assertIsNotNone(rx_message)
+        self.assertIsInstance(rx_message, message.__class__)
+        checker(rx_message)
+
+    def test_send_receive_message_test(self):
+        print("Channel test send and receive message")
+        message = MessageTest()
+
+        def check(rx_message: MessageBase):
+            self.assertIsInstance(rx_message, message.__class__)
+            self.assertEqual(message.id, rx_message.id)
+            self.assertEqual(message.data, rx_message.data)
+            self.assertNotEqual(message.not_serialized, rx_message.not_serialized)
+
+        self.eat_own_dog_food(message, check)
+
+    def test_buffer_small_bidirectional(self):
+        data = "Hello\n"
+        with RNS.Buffer.create_bidirectional_buffer(0, 0, self.h.channel) as buffer:
+            count = buffer.write(data.encode("utf-8"))
+            buffer.flush()
+
+            self.assertEqual(len(data), count)
+            self.assertEqual(1, len(self.h.outlet.packets))
+
+            packet = self.h.outlet.packets[0]
+            self.h.channel._receive(packet.raw)
+            result = buffer.readline()
+
+            self.assertIsNotNone(result)
+            self.assertEqual(len(result), len(data))
+
+            decoded = result.decode("utf-8")
+
+            self.assertEqual(data, decoded)
+
+    def test_buffer_big(self):
+        writer = RNS.Buffer.create_writer(15, self.h.channel)
+        reader = RNS.Buffer.create_reader(15, self.h.channel)
+        data = "01234556789"*1024  # 10 KB
+        count = 0
+        write_finished = False
+
+        def write_thread():
+            nonlocal count, write_finished
+            count = writer.write(data.encode("utf-8"))
+            writer.flush()
+            writer.close()
+            write_finished = True
+        threading.Thread(target=write_thread, name="Write Thread", daemon=True).start()
+
+        while not write_finished or next(filter(lambda x: x.state != MessageState.MSGSTATE_DELIVERED,
+                                                self.h.outlet.packets), None) is not None:
+            with self.h.outlet.lock:
+                for packet in self.h.outlet.packets:
+                    if packet.state != MessageState.MSGSTATE_DELIVERED:
+                        self.h.channel._receive(packet.raw)
+                        packet.delivered()
+            time.sleep(0.0001)
+
+        self.assertEqual(len(data), count)
+
+        read_finished = False
+        result = bytes()
+
+        def read_thread():
+            nonlocal read_finished, result
+            result = reader.read()
+            read_finished = True
+        threading.Thread(target=read_thread, name="Read Thread", daemon=True).start()
+
+        timeout_at = time.time() + 7
+        while not read_finished and time.time() < timeout_at:
+            time.sleep(0.001)
+
+        self.assertTrue(read_finished)
+        self.assertEqual(len(data), len(result))
+
+        decoded = result.decode("utf-8")
+
+        self.assertSequenceEqual(data, decoded)
+
+    def test_buffer_small_with_callback(self):
+        callbacks = 0
+        last_cb_value = None
+
+        def callback(ready: int):
+            nonlocal callbacks, last_cb_value
+            callbacks += 1
+            last_cb_value = ready
+
+        data = "Hello\n"
+        with RNS.RawChannelWriter(0, self.h.channel) as writer, RNS.RawChannelReader(0, self.h.channel) as reader:
+            reader.add_ready_callback(callback)
+            count = writer.write(data.encode("utf-8"))
+            writer.flush()
+
+            self.assertEqual(len(data), count)
+            self.assertEqual(1, len(self.h.outlet.packets))
+
+            packet = self.h.outlet.packets[0]
+            self.h.channel._receive(packet.raw)
+            packet.delivered()
+
+            self.assertEqual(1, callbacks)
+            self.assertEqual(len(data), last_cb_value)
+
+            result = reader.readline()
+
+            self.assertIsNotNone(result)
+            self.assertEqual(len(result), len(data))
+
+            decoded = result.decode("utf-8")
+
+            self.assertEqual(data, decoded)
+            self.assertEqual(1, len(self.h.outlet.packets))
+
+            result = reader.read(1)
+
+            self.assertIsNone(result)
+            self.assertTrue(self.h.channel.is_ready_to_send())
+
+            writer.close()
+
+            self.assertEqual(2, len(self.h.outlet.packets))
+
+            packet = self.h.outlet.packets[1]
+            self.h.channel._receive(packet.raw)
+            packet.delivered()
+
+            result = reader.read(1)
+
+            self.assertIsNotNone(result)
+            self.assertTrue(len(result) == 0)
+
+
+
+
+if __name__ == '__main__':
+    unittest.main(verbosity=2)

tests/link.py

@@ -4,8 +4,14 @@ import subprocess
 import shlex
 import threading
 import time
+from unittest import skipIf
 import RNS
 import os
+from tests.channel import MessageTest
+from RNS.Channel import MessageBase
+from RNS.Buffer import StreamDataMessage
+from RNS.Interfaces.LocalInterface import LocalClientInterface
+from math import ceil
 
 APP_NAME = "rns_unit_tests"
 
@@ -346,6 +352,203 @@ class TestLink(unittest.TestCase):
         time.sleep(0.5)
         self.assertEqual(l1.status, RNS.Link.CLOSED)
 
+    def test_10_channel_round_trip(self):
+        global c_rns
+        init_rns(self)
+        print("")
+        print("Channel round trip test")
+
+        # TODO: Load this from public bytes only
+        id1 = RNS.Identity.from_bytes(bytes.fromhex(fixed_keys[0][0]))
+        self.assertEqual(id1.hash, bytes.fromhex(fixed_keys[0][1]))
+
+        dest = RNS.Destination(id1, RNS.Destination.OUT, RNS.Destination.SINGLE, APP_NAME, "link", "establish")
+
+        self.assertEqual(dest.hash, bytes.fromhex("fb48da0e82e6e01ba0c014513f74540d"))
+
+        l1 = RNS.Link(dest)
+        time.sleep(1)
+        self.assertEqual(l1.status, RNS.Link.ACTIVE)
+
+        received = []
+
+        def handle_message(message: MessageBase):
+            received.append(message)
+
+        test_message = MessageTest()
+        test_message.data = "Hello"
+
+        channel = l1.get_channel()
+        channel.register_message_type(MessageTest)
+        channel.add_message_handler(handle_message)
+        channel.send(test_message)
+
+        time.sleep(0.5)
+
+        self.assertEqual(1, len(received))
+
+        rx_message = received[0]
+
+        self.assertIsInstance(rx_message, MessageTest)
+        self.assertEqual("Hello back", rx_message.data)
+        self.assertEqual(test_message.id, rx_message.id)
+        self.assertNotEqual(test_message.not_serialized, rx_message.not_serialized)
+        self.assertEqual(1, len(l1._channel._rx_ring))
+
+        l1.teardown()
+        time.sleep(0.5)
+        self.assertEqual(l1.status, RNS.Link.CLOSED)
+        self.assertEqual(0, len(l1._channel._rx_ring))
+
+    def test_11_buffer_round_trip(self):
+        global c_rns
+        init_rns(self)
+        print("")
+        print("Buffer round trip test")
+
+        # TODO: Load this from public bytes only
+        id1 = RNS.Identity.from_bytes(bytes.fromhex(fixed_keys[0][0]))
+        self.assertEqual(id1.hash, bytes.fromhex(fixed_keys[0][1]))
+
+        dest = RNS.Destination(id1, RNS.Destination.OUT, RNS.Destination.SINGLE, APP_NAME, "link", "establish")
+
+        self.assertEqual(dest.hash, bytes.fromhex("fb48da0e82e6e01ba0c014513f74540d"))
+
+        l1 = RNS.Link(dest)
+        time.sleep(1)
+        self.assertEqual(l1.status, RNS.Link.ACTIVE)
+        buffer = None
+
+        received = []
+        def handle_data(ready_bytes: int):
+            data = buffer.read(ready_bytes)
+            received.append(data)
+
+        channel = l1.get_channel()
+        buffer = RNS.Buffer.create_bidirectional_buffer(0, 0, channel, handle_data)
+
+        buffer.write("Hi there".encode("utf-8"))
+        buffer.flush()
+
+        time.sleep(0.5)
+
+        self.assertEqual(1 , len(received))
+
+        rx_message = received[0].decode("utf-8")
+
+        self.assertEqual("Hi there back at you", rx_message)
+
+        l1.teardown()
+        time.sleep(0.5)
+        self.assertEqual(l1.status, RNS.Link.CLOSED)
+
+    def test_12_buffer_round_trip_big(self, local_bitrate = None):
+        global c_rns
+        init_rns(self)
+        print("")
+        print("Buffer round trip test")
+
+        local_interface = next(filter(lambda iface: isinstance(iface, LocalClientInterface), RNS.Transport.interfaces), None)
+        self.assertIsNotNone(local_interface)
+        original_bitrate = local_interface.bitrate
+
+        try:
+            if local_bitrate is not None:
+                local_interface.bitrate = local_bitrate
+                local_interface._force_bitrate = True
+                print("Forcing local bitrate of " + str(local_bitrate) + " bps (" + str(round(local_bitrate/8, 0)) + " B/s)")
+
+            # TODO: Load this from public bytes only
+            id1 = RNS.Identity.from_bytes(bytes.fromhex(fixed_keys[0][0]))
+            self.assertEqual(id1.hash, bytes.fromhex(fixed_keys[0][1]))
+
+            dest = RNS.Destination(id1, RNS.Destination.OUT, RNS.Destination.SINGLE, APP_NAME, "link", "establish")
+
+            self.assertEqual(dest.hash, bytes.fromhex("fb48da0e82e6e01ba0c014513f74540d"))
+
+            l1 = RNS.Link(dest)
+            # delay a reasonable time for link to come up at current bitrate
+            link_sleep = max(RNS.Link.MDU * 3 / local_interface.bitrate * 8, 2)
+            timeout_at = time.time() + link_sleep
+            print("Waiting " + str(round(link_sleep, 1)) + " sec for link to come up")
+            while l1.status != RNS.Link.ACTIVE and time.time() < timeout_at:
+                time.sleep(0.01)
+
+            self.assertEqual(l1.status, RNS.Link.ACTIVE)
+
+            buffer = None
+            received = []
+            def handle_data(ready_bytes: int):
+                data = buffer.read(ready_bytes)
+                received.append(data)
+
+            channel = l1.get_channel()
+            buffer = RNS.Buffer.create_bidirectional_buffer(0, 0, channel, handle_data)
+
+            # try to make the message big enough to split across packets, but
+            # small enough to make the test complete in a reasonable amount of time
+            seed_text = "0123456789"
+            message = seed_text*ceil(min(max(local_interface.bitrate / 8,
+                                             StreamDataMessage.MAX_DATA_LEN * 2 / len(seed_text)),
+                                         1000))
+            # the return message will have an appendage string " back at you"
+            # for every StreamDataMessage that arrives. To verify, we need
+            # to insert that string every MAX_DATA_LEN and also at the end.
+            expected_rx_message = ""
+            for i in range(0, len(message)):
+                if i > 0 and (i % StreamDataMessage.MAX_DATA_LEN) == 0:
+                    expected_rx_message += " back at you"
+                expected_rx_message += message[i]
+            expected_rx_message += " back at you"
+
+            # since the segments will be received at max length for a
+            # StreamDataMessage, the appended text will end up in a
+            # separate packet.
+            expected_chunk_count = ceil(len(message)/StreamDataMessage.MAX_DATA_LEN * 2)
+            print("Sending " + str(len(message)) + " bytes, receiving " + str(len(expected_rx_message)) + " bytes, " +
+                  "expecting " + str(expected_chunk_count) + " chunks of " + str(StreamDataMessage.MAX_DATA_LEN) + " bytes")
+            transfer_sleep = max(expected_chunk_count * 3 * c_rns.MTU / local_interface.bitrate * 8, 3)
+            print("Will take up to " + str(round(transfer_sleep, 0)) + " seconds to transfer")
+            expected_ready_time = time.time() + transfer_sleep
+            buffer.write(message.encode("utf-8"))
+            buffer.flush()
+            # delay a reasonable time for the send and receive
+            # a chunk each way plus a little more for a proof each way
+            while time.time() < expected_ready_time and len(received) < expected_chunk_count:
+                time.sleep(0.1)
+            # sleep for at least one more chunk round trip in case there
+            # are more chunks than expected
+            if time.time() < expected_ready_time:
+                time.sleep(max(c_rns.MTU * 2 / local_interface.bitrate * 8, 1))
+
+            # Why does this not always work out correctly?
+            # self.assertEqual(expected_chunk_count, len(received))
+
+            data = bytearray()
+            for rx in received:
+                data.extend(rx)
+
+            rx_message = data.decode("utf-8")
+
+            self.assertEqual(len(expected_rx_message), len(rx_message))
+            for i in range(0, len(expected_rx_message)):
+                self.assertEqual(expected_rx_message[i], rx_message[i])
+            self.assertEqual(expected_rx_message, rx_message)
+
+            l1.teardown()
+            time.sleep(0.5)
+            self.assertEqual(l1.status, RNS.Link.CLOSED)
+        finally:
+            local_interface.bitrate = original_bitrate
+            local_interface._force_bitrate = False
+
+    # Run with
+    #  RUN_SLOW_TESTS=1 python tests/link.py TestLink.test_13_buffer_round_trip_big_slow
+    # Or
+    #  make RUN_SLOW_TESTS=1 test
+    @skipIf(int(os.getenv('RUN_SLOW_TESTS', 0)) < 1, "Not running slow tests")
+    def test_13_buffer_round_trip_big_slow(self):
+        self.test_12_buffer_round_trip_big(local_bitrate=410)
 
     def size_str(self, num, suffix='B'):
         units = ['','K','M','G','T','P','E','Z']
@@ -404,6 +607,22 @@ def targets(yp=False):
         link.set_resource_strategy(RNS.Link.ACCEPT_ALL)
         link.set_resource_started_callback(resource_started)
         link.set_resource_concluded_callback(resource_concluded)
+        channel = link.get_channel()
+
+        def handle_message(message):
+            message.data = message.data + " back"
+            channel.send(message)
+        channel.register_message_type(MessageTest)
+        channel.add_message_handler(handle_message)
+
+        buffer = None
+
+        def handle_buffer(ready_bytes: int):
+            data = buffer.read(ready_bytes)
+            buffer.write((data.decode("utf-8") + " back at you").encode("utf-8"))
+            buffer.flush()
+
+        buffer = RNS.Buffer.create_bidirectional_buffer(0, 0, channel, handle_buffer)
 
     m_rns = RNS.Reticulum("./tests/rnsconfig")
     id1 = RNS.Identity.from_bytes(bytes.fromhex(fixed_keys[0][0]))