Updated docs

Record dependency on six

.gitignore

@@ -5,4 +5,5 @@ TODO
 Examples/RNS
 build
 dist
+docs/build
 rns*.egg-info

Documentation/Reticulum Overview.md

@@ -1,492 +0,0 @@
-# Reticulum Overview
-
-This paper will briefly describe the overall purpose and operating principles of Reticulum, a
-networking stack designed for reliable and secure communication over high-latency, low-bandwidth
-links. It should give you an overview of how the stack works, and an understanding of how to
-develop networked applications using Reticulum.
-
-This document is not an exhaustive source of information on Reticulum, at least not yet. Currently,
-the best place to go for such information is the Python reference implementation of Reticulum. Both
-the reference implementation and this document may (and will) change rapidly in the current phase
-of development, but historical versions will always be available in the Git repositories.
-
-After reading this document, you should be well-equipped to understand how a Reticulum network
-operates, what it can achieve, and how you can use it yourself. If you want to help out with the
-development, this is also the place to start, since it will also provide a pretty clear overview of the
-sentiments and the philosophy behind Reticulum.
-
-## Motivation
-
-The primary motivation for designing and implementing Reticulum has been the current lack of
-reliable, functional and secure minimal-infrastructure modes of digital communication. It is my
-belief that it is highly desirable to create a cheap and reliable way to set up a wide-range digital
-communication network that can securely allow exchange of information between people and
-machines, with no central point of authority, control, censorship or barrier to entry.
-
-Almost all of the various networking stacks in wide use today share a common limitation, namely
-that they require large amounts of coordination to work. You can’t just plug in a bunch of ethernet
-cables to the same switch, or turn on a number of WiFi radios, and expect such a setup to provide a
-reliable platform for communication.
-
-The designers of the Internet Protocol had the foresight to create a protocol that powers the modern
-Internet, and works brilliantly in world very different from when it was conceived. But networks
-using the traditional IP stack needs large amounts of coordination from the people involved, and
-without central actors in ultimate control of network segments, it is very easy for a single person to
-render the platform unusable for everyone else. These limitations are inherent to the design
-principles of IP, and during the design of IP, this was a very reasonable tradeoff indeed.
-
-Reticulum aims to require as little coordination and trust as possible. In fact, the only
-“coordination” required is to know how to get connected to a Reticulum network. Since Reticulum
-is medium agnostic, this could be whatever is best suited to the situation. In some cases, this might
-be 1200 baud packet radio links over VHF frequencies, in other cases it might be a microwave
-network using off-the-shelf radios. At the time of release of this document, the recommended setup
-is using cheap LoRa radio modules with an open source firmware (see the chapter _Reference System
-Setup_ ), connected to a small computer like a Raspberry Pi. As an example, the default reference
-setup provides a channel capacity of 5.4 Kbps, and a usable direct node-to-node range of around 15
-kilometers (indefinitely extendable by using multiple hops).
-
-
-## Goals
-
-To be as widely usable and easy to implement as possible, the following goals have been used to
-guide the design of Reticulum:
-
-- **Fully useable as open source software stack**
-    Reticulum must be implemented, and be able to run using only open source software. This is
-    critical to ensuring availability, security and transparency of the system.
-- **Hardware layer agnosticism**
-    Reticulum shall be fully hardware agnostic, and should be useable over a wide range
-    physical networking layers, such as data radios, serial lines, modems, handheld transceivers,
-    wired ethernet, wifi, or anything else that can carry a digital data stream. Hardware made for
-    dedicated Reticulum use shall be as cheap as possible and use off-the-shelf components, so
-    it can be easily replicated.
-- **Very low bandwidth requirements**
-    Reticulum should be able to function reliably over links with a data capacity as low as _1,_
-    _bps_.
-- **Encryption by default**
-    Reticulum must use encryption by default where possible and applicable.
-- **Unlicensed use**
-    Reticulum shall be functional over physical communication mediums that do not require any
-    form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio
-    frequency bands, and can provide functional long distance links in such conditions.
-- **Supplied software**
-    Apart from the core networking stack and API, that allows any developer to build
-    applications with Reticulum, a basic communication suite using Reticulum must be
-    implemented and released at the same time as Reticulum itself. This shall serve both as a
-    functional communication suite, and as an example and learning resource to others wishing
-    to build applications with Reticulum.
-- **Ease of use**
-    The reference implementation of Reticulum is written in Python, to make it very easy to use
-    and understand. Any programmer with only basic experience should be able to use
-    Reticulum in their own applications.
-- **Low cost**
-    It shall be as cheap as possible to deploy a communication system based on Reticulum. This
-    should be achieved by using cheap off-the-shelf hardware that potential users might already
-    own. The cost of setting up a functioning node should be less than $100 even if all parts
-    needs to be purchased.
-
-
-# Introduction & Basic Functionality
-
-Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
-core _message oriented_ , but can provide connection oriented sessions. It is suited for both local
-point-to-point or point-to-multipoint scenarios where alle nodes are within range of each other, as
-well as scenarios where packets need to be transported over multiple hops 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
-networking stack will need to create one or more destinations to receive data, and know the
-destinations it needs to send data to.
-
-Reticulum encrypts all data by default using public-key cryptography. Any message sent to a
-destination is encrypted with that destinations public key. Reticulum also offers symmetric key
-encryption for group-oriented communications, as well as unencrypted packets for broadcast
-purposes, or situations where you need the communication to be in plain text. The multi-hop
-transport, coordination, verification and reliability layers are fully autonomous and based on public
-key cryptography.
-
-Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
-and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
-private IP networks.
-
-## Destinations
-
-To receive and send data with the Reticulum stack, an application needs to create one or more
-destinations. Reticulum uses three different basic destination types, and one special:
-
-- **Single**
-    The _single_ destination type defines a public-key encrypted destination. Any data sent to this
-    destination will be encrypted with the destination’s public key, and will only be readable by
-    the creator of the destination.
-- **Group**
-    The _group_ destination type defines a symmetrically encrypted destination. Data sent to this
-    destination will be encrypted with a symmetric key, and will be readable by anyone in
-    possession of the key. The _group_ destination can be used just as well by only two peers, as it
-    can by many.
-- **Plain**
-    A _plain_ destination type is unencrypted, and suited for traffic that should be broadcast to a
-    number of users, or should be readable by anyone.
-- **Link**
-    A _link_ is a special destination type, that serves as an abstract channel between two _single_
-    destinations, directly connected or over multiple hops. The _link_ also offers reliability and
-    more efficient encryption, and as such is useful even when nodes are directly connected.
-
-
-## Destination Naming
-
-Destinations are created and named in an easy to understand dotted notation of _aspects_ , and
-represented on the network as a hash of this value. The hash is a SHA-256 truncated to 80 bits. The
-top level aspect should always be the a unique identifier for the application using the destination.
-The next levels of aspects can be defined in any way by the creator of the application. For example,
-a destination for a messaging application could be made up of the application name and a username,
-and look like this:
-
-```
-name: simplemessenger.someuser hash: 2a7ddfab5213f916dea
-```
-For the _single_ destination, Reticulum will automatically append the associated public key as a
-destination aspect before hashing. This is done to ensure only the correct destination is reached,
-since anyone can listen to any destination name. Appending the public key ensures that a given
-packet is only directed at the destination that holds the corresponding private key to decrypt the
-packet. It is important to understand that anyone can use the destination name
-_simplemessenger.myusername_ , but each person that does so will still have a different destination
-hash, because their public keys will differ. In actual use of _single_ destination naming, it is advisable
-not to use any uniquely identifying features in aspect naming, though. In the simple messenger
-example, when using _single_ destinations, we would instead use a destination naming scheme such
-as _simplemessenger.user_ where appending the public key expands the destination into a uniquely
-identifying one.
-
-To recap, the destination types should be used in the following situations:
-
-- **Single**
-    When private communication between two endpoints is needed. Supports routing.
-- **Group**
-    When private communication between two or more endpoints is needed. More efficient in
-    data usage than _single_ destinations. Supports routing indirectly, but must first be established
-    through a _single_ destination.
-- **Plain**
-    When plain-text communication is desirable, for example when broadcasting information.
-
-To communicate with a _single_ destination, you need to know it’s 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_.
-
-Note that this information could be shared and verified in many other ways, and that it is therefore
-not required to use the announce functionality, although it is by far the easiest, and should probably
-be used if you are not confident in how to verify public keys and signatures manually.
-
-
-## Public key announcements
-
-An _announce_ will send a special packet over any configured interfaces, containing all needed
-information about the destination hash and public key, and can also contain some additional,
-application specific data. The entire packet is signed by the sender to ensure authenticity. It is not
-required to use the announce functionality, but in many cases it will be the simplest way to share
-public keys on the network. As an example, an announce in a simple messenger application might
-contain the following information:
-
-- The announcers destination hash
-- The announcers public key
-- Application specific data, in this case the users nickname and availability status
-- A random blob, making each new announce unique
-- A signature of the above information, verifying authenticity
-
-With this information, any Reticulum node that receives it will be able to reconstruct an outgoing
-destination to securely communicate with that destination. You might have noticed that there is one
-piece of information lacking to reconstruct full knowledge of the announced destination, and that is
-the aspect names of the destination. These are intentionally left out to save bandwidth, since they
-will be implicit in almost all cases. If a destination name is not entirely implicit, information can be
-included in the application specific data part that will allow the receiver to infer the naming.
-
-It is important to note that announcements will be forwarded throughout the network according to a
-certain pattern. This will be detailed later. Seeing how _single_ destinations are always tied to a
-private/public key pair leads us to the next topic.
-
-
-## Identities
-
-In Reticulum, an _identity_ does not necessarily represent a personal identity, but is an abstraction that
-can represent any kind of _verified entity_. This could very well be a person, but it could also be the
-control interface of a machine, a program, robot, computer, sensor or something else entirely. In
-general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be
-represented as an identity.
-
-As we have seen, a _single_ destination will always have an _identity_ tied to it, but not _plain_ or _group_
-destinations. Destinations and identities share a multilateral connection. You can create a
-destination, and if it is not connected to an identity upon creation, it will just create a new one to use
-automatically. This may be desirable in some situations, but often you will probably want to create
-the identity first, and then link it to created destinations.
-
-Building upon the simple messenger example, we could use an identity to represent the user of the
-application. Destinations created will then be linked to this identity to allow communication to
-reach the user. In such a case it is of great importance to store the user’s identity securely and
-privately.
-
-## Getting Further
-
-The above functions and principles form the core of Reticulum, and would suffice to create
-functional networked applications in local clusters, for example over radio links where all interested
-nodes can hear each other. But to be truly useful, we need a way to go further. In the next chapter,
-two concepts that allow this will be introduced, _paths_ and _resources_.
-
-
-# Transport
-
-I have purposefully avoided the term routing until now, and will continue to do so, because the
-current methods of routing used in IP based networks are fundamentally incompatible for the link
-types that Reticulum was designed to handle. These routing methodologies assume trust at the
-physical layer. Since Reticulum is designed to run over open radio spectrum, no such trust exists.
-Furthermore, existing routing protocols like BGP or OSPF carry too much overhead to be
-practically useable over bandwidth-limited, high-latency links.
-
-To overcome such challenges, Reticulum’s _Transport_ system uses public-key cryptography to
-implement the concept of _paths_ that allow discovery of how to get information to a certain
-destination, and _resources_ that help alleviate congestion and make reliable communication more
-efficient and less bandwidth-hungry.
-
-## Threading a Path
-
-In networks with changing topology and trustless connectivity, nodes need a way to establish
-_verified connectivity_ with each other. To do this, the following process is employed:
-
-- First, the node that wishes to establish connectivity will send out a special packet, that
-    traverses the network and locates the desired destination. Along the way, the nodes that
-    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
-    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.
-- When the validity of the _link_ has been accepted by forwarding nodes, these nodes will
-    remember the _link_ , and it can subsequently be used by referring to a hash representing it.
-- As a part of the _link request_ , a Diffie-Hellman key exchange takes place, that sets up an
-    efficient symmetrically encrypted tunnel between the two nodes, using elliptic curve
-    cryptography. As such, this mode of communication is preferred, even for situations when
-    nodes can directly communicate, when the amount of data to be exchanged numbers in the
-    tens of packets.
-- When a _link_ has been set up, it automatically provides message receipt functionality, so the
-    sending node can obtain verified confirmation that the information reached the intended
-    recipient.
-
-In a moment, we will discuss the specifics of how this methodology is implemented, but let’s first
-recap what purposes this serves. We first ensure that the node answering our request is actually the
-one we want to communicate with, and not a malicious actor pretending to be so. At the same time
-we establish an efficient encrypted channel. The setup of this is relatively cheap in terms of
-bandwidth, so it can be used just for a short exchange, and then recreated as needed, which will also
-
-
-rotate encryption keys (keys can also be rotated over an existing path), but the link can also be kept
-alive for longer periods of time, if this is more suitable to the application. The amount of bandwidth
-used on keeping a link open is practically negligible. The procedure also inserts the _link id_ , a hash
-calculated from the link request packet, into the memory of forwarding nodes, which means that the
-communicating nodes can thereafter reach each other simply by referring to this _link id_.
-
-**Step 1, pathfinding**
-
-The pathfinding method builds on the _announce_ functionality discussed earlier. When an announce
-is sent out by a node, it will be forwarded by any node receiving it, but according to some specific
-rules:
-
-- If this announce has already been received before, ignore it.
-- Record into a table which node the announce was received from, and how many times in
-    total it has been retransmitted to get here.
-- If the announce has been retransmitted _m+1_ times, it will not be forwarded. By default, _m_ is
-    set to 18.
-- The announce will be assigned a delay _d_ = _ch_ seconds, where _c_ is a decay constant, by
-    default 2, and _h_ is the amount of times this packet has already been forwarded.
-- The packet will be given a priority _p = 1/d_.
-- If at least _d_ seconds has passed since the announce was received, and no other packets with a
-    priority higher than _p_ are waiting in the queue (see Packet Prioritisation), and the channel is
-    not utilized by other traffic, the announce will be forwarded.
-- If no other nodes are heard retransmitting the announce with a greater hop count than when
-    it left this node, transmitting it will be retried _r_ times. By default, _r_ is set to 2. Retries follow
-    same rules as above, with the exception that it must wait for at least _d = ch+1 + t_ seconds, ie.,
-    the amount of time it would take the next node to retransmit the packet. By default, _t_ is set to
-    10.
-- If a newer announce from the same destination arrives, while an identical one is already in
-    the queue, the newest announce is discarded. If the newest announce contains different
-    application specific data, it will replace the old announce, but will use _d_ and _p_ of the old
-    announce.
-
-Once an announce has reached a node in the network, any other node in direct contact with that
-node will be able to reach the destination the announce originated from, simply by sending a packet
-addressed to that destination. Any node with knowledge of the announce will be able to direct the
-packet towards the destination by looking up the next node with the shortest amount of hops to the
-destination. The specifics of this process is detailed in _Path Calculation_.
-
-According to these rules and default constants, an announce will propagate throughout the network
-in a predictable way. In an example network utilising the default constants, and with an average link
-
-
-distance of _Lavg =_ 15 kilometers, an announce will be able to propagate outwards to a radius of 180
-kilometers in 34 minutes, and a _maximum announce radius_ of 270 kilometers in approximately 3
-days. Methods for overcoming the distance limitation of _m * Lavg_ will be introduced later in this
-chapter.
-
-**Step 2, link establishment**
-
-After seeing how the conditions for finding a path through the network are created, we will now
-explore how two nodes can establish reliable communications over multiple hops. The _link_ in
-Reticulum terminology should not be viewed as a direct node-to-node link on the physical layer, but
-as an abstract channel, that can be open for any amount of time, and can span an arbitrary number
-of hops, where information will be exchanged between two nodes.
-
-- When a node in the network wants to establish verified connectivity with another node, it
-    will create a _link request_ packet, and broadcast it.
-- The _link request_ packet contains the destination hash _Hd_ , and an asymmetrically encrypted
-    part containing the following data: The source hash _Hs_ , a symmetric key _Lk_ , a truncated
-    hash of a random number _Hr_ , and a signature _S_ of the plaintext values of _Hd_ , _Hs_ , _Lk_ and _Hr_.
-- The broadcasted packet will be directed through the network according to the rules laid out
-    previously.
-- Any node that forwards the link request will store a _link id_ in it’s _link table_ , along with the
-    amount of hops the packet had taken when received. The link id is a hash of the entire link
-    request packet. If the path is not _proven_ within some set amount of time, the entry will be
-    dropped from the table again.
-- When the destination receives the link request packet, it will decide whether to accept the
-    request. If it is accepted, it will create a special packet called a _proof_. A _proof_ is a simple
-    construct, consisting of a truncated hash of the message that needs to be proven, and a
-    signature (made by the destination’s private key) of this hash. This _proof_ effectively verifies
-    that the intended recipient got the packet, and also serves to verify the discovered path
-    through the network. Since the _proof_ hash matches the _path id_ in the intermediary nodes’
-    _path tables_ , the intermediary nodes can forward the proof all the way back to the source.
-- When the source receives the _proof_ , it will know unequivocally that a verified path has been
-    established to the destination, and that information can now be exchanged reliably and
-    securely.
-
-It’s important to note that this methodology ensures that the source of the request does not need to
-reveal any identifying information. Only the intended destination will know “who called”, so to
-speak. This is a huge improvement to protocols like IP, where by design, you have to reveal your
-own address to communicate with anyone, unless you jump through a lot of hoops to hide it.
-Reticulum offers initiator anonymity by design.
-
-
-When using _links_ , Reticulum will automatically verify anything sent over the link, and also
-automates retransmissions if parts of a message was lost along the way. Due to the caching features
-of Reticulum, such a retransmission does not need to travel the entire length of an established path.
-If a packet is lost on the 8th hop of a 12 hop path, it can be fetched from the last hop that received it
-reliably.
-
-## Crossing Continents
-
-When a packet needs to travel farther than local network topology knowledge stretches, a system of
-geographical or topological hinting is used to direct the packet towards a network segment with
-direct knowledge of the intended destination. This functionality is currently left out of the protocol
-for simplicity of testing other parts, but will be activated in a future release. For more information
-on when, refer to the roadmap on the website.
-
-## Resourceful Memory
-
-In traditional networks, large amounts of data is rapidly exchanged with very low latency. Links of
-several thousand kilometers will often only have round-trip latency in the tens of milliseconds, and
-as such, traditional protocols are often designed to not store any transmitted data at intermediary
-hops. If a transmission error occurs, the sending node will simply notice the lack of a packet
-acknowledgement, and retransmit the packet all the way, until it hears back from the receiver that it
-got the intended data.
-
-In bandwidth-limited and high-latency conditions, such behaviour quickly causes congestion on the
-network, and communications that span many hops become exceedingly expensive in terms of
-bandwidth usage, due to the higher risk of some packets failing.
-
-Reticulum alleviates this in part with it’s _path_ discovery methodology, and in part by implementing
-_resource_ caching at all nodes that can support it. Network operation can be made much more
-efficient by caching everything for a period of time, and given the availability of cheap memory and
-storage, this is a very welcome tradeoff. A gigabyte of memory can store millions of Reticulum
-packets, and since everything is encrypted by default, the storing poses very little privacy risk.
-
-In a Reticulum network, any node that is able to do so, should cache as many packets as it’s
-memory will allow for. When a packet is received, a timestamp and a hash of the packet is stored
-along with the full packet itself, and it will be kept in storage until the allocated cache storage is
-full, whereupon the packet that was last accessed in the cache will be deleted. If a packet is accessed
-from the cache, it’s timestamp will be updated to the current time, to ensure that packets that are
-used stay in the cache, and packets that are not used are dropped from memory.
-
-Some packet types are stored in separate caching tables, that allow easier lookup for other nodes.
-For example, an announce is stored in a way, that allows other nodes to request the public key for a
-certain destination, and as such the network as a whole operates as a distributed key ledger.
-
-For more details on how the caching works and is used, see the reference implementation source
-code.
-
-
-# Reference System Setup
-
-This section will detail the recommended _Reference System Setup_ for Reticulum. It is important to
-note that Reticulum is designed to be usable over more or less any medium that allows you to send
-and receive data in a digital form, and satisfies some very low minimum requirements. The
-communication channel must support at least half-duplex operation, and provide an average
-throughput of around 1000 bits per second, and supports a physical layer MTU of 500 bytes. The
-Reticulum software should be able to run on more or less any hardware that can provide a Python
-runtime environment.
-
-That being said, the reference setup has been outlined to provide a common platform for anyone
-who wants to help in the development of Reticulum, and for everyone who wants to know a
-recommended setup to get started. A reference system consists of three parts:
-
-- **A channel access device**
-    Or _CAD_ , in short, provides access to the physical medium whereupon the communication
-    takes place, for example a radio with an integrated modem. A setup with a separate modem
-    connected to a radio would also be termed a “channel access device”.
-- **A host device**
-    Some sort of computing device that can run the necessary software, communicates with the
-    channel access device, and provides user interaction.
-- **A software stack**
-    The software implementing the Reticulum protocol and applications using it.
-
-The reference setup can be considered a relatively stable platform to develop on, and also to start
-building networks on. While details of the implementation might change at the current stage of
-development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
-the current reference setup has been determined to provide a functional platform for many years
-into the future. The current Reference System Setup is as follows:
-
-- **Channel Access Device**
-    A data radio consisting of a LoRa radio module, and a microcontroller with open source
-    firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
-    MHz frequency bands. More details on the exact parts and how to get/make one can be
-    found on the website.
-- **Host device**
-    Any computer device running Linux and Python. A Raspberry Pi with Raspbian is
-    recommended.
-- **Software stack**
-    The current Reference Implementation Release of Reticulum, running on a Debian based
-    operating system.
-
-
-It is very important to note, that the reference channel access device **does not** use the LoRaWAN
-standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
-need a plain LoRa radio module connected to an MCU with the correct Reticulum firmware. Full
-details on how to get or make such a device is available on the website.
-
-With the current reference setup, it should be possible to get on a Reticulum network for around 70$
-even if you have none of the hardware already.
-
-
-# Protocol Specifics
-
-This chapter will detail protocol specific information that is essential to the implementation of
-Reticulum, but non critical in understanding how the protocol works on a general level. It should be
-treated more as a reference than as essential reading.
-
-## Node Types
-
-Currently Reticulum defines two node types, the _Station_ and the _Peer_. A node is a _station_ if it fixed
-in one place, and if it is intended to be kept online at all times. Otherwise the node is a _peer_. This
-distinction is made by the user configuring the node, and is used to determine what nodes on the
-network will help forward traffic, and what nodes rely on other nodes for connectivity.
-
-## Packet Prioritisation
-
-_The packet prioritisation algorithms are subject to rapid change at the moment, and for now, they
-are not documented here. See the reference implementation for more info on how this functionality
-works._
-
-## Path Calculation
-
-_The path calculation algorithms are subject to rapid change at the moment, and for now, they are
-not documented here. See the reference implementation for more info on how this functionality
-works._
-
-## Binary Packet Format
-
-_The binary packet format is subject to rapid change at the moment, and for now, it is not
-documented here. See the reference implementation for the specific details on this topic._
-
-

Examples/Announce.py

@@ -0,0 +1,170 @@
+##########################################################
+# This RNS example demonstrates setting up announce      #
+# callbacks, which will let an application receive a     #
+# notification when an announce relevant for it arrives  #
+##########################################################
+
+import argparse
+import random
+import RNS
+
+# Let's define an app name. We'll use this for all
+# destinations we create. Since this basic example
+# is part of a range of example utilities, we'll put
+# them all within the app namespace "example_utilities"
+APP_NAME = "example_utilities"
+
+# We initialise two lists of strings to use as app_data
+fruits = ["Peach", "Quince", "Date palm", "Tangerine", "Pomelo", "Carambola", "Grape"]
+noble_gases = ["Helium", "Neon", "Argon", "Krypton", "Xenon", "Radon", "Oganesson"]
+
+# This initialisation is executed when the program is started
+def program_setup(configpath):
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
+    
+    # Randomly create a new identity for our example
+    identity = RNS.Identity()
+
+    # Using the identity we just created, we create two destinations
+    # in the "example_utilities.announcesample" application space.
+    #
+    # Destinations are endpoints in Reticulum, that can be addressed
+    # and communicated with. Destinations can also announce their
+    # existence, which will let the network know they are reachable
+    # and autoomatically create paths to them, from anywhere else
+    # in the network.
+    destination_1 = RNS.Destination(
+        identity,
+        RNS.Destination.IN,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "announcesample",
+        "fruits"
+    )
+
+    destination_2 = RNS.Destination(
+        identity,
+        RNS.Destination.IN,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "announcesample",
+        "noble_gases"
+    )
+
+    # We configure the destinations to automatically prove all
+    # packets adressed to it. By doing this, RNS will automatically
+    # generate a proof for each incoming packet and transmit it
+    # back to the sender of that packet. This will let anyone that
+    # tries to communicate with the destination know whether their
+    # communication was received correctly.
+    destination_1.set_proof_strategy(RNS.Destination.PROVE_ALL)
+    destination_2.set_proof_strategy(RNS.Destination.PROVE_ALL)
+
+    # We create an announce handler and configure it to only ask for
+    # announces from "example_utilities.announcesample.fruits".
+    # Try changing the filter and see what happens.
+    announce_handler = ExampleAnnounceHandler(
+        aspect_filter="example_utilities.announcesample.fruits"
+    )
+
+    # We register the announce handler with Reticulum
+    RNS.Transport.register_announce_handler(announce_handler)
+    
+    # Everything's ready!
+    # Let's hand over control to the announce loop
+    announceLoop(destination_1, destination_2)
+
+
+def announceLoop(destination_1, destination_2):
+    # Let the user know that everything is ready
+    RNS.log("Announce example running, 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()
+        
+        # Randomly select a fruit
+        fruit = fruits[random.randint(0,len(fruits)-1)]
+
+        # Send the announce including the app data
+        destination_1.announce(app_data=fruit.encode("utf-8"))
+        RNS.log(
+            "Sent announce from "+
+            RNS.prettyhexrep(destination_1.hash)+
+            " ("+destination_1.name+")"
+        )
+
+        # Randomly select a noble gas
+        noble_gas = noble_gases[random.randint(0,len(noble_gases)-1)]
+
+        # Send the announce including the app data
+        destination_2.announce(app_data=noble_gas.encode("utf-8"))
+        RNS.log(
+            "Sent announce from "+
+            RNS.prettyhexrep(destination_2.hash)+
+            " ("+destination_2.name+")"
+        )
+
+# We will need to define an announce handler class that
+# Reticulum can message when an announce arrives.
+class ExampleAnnounceHandler:
+    # The initialisation method takes the optional
+    # aspect_filter argument. If aspect_filter is set to
+    # None, all announces will be passed to the instance.
+    # If only some announces are wanted, it can be set to
+    # an aspect string.
+    def __init__(self, aspect_filter=None):
+        self.aspect_filter = aspect_filter
+
+    # This method will be called by Reticulums Transport
+    # system when an announce arrives that matches the
+    # configured aspect filter. Filters must be specific,
+    # and cannot use wildcards.
+    def received_announce(self, destination_hash, announced_identity, app_data):
+        RNS.log(
+            "Received an announce from "+
+            RNS.prettyhexrep(destination_hash)
+        )
+
+        RNS.log(
+            "The announce contained the following app data: "+
+            app_data.decode("utf-8")
+        )
+
+##########################################################
+#### Program Startup #####################################
+##########################################################
+
+# This part of the program gets run at startup,
+# and parses input from the user, and then starts
+# the desired program mode.
+if __name__ == "__main__":
+    try:
+        parser = argparse.ArgumentParser(
+            description="Reticulum example that demonstrates announces and announce handlers"
+        )
+
+        parser.add_argument(
+            "--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
+
+        args = parser.parse_args()
+
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        program_setup(configarg)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()

Examples/Broadcast.py

@@ -11,7 +11,7 @@ import RNS
 # destinations we create. Since this basic example
 # is part of a range of example utilities, we'll put
 # them all within the app namespace "example_utilities"
-APP_NAME = "example_utilitites"
+APP_NAME = "example_utilities"
 
 # This initialisation is executed when the program is started
 def program_setup(configpath, channel=None):
@@ -28,11 +28,18 @@ def program_setup(configpath, channel=None):
 
     # We create a PLAIN destination. This is an uncencrypted endpoint
     # that anyone can listen to and send information to.
-    broadcast_destination = RNS.Destination(None, RNS.Destination.IN, RNS.Destination.PLAIN, APP_NAME, "broadcast", channel)
+    broadcast_destination = RNS.Destination(
+        None,
+        RNS.Destination.IN,
+        RNS.Destination.PLAIN,
+        APP_NAME,
+        "broadcast",
+        channel
+    )
 
     # We specify a callback that will get called every time
     # the destination receives data.
-    broadcast_destination.packet_callback(packet_callback)
+    broadcast_destination.set_packet_callback(packet_callback)
     
     # Everything's ready!
     # Let's hand over control to the main loop
@@ -46,7 +53,11 @@ def packet_callback(data, packet):
 
 def broadcastLoop(destination):
     # Let the user know that everything is ready
-    RNS.log("Broadcast example "+RNS.prettyhexrep(destination.hash)+" running, enter text and hit enter to broadcast (Ctrl-C to quit)")
+    RNS.log(
+        "Broadcast example "+
+        RNS.prettyhexrep(destination.hash)+
+        " running, enter text and hit enter to broadcast (Ctrl-C to quit)"
+    )
 
     # We enter a loop that runs until the users exits.
     # If the user hits enter, we will send the information
@@ -71,9 +82,26 @@ def broadcastLoop(destination):
 # the program.
 if __name__ == "__main__":
     try:
-        parser = argparse.ArgumentParser(description="Reticulum example that demonstrates sending and receiving unencrypted broadcasts")
-        parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
-        parser.add_argument("--channel", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser = argparse.ArgumentParser(
+            description="Reticulum example demonstrating sending and receiving broadcasts"
+        )
+
+        parser.add_argument(
+            "--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
+
+        parser.add_argument(
+            "--channel",
+            action="store",
+            default=None,
+            help="broadcast channel name",
+            type=str
+        )
+
         args = parser.parse_args()
 
         if args.config:

Examples/Echo.py

@@ -12,7 +12,7 @@ import RNS
 # 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_utilitites"
+APP_NAME = "example_utilities"
 
 
 ##########################################################
@@ -22,6 +22,8 @@ APP_NAME = "example_utilitites"
 # This initialisation is executed when the users chooses
 # to run as a server
 def server(configpath):
+    global reticulum
+
     # We must first initialise Reticulum
     reticulum = RNS.Reticulum(configpath)
     
@@ -34,7 +36,14 @@ def server(configpath):
     # messages. This way the client can send a request and be
     # certain that no-one else than this destination was able
     # to read it. 
-    echo_destination = RNS.Destination(server_identity, RNS.Destination.IN, RNS.Destination.SINGLE, APP_NAME, "echo", "request")
+    echo_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.IN,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "echo",
+        "request"
+    )
 
     # We configure the destination to automatically prove all
     # packets adressed to it. By doing this, RNS will automatically
@@ -45,7 +54,7 @@ def server(configpath):
     # Tell the destination which function in our program to
     # run when a packet is received. We do this so we can
     # print a log message when the server receives a request
-    echo_destination.packet_callback(server_callback)
+    echo_destination.set_packet_callback(server_callback)
 
     # Everything's ready!
     # Let's Wait for client requests or user input
@@ -54,7 +63,11 @@ def server(configpath):
 
 def announceLoop(destination):
     # Let the user know that everything is ready
-    RNS.log("Echo server "+RNS.prettyhexrep(destination.hash)+" running, hit enter to manually send an announce (Ctrl-C to quit)")
+    RNS.log(
+        "Echo server "+
+        RNS.prettyhexrep(destination.hash)+
+        " running, 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
@@ -67,11 +80,32 @@ def announceLoop(destination):
 
 
 def server_callback(message, packet):
+    global reticulum
+    
     # Tell the user that we received an echo request, and
     # that we are going to send a reply to the requester.
     # Sending the proof is handled automatically, since we
     # set up the destination to prove all incoming packets.
-    RNS.log("Received packet from echo client, proof sent")
+
+    reception_stats = ""
+    if reticulum.is_connected_to_shared_instance:
+        reception_rssi = reticulum.get_packet_rssi(packet.packet_hash)
+        reception_snr  = reticulum.get_packet_snr(packet.packet_hash)
+
+        if reception_rssi != None:
+            reception_stats += " [RSSI "+str(reception_rssi)+" dBm]"
+        
+        if reception_snr != None:
+            reception_stats += " [SNR "+str(reception_snr)+" dBm]"
+
+    else:
+        if packet.rssi != None:
+            reception_stats += " [RSSI "+str(packet.rssi)+" dBm]"
+        
+        if packet.snr != None:
+            reception_stats += " [SNR "+str(packet.snr)+" dB]"
+
+    RNS.log("Received packet from echo client, proof sent"+reception_stats)
 
 
 ##########################################################
@@ -81,11 +115,16 @@ def server_callback(message, packet):
 # This initialisation is executed when the users chooses
 # to run as a client
 def client(destination_hexhash, configpath, timeout=None):
+    global reticulum
+    
     # We need a binary representation of the destination
     # hash that was entered on the command line
     try:
         if len(destination_hexhash) != 20:
-            raise ValueError("Destination length is invalid, must be 20 hexadecimal characters (10 bytes)")
+            raise ValueError(
+                "Destination length is invalid, must be 20 hexadecimal characters (10 bytes)"
+            )
+
         destination_hash = bytes.fromhex(destination_hexhash)
     except:
         RNS.log("Invalid destination entered. Check your input!\n")
@@ -100,7 +139,11 @@ def client(destination_hexhash, configpath, timeout=None):
         RNS.loglevel = RNS.LOG_INFO
 
     # Tell the user that the client is ready!
-    RNS.log("Echo client ready, hit enter to send echo request to "+destination_hexhash+" (Ctrl-C to quit)")
+    RNS.log(
+        "Echo client ready, hit enter to send echo request to "+
+        destination_hexhash+
+        " (Ctrl-C to quit)"
+    )
 
     # We enter a loop that runs until the user exits.
     # If the user hits enter, we will try to send an
@@ -111,7 +154,7 @@ def client(destination_hexhash, configpath, timeout=None):
         
         # Let's first check if RNS knows a path to the destination.
         # If it does, we'll load the server identity and create a packet
-        if RNS.Transport.hasPath(destination_hash):
+        if RNS.Transport.has_path(destination_hash):
 
             # To address the server, we need to know it's public
             # key, so we check if Reticulum knows this destination.
@@ -127,13 +170,20 @@ def client(destination_hexhash, configpath, timeout=None):
             # example_utilities.echo.request
             # This matches the naming we specified in the
             # server part of the code.
-            request_destination = RNS.Destination(server_identity, RNS.Destination.OUT, RNS.Destination.SINGLE, APP_NAME, "echo", "request")
+            request_destination = RNS.Destination(
+                server_identity,
+                RNS.Destination.OUT,
+                RNS.Destination.SINGLE,
+                APP_NAME,
+                "echo",
+                "request"
+            )
 
             # The destination is ready, so let's create a packet.
             # We set the destination to the request_destination
             # that was just created, and the only data we add
             # is a random hash.
-            echo_request = RNS.Packet(request_destination, RNS.Identity.getRandomHash())
+            echo_request = RNS.Packet(request_destination, RNS.Identity.get_random_hash())
 
             # Send the packet! If the packet is successfully
             # sent, it will return a PacketReceipt instance.
@@ -145,12 +195,12 @@ def client(destination_hexhash, configpath, timeout=None):
             # the packet times out.
             if timeout != None:
                 packet_receipt.set_timeout(timeout)
-                packet_receipt.timeout_callback(packet_timed_out)
+                packet_receipt.set_timeout_callback(packet_timed_out)
 
             # We can then set a delivery callback on the receipt.
             # This will get automatically called when a proof for
             # this specific packet is received from the destination.
-            packet_receipt.delivery_callback(packet_delivered)
+            packet_receipt.set_delivery_callback(packet_delivered)
 
             # Tell the user that the echo request was sent
             RNS.log("Sent echo request to "+RNS.prettyhexrep(request_destination.hash))
@@ -158,13 +208,15 @@ 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.Transport.requestPath(destination_hash)
+            RNS.Transport.request_path(destination_hash)
 
 # This function is called when our reply destination
 # receives a proof packet.
 def packet_delivered(receipt):
+    global reticulum
+
     if receipt.status == RNS.PacketReceipt.DELIVERED:
-        rtt = receipt.rtt()
+        rtt = receipt.get_rtt()
         if (rtt >= 1):
             rtt = round(rtt, 3)
             rttstring = str(rtt)+" seconds"
@@ -172,7 +224,31 @@ def packet_delivered(receipt):
             rtt = round(rtt*1000, 3)
             rttstring = str(rtt)+" milliseconds"
 
-        RNS.log("Valid reply received from "+RNS.prettyhexrep(receipt.destination.hash)+", round-trip time is "+rttstring)
+        reception_stats = ""
+        if reticulum.is_connected_to_shared_instance:
+            reception_rssi = reticulum.get_packet_rssi(receipt.proof_packet.packet_hash)
+            reception_snr  = reticulum.get_packet_snr(receipt.proof_packet.packet_hash)
+
+            if reception_rssi != None:
+                reception_stats += " [RSSI "+str(reception_rssi)+" dBm]"
+            
+            if reception_snr != None:
+                reception_stats += " [SNR "+str(reception_snr)+" dB]"
+
+        else:
+            if receipt.proof_packet != None:
+                if receipt.proof_packet.rssi != None:
+                    reception_stats += " [RSSI "+str(receipt.proof_packet.rssi)+" dBm]"
+                
+                if receipt.proof_packet.snr != None:
+                    reception_stats += " [SNR "+str(receipt.proof_packet.snr)+" dB]"
+
+        RNS.log(
+            "Valid reply received from "+
+            RNS.prettyhexrep(receipt.destination.hash)+
+            ", round-trip time is "+rttstring+
+            reception_stats
+        )
 
 # This function is called if a packet times out.
 def packet_timed_out(receipt):
@@ -190,10 +266,39 @@ def packet_timed_out(receipt):
 if __name__ == "__main__":
     try:
         parser = argparse.ArgumentParser(description="Simple echo server and client utility")
-        parser.add_argument("-s", "--server", action="store_true", help="wait for incoming packets from clients")
-        parser.add_argument("-t", "--timeout", action="store", metavar="s", default=None, help="set a reply timeout in seconds", type=float)
-        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)
+
+        parser.add_argument(
+            "-s",
+            "--server",
+            action="store_true",
+            help="wait for incoming packets from clients"
+        )
+
+        parser.add_argument(
+            "-t",
+            "--timeout",
+            action="store",
+            metavar="s",
+            default=None,
+            help="set a reply timeout in seconds",
+            type=float
+        )
+
+        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.server:

Examples/Filetransfer.py

@@ -28,7 +28,7 @@ import RNS.vendor.umsgpack as umsgpack
 # 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_utilitites"
+APP_NAME = "example_utilities"
 
 # We'll also define a default timeout, in seconds
 APP_TIMEOUT = 45.0
@@ -54,11 +54,18 @@ def server(configpath, path):
     # 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, "filetransfer", "server")
+    server_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.IN,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "filetransfer",
+        "server"
+    )
 
     # We configure a function that will get called every time
     # a new client creates a link to this destination.
-    server_destination.link_established_callback(client_connected)
+    server_destination.set_link_established_callback(client_connected)
 
     # Everything's ready!
     # Let's Wait for client requests or user input
@@ -95,7 +102,7 @@ def client_connected(link):
     if os.path.isdir(serve_path):
         RNS.log("Client connected, sending file list...")
 
-        link.link_closed_callback(client_disconnected)
+        link.set_link_closed_callback(client_disconnected)
 
         # We pack a list of files for sending in a packet
         data = umsgpack.packb(list_files())
@@ -107,8 +114,8 @@ def client_connected(link):
             list_packet = RNS.Packet(link, data)
             list_receipt = list_packet.send()
             list_receipt.set_timeout(APP_TIMEOUT)
-            list_receipt.delivery_callback(list_delivered)
-            list_receipt.timeout_callback(list_timeout)
+            list_receipt.set_delivery_callback(list_delivered)
+            list_receipt.set_timeout_callback(list_timeout)
         else:
             RNS.log("Too many files in served directory!", RNS.LOG_ERROR)
             RNS.log("You should implement a function to split the filelist over multiple packets.", RNS.LOG_ERROR)
@@ -118,7 +125,7 @@ def client_connected(link):
         # open until the client requests a file. We'll
         # configure a function that get's called when
         # the client sends a packet with a file request.
-        link.packet_callback(client_request)
+        link.set_packet_callback(client_request)
     else:
         RNS.log("Client connected, but served path no longer exists!", RNS.LOG_ERROR)
         link.teardown()
@@ -128,14 +135,25 @@ def client_disconnected(link):
 
 def client_request(message, packet):
     global serve_path
-    filename = message.decode("utf-8")
+
+    try:
+        filename = message.decode("utf-8")
+    except Exception as e:
+        filename = None
+
     if filename in list_files():
         try:
             # If we have the requested file, we'll
             # read it and pack it as a resource
             RNS.log("Client requested \""+filename+"\"")
             file = open(os.path.join(serve_path, filename), "rb")
-            file_resource = RNS.Resource(file, packet.link, callback=resource_sending_concluded)
+            
+            file_resource = RNS.Resource(
+                file,
+                packet.link,
+                callback=resource_sending_concluded
+            )
+
             file_resource.filename = filename
         except Exception as e:
             # If somethign went wrong, we close
@@ -209,10 +227,10 @@ def client(destination_hexhash, configpath):
 
 
     # Check if we know a path to the destination
-    if not RNS.Transport.hasPath(destination_hash):
+    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.requestPath(destination_hash)
-        while not RNS.Transport.hasPath(destination_hash):
+        RNS.Transport.request_path(destination_hash)
+        while not RNS.Transport.has_path(destination_hash):
             time.sleep(0.1)
 
     # Recall the server identity
@@ -223,7 +241,14 @@ def client(destination_hexhash, configpath):
 
     # 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, "filetransfer", "server")
+    server_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.OUT,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "filetransfer",
+        "server"
+    )
 
     # We also want to automatically prove incoming packets
     server_destination.set_proof_strategy(RNS.Destination.PROVE_ALL)
@@ -234,18 +259,18 @@ def client(destination_hexhash, configpath):
     # We expect any normal data packets on the link
     # to contain a list of served files, so we set
     # a callback accordingly
-    link.packet_callback(filelist_received)
+    link.set_packet_callback(filelist_received)
 
     # We'll also set up functions to inform the
     # user when the link is established or closed
-    link.link_established_callback(link_established)
-    link.link_closed_callback(link_closed)
+    link.set_link_established_callback(link_established)
+    link.set_link_closed_callback(link_closed)
 
     # And set the link to automatically begin
     # downloading advertised resources
     link.set_resource_strategy(RNS.Link.ACCEPT_ALL)
-    link.resource_started_callback(download_began)
-    link.resource_concluded_callback(download_concluded)
+    link.set_resource_started_callback(download_began)
+    link.set_resource_concluded_callback(download_concluded)
 
     menu()
 
@@ -333,7 +358,7 @@ def print_menu():
         print("")
         while menu_mode == "downloading":
             global current_download
-            percent = round(current_download.progress() * 100.0, 1)
+            percent = round(current_download.get_progress() * 100.0, 1)
             print(("\rProgress: "+str(percent)+" %   "), end=' ')
             sys.stdout.flush()
             time.sleep(0.1)
@@ -477,7 +502,6 @@ def download_concluded(resource):
 
     saved_filename = current_filename
 
-
     if resource.status == RNS.Resource.COMPLETE:
         counter = 0
         while os.path.isfile(saved_filename):
@@ -524,10 +548,34 @@ def clear_screen():
 # starts up the desired program mode.
 if __name__ == "__main__":
     try:
-        parser = argparse.ArgumentParser(description="Simple file transfer server and client utility")
-        parser.add_argument("-s", "--serve", action="store", metavar="dir", help="serve a directory of files to 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)
+        parser = argparse.ArgumentParser(
+            description="Simple file transfer server and client utility"
+        )
+
+        parser.add_argument(
+            "-s",
+            "--serve",
+            action="store",
+            metavar="dir",
+            help="serve a directory of files to 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:

Examples/Identify.py

@@ -0,0 +1,310 @@
+##########################################################
+# This RNS example demonstrates how to set up a link to  #
+# a destination, and identify the initiator to it's peer #
+##########################################################
+
+import os
+import sys
+import time
+import argparse
+import RNS
+
+# 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
+
+# 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,
+        "identifyexample"
+    )
+
+    # 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 identification 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
+
+    RNS.log("Client connected")
+    link.set_link_closed_callback(client_disconnected)
+    link.set_packet_callback(server_packet_received)
+    link.set_remote_identified_callback(remote_identified)
+    latest_client_link = link
+
+def client_disconnected(link):
+    RNS.log("Client disconnected")
+
+def remote_identified(identity):
+    RNS.log("Remote identified as: "+str(identity))
+
+def server_packet_received(message, packet):
+    global latest_client_link
+
+    # Get the originating identity for display
+    remote_peer =  "unidentified peer"
+    if packet.link.get_remote_identity() != None:
+        remote_peer = str(packet.link.get_remote_identity())
+
+    # When data is received over any active link,
+    # it will all be directed to the last client
+    # that connected.
+    text = message.decode("utf-8")
+
+    RNS.log("Received data from "+remote_peer+": "+text)
+    
+    reply_text = "I received \""+text+"\" over the link from "+remote_peer
+    reply_data = reply_text.encode("utf-8")
+    RNS.Packet(latest_client_link, reply_data).send()
+
+
+##########################################################
+#### Client Part #########################################
+##########################################################
+
+# A reference to the server link
+server_link = None
+
+# A reference to the client identity
+client_identity = None
+
+# This initialisation is executed when the users chooses
+# to run as a client
+def client(destination_hexhash, configpath):
+    global client_identity
+    # We need a binary representation of the destination
+    # hash that was entered on the command line
+    try:
+        if len(destination_hexhash) != 20:
+            raise ValueError("Destination length is invalid, must be 20 hexadecimal characters (10 bytes)")
+        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)
+
+    # Create a new client identity
+    client_identity = RNS.Identity()
+    RNS.log(
+        "Client created new identity "+
+        str(client_identity)
+    )
+
+    # 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,
+        "identifyexample"
+    )
+
+    # And create a link
+    link = RNS.Link(server_destination)
+
+    # We set a callback that will get executed
+    # every time a packet is received over the
+    # link
+    link.set_packet_callback(client_packet_received)
+
+    # 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 != "":
+                data = text.encode("utf-8")
+                if len(data) <= RNS.Link.MDU:
+                    RNS.Packet(server_link, data).send()
+                else:
+                    RNS.log(
+                        "Cannot send this packet, the data size of "+
+                        str(len(data))+" bytes exceeds the link packet MDU of "+
+                        str(RNS.Link.MDU)+" bytes",
+                        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, client_identity
+    server_link = link
+
+    # Inform the user that the server is
+    # connected
+    RNS.log("Link established with server, identifying to remote peer...")
+
+    link.identify(client_identity)
+
+# 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 link, we
+# simply print out the data.
+def client_packet_received(message, packet):
+    text = message.decode("utf-8")
+    RNS.log("Received data on the link: "+text)
+    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 link 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/Link.py

@@ -13,7 +13,7 @@ import RNS
 # 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_utilitites"
+APP_NAME = "example_utilities"
 
 ##########################################################
 #### Server Part #########################################
@@ -34,11 +34,17 @@ def server(configpath):
     # 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, "linkexample")
+    server_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.IN,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "linkexample"
+    )
 
     # We configure a function that will get called every time
     # a new client creates a link to this destination.
-    server_destination.link_established_callback(client_connected)
+    server_destination.set_link_established_callback(client_connected)
 
     # Everything's ready!
     # Let's Wait for client requests or user input
@@ -46,7 +52,12 @@ def server(configpath):
 
 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(
+        "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.
@@ -65,8 +76,8 @@ def client_connected(link):
     global latest_client_link
 
     RNS.log("Client connected")
-    link.link_closed_callback(client_disconnected)
-    link.packet_callback(server_packet_received)
+    link.set_link_closed_callback(client_disconnected)
+    link.set_packet_callback(server_packet_received)
     latest_client_link = link
 
 def client_disconnected(link):
@@ -110,10 +121,10 @@ def client(destination_hexhash, configpath):
     reticulum = RNS.Reticulum(configpath)
 
     # Check if we know a path to the destination
-    if not RNS.Transport.hasPath(destination_hash):
+    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.requestPath(destination_hash)
-        while not RNS.Transport.hasPath(destination_hash):
+        RNS.Transport.request_path(destination_hash)
+        while not RNS.Transport.has_path(destination_hash):
             time.sleep(0.1)
 
     # Recall the server identity
@@ -124,7 +135,13 @@ def client(destination_hexhash, configpath):
 
     # 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, "linkexample")
+    server_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.OUT,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "linkexample"
+    )
 
     # And create a link
     link = RNS.Link(server_destination)
@@ -132,12 +149,12 @@ def client(destination_hexhash, configpath):
     # We set a callback that will get executed
     # every time a packet is received over the
     # link
-    link.packet_callback(client_packet_received)
+    link.set_packet_callback(client_packet_received)
 
     # We'll also set up functions to inform the
     # user when the link is established or closed
-    link.link_established_callback(link_established)
-    link.link_closed_callback(link_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
@@ -164,8 +181,18 @@ def client_loop():
             # If not, send the entered text over the link
             if text != "":
                 data = text.encode("utf-8")
-                RNS.Packet(server_link, data).send()
+                if len(data) <= RNS.Link.MDU:
+                    RNS.Packet(server_link, data).send()
+                else:
+                    RNS.log(
+                        "Cannot send this packet, the data size of "+
+                        str(len(data))+" bytes exceeds the link packet MDU of "+
+                        str(RNS.Link.MDU)+" bytes",
+                        RNS.LOG_ERROR
+                    )
+
         except Exception as e:
+            RNS.log("Error while sending data over the link: "+str(e))
             should_quit = True
             server_link.teardown()
 
@@ -214,9 +241,30 @@ def client_packet_received(message, packet):
 if __name__ == "__main__":
     try:
         parser = argparse.ArgumentParser(description="Simple link 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)
+
+        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:

Examples/Minimal.py

@@ -11,7 +11,7 @@ import RNS
 # destinations we create. Since this basic example
 # is part of a range of example utilities, we'll put
 # them all within the app namespace "example_utilities"
-APP_NAME = "example_utilitites"
+APP_NAME = "example_utilities"
 
 # This initialisation is executed when the program is started
 def program_setup(configpath):
@@ -27,7 +27,13 @@ def program_setup(configpath):
     # existence, which will let the network know they are reachable
     # and autoomatically create paths to them, from anywhere else
     # in the network.
-    destination = RNS.Destination(identity, RNS.Destination.IN, RNS.Destination.SINGLE, APP_NAME, "minimalsample")
+    destination = RNS.Destination(
+        identity,
+        RNS.Destination.IN,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "minimalsample"
+    )
 
     # We configure the destination to automatically prove all
     # packets adressed to it. By doing this, RNS will automatically
@@ -44,7 +50,11 @@ def program_setup(configpath):
 
 def announceLoop(destination):
     # Let the user know that everything is ready
-    RNS.log("Minimal example "+RNS.prettyhexrep(destination.hash)+" running, hit enter to manually send an announce (Ctrl-C to quit)")
+    RNS.log(
+        "Minimal example "+
+        RNS.prettyhexrep(destination.hash)+
+        " running, 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
@@ -65,8 +75,18 @@ def announceLoop(destination):
 # the desired program mode.
 if __name__ == "__main__":
     try:
-        parser = argparse.ArgumentParser(description="Bare minimum example to start Reticulum and create a destination")
-        parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser = argparse.ArgumentParser(
+            description="Minimal example to start Reticulum and create a destination"
+        )
+
+        parser.add_argument(
+            "--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
+
         args = parser.parse_args()
 
         if args.config:

Examples/Request.py

@@ -0,0 +1,283 @@
+##########################################################
+# This RNS example demonstrates how to set perform       #
+# requests and receive responses over a link.            #
+##########################################################
+
+import os
+import sys
+import time
+import random
+import argparse
+import RNS
+
+# 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
+
+def random_text_generator(path, data, request_id, remote_identity, requested_at):
+    RNS.log("Generating response to request "+RNS.prettyhexrep(request_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)]
+
+# 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,
+        "requestexample"
+    )
+
+    # 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)
+
+    # We register a request handler for handling incoming
+    # requests over any established links.
+    server_destination.register_request_handler(
+        "/random/text",
+        response_generator = random_text_generator,
+        allow = RNS.Destination.ALLOW_ALL
+    )
+
+    # 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(
+        "Request 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
+
+    RNS.log("Client connected")
+    link.set_link_closed_callback(client_disconnected)
+    latest_client_link = link
+
+def client_disconnected(link):
+    RNS.log("Client disconnected")
+
+
+##########################################################
+#### 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:
+        if len(destination_hexhash) != 20:
+            raise ValueError("Destination length is invalid, must be 20 hexadecimal characters (10 bytes)")
+        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,
+        "requestexample"
+    )
+
+    # And create a link
+    link = RNS.Link(server_destination)
+
+    # We'll 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:
+                server_link.request(
+                    "/random/text",
+                    data = None,
+                    response_callback = got_response,
+                    failed_callback = request_failed
+                )
+
+
+        except Exception as e:
+            RNS.log("Error while sending request over the link: "+str(e))
+            should_quit = True
+            server_link.teardown()
+
+def got_response(request_receipt):
+    request_id = request_receipt.request_id
+    response = request_receipt.response
+
+    RNS.log("Got response for request "+RNS.prettyhexrep(request_id)+": "+str(response))
+
+def request_received(request_receipt):
+    RNS.log("The request "+RNS.prettyhexrep(request_receipt.request_id)+" was received by the remote peer.")
+
+def request_failed(request_receipt):
+    RNS.log("The request "+RNS.prettyhexrep(request_receipt.request_id)+" failed.")
+
+
+# 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
+
+    # Inform the user that the server is
+    # connected
+    RNS.log("Link established with server, hit enter to perform a request, or type in \"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)
+
+
+##########################################################
+#### 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 request/response example")
+
+        parser.add_argument(
+            "-s",
+            "--server",
+            action="store_true",
+            help="wait for incoming 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/Speedtest.py

@@ -0,0 +1,337 @@
+##########################################################
+# This RNS example demonstrates a simple speedtest       #
+# program to measure link throughput.                    #
+##########################################################
+
+import os
+import sys
+import time
+import argparse
+import RNS
+
+# Let's define an app name. We'll use this for all
+# destinations we create.
+APP_NAME = "example_utilities"
+
+##########################################################
+#### Server Part #########################################
+##########################################################
+
+latest_client_link = None
+first_packet_at = None
+last_packet_at = None
+received_data = 0
+rc = 0
+data_cap = 2*1024*1024
+printed = False
+
+# 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,
+        "speedtest"
+    )
+
+    # 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(
+        "Speedtest "+
+        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, first_packet_at, rc
+
+    RNS.log("Client connected")
+    first_packet_at = time.time()
+    rc = 0
+    link.set_link_closed_callback(client_disconnected)
+    link.set_packet_callback(server_packet_received)
+    latest_client_link = link
+
+def client_disconnected(link):
+    RNS.log("Client disconnected")
+
+
+# A convenience function for printing a human-
+# readable file size
+def size_str(num, suffix='B'):
+    units = ['','Ki','Mi','Gi','Ti','Pi','Ei','Zi']
+    last_unit = 'Yi'
+
+    if suffix == 'b':
+        num *= 8
+        units = ['','K','M','G','T','P','E','Z']
+        last_unit = 'Y'
+
+    for unit in units:
+        if abs(num) < 1024.0:
+            return "%3.2f %s%s" % (num, unit, suffix)
+        num /= 1024.0
+    return "%.2f %s%s" % (num, last_unit, suffix)
+
+
+def server_packet_received(message, packet):
+    global latest_client_link, first_packet_at, last_packet_at, received_data, rc, data_cap
+    
+    received_data += len(packet.data)
+    
+    rc += 1
+    if rc >= 50:
+        RNS.log(size_str(received_data))
+        rc = 0
+
+    if received_data > data_cap:
+        rcv_d = received_data
+        received_data = 0
+        rc = 0
+
+        last_packet_at = time.time()
+        
+        # Print statistics
+        download_time = last_packet_at-first_packet_at
+        hours, rem = divmod(download_time, 3600)
+        minutes, seconds = divmod(rem, 60)
+        timestring = "{:0>2}:{:0>2}:{:05.2f}".format(int(hours),int(minutes),seconds)
+
+        print("")
+        print("")
+        print("--- Statistics -----")
+        print("\tTime taken       : "+timestring)
+        print("\tData transferred : "+size_str(rcv_d))
+        print("\tTransfer rate    : "+size_str(rcv_d/download_time, suffix='b')+"/s")
+        print("")
+
+        sys.stdout.flush()
+        latest_client_link.teardown()
+        time.sleep(0.2)
+        rc = 0
+        received_data = 0
+        # latest_client_link.teardown()
+        # os._exit(0)
+
+
+##########################################################
+#### 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:
+        if len(destination_hexhash) != 20:
+            raise ValueError("Destination length is invalid, must be 20 hexadecimal characters (10 bytes)")
+        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,
+        "speedtest"
+    )
+
+    # 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:
+            text = input()
+
+            # Check if we should quit the example
+            if text == "quit" or text == "q" or text == "exit":
+                should_quit = True
+                server_link.teardown()
+
+        except Exception as e:
+            raise e
+
+# 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, data_cap, printed
+    server_link = link
+    data_sent = 0
+
+    # Inform the user that the server is
+    # connected
+    RNS.log("Link established with server,sending...")
+    rd = os.urandom(RNS.Link.MDU)
+    started = time.time()
+    while link.status == RNS.Link.ACTIVE and data_sent < data_cap*1.25:
+        RNS.Packet(server_link, rd, create_receipt=False).send()
+        data_sent += len(rd)
+
+        if data_sent > data_cap and not printed:
+            printed = True
+            ended = time.time()
+            # Print statistics
+            download_time = ended-started
+            hours, rem = divmod(download_time, 3600)
+            minutes, seconds = divmod(rem, 60)
+            timestring = "{:0>2}:{:0>2}:{:05.2f}".format(int(hours),int(minutes),seconds)
+            print("")
+            print("")
+            print("--- Statistics -----")
+            print("\tTime taken       : "+timestring)
+            print("\tData transferred : "+size_str(data_sent))
+            print("\tTransfer rate    : "+size_str(data_sent/download_time, suffix='b')+"/s")
+            print("")
+
+            sys.stdout.flush()
+            time.sleep(0.1)
+
+
+# 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)
+
+def client_packet_received(message, packet):
+    pass
+
+##########################################################
+#### 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="Speedtest example")
+
+        parser.add_argument(
+            "-s",
+            "--server",
+            action="store_true",
+            help="wait for incoming 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()

Notes/Wire Format

@@ -1,54 +0,0 @@
-Reticulum Wire Format
-
-Header Types
------------------
-type 1          00  Two byte header, one 10 byte address field
-type 2          01  Two byte header, two 10 byte address fields
-type 3          10  Reserved
-type 4          11  Reserved
-
-
-Propagation Types
------------------
-broadcast       00
-transport       01
-reserved        10
-reserved        11
-
-
-Destination Types
------------------
-single          00
-group           01
-plain           10
-link            11
-
-
-Packet Types
------------------
-data            00
-announce        01
-link request    10
-proof           11
-
-
-+- Packet Example -+
-
-01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
- | | | |    |
- | | | |    +-- Hops = 4
- | | | +------- DATA packet
- | | +--------- SINGLE destination
- | +----------- TRANSPORT propagation type
- +------------- HEADER_2, two byte header, two address fields
-
-
- +- Packet Example -+
-
-00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]
- | | | |    |
- | | | |    +-- Hops = 7
- | | | +------- DATA packet
- | | +--------- SINGLE destination
- | +----------- BROADCAST propagation type
- +------------- HEADER_1, two byte header, one address field

README.html

@@ -1,848 +0,0 @@
-<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>@font-face {
-  font-family: octicons-anchor;
-  src: url(https://cdnjs.cloudflare.com/ajax/libs/octicons/4.4.0/font/octicons.woff) format('woff');
-}
-
-* {
-    box-sizing: border-box;
-}
-
-body {
-    width: 980px;
-    margin-right: auto;
-    margin-left: auto;
-    color:#333;
-    background:#fff;
-}
-
-body .markdown-body {
-    padding: 45px;
-    border: 1px solid #ddd;
-    border-radius: 3px;
-    word-wrap: break-word;
-}
-
-pre {
-    font: 12px Consolas, "Liberation Mono", Menlo, Courier, monospace;
-}
-
-.markdown-body {
-  -webkit-text-size-adjust: 100%;
-  text-size-adjust: 100%;
-  color: #333;
-  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
-  font-size: 16px;
-  line-height: 1.6;
-  word-wrap: break-word;
-}
-
-.markdown-body a {
-  background-color: transparent;
-}
-
-.markdown-body a:active,
-.markdown-body a:hover {
-  outline: 0;
-}
-
-.markdown-body strong {
-  font-weight: bold;
-}
-
-.markdown-body h1 {
-  font-size: 2em;
-  margin: 0.67em 0;
-}
-
-.markdown-body img {
-  border: 0;
-}
-
-.markdown-body hr {
-  box-sizing: content-box;
-  height: 0;
-}
-
-.markdown-body pre {
-  overflow: auto;
-}
-
-.markdown-body code,
-.markdown-body kbd,
-.markdown-body pre {
-  font-family: monospace, monospace;
-  font-size: 1em;
-}
-
-.markdown-body input {
-  color: inherit;
-  font: inherit;
-  margin: 0;
-}
-
-.markdown-body html input[disabled] {
-  cursor: default;
-}
-
-.markdown-body input {
-  line-height: normal;
-}
-
-.markdown-body input[type="checkbox"] {
-  box-sizing: border-box;
-  padding: 0;
-}
-
-.markdown-body table {
-  border-collapse: collapse;
-  border-spacing: 0;
-}
-
-.markdown-body td,
-.markdown-body th {
-  padding: 0;
-}
-
-.markdown-body input {
-  font: 13px / 1.4 Helvetica, arial, nimbussansl, liberationsans, freesans, clean, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
-}
-
-.markdown-body a {
-  color: #4078c0;
-  text-decoration: none;
-}
-
-.markdown-body a:hover,
-.markdown-body a:active {
-  text-decoration: underline;
-}
-
-.markdown-body hr {
-  height: 0;
-  margin: 15px 0;
-  overflow: hidden;
-  background: transparent;
-  border: 0;
-  border-bottom: 1px solid #ddd;
-}
-
-.markdown-body hr:before {
-  display: table;
-  content: "";
-}
-
-.markdown-body hr:after {
-  display: table;
-  clear: both;
-  content: "";
-}
-
-.markdown-body h1,
-.markdown-body h2,
-.markdown-body h3,
-.markdown-body h4,
-.markdown-body h5,
-.markdown-body h6 {
-  margin-top: 15px;
-  margin-bottom: 15px;
-  line-height: 1.1;
-}
-
-.markdown-body h1 {
-  font-size: 30px;
-}
-
-.markdown-body h2 {
-  font-size: 21px;
-}
-
-.markdown-body h3 {
-  font-size: 16px;
-}
-
-.markdown-body h4 {
-  font-size: 14px;
-}
-
-.markdown-body h5 {
-  font-size: 12px;
-}
-
-.markdown-body h6 {
-  font-size: 11px;
-}
-
-.markdown-body blockquote {
-  margin: 0;
-}
-
-.markdown-body ul,
-.markdown-body ol {
-  padding: 0;
-  margin-top: 0;
-  margin-bottom: 0;
-}
-
-.markdown-body ol ol,
-.markdown-body ul ol {
-  list-style-type: lower-roman;
-}
-
-.markdown-body ul ul ol,
-.markdown-body ul ol ol,
-.markdown-body ol ul ol,
-.markdown-body ol ol ol {
-  list-style-type: lower-alpha;
-}
-
-.markdown-body dd {
-  margin-left: 0;
-}
-
-.markdown-body code {
-  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
-  font-size: 12px;
-}
-
-.markdown-body pre {
-  margin-top: 0;
-  margin-bottom: 0;
-  font: 12px Consolas, "Liberation Mono", Menlo, Courier, monospace;
-}
-
-.markdown-body .select::-ms-expand {
-  opacity: 0;
-}
-
-.markdown-body .octicon {
-  font: normal normal normal 16px/1 octicons-anchor;
-  display: inline-block;
-  text-decoration: none;
-  text-rendering: auto;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-  -webkit-user-select: none;
-  -moz-user-select: none;
-  -ms-user-select: none;
-  user-select: none;
-}
-
-.markdown-body .octicon-link:before {
-  content: '\f05c';
-}
-
-.markdown-body:before {
-  display: table;
-  content: "";
-}
-
-.markdown-body:after {
-  display: table;
-  clear: both;
-  content: "";
-}
-
-.markdown-body>*:first-child {
-  margin-top: 0 !important;
-}
-
-.markdown-body>*:last-child {
-  margin-bottom: 0 !important;
-}
-
-.markdown-body a:not([href]) {
-  color: inherit;
-  text-decoration: none;
-}
-
-.markdown-body .anchor {
-  display: inline-block;
-  padding-right: 2px;
-  margin-left: -18px;
-}
-
-.markdown-body .anchor:focus {
-  outline: none;
-}
-
-.markdown-body h1,
-.markdown-body h2,
-.markdown-body h3,
-.markdown-body h4,
-.markdown-body h5,
-.markdown-body h6 {
-  margin-top: 1em;
-  margin-bottom: 16px;
-  font-weight: bold;
-  line-height: 1.4;
-}
-
-.markdown-body h1 .octicon-link,
-.markdown-body h2 .octicon-link,
-.markdown-body h3 .octicon-link,
-.markdown-body h4 .octicon-link,
-.markdown-body h5 .octicon-link,
-.markdown-body h6 .octicon-link {
-  color: #000;
-  vertical-align: middle;
-  visibility: hidden;
-}
-
-.markdown-body h1:hover .anchor,
-.markdown-body h2:hover .anchor,
-.markdown-body h3:hover .anchor,
-.markdown-body h4:hover .anchor,
-.markdown-body h5:hover .anchor,
-.markdown-body h6:hover .anchor {
-  text-decoration: none;
-}
-
-.markdown-body h1:hover .anchor .octicon-link,
-.markdown-body h2:hover .anchor .octicon-link,
-.markdown-body h3:hover .anchor .octicon-link,
-.markdown-body h4:hover .anchor .octicon-link,
-.markdown-body h5:hover .anchor .octicon-link,
-.markdown-body h6:hover .anchor .octicon-link {
-  visibility: visible;
-}
-
-.markdown-body h1 {
-  padding-bottom: 0.3em;
-  font-size: 2.25em;
-  line-height: 1.2;
-  border-bottom: 1px solid #eee;
-}
-
-.markdown-body h1 .anchor {
-  line-height: 1;
-}
-
-.markdown-body h2 {
-  padding-bottom: 0.3em;
-  font-size: 1.75em;
-  line-height: 1.225;
-  border-bottom: 1px solid #eee;
-}
-
-.markdown-body h2 .anchor {
-  line-height: 1;
-}
-
-.markdown-body h3 {
-  font-size: 1.5em;
-  line-height: 1.43;
-}
-
-.markdown-body h3 .anchor {
-  line-height: 1.2;
-}
-
-.markdown-body h4 {
-  font-size: 1.25em;
-}
-
-.markdown-body h4 .anchor {
-  line-height: 1.2;
-}
-
-.markdown-body h5 {
-  font-size: 1em;
-}
-
-.markdown-body h5 .anchor {
-  line-height: 1.1;
-}
-
-.markdown-body h6 {
-  font-size: 1em;
-  color: #777;
-}
-
-.markdown-body h6 .anchor {
-  line-height: 1.1;
-}
-
-.markdown-body p,
-.markdown-body blockquote,
-.markdown-body ul,
-.markdown-body ol,
-.markdown-body dl,
-.markdown-body table,
-.markdown-body pre {
-  margin-top: 0;
-  margin-bottom: 16px;
-}
-
-.markdown-body hr {
-  height: 4px;
-  padding: 0;
-  margin: 16px 0;
-  background-color: #e7e7e7;
-  border: 0 none;
-}
-
-.markdown-body ul,
-.markdown-body ol {
-  padding-left: 2em;
-}
-
-.markdown-body ul ul,
-.markdown-body ul ol,
-.markdown-body ol ol,
-.markdown-body ol ul {
-  margin-top: 0;
-  margin-bottom: 0;
-}
-
-.markdown-body li>p {
-  margin-top: 16px;
-}
-
-.markdown-body dl {
-  padding: 0;
-}
-
-.markdown-body dl dt {
-  padding: 0;
-  margin-top: 16px;
-  font-size: 1em;
-  font-style: italic;
-  font-weight: bold;
-}
-
-.markdown-body dl dd {
-  padding: 0 16px;
-  margin-bottom: 16px;
-}
-
-.markdown-body blockquote {
-  padding: 0 15px;
-  color: #777;
-  border-left: 4px solid #ddd;
-}
-
-.markdown-body blockquote>:first-child {
-  margin-top: 0;
-}
-
-.markdown-body blockquote>:last-child {
-  margin-bottom: 0;
-}
-
-.markdown-body table {
-  display: block;
-  width: 100%;
-  overflow: auto;
-  word-break: normal;
-  word-break: keep-all;
-}
-
-.markdown-body table th {
-  font-weight: bold;
-}
-
-.markdown-body table th,
-.markdown-body table td {
-  padding: 6px 13px;
-  border: 1px solid #ddd;
-}
-
-.markdown-body table tr {
-  background-color: #fff;
-  border-top: 1px solid #ccc;
-}
-
-.markdown-body table tr:nth-child(2n) {
-  background-color: #f8f8f8;
-}
-
-.markdown-body img {
-  max-width: 100%;
-  box-sizing: content-box;
-  background-color: #fff;
-}
-
-.markdown-body code {
-  padding: 0;
-  padding-top: 0.2em;
-  padding-bottom: 0.2em;
-  margin: 0;
-  font-size: 85%;
-  background-color: rgba(0,0,0,0.04);
-  border-radius: 3px;
-}
-
-.markdown-body code:before,
-.markdown-body code:after {
-  letter-spacing: -0.2em;
-  content: "\00a0";
-}
-
-.markdown-body pre>code {
-  padding: 0;
-  margin: 0;
-  font-size: 100%;
-  word-break: normal;
-  white-space: pre;
-  background: transparent;
-  border: 0;
-}
-
-.markdown-body .highlight {
-  margin-bottom: 16px;
-}
-
-.markdown-body .highlight pre,
-.markdown-body pre {
-  padding: 16px;
-  overflow: auto;
-  font-size: 85%;
-  line-height: 1.45;
-  background-color: #f7f7f7;
-  border-radius: 3px;
-}
-
-.markdown-body .highlight pre {
-  margin-bottom: 0;
-  word-break: normal;
-}
-
-.markdown-body pre {
-  word-wrap: normal;
-}
-
-.markdown-body pre code {
-  display: inline;
-  max-width: initial;
-  padding: 0;
-  margin: 0;
-  overflow: initial;
-  line-height: inherit;
-  word-wrap: normal;
-  background-color: transparent;
-  border: 0;
-}
-
-.markdown-body pre code:before,
-.markdown-body pre code:after {
-  content: normal;
-}
-
-.markdown-body kbd {
-  display: inline-block;
-  padding: 3px 5px;
-  font-size: 11px;
-  line-height: 10px;
-  color: #555;
-  vertical-align: middle;
-  background-color: #fcfcfc;
-  border: solid 1px #ccc;
-  border-bottom-color: #bbb;
-  border-radius: 3px;
-  box-shadow: inset 0 -1px 0 #bbb;
-}
-
-.markdown-body .pl-c {
-  color: #969896;
-}
-
-.markdown-body .pl-c1,
-.markdown-body .pl-s .pl-v {
-  color: #0086b3;
-}
-
-.markdown-body .pl-e,
-.markdown-body .pl-en {
-  color: #795da3;
-}
-
-.markdown-body .pl-s .pl-s1,
-.markdown-body .pl-smi {
-  color: #333;
-}
-
-.markdown-body .pl-ent {
-  color: #63a35c;
-}
-
-.markdown-body .pl-k {
-  color: #a71d5d;
-}
-
-.markdown-body .pl-pds,
-.markdown-body .pl-s,
-.markdown-body .pl-s .pl-pse .pl-s1,
-.markdown-body .pl-sr,
-.markdown-body .pl-sr .pl-cce,
-.markdown-body .pl-sr .pl-sra,
-.markdown-body .pl-sr .pl-sre {
-  color: #183691;
-}
-
-.markdown-body .pl-v {
-  color: #ed6a43;
-}
-
-.markdown-body .pl-id {
-  color: #b52a1d;
-}
-
-.markdown-body .pl-ii {
-  background-color: #b52a1d;
-  color: #f8f8f8;
-}
-
-.markdown-body .pl-sr .pl-cce {
-  color: #63a35c;
-  font-weight: bold;
-}
-
-.markdown-body .pl-ml {
-  color: #693a17;
-}
-
-.markdown-body .pl-mh,
-.markdown-body .pl-mh .pl-en,
-.markdown-body .pl-ms {
-  color: #1d3e81;
-  font-weight: bold;
-}
-
-.markdown-body .pl-mq {
-  color: #008080;
-}
-
-.markdown-body .pl-mi {
-  color: #333;
-  font-style: italic;
-}
-
-.markdown-body .pl-mb {
-  color: #333;
-  font-weight: bold;
-}
-
-.markdown-body .pl-md {
-  background-color: #ffecec;
-  color: #bd2c00;
-}
-
-.markdown-body .pl-mi1 {
-  background-color: #eaffea;
-  color: #55a532;
-}
-
-.markdown-body .pl-mdr {
-  color: #795da3;
-  font-weight: bold;
-}
-
-.markdown-body .pl-mo {
-  color: #1d3e81;
-}
-
-.markdown-body kbd {
-  display: inline-block;
-  padding: 3px 5px;
-  font: 11px Consolas, "Liberation Mono", Menlo, Courier, monospace;
-  line-height: 10px;
-  color: #555;
-  vertical-align: middle;
-  background-color: #fcfcfc;
-  border: solid 1px #ccc;
-  border-bottom-color: #bbb;
-  border-radius: 3px;
-  box-shadow: inset 0 -1px 0 #bbb;
-}
-
-.markdown-body .plan-price-unit {
-  color: #767676;
-  font-weight: normal;
-}
-
-.markdown-body .task-list-item {
-  list-style-type: none;
-}
-
-.markdown-body .task-list-item+.task-list-item {
-  margin-top: 3px;
-}
-
-.markdown-body .task-list-item input {
-  margin: 0 0.35em 0.25em -1.6em;
-  vertical-align: middle;
-}
-
-.markdown-body .plan-choice {
-  padding: 15px;
-  padding-left: 40px;
-  display: block;
-  border: 1px solid #e0e0e0;
-  position: relative;
-  font-weight: normal;
-  background-color: #fafafa;
-}
-
-.markdown-body .plan-choice.open {
-  background-color: #fff;
-}
-
-.markdown-body .plan-choice.open .plan-choice-seat-breakdown {
-  display: block;
-}
-
-.markdown-body .plan-choice-free {
-  border-radius: 3px 3px 0 0;
-}
-
-.markdown-body .plan-choice-paid {
-  border-radius: 0 0 3px 3px;
-  border-top: 0;
-  margin-bottom: 20px;
-}
-
-.markdown-body .plan-choice-radio {
-  position: absolute;
-  left: 15px;
-  top: 18px;
-}
-
-.markdown-body .plan-choice-exp {
-  color: #999;
-  font-size: 12px;
-  margin-top: 5px;
-}
-
-.markdown-body .plan-choice-seat-breakdown {
-  margin-top: 10px;
-  display: none;
-}
-
-.markdown-body :checked+.radio-label {
-  z-index: 1;
-  position: relative;
-  border-color: #4078c0;
-}
-
-@media print {
-  body .markdown-body {
-    padding: 0;
-    border: none;
-  }
-}
-</style><title>README</title></head><body><article class="markdown-body"><h1>
-<a id="user-content-reticulum-network-stack-α" class="anchor" href="#reticulum-network-stack-%CE%B1" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Reticulum Network Stack α</h1>
-<p>Reticulum is a cryptography-based networking stack for wide-area networks built on readily available hardware, and can operate even with very high latency and extremely low bandwidth. Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more.</p>
-<p>Reticulum is a complete networking stack, and does not use IP or higher layers, although it is easy to utilise IP (with TCP or UDP) as the underlying carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks.</p>
-<p>Having no dependencies on traditional networking stacks free up overhead that has been utilised to implement a networking stack built directly on cryptographic principles, allowing resilience and stable functionality in open and trustless networks.</p>
-<p>No kernel modules or drivers are required. Reticulum runs completely in userland, and can run on practically any system that runs Python 3.</p>
-<p>For more info, see <a href="https://unsigned.io/projects/reticulum/" rel="nofollow">unsigned.io/projects/reticulum</a></p>
-<h2>
-<a id="user-content-notable-features" class="anchor" href="#notable-features" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Notable Features</h2>
-<ul>
-<li>Coordination-less globally unique adressing and identification</li>
-<li>Fully self-configuring multi-hop routing</li>
-<li>Asymmetric RSA encryption and signatures as basis for all communication</li>
-<li>Perfect Forward Secrecy on links with ephemereal Elliptic Curve Diffie-Hellman keys (on the SECP256R1 curve)</li>
-<li>Reticulum uses the <a href="https://github.com/fernet/spec/blob/master/Spec.md">Fernet</a> specification for encryption on links and to group destinations
-<ul>
-<li>AES-128 in CBC mode with PKCS7 padding</li>
-<li>HMAC using SHA256 for authentication</li>
-<li>IVs are generated through os.urandom()</li>
-</ul>
-</li>
-<li>Unforgeable packet delivery confirmations</li>
-<li>A variety of supported interface types</li>
-<li>An intuitive and easy-to-use API</li>
-<li>Reliable and efficient transfer of arbritrary amounts of data
-<ul>
-<li>Reticulum can handle a few bytes of data or files of many gigabytes</li>
-<li>Sequencing, transfer coordination and checksumming is automatic</li>
-<li>The API is very easy to use, and provides transfer progress</li>
-</ul>
-</li>
-</ul>
-<h2>
-<a id="user-content-where-can-reticulum-be-used" class="anchor" href="#where-can-reticulum-be-used" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Where can Reticulum be used?</h2>
-<p>On practically any hardware that can support at least a half-duplex channel with 1.000 bits per second throughput, and an MTU of 500 bytes. Data radios, modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes, ad-hoc WiFi, free-space optical links and similar systems are all examples of the types of interfaces Reticulum was designed for.</p>
-<p>An open-source LoRa-based interface called <a href="https://unsigned.io/projects/rnode/" rel="nofollow">RNode</a> has been designed specifically for use with Reticulum. It is possible to build yourself, or it can be purchased as a complete transceiver that just needs a USB connection to the host.</p>
-<p>Reticulum can also be encapsulated over existing IP networks, so there's nothing stopping you from using it over wired ethernet or your local WiFi network, where it'll work just as well. In fact, one of the strengths of Reticulum is how easily it allows you to connect different mediums into a self-configuring, resilient and encrypted mesh.</p>
-<p>As an example, it's possible to set up a Raspberry Pi connected to both a LoRa radio, a packet radio TNC and a WiFi network. Once the interfaces are configured, Reticulum will take care of the rest, and any device on the WiFi network can communicate with nodes on the LoRa and packet radio sides of the network, and vice versa.</p>
-<h2>
-<a id="user-content-current-status" class="anchor" href="#current-status" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Current Status</h2>
-<p>Consider Reticulum in extended testing at this stage. All core protocol features are implemented and functioning, but additions and changes can still occur if it is warranted.</p>
-<p>An API- and wireformat-stable beta is near at hand.</p>
-<h2>
-<a id="user-content-supported-interface-types-and-devices" class="anchor" href="#supported-interface-types-and-devices" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Supported interface types and devices</h2>
-<p>Reticulum implements a range of generalised interface types that covers most of the communications hardware that Reticulum can run over. If your hardware is not supported, it's relatively simple to implement an interface class. Currently, the following interfaces are supported:</p>
-<ul>
-<li>Any ethernet device</li>
-<li>LoRa using <a href="https://unsigned.io/projects/rnode/" rel="nofollow">RNode</a>
-</li>
-<li>Packet Radio TNCs (with or without AX.25)</li>
-<li>Any device with a serial port</li>
-<li>TCP over IP networks</li>
-<li>UDP over IP networks</li>
-</ul>
-<h2>
-<a id="user-content-what-is-currently-being-worked-on" class="anchor" href="#what-is-currently-being-worked-on" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>What is currently being worked on?</h2>
-<ul>
-<li>Delay/disruption tolerance</li>
-<li>API documentation</li>
-<li>Useful example programs and utilities</li>
-<li>A generic message transfer protocol built on Reticulum, see <a href="https://github.com/markqvist/lxmf">LXMF</a>
-</li>
-<li>A few useful-in-the-real-world apps built with Reticulum</li>
-</ul>
-<h2>
-<a id="user-content-can-i-use-reticulum-on-amateur-radio-spectrum" class="anchor" href="#can-i-use-reticulum-on-amateur-radio-spectrum" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Can I use Reticulum on amateur radio spectrum?</h2>
-<p>Some countries still ban the use of encryption when operating under an amateur radio license. Reticulum offers several encryptionless modes, while still using cryptographic principles for station verification, link establishment, data integrity verification, acknowledgements and routing. It is therefore perfectly possible to include Reticulum in amateur radio use, even if your country bans encryption.</p>
-<h2>
-<a id="user-content-dependencies" class="anchor" href="#dependencies" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Dependencies:</h2>
-<ul>
-<li>Python 3</li>
-<li>cryptography.io</li>
-<li>pyserial</li>
-</ul>
-<h2>
-<a id="user-content-how-do-i-get-started" class="anchor" href="#how-do-i-get-started" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>How do I get started?</h2>
-<p>Full documentation and tutorials are coming with the stable alpha release. Until then, you are mostly on your own. If you want to experiment already, you could take a look in the "Examples" folder, for some well-documented example programs. The default configuration file created by Reticulum on the first run is also worth reading. Be sure to also read the <a href="http://unsigned.io/wp-content/uploads/2018/04/Reticulum_Overview_v0.4.pdf" rel="nofollow">Reticulum Overview Document</a>.</p>
-<p>If you just need Reticulum as a dependency for another application, the easiest way is probably via pip:</p>
-<div class="highlight highlight-source-shell"><pre>pip3 install rns</pre></div>
-<p>For Reticulum development, you might want to get the latest source from GitHub. In that case, don't use pip, but try this recipe:</p>
-<div class="highlight highlight-source-shell"><pre><span class="pl-c"><span class="pl-c">#</span> Install dependencies</span>
-pip3 install cryptography pyserial
-
-<span class="pl-c"><span class="pl-c">#</span> Clone repository</span>
-git clone https://github.com/markqvist/Reticulum.git
-
-<span class="pl-c"><span class="pl-c">#</span> Move into Reticulum folder and symlink library to examples folder</span>
-<span class="pl-c1">cd</span> Reticulum
-ln -s ../RNS ./Examples/
-
-<span class="pl-c"><span class="pl-c">#</span> Run an example</span>
-python3 Examples/Echo.py -s
-
-<span class="pl-c"><span class="pl-c">#</span> Unless you've manually created a config file, Reticulum will do so now,</span>
-<span class="pl-c"><span class="pl-c">#</span> and immediately exit. Make any necessary changes to the file:</span>
-nano <span class="pl-k">~</span>/.reticulum/config
-
-<span class="pl-c"><span class="pl-c">#</span> ... and launch the example again.</span>
-python3 Examples/Echo.py -s
-
-<span class="pl-c"><span class="pl-c">#</span> You can now repeat the process on another computer,</span>
-<span class="pl-c"><span class="pl-c">#</span> and run the same example with -h to get command line options.</span>
-python3 Examples/Echo.py -h
-
-<span class="pl-c"><span class="pl-c">#</span> Run the example in client mode to "ping" the server.</span>
-<span class="pl-c"><span class="pl-c">#</span> Replace the hash below with the actual destination hash of your server.</span>
-python3 Examples/Echo.py 3e12fc71692f8ec47bc5
-
-<span class="pl-c"><span class="pl-c">#</span> Have a look at another example</span>
-python3 Examples/Filetransfer.py -h</pre></div>
-<p>The default config file contains examples for using Reticulum with LoRa transceivers (specifically <a href="https://unsigned.io/projects/rnode/" rel="nofollow">RNode</a>), packet radio TNCs/modems and UDP. By default a UDP interface is already enabled in the default config, which will enable Reticulum communication in your local ethernet broadcast domain.</p>
-<p>You can use the examples in the config file to expand communication over other mediums such as packet radio or LoRa, or over fast IP links using the UDP interface. I'll add in-depth tutorials and explanations on these topics later. For now, the included examples will hopefully be enough to get started.</p>
-<h2>
-<a id="user-content-caveat-emptor" class="anchor" href="#caveat-emptor" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Caveat Emptor</h2>
-<p>Reticulum is experimental software, and should be considered as such. While it has been built with cryptography best-practices very foremost in mind, it <em>has not</em> been externally security audited, and there could very well be privacy-breaking bugs. If you want to help out, or help sponsor an audit, please do get in touch.</p>
-</article></body></html>

README.md

@@ -1,22 +1,28 @@
-Reticulum Network Stack α
+Reticulum Network Stack β
 ==========
 
 Reticulum is a cryptography-based networking stack for wide-area networks built on readily available hardware, and can operate even with very high latency and extremely low bandwidth. Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more.
 
-Reticulum is a complete networking stack, and does not use IP or higher layers, although it is easy to utilise IP (with TCP or UDP) as the underlying carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks.
+Reticulum is a complete networking stack, and does not need IP or higher layers, although it is easy to use IP (with TCP or UDP) as the underlying carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks.
 
 Having no dependencies on traditional networking stacks free up overhead that has been utilised to implement a networking stack built directly on cryptographic principles, allowing resilience and stable functionality in open and trustless networks.
 
 No kernel modules or drivers are required. Reticulum runs completely in userland, and can run on practically any system that runs Python 3.
 
+The full documentation for Reticulum is available at [markqvist.github.io/Reticulum/manual/](https://markqvist.github.io/Reticulum/manual/).
+
+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/)
 
 ## Notable Features
  - Coordination-less globally unique adressing and identification
  - Fully self-configuring multi-hop routing
- - Asymmetric RSA encryption and signatures as basis for all communication
- - Perfect Forward Secrecy on links with ephemereal Elliptic Curve Diffie-Hellman keys (on the SECP256R1 curve)
- - Reticulum uses the [Fernet](https://github.com/fernet/spec/blob/master/Spec.md) specification for encryption on links and to group destinations
+ - Complete initiator anonymity, communicate without revealing your identity
+ - Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
+ - Forward Secrecy with ephemereal Elliptic Curve Diffie-Hellman keys on Curve25519
+ - Reticulum uses the [Fernet](https://github.com/fernet/spec/blob/master/Spec.md) specification for on-the-wire / over-the-air encryption
+    - Keys are ephemeral and derived from an ECDH key exchange on Curve25519
     - AES-128 in CBC mode with PKCS7 padding
     - HMAC using SHA256 for authentication
     - IVs are generated through os.urandom()
@@ -27,9 +33,19 @@ For more info, see [unsigned.io/projects/reticulum](https://unsigned.io/projects
     - Reticulum can handle a few bytes of data or files of many gigabytes
     - Sequencing, transfer coordination and checksumming is automatic
     - The API is very easy to use, and provides transfer progress
+ - Lightweight, flexible and expandable Request/Response mechanism
+ - Efficient link establishment
+    - Total bandwidth cost of setting up a link is 3 packets totalling 237 bytes
+    - Low cost of keeping links open at only 0.62 bits per second
+
+## Examples of Reticulum Applications
+If you want to quickly get an idea of what Reticulum can do, take a look at the following resources.
+
+ - For an off-grid, encrypted and resilient mesh communications platform, see [Nomad Network](https://github.com/markqvist/NomadNet)
+ - For a distributed, delay and disruption tolerant message transfer protocol built on Reticulum, see [LXMF](https://github.com/markqvist/lxmf)
 
 ## Where can Reticulum be used?
-On practically any hardware that can support at least a half-duplex channel with 1.000 bits per second throughput, and an MTU of 500 bytes. Data radios, modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes, ad-hoc WiFi, free-space optical links and similar systems are all examples of the types of interfaces Reticulum was designed for.
+Over practically any medium that can support at least a half-duplex channel with 500 bits per second throughput, and an MTU of 500 bytes. Data radios, modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes, ad-hoc WiFi, free-space optical links and similar systems are all examples of the types of interfaces Reticulum was designed for.
 
 An open-source LoRa-based interface called [RNode](https://unsigned.io/projects/rnode/) has been designed specifically for use with Reticulum. It is possible to build yourself, or it can be purchased as a complete transceiver that just needs a USB connection to the host.
 
@@ -38,9 +54,7 @@ Reticulum can also be encapsulated over existing IP networks, so there's nothing
 As an example, it's possible to set up a Raspberry Pi connected to both a LoRa radio, a packet radio TNC and a WiFi network. Once the interfaces are configured, Reticulum will take care of the rest, and any device on the WiFi network can communicate with nodes on the LoRa and packet radio sides of the network, and vice versa.
 
 ## Current Status
-Consider Reticulum in extended testing at this stage. All core protocol features are implemented and functioning, but additions and changes can still occur if it is warranted.
-
-An API- and wireformat-stable beta is near at hand.
+Reticulum should currently be considered beta software. All core protocol 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.
 
 ## Supported interface types and devices
 
@@ -53,15 +67,19 @@ Reticulum implements a range of generalised interface types that covers most of
  - TCP over IP networks
  - UDP over IP networks
 
-## What is currently being worked on?
- - Delay/disruption tolerance
- - API documentation
- - Useful example programs and utilities
- - A generic message transfer protocol built on Reticulum, see [LXMF](https://github.com/markqvist/lxmf)
- - A few useful-in-the-real-world apps built with Reticulum
 
-## Can I use Reticulum on amateur radio spectrum?
-Some countries still ban the use of encryption when operating under an amateur radio license. Reticulum offers several encryptionless modes, while still using cryptographic principles for station verification, link establishment, data integrity verification, acknowledgements and routing. It is therefore perfectly possible to include Reticulum in amateur radio use, even if your country bans encryption.
+
+## Feature Roadmap
+ - Stream mode for links
+ - More interface types for even broader compatibility
+   - ESP32 devices (ESP-Now, Bluetooth, etc.)
+   - More LoRa transceivers
+   - AT-compatible modems
+   - CAN-bus
+   - ZeroMQ
+   - MQTT
+   - SPI
+   - i²c
 
 ## Dependencies:
  - Python 3
@@ -69,52 +87,25 @@ Some countries still ban the use of encryption when operating under an amateur r
  - pyserial
 
 ## How do I get started?
-Full documentation and tutorials are coming with the stable alpha release. Until then, you are mostly on your own. If you want to experiment already, you could take a look in the "Examples" folder, for some well-documented example programs. The default configuration file created by Reticulum on the first run is also worth reading. Be sure to also read the [Reticulum Overview Document](http://unsigned.io/wp-content/uploads/2018/04/Reticulum_Overview_v0.4.pdf).
+The best way to get started with the Reticulum Network Stack depends on what
+you want to do. For full details and examples, have a look at the [Getting Started Fast](https://markqvist.github.io/Reticulum/manual/gettingstartedfast.html) section of the [Reticulum Manual](https://markqvist.github.io/Reticulum/manual/).
 
-If you just need Reticulum as a dependency for another application, the easiest way is probably via pip:
+If you just need Reticulum as a dependency for another application, the easiest way is via pip:
 
 ```bash
 pip3 install rns
 ```
 
-For Reticulum development, you might want to get the latest source from GitHub. In that case, don't use pip, but try this recipe:
-
-```bash
-# Install dependencies
-pip3 install cryptography pyserial
-
-# Clone repository
-git clone https://github.com/markqvist/Reticulum.git
-
-# Move into Reticulum folder and symlink library to examples folder
-cd Reticulum
-ln -s ../RNS ./Examples/
-
-# Run an example
-python3 Examples/Echo.py -s
-
-# Unless you've manually created a config file, Reticulum will do so now,
-# and immediately exit. Make any necessary changes to the file:
-nano ~/.reticulum/config
-
-# ... and launch the example again.
-python3 Examples/Echo.py -s
-
-# You can now repeat the process on another computer,
-# and run the same example with -h to get command line options.
-python3 Examples/Echo.py -h
-
-# Run the example in client mode to "ping" the server.
-# Replace the hash below with the actual destination hash of your server.
-python3 Examples/Echo.py 3e12fc71692f8ec47bc5
-
-# Have a look at another example
-python3 Examples/Filetransfer.py -h
-```
-
 The default config file contains examples for using Reticulum with LoRa transceivers (specifically [RNode](https://unsigned.io/projects/rnode/)), packet radio TNCs/modems and UDP. By default a UDP interface is already enabled in the default config, which will enable Reticulum communication in your local ethernet broadcast domain.
 
 You can use the examples in the config file to expand communication over other mediums such as packet radio or LoRa, or over fast IP links using the UDP interface. I'll add in-depth tutorials and explanations on these topics later. For now, the included examples will hopefully be enough to get started.
 
+## Support Reticulum
+You can help support the continued development of open, free and private communications systems by donating via one of the following channels:
+
+- Ethereum: 0x81F7B979fEa6134bA9FD5c701b3501A2e61E897a
+- Bitcoin: 3CPmacGm34qYvR6XWLVEJmi2aNe3PZqUuq
+- Ko-Fi: https://ko-fi.com/markqvist
+
 ## Caveat Emptor
-Reticulum is experimental software, 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 privacy-breaking bugs. If you want to help out, or help sponsor an audit, please do get in touch.
+Reticulum is experimental software, 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 privacy-breaking bugs. If you want to help out, or help sponsor an audit, please do get in touch.

RNS/Destination.py

@@ -1,13 +1,11 @@
 import base64
 import math
+import time
 import RNS
 
 from cryptography.fernet import Fernet
 from cryptography.hazmat.primitives import hashes
 from cryptography.hazmat.backends import default_backend
-from cryptography.hazmat.primitives import serialization
-from cryptography.hazmat.primitives.asymmetric import rsa
-from cryptography.hazmat.primitives.asymmetric import padding
 
 class Callbacks:
     def __init__(self):
@@ -16,8 +14,20 @@ class Callbacks:
         self.proof_requested = None
 
 class Destination:
-    KEYSIZE    = RNS.Identity.KEYSIZE;
-    PADDINGSIZE= RNS.Identity.PADDINGSIZE;
+    """
+    A class used to describe endpoints in a Reticulum Network. Destination
+    instances are used both to create outgoing and incoming endpoints. The
+    destination type will decide if encryption, and what type, is used in
+    communication with the endpoint. A destination can also announce its
+    presence on the network, which will also distribute necessary keys for
+    encrypted communication with it.
+
+    :param identity: An instance of :ref:`RNS.Identity<api-identity>`. Can hold only public keys for an outgoing destination, or holding private keys for an ingoing.
+    :param direction: ``RNS.Destination.IN`` or ``RNS.Destination.OUT``.
+    :param type: ``RNS.Destination.SINGLE``, ``RNS.Destination.GROUP`` or ``RNS.Destination.PLAIN``.
+    :param app_name: A string specifying the app name.
+    :param \*aspects: Any non-zero number of string arguments.
+    """
 
     # Constants
     SINGLE     = 0x00
@@ -31,12 +41,21 @@ class Destination:
     PROVE_ALL  = 0x23
     proof_strategies = [PROVE_NONE, PROVE_APP, PROVE_ALL]
 
+    ALLOW_NONE = 0x00
+    ALLOW_ALL  = 0x01
+    ALLOW_LIST = 0x02
+    request_policies = [ALLOW_NONE, ALLOW_ALL, ALLOW_LIST]
+
     IN         = 0x11;
     OUT        = 0x12;
     directions = [IN, OUT]
 
     @staticmethod
-    def getDestinationName(app_name, *aspects):
+    def full_name(app_name, *aspects):
+        """
+        :returns: A string containing the full human-readable name of the destination, for an app_name and a number of aspects.
+        """
+
         # Check input values and build name string
         if "." in app_name: raise ValueError("Dots can't be used in app names")
 
@@ -49,8 +68,11 @@ class Destination:
 
 
     @staticmethod
-    def getDestinationHash(app_name, *aspects):
-        name = Destination.getDestinationName(app_name, *aspects)
+    def hash(app_name, *aspects):
+        """
+        :returns: A destination name in adressable hash form, for an app_name and a number of aspects.
+        """
+        name = Destination.full_name(app_name, *aspects)
 
         # Create a digest for the destination
         digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
@@ -58,6 +80,22 @@ class Destination:
 
         return digest.finalize()[:10]
 
+    @staticmethod
+    def app_and_aspects_from_name(full_name):
+        """
+        :returns: A tuple containing the app name and a list of aspects, for a full-name string.
+        """
+        components = full_name.split(".")
+        return (components[0], components[1:])
+
+    @staticmethod
+    def hash_from_name_and_identity(full_name, identity):
+        """
+        :returns: A destination name in adressable hash form, for a full name string and Identity instance.
+        """
+        app_name, aspects = Destination.app_and_aspects_from_name(full_name)
+        aspects.append(identity.hexhash)
+        return Destination.hash(app_name, *aspects)
 
     def __init__(self, identity, direction, type, app_name, *aspects):
         # Check input values and build name string
@@ -65,6 +103,7 @@ class Destination:
         if not type in Destination.types: raise ValueError("Unknown destination type")
         if not direction in Destination.directions: raise ValueError("Unknown destination direction")
         self.callbacks = Callbacks()
+        self.request_handlers = {}
         self.type = type
         self.direction = direction
         self.proof_strategy = Destination.PROVE_NONE
@@ -81,51 +120,166 @@ class Destination:
 
         self.identity = identity
 
-        self.name = Destination.getDestinationName(app_name, *aspects)      
-        self.hash = Destination.getDestinationHash(app_name, *aspects)
+        self.name = Destination.full_name(app_name, *aspects)      
+        self.hash = Destination.hash(app_name, *aspects)
         self.hexhash = self.hash.hex()
+        self.default_app_data = None
 
         self.callback = None
         self.proofcallback = None
 
-        RNS.Transport.registerDestination(self)
+        RNS.Transport.register_destination(self)
 
 
     def __str__(self):
+        """
+        :returns: A human-readable representation of the destination including addressable hash and full name.
+        """
         return "<"+self.name+"/"+self.hexhash+">"
 
 
-    def link_established_callback(self, callback):
+    def announce(self, app_data=None, path_response=False):
+        """
+        Creates an announce packet for this destination and broadcasts it on all
+        relevant interfaces. Application specific data can be added to the announce.
+
+        :param app_data: *bytes* containing the app_data.
+        :param path_response: Internal flag used by :ref:`RNS.Transport<api-transport>`. Ignore.
+        """
+        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()+random_hash
+        if app_data != None:
+            signed_data += app_data
+
+        signature = self.identity.sign(signed_data)
+
+        announce_data = self.identity.get_public_key()+random_hash+signature
+
+        if app_data != None:
+            announce_data += app_data
+
+        if path_response:
+            announce_context = RNS.Packet.PATH_RESPONSE
+        else:
+            announce_context = RNS.Packet.NONE
+
+        RNS.Packet(self, announce_data, RNS.Packet.ANNOUNCE, context = announce_context).send()
+
+
+    def set_link_established_callback(self, callback):
+        """
+        Registers a function to be called when a link has been established to
+        this destination.
+
+        :param callback: A function or method to be called.
+        """
         self.callbacks.link_established = callback
 
-    def packet_callback(self, callback):
+    def set_packet_callback(self, callback):
+        """
+        Registers a function to be called when a packet has been received by
+        this destination.
+
+        :param callback: A function or method to be called.
+        """
         self.callbacks.packet = callback
 
-    def proof_requested_callback(self, callback):
+    def set_proof_requested_callback(self, callback):
+        """
+        Registers a function to be called when a proof has been requested for
+        a packet sent to this destination. Allows control over when and if
+        proofs should be returned for received packets.
+
+        :param callback: A function or method to be called. The callback must return one of True or False. If the callback returns True, a proof will be sent. If it returns False, a proof will not be sent.
+        """
         self.callbacks.proof_requested = callback
 
     def set_proof_strategy(self, proof_strategy):
+        """
+        Sets the destinations proof strategy.
+
+        :param proof_strategy: One of ``RNS.Destination.PROVE_NONE``, ``RNS.Destination.PROVE_ALL`` or ``RNS.Destination.PROVE_APP``. If ``RNS.Destination.PROVE_APP`` is set, the `proof_requested_callback` will be called to determine whether a proof should be sent or not.
+        """
         if not proof_strategy in Destination.proof_strategies:
             raise TypeError("Unsupported proof strategy")
         else:
             self.proof_strategy = proof_strategy
 
+
+    def register_request_handler(self, path, response_generator = None, allow = ALLOW_NONE, allowed_list = None):
+        """
+        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 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.
+        """
+        if path == None or path == "":
+            raise ValueError("Invalid path specified")
+        elif not callable(response_generator):
+            raise ValueError("Invalid response generator specified")
+        elif not allow in Destination.request_policies:
+            raise ValueError("Invalid request policy")
+        else:
+            path_hash = RNS.Identity.truncated_hash(path.encode("utf-8"))
+            request_handler = [path, response_generator, allow, allowed_list]
+            self.request_handlers[path_hash] = request_handler
+
+
+    def deregister_request_handler(self, path):
+        """
+        Deregisters a request handler.
+
+        :param path: The path for the request handler to be deregistered.
+        :returns: True if the handler was deregistered, otherwise False.
+        """
+        path_hash = RNS.Identity.truncated_hash(path.encode("utf-8"))
+        if path_hash in self.request_handlers:
+            self.request_handlers.pop(path_hash)
+            return True
+        else:
+            return False
+
+        
+
     def receive(self, packet):
-        plaintext = self.decrypt(packet.data)
-        if plaintext != None:
-            if packet.packet_type == RNS.Packet.LINKREQUEST:
-                self.incomingLinkRequest(plaintext, packet)
+        if packet.packet_type == RNS.Packet.LINKREQUEST:
+            plaintext = packet.data
+            self.incoming_link_request(plaintext, packet)
+        else:
+            plaintext = self.decrypt(packet.data)
+            if plaintext != None:
+                if packet.packet_type == RNS.Packet.DATA:
+                    if self.callbacks.packet != None:
+                        try:
+                            self.callbacks.packet(plaintext, packet)
+                        except Exception as e:
+                            RNS.log("Error while executing receive callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
-            if packet.packet_type == RNS.Packet.DATA:
-                if self.callbacks.packet != None:
-                    self.callbacks.packet(plaintext, packet)
 
-    def incomingLinkRequest(self, data, packet):
-        link = RNS.Link.validateRequest(self, data, packet)
+    def incoming_link_request(self, data, packet):
+        link = RNS.Link.validate_request(self, data, packet)
         if link != None:
             self.links.append(link)
 
-    def createKeys(self):
+    def create_keys(self):
+        """
+        For a ``RNS.Destination.GROUP`` type destination, creates a new symmetric key.
+
+        :raises: ``TypeError`` if called on an incompatible type of destination.
+        """
         if self.type == Destination.PLAIN:
             raise TypeError("A plain destination does not hold any keys")
 
@@ -133,11 +287,16 @@ class Destination:
             raise TypeError("A single destination holds keys through an Identity instance")
 
         if self.type == Destination.GROUP:
-            self.prv_bytes = Fernet.generate_key()
-            self.prv = Fernet(self.prv_bytes)
+            self.prv_bytes = base64.urlsafe_b64decode(Fernet.generate_key())
+            self.prv = Fernet(base64.urlsafe_b64encode(self.prv_bytes))
 
 
-    def getPrivateKey(self):
+    def get_private_key(self):
+        """
+        For a ``RNS.Destination.GROUP`` type destination, returns the symmetric private key.
+
+        :raises: ``TypeError`` if called on an incompatible type of destination.
+        """
         if self.type == Destination.PLAIN:
             raise TypeError("A plain destination does not hold any keys")
         elif self.type == Destination.SINGLE:
@@ -146,7 +305,13 @@ class Destination:
             return self.prv_bytes
 
 
-    def loadPrivateKey(self, key):
+    def load_private_key(self, key):
+        """
+        For a ``RNS.Destination.GROUP`` type destination, loads a symmetric private key.
+
+        :param key: A *bytes-like* containing the symmetric key.
+        :raises: ``TypeError`` if called on an incompatible type of destination.
+        """
         if self.type == Destination.PLAIN:
             raise TypeError("A plain destination does not hold any keys")
 
@@ -155,9 +320,9 @@ class Destination:
 
         if self.type == Destination.GROUP:
             self.prv_bytes = key
-            self.prv = Fernet(self.prv_bytes)
+            self.prv = Fernet(base64.urlsafe_b64encode(self.prv_bytes))
 
-    def loadPublicKey(self, key):
+    def load_public_key(self, key):
         if self.type != Destination.SINGLE:
             raise TypeError("Only the \"single\" destination type can hold a public key")
         else:
@@ -165,6 +330,12 @@ class Destination:
 
 
     def encrypt(self, plaintext):
+        """
+        Encrypts information for ``RNS.Destination.SINGLE`` or ``RNS.Destination.GROUP`` type destination.
+
+        :param plaintext: A *bytes-like* containing the plaintext to be encrypted.
+        :raises: ``ValueError`` if destination does not hold a necessary key for encryption.
+        """
         if self.type == Destination.PLAIN:
             return plaintext
 
@@ -184,6 +355,12 @@ class Destination:
 
 
     def decrypt(self, ciphertext):
+        """
+        Decrypts information for ``RNS.Destination.SINGLE`` or ``RNS.Destination.GROUP`` type destination.
+
+        :param ciphertext: *Bytes* containing the ciphertext to be decrypted.
+        :raises: ``ValueError`` if destination does not hold a necessary key for decryption.
+        """
         if self.type == Destination.PLAIN:
             return ciphertext
 
@@ -202,36 +379,29 @@ class Destination:
 
 
     def sign(self, message):
+        """
+        Signs information for ``RNS.Destination.SINGLE`` type destination.
+
+        :param message: *Bytes* containing the message to be signed.
+        :returns: A *bytes-like* containing the message signature, or *None* if the destination could not sign the message.
+        """
         if self.type == Destination.SINGLE and self.identity != None:
             return self.identity.sign(message)
         else:
             return None
 
+    def set_default_app_data(self, app_data=None):
+        """
+        Sets the default app_data for the destination. If set, the default
+        app_data will be included in every announce sent by the destination,
+        unless other app_data is specified in the *announce* method.
 
-    # Creates an announce packet for this destination.
-    # Application specific data can be added to the announce.
-    def announce(self, app_data=None, path_response=False):
-        destination_hash = self.hash
-        random_hash = RNS.Identity.getRandomHash()
-        
-        signed_data = self.hash+self.identity.getPublicKey()+random_hash
-        if app_data != None:
-            signed_data += app_data
-
-        signature = self.identity.sign(signed_data)
-
-        # TODO: Check if this could be optimised by only
-        # carrying the hash in the destination field, not
-        # also redundantly inside the signed blob as here
-        announce_data = self.hash+self.identity.getPublicKey()+random_hash+signature
-
-        if app_data != None:
-            announce_data += app_data
-
-        if path_response:
-            announce_context = RNS.Packet.PATH_RESPONSE
-        else:
-            announce_context = RNS.Packet.NONE
-
-        RNS.Packet(self, announce_data, RNS.Packet.ANNOUNCE, context = announce_context).send()
+        :param app_data: A *bytes-like* containing the default app_data, or a *callable* returning a *bytes-like* containing the app_data.
+        """
+        self.default_app_data = app_data
 
+    def clear_default_app_data(self):
+        """
+        Clears default app_data previously set for the destination.
+        """
+        self.set_default_app_data(app_data=None)

RNS/Identity.py

@@ -4,61 +4,116 @@ import os
 import RNS
 import time
 import atexit
+import base64
 from .vendor import umsgpack as umsgpack
-from cryptography.hazmat.primitives import hashes
 from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import hashes
 from cryptography.hazmat.primitives import serialization
-from cryptography.hazmat.primitives.serialization import load_der_public_key
-from cryptography.hazmat.primitives.serialization import load_der_private_key
-from cryptography.hazmat.primitives.asymmetric import rsa
-from cryptography.hazmat.primitives.asymmetric import padding
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey, X25519PublicKey
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.fernet import Fernet
 
 class Identity:
-   #KEYSIZE     = 1536
-    KEYSIZE     = 1024
-    DERKEYSIZE  = KEYSIZE+272
+    """
+    This class is used to manage identities in Reticulum. It provides methods
+    for encryption, decryption, signatures and verification, and is the basis
+    for all encrypted communication over Reticulum networks.
+
+    :param create_keys: Specifies whether new encryption and signing keys should be generated.
+    """
+
+    CURVE = "Curve25519"
+    """
+    The curve used for Elliptic Curve DH key exchanges
+    """
+
+    KEYSIZE     = 256*2
+    """
+    X25519 key size in bits. A complete key is the concatenation of a 256 bit encryption key, and a 256 bit signing key.
+    """   
 
     # Non-configurable constants
-    PADDINGSIZE = 336       # In bits
-    HASHLENGTH  = 256       # In bits
-    SIGLENGTH   = KEYSIZE
+    FERNET_VERSION   = 0x80
+    FERNET_OVERHEAD  = 54     # In bytes
+    AES128_BLOCKSIZE = 16     # In bytes
+    HASHLENGTH  = 256         # In bits
+    SIGLENGTH   = KEYSIZE     # In bits
 
-    ENCRYPT_CHUNKSIZE = (KEYSIZE-PADDINGSIZE)//8
-    DECRYPT_CHUNKSIZE = KEYSIZE//8
-
-    TRUNCATED_HASHLENGTH = 80 # In bits
+    TRUNCATED_HASHLENGTH = RNS.Reticulum.TRUNCATED_HASHLENGTH
+    """
+    Constant specifying the truncated hash length (in bits) used by Reticulum
+    for addressable hashes and other purposes. Non-configurable.
+    """
 
     # Storage
     known_destinations = {}
 
     @staticmethod
     def remember(packet_hash, destination_hash, public_key, app_data = None):
-        Identity.known_destinations[destination_hash] = [time.time(), packet_hash, public_key, app_data]
+        if len(public_key) != Identity.KEYSIZE//8:
+            raise TypeError("Can't remember "+RNS.prettyhexrep(destination_hash)+", the public key size of "+str(len(public_key))+" is not valid.", RNS.LOG_ERROR)
+        else:
+            Identity.known_destinations[destination_hash] = [time.time(), packet_hash, public_key, app_data]
 
 
     @staticmethod
     def recall(destination_hash):
-        RNS.log("Searching for "+RNS.prettyhexrep(destination_hash)+"...", RNS.LOG_EXTREME)
+        """
+        Recall identity for a destination hash.
+
+        :param destination_hash: Destination hash as *bytes*.
+        :returns: An :ref:`RNS.Identity<api-identity>` instance that can be used to create an outgoing :ref:`RNS.Destination<api-destination>`, or *None* if the destination is unknown.
+        """
         if destination_hash in Identity.known_destinations:
             identity_data = Identity.known_destinations[destination_hash]
-            identity = Identity(public_only=True)
-            identity.loadPublicKey(identity_data[2])
-            RNS.log("Found "+RNS.prettyhexrep(destination_hash)+" in known destinations", RNS.LOG_EXTREME)
+            identity = Identity(create_keys=False)
+            identity.load_public_key(identity_data[2])
+            identity.app_data = identity_data[3]
             return identity
         else:
-            RNS.log("Could not find "+RNS.prettyhexrep(destination_hash)+" in known destinations", RNS.LOG_EXTREME)
             return None
 
     @staticmethod
-    def saveKnownDestinations():
-        RNS.log("Saving known destinations to storage...", RNS.LOG_VERBOSE)
-        file = open(RNS.Reticulum.storagepath+"/known_destinations","wb")
-        umsgpack.dump(Identity.known_destinations, file)
-        file.close()
-        RNS.log("Done saving known destinations to storage", RNS.LOG_VERBOSE)
+    def recall_app_data(destination_hash):
+        """
+        Recall last heard app_data for a destination hash.
+
+        :param destination_hash: Destination hash as *bytes*.
+        :returns: *Bytes* containing app_data, or *None* if the destination is unknown.
+        """
+        if destination_hash in Identity.known_destinations:
+            app_data = Identity.known_destinations[destination_hash][3]
+            return app_data
+        else:
+            return None
 
     @staticmethod
-    def loadKnownDestinations():
+    def save_known_destinations():
+        try:
+            storage_known_destinations = {}
+            if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
+                try:
+                    file = open(RNS.Reticulum.storagepath+"/known_destinations","rb")
+                    storage_known_destinations = umsgpack.load(file)
+                    file.close()
+                except:
+                    pass
+
+            for destination_hash in storage_known_destinations:
+                if not destination_hash in Identity.known_destinations:
+                    Identity.known_destinations[destination_hash] = storage_known_destinations[destination_hash]
+
+            RNS.log("Saving known destinations to storage...", RNS.LOG_VERBOSE)
+            file = open(RNS.Reticulum.storagepath+"/known_destinations","wb")
+            umsgpack.dump(Identity.known_destinations, file)
+            file.close()
+            RNS.log("Done saving known destinations to storage", RNS.LOG_VERBOSE)
+        except Exception as e:
+            RNS.log("Error while saving known destinations to disk, the contained exception was: "+str(e), RNS.LOG_ERROR)
+
+    @staticmethod
+    def load_known_destinations():
         if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
             try:
                 file = open(RNS.Reticulum.storagepath+"/known_destinations","rb")
@@ -68,46 +123,63 @@ class Identity:
             except:
                 RNS.log("Error loading known destinations from disk, file will be recreated on exit", RNS.LOG_ERROR)
         else:
-            RNS.log("Destinations file does not exist, so no known destinations loaded", RNS.LOG_VERBOSE)
+            RNS.log("Destinations file does not exist, no known destinations loaded", RNS.LOG_VERBOSE)
 
     @staticmethod
-    def fullHash(data):
+    def full_hash(data):
+        """
+        Get a SHA-256 hash of passed data.
+
+        :param data: Data to be hashed as *bytes*.
+        :returns: SHA-256 hash as *bytes*
+        """
         digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
         digest.update(data)
 
         return digest.finalize()
 
     @staticmethod
-    def truncatedHash(data):
-        # TODO: Remove
-        # digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
-        # digest.update(data)
+    def truncated_hash(data):
+        """
+        Get a truncated SHA-256 hash of passed data.
 
-        return Identity.fullHash(data)[:(Identity.TRUNCATED_HASHLENGTH//8)]
+        :param data: Data to be hashed as *bytes*.
+        :returns: Truncated SHA-256 hash as *bytes*
+        """
+        return Identity.full_hash(data)[:(Identity.TRUNCATED_HASHLENGTH//8)]
 
     @staticmethod
-    def getRandomHash():
-        return Identity.truncatedHash(os.urandom(10))
+    def get_random_hash():
+        """
+        Get a random SHA-256 hash.
+
+        :param data: Data to be hashed as *bytes*.
+        :returns: Truncated SHA-256 hash of random data as *bytes*
+        """
+        return Identity.truncated_hash(os.urandom(10))
 
     @staticmethod
-    def validateAnnounce(packet):
+    def validate_announce(packet):
         if packet.packet_type == RNS.Packet.ANNOUNCE:
             RNS.log("Validating announce from "+RNS.prettyhexrep(packet.destination_hash), RNS.LOG_DEBUG)
             destination_hash = packet.destination_hash
-            public_key = packet.data[10:Identity.DERKEYSIZE//8+10]
-            random_hash = packet.data[Identity.DERKEYSIZE//8+10:Identity.DERKEYSIZE//8+20]
-            signature = packet.data[Identity.DERKEYSIZE//8+20:Identity.DERKEYSIZE//8+20+Identity.KEYSIZE//8]
+            public_key = packet.data[:Identity.KEYSIZE//8]
+            random_hash = packet.data[Identity.KEYSIZE//8:Identity.KEYSIZE//8+10]
+            signature = packet.data[Identity.KEYSIZE//8+10:Identity.KEYSIZE//8+10+Identity.KEYSIZE//8]
             app_data = b""
-            if len(packet.data) > Identity.DERKEYSIZE//8+20+Identity.KEYSIZE//8:
-                app_data = packet.data[Identity.DERKEYSIZE//8+20+Identity.KEYSIZE//8:]
+            if len(packet.data) > Identity.KEYSIZE//8+10+Identity.KEYSIZE//8:
+                app_data = packet.data[Identity.KEYSIZE//8+10+Identity.KEYSIZE//8:]
 
             signed_data = destination_hash+public_key+random_hash+app_data
 
-            announced_identity = Identity(public_only=True)
-            announced_identity.loadPublicKey(public_key)
+            if not len(packet.data) > Identity.KEYSIZE//8+10+Identity.KEYSIZE//8:
+                app_data = None
+
+            announced_identity = Identity(create_keys=False)
+            announced_identity.load_public_key(public_key)
 
             if announced_identity.pub != None and announced_identity.validate(signature, signed_data):
-                RNS.Identity.remember(packet.getHash(), destination_hash, public_key)
+                RNS.Identity.remember(packet.get_hash(), destination_hash, public_key, app_data)
                 RNS.log("Stored valid announce from "+RNS.prettyhexrep(destination_hash), RNS.LOG_DEBUG)
                 del announced_identity
                 return True
@@ -117,193 +189,292 @@ class Identity:
                 return False
 
     @staticmethod
-    def exitHandler():
-        Identity.saveKnownDestinations()
+    def exit_handler():
+        Identity.save_known_destinations()
 
 
     @staticmethod
-    def from_file(path):
-        identity = Identity(public_only=True)
-        if identity.load(path):
+    def from_bytes(prv_bytes):
+        """
+        Create a new :ref:`RNS.Identity<api-identity>` instance from *bytes* of private key.
+        Can be used to load previously created and saved identities into Reticulum.
+
+        :param prv_bytes: The *bytes* of private a saved private key. **HAZARD!** Never use this to generate a new key by feeding random data in prv_bytes.
+        :returns: A :ref:`RNS.Identity<api-identity>` instance, or *None* if the *bytes* data was invalid.
+        """
+        identity = Identity(create_keys=False)
+        if identity.load_private_key(prv_bytes):
             return identity
         else:
             return None
 
 
-    def __init__(self,public_only=False):
-        # Initialize keys to none
-        self.prv = None
-        self.pub = None
-        self.prv_bytes = None
-        self.pub_bytes = None
-        self.hash = None
-        self.hexhash = None
+    @staticmethod
+    def from_file(path):
+        """
+        Create a new :ref:`RNS.Identity<api-identity>` instance from a file.
+        Can be used to load previously created and saved identities into Reticulum.
 
-        if not public_only:
-            self.createKeys()
+        :param path: The full path to the saved :ref:`RNS.Identity<api-identity>` data
+        :returns: A :ref:`RNS.Identity<api-identity>` instance, or *None* if the loaded data was invalid.
+        """
+        identity = Identity(create_keys=False)
+        if identity.load(path):
+            return identity
+        else:
+            return None
 
-    def createKeys(self):
-        self.prv = rsa.generate_private_key(
-            public_exponent=65537,
-            key_size=Identity.KEYSIZE,
-            backend=default_backend()
-        )
-        self.prv_bytes = self.prv.private_bytes(
-            encoding=serialization.Encoding.DER,
-            format=serialization.PrivateFormat.PKCS8,
-            encryption_algorithm=serialization.NoEncryption()
-        )
-        self.pub = self.prv.public_key()
-        self.pub_bytes = self.pub.public_bytes(
-            encoding=serialization.Encoding.DER,
-            format=serialization.PublicFormat.SubjectPublicKeyInfo
-        )
+    def to_file(self, path):
+        """
+        Saves the identity to a file. This will write the private key to disk,
+        and anyone with access to this file will be able to decrypt all
+        communication for the identity. Be very careful with this method.
 
-        self.updateHashes()
-
-        RNS.log("Identity keys created for "+RNS.prettyhexrep(self.hash), RNS.LOG_VERBOSE)
-
-    def getPrivateKey(self):
-        return self.prv_bytes
-
-    def getPublicKey(self):
-        return self.pub_bytes
-
-    def loadPrivateKey(self, prv_bytes):
-        try:
-            self.prv_bytes = prv_bytes
-            self.prv = serialization.load_der_private_key(
-                self.prv_bytes,
-                password=None,
-                backend=default_backend()
-            )
-            self.pub = self.prv.public_key()
-            self.pub_bytes = self.pub.public_bytes(
-                encoding=serialization.Encoding.DER,
-                format=serialization.PublicFormat.SubjectPublicKeyInfo
-            )
-            self.updateHashes()
-
-            return True
-
-        except Exception as e:
-            RNS.log("Failed to load identity key", RNS.LOG_ERROR)
-            RNS.log("The contained exception was: "+str(e))
-            return False
-
-    def loadPublicKey(self, key):
-        try:
-            self.pub_bytes = key
-            self.pub = load_der_public_key(self.pub_bytes, backend=default_backend())
-            self.updateHashes()
-        except Exception as e:
-            RNS.log("Error while loading public key, the contained exception was: "+str(e), RNS.LOG_ERROR)
-
-    def updateHashes(self):
-        self.hash = Identity.truncatedHash(self.pub_bytes)
-        self.hexhash = self.hash.hex()
-
-    def save(self, path):
+        :param path: The full path specifying where to save the identity.
+        :returns: True if the file was saved, otherwise False.
+        """
         try:
             with open(path, "wb") as key_file:
-                key_file.write(self.prv_bytes)
+                key_file.write(self.get_private_key())
                 return True
             return False
         except Exception as e:
             RNS.log("Error while saving identity to "+str(path), RNS.LOG_ERROR)
             RNS.log("The contained exception was: "+str(e))
 
+    def __init__(self,create_keys=True):
+        # Initialize keys to none
+        self.prv           = None
+        self.prv_bytes     = None
+        self.sig_prv       = None
+        self.sig_prv_bytes = None
+
+        self.pub           = None
+        self.pub_bytes     = None
+        self.sig_pub       = None
+        self.sig_pub_bytes = None
+
+        self.hash          = None
+        self.hexhash       = None
+
+        if create_keys:
+            self.create_keys()
+
+    def create_keys(self):
+        self.prv           = X25519PrivateKey.generate()
+        self.prv_bytes     = self.prv.private_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PrivateFormat.Raw,
+            encryption_algorithm=serialization.NoEncryption()
+        )
+
+        self.sig_prv       = Ed25519PrivateKey.generate()
+        self.sig_prv_bytes = self.sig_prv.private_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PrivateFormat.Raw,
+            encryption_algorithm=serialization.NoEncryption()
+        )
+
+        self.pub           = self.prv.public_key()
+        self.pub_bytes     = self.pub.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw
+        )
+
+        self.sig_pub       = self.sig_prv.public_key()
+        self.sig_pub_bytes = self.sig_pub.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw
+        )
+
+        self.update_hashes()
+
+        RNS.log("Identity keys created for "+RNS.prettyhexrep(self.hash), RNS.LOG_VERBOSE)
+
+    def get_private_key(self):
+        """
+        :returns: The private key as *bytes*
+        """
+        return self.prv_bytes+self.sig_prv_bytes
+
+    def get_public_key(self):
+        """
+        :returns: The public key as *bytes*
+        """
+        return self.pub_bytes+self.sig_pub_bytes
+
+    def load_private_key(self, prv_bytes):
+        """
+        Load a private key into the instance.
+
+        :param prv_bytes: The private key as *bytes*.
+        :returns: True if the key was loaded, otherwise False.
+        """
+        try:
+            self.prv_bytes     = prv_bytes[:Identity.KEYSIZE//8//2]
+            self.prv           = X25519PrivateKey.from_private_bytes(self.prv_bytes)
+            self.sig_prv_bytes = prv_bytes[Identity.KEYSIZE//8//2:]
+            self.sig_prv       = Ed25519PrivateKey.from_private_bytes(self.sig_prv_bytes)
+            
+            self.pub           = self.prv.public_key()
+            self.pub_bytes     = self.pub.public_bytes(
+                encoding=serialization.Encoding.Raw,
+                format=serialization.PublicFormat.Raw
+            )
+
+            self.sig_pub       = self.sig_prv.public_key()
+            self.sig_pub_bytes = self.sig_pub.public_bytes(
+                encoding=serialization.Encoding.Raw,
+                format=serialization.PublicFormat.Raw
+            )
+
+            self.update_hashes()
+
+            return True
+
+        except Exception as e:
+            raise e
+            RNS.log("Failed to load identity key", RNS.LOG_ERROR)
+            RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+            return False
+
+    def load_public_key(self, pub_bytes):
+        """
+        Load a public key into the instance.
+
+        :param pub_bytes: The public key as *bytes*.
+        :returns: True if the key was loaded, otherwise False.
+        """
+        try:
+            self.pub_bytes     = pub_bytes[:Identity.KEYSIZE//8//2]
+            self.sig_pub_bytes = pub_bytes[Identity.KEYSIZE//8//2:]
+
+            self.pub           = X25519PublicKey.from_public_bytes(self.pub_bytes)
+            self.sig_pub       = Ed25519PublicKey.from_public_bytes(self.sig_pub_bytes)
+
+            self.update_hashes()
+        except Exception as e:
+            RNS.log("Error while loading public key, the contained exception was: "+str(e), RNS.LOG_ERROR)
+
+    def update_hashes(self):
+        self.hash = Identity.truncated_hash(self.get_public_key())
+        self.hexhash = self.hash.hex()
+
     def load(self, path):
         try:
             with open(path, "rb") as key_file:
                 prv_bytes = key_file.read()
-                return self.loadPrivateKey(prv_bytes)
+                return self.load_private_key(prv_bytes)
             return False
         except Exception as e:
             RNS.log("Error while loading identity from "+str(path), RNS.LOG_ERROR)
             RNS.log("The contained exception was: "+str(e))
 
-    def encrypt(self, plaintext):
-        if self.pub != None:
-            chunksize = Identity.ENCRYPT_CHUNKSIZE
-            chunks = int(math.ceil(len(plaintext)/(float(chunksize))))
+    def get_salt(self):
+        return self.hash
 
-            ciphertext = b"";
-            for chunk in range(chunks):
-                start = chunk*chunksize
-                end = (chunk+1)*chunksize
-                if (chunk+1)*chunksize > len(plaintext):
-                    end = len(plaintext)
-                
-                ciphertext += self.pub.encrypt(
-                    plaintext[start:end],
-                    padding.OAEP(
-                        mgf=padding.MGF1(algorithm=hashes.SHA1()),
-                        algorithm=hashes.SHA1(),
-                        label=None
-                    )
-                )
-            return ciphertext
+    def get_context(self):
+        return None
+
+    def encrypt(self, plaintext):
+        """
+        Encrypts information for the identity.
+
+        :param plaintext: The plaintext to be encrypted as *bytes*.
+        :returns: Ciphertext token as *bytes*.
+        :raises: *KeyError* if the instance does not hold a public key.
+        """
+        if self.pub != None:
+            ephemeral_key = X25519PrivateKey.generate()
+            ephemeral_pub_bytes = ephemeral_key.public_key().public_bytes(
+                encoding=serialization.Encoding.Raw,
+                format=serialization.PublicFormat.Raw
+            )
+
+            shared_key = ephemeral_key.exchange(self.pub)
+            derived_key = derived_key = HKDF(
+                algorithm=hashes.SHA256(),
+                length=32,
+                salt=self.get_salt(),
+                info=self.get_context(),
+            ).derive(shared_key)
+
+            fernet = Fernet(base64.urlsafe_b64encode(derived_key))
+            ciphertext = base64.urlsafe_b64decode(fernet.encrypt(plaintext))
+            token = ephemeral_pub_bytes+ciphertext
+
+            return token
         else:
             raise KeyError("Encryption failed because identity does not hold a public key")
 
 
-    def decrypt(self, ciphertext):
+    def decrypt(self, ciphertext_token):
+        """
+        Decrypts information for the identity.
+
+        :param ciphertext: The ciphertext to be decrypted as *bytes*.
+        :returns: Plaintext as *bytes*, or *None* if decryption fails.
+        :raises: *KeyError* if the instance does not hold a private key.
+        """
         if self.prv != None:
-            plaintext = None
-            try:
-                chunksize = Identity.DECRYPT_CHUNKSIZE
-                chunks = int(math.ceil(len(ciphertext)/(float(chunksize))))
+            if len(ciphertext_token) > Identity.KEYSIZE//8//2:
+                plaintext = None
+                try:
+                    peer_pub_bytes = ciphertext_token[:Identity.KEYSIZE//8//2]
+                    peer_pub = X25519PublicKey.from_public_bytes(peer_pub_bytes)
 
-                plaintext = b"";
-                for chunk in range(chunks):
-                    start = chunk*chunksize
-                    end = (chunk+1)*chunksize
-                    if (chunk+1)*chunksize > len(ciphertext):
-                        end = len(ciphertext)
+                    shared_key = self.prv.exchange(peer_pub)
+                    derived_key = derived_key = HKDF(
+                        algorithm=hashes.SHA256(),
+                        length=32,
+                        salt=self.get_salt(),
+                        info=self.get_context(),
+                    ).derive(shared_key)
 
-                    plaintext += self.prv.decrypt(
-                        ciphertext[start:end],
-                        padding.OAEP(
-                            mgf=padding.MGF1(algorithm=hashes.SHA1()),
-                            algorithm=hashes.SHA1(),
-                            label=None
-                        )
-                    )
-            except:
-                RNS.log("Decryption by "+RNS.prettyhexrep(self.hash)+" failed", RNS.LOG_VERBOSE)
-                
-            return plaintext;
+                    fernet = Fernet(base64.urlsafe_b64encode(derived_key))
+                    ciphertext = ciphertext_token[Identity.KEYSIZE//8//2:]
+                    plaintext = fernet.decrypt(base64.urlsafe_b64encode(ciphertext))
+
+                except Exception as e:
+                    RNS.log("Decryption by "+RNS.prettyhexrep(self.hash)+" failed: "+str(e), RNS.LOG_DEBUG)
+                    
+                return plaintext;
+            else:
+                RNS.log("Decryption failed because the token size was invalid.", RNS.LOG_DEBUG)
+                return None
         else:
             raise KeyError("Decryption failed because identity does not hold a private key")
 
 
     def sign(self, message):
-        if self.prv != None:
-            signature = self.prv.sign(
-                message,
-                padding.PSS(
-                    mgf=padding.MGF1(hashes.SHA256()),
-                    salt_length=padding.PSS.MAX_LENGTH
-                ),
-                hashes.SHA256()
-            )
-            return signature
+        """
+        Signs information by the identity.
+
+        :param message: The message to be signed as *bytes*.
+        :returns: Signature as *bytes*.
+        :raises: *KeyError* if the instance does not hold a private key.
+        """
+        if self.sig_prv != None:
+            try:
+                return self.sig_prv.sign(message)    
+            except Exception as e:
+                RNS.log("The identity "+str(self)+" could not sign the requested message. The contained exception was: "+str(e), RNS.LOG_ERROR)
+                raise e 
         else:
             raise KeyError("Signing failed because identity does not hold a private key")
 
     def validate(self, signature, message):
+        """
+        Validates the signature of a signed message.
+
+        :param signature: The signature to be validated as *bytes*.
+        :param message: The message to be validated as *bytes*.
+        :returns: True if the signature is valid, otherwise False.
+        :raises: *KeyError* if the instance does not hold a public key.
+        """
         if self.pub != None:
             try:
-                self.pub.verify(
-                    signature,
-                    message,
-                    padding.PSS(
-                        mgf=padding.MGF1(hashes.SHA256()),
-                        salt_length=padding.PSS.MAX_LENGTH
-                    ),
-                    hashes.SHA256()
-                )
+                self.sig_pub.verify(signature, message)
                 return True
             except Exception as e:
                 return False
@@ -318,7 +489,7 @@ class Identity:
             proof_data = packet.packet_hash + signature
         
         if destination == None:
-            destination = packet.generateProofDestination()
+            destination = packet.generate_proof_destination()
 
         proof = RNS.Packet(destination, proof_data, RNS.Packet.PROOF, attached_interface = packet.receiving_interface)
         proof.send()

RNS/Interfaces/AX25KISSInterface.py

@@ -48,6 +48,9 @@ class AX25KISSInterface(Interface):
     serial   = None
 
     def __init__(self, owner, name, callsign, ssid, port, speed, databits, parity, stopbits, preamble, txtail, persistence, slottime, flow_control):
+        self.rxb = 0
+        self.txb = 0
+        
         self.serial   = None
         self.owner    = owner
         self.name     = name
@@ -62,13 +65,12 @@ class AX25KISSInterface(Interface):
         self.stopbits = stopbits
         self.timeout  = 100
         self.online   = False
-        # TODO: Sane default and make this configurable
-        # TODO: Changed to 25ms instead of 100ms, check it
-        self.txdelay  = 0.025
 
         self.packet_queue    = []
         self.flow_control    = flow_control
         self.interface_ready = False
+        self.flow_control_timeout = 5
+        self.flow_control_locked  = time.time()
 
         if (len(self.src_call) < 3 or len(self.src_call) > 6):
             raise ValueError("Invalid callsign for "+str(self))
@@ -189,14 +191,17 @@ class AX25KISSInterface(Interface):
 
     def processIncoming(self, data):
         if (len(data) > AX25.HEADER_SIZE):
+            self.rxb += len(data)
             self.owner.inbound(data[AX25.HEADER_SIZE:], self)
 
 
     def processOutgoing(self,data):
+        datalen = len(data)
         if self.online:
             if self.interface_ready:
                 if self.flow_control:
                     self.interface_ready = False
+                    self.flow_control_locked = time.time()
 
                 encoded_dst_ssid = bytes([0x60 | (self.dst_ssid << 1)])
                 encoded_src_ssid = bytes([0x60 | (self.src_ssid << 1) | 0x01])
@@ -223,11 +228,9 @@ class AX25KISSInterface(Interface):
                 data = data.replace(bytes([0xc0]), bytes([0xdb])+bytes([0xdc]))
                 kiss_frame = bytes([KISS.FEND])+bytes([0x00])+data+bytes([KISS.FEND])
 
-                if (self.txdelay > 0):
-                    RNS.log(str(self.name)+" delaying TX for "+str(self.txdelay)+" seconds", RNS.LOG_EXTREME)
-                    sleep(self.txdelay)
-
                 written = self.serial.write(kiss_frame)
+                self.txb += datalen
+
                 if written != len(kiss_frame):
                     if self.flow_control:
                         self.interface_ready = True
@@ -294,12 +297,21 @@ class AX25KISSInterface(Interface):
                         in_frame = False
                         command = KISS.CMD_UNKNOWN
                         escape = False
-                    sleep(0.08)
+                    sleep(0.05)
+
+                    if self.flow_control:
+                        if not self.interface_ready:
+                            if time.time() > self.flow_control_locked + self.flow_control_timeout:
+                                RNS.log("Interface "+str(self)+" is unlocking flow control due to time-out. This should not happen. Your hardware might have missed a flow-control READY command, or maybe it does not support flow-control.", RNS.LOG_WARNING)
+                                self.process_queue()
 
         except Exception as e:
             self.online = False
             RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
-            RNS.log("The interface "+str(self.name)+" is now offline. Restart Reticulum to attempt reconnection.", RNS.LOG_ERROR)
+            RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down. Restart Reticulum to attempt to open this interface again.", RNS.LOG_ERROR)
+
+            if RNS.Reticulum.panic_on_interface_error:
+                RNS.panic()
 
     def __str__(self):
         return "AX25KISSInterface["+self.name+"]"

RNS/Interfaces/Interface.py

@@ -8,8 +8,12 @@ class Interface:
     name = None
 
     def __init__(self):
-        pass
+        self.rxb = 0
+        self.txb = 0
+        self.online = False
 
     def get_hash(self):
-        # TODO: Maybe expand this to something more unique
-        return RNS.Identity.fullHash(str(self).encode("utf-8"))
+        return RNS.Identity.full_hash(str(self).encode("utf-8"))
+
+    def detach(self):
+        pass

RNS/Interfaces/KISSInterface.py

@@ -40,6 +40,12 @@ class KISSInterface(Interface):
     serial   = None
 
     def __init__(self, owner, name, port, speed, databits, parity, stopbits, preamble, txtail, persistence, slottime, flow_control, beacon_interval, beacon_data):
+        self.rxb = 0
+        self.txb = 0
+        
+        if beacon_data == None:
+            beacon_data = ""
+
         self.serial   = None
         self.owner    = owner
         self.name     = name
@@ -57,7 +63,7 @@ class KISSInterface(Interface):
         self.packet_queue    = []
         self.flow_control    = flow_control
         self.interface_ready = False
-        self.flow_control_timeout = 10
+        self.flow_control_timeout = 5
         self.flow_control_locked  = time.time()
 
         self.preamble    = preamble if preamble != None else 350;
@@ -171,10 +177,12 @@ class KISSInterface(Interface):
 
 
     def processIncoming(self, data):
+        self.rxb += len(data)  
         self.owner.inbound(data, self)
 
 
     def processOutgoing(self,data):
+        datalen = len(data)
         if self.online:
             if self.interface_ready:
                 if self.flow_control:
@@ -186,6 +194,7 @@ class KISSInterface(Interface):
                 frame = bytes([KISS.FEND])+bytes([0x00])+data+bytes([KISS.FEND])
 
                 written = self.serial.write(frame)
+                self.txb += datalen
 
                 if data == self.beacon_d:
                     self.first_tx = None
@@ -256,12 +265,12 @@ class KISSInterface(Interface):
                         in_frame = False
                         command = KISS.CMD_UNKNOWN
                         escape = False
-                    sleep(0.08)
+                    sleep(0.05)
 
                     if self.flow_control:
                         if not self.interface_ready:
                             if time.time() > self.flow_control_locked + self.flow_control_timeout:
-                                RNS.log("Interface "+str(self)+" is unlocking flow control due to time-out. This should not happen. Your hardware might have missed a flow-control READY command.", RNS.LOG_WARNING)
+                                RNS.log("Interface "+str(self)+" is unlocking flow control due to time-out. This should not happen. Your hardware might have missed a flow-control READY command, or maybe it does not support flow-control.", RNS.LOG_WARNING)
                                 self.process_queue()
 
                     if self.beacon_i != None and self.beacon_d != None:
@@ -274,7 +283,10 @@ class KISSInterface(Interface):
         except Exception as e:
             self.online = False
             RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
-            RNS.log("The interface "+str(self.name)+" is now offline. Restart Reticulum to attempt reconnection.", RNS.LOG_ERROR)
+            RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down. Restart Reticulum to attempt to open this interface again.", RNS.LOG_ERROR)
+
+            if RNS.Reticulum.panic_on_interface_error:
+                RNS.panic()
 
     def __str__(self):
         return "KISSInterface["+self.name+"]"

RNS/Interfaces/LocalInterface.py

@@ -24,6 +24,10 @@ class ThreadingTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
 class LocalClientInterface(Interface):
 
     def __init__(self, owner, name, target_port = None, connected_socket=None):
+        self.rxb = 0
+        self.txb = 0
+        self.online  = False
+        
         self.IN               = True
         self.OUT              = False
         self.socket           = None
@@ -36,6 +40,8 @@ class LocalClientInterface(Interface):
             self.target_port = None
             self.socket      = connected_socket
 
+            self.is_connected_to_shared_instance = False
+
         elif target_port != None:
             self.receives    = True
             self.target_ip   = "127.0.0.1"
@@ -56,6 +62,10 @@ class LocalClientInterface(Interface):
             thread.start()
 
     def processIncoming(self, data):
+        self.rxb += len(data)
+        if hasattr(self, "parent_interface") and self.parent_interface != None:
+            self.parent_interface.rxb += len(data)
+            
         self.owner.inbound(data, self)
 
     def processOutgoing(self, data):
@@ -68,6 +78,10 @@ class LocalClientInterface(Interface):
                 data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
                 self.socket.sendall(data)
                 self.writing = False
+                self.txb += len(data)
+                if hasattr(self, "parent_interface") and self.parent_interface != None:
+                    self.parent_interface.txb += len(data)
+
             except Exception as e:
                 RNS.log("Exception occurred while transmitting via "+str(self)+", tearing down interface", RNS.LOG_ERROR)
                 RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -106,7 +120,7 @@ class LocalClientInterface(Interface):
                                 data_buffer = data_buffer+bytes([byte])
                 else:
                     RNS.log("Socket for "+str(self)+" was closed, tearing down interface", RNS.LOG_VERBOSE)
-                    self.teardown()
+                    self.teardown(nowarning=True)
                     break
 
                 
@@ -116,7 +130,26 @@ class LocalClientInterface(Interface):
             RNS.log("Tearing down "+str(self), RNS.LOG_ERROR)
             self.teardown()
 
-    def teardown(self):
+    def detach(self):
+        if self.socket != None:
+            if hasattr(self.socket, "close"):
+                if callable(self.socket.close):
+                    RNS.log("Detaching "+str(self), RNS.LOG_DEBUG)
+                    self.detached = True
+                    
+                    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))
+
+                    self.socket = None
+
+    def teardown(self, nowarning=False):
         self.online = False
         self.OUT = False
         self.IN = False
@@ -126,6 +159,22 @@ class LocalClientInterface(Interface):
 
         if self in RNS.Transport.local_client_interfaces:
             RNS.Transport.local_client_interfaces.remove(self)
+            if hasattr(self, "parent_interface") and self.parent_interface != None:
+                self.parent_interface.clients -= 1
+
+        if nowarning == False:
+            RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down. Restart Reticulum to attempt to open this interface again.", RNS.LOG_ERROR)
+            if RNS.Reticulum.panic_on_interface_error:
+                RNS.panic()
+
+        if self.is_connected_to_shared_instance:
+            # TODO: Maybe add automatic recovery here.
+            # Needs thinking through, since user needs
+            # to now that all connectivity has been cut
+            # while service is recovering. Better for
+            # now to take down entire stack.
+            RNS.log("Lost connection to local shared RNS instance. Exiting now.", RNS.LOG_CRITICAL)
+            RNS.panic()
 
 
     def __str__(self):
@@ -135,6 +184,11 @@ class LocalClientInterface(Interface):
 class LocalServerInterface(Interface):
 
     def __init__(self, owner, bindport=None):
+        self.rxb = 0
+        self.txb = 0
+        self.online = False
+        self.clients = 0
+        
         self.IN  = True
         self.OUT = False
         self.name = "Reticulum"
@@ -153,12 +207,17 @@ class LocalServerInterface(Interface):
             self.is_local_shared_instance = True
 
             address = (self.bind_ip, self.bind_port)
+
+            ThreadingTCPServer.allow_reuse_address = True
             self.server = ThreadingTCPServer(address, handlerFactory(self.incoming_connection))
 
             thread = threading.Thread(target=self.server.serve_forever)
             thread.setDaemon(True)
             thread.start()
 
+            self.online = True
+
+
 
     def incoming_connection(self, handler):
         interface_name = str(str(handler.client_address[1]))
@@ -171,13 +230,14 @@ class LocalServerInterface(Interface):
         RNS.log("Accepting new connection to shared instance: "+str(spawned_interface), RNS.LOG_VERBOSE)
         RNS.Transport.interfaces.append(spawned_interface)
         RNS.Transport.local_client_interfaces.append(spawned_interface)
+        self.clients += 1
         spawned_interface.read_loop()
 
     def processOutgoing(self, data):
         pass
 
     def __str__(self):
-        return "Shared Instance ["+str(self.bind_port)+"]"
+        return "Shared Instance["+str(self.bind_port)+"]"
 
 class LocalInterfaceHandler(socketserver.BaseRequestHandler):
     def __init__(self, callback, *args, **keys):

RNS/Interfaces/RNodeInterface.py

@@ -72,6 +72,9 @@ class RNodeInterface(Interface):
     CALLSIGN_MAX_LEN    = 32
 
     def __init__(self, owner, name, port, frequency = None, bandwidth = None, txpower = None, sf = None, cr = None, flow_control = False, id_interval = None, id_callsign = None):
+        self.rxb = 0
+        self.txb = 0
+        
         self.serial      = None
         self.owner       = owner
         self.name        = name
@@ -273,15 +276,19 @@ class RNodeInterface(Interface):
         try:
             self.bitrate = self.r_sf * ( (4.0/self.r_cr) / (math.pow(2,self.r_sf)/(self.r_bandwidth/1000)) ) * 1000
             self.bitrate_kbps = round(self.bitrate/1000.0, 2)
-            RNS.log(str(self)+" On-air bitrate is now "+str(self.bitrate_kbps)+ " kbps", RNS.LOG_INFO)
+            RNS.log(str(self)+" On-air bitrate is now "+str(self.bitrate_kbps)+ " kbps", RNS.LOG_VERBOSE)
         except:
             self.bitrate = 0
 
     def processIncoming(self, data):
+        self.rxb += len(data)            
         self.owner.inbound(data, self)
+        self.r_stat_rssi = None
+        self.r_stat_snr = None
 
 
     def processOutgoing(self,data):
+        datalen = len(data)
         if self.online:
             if self.interface_ready:
                 if self.flow_control:
@@ -297,6 +304,7 @@ class RNodeInterface(Interface):
                 frame   = bytes([0xc0])+bytes([0x00])+data+bytes([0xc0])
 
                 written = self.serial.write(frame)
+                self.txb += datalen
 
                 if written != len(frame):
                     raise IOError("Serial interface only wrote "+str(written)+" bytes of "+str(len(data)))
@@ -463,7 +471,10 @@ class RNodeInterface(Interface):
         except Exception as e:
             self.online = False
             RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
-            RNS.log("The interface "+str(self.name)+" is now offline. Restart Reticulum to attempt reconnection.", RNS.LOG_ERROR)
+            RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down. Restart Reticulum to attempt to open this interface again.", RNS.LOG_ERROR)
+
+            if RNS.Reticulum.panic_on_interface_error:
+                RNS.panic()
 
     def __str__(self):
         return "RNodeInterface["+self.name+"]"

RNS/Interfaces/SerialInterface.py

@@ -31,6 +31,9 @@ class SerialInterface(Interface):
     serial   = None
 
     def __init__(self, owner, name, port, speed, databits, parity, stopbits):
+        self.rxb = 0
+        self.txb = 0
+        
         self.serial   = None
         self.owner    = owner
         self.name     = name
@@ -79,6 +82,7 @@ class SerialInterface(Interface):
 
 
     def processIncoming(self, data):
+        self.rxb += len(data)            
         self.owner.inbound(data, self)
 
 
@@ -86,6 +90,7 @@ class SerialInterface(Interface):
         if self.online:
             data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
             written = self.serial.write(data)
+            self.txb += len(data)            
             if written != len(data):
                 raise IOError("Serial interface only wrote "+str(written)+" bytes of "+str(len(data)))
 
@@ -130,7 +135,10 @@ class SerialInterface(Interface):
         except Exception as e:
             self.online = False
             RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
-            RNS.log("The interface "+str(self.name)+" is now offline. Restart Reticulum to attempt reconnection.", RNS.LOG_ERROR)
+            RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down. Restart Reticulum to attempt to open this interface again.", RNS.LOG_ERROR)
+
+            if RNS.Reticulum.panic_on_interface_error:
+                RNS.panic()
 
     def __str__(self):
         return "SerialInterface["+self.name+"]"

RNS/Interfaces/TCPInterface.py

@@ -1,6 +1,8 @@
 from .Interface import Interface
 import socketserver
 import threading
+import netifaces
+import platform
 import socket
 import time
 import sys
@@ -22,13 +24,36 @@ class ThreadingTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
     pass
 
 class TCPClientInterface(Interface):
+    RECONNECT_WAIT = 5
+    RECONNECT_MAX_TRIES = None
 
-    def __init__(self, owner, name, target_ip=None, target_port=None, connected_socket=None):
+    # TCP socket options
+    TCP_USER_TIMEOUT = 20
+    TCP_PROBE_AFTER = 5
+    TCP_PROBE_INTERVAL = 3
+    TCP_PROBES = 5
+
+    def __init__(self, owner, name, target_ip=None, target_port=None, connected_socket=None, max_reconnect_tries=None):
+        self.rxb = 0
+        self.txb = 0
+        
         self.IN               = True
         self.OUT              = False
         self.socket           = None
         self.parent_interface = None
         self.name             = name
+        self.initiator        = False
+        self.reconnecting     = False
+        self.never_connected  = True
+        self.owner            = owner
+        self.writing          = False
+        self.online           = False
+        self.detached         = False
+
+        if max_reconnect_tries == None:
+            self.max_reconnect_tries = TCPClientInterface.RECONNECT_MAX_TRIES
+        else:
+            self.max_reconnect_tries = max_reconnect_tries
 
         if connected_socket != None:
             self.receives    = True
@@ -36,24 +61,129 @@ class TCPClientInterface(Interface):
             self.target_port = None
             self.socket      = connected_socket
 
+            if platform.system() == "Linux":
+                self.set_timeouts_linux()
+            elif platform.system() == "Darwin":
+                self.set_timeouts_osx()
+
         elif target_ip != None and target_port != None:
             self.receives    = True
             self.target_ip   = target_ip
             self.target_port = target_port
+            self.initiator   = True
+            
+            if not self.connect(initial=True):
+                thread = threading.Thread(target=self.reconnect)
+                thread.setDaemon(True)
+                thread.start()
+            else:
+                thread = threading.Thread(target=self.read_loop)
+                thread.setDaemon(True)
+                thread.start()
+                self.wants_tunnel = True
 
+
+    def set_timeouts_linux(self):
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_USER_TIMEOUT, int(TCPClientInterface.TCP_USER_TIMEOUT * 1000))
+
+        self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, int(TCPClientInterface.TCP_PROBE_AFTER))
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, int(TCPClientInterface.TCP_PROBE_INTERVAL))
+        self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, int(TCPClientInterface.TCP_PROBES))
+
+    def set_timeouts_osx(self):
+        if hasattr(socket, "TCP_KEEPALIVE"):
+            TCP_KEEPIDLE = socket.TCP_KEEPALIVE
+        else:
+            TCP_KEEPIDLE = 0x10
+
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+        sock.setsockopt(socket.IPPROTO_TCP, TCP_KEEPIDLE, int(TCPClientInterface.TCP_PROBE_AFTER))
+
+    def detach(self):
+        if self.socket != None:
+            if hasattr(self.socket, "close"):
+                if callable(self.socket.close):
+                    RNS.log("Detaching "+str(self), RNS.LOG_DEBUG)
+                    self.detached = True
+                    
+                    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))
+
+                    self.socket = None
+
+    def connect(self, initial=False):
+        try:
             self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
             self.socket.connect((self.target_ip, self.target_port))
+            self.online  = True
+        
+        except Exception as e:
+            if initial:
+                RNS.log("Initial connection for "+str(self)+" could not be established: "+str(e), RNS.LOG_ERROR)
+                RNS.log("Leaving unconnected and retrying connection in "+str(TCPClientInterface.RECONNECT_WAIT)+" seconds.", RNS.LOG_ERROR)
+                return False
+            
+            else:
+                raise e
 
-        self.owner   = owner
+        if platform.system() == "Linux":
+            self.set_timeouts_linux()
+        elif platform.system() == "Darwin":
+            self.set_timeouts_osx()
+        
         self.online  = True
         self.writing = False
+        self.never_connected = False
 
-        if connected_socket == None:
-            thread = threading.Thread(target=self.read_loop)
-            thread.setDaemon(True)
-            thread.start()
+        return True
+
+
+    def reconnect(self):
+        if self.initiator:
+            if not self.reconnecting:
+                self.reconnecting = True
+                attempts = 0
+                while not self.online:
+                    time.sleep(TCPClientInterface.RECONNECT_WAIT)
+                    attempts += 1
+
+                    if self.max_reconnect_tries != None and attempts > self.max_reconnect_tries:
+                        RNS.log("Max reconnection attempts reached for "+str(self), RNS.LOG_ERROR)
+                        self.teardown()
+                        break
+
+                    try:
+                        self.connect()
+
+                    except Exception as e:
+                        RNS.log("Connection attempt for "+str(self)+" failed: "+str(e), RNS.LOG_DEBUG)
+
+                if not self.never_connected:
+                    RNS.log("Reconnected TCP socket for "+str(self)+".", RNS.LOG_INFO)
+
+                self.reconnecting = False
+                thread = threading.Thread(target=self.read_loop)
+                thread.setDaemon(True)
+                thread.start()
+                RNS.Transport.synthesize_tunnel(self)
+
+        else:
+            RNS.log("Attempt to reconnect on a non-initiator TCP interface. This should not happen.", RNS.LOG_ERROR)
+            raise IOError("Attempt to reconnect on a non-initiator TCP interface")
 
     def processIncoming(self, data):
+        self.rxb += len(data)
+        if hasattr(self, "parent_interface") and self.parent_interface != None:
+            self.parent_interface.rxb += len(data)
+                    
         self.owner.inbound(data, self)
 
     def processOutgoing(self, data):
@@ -66,6 +196,10 @@ class TCPClientInterface(Interface):
                 data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
                 self.socket.sendall(data)
                 self.writing = False
+                self.txb += len(data)
+                if hasattr(self, "parent_interface") and self.parent_interface != None:
+                    self.parent_interface.txb += len(data)
+
             except Exception as e:
                 RNS.log("Exception occurred while transmitting via "+str(self)+", tearing down interface", RNS.LOG_ERROR)
                 RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
@@ -103,23 +237,46 @@ class TCPClientInterface(Interface):
                                     escape = False
                                 data_buffer = data_buffer+bytes([byte])
                 else:
-                    RNS.log("TCP socket for "+str(self)+" was closed, tearing down interface", RNS.LOG_VERBOSE)
-                    self.teardown()
+                    self.online = False
+                    if self.initiator and not self.detached:
+                        RNS.log("TCP socket for "+str(self)+" was closed, attempting to reconnect...", RNS.LOG_WARNING)
+                        self.reconnect()
+                    else:
+                        RNS.log("TCP socket for remote client "+str(self)+" was closed.", RNS.LOG_VERBOSE)
+                        self.teardown()
+
                     break
 
                 
         except Exception as e:
             self.online = False
-            RNS.log("An interface error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
-            RNS.log("Tearing down "+str(self), RNS.LOG_ERROR)
-            self.teardown()
+            RNS.log("An interface error occurred for "+str(self)+", the contained exception was: "+str(e), RNS.LOG_WARNING)
+
+            if self.initiator:
+                RNS.log("Attempting to reconnect...", RNS.LOG_WARNING)
+                self.reconnect()
+            else:
+                self.teardown()
 
     def teardown(self):
+        if self.initiator and not self.detached:
+            RNS.log("The interface "+str(self)+" experienced an unrecoverable error and is being torn down. Restart Reticulum to attempt to open this interface again.", RNS.LOG_ERROR)
+            if RNS.Reticulum.panic_on_interface_error:
+                RNS.panic()
+
+        else:
+            RNS.log("The interface "+str(self)+" is being torn down.", RNS.LOG_VERBOSE)
+
         self.online = False
         self.OUT = False
         self.IN = False
+
+        if hasattr(self, "parent_interface") and self.parent_interface != None:
+            self.parent_interface.clients -= 1
+
         if self in RNS.Transport.interfaces:
-            RNS.Transport.interfaces.remove(self)
+            if not self.initiator:
+                RNS.Transport.interfaces.remove(self)
 
 
     def __str__(self):
@@ -127,12 +284,26 @@ class TCPClientInterface(Interface):
 
 
 class TCPServerInterface(Interface):
+    @staticmethod
+    def get_address_for_if(name):
+        return netifaces.ifaddresses(name)[netifaces.AF_INET][0]['addr']
 
-    def __init__(self, owner, name, bindip=None, bindport=None):
+    def get_broadcast_for_if(name):
+        return netifaces.ifaddresses(name)[netifaces.AF_INET][0]['broadcast']
+
+    def __init__(self, owner, name, device=None, bindip=None, bindport=None):
+        self.rxb = 0
+        self.txb = 0
+        self.online = False
+        self.clients = 0
+        
         self.IN  = True
         self.OUT = False
         self.name = name
 
+        if device != None:
+            bindip = TCPServerInterface.get_address_for_if(device)
+
         if (bindip != None and bindport != None):
             self.receives = True
             self.bind_ip = bindip
@@ -145,12 +316,16 @@ class TCPServerInterface(Interface):
 
             self.owner = owner
             address = (self.bind_ip, self.bind_port)
+
+            ThreadingTCPServer.allow_reuse_address = True
             self.server = ThreadingTCPServer(address, handlerFactory(self.incoming_connection))
 
             thread = threading.Thread(target=self.server.serve_forever)
             thread.setDaemon(True)
             thread.start()
 
+            self.online = True
+
 
     def incoming_connection(self, handler):
         RNS.log("Accepting incoming TCP connection", RNS.LOG_VERBOSE)
@@ -161,8 +336,10 @@ class TCPServerInterface(Interface):
         spawned_interface.target_ip = handler.client_address[0]
         spawned_interface.target_port = str(handler.client_address[1])
         spawned_interface.parent_interface = self
+        spawned_interface.online = True
         RNS.log("Spawned new TCPClient Interface: "+str(spawned_interface), RNS.LOG_VERBOSE)
         RNS.Transport.interfaces.append(spawned_interface)
+        self.clients += 1
         spawned_interface.read_loop()
 
     def processOutgoing(self, data):

RNS/Interfaces/UDPInterface.py

@@ -1,17 +1,36 @@
 from .Interface import Interface
 import socketserver
 import threading
+import netifaces
 import socket
 import time
 import sys
 import RNS
 
+
 class UDPInterface(Interface):
 
-    def __init__(self, owner, name, bindip=None, bindport=None, forwardip=None, forwardport=None):
+    @staticmethod
+    def get_address_for_if(name):
+        return netifaces.ifaddresses(name)[netifaces.AF_INET][0]['addr']
+
+    def get_broadcast_for_if(name):
+        return netifaces.ifaddresses(name)[netifaces.AF_INET][0]['broadcast']
+
+    def __init__(self, owner, name, device=None, bindip=None, bindport=None, forwardip=None, forwardport=None):
+        self.rxb = 0
+        self.txb = 0
         self.IN  = True
         self.OUT = False
         self.name = name
+        self.online = False
+
+        if device != None:
+            if bindip == None:
+                bindip = UDPInterface.get_broadcast_for_if(device)
+            if forwardip == None:
+                forwardip = UDPInterface.get_broadcast_for_if(device)
+
 
         if (bindip != None and bindport != None):
             self.receives = True
@@ -31,6 +50,8 @@ class UDPInterface(Interface):
             thread.setDaemon(True)
             thread.start()
 
+            self.online = True
+
         if (forwardip != None and forwardport != None):
             self.forwards = True
             self.forward_ip = forwardip
@@ -38,12 +59,18 @@ class UDPInterface(Interface):
 
 
     def processIncoming(self, data):
+        self.rxb += len(data)
         self.owner.inbound(data, self)
 
     def processOutgoing(self,data):
-        udp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
-        udp_socket.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
-        udp_socket.sendto(data, (self.forward_ip, self.forward_port))
+        try:
+            udp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            udp_socket.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+            udp_socket.sendto(data, (self.forward_ip, self.forward_port))
+            self.txb += len(data)
+            
+        except Exception as e:
+            RNS.log("Could not transmit on "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
 
     def __str__(self):

RNS/Packet.py

@@ -5,6 +5,23 @@ import time
 import RNS
 
 class Packet:
+    """
+    The Packet class is used to create packet instances that can be sent
+    over a Reticulum network. Packets to will automatically be encrypted if
+    they are adressed to a ``RNS.Destination.SINGLE`` destination,
+    ``RNS.Destination.GROUP`` destination or a :ref:`RNS.Link<api-link>`.
+
+    For ``RNS.Destination.GROUP`` destinations, Reticulum will use the
+    pre-shared key configured for the destination.
+
+    For ``RNS.Destination.SINGLE`` destinations and :ref:`RNS.Link<api-link>`
+    destinations, reticulum will use ephemeral keys, and offers **Forward Secrecy**.
+
+    :param destination: A :ref:`RNS.Destination<api-destination>` instance to which the packet will be sent.
+    :param data: The data payload to be included in the packet as *bytes*.
+    :param create_receipt: Specifies whether a :ref:`RNS.PacketReceipt<api-packetreceipt>` should be created when instantiating the packet.
+    """
+
     # Packet types
     DATA         = 0x00     # Data packets
     ANNOUNCE     = 0x01     # Announces
@@ -19,7 +36,7 @@ class Packet:
     HEADER_4     = 0x03     # Reserved
     header_types = [HEADER_1, HEADER_2, HEADER_3, HEADER_4]
 
-    # Data packet context types
+    # Packet context types
     NONE           = 0x00   # Generic data packet
     RESOURCE       = 0x01   # Packet is part of a resource
     RESOURCE_ADV   = 0x02   # Packet is a resource advertisement
@@ -34,7 +51,8 @@ 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
-    KEEPALIVE      = 0xFB   # Packet is a keepalive packet
+    KEEPALIVE      = 0xFA   # Packet is a keepalive packet
+    LINKIDENTIFY   = 0xFB   # Packet is a link peer identification proof
     LINKCLOSE      = 0xFC   # Packet is a link close message
     LINKPROOF      = 0xFD   # Packet is a link packet proof
     LRRTT          = 0xFE   # Packet is a link request round-trip time measurement
@@ -42,19 +60,24 @@ class Packet:
 
     # This is used to calculate allowable
     # payload sizes
-    HEADER_MAXSIZE = 23
+    HEADER_MAXSIZE = RNS.Reticulum.HEADER_MAXSIZE
     MDU            = RNS.Reticulum.MDU
 
-    # With an MTU of 500, the maximum RSA-encrypted
-    # amount of data we can send in a single packet
-    # is given by the below calculation; 258 bytes.
-    RSA_MDU   = math.floor(MDU/RNS.Identity.DECRYPT_CHUNKSIZE)*RNS.Identity.ENCRYPT_CHUNKSIZE
-    PLAIN_MDU = MDU
+    # With an MTU of 500, the maximum of data we can
+    # send in a single encrypted packet is given by
+    # the below calculation; 383 bytes.
+    ENCRYPTED_MDU  = math.floor((RNS.Reticulum.MDU-RNS.Identity.FERNET_OVERHEAD-RNS.Identity.KEYSIZE//16)/RNS.Identity.AES128_BLOCKSIZE)*RNS.Identity.AES128_BLOCKSIZE - 1
+    """
+    The maximum size of the payload data in a single encrypted packet 
+    """
+    PLAIN_MDU      = MDU
+    """
+    The maximum size of the payload data in a single unencrypted packet 
+    """
 
-    # TODO: This should be calculated
-    # more intelligently
-    # Default packet timeout
-    TIMEOUT      = 60
+    # This value is set at a reasonable
+    # level for a 1 Kb/s channel.
+    TIMEOUT_PER_HOP = 5
 
     def __init__(self, destination, data, packet_type = DATA, context = NONE, transport_type = RNS.Transport.BROADCAST, header_type = HEADER_1, transport_id = None, attached_interface = None, create_receipt = True):
         if destination != None:
@@ -70,7 +93,7 @@ class Packet:
             self.destination    = destination
             self.transport_id   = transport_id
             self.data           = data
-            self.flags          = self.getPackedFlags()
+            self.flags          = self.get_packed_flags()
 
             self.raw            = None
             self.packed         = False
@@ -90,8 +113,10 @@ class Packet:
 
         self.attached_interface = attached_interface
         self.receiving_interface = None
+        self.rssi = None
+        self.snr = None
 
-    def getPackedFlags(self):
+    def get_packed_flags(self):
         if self.context == Packet.LRPROOF:
             packed_flags = (self.header_type << 6) | (self.transport_type << 4) | RNS.Destination.LINK | self.packet_type
         else:
@@ -114,6 +139,9 @@ class Packet:
                 if self.packet_type == Packet.ANNOUNCE:
                     # Announce packets are not encrypted
                     self.ciphertext = self.data
+                elif self.packet_type == Packet.LINKREQUEST:
+                    # Link request packets are not encrypted
+                    self.ciphertext = self.data
                 elif self.packet_type == Packet.PROOF and self.context == Packet.RESOURCE_PRF:
                     # Resource proofs are not encrypted
                     self.ciphertext = self.data
@@ -155,7 +183,8 @@ class Packet:
             raise IOError("Packet size of "+str(len(self.raw))+" exceeds MTU of "+str(self.MTU)+" bytes")
 
         self.packed = True
-        self.updateHash()
+        self.update_hash()
+
 
     def unpack(self):
         self.flags = self.raw[0]
@@ -178,12 +207,14 @@ class Packet:
             self.data = self.raw[13:]
 
         self.packed = False
-        self.updateHash()
+        self.update_hash()
 
-    # Sends the packet. Returns a receipt if one is generated,
-    # or None if no receipt is available. Returns False if the
-    # packet could not be sent.
     def send(self):
+        """
+        Sends the packet.
+        
+        :returns: A :ref:`RNS.PacketReceipt<api-packetreceipt>` instance if *create_receipt* was set to *True* when the packet was instantiated, if not returns *None*. If the packet could not be sent *False* is returned.
+        """
         if not self.sent:
             if self.destination.type == RNS.Destination.LINK:
                 if self.destination.status == RNS.Link.CLOSED:
@@ -208,6 +239,11 @@ class Packet:
             raise IOError("Packet was already sent")
 
     def resend(self):
+        """
+        Re-sends the packet.
+        
+        :returns: A :ref:`RNS.PacketReceipt<api-packetreceipt>` instance if *create_receipt* was set to *True* when the packet was instantiated, if not returns *None*. If the packet could not be sent *False* is returned.
+        """
         if self.sent:
             if RNS.Transport.outbound(self):
                 return self.receipt
@@ -230,25 +266,25 @@ class Packet:
 
     # Generates a special destination that allows Reticulum
     # to direct the proof back to the proved packet's sender
-    def generateProofDestination(self):
+    def generate_proof_destination(self):
         return ProofDestination(self)
 
-    def validateProofPacket(self, proof_packet):
-        return self.receipt.validateProofPacket(proof_packet)
+    def validate_proof_packet(self, proof_packet):
+        return self.receipt.validate_proof_packet(proof_packet)
 
-    def validateProof(self, proof):
-        return self.receipt.validateProof(proof)
+    def validate_proof(self, proof):
+        return self.receipt.validate_proof(proof)
 
-    def updateHash(self):
-        self.packet_hash = self.getHash()
+    def update_hash(self):
+        self.packet_hash = self.get_hash()
 
-    def getHash(self):
-        return RNS.Identity.fullHash(self.getHashablePart())
+    def get_hash(self):
+        return RNS.Identity.full_hash(self.get_hashable_part())
 
     def getTruncatedHash(self):
-        return RNS.Identity.truncatedHash(self.getHashablePart())
+        return RNS.Identity.truncated_hash(self.get_hashable_part())
 
-    def getHashablePart(self):
+    def get_hashable_part(self):
         hashable_part = bytes([self.raw[0] & 0b00001111])
         if self.header_type == Packet.HEADER_2:
             hashable_part += self.raw[12:]
@@ -259,7 +295,7 @@ class Packet:
 
 class ProofDestination:
     def __init__(self, packet):
-        self.hash = packet.getHash()[:10];
+        self.hash = packet.get_hash()[:10];
         self.type = RNS.Destination.SINGLE
 
     def encrypt(self, plaintext):
@@ -267,6 +303,12 @@ class ProofDestination:
 
 
 class PacketReceipt:
+    """
+    The PacketReceipt class is used to receive notifications about
+    :ref:`RNS.Packet<api-packet>` instances sent over the network. Instances
+    of this class are never created manually, but always returned from
+    the *send()* method of a :ref:`RNS.Packet<api-packet>` instance.
+    """
     # Receipt status constants
     FAILED    = 0x00
     SENT      = 0x01
@@ -279,25 +321,38 @@ class PacketReceipt:
 
     # Creates a new packet receipt from a sent packet
     def __init__(self, packet):
-        self.hash    = packet.getHash()
-        self.sent    = True
-        self.sent_at = time.time()
-        self.timeout = Packet.TIMEOUT
-        self.proved  = False
-        self.status  = PacketReceipt.SENT
-        self.destination = packet.destination
-        self.callbacks   = PacketReceiptCallbacks()
-        self.concluded_at = None
+        self.hash           = packet.get_hash()
+        self.truncated_hash = packet.getTruncatedHash()
+        self.sent           = True
+        self.sent_at        = time.time()
+        self.proved         = False
+        self.status         = PacketReceipt.SENT
+        self.destination    = packet.destination
+        self.callbacks      = PacketReceiptCallbacks()
+        self.concluded_at   = None
+        self.proof_packet   = None
+
+        if packet.destination.type == RNS.Destination.LINK:
+            self.timeout    = packet.destination.rtt * packet.destination.traffic_timeout_factor
+        else:
+            self.timeout    = Packet.TIMEOUT_PER_HOP * RNS.Transport.hops_to(self.destination.hash)
+
+
+    def get_status(self):
+        """
+        :returns: The status of the associated :ref:`RNS.Packet<api-packet>` instance. Can be one of ``RNS.PacketReceipt.SENT``, ``RNS.PacketReceipt.DELIVERED``, ``RNS.PacketReceipt.FAILED`` or ``RNS.PacketReceipt.CULLED``. 
+        """
+        return self.status
 
     # Validate a proof packet
-    def validateProofPacket(self, proof_packet):
+    def validate_proof_packet(self, proof_packet):
         if hasattr(proof_packet, "link") and proof_packet.link:
-            return self.validate_link_proof(proof_packet.data, proof_packet.link)
+            return self.validate_link_proof(proof_packet.data, proof_packet.link, proof_packet)
         else:
-            return self.validateProof(proof_packet.data)
+            return self.validate_proof(proof_packet.data, proof_packet)
 
     # Validate a raw proof for a link
-    def validate_link_proof(self, proof, link):
+    def validate_link_proof(self, proof, link, proof_packet=None):
         # TODO: Hardcoded as explicit proofs for now
         if True or len(proof) == PacketReceipt.EXPL_LENGTH:
             # This is an explicit proof
@@ -309,6 +364,8 @@ class PacketReceipt:
                     self.status = PacketReceipt.DELIVERED
                     self.proved = True
                     self.concluded_at = time.time()
+                    self.proof_packet = proof_packet
+
                     if self.callbacks.delivery != None:
                         self.callbacks.delivery(self)
                     return True
@@ -336,7 +393,7 @@ class PacketReceipt:
             return False
 
     # Validate a raw proof
-    def validateProof(self, proof):
+    def validate_proof(self, proof, proof_packet=None):
         if len(proof) == PacketReceipt.EXPL_LENGTH:
             # This is an explicit proof
             proof_hash = proof[:RNS.Identity.HASHLENGTH//8]
@@ -347,8 +404,14 @@ class PacketReceipt:
                     self.status = PacketReceipt.DELIVERED
                     self.proved = True
                     self.concluded_at = time.time()
+                    self.proof_packet = proof_packet
+
                     if self.callbacks.delivery != None:
-                        self.callbacks.delivery(self)
+                        try:
+                            self.callbacks.delivery(self)
+                        except Exception as e:
+                            RNS.log("Error while executing proof validated callback. The contained exception was: "+str(e), RNS.LOG_ERROR)
+
                     return True
                 else:
                     return False
@@ -365,22 +428,31 @@ class PacketReceipt:
                     self.status = PacketReceipt.DELIVERED
                     self.proved = True
                     self.concluded_at = time.time()
+                    self.proof_packet = proof_packet
+
                     if self.callbacks.delivery != None:
-                        self.callbacks.delivery(self)
+                        try:
+                            self.callbacks.delivery(self)
+                        except Exception as e:
+                            RNS.log("Error while executing proof validated callback. The contained exception was: "+str(e), RNS.LOG_ERROR)
+                            
                     return True
             else:
                 return False
         else:
             return False
 
-    def rtt(self):
+    def get_rtt(self):
+        """
+        :returns: The round-trip-time in seconds
+        """
         return self.concluded_at - self.sent_at
 
     def is_timed_out(self):
         return (self.sent_at+self.timeout < time.time())
 
     def check_timeout(self):
-        if self.is_timed_out():
+        if self.status == PacketReceipt.SENT and self.is_timed_out():
             if self.timeout == -1:
                 self.status = PacketReceipt.CULLED
             else:
@@ -392,21 +464,32 @@ class PacketReceipt:
                 thread = threading.Thread(target=self.callbacks.timeout, args=(self,))
                 thread.setDaemon(True)
                 thread.start()
-                #self.callbacks.timeout(self)
 
 
-    # Set the timeout in seconds
     def set_timeout(self, timeout):
+        """
+        Sets a timeout in seconds
+        
+        :param timeout: The timeout in seconds.
+        """
         self.timeout = float(timeout)
 
-    # Set a function that gets called when
-    # a successfull delivery has been proved
-    def delivery_callback(self, callback):
+    def set_delivery_callback(self, callback):
+        """
+        Sets a function that gets called if a successfull delivery has been proven.
+
+        :param callback: A *callable* with the signature *callback(packet_receipt)*
+        """
         self.callbacks.delivery = callback
 
     # Set a function that gets called if the
     # delivery times out
-    def timeout_callback(self, callback):
+    def set_timeout_callback(self, callback):
+        """
+        Sets a function that gets called if the delivery times out.
+
+        :param callback: A *callable* with the signature *callback(packet_receipt)*
+        """
         self.callbacks.timeout = callback
 
 class PacketReceiptCallbacks:

RNS/Resource.py

@@ -8,6 +8,18 @@ from .vendor import umsgpack as umsgpack
 from time import sleep
 
 class Resource:
+    """
+    The Resource class allows transferring arbitrary amounts
+    of data over a link. It will automatically handle sequencing,
+    compression, coordination and checksumming.
+
+    :param data: The data to be transferred. Can be *bytes* or an open *file handle*. See the :ref:`Filetransfer Example<example-filetransfer>` for details.
+    :param link: The :ref:`RNS.Link<api-link>` instance on which to transfer the data.
+    :param advertise: Optional. Whether to automatically advertise the resource. Can be *True* or *False*.
+    :param auto_compress: Optional. Whether to auto-compress the resource. Can be *True* or *False*.
+    :param callback: An optional *callable* with the signature *callback(resource)*. Will be called when the resource transfer concludes.
+    :param progress_callback: An optional *callable* with the signature *callback(resource)*. Will be called whenever the resource transfer progress is updated.
+    """
     WINDOW_FLEXIBILITY   = 4
     WINDOW_MIN           = 1
     WINDOW_MAX           = 10
@@ -25,39 +37,47 @@ class Resource:
     # defined as a Raspberry Pi, which should
     # be able to compress, encrypt and hash-map
     # the resource in about 10 seconds.
-    MAX_EFFICIENT_SIZE   = 16 * 1024 * 1024
-
+    #
+    # This constant will be used when determining
+    # how to sequence the sending of large resources.
+    #
+    # Capped at 16777215 (0xFFFFFF) per segment to
+    # fit in 3 bytes in resource advertisements.
+    MAX_EFFICIENT_SIZE      = 16 * 1024 * 1024 - 1
+    RESPONSE_MAX_GRACE_TIME = 10
+    
     # The maximum size to auto-compress with
     # bz2 before sending.
     AUTO_COMPRESS_MAX_SIZE = MAX_EFFICIENT_SIZE
 
-    # TODO: Should be allocated more
-    # intelligently
-    # TODO: Set higher
-    MAX_RETRIES       = 5
-    SENDER_GRACE_TIME = 10
-    RETRY_GRACE_TIME  = 0.25
+    PART_TIMEOUT_FACTOR           = 4
+    PART_TIMEOUT_FACTOR_AFTER_RTT = 2
+    MAX_RETRIES                   = 5
+    SENDER_GRACE_TIME             = 10
+    RETRY_GRACE_TIME              = 0.25
+
+    WATCHDOG_MAX_SLEEP            = 1
 
     HASHMAP_IS_NOT_EXHAUSTED = 0x00
     HASHMAP_IS_EXHAUSTED = 0xFF
 
     # Status constants
-    NONE             = 0x00
-    QUEUED             = 0x01
-    ADVERTISED         = 0x02
+    NONE            = 0x00
+    QUEUED          = 0x01
+    ADVERTISED      = 0x02
     TRANSFERRING    = 0x03
     AWAITING_PROOF  = 0x04
     ASSEMBLING      = 0x05
     COMPLETE        = 0x06
-    FAILED            = 0x07
-    CORRUPT            = 0x08
+    FAILED          = 0x07
+    CORRUPT         = 0x08
 
     @staticmethod
-    def accept(advertisement_packet, callback=None, progress_callback = None):
+    def accept(advertisement_packet, callback=None, progress_callback = None, request_id = None):
         try:
             adv = ResourceAdvertisement.unpack(advertisement_packet.plaintext)
 
-            resource = Resource(None, advertisement_packet.link)
+            resource = Resource(None, advertisement_packet.link, request_id = request_id)
             resource.status = Resource.TRANSFERRING
 
             resource.flags               = adv.f
@@ -102,7 +122,11 @@ class Resource:
             resource.link.register_incoming_resource(resource)
 
             RNS.log("Accepting resource advertisement for "+RNS.prettyhexrep(resource.hash), RNS.LOG_DEBUG)
-            resource.link.callbacks.resource_started(resource)
+            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)
 
             resource.hashmap_update(0, resource.hashmap_raw)
 
@@ -111,14 +135,12 @@ class Resource:
             return resource
         except Exception as e:
             RNS.log("Could not decode resource advertisement, dropping resource", RNS.LOG_DEBUG)
-            # TODO: Remove
-            raise e
             return None
 
     # Create a resource for transmission to a remote destination
     # The data passed can be either a bytes-array or a file opened
     # in binary read mode.
-    def __init__(self, data, link, advertise=True, auto_compress=True, must_compress=False, callback=None, progress_callback=None, segment_index = 1, original_hash = None):
+    def __init__(self, data, link, advertise=True, auto_compress=True, callback=None, progress_callback=None, timeout = None, segment_index = 1, original_hash = None, request_id = None, is_response = False):
         data_size = None
         resource_data = None
         if hasattr(data, "read"):
@@ -165,24 +187,32 @@ class Resource:
         self.link = link
         self.max_retries = Resource.MAX_RETRIES
         self.retries_left = self.max_retries
-        self.default_timeout = self.link.default_timeout
-        self.timeout_factor = self.link.timeout_factor
+        self.timeout_factor = self.link.traffic_timeout_factor
+        self.part_timeout_factor = Resource.PART_TIMEOUT_FACTOR
         self.sender_grace_time = Resource.SENDER_GRACE_TIME
         self.hmu_retry_ok = False
         self.watchdog_lock = False
         self.__watchdog_job_id = 0
         self.__progress_callback = progress_callback
         self.rtt = None
+        self.request_id = request_id
+        self.is_response = is_response
 
+        self.req_hashlist = []
         self.receiver_min_consecutive_height = 0
 
+        if timeout != None:
+            self.timeout = timeout
+        else:
+            self.timeout = self.link.rtt * self.link.traffic_timeout_factor
+
         if data != None:
             self.initiator         = True
             self.callback          = callback
             self.uncompressed_data = data
 
             compression_began = time.time()
-            if must_compress or (auto_compress and len(self.uncompressed_data) < Resource.AUTO_COMPRESS_MAX_SIZE):
+            if (auto_compress and len(self.uncompressed_data) < Resource.AUTO_COMPRESS_MAX_SIZE):
                 RNS.log("Compressing resource data...", RNS.LOG_DEBUG)
                 self.compressed_data   = bz2.compress(self.uncompressed_data)
                 RNS.log("Compression completed in "+str(round(time.time()-compression_began, 3))+" seconds", RNS.LOG_DEBUG)
@@ -197,7 +227,7 @@ class Resource:
                 RNS.log("Compression saved "+str(saved_bytes)+" bytes, sending compressed", RNS.LOG_DEBUG)
 
                 self.data  = b""
-                self.data += RNS.Identity.getRandomHash()[:Resource.RANDOM_HASH_SIZE]
+                self.data += RNS.Identity.get_random_hash()[:Resource.RANDOM_HASH_SIZE]
                 self.data += self.compressed_data
                 
                 self.compressed = True
@@ -205,7 +235,7 @@ class Resource:
 
             else:
                 self.data  = b""
-                self.data += RNS.Identity.getRandomHash()[:Resource.RANDOM_HASH_SIZE]
+                self.data += RNS.Identity.get_random_hash()[:Resource.RANDOM_HASH_SIZE]
                 self.data += self.uncompressed_data
                 self.uncompressed_data = self.data
 
@@ -218,11 +248,8 @@ class Resource:
             # make optimal use of packet MTU on an entire
             # encrypted stream. The Resource instance will
             # use it's underlying link directly to encrypt.
-            if not self.link.encryption_disabled():
-                self.data = self.link.encrypt(self.data)
-                self.encrypted = True
-            else:
-                self.encrypted = False
+            self.data = self.link.encrypt(self.data)
+            self.encrypted = True
 
             self.size = len(self.data)
             self.sent_parts = 0
@@ -233,9 +260,10 @@ class Resource:
                 hashmap_computation_began = time.time()
                 RNS.log("Starting resource hashmap computation with "+str(hashmap_entries)+" entries...", RNS.LOG_DEBUG)
 
-                self.random_hash       = RNS.Identity.getRandomHash()[:Resource.RANDOM_HASH_SIZE]
-                self.hash = RNS.Identity.fullHash(data+self.random_hash)
-                self.expected_proof = RNS.Identity.fullHash(data+self.hash)
+                self.random_hash       = RNS.Identity.get_random_hash()[:Resource.RANDOM_HASH_SIZE]
+                self.hash = RNS.Identity.full_hash(data+self.random_hash)
+                self.truncated_hash = RNS.Identity.truncated_hash(data+self.random_hash)
+                self.expected_proof = RNS.Identity.full_hash(data+self.hash)
 
                 if original_hash == None:
                     self.original_hash = self.hash
@@ -247,7 +275,7 @@ class Resource:
                 collision_guard_list = []
                 for i in range(0,hashmap_entries):
                     data = self.data[i*Resource.SDU:(i+1)*Resource.SDU]
-                    map_hash = self.getMapHash(data)
+                    map_hash = self.get_map_hash(data)
 
                     if map_hash in collision_guard_list:
                         RNS.log("Found hash collision in resource map, remapping...", RNS.LOG_VERBOSE)
@@ -295,14 +323,18 @@ class Resource:
             self.waiting_for_hmu = False
             self.request_next()
 
-    def getMapHash(self, data):
+    def get_map_hash(self, data):
         # TODO: This will break if running unencrypted,
         # uncompressed transfers on streams with long blocks
         # of identical bytes. Doing so would be very silly
         # anyways but maybe it should be handled gracefully.
-        return RNS.Identity.fullHash(data+self.random_hash)[:Resource.MAPHASH_LEN]
+        return RNS.Identity.full_hash(data+self.random_hash)[:Resource.MAPHASH_LEN]
 
     def advertise(self):
+        """
+        Advertise the resource. If the other end of the link accepts
+        the resource advertisement it will begin transferring.
+        """
         thread = threading.Thread(target=self.__advertise_job)
         thread.setDaemon(True)
         thread.start()
@@ -345,7 +377,7 @@ class Resource:
             sleep_time = None
 
             if self.status == Resource.ADVERTISED:
-                sleep_time = (self.adv_sent+self.default_timeout)-time.time()
+                sleep_time = (self.adv_sent+self.timeout)-time.time()
                 if sleep_time < 0:
                     if self.retries_left <= 0:
                         RNS.log("Resource transfer timeout after sending advertisement", RNS.LOG_DEBUG)
@@ -366,8 +398,24 @@ class Resource:
 
             elif self.status == Resource.TRANSFERRING:
                 if not self.initiator:
-                    rtt = self.link.rtt if self.rtt == None else self.rtt
-                    sleep_time = self.last_activity + (rtt*self.timeout_factor) + Resource.RETRY_GRACE_TIME - time.time()
+
+                    if self.rtt == None:
+                        rtt = self.link.rtt
+                    else:
+                        rtt = self.rtt
+
+                    window_remaining = self.outstanding_parts
+
+                    sleep_time = self.last_activity + (rtt*(self.part_timeout_factor+window_remaining)) + Resource.RETRY_GRACE_TIME - time.time()
+                    
+                    # TODO: Remove debug info
+                    # RNS.log("rtt   "+str(rtt))
+                    # RNS.log("ptof  "+str(self.part_timeout_factor))
+                    # RNS.log("wait  "+str((rtt*self.part_timeout_factor) + Resource.RETRY_GRACE_TIME))
+                    # RNS.log("sleep "+str(sleep_time))
+                    # RNS.log("wndw  "+str(self.window))
+                    # RNS.log("wndwr "+str(window_remaining))
+                    # RNS.log("")
 
                     if sleep_time < 0:
                         if self.retries_left > 0:
@@ -418,7 +466,7 @@ class Resource:
                 self.cancel()
             
             if sleep_time != None:
-                sleep(sleep_time)
+                sleep(min(sleep_time, Resource.WATCHDOG_MAX_SLEEP))
 
     def assemble(self):
         if not self.status == Resource.FAILED:
@@ -439,7 +487,7 @@ class Resource:
                 else:
                     self.data = data
 
-                calculated_hash = RNS.Identity.fullHash(self.data+self.random_hash)
+                calculated_hash = RNS.Identity.full_hash(self.data+self.random_hash)
 
                 if calculated_hash == self.hash:
                     self.file = open(self.storagepath, "ab")
@@ -461,7 +509,10 @@ class Resource:
             if self.segment_index == self.total_segments:
                 if self.callback != None:
                     self.data = open(self.storagepath, "rb")
-                    self.callback(self)
+                    try:
+                        self.callback(self)
+                    except Exception as e:
+                        RNS.log("Error while executing resource assembled callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
                 try:
                     self.data.close()
@@ -476,7 +527,7 @@ class Resource:
     def prove(self):
         if not self.status == Resource.FAILED:
             try:
-                proof = RNS.Identity.fullHash(self.data+self.hash)
+                proof = RNS.Identity.full_hash(self.data+self.hash)
                 proof_data = self.hash+proof
                 proof_packet = RNS.Packet(self.link, proof_data, packet_type=RNS.Packet.PROOF, context=RNS.Packet.RESOURCE_PRF)
                 proof_packet.send()
@@ -485,7 +536,7 @@ class Resource:
                 RNS.log("The contained exception was: "+str(e), RNS.LOG_DEBUG)
                 self.cancel()
 
-    def validateProof(self, proof_data):
+    def validate_proof(self, proof_data):
         if not self.status == Resource.FAILED:
             if len(proof_data) == RNS.Identity.HASHLENGTH//8*2:
                 if proof_data[RNS.Identity.HASHLENGTH//8:] == self.expected_proof:
@@ -495,7 +546,10 @@ class Resource:
                         # If all segments were processed, we'll
                         # signal that the resource sending concluded
                         if self.callback != None:
-                            self.callback(self)
+                            try:
+                                self.callback(self)
+                            except Exception as e:
+                                RNS.log("Error while executing resource concluded callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
                     else:
                         # Otherwise we'll recursively create the
                         # next segment of the resource
@@ -517,16 +571,20 @@ class Resource:
         if self.req_resp == None:
             self.req_resp = self.last_activity
             rtt = self.req_resp-self.req_sent
+
+            self.part_timeout_factor = Resource.PART_TIMEOUT_FACTOR_AFTER_RTT
             if self.rtt == None:
-                self.rtt = rtt
+                self.rtt = self.link.rtt
                 self.watchdog_job()
-            elif self.rtt < rtt:
-                self.rtt = rtt
+            elif rtt < self.rtt:
+                self.rtt = max(self.rtt - self.rtt*0.05, rtt)
+            elif rtt > self.rtt:
+                self.rtt = min(self.rtt + self.rtt*0.05, rtt)
 
         if not self.status == Resource.FAILED:
             self.status = Resource.TRANSFERRING
             part_data = packet.data
-            part_hash = self.getMapHash(part_data)
+            part_hash = self.get_map_hash(part_data)
 
             i = self.consecutive_completed_height
             for map_hash in self.hashmap[self.consecutive_completed_height:self.consecutive_completed_height+self.window]:
@@ -546,14 +604,22 @@ class Resource:
                             self.consecutive_completed_height = cp
                             cp += 1
 
+                        if self.__progress_callback != None:
+                            try:
+                                self.__progress_callback(self)
+                            except Exception as e:
+                                RNS.log("Error while executing progress callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
+
+                        # TODO: Remove debug info
+                        # RNS.log("outstanding_parts "+str(self.outstanding_parts))
+                        # RNS.log("total_parts "+str(self.total_parts))
+                        # RNS.log("received_count "+str(self.received_count))
+
                 i += 1
 
             self.receiving_part = False
 
-            if self.__progress_callback != None:
-                self.__progress_callback(self)
-
-            if self.outstanding_parts == 0 and self.received_count == self.total_parts:
+            if self.received_count == self.total_parts:
                 self.assemble()
             elif self.outstanding_parts == 0:
                 # TODO: Figure out if there is a mathematically
@@ -671,6 +737,7 @@ class Resource:
                 if part_index % ResourceAdvertisement.HASHMAP_MAX_LEN != 0:
                     RNS.log("Resource sequencing error, cancelling transfer!", RNS.LOG_ERROR)
                     self.cancel()
+                    return
                 else:
                     segment = part_index // ResourceAdvertisement.HASHMAP_MAX_LEN
 
@@ -697,9 +764,15 @@ class Resource:
                 self.status = Resource.AWAITING_PROOF
 
             if self.__progress_callback != None:
-                self.__progress_callback(self)
+                try:
+                    self.__progress_callback(self)
+                except Exception as e:
+                    RNS.log("Error while executing progress callback from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
 
     def cancel(self):
+        """
+        Cancels transferring the resource.
+        """
         if self.status < Resource.COMPLETE:
             self.status = Resource.FAILED
             if self.initiator:
@@ -714,16 +787,23 @@ class Resource:
                 self.link.cancel_incoming_resource(self)
             
             if self.callback != None:
-                self.link.resource_concluded(self)
-                self.callback(self)
+                try:
+                    self.link.resource_concluded(self)
+                    self.callback(self)
+                except Exception as e:
+                    RNS.log("Error while executing callbacks on resource cancel from "+str(self)+". The contained exception was: "+str(e), RNS.LOG_ERROR)
+
+    def set_callback(self, callback):
+        self.callback = callback
 
     def progress_callback(self, callback):
         self.__progress_callback = callback
 
-    def progress(self):
+    def get_progress(self):
+        """
+        :returns: The current progress of the resource transfer as a *float* between 0.0 and 1.0.
+        """
         if self.initiator:
-            # TODO: Remove
-            # progress = self.sent_parts / len(self.parts)
             self.processed_parts  = (self.segment_index-1)*math.ceil(Resource.MAX_EFFICIENT_SIZE/Resource.SDU)
             self.processed_parts += self.sent_parts
             self.progress_total_parts = float(self.grand_total_parts)
@@ -740,28 +820,82 @@ class Resource:
         return progress
 
     def __str__(self):
-        return RNS.prettyhexrep(self.hash)+str(self.link)
+        return "<"+RNS.hexrep(self.hash)+"/"+RNS.hexrep(self.link.link_id)+">"
 
 
 class ResourceAdvertisement:
-    HASHMAP_MAX_LEN      = 75
+    OVERHEAD             = 128
+    HASHMAP_MAX_LEN      = math.floor((RNS.Link.MDU-OVERHEAD)/Resource.MAPHASH_LEN)
     COLLISION_GUARD_SIZE = 2*Resource.WINDOW_MAX+HASHMAP_MAX_LEN
 
-    def __init__(self, resource=None):
+    assert HASHMAP_MAX_LEN > 0, "The configured MTU is too small to include any map hashes in resource advertisments"
+
+    @staticmethod
+    def is_request(advertisement_packet):
+        adv = ResourceAdvertisement.unpack(advertisement_packet.plaintext)
+        if adv.q != None and adv.u:
+            return True
+        else:
+            return False
+
+
+    @staticmethod
+    def is_response(advertisement_packet):
+        adv = ResourceAdvertisement.unpack(advertisement_packet.plaintext)
+
+        if adv.q != None and adv.p:
+            return True
+        else:
+            return False
+
+
+    @staticmethod
+    def get_request_id(advertisement_packet):
+        adv = ResourceAdvertisement.unpack(advertisement_packet.plaintext)
+        return adv.q
+
+
+    @staticmethod
+    def get_transfer_size(advertisement_packet):
+        adv = ResourceAdvertisement.unpack(advertisement_packet.plaintext)
+        return adv.t
+
+
+    @staticmethod
+    def get_size(advertisement_packet):
+        adv = ResourceAdvertisement.unpack(advertisement_packet.plaintext)
+        return adv.d
+
+
+    def __init__(self, resource=None, request_id=None, is_response=False):
         if resource != None:
-            self.t = resource.size                             # Transfer size
-            self.d = resource.total_size                       # Total uncompressed data size
-            self.n = len(resource.parts)                       # Number of parts
-            self.h = resource.hash                             # Resource hash
-            self.r = resource.random_hash                      # Resource random hash
-            self.o = resource.original_hash                    # First-segment hash
-            self.m = resource.hashmap                          # Resource hashmap
-            self.c = resource.compressed                       # Compression flag
-            self.e = resource.encrypted                        # Encryption flag
-            self.s = resource.split                            # Split flag
-            self.i = resource.segment_index                    # Segment index
-            self.l = resource.total_segments                   # Total segments
-            self.f = 0x00 | self.s << 2 | self.c << 1 | self.e # Flags
+            self.t = resource.size              # Transfer size
+            self.d = resource.total_size        # Total uncompressed data size
+            self.n = len(resource.parts)        # Number of parts
+            self.h = resource.hash              # Resource hash
+            self.r = resource.random_hash       # Resource random hash
+            self.o = resource.original_hash     # First-segment hash
+            self.m = resource.hashmap           # Resource hashmap
+            self.c = resource.compressed        # Compression flag
+            self.e = resource.encrypted         # Encryption flag
+            self.s = resource.split             # Split flag
+            self.i = resource.segment_index     # Segment index
+            self.l = resource.total_segments    # Total segments
+            self.q = resource.request_id        # ID of associated request
+            self.u = False                      # Is request flag
+            self.p = False                      # Is response flag
+
+            if self.q != None:
+                if not resource.is_response:
+                    self.u = True
+                    self.p = False
+                else:
+                    self.u = False
+                    self.p = True
+
+            # Flags
+            self.f = 0x00 | self.p << 4 | self.u << 3 | self.s << 2 | self.c << 1 | self.e
+
 
     def pack(self, segment=0):
         hashmap_start = segment*ResourceAdvertisement.HASHMAP_MAX_LEN
@@ -780,12 +914,14 @@ class ResourceAdvertisement:
             "o": self.o,    # Original hash
             "i": self.i,    # Segment index
             "l": self.l,    # Total segments
+            "q": self.q,    # Request ID
             "f": self.f,    # Resource flags
             "m": hashmap
         }
 
         return umsgpack.packb(dictionary)
 
+
     @staticmethod
     def unpack(data):
         dictionary = umsgpack.unpackb(data)
@@ -801,8 +937,11 @@ class ResourceAdvertisement:
         adv.f = dictionary["f"]
         adv.i = dictionary["i"]
         adv.l = dictionary["l"]
+        adv.q = dictionary["q"]
         adv.e = True if (adv.f & 0x01) == 0x01 else False
         adv.c = True if ((adv.f >> 1) & 0x01) == 0x01 else False
         adv.s = True if ((adv.f >> 2) & 0x01) == 0x01 else False
+        adv.u = True if ((adv.f >> 3) & 0x01) == 0x01 else False
+        adv.p = True if ((adv.f >> 4) & 0x01) == 0x01 else False
 
         return adv

RNS/Reticulum.py

@@ -1,7 +1,10 @@
 from .Interfaces import *
-import configparser
 from .vendor.configobj import ConfigObj
+import configparser
+import multiprocessing.connection
 import RNS
+import signal
+import threading
 import atexit
 import struct
 import array
@@ -10,13 +13,59 @@ import os
 import RNS
 
 class Reticulum:
+    """
+    This class is used to initialise access to Reticulum within a
+    program. You must create exactly one instance of this class before
+    carrying out any other RNS operations, such as creating destinations
+    or sending traffic. Every independently executed program must create
+    their own instance of the Reticulum class, but Reticulum will
+    automatically handle inter-program communication on the same system,
+    and expose all connected programs to external interfaces as well.
+
+    As soon as an instance of this class is created, Reticulum will start
+    opening and configuring any hardware devices specified in the supplied
+    configuration.
+
+    Currently the first running instance must be kept running while other
+    local instances are connected, as the first created instance will
+    act as a master instance that directly communicates with external
+    hardware such as modems, TNCs and radios. If a master instance is
+    asked to exit, it will not exit until all client processes have
+    terminated (unless killed forcibly).
+
+    If you are running Reticulum on a system with several different
+    programs that use RNS starting and terminating at different times,
+    it will be advantageous to run a master RNS instance as a daemon for
+    other programs to use on demand.
+    """
+
+    # Future minimum will probably be locked in at 244 bytes to support
+    # networks with segments of different MTUs. Absolute minimum is 211.
     MTU            = 500
-    HEADER_MAXSIZE = 23
+    """
+    The MTU that Reticulum adheres to, and will expect other peers to
+    adhere to. By default, the MTU is 500 bytes. In custom RNS network
+    implementations, it is possible to change this value, but doing so will
+    completely break compatibility with all other RNS networks. An identical
+    MTU is a prerequisite for peers to communicate in the same network.
+
+    Unless you really know what you are doing, the MTU should be left at
+    the default value.
+    """
+
+    # Length of truncated hashes in bits.
+    TRUNCATED_HASHLENGTH = 80
+
+    HEADER_MINSIZE = 2+1+(TRUNCATED_HASHLENGTH//8)*1
+    HEADER_MAXSIZE = 2+1+(TRUNCATED_HASHLENGTH//8)*2
+    
     MDU            = MTU - HEADER_MAXSIZE
 
     router         = None
     config         = None
     
+    # The default configuration path will be expanded to a directory
+    # named ".reticulum" inside the current users home directory
     configdir    = os.path.expanduser("~")+"/.reticulum"
     configpath   = ""
     storagepath  = ""
@@ -24,10 +73,29 @@ class Reticulum:
     
     @staticmethod
     def exit_handler():
-        RNS.Transport.exitHandler()
-        RNS.Identity.exitHandler()
+        # This exit handler is called whenever Reticulum is asked to
+        # shut down, and will in turn call exit handlers in other
+        # classes, saving necessary information to disk and carrying
+        # out cleanup operations.
+
+        RNS.Transport.exit_handler()
+        RNS.Identity.exit_handler()
+
+    @staticmethod
+    def sigint_handler(signal, frame):
+        RNS.Transport.detach_interfaces()
+        RNS.exit()
+
+
+    def __init__(self,configdir=None, loglevel=None):
+        """
+        Initialises and starts a Reticulum instance. This must be
+        done before any other operations, and Reticulum will not
+        pass any traffic before being instantiated.
+
+        :param configdir: Full path to a Reticulum configuration directory.
+        """
 
-    def __init__(self,configdir=None):
         if configdir != None:
             Reticulum.configdir = configdir
         
@@ -36,12 +104,24 @@ class Reticulum:
         Reticulum.cachepath     = Reticulum.configdir+"/storage/cache"
         Reticulum.resourcepath  = Reticulum.configdir+"/storage/resources"
 
-        Reticulum.__allow_unencrypted = False
         Reticulum.__transport_enabled = False
         Reticulum.__use_implicit_proof = True
 
+        Reticulum.panic_on_interface_error = False
+
         self.local_interface_port = 37428
-        self.share_instance = True
+        self.local_control_port   = 37429
+        self.share_instance       = True
+        self.rpc_listener         = None
+
+        self.requested_loglevel = loglevel
+        if self.requested_loglevel != None:
+            if self.requested_loglevel > RNS.LOG_EXTREME:
+                self.requested_loglevel = RNS.LOG_EXTREME
+            if self.requested_loglevel < RNS.LOG_CRITICAL:
+                self.requested_loglevel = RNS.LOG_CRITICAL
+
+            RNS.loglevel = self.requested_loglevel
 
         self.is_shared_instance = False
         self.is_connected_to_shared_instance = False
@@ -59,26 +139,37 @@ class Reticulum:
         if os.path.isfile(self.configpath):
             try:
                 self.config = ConfigObj(self.configpath)
-                RNS.log("Configuration loaded from "+self.configpath)
             except Exception as e:
                 RNS.log("Could not parse the configuration at "+self.configpath, RNS.LOG_ERROR)
                 RNS.log("Check your configuration file for errors!", RNS.LOG_ERROR)
                 RNS.panic()
         else:
             RNS.log("Could not load config file, creating default configuration file...")
-            self.createDefaultConfig()
+            self.__create_default_config()
             RNS.log("Default config file created. Make any necessary changes in "+Reticulum.configdir+"/config and start Reticulum again.")
             RNS.log("Exiting now!")
             exit(1)
 
-        self.applyConfig()
-        RNS.Identity.loadKnownDestinations()
+        self.__apply_config()
+        RNS.log("Configuration loaded from "+self.configpath, RNS.LOG_VERBOSE)
+        
+        RNS.Identity.load_known_destinations()
 
         RNS.Transport.start(self)
 
-        atexit.register(Reticulum.exit_handler)
+        self.rpc_addr = ("127.0.0.1", self.local_control_port)
+        self.rpc_key  = RNS.Identity.full_hash(RNS.Transport.identity.get_private_key())
+        
+        if self.is_shared_instance:
+            self.rpc_listener = multiprocessing.connection.Listener(self.rpc_addr, authkey=self.rpc_key)
+            thread = threading.Thread(target=self.rpc_loop)
+            thread.setDaemon(True)
+            thread.start()
 
-    def start_local_interface(self):
+        atexit.register(Reticulum.exit_handler)
+        signal.signal(signal.SIGINT, Reticulum.sigint_handler)
+
+    def __start_local_interface(self):
         if self.share_instance:
             try:
                 interface = LocalInterface.LocalServerInterface(
@@ -87,6 +178,7 @@ class Reticulum:
                 )
                 interface.OUT = True
                 RNS.Transport.interfaces.append(interface)
+                
                 self.is_shared_instance = True
                 RNS.log("Started shared instance interface: "+str(interface), RNS.LOG_DEBUG)
             except Exception as e:
@@ -101,6 +193,7 @@ class Reticulum:
                     self.is_shared_instance = False
                     self.is_standalone_instance = False
                     self.is_connected_to_shared_instance = True
+                    Reticulum.__transport_enabled = False
                     RNS.log("Connected to local shared instance via: "+str(interface), RNS.LOG_DEBUG)
                 except Exception as e:
                     RNS.log("Local shared instance appears to be running, but it could not be connected", RNS.LOG_ERROR)
@@ -113,11 +206,11 @@ class Reticulum:
             self.is_standalone_instance = True
             self.is_connected_to_shared_instance = False
 
-    def applyConfig(self):
+    def __apply_config(self):
         if "logging" in self.config:
             for option in self.config["logging"]:
                 value = self.config["logging"][option]
-                if option == "loglevel":
+                if option == "loglevel" and self.requested_loglevel == None:
                     RNS.loglevel = int(value)
                     if RNS.loglevel < 0:
                         RNS.loglevel = 0
@@ -133,32 +226,25 @@ class Reticulum:
                 if option == "shared_instance_port":
                     value = int(self.config["reticulum"][option])
                     self.local_interface_port = value
+                if option == "instance_control_port":
+                    value = int(self.config["reticulum"][option])
+                    self.local_control_port = value
                 if option == "enable_transport":
                     v = self.config["reticulum"].as_bool(option)
                     if v == True:
                         Reticulum.__transport_enabled = True
+                if option == "panic_on_interface_error":
+                    v = self.config["reticulum"].as_bool(option)
+                    if v == True:
+                        Reticulum.panic_on_interface_error = True
                 if option == "use_implicit_proof":
                     v = self.config["reticulum"].as_bool(option)
                     if v == True:
                         Reticulum.__use_implicit_proof = True
                     if v == False:
                         Reticulum.__use_implicit_proof = False
-                if option == "allow_unencrypted":
-                    v = self.config["reticulum"].as_bool(option)
-                    if v == True:
-                        RNS.log("", RNS.LOG_CRITICAL)
-                        RNS.log("! ! !     ! ! !     ! ! !", RNS.LOG_CRITICAL)
-                        RNS.log("", RNS.LOG_CRITICAL)
-                        RNS.log("Danger! Encryptionless links have been allowed in the config file!", RNS.LOG_CRITICAL)
-                        RNS.log("Beware of the consequences! Any data sent over a link can potentially be intercepted,", RNS.LOG_CRITICAL)
-                        RNS.log("read and modified! If you are not absolutely sure that you want this,", RNS.LOG_CRITICAL)
-                        RNS.log("you should exit Reticulum NOW and change your config file!", RNS.LOG_CRITICAL)
-                        RNS.log("", RNS.LOG_CRITICAL)
-                        RNS.log("! ! !     ! ! !     ! ! !", RNS.LOG_CRITICAL)
-                        RNS.log("", RNS.LOG_CRITICAL)
-                        Reticulum.__allow_unencrypted = True
 
-        self.start_local_interface()
+        self.__start_local_interface()
 
         if self.is_shared_instance or self.is_standalone_instance:
             interface_names = []
@@ -169,13 +255,27 @@ class Reticulum:
                     try:
                         if ("interface_enabled" in c) and c.as_bool("interface_enabled") == True:
                             if c["type"] == "UDPInterface":
+                                device       = c["device"] if "device" in c else None
+                                port         = int(c["port"]) if "port" in c else None
+                                listen_ip    = c["listen_ip"] if "listen_ip" in c else None
+                                listen_port  = int(c["listen_port"]) if "listen_port" in c else None
+                                forward_ip   = c["forward_ip"] if "forward_ip" in c else None
+                                forward_port = int(c["forward_port"]) if "forward_port" in c else None
+
+                                if port != None:
+                                    if listen_port == None:
+                                        listen_port = port
+                                    if forward_port == None:
+                                        forward_port = port
+
                                 interface = UDPInterface.UDPInterface(
                                     RNS.Transport,
                                     name,
-                                    c["listen_ip"],
-                                    int(c["listen_port"]),
-                                    c["forward_ip"],
-                                    int(c["forward_port"])
+                                    device,
+                                    listen_ip,
+                                    listen_port,
+                                    forward_ip,
+                                    forward_port
                                 )
 
                                 if "outgoing" in c and c.as_bool("outgoing") == True:
@@ -187,11 +287,20 @@ class Reticulum:
 
 
                             if c["type"] == "TCPServerInterface":
+                                device       = c["device"] if "device" in c else None
+                                port         = int(c["port"]) if "port" in c else None
+                                listen_ip    = c["listen_ip"] if "listen_ip" in c else None
+                                listen_port  = int(c["listen_port"]) if "listen_port" in c else None
+
+                                if port != None:
+                                    listen_port = port
+
                                 interface = TCPInterface.TCPServerInterface(
                                     RNS.Transport,
                                     name,
-                                    c["listen_ip"],
-                                    int(c["listen_port"])
+                                    device,
+                                    listen_ip,
+                                    listen_port
                                 )
 
                                 if "outgoing" in c and c.as_bool("outgoing") == True:
@@ -238,7 +347,7 @@ class Reticulum:
                                     stopbits
                                 )
 
-                                if "outgoing" in c and c["outgoing"].lower() == "true":
+                                if "outgoing" in c and c.as_bool("outgoing") == True:
                                     interface.OUT = True
                                 else:
                                     interface.OUT = False
@@ -279,7 +388,7 @@ class Reticulum:
                                     beacon_data
                                 )
 
-                                if "outgoing" in c and c["outgoing"].lower() == "true":
+                                if "outgoing" in c and c.as_bool("outgoing") == True:
                                     interface.OUT = True
                                 else:
                                     interface.OUT = False
@@ -321,7 +430,7 @@ class Reticulum:
                                     flow_control
                                 )
 
-                                if "outgoing" in c and c["outgoing"].lower() == "true":
+                                if "outgoing" in c and c.as_bool("outgoing") == True:
                                     interface.OUT = True
                                 else:
                                     interface.OUT = False
@@ -357,14 +466,14 @@ class Reticulum:
                                     id_callsign = id_callsign
                                 )
 
-                                if "outgoing" in c and c["outgoing"].lower() == "true":
+                                if "outgoing" in c and c.as_bool("outgoing") == True:
                                     interface.OUT = True
                                 else:
                                     interface.OUT = False
 
                                 RNS.Transport.interfaces.append(interface)
                         else:
-                            RNS.log("Skipping disabled interface \""+name+"\"", RNS.LOG_NOTICE)
+                            RNS.log("Skipping disabled interface \""+name+"\"", RNS.LOG_INFO)
 
                     except Exception as e:
                         RNS.log("The interface \""+name+"\" could not be created. Check your configuration file for errors!", RNS.LOG_ERROR)
@@ -375,25 +484,137 @@ class Reticulum:
                     RNS.panic()
                 
 
-    def createDefaultConfig(self):
+    def __create_default_config(self):
         self.config = ConfigObj(__default_rns_config__)
         self.config.filename = Reticulum.configpath
         
         if not os.path.isdir(Reticulum.configdir):
             os.makedirs(Reticulum.configdir)
         self.config.write()
-        self.applyConfig()
+        self.__apply_config()
+
+    def rpc_loop(self):
+        while True:
+            try:
+                rpc_connection = self.rpc_listener.accept()
+                call = rpc_connection.recv()
+
+                if "get" in call:
+                    path = call["get"]
+
+                    if path == "interface_stats":
+                        rpc_connection.send(self.get_interface_stats())
+
+                    if path == "next_hop_if_name":
+                        rpc_connection.send(self.get_next_hop_if_name(call["destination_hash"]))
+
+                    if path == "next_hop":
+                        rpc_connection.send(self.get_next_hop(call["destination_hash"]))
+
+                    if path == "packet_rssi":
+                        rpc_connection.send(self.get_packet_rssi(call["packet_hash"]))
+
+                    if path == "packet_snr":
+                        rpc_connection.send(self.get_packet_snr(call["packet_hash"]))
+
+                rpc_connection.close()
+            except Exception as e:
+                RNS.log("An error ocurred while handling RPC call from local client: "+str(e), RNS.LOG_ERROR)
+
+    def get_interface_stats(self):
+        if self.is_connected_to_shared_instance:
+            rpc_connection = multiprocessing.connection.Client(self.rpc_addr, authkey=self.rpc_key)
+            rpc_connection.send({"get": "interface_stats"})
+            response = rpc_connection.recv()
+            return response
+        else:
+            stats = []
+            for interface in RNS.Transport.interfaces:
+                ifstats = {}
+                
+                if hasattr(interface, "clients"):
+                    ifstats["clients"] = interface.clients
+                else:
+                    ifstats["clients"] = None
+
+                ifstats["name"] = str(interface)
+                ifstats["rxb"] = interface.rxb
+                ifstats["txb"] = interface.txb
+                ifstats["status"] = interface.online
+                stats.append(ifstats)
+
+            return stats
+
+    def get_next_hop_if_name(self, destination):
+        if self.is_connected_to_shared_instance:
+            rpc_connection = multiprocessing.connection.Client(self.rpc_addr, authkey=self.rpc_key)
+            rpc_connection.send({"get": "next_hop_if_name", "destination_hash": destination})
+            response = rpc_connection.recv()
+            return response
+
+        else:
+            return str(RNS.Transport.next_hop_interface(destination))
+
+    def get_next_hop(self, destination):
+        if self.is_connected_to_shared_instance:
+            rpc_connection = multiprocessing.connection.Client(self.rpc_addr, authkey=self.rpc_key)
+            rpc_connection.send({"get": "next_hop", "destination_hash": destination})
+            response = rpc_connection.recv()
+            return response
+
+        else:
+            return RNS.Transport.next_hop(destination)
+
+    def get_packet_rssi(self, packet_hash):
+        if self.is_connected_to_shared_instance:
+            rpc_connection = multiprocessing.connection.Client(self.rpc_addr, authkey=self.rpc_key)
+            rpc_connection.send({"get": "packet_rssi", "packet_hash": packet_hash})
+            response = rpc_connection.recv()
+            return response
+
+        else:
+            for entry in RNS.Transport.local_client_rssi_cache:
+                if entry[0] == packet_hash:
+                    return entry[1]
+
+            return None
+
+    def get_packet_snr(self, packet_hash):
+        if self.is_connected_to_shared_instance:
+            rpc_connection = multiprocessing.connection.Client(self.rpc_addr, authkey=self.rpc_key)
+            rpc_connection.send({"get": "packet_snr", "packet_hash": packet_hash})
+            response = rpc_connection.recv()
+            return response
+
+        else:
+            for entry in RNS.Transport.local_client_snr_cache:
+                if entry[0] == packet_hash:
+                    return entry[1]
+
+            return None
 
-    @staticmethod
-    def should_allow_unencrypted():
-        return Reticulum.__allow_unencrypted
 
     @staticmethod
     def should_use_implicit_proof():
+        """
+        Returns whether proofs sent are explicit or implicit.
+
+        :returns: True if the current running configuration specifies to use implicit proofs. False if not.
+        """
         return Reticulum.__use_implicit_proof
 
     @staticmethod
     def transport_enabled():
+        """
+        Returns whether Transport is enabled for the running
+        instance.
+
+        When Transport is enabled, Reticulum will
+        route traffic for other peers, respond to path requests
+        and pass announces over the network.
+
+        :returns: True if Transport is enabled, False if not.
+        """
         return Reticulum.__transport_enabled
 
 # Default configuration file:
@@ -403,20 +624,12 @@ __default_rns_config__ = '''# This is the default Reticulum config file.
 
 [reticulum]
 
-# Don't allow unencrypted links by default.
-# If you REALLY need to allow unencrypted links, for example
-# for debug or regulatory purposes, this can be set to true.
-# This directive is optional and can be removed for brevity.
-
-allow_unencrypted = False
-
-
 # If you enable Transport, your system will route traffic
 # for other peers, pass announces and serve path requests.
-# Unless you really know what you're doing, this should be
-# done only for systems that are suited to act as transport
-# nodes, ie. if they are stationary and always-on. This
-# directive is optional and can be removed for brevity.
+# This should be done for systems that are suited to act
+# as transport nodes, ie. if they are stationary and
+# always-on. This directive is optional and can be removed
+# for brevity.
 
 enable_transport = False
 
@@ -434,11 +647,21 @@ share_instance = Yes
 
 
 # If you want to run multiple *different* shared instances
-# on the same system, you will need to specify a different
-# shared instance port for each. The default is given below,
-# and again, this option is optional and can be left out.
+# on the same system, you will need to specify different
+# shared instance ports for each. The defaults are given
+# below, and again, these options can be left out if you
+# don't need them.
 
 shared_instance_port = 37428
+instance_control_port = 37429
+
+# You can configure Reticulum to panic and forcibly close
+# if an unrecoverable interface error occurs, such as the
+# hardware device for an interface disappearing. This is
+# an optional directive, and can be left out for brevity.
+# This behaviour is disabled by default.
+
+panic_on_interface_error = No
 
 
 [logging]
@@ -464,11 +687,11 @@ loglevel = 4
 [interfaces]
 
   # This interface enables communication with other
-  # Reticulum nodes on your local ethernet networks.
-  # It's enabled by default, and provides basic
-  # connectivity to other peers in your local ethernet
-  # broadcast domain. You can modify it to suit your
-  # needs or turn it off completely.
+  # local Reticulum nodes over UDP. You can modify it
+  # to suit your needs or turn it off completely.
+  # As a minimum, you should probably specify the
+  # network device you want to communicate on, such
+  # as eth0 or wlan0.
   
   [[Default UDP Interface]]
     type = UDPInterface
@@ -479,6 +702,38 @@ loglevel = 4
     forward_ip = 255.255.255.255
     forward_port = 4242
 
+    # The above configuration will allow communication
+    # within the local broadcast domains of all local
+    # IP interfaces. This is enabled by default as an
+    # easy way to get started, but you might want to
+    # consider altering it to something more specific.
+
+    # Instead of specifying listen_ip, listen_port,
+    # forward_ip and forward_port, you can also bind
+    # to a specific network device like below.
+
+    # device = eth0
+    # port = 4242
+
+    # Assuming the eth0 device has the address
+    # 10.55.0.72/24, the above configuration would
+    # be equivalent to the following manual setup.
+    # Note that we are both listening and forwarding to
+    # the broadcast address of the network segments.
+
+    # listen_ip = 10.55.0.255
+    # listen_port = 4242
+    # forward_ip = 10.55.0.255
+    # forward_port = 4242
+
+    # You can of course also communicate only with
+    # a single IP address
+
+    # listen_ip = 10.55.0.15
+    # listen_port = 4242
+    # forward_ip = 10.55.0.16
+    # forward_port = 4242
+
 
   # This example demonstrates a TCP server interface.
   # It will listen for incoming connections on the
@@ -488,9 +743,23 @@ loglevel = 4
     type = TCPServerInterface
     interface_enabled = False
     outgoing = True
+
+    # This configuration will listen on all IP
+    # interfaces on port 4242
+    
     listen_ip = 0.0.0.0
     listen_port = 4242
 
+    # Alternatively you can bind to a specific IP
+    
+    # listen_ip = 10.0.0.88
+    # listen_port = 4242
+
+    # Or a specific network device
+    
+    # device = eth0
+    # port = 4242
+
 
   # To connect to a TCP server interface, you would
   # naturally use the TCP client interface. Here's

RNS/Transport.py

@@ -9,6 +9,10 @@ from time import sleep
 from .vendor import umsgpack as umsgpack
 
 class Transport:
+    """
+    Through static methods of this class you can interact with the
+    Transport system of Reticulum.
+    """
     # Constants
     BROADCAST    = 0x00;
     TRANSPORT    = 0x01;
@@ -22,40 +26,45 @@ class Transport:
 
     APP_NAME = "rnstransport"
 
-    # TODO: Document the addition of random windows
-    # and max local rebroadcasts.
-    PATHFINDER_M    = 18        # Max hops
-    PATHFINDER_C    = 2.0       # Decay constant
-    PATHFINDER_R    = 1         # Retransmit retries
-    PATHFINDER_T    = 10        # Retry grace period
-    PATHFINDER_RW   = 10        # Random window for announce rebroadcast
-    PATHFINDER_E    = 60*15     # Path expiration in seconds
+    PATHFINDER_M    = 128       # Max hops
+    """
+    Maximum amount of hops that Reticulum will transport a packet.
+    """
+    PATHFINDER_C    = 2.0        # Decay constant
+    PATHFINDER_R    = 1          # Retransmit retries
+    PATHFINDER_T    = 10         # Retry grace period
+    PATHFINDER_RW   = 10         # Random window for announce rebroadcast
+    PATHFINDER_E    = 60*60*24*7 # Path expiration in seconds
 
     # TODO: Calculate an optimal number for this in
     # various situations
-    LOCAL_REBROADCASTS_MAX = 2        # How many local rebroadcasts of an announce is allowed
+    LOCAL_REBROADCASTS_MAX = 2          # How many local rebroadcasts of an announce is allowed
 
-    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_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
 
     LINK_TIMEOUT         = RNS.Link.KEEPALIVE * 2
-    REVERSE_TIMEOUT      = 30*60      # Reverse table entries are removed after max 30 minutes
-    DESTINATION_TIMEOUT  = 60*60*24*7 # Destination table entries are removed if unused for one week
-    MAX_RECEIPTS         = 1024       # Maximum number of receipts to keep track of
+    REVERSE_TIMEOUT      = 30*60        # Reverse table entries are removed after max 30 minutes
+    DESTINATION_TIMEOUT  = PATHFINDER_E # Destination table entries are removed if unused for one week
+    MAX_RECEIPTS         = 1024         # Maximum number of receipts to keep track of
 
-    interfaces           = []         # All active interfaces
-    destinations         = []         # All active destinations
-    pending_links        = []         # Links that are being established
-    active_links         = []         # Links that are active
-    packet_hashlist      = []         # A list of packet hashes for duplicate detection
-    receipts             = []         # Receipts of all outgoing packets for proof processing
+    interfaces           = []           # All active interfaces
+    destinations         = []           # All active destinations
+    pending_links        = []           # Links that are being established
+    active_links         = []           # Links that are active
+    packet_hashlist      = []           # A list of packet hashes for duplicate detection
+    receipts             = []           # Receipts of all outgoing packets for proof processing
 
     # TODO: "destination_table" should really be renamed to "path_table"
-    announce_table       = {}         # A table for storing announces currently waiting to be retransmitted
-    destination_table    = {}         # A lookup table containing the next hop to a given destination
-    reverse_table        = {}         # A lookup table for storing packet hashes used to return proofs and replies
-    link_table           = {}         # A lookup table containing hops for links
-    held_announces       = {}         # A table containing temporarily held announce-table entries
+    # Notes on memory usage: 1 megabyte of memory can store approximately
+    # 55.100 path table entries or approximately 22.300 link table entries.
+    announce_table       = {}           # A table for storing announces currently waiting to be retransmitted
+    destination_table    = {}           # A lookup table containing the next hop to a given destination
+    reverse_table        = {}           # A lookup table for storing packet hashes used to return proofs and replies
+    link_table           = {}           # A lookup table containing hops for links
+    held_announces       = {}           # A table containing temporarily held announce-table entries
+    announce_handlers    = []           # A table storing externally registered announce handlers
+    tunnels              = {}           # A table storing tunnels to other transport instances
 
     # Transport control destinations are used
     # for control purposes like path requests
@@ -67,6 +76,10 @@ class Transport:
     # Reticulum instance
     local_client_interfaces = []
 
+    local_client_rssi_cache    = []
+    local_client_snr_cache     = []
+    LOCAL_CLIENT_CACHE_MAXSIZE = 512
+
     jobs_locked = False
     jobs_running = False
     job_interval = 0.250
@@ -92,7 +105,7 @@ class Transport:
             if Transport.identity == None:
                 RNS.log("No valid Transport Identity in storage, creating...", RNS.LOG_VERBOSE)
                 Transport.identity = RNS.Identity()
-                Transport.identity.save(transport_identity_path)
+                Transport.identity.to_file(transport_identity_path)
             else:
                 RNS.log("Loaded Transport Identity from storage", RNS.LOG_VERBOSE)
 
@@ -107,16 +120,23 @@ class Transport:
 
         # Create transport-specific destinations
         Transport.path_request_destination = RNS.Destination(None, RNS.Destination.IN, RNS.Destination.PLAIN, Transport.APP_NAME, "path", "request")
-        Transport.path_request_destination.packet_callback(Transport.path_request_handler)
+        Transport.path_request_destination.set_packet_callback(Transport.path_request_handler)
         Transport.control_destinations.append(Transport.path_request_destination)
         Transport.control_hashes.append(Transport.path_request_destination.hash)
 
+        Transport.tunnel_synthesize_destination = RNS.Destination(None, RNS.Destination.IN, RNS.Destination.PLAIN, Transport.APP_NAME, "tunnel", "synthesize")
+        Transport.tunnel_synthesize_destination.set_packet_callback(Transport.tunnel_synthesize_handler)
+        Transport.control_destinations.append(Transport.tunnel_synthesize_handler)
+        Transport.control_hashes.append(Transport.tunnel_synthesize_destination.hash)
+
         thread = threading.Thread(target=Transport.jobloop)
         thread.setDaemon(True)
         thread.start()
 
         if RNS.Reticulum.transport_enabled():
             destination_table_path = RNS.Reticulum.storagepath+"/destination_table"
+            tunnel_table_path = RNS.Reticulum.storagepath+"/tunnels"
+
             if os.path.isfile(destination_table_path) and not Transport.owner.is_connected_to_shared_instance:
                 serialised_destinations = []
                 try:
@@ -160,7 +180,63 @@ class Transport:
                 except Exception as e:
                     RNS.log("Could not load destination table from storage, the contained exception was: "+str(e), RNS.LOG_ERROR)
 
-            RNS.log("Transport instance "+str(Transport.identity)+" started")
+            if os.path.isfile(tunnel_table_path) and not Transport.owner.is_connected_to_shared_instance:
+                serialised_tunnels = []
+                try:
+                    file = open(tunnel_table_path, "rb")
+                    serialised_tunnels = umsgpack.unpackb(file.read())
+                    file.close()
+
+                    for serialised_tunnel in serialised_tunnels:
+                        tunnel_id = serialised_tunnel[0]
+                        interface_hash = serialised_tunnel[1]
+                        serialised_paths = serialised_tunnel[2]
+                        expires = serialised_tunnel[3]
+
+                        tunnel_paths = {}
+                        for serialised_entry in serialised_paths:
+                            destination_hash = serialised_entry[0]
+                            timestamp = serialised_entry[1]
+                            received_from = serialised_entry[2]
+                            hops = serialised_entry[3]
+                            expires = serialised_entry[4]
+                            random_blobs = serialised_entry[5]
+                            receiving_interface = Transport.find_interface_from_hash(serialised_entry[6])
+                            announce_packet = Transport.get_cached_packet(serialised_entry[7])
+
+                            if announce_packet != None:
+                                announce_packet.unpack()
+                                # We increase the hops, since reading a packet
+                                # from cache is equivalent to receiving it again
+                                # over an interface. It is cached with it's non-
+                                # increased hop-count.
+                                announce_packet.hops += 1
+
+                                tunnel_path = [timestamp, received_from, hops, expires, random_blobs, receiving_interface, announce_packet]
+                                tunnel_paths[destination_hash] = tunnel_path
+
+                        tunnel = [tunnel_id, None, tunnel_paths, expires]
+                        Transport.tunnels[tunnel_id] = tunnel
+
+                    if len(Transport.destination_table) == 1:
+                        specifier = "entry"
+                    else:
+                        specifier = "entries"
+
+                    RNS.log("Loaded "+str(len(Transport.tunnels))+" tunnel table "+specifier+" from storage", RNS.LOG_VERBOSE)
+
+                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
+        for interface in Transport.interfaces:
+            interface.tunnel_id = None
+            if hasattr(interface, "wants_tunnel") and interface.wants_tunnel:
+                Transport.synthesize_tunnel(interface)
 
     @staticmethod
     def jobloop():
@@ -179,7 +255,7 @@ class Transport:
                     while len(Transport.receipts) > Transport.MAX_RECEIPTS:
                         culled_receipt = Transport.receipts.pop(0)
                         culled_receipt.timeout = -1
-                        receipt.check_timeout()
+                        culled_receipt.check_timeout()
 
                     for receipt in Transport.receipts:
                         receipt.check_timeout()
@@ -245,15 +321,16 @@ class Transport:
 
 
                 # Cull the packet hashlist if it has reached max size
-                while (len(Transport.packet_hashlist) > Transport.hashlist_maxsize):
-                    Transport.packet_hashlist.pop(0)
+                if len(Transport.packet_hashlist) > Transport.hashlist_maxsize:
+                    Transport.packet_hashlist = Transport.packet_hashlist[len(Transport.packet_hashlist)-Transport.hashlist_maxsize:len(Transport.packet_hashlist)-1]
 
                 if time.time() > Transport.tables_last_culled + Transport.tables_cull_interval:
                     # Cull the reverse table according to timeout
+                    stale_reverse_entries = []
                     for truncated_packet_hash in Transport.reverse_table:
                         reverse_entry = Transport.reverse_table[truncated_packet_hash]
                         if time.time() > reverse_entry[2] + Transport.REVERSE_TIMEOUT:
-                            Transport.reverse_table.pop(truncated_packet_hash)
+                            stale_reverse_entries.append(truncated_packet_hash)
 
                     # Cull the link table according to timeout
                     stale_links = []
@@ -271,11 +348,56 @@ class Transport:
                         if time.time() > destination_entry[0] + Transport.DESTINATION_TIMEOUT:
                             stale_paths.append(destination_hash)
                             RNS.log("Path to "+RNS.prettyhexrep(destination_hash)+" timed out and was removed", RNS.LOG_DEBUG)
-
-                        if not attached_interface in Transport.interfaces:
+                        elif not attached_interface in Transport.interfaces:
                             stale_paths.append(destination_hash)
                             RNS.log("Path to "+RNS.prettyhexrep(destination_hash)+" was removed since the attached interface no longer exists", RNS.LOG_DEBUG)
 
+                    # Cull the tunnel table
+                    stale_tunnels = []
+                    ti = 0
+                    for tunnel_id in Transport.tunnels:
+                        tunnel_entry = Transport.tunnels[tunnel_id]
+
+                        expires = tunnel_entry[3]
+                        if time.time() > expires:
+                            stale_tunnels.append(tunnel_id)
+                            RNS.log("Tunnel "+RNS.prettyhexrep(tunnel_id)+" timed out and was removed", RNS.LOG_DEBUG)
+                        else:
+                            stale_tunnel_paths = []
+                            tunnel_paths = tunnel_entry[2]
+                            for tunnel_path in tunnel_paths:
+                                tunnel_path_entry = tunnel_paths[tunnel_path]
+
+                                if time.time() > tunnel_path_entry[0] + Transport.DESTINATION_TIMEOUT:
+                                    stale_tunnel_paths.append(tunnel_path)
+                                    RNS.log("Tunnel path to "+RNS.prettyhexrep(tunnel_path)+" timed out and was removed", RNS.LOG_DEBUG)
+
+                            for tunnel_path in stale_tunnel_paths:
+                                tunnel_paths.pop(tunnel_path)
+                                ti += 1
+
+
+                    if ti > 0:
+                        if ti == 1:
+                            RNS.log("Removed "+str(ti)+" tunnel path", RNS.LOG_DEBUG)
+                        else:
+                            RNS.log("Removed "+str(ti)+" tunnel paths", RNS.LOG_DEBUG)
+
+
+                    
+                    i = 0
+                    for truncated_packet_hash in stale_reverse_entries:
+                        Transport.reverse_table.pop(truncated_packet_hash)
+                        i += 1
+
+                    if i > 0:
+                        if i == 1:
+                            RNS.log("Dropped "+str(i)+" reverse table entry", RNS.LOG_DEBUG)
+                        else:
+                            RNS.log("Dropped "+str(i)+" reverse table entries", RNS.LOG_DEBUG)
+
+                    
+
                     i = 0
                     for link_id in stale_links:
                         Transport.link_table.pop(link_id)
@@ -298,6 +420,17 @@ class Transport:
                         else:
                             RNS.log("Removed "+str(i)+" paths", RNS.LOG_DEBUG)
 
+                    i = 0
+                    for tunnel_id in stale_tunnels:
+                        Transport.tunnels.pop(tunnel_id)
+                        i += 1
+
+                    if i > 0:
+                        if i == 1:
+                            RNS.log("Removed "+str(i)+" tunnel", RNS.LOG_DEBUG)
+                        else:
+                            RNS.log("Removed "+str(i)+" tunnels", RNS.LOG_DEBUG)
+
                     Transport.tables_last_culled = time.time()
 
         except Exception as e:
@@ -317,7 +450,7 @@ class Transport:
 
         Transport.jobs_locked = True
         # TODO: This updateHash call might be redundant
-        packet.updateHash()
+        packet.update_hash()
         sent = False
 
         # Check if we have a known path for the destination in the path table
@@ -337,8 +470,6 @@ class Transport:
                     new_raw += packet.raw[1:2]
                     new_raw += Transport.destination_table[packet.destination_hash][1]
                     new_raw += packet.raw[2:]
-                    # TODO: Remove at some point
-                    # RNS.log("Packet was inserted into transport via "+RNS.prettyhexrep(Transport.destination_table[packet.destination_hash][1])+" on: "+str(outbound_interface), RNS.LOG_EXTREME)
                     outbound_interface.processOutgoing(new_raw)
                     Transport.destination_table[packet.destination_hash][0] = time.time()
                     sent = True
@@ -358,8 +489,6 @@ class Transport:
                     new_raw += packet.raw[1:2]
                     new_raw += Transport.destination_table[packet.destination_hash][1]
                     new_raw += packet.raw[2:]
-                    # TODO: Remove at some point
-                    # RNS.log("Packet was inserted into transport via "+RNS.prettyhexrep(Transport.destination_table[packet.destination_hash][1])+" on: "+str(outbound_interface), RNS.LOG_EXTREME)
                     outbound_interface.processOutgoing(new_raw)
                     Transport.destination_table[packet.destination_hash][0] = time.time()
                     sent = True
@@ -376,6 +505,7 @@ class Transport:
         # just the relevant interface if the packet has an attached
         # interface, or belongs to a link.
         else:
+            stored_hash = False
             for interface in Transport.interfaces:
                 if interface.OUT:
                     should_transmit = True
@@ -388,8 +518,10 @@ class Transport:
                         should_transmit = False
                             
                     if should_transmit:
-                        RNS.log("Transmitting "+str(len(packet.raw))+" bytes on: "+str(interface), RNS.LOG_EXTREME)
-                        RNS.log("Hash is "+RNS.prettyhexrep(packet.packet_hash), RNS.LOG_EXTREME)
+                        if not stored_hash:
+                            Transport.packet_hashlist.append(packet.packet_hash)
+                            stored_hash = True
+
                         interface.processOutgoing(packet.raw)
                         sent = True
 
@@ -397,7 +529,7 @@ class Transport:
             packet.sent = True
             packet.sent_at = time.time()
 
-                # Don't generate receipt if it has been explicitly disabled
+            # Don't generate receipt if it has been explicitly disabled
             if (packet.create_receipt == True and
                 # Only generate receipts for DATA packets
                 packet.packet_type == RNS.Packet.DATA and
@@ -446,7 +578,7 @@ class Transport:
     @staticmethod
     def inbound(raw, interface=None):
         while (Transport.jobs_running):
-            sleep(0.1)
+            sleep(0.01)
             
         Transport.jobs_locked = True
         
@@ -455,12 +587,29 @@ class Transport:
         packet.receiving_interface = interface
         packet.hops += 1
 
-        RNS.log(str(interface)+" received packet with hash "+RNS.prettyhexrep(packet.packet_hash), RNS.LOG_EXTREME)
+        if interface != None:
+            if hasattr(interface, "r_stat_rssi"):
+                if interface.r_stat_rssi != None:
+                    packet.rssi = interface.r_stat_rssi
+                    if len(Transport.local_client_interfaces) > 0:
+                        Transport.local_client_rssi_cache.append([packet.packet_hash, packet.rssi])
+
+                        while len(Transport.local_client_rssi_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
+                            Transport.local_client_rssi_cache.pop()
+
+            if hasattr(interface, "r_stat_snr"):
+                if interface.r_stat_rssi != None:
+                    packet.snr = interface.r_stat_snr
+                    if len(Transport.local_client_interfaces) > 0:
+                        Transport.local_client_snr_cache.append([packet.packet_hash, packet.snr])
+
+                        while len(Transport.local_client_snr_cache) > Transport.LOCAL_CLIENT_CACHE_MAXSIZE:
+                            Transport.local_client_snr_cache.pop()
 
         if len(Transport.local_client_interfaces) > 0:
-
             if Transport.is_local_client_interface(interface):
                 packet.hops -= 1
+
         elif Transport.interface_to_shared_instance(interface):
             packet.hops -= 1
 
@@ -521,11 +670,10 @@ class Transport:
                 # accordingly if we are.
                 if packet.transport_id != None and packet.packet_type != RNS.Packet.ANNOUNCE:
                     if packet.transport_id == Transport.identity.hash:
-                        RNS.log("Received packet in transport for "+RNS.prettyhexrep(packet.destination_hash)+" with matching transport ID, transporting it...", RNS.LOG_DEBUG)
                         if packet.destination_hash in Transport.destination_table:
                             next_hop = Transport.destination_table[packet.destination_hash][1]
                             remaining_hops = Transport.destination_table[packet.destination_hash][2]
-                            RNS.log("Next hop to destination is "+RNS.prettyhexrep(next_hop)+" with "+str(remaining_hops)+" hops remaining, transporting it.", RNS.LOG_DEBUG)
+                            
                             if remaining_hops > 1:
                                 # Just increase hop count and transmit
                                 new_raw  = packet.raw[0:1]
@@ -573,7 +721,7 @@ class Transport:
                             # TODO: There should probably be some kind of REJECT
                             # mechanism here, to signal to the source that their
                             # expected path failed.
-                            RNS.log("Got packet in transport, but no known path to final destination. Dropping packet.", RNS.LOG_DEBUG)
+                            RNS.log("Got packet in transport, but no known path to final destination "+RNS.prettyhexrep(packet.destination_hash)+". Dropping packet.", RNS.LOG_DEBUG)
 
                 # Link transport handling. Directs packets according
                 # to entries in the link tables
@@ -617,7 +765,7 @@ class Transport:
             # of queued announce rebroadcasts once handed to the next node.
             if packet.packet_type == RNS.Packet.ANNOUNCE:
                 local_destination = next((d for d in Transport.destinations if d.hash == packet.destination_hash), None)
-                if local_destination == None and RNS.Identity.validateAnnounce(packet):
+                if local_destination == None and RNS.Identity.validate_announce(packet): 
                     if packet.transport_id != None:
                         received_from = packet.transport_id
                         
@@ -650,7 +798,8 @@ class Transport:
                     # First, check that the announce is not for a destination
                     # local to this system, and that hops are less than the max
                     if (not any(packet.destination_hash == d.hash for d in Transport.destinations) and packet.hops < Transport.PATHFINDER_M+1):
-                        random_blob = packet.data[RNS.Identity.DERKEYSIZE//8+10:RNS.Identity.DERKEYSIZE//8+20]
+                        random_blob = packet.data[RNS.Identity.KEYSIZE//8:RNS.Identity.KEYSIZE//8+RNS.Reticulum.TRUNCATED_HASHLENGTH//8]
+                        announce_emitted = int.from_bytes(random_blob[5:10], "big")
                         random_blobs = []
                         if packet.destination_hash in Transport.destination_table:
                             random_blobs = Transport.destination_table[packet.destination_hash][4]
@@ -671,8 +820,18 @@ class Transport:
                             else:
                                 # If an announce arrives with a larger hop
                                 # count than we already have in the table,
-                                # ignore it, unless the path is expired
-                                if (time.time() > Transport.destination_table[packet.destination_hash][3]):
+                                # ignore it, unless the path is expired, or
+                                # the emission timestamp is more recent.
+                                now = time.time()
+                                path_expires = Transport.destination_table[packet.destination_hash][3]
+                                
+                                path_announce_emitted = 0
+                                for path_random_blob in random_blobs:
+                                    path_announce_emitted = max(path_announce_emitted, int.from_bytes(path_random_blob[5:10], "big"))
+                                    if path_announce_emitted >= announce_emitted:
+                                        break
+
+                                if (now >= path_expires):
                                     # We also check that the announce hash is
                                     # different from ones we've already heard,
                                     # to avoid loops in the network
@@ -684,7 +843,13 @@ class Transport:
                                     else:
                                         should_add = False
                                 else:
-                                    should_add = False
+                                    if (announce_emitted > path_announce_emitted):
+                                        if not random_blob in random_blobs:
+                                            RNS.log("Replacing destination table entry for "+str(RNS.prettyhexrep(packet.destination_hash))+" with new announce, since it was more recently emitted", RNS.LOG_DEBUG)
+                                            should_add = True
+                                        else:
+                                            should_add = False
+
                         else:
                             # If this destination is unknown in our table
                             # we should add it
@@ -706,6 +871,7 @@ class Transport:
                                 # If the announce is from a local client,
                                 # we announce it immediately, but only one
                                 # time.
+
                                 if Transport.from_local_client(packet):
                                     retransmit_timeout = now
                                     retries = Transport.PATHFINDER_R
@@ -732,23 +898,81 @@ class Transport:
                                 announce_context = RNS.Packet.NONE
                                 announce_data = packet.data
 
-                                new_announce = RNS.Packet(
-                                    announce_destination,
-                                    announce_data,
-                                    RNS.Packet.ANNOUNCE,
-                                    context = announce_context,
-                                    header_type = RNS.Packet.HEADER_2,
-                                    transport_type = Transport.TRANSPORT,
-                                    transport_id = Transport.identity.hash,
-                                    attached_interface = attached_interface
-                                )
+                                if Transport.from_local_client(packet) and packet.context == RNS.Packet.PATH_RESPONSE:
+                                    for local_interface in Transport.local_client_interfaces:
+                                        if packet.receiving_interface != local_interface:
+                                            new_announce = RNS.Packet(
+                                                announce_destination,
+                                                announce_data,
+                                                RNS.Packet.ANNOUNCE,
+                                                context = announce_context,
+                                                header_type = RNS.Packet.HEADER_2,
+                                                transport_type = Transport.TRANSPORT,
+                                                transport_id = Transport.identity.hash,
+                                                attached_interface = local_interface
+                                            )
+                                            
+                                            new_announce.hops = packet.hops
+                                            new_announce.send()
 
-                                new_announce.hops = packet.hops
-                                new_announce.send()
+                                else:
+                                    for local_interface in Transport.local_client_interfaces:
+                                        if packet.receiving_interface != local_interface:
+                                            new_announce = RNS.Packet(
+                                                announce_destination,
+                                                announce_data,
+                                                RNS.Packet.ANNOUNCE,
+                                                context = announce_context,
+                                                header_type = RNS.Packet.HEADER_2,
+                                                transport_type = Transport.TRANSPORT,
+                                                transport_id = Transport.identity.hash,
+                                                attached_interface = local_interface
+                                            )
 
-                            Transport.destination_table[packet.destination_hash] = [now, received_from, announce_hops, expires, random_blobs, packet.receiving_interface, packet]
+                                            new_announce.hops = packet.hops
+                                            new_announce.send()
+
+                            destination_table_entry = [now, received_from, announce_hops, expires, random_blobs, packet.receiving_interface, packet]
+                            Transport.destination_table[packet.destination_hash] = destination_table_entry
                             RNS.log("Path to "+RNS.prettyhexrep(packet.destination_hash)+" is now "+str(announce_hops)+" hops away via "+RNS.prettyhexrep(received_from)+" on "+str(packet.receiving_interface), RNS.LOG_VERBOSE)
-            
+
+                            # If the receiving interface is a tunnel, we add the
+                            # announce to the tunnels table
+                            if hasattr(packet.receiving_interface, "tunnel_id") and packet.receiving_interface.tunnel_id != None:
+                                tunnel_entry = Transport.tunnels[packet.receiving_interface.tunnel_id]
+                                paths = tunnel_entry[2]
+                                paths[packet.destination_hash] = destination_table_entry
+                                expires = time.time() + Transport.DESTINATION_TIMEOUT
+                                tunnel_entry[3] = expires
+                                RNS.log("Path to "+RNS.prettyhexrep(packet.destination_hash)+" associated with tunnel "+RNS.prettyhexrep(packet.receiving_interface.tunnel_id), RNS.LOG_VERBOSE)
+
+                            # Call externally registered callbacks from apps
+                            # wanting to know when an announce arrives
+                            if packet.context != RNS.Packet.PATH_RESPONSE:
+                                for handler in Transport.announce_handlers:
+                                    try:
+                                        # Check that the announced destination matches
+                                        # the handlers aspect filter
+                                        execute_callback = False
+                                        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
+                                        if execute_callback:
+                                            handler.received_announce(
+                                                destination_hash=packet.destination_hash,
+                                                announced_identity=announce_identity,
+                                                app_data=RNS.Identity.recall_app_data(packet.destination_hash)
+                                            )
+                                    except Exception as e:
+                                        RNS.log("Error while processing external announce callback.", RNS.LOG_ERROR)
+                                        RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+
             # Handling for linkrequests to local destinations
             elif packet.packet_type == RNS.Packet.LINKREQUEST:
                 for destination in Transport.destinations:
@@ -774,8 +998,11 @@ class Transport:
 
                             elif destination.proof_strategy == RNS.Destination.PROVE_APP:
                                 if destination.callbacks.proof_requested:
-                                    if destination.callbacks.proof_requested(packet):
-                                        packet.prove()
+                                    try:
+                                        if destination.callbacks.proof_requested(packet):
+                                            packet.prove()
+                                    except Exception as e:
+                                        RNS.log("Error while executing proof request callback. The contained exception was: "+str(e), RNS.LOG_ERROR)
 
             # Handling for proofs and link-request proofs
             elif packet.packet_type == RNS.Packet.PROOF:
@@ -800,7 +1027,7 @@ class Transport:
                         # pending link
                         for link in Transport.pending_links:
                             if link.link_id == packet.destination_hash:
-                                link.validateProof(packet)
+                                link.validate_proof(packet)
 
                 elif packet.context == RNS.Packet.RESOURCE_PRF:
                     for link in Transport.active_links:
@@ -834,30 +1061,143 @@ class Transport:
                         if proof_hash != None:
                             # Only test validation if hash matches
                             if receipt.hash == proof_hash:
-                                receipt_validated = receipt.validateProofPacket(packet)
+                                receipt_validated = receipt.validate_proof_packet(packet)
                         else:
+                            # TODO: This looks like it should actually
+                            # be rewritten when implicit proofs are added.
+
                             # In case of an implicit proof, we have
                             # to check every single outstanding receipt
-                            receipt_validated = receipt.validateProofPacket(packet)
+                            receipt_validated = receipt.validate_proof_packet(packet)
 
                         if receipt_validated:
-                            Transport.receipts.remove(receipt)
+                            if receipt in Transport.receipts:
+                                Transport.receipts.remove(receipt)
 
         Transport.jobs_locked = False
 
     @staticmethod
-    def registerDestination(destination):
+    def synthesize_tunnel(interface):
+        interface_hash = interface.get_hash()
+        public_key     = RNS.Transport.identity.get_public_key()
+        random_hash    = RNS.Identity.get_random_hash()
+        
+        tunnel_id_data = public_key+interface_hash
+        tunnel_id      = RNS.Identity.full_hash(tunnel_id_data)
+
+        signed_data    = tunnel_id_data+random_hash
+        signature      = Transport.identity.sign(signed_data)
+        
+        data           = signed_data+signature
+
+        tnl_snth_dst   = RNS.Destination(None, RNS.Destination.OUT, RNS.Destination.PLAIN, Transport.APP_NAME, "tunnel", "synthesize")
+
+        packet = RNS.Packet(tnl_snth_dst, data, packet_type = RNS.Packet.DATA, transport_type = RNS.Transport.BROADCAST, header_type = RNS.Packet.HEADER_1, attached_interface = interface)
+        packet.send()
+
+        interface.wants_tunnel = False
+
+    @staticmethod
+    def tunnel_synthesize_handler(data, packet):
+        try:
+            expected_length = RNS.Identity.KEYSIZE//8+RNS.Identity.HASHLENGTH//8+RNS.Reticulum.TRUNCATED_HASHLENGTH//8+RNS.Identity.SIGLENGTH//8
+            if len(data) == expected_length:
+                public_key     = data[:RNS.Identity.KEYSIZE//8]
+                interface_hash = data[RNS.Identity.KEYSIZE//8:RNS.Identity.KEYSIZE//8+RNS.Identity.HASHLENGTH//8]
+                tunnel_id_data = public_key+interface_hash
+                tunnel_id      = RNS.Identity.full_hash(tunnel_id_data)
+                random_hash    = data[RNS.Identity.KEYSIZE//8+RNS.Identity.HASHLENGTH//8:RNS.Identity.KEYSIZE//8+RNS.Identity.HASHLENGTH//8+RNS.Reticulum.TRUNCATED_HASHLENGTH//8]
+                
+                signature      = data[RNS.Identity.KEYSIZE//8+RNS.Identity.HASHLENGTH//8+RNS.Reticulum.TRUNCATED_HASHLENGTH//8:expected_length]
+                signed_data    = tunnel_id_data+random_hash
+
+                remote_transport_identity = RNS.Identity(create_keys=False)
+                remote_transport_identity.load_public_key(public_key)
+
+                if remote_transport_identity.validate(signature, signed_data):
+                    Transport.handle_tunnel(tunnel_id, packet.receiving_interface)
+
+        except Exception as e:
+            RNS.log("An error occurred while validating tunnel establishment packet.", RNS.LOG_DEBUG)
+            RNS.log("The contained exception was: "+str(e), RNS.LOG_DEBUG)
+
+    @staticmethod
+    def handle_tunnel(tunnel_id, interface):
+        expires = time.time() + Transport.DESTINATION_TIMEOUT
+        if not tunnel_id in Transport.tunnels:
+            RNS.log("Tunnel endpoint "+RNS.prettyhexrep(tunnel_id)+" established.", RNS.LOG_DEBUG)
+            paths = {}
+            tunnel_entry = [tunnel_id, interface, paths, expires]
+            interface.tunnel_id = tunnel_id
+            Transport.tunnels[tunnel_id] = tunnel_entry
+        else:
+            RNS.log("Tunnel endpoint "+RNS.prettyhexrep(tunnel_id)+" reappeared. Restoring paths...", RNS.LOG_DEBUG)
+            tunnel_entry = Transport.tunnels[tunnel_id]
+            tunnel_entry[1] = interface
+            tunnel_entry[3] = expires
+            interface.tunnel_id = tunnel_id
+            paths = tunnel_entry[2]
+
+            deprecated_paths = []
+            for destination_hash, path_entry in paths.items():
+                received_from = path_entry[1]
+                announce_hops = path_entry[2]
+                expires = path_entry[3]
+                random_blobs = path_entry[4]
+                receiving_interface = interface
+                packet = path_entry[6]
+                new_entry = [time.time(), received_from, announce_hops, expires, random_blobs, receiving_interface, packet]
+
+                should_add = False
+                if destination_hash in Transport.destination_table:
+                    old_entry = Transport.destination_table[destination_hash]
+                    old_hops = old_entry[2]
+                    old_expires = old_entry[3]
+                    if announce_hops <= old_hops or time.time() > old_expires:
+                        should_add = True
+                    else:
+                        RNS.log("Did not restore path to "+RNS.prettyhexrep(packet.destination_hash)+" because a newer path with fewer hops exist", RNS.LOG_DEBUG)
+                else:
+                    if time.time() < expires:
+                        should_add = True
+                    else:
+                        RNS.log("Did not restore path to "+RNS.prettyhexrep(packet.destination_hash)+" because it has expired", RNS.LOG_DEBUG)
+
+                if should_add:
+                    Transport.destination_table[destination_hash] = new_entry
+                    RNS.log("Restored path to "+RNS.prettyhexrep(packet.destination_hash)+" is now "+str(announce_hops)+" hops away via "+RNS.prettyhexrep(received_from)+" on "+str(receiving_interface), RNS.LOG_DEBUG)
+                else:
+                    deprecated_paths.append(destination_hash)
+
+            for deprecated_path in deprecated_paths:
+                RNS.log("Removing path to "+RNS.prettyhexrep(deprecated_path)+" from tunnel "+RNS.prettyhexrep(tunnel_id), RNS.LOG_DEBUG)
+                paths.pop(deprecated_path)
+
+
+                
+
+
+    @staticmethod
+    def register_destination(destination):
         destination.MTU = RNS.Reticulum.MTU
         if destination.direction == RNS.Destination.IN:
+            for registered_destination in Transport.destinations:
+                if destination.hash == registered_destination.hash:
+                    raise KeyError("Attempt to register an already registered destination.")
+            
             Transport.destinations.append(destination)
 
+            if Transport.owner.is_connected_to_shared_instance:
+                if destination.type == RNS.Destination.SINGLE:
+                    destination.announce(path_response=True)
+
     @staticmethod
     def deregister_destination(destination):
         if destination in Transport.destinations:
             Transport.destinations.remove(destination)
 
     @staticmethod
-    def registerLink(link):
+    def register_link(link):
         RNS.log("Registering link "+str(link), RNS.LOG_DEBUG)
         if link.initiator:
             Transport.pending_links.append(link)
@@ -865,7 +1205,7 @@ class Transport:
             Transport.active_links.append(link)
 
     @staticmethod
-    def activateLink(link):
+    def activate_link(link):
         RNS.log("Activating link "+str(link), RNS.LOG_DEBUG)
         if link in Transport.pending_links:
             Transport.pending_links.remove(link)
@@ -874,6 +1214,27 @@ class Transport:
         else:
             RNS.log("Attempted to activate a link that was not in the pending table", RNS.LOG_ERROR)
 
+    @staticmethod
+    def register_announce_handler(handler):
+        """
+        Registers an announce handler.
+
+        :param handler: Must be an object with an *aspect_filter* attribute and a *received_announce(destination_hash, announced_identity, app_data)* callable. See the :ref:`Announce Example<example-announce>` for more info.
+        """
+        if hasattr(handler, "received_announce") and callable(handler.received_announce):
+            if hasattr(handler, "aspect_filter"):
+                Transport.announce_handlers.append(handler)
+
+    @staticmethod
+    def deregister_announce_handler(handler):
+        """
+        Deregisters an announce handler.
+
+        :param handler: The announce handler to be deregistered.
+        """
+        while handler in Transport.announce_handlers:
+            Transport.announce_handlers.remove(handler)
+
     @staticmethod
     def find_interface_from_hash(interface_hash):
         for interface in Transport.interfaces:
@@ -883,7 +1244,7 @@ class Transport:
         return None
 
     @staticmethod
-    def shouldCache(packet):
+    def should_cache(packet):
         if packet.context == RNS.Packet.RESOURCE_PRF:
             return True
 
@@ -896,9 +1257,9 @@ class Transport:
     # the packet cache.
     @staticmethod
     def cache(packet, force_cache=False):
-        if RNS.Transport.shouldCache(packet) or force_cache:
+        if RNS.Transport.should_cache(packet) or force_cache:
             try:
-                packet_hash = RNS.hexrep(packet.getHash(), delimit=False)
+                packet_hash = RNS.hexrep(packet.get_hash(), delimit=False)
                 interface_reference = None
                 if packet.receiving_interface != None:
                     interface_reference = str(packet.receiving_interface)
@@ -966,37 +1327,84 @@ class Transport:
             RNS.Packet(destination, packet_hash, context = RNS.Packet.CACHE_REQUEST).send()
 
     @staticmethod
-    def hasPath(destination_hash):
+    def has_path(destination_hash):
+        """
+        :param destination_hash: A destination hash as *bytes*.
+        :returns: *True* if a path to the destination is known, otherwise *False*.
+        """
         if destination_hash in Transport.destination_table:
             return True
         else:
             return False
 
     @staticmethod
-    def requestPath(destination_hash):
-        path_request_data = destination_hash + RNS.Identity.getRandomHash()
+    def hops_to(destination_hash):
+        """
+        :param destination_hash: A destination hash as *bytes*.
+        :returns: The number of hops to the specified destination, or ``RNS.Transport.PATHFINDER_M`` if the number of hops is unknown.
+        """
+        if destination_hash in Transport.destination_table:
+            return Transport.destination_table[destination_hash][2]
+        else:
+            return Transport.PATHFINDER_M
+
+    @staticmethod
+    def next_hop(destination_hash):
+        """
+        :param destination_hash: A destination hash as *bytes*.
+        :returns: The destination hash as *bytes* for the next hop to the specified destination, or *None* if the next hop is unknown.
+        """
+        if destination_hash in Transport.destination_table:
+            return Transport.destination_table[destination_hash][1]
+        else:
+            return None
+
+    @staticmethod
+    def next_hop_interface(destination_hash):
+        """
+        :param destination_hash: A destination hash as *bytes*.
+        :returns: The interface for the next hop to the specified destination, or *None* if the interface is unknown.
+        """
+        if destination_hash in Transport.destination_table:
+            return Transport.destination_table[destination_hash][5]
+        else:
+            return None
+
+    @staticmethod
+    def request_path(destination_hash):
+        """
+        Requests a path to the destination from the network. If
+        another reachable peer on the network knows a path, it
+        will announce it.
+
+        :param destination_hash: A destination hash as *bytes*.
+        """
+        path_request_data = destination_hash + RNS.Identity.get_random_hash()
         path_request_dst = RNS.Destination(None, RNS.Destination.OUT, RNS.Destination.PLAIN, Transport.APP_NAME, "path", "request")
         packet = RNS.Packet(path_request_dst, path_request_data, packet_type = RNS.Packet.DATA, transport_type = RNS.Transport.BROADCAST, header_type = RNS.Packet.HEADER_1)
         packet.send()
 
     @staticmethod
-    def requestPathOnInterface(destination_hash, interface):
-        path_request_data = destination_hash + RNS.Identity.getRandomHash()
+    def request_path_on_interface(destination_hash, interface):
+        path_request_data = destination_hash + RNS.Identity.get_random_hash()
         path_request_dst = RNS.Destination(None, RNS.Destination.OUT, RNS.Destination.PLAIN, Transport.APP_NAME, "path", "request")
         packet = RNS.Packet(path_request_dst, path_request_data, packet_type = RNS.Packet.DATA, transport_type = RNS.Transport.BROADCAST, header_type = RNS.Packet.HEADER_1, attached_interface = interface)
         packet.send()
 
     @staticmethod
     def path_request_handler(data, packet):
-        if len(data) >= RNS.Identity.TRUNCATED_HASHLENGTH//8:
-            Transport.pathRequest(
-                data[:RNS.Identity.TRUNCATED_HASHLENGTH//8],
-                Transport.from_local_client(packet),
-                packet.receiving_interface
-            )
+        try:
+            if len(data) >= RNS.Identity.TRUNCATED_HASHLENGTH//8:
+                Transport.path_request(
+                    data[:RNS.Identity.TRUNCATED_HASHLENGTH//8],
+                    Transport.from_local_client(packet),
+                    packet.receiving_interface
+                )
+        except Exception as e:
+            RNS.log("Error while handling path request. The contained exception was: "+str(e), RNS.LOG_ERROR)
 
     @staticmethod
-    def pathRequest(destination_hash, is_from_local_client, attached_interface):
+    def path_request(destination_hash, is_from_local_client, attached_interface):
         RNS.log("Path request for "+RNS.prettyhexrep(destination_hash), RNS.LOG_DEBUG)
         
         local_destination = next((d for d in Transport.destinations if d.hash == destination_hash), None)
@@ -1004,7 +1412,7 @@ class Transport:
             RNS.log("Destination is local to this system, announcing", RNS.LOG_DEBUG)
             local_destination.announce(path_response=True)
 
-        elif (RNS.Reticulum.transport_enabled() or is_from_local_client) and destination_hash in Transport.destination_table:
+        elif (RNS.Reticulum.transport_enabled() or is_from_local_client or len(Transport.local_client_interfaces) > 0) and destination_hash in Transport.destination_table:
             RNS.log("Path found, inserting announce for transmission", RNS.LOG_DEBUG)
             packet = Transport.destination_table[destination_hash][6]
             received_from = Transport.destination_table[destination_hash][5]
@@ -1038,13 +1446,13 @@ class Transport:
             # except the local client
             for interface in Transport.interfaces:
                 if not interface == attached_interface:
-                    Transport.requestPathOnInterface(destination_hash, interface)
+                    Transport.request_path_on_interface(destination_hash, interface)
 
         elif not is_from_local_client and len(Transport.local_client_interfaces) > 0:
             # Forward the path request on all local
             # client interfaces
             for interface in Transport.local_client_interfaces:
-                Transport.requestPathOnInterface(destination_hash, interface)
+                Transport.request_path_on_interface(destination_hash, interface)
 
         else:
             RNS.log("No known path to requested destination, ignoring request", RNS.LOG_DEBUG)
@@ -1074,14 +1482,27 @@ class Transport:
             return False
 
     @staticmethod
-    def exitHandler():
-        RNS.log("Saving packet hashlist to storage...", RNS.LOG_VERBOSE)
+    def detach_interfaces():
+        for interface in Transport.interfaces:
+            interface.detach()
+
+        for interface in Transport.local_client_interfaces:
+            interface.detach()
+
+
+    @staticmethod
+    def exit_handler():
         try:
+            if not RNS.Reticulum.transport_enabled():
+                Transport.packet_hashlist = []
+            else:
+                RNS.log("Saving packet hashlist to storage...", RNS.LOG_VERBOSE)
+
             packet_hashlist_path = RNS.Reticulum.storagepath+"/packet_hashlist"
             file = open(packet_hashlist_path, "wb")
             file.write(umsgpack.packb(Transport.packet_hashlist))
             file.close()
-            RNS.log("Done packet hashlist to storage", RNS.LOG_VERBOSE)
+
         except Exception as e:
             RNS.log("Could not save packet hashlist to storage, the contained exception was: "+str(e), RNS.LOG_ERROR)
 
@@ -1105,7 +1526,7 @@ class Transport:
                         hops = de[2]
                         expires = de[3]
                         random_blobs = de[4]
-                        packet_hash = de[6].getHash()
+                        packet_hash = de[6].get_hash()
 
                         serialised_entry = [
                             destination_hash,
@@ -1126,6 +1547,58 @@ class Transport:
                 file = open(destination_table_path, "wb")
                 file.write(umsgpack.packb(serialised_destinations))
                 file.close()
-                RNS.log("Done saving path table to storage", RNS.LOG_VERBOSE)
+                RNS.log("Done saving "+str(len(serialised_destinations))+" path table entries to storage", RNS.LOG_VERBOSE)
             except Exception as e:
                 RNS.log("Could not save path table to storage, the contained exception was: "+str(e), RNS.LOG_ERROR)
+
+            RNS.log("Saving tunnel table to storage...", RNS.LOG_VERBOSE)
+            try:
+                serialised_tunnels = []
+                for tunnel_id in Transport.tunnels:
+                    te = Transport.tunnels[tunnel_id]
+                    interface = te[1]
+                    tunnel_paths = te[2]
+                    expires = te[3]
+
+                    if interface != None:
+                        interface_hash = interface.get_hash()
+                    else:
+                        interface_hash = None
+
+                    serialised_paths = []
+                    for destination_hash in tunnel_paths:
+                        de = tunnel_paths[destination_hash]
+
+                        timestamp = de[0]
+                        received_from = de[1]
+                        hops = de[2]
+                        expires = de[3]
+                        random_blobs = de[4]
+                        packet_hash = de[6].get_hash()
+
+                        serialised_entry = [
+                            destination_hash,
+                            timestamp,
+                            received_from,
+                            hops,
+                            expires,
+                            random_blobs,
+                            interface_hash,
+                            packet_hash
+                        ]
+
+                        serialised_paths.append(serialised_entry)
+
+                        Transport.cache(de[6], force_cache=True)
+
+
+                    serialised_tunnel = [tunnel_id, interface_hash, serialised_paths, expires]
+                    serialised_tunnels.append(serialised_tunnel)
+
+                tunnels_path = RNS.Reticulum.storagepath+"/tunnels"
+                file = open(tunnels_path, "wb")
+                file.write(umsgpack.packb(serialised_tunnels))
+                file.close()
+                RNS.log("Done saving "+str(len(serialised_tunnels))+" tunnel table entries to storage", RNS.LOG_VERBOSE)
+            except Exception as e:
+                RNS.log("Could not save tunnel table to storage, the contained exception was: "+str(e), RNS.LOG_ERROR)

RNS/Utilities/__init__.py

@@ -0,0 +1,5 @@
+import os
+import glob
+
+modules = glob.glob(os.path.dirname(__file__)+"/*.py")
+__all__ = [ os.path.basename(f)[:-3] for f in modules if not f.endswith('__init__.py')]

RNS/Utilities/rnpath.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+
+import RNS
+import sys
+import time
+import argparse
+
+from RNS._version import __version__
+
+
+def program_setup(configdir, destination_hexhash, verbosity):
+    try:
+        dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
+        if len(destination_hexhash) != dest_len:
+            raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+        try:
+            destination_hash = bytes.fromhex(destination_hexhash)
+        except Exception as e:
+            raise ValueError("Invalid destination entered. Check your input.")
+    except Exception as e:
+        print(str(e))
+        exit()
+
+    reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity)
+
+    if not RNS.Transport.has_path(destination_hash):
+        RNS.Transport.request_path(destination_hash)
+        print("Path to "+RNS.prettyhexrep(destination_hash)+" requested  ", end=" ")
+        sys.stdout.flush()
+
+    i = 0
+    syms = "⢄⢂⢁⡁⡈⡐⡠"
+    while not RNS.Transport.has_path(destination_hash):
+        time.sleep(0.1)
+        print(("\b\b"+syms[i]+" "), end="")
+        sys.stdout.flush()
+        i = (i+1)%len(syms)
+
+    hops = RNS.Transport.hops_to(destination_hash)
+    next_hop = RNS.prettyhexrep(reticulum.get_next_hop(destination_hash))
+    next_hop_interface = reticulum.get_next_hop_if_name(destination_hash)
+
+    if hops != 1:
+        ms = "s"
+    else:
+        ms = ""
+
+    print("\rPath found, destination "+RNS.prettyhexrep(destination_hash)+" is "+str(hops)+" hop"+ms+" away via "+next_hop+" on "+next_hop_interface)
+    
+
+def main():
+    try:
+        parser = argparse.ArgumentParser(description="Reticulum Path Discovery Utility")
+
+        parser.add_argument("--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
+
+        parser.add_argument(
+            "--version",
+            action="version",
+            version="rnpath {version}".format(version=__version__)
+        )
+
+        parser.add_argument(
+            "destination",
+            nargs="?",
+            default=None,
+            help="hexadecimal hash of the destination",
+            type=str
+        )
+
+        parser.add_argument('-v', '--verbose', action='count', default=0)
+        
+        args = parser.parse_args()
+
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        if not args.destination:
+            print("")
+            parser.print_help()
+            print("")
+        else:
+            program_setup(configdir = configarg, destination_hexhash = args.destination, verbosity = args.verbose)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()
+
+if __name__ == "__main__":
+    main()

RNS/Utilities/rnprobe.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+
+import RNS
+import os
+import sys
+import time
+import argparse
+
+from RNS._version import __version__
+
+DEFAULT_PROBE_SIZE = 16
+
+def program_setup(configdir, destination_hexhash, size=DEFAULT_PROBE_SIZE, full_name = None, verbosity = 0):
+    if full_name == None:
+        print("The full destination name including application name aspects must be specified for the destination")
+        exit()
+    
+    try:
+        app_name, aspects = RNS.Destination.app_and_aspects_from_name(full_name)
+
+    except Exception as e:
+        print(str(e))
+        exit()
+
+    try:
+        dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
+        if len(destination_hexhash) != dest_len:
+            raise ValueError("Destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+        try:
+            destination_hash = bytes.fromhex(destination_hexhash)
+        except Exception as e:
+            raise ValueError("Invalid destination entered. Check your input.")
+    except Exception as e:
+        print(str(e))
+        exit()
+
+    if verbosity > 0:
+        more_output = True
+        verbosity -= 1
+    else:
+        more_output = False
+        verbosity -= 1
+
+
+    reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity)
+
+    if not RNS.Transport.has_path(destination_hash):
+        RNS.Transport.request_path(destination_hash)
+        print("Path to "+RNS.prettyhexrep(destination_hash)+" requested  ", end=" ")
+        sys.stdout.flush()
+
+    i = 0
+    syms = "⢄⢂⢁⡁⡈⡐⡠"
+    while not RNS.Transport.has_path(destination_hash):
+        time.sleep(0.1)
+        print(("\b\b"+syms[i]+" "), end="")
+        sys.stdout.flush()
+        i = (i+1)%len(syms)
+
+    server_identity = RNS.Identity.recall(destination_hash)
+
+    request_destination = RNS.Destination(
+        server_identity,
+        RNS.Destination.OUT,
+        RNS.Destination.SINGLE,
+        app_name,
+        *aspects
+    )
+
+    probe = RNS.Packet(request_destination, os.urandom(size))
+    receipt = probe.send()
+
+    if more_output:
+        more = " via "+RNS.prettyhexrep(reticulum.get_next_hop(destination_hash))+" on "+str(reticulum.get_next_hop_if_name(destination_hash))
+    else:
+        more = ""
+
+    print("\rSent "+str(size)+" byte probe to "+RNS.prettyhexrep(destination_hash)+more+"  ", end=" ")
+
+    i = 0
+    while not receipt.status == RNS.PacketReceipt.DELIVERED:
+        time.sleep(0.1)
+        print(("\b\b"+syms[i]+" "), end="")
+        sys.stdout.flush()
+        i = (i+1)%len(syms)
+
+    print("\b\b ")
+    sys.stdout.flush()
+
+    hops = RNS.Transport.hops_to(destination_hash)
+    if hops != 1:
+        ms = "s"
+    else:
+        ms = ""
+
+    rtt = receipt.get_rtt()
+    if (rtt >= 1):
+        rtt = round(rtt, 3)
+        rttstring = str(rtt)+" seconds"
+    else:
+        rtt = round(rtt*1000, 3)
+        rttstring = str(rtt)+" milliseconds"
+
+    reception_stats = ""
+    if reticulum.is_connected_to_shared_instance:
+        reception_rssi = reticulum.get_packet_rssi(receipt.proof_packet.packet_hash)
+        reception_snr  = reticulum.get_packet_snr(receipt.proof_packet.packet_hash)
+
+        if reception_rssi != None:
+            reception_stats += " [RSSI "+str(reception_rssi)+" dBm]"
+        
+        if reception_snr != None:
+            reception_stats += " [SNR "+str(reception_snr)+" dB]"
+
+    else:
+        if receipt.proof_packet != None:
+            if receipt.proof_packet.rssi != None:
+                reception_stats += " [RSSI "+str(receipt.proof_packet.rssi)+" dBm]"
+            
+            if receipt.proof_packet.snr != None:
+                reception_stats += " [SNR "+str(receipt.proof_packet.snr)+" dB]"
+
+    print(
+        "Valid reply received from "+
+        RNS.prettyhexrep(receipt.destination.hash)+
+        "\nRound-trip time is "+rttstring+
+        " over "+str(hops)+" hop"+ms+
+        reception_stats
+    )
+
+    
+
+def main():
+    try:
+        parser = argparse.ArgumentParser(description="Reticulum Probe Utility")
+
+        parser.add_argument("--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
+
+        parser.add_argument(
+            "--version",
+            action="version",
+            version="rnprobe {version}".format(version=__version__)
+        )
+
+        parser.add_argument(
+            "full_name",
+            nargs="?",
+            default=None,
+            help="full destination name in dotted notation",
+            type=str
+        )
+
+        parser.add_argument(
+            "destination_hash",
+            nargs="?",
+            default=None,
+            help="hexadecimal hash of the destination",
+            type=str
+        )
+
+        parser.add_argument('-v', '--verbose', action='count', default=0)
+
+        args = parser.parse_args()
+
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        if not args.destination_hash:
+            print("")
+            parser.print_help()
+            print("")
+        else:
+            program_setup(
+                configdir = configarg,
+                destination_hexhash = args.destination_hash,
+                full_name = args.full_name,
+                verbosity = args.verbose
+            )
+
+    except KeyboardInterrupt:
+        print("")
+        exit()
+
+if __name__ == "__main__":
+    main()

RNS/Utilities/rnsd.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+
+import RNS
+import argparse
+
+from RNS._version import __version__
+
+
+def program_setup(configdir, verbosity = 0, quietness = 0):
+    reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity-quietness)
+    RNS.log("Started rnsd version {version}".format(version=__version__), RNS.LOG_NOTICE)
+    while True:
+        input()
+
+def main():
+    try:
+        parser = argparse.ArgumentParser(description="Reticulum Network Stack Daemon")
+        parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser.add_argument('-v', '--verbose', action='count', default=0)
+        parser.add_argument('-q', '--quiet', action='count', default=0)
+        parser.add_argument("--version", action="version", version="rnsd {version}".format(version=__version__))
+        
+        args = parser.parse_args()
+
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        program_setup(configdir = configarg, verbosity=args.verbose, quietness=args.quiet)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()
+
+if __name__ == "__main__":
+    main()

RNS/Utilities/rnstatus.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+
+import RNS
+import argparse
+
+from RNS._version import __version__
+
+def size_str(num, suffix='B'):
+    units = ['','K','M','G','T','P','E','Z']
+    last_unit = 'Y'
+
+    if suffix == 'b':
+        num *= 8
+        units = ['','K','M','G','T','P','E','Z']
+        last_unit = 'Y'
+
+    for unit in units:
+        if abs(num) < 1000.0:
+            if unit == "":
+                return "%.0f %s%s" % (num, unit, suffix)
+            else:
+                return "%.2f %s%s" % (num, unit, suffix)
+        num /= 1000.0
+
+    return "%.2f%s%s" % (num, last_unit, suffix)
+
+def program_setup(configdir, dispall=False, verbosity = 0):
+    reticulum = RNS.Reticulum(configdir = configdir, loglevel = 3+verbosity)
+    
+    ifstats = reticulum.get_interface_stats()
+    if ifstats != None:
+        for ifstat in ifstats:
+            name = ifstat["name"]
+
+            if dispall or not (name.startswith("LocalInterface[") or name.startswith("TCPInterface[Client")):
+                print("")
+                if ifstat["status"]:
+                    ss = "Up"
+                else:
+                    ss = "Down"
+
+                if ifstat["clients"] != None:
+                    clients = ifstat["clients"]
+                    if name.startswith("Shared Instance["):
+                        clients_string = "Connected applications: "+str(max(clients-1,0))
+                    else:
+                        clients_string = "Connected clients: "+str(clients)
+
+                else:
+                    clients = None
+
+                print(" {n}".format(n=ifstat["name"]))
+                print("\tStatus: {ss}".format(ss=ss))
+                if clients != None:
+                    print("\t"+clients_string)
+                print("\tRX: {rxb}\n\tTX: {txb}".format(rxb=size_str(ifstat["rxb"]), txb=size_str(ifstat["txb"])))
+
+        print("")
+                
+    else:
+        print("Could not get RNS status")
+
+def main():
+    try:
+        parser = argparse.ArgumentParser(description="Reticulum Network Stack Status")
+        parser.add_argument("--config", action="store", default=None, help="path to alternative Reticulum config directory", type=str)
+        parser.add_argument("--version", action="version", version="rnstatus {version}".format(version=__version__))
+
+        parser.add_argument(
+            "-a",
+            "--all",
+            action="store_true",
+            help="show all interfaces",
+            default=False
+        )
+
+        parser.add_argument('-v', '--verbose', action='count', default=0)
+        
+        args = parser.parse_args()
+
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        program_setup(configdir = configarg, dispall = args.all, verbosity=args.verbose)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()
+
+if __name__ == "__main__":
+    main()

RNS/__init__.py

@@ -3,15 +3,18 @@ import sys
 import glob
 import time
 import random
+import threading
+
+from ._version import __version__
 
 from .Reticulum import Reticulum
 from .Identity import Identity
-from .Link import Link
+from .Link import Link, RequestReceipt
 from .Transport import Transport
 from .Destination import Destination
 from .Packet import Packet
 from .Packet import PacketReceipt
-from .Resource import Resource
+from .Resource import Resource, ResourceAdvertisement
 
 modules = glob.glob(os.path.dirname(__file__)+"/*.py")
 __all__ = [ os.path.basename(f)[:-3] for f in modules if not f.endswith('__init__.py')]
@@ -28,6 +31,8 @@ LOG_EXTREME  = 7
 LOG_STDOUT   = 0x91
 LOG_FILE     = 0x92
 
+LOG_MAXSIZE  = 5*1024*1024
+
 loglevel     = LOG_NOTICE
 logfile      = None
 logdest      = LOG_STDOUT
@@ -35,6 +40,10 @@ logtimefmt   = "%Y-%m-%d %H:%M:%S"
 
 random.seed(os.urandom(10))
 
+_always_override_destination = False
+
+logging_lock = threading.Lock()
+
 def loglevelname(level):
     if (level == LOG_CRITICAL):
         return "Critical"
@@ -55,19 +64,41 @@ def loglevelname(level):
     
     return "Unknown"
 
-def log(msg, level=3):
-    # TODO: not thread safe
+def version():
+    return __version__
+
+def log(msg, level=3, _override_destination = False):
+    global _always_override_destination
+    
     if loglevel >= level:
         timestamp = time.time()
         logstring = "["+time.strftime(logtimefmt)+"] ["+loglevelname(level)+"] "+msg
+        logging_lock.acquire()
 
-        if (logdest == LOG_STDOUT):
+        if (logdest == LOG_STDOUT or _always_override_destination or _override_destination):
             print(logstring)
+            logging_lock.release()
 
-        if (logdest == LOG_FILE and logfile != None):
-            file = open(logfile, "a")
-            file.write(logstring+"\n")
-            file.close()
+        elif (logdest == LOG_FILE and logfile != None):
+            try:
+                file = open(logfile, "a")
+                file.write(logstring+"\n")
+                file.close()
+                
+                if os.path.getsize(logfile) > LOG_MAXSIZE:
+                    prevfile = logfile+".1"
+                    if os.path.isfile(prevfile):
+                        os.unlink(prevfile)
+                    os.rename(logfile, prevfile)
+
+                logging_lock.release()
+            except Exception as e:
+                logging_lock.release()
+                _always_override_destination = True
+                log("Exception occurred while writing log message to log file: "+str(e), LOG_CRITICAL)
+                log("Dumping future log events to console!", LOG_CRITICAL)
+                log(msg, level)
+                
 
 def rand():
     result = random.random()
@@ -86,4 +117,7 @@ def prettyhexrep(data):
     return hexrep
 
 def panic():
-    os._exit(255)
+    os._exit(255)
+
+def exit():
+    sys.exit(0)

RNS/_version.py

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

RNS/vendor/configobj.py

@@ -19,7 +19,7 @@ import sys
 
 from codecs import BOM_UTF8, BOM_UTF16, BOM_UTF16_BE, BOM_UTF16_LE
 
-import six
+import RNS.vendor.six as six
 __version__ = '5.0.6'
 
 # imported lazily to avoid startup performance hit if it isn't used

RNS/vendor/six.py

@@ -0,0 +1,998 @@
+# Copyright (c) 2010-2020 Benjamin Peterson
+#
+# 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.
+
+"""Utilities for writing code that runs on Python 2 and 3"""
+
+from __future__ import absolute_import
+
+import functools
+import itertools
+import operator
+import sys
+import types
+
+__author__ = "Benjamin Peterson <benjamin@python.org>"
+__version__ = "1.16.0"
+
+
+# Useful for very coarse version differentiation.
+PY2 = sys.version_info[0] == 2
+PY3 = sys.version_info[0] == 3
+PY34 = sys.version_info[0:2] >= (3, 4)
+
+if PY3:
+    string_types = str,
+    integer_types = int,
+    class_types = type,
+    text_type = str
+    binary_type = bytes
+
+    MAXSIZE = sys.maxsize
+else:
+    string_types = basestring,
+    integer_types = (int, long)
+    class_types = (type, types.ClassType)
+    text_type = unicode
+    binary_type = str
+
+    if sys.platform.startswith("java"):
+        # Jython always uses 32 bits.
+        MAXSIZE = int((1 << 31) - 1)
+    else:
+        # It's possible to have sizeof(long) != sizeof(Py_ssize_t).
+        class X(object):
+
+            def __len__(self):
+                return 1 << 31
+        try:
+            len(X())
+        except OverflowError:
+            # 32-bit
+            MAXSIZE = int((1 << 31) - 1)
+        else:
+            # 64-bit
+            MAXSIZE = int((1 << 63) - 1)
+        del X
+
+if PY34:
+    from importlib.util import spec_from_loader
+else:
+    spec_from_loader = None
+
+
+def _add_doc(func, doc):
+    """Add documentation to a function."""
+    func.__doc__ = doc
+
+
+def _import_module(name):
+    """Import module, returning the module after the last dot."""
+    __import__(name)
+    return sys.modules[name]
+
+
+class _LazyDescr(object):
+
+    def __init__(self, name):
+        self.name = name
+
+    def __get__(self, obj, tp):
+        result = self._resolve()
+        setattr(obj, self.name, result)  # Invokes __set__.
+        try:
+            # This is a bit ugly, but it avoids running this again by
+            # removing this descriptor.
+            delattr(obj.__class__, self.name)
+        except AttributeError:
+            pass
+        return result
+
+
+class MovedModule(_LazyDescr):
+
+    def __init__(self, name, old, new=None):
+        super(MovedModule, self).__init__(name)
+        if PY3:
+            if new is None:
+                new = name
+            self.mod = new
+        else:
+            self.mod = old
+
+    def _resolve(self):
+        return _import_module(self.mod)
+
+    def __getattr__(self, attr):
+        _module = self._resolve()
+        value = getattr(_module, attr)
+        setattr(self, attr, value)
+        return value
+
+
+class _LazyModule(types.ModuleType):
+
+    def __init__(self, name):
+        super(_LazyModule, self).__init__(name)
+        self.__doc__ = self.__class__.__doc__
+
+    def __dir__(self):
+        attrs = ["__doc__", "__name__"]
+        attrs += [attr.name for attr in self._moved_attributes]
+        return attrs
+
+    # Subclasses should override this
+    _moved_attributes = []
+
+
+class MovedAttribute(_LazyDescr):
+
+    def __init__(self, name, old_mod, new_mod, old_attr=None, new_attr=None):
+        super(MovedAttribute, self).__init__(name)
+        if PY3:
+            if new_mod is None:
+                new_mod = name
+            self.mod = new_mod
+            if new_attr is None:
+                if old_attr is None:
+                    new_attr = name
+                else:
+                    new_attr = old_attr
+            self.attr = new_attr
+        else:
+            self.mod = old_mod
+            if old_attr is None:
+                old_attr = name
+            self.attr = old_attr
+
+    def _resolve(self):
+        module = _import_module(self.mod)
+        return getattr(module, self.attr)
+
+
+class _SixMetaPathImporter(object):
+
+    """
+    A meta path importer to import six.moves and its submodules.
+
+    This class implements a PEP302 finder and loader. It should be compatible
+    with Python 2.5 and all existing versions of Python3
+    """
+
+    def __init__(self, six_module_name):
+        self.name = six_module_name
+        self.known_modules = {}
+
+    def _add_module(self, mod, *fullnames):
+        for fullname in fullnames:
+            self.known_modules[self.name + "." + fullname] = mod
+
+    def _get_module(self, fullname):
+        return self.known_modules[self.name + "." + fullname]
+
+    def find_module(self, fullname, path=None):
+        if fullname in self.known_modules:
+            return self
+        return None
+
+    def find_spec(self, fullname, path, target=None):
+        if fullname in self.known_modules:
+            return spec_from_loader(fullname, self)
+        return None
+
+    def __get_module(self, fullname):
+        try:
+            return self.known_modules[fullname]
+        except KeyError:
+            raise ImportError("This loader does not know module " + fullname)
+
+    def load_module(self, fullname):
+        try:
+            # in case of a reload
+            return sys.modules[fullname]
+        except KeyError:
+            pass
+        mod = self.__get_module(fullname)
+        if isinstance(mod, MovedModule):
+            mod = mod._resolve()
+        else:
+            mod.__loader__ = self
+        sys.modules[fullname] = mod
+        return mod
+
+    def is_package(self, fullname):
+        """
+        Return true, if the named module is a package.
+
+        We need this method to get correct spec objects with
+        Python 3.4 (see PEP451)
+        """
+        return hasattr(self.__get_module(fullname), "__path__")
+
+    def get_code(self, fullname):
+        """Return None
+
+        Required, if is_package is implemented"""
+        self.__get_module(fullname)  # eventually raises ImportError
+        return None
+    get_source = get_code  # same as get_code
+
+    def create_module(self, spec):
+        return self.load_module(spec.name)
+
+    def exec_module(self, module):
+        pass
+
+_importer = _SixMetaPathImporter(__name__)
+
+
+class _MovedItems(_LazyModule):
+
+    """Lazy loading of moved objects"""
+    __path__ = []  # mark as package
+
+
+_moved_attributes = [
+    MovedAttribute("cStringIO", "cStringIO", "io", "StringIO"),
+    MovedAttribute("filter", "itertools", "builtins", "ifilter", "filter"),
+    MovedAttribute("filterfalse", "itertools", "itertools", "ifilterfalse", "filterfalse"),
+    MovedAttribute("input", "__builtin__", "builtins", "raw_input", "input"),
+    MovedAttribute("intern", "__builtin__", "sys"),
+    MovedAttribute("map", "itertools", "builtins", "imap", "map"),
+    MovedAttribute("getcwd", "os", "os", "getcwdu", "getcwd"),
+    MovedAttribute("getcwdb", "os", "os", "getcwd", "getcwdb"),
+    MovedAttribute("getoutput", "commands", "subprocess"),
+    MovedAttribute("range", "__builtin__", "builtins", "xrange", "range"),
+    MovedAttribute("reload_module", "__builtin__", "importlib" if PY34 else "imp", "reload"),
+    MovedAttribute("reduce", "__builtin__", "functools"),
+    MovedAttribute("shlex_quote", "pipes", "shlex", "quote"),
+    MovedAttribute("StringIO", "StringIO", "io"),
+    MovedAttribute("UserDict", "UserDict", "collections"),
+    MovedAttribute("UserList", "UserList", "collections"),
+    MovedAttribute("UserString", "UserString", "collections"),
+    MovedAttribute("xrange", "__builtin__", "builtins", "xrange", "range"),
+    MovedAttribute("zip", "itertools", "builtins", "izip", "zip"),
+    MovedAttribute("zip_longest", "itertools", "itertools", "izip_longest", "zip_longest"),
+    MovedModule("builtins", "__builtin__"),
+    MovedModule("configparser", "ConfigParser"),
+    MovedModule("collections_abc", "collections", "collections.abc" if sys.version_info >= (3, 3) else "collections"),
+    MovedModule("copyreg", "copy_reg"),
+    MovedModule("dbm_gnu", "gdbm", "dbm.gnu"),
+    MovedModule("dbm_ndbm", "dbm", "dbm.ndbm"),
+    MovedModule("_dummy_thread", "dummy_thread", "_dummy_thread" if sys.version_info < (3, 9) else "_thread"),
+    MovedModule("http_cookiejar", "cookielib", "http.cookiejar"),
+    MovedModule("http_cookies", "Cookie", "http.cookies"),
+    MovedModule("html_entities", "htmlentitydefs", "html.entities"),
+    MovedModule("html_parser", "HTMLParser", "html.parser"),
+    MovedModule("http_client", "httplib", "http.client"),
+    MovedModule("email_mime_base", "email.MIMEBase", "email.mime.base"),
+    MovedModule("email_mime_image", "email.MIMEImage", "email.mime.image"),
+    MovedModule("email_mime_multipart", "email.MIMEMultipart", "email.mime.multipart"),
+    MovedModule("email_mime_nonmultipart", "email.MIMENonMultipart", "email.mime.nonmultipart"),
+    MovedModule("email_mime_text", "email.MIMEText", "email.mime.text"),
+    MovedModule("BaseHTTPServer", "BaseHTTPServer", "http.server"),
+    MovedModule("CGIHTTPServer", "CGIHTTPServer", "http.server"),
+    MovedModule("SimpleHTTPServer", "SimpleHTTPServer", "http.server"),
+    MovedModule("cPickle", "cPickle", "pickle"),
+    MovedModule("queue", "Queue"),
+    MovedModule("reprlib", "repr"),
+    MovedModule("socketserver", "SocketServer"),
+    MovedModule("_thread", "thread", "_thread"),
+    MovedModule("tkinter", "Tkinter"),
+    MovedModule("tkinter_dialog", "Dialog", "tkinter.dialog"),
+    MovedModule("tkinter_filedialog", "FileDialog", "tkinter.filedialog"),
+    MovedModule("tkinter_scrolledtext", "ScrolledText", "tkinter.scrolledtext"),
+    MovedModule("tkinter_simpledialog", "SimpleDialog", "tkinter.simpledialog"),
+    MovedModule("tkinter_tix", "Tix", "tkinter.tix"),
+    MovedModule("tkinter_ttk", "ttk", "tkinter.ttk"),
+    MovedModule("tkinter_constants", "Tkconstants", "tkinter.constants"),
+    MovedModule("tkinter_dnd", "Tkdnd", "tkinter.dnd"),
+    MovedModule("tkinter_colorchooser", "tkColorChooser",
+                "tkinter.colorchooser"),
+    MovedModule("tkinter_commondialog", "tkCommonDialog",
+                "tkinter.commondialog"),
+    MovedModule("tkinter_tkfiledialog", "tkFileDialog", "tkinter.filedialog"),
+    MovedModule("tkinter_font", "tkFont", "tkinter.font"),
+    MovedModule("tkinter_messagebox", "tkMessageBox", "tkinter.messagebox"),
+    MovedModule("tkinter_tksimpledialog", "tkSimpleDialog",
+                "tkinter.simpledialog"),
+    MovedModule("urllib_parse", __name__ + ".moves.urllib_parse", "urllib.parse"),
+    MovedModule("urllib_error", __name__ + ".moves.urllib_error", "urllib.error"),
+    MovedModule("urllib", __name__ + ".moves.urllib", __name__ + ".moves.urllib"),
+    MovedModule("urllib_robotparser", "robotparser", "urllib.robotparser"),
+    MovedModule("xmlrpc_client", "xmlrpclib", "xmlrpc.client"),
+    MovedModule("xmlrpc_server", "SimpleXMLRPCServer", "xmlrpc.server"),
+]
+# Add windows specific modules.
+if sys.platform == "win32":
+    _moved_attributes += [
+        MovedModule("winreg", "_winreg"),
+    ]
+
+for attr in _moved_attributes:
+    setattr(_MovedItems, attr.name, attr)
+    if isinstance(attr, MovedModule):
+        _importer._add_module(attr, "moves." + attr.name)
+del attr
+
+_MovedItems._moved_attributes = _moved_attributes
+
+moves = _MovedItems(__name__ + ".moves")
+_importer._add_module(moves, "moves")
+
+
+class Module_six_moves_urllib_parse(_LazyModule):
+
+    """Lazy loading of moved objects in six.moves.urllib_parse"""
+
+
+_urllib_parse_moved_attributes = [
+    MovedAttribute("ParseResult", "urlparse", "urllib.parse"),
+    MovedAttribute("SplitResult", "urlparse", "urllib.parse"),
+    MovedAttribute("parse_qs", "urlparse", "urllib.parse"),
+    MovedAttribute("parse_qsl", "urlparse", "urllib.parse"),
+    MovedAttribute("urldefrag", "urlparse", "urllib.parse"),
+    MovedAttribute("urljoin", "urlparse", "urllib.parse"),
+    MovedAttribute("urlparse", "urlparse", "urllib.parse"),
+    MovedAttribute("urlsplit", "urlparse", "urllib.parse"),
+    MovedAttribute("urlunparse", "urlparse", "urllib.parse"),
+    MovedAttribute("urlunsplit", "urlparse", "urllib.parse"),
+    MovedAttribute("quote", "urllib", "urllib.parse"),
+    MovedAttribute("quote_plus", "urllib", "urllib.parse"),
+    MovedAttribute("unquote", "urllib", "urllib.parse"),
+    MovedAttribute("unquote_plus", "urllib", "urllib.parse"),
+    MovedAttribute("unquote_to_bytes", "urllib", "urllib.parse", "unquote", "unquote_to_bytes"),
+    MovedAttribute("urlencode", "urllib", "urllib.parse"),
+    MovedAttribute("splitquery", "urllib", "urllib.parse"),
+    MovedAttribute("splittag", "urllib", "urllib.parse"),
+    MovedAttribute("splituser", "urllib", "urllib.parse"),
+    MovedAttribute("splitvalue", "urllib", "urllib.parse"),
+    MovedAttribute("uses_fragment", "urlparse", "urllib.parse"),
+    MovedAttribute("uses_netloc", "urlparse", "urllib.parse"),
+    MovedAttribute("uses_params", "urlparse", "urllib.parse"),
+    MovedAttribute("uses_query", "urlparse", "urllib.parse"),
+    MovedAttribute("uses_relative", "urlparse", "urllib.parse"),
+]
+for attr in _urllib_parse_moved_attributes:
+    setattr(Module_six_moves_urllib_parse, attr.name, attr)
+del attr
+
+Module_six_moves_urllib_parse._moved_attributes = _urllib_parse_moved_attributes
+
+_importer._add_module(Module_six_moves_urllib_parse(__name__ + ".moves.urllib_parse"),
+                      "moves.urllib_parse", "moves.urllib.parse")
+
+
+class Module_six_moves_urllib_error(_LazyModule):
+
+    """Lazy loading of moved objects in six.moves.urllib_error"""
+
+
+_urllib_error_moved_attributes = [
+    MovedAttribute("URLError", "urllib2", "urllib.error"),
+    MovedAttribute("HTTPError", "urllib2", "urllib.error"),
+    MovedAttribute("ContentTooShortError", "urllib", "urllib.error"),
+]
+for attr in _urllib_error_moved_attributes:
+    setattr(Module_six_moves_urllib_error, attr.name, attr)
+del attr
+
+Module_six_moves_urllib_error._moved_attributes = _urllib_error_moved_attributes
+
+_importer._add_module(Module_six_moves_urllib_error(__name__ + ".moves.urllib.error"),
+                      "moves.urllib_error", "moves.urllib.error")
+
+
+class Module_six_moves_urllib_request(_LazyModule):
+
+    """Lazy loading of moved objects in six.moves.urllib_request"""
+
+
+_urllib_request_moved_attributes = [
+    MovedAttribute("urlopen", "urllib2", "urllib.request"),
+    MovedAttribute("install_opener", "urllib2", "urllib.request"),
+    MovedAttribute("build_opener", "urllib2", "urllib.request"),
+    MovedAttribute("pathname2url", "urllib", "urllib.request"),
+    MovedAttribute("url2pathname", "urllib", "urllib.request"),
+    MovedAttribute("getproxies", "urllib", "urllib.request"),
+    MovedAttribute("Request", "urllib2", "urllib.request"),
+    MovedAttribute("OpenerDirector", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPDefaultErrorHandler", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPRedirectHandler", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPCookieProcessor", "urllib2", "urllib.request"),
+    MovedAttribute("ProxyHandler", "urllib2", "urllib.request"),
+    MovedAttribute("BaseHandler", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPPasswordMgr", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPPasswordMgrWithDefaultRealm", "urllib2", "urllib.request"),
+    MovedAttribute("AbstractBasicAuthHandler", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPBasicAuthHandler", "urllib2", "urllib.request"),
+    MovedAttribute("ProxyBasicAuthHandler", "urllib2", "urllib.request"),
+    MovedAttribute("AbstractDigestAuthHandler", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPDigestAuthHandler", "urllib2", "urllib.request"),
+    MovedAttribute("ProxyDigestAuthHandler", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPHandler", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPSHandler", "urllib2", "urllib.request"),
+    MovedAttribute("FileHandler", "urllib2", "urllib.request"),
+    MovedAttribute("FTPHandler", "urllib2", "urllib.request"),
+    MovedAttribute("CacheFTPHandler", "urllib2", "urllib.request"),
+    MovedAttribute("UnknownHandler", "urllib2", "urllib.request"),
+    MovedAttribute("HTTPErrorProcessor", "urllib2", "urllib.request"),
+    MovedAttribute("urlretrieve", "urllib", "urllib.request"),
+    MovedAttribute("urlcleanup", "urllib", "urllib.request"),
+    MovedAttribute("URLopener", "urllib", "urllib.request"),
+    MovedAttribute("FancyURLopener", "urllib", "urllib.request"),
+    MovedAttribute("proxy_bypass", "urllib", "urllib.request"),
+    MovedAttribute("parse_http_list", "urllib2", "urllib.request"),
+    MovedAttribute("parse_keqv_list", "urllib2", "urllib.request"),
+]
+for attr in _urllib_request_moved_attributes:
+    setattr(Module_six_moves_urllib_request, attr.name, attr)
+del attr
+
+Module_six_moves_urllib_request._moved_attributes = _urllib_request_moved_attributes
+
+_importer._add_module(Module_six_moves_urllib_request(__name__ + ".moves.urllib.request"),
+                      "moves.urllib_request", "moves.urllib.request")
+
+
+class Module_six_moves_urllib_response(_LazyModule):
+
+    """Lazy loading of moved objects in six.moves.urllib_response"""
+
+
+_urllib_response_moved_attributes = [
+    MovedAttribute("addbase", "urllib", "urllib.response"),
+    MovedAttribute("addclosehook", "urllib", "urllib.response"),
+    MovedAttribute("addinfo", "urllib", "urllib.response"),
+    MovedAttribute("addinfourl", "urllib", "urllib.response"),
+]
+for attr in _urllib_response_moved_attributes:
+    setattr(Module_six_moves_urllib_response, attr.name, attr)
+del attr
+
+Module_six_moves_urllib_response._moved_attributes = _urllib_response_moved_attributes
+
+_importer._add_module(Module_six_moves_urllib_response(__name__ + ".moves.urllib.response"),
+                      "moves.urllib_response", "moves.urllib.response")
+
+
+class Module_six_moves_urllib_robotparser(_LazyModule):
+
+    """Lazy loading of moved objects in six.moves.urllib_robotparser"""
+
+
+_urllib_robotparser_moved_attributes = [
+    MovedAttribute("RobotFileParser", "robotparser", "urllib.robotparser"),
+]
+for attr in _urllib_robotparser_moved_attributes:
+    setattr(Module_six_moves_urllib_robotparser, attr.name, attr)
+del attr
+
+Module_six_moves_urllib_robotparser._moved_attributes = _urllib_robotparser_moved_attributes
+
+_importer._add_module(Module_six_moves_urllib_robotparser(__name__ + ".moves.urllib.robotparser"),
+                      "moves.urllib_robotparser", "moves.urllib.robotparser")
+
+
+class Module_six_moves_urllib(types.ModuleType):
+
+    """Create a six.moves.urllib namespace that resembles the Python 3 namespace"""
+    __path__ = []  # mark as package
+    parse = _importer._get_module("moves.urllib_parse")
+    error = _importer._get_module("moves.urllib_error")
+    request = _importer._get_module("moves.urllib_request")
+    response = _importer._get_module("moves.urllib_response")
+    robotparser = _importer._get_module("moves.urllib_robotparser")
+
+    def __dir__(self):
+        return ['parse', 'error', 'request', 'response', 'robotparser']
+
+_importer._add_module(Module_six_moves_urllib(__name__ + ".moves.urllib"),
+                      "moves.urllib")
+
+
+def add_move(move):
+    """Add an item to six.moves."""
+    setattr(_MovedItems, move.name, move)
+
+
+def remove_move(name):
+    """Remove item from six.moves."""
+    try:
+        delattr(_MovedItems, name)
+    except AttributeError:
+        try:
+            del moves.__dict__[name]
+        except KeyError:
+            raise AttributeError("no such move, %r" % (name,))
+
+
+if PY3:
+    _meth_func = "__func__"
+    _meth_self = "__self__"
+
+    _func_closure = "__closure__"
+    _func_code = "__code__"
+    _func_defaults = "__defaults__"
+    _func_globals = "__globals__"
+else:
+    _meth_func = "im_func"
+    _meth_self = "im_self"
+
+    _func_closure = "func_closure"
+    _func_code = "func_code"
+    _func_defaults = "func_defaults"
+    _func_globals = "func_globals"
+
+
+try:
+    advance_iterator = next
+except NameError:
+    def advance_iterator(it):
+        return it.next()
+next = advance_iterator
+
+
+try:
+    callable = callable
+except NameError:
+    def callable(obj):
+        return any("__call__" in klass.__dict__ for klass in type(obj).__mro__)
+
+
+if PY3:
+    def get_unbound_function(unbound):
+        return unbound
+
+    create_bound_method = types.MethodType
+
+    def create_unbound_method(func, cls):
+        return func
+
+    Iterator = object
+else:
+    def get_unbound_function(unbound):
+        return unbound.im_func
+
+    def create_bound_method(func, obj):
+        return types.MethodType(func, obj, obj.__class__)
+
+    def create_unbound_method(func, cls):
+        return types.MethodType(func, None, cls)
+
+    class Iterator(object):
+
+        def next(self):
+            return type(self).__next__(self)
+
+    callable = callable
+_add_doc(get_unbound_function,
+         """Get the function out of a possibly unbound function""")
+
+
+get_method_function = operator.attrgetter(_meth_func)
+get_method_self = operator.attrgetter(_meth_self)
+get_function_closure = operator.attrgetter(_func_closure)
+get_function_code = operator.attrgetter(_func_code)
+get_function_defaults = operator.attrgetter(_func_defaults)
+get_function_globals = operator.attrgetter(_func_globals)
+
+
+if PY3:
+    def iterkeys(d, **kw):
+        return iter(d.keys(**kw))
+
+    def itervalues(d, **kw):
+        return iter(d.values(**kw))
+
+    def iteritems(d, **kw):
+        return iter(d.items(**kw))
+
+    def iterlists(d, **kw):
+        return iter(d.lists(**kw))
+
+    viewkeys = operator.methodcaller("keys")
+
+    viewvalues = operator.methodcaller("values")
+
+    viewitems = operator.methodcaller("items")
+else:
+    def iterkeys(d, **kw):
+        return d.iterkeys(**kw)
+
+    def itervalues(d, **kw):
+        return d.itervalues(**kw)
+
+    def iteritems(d, **kw):
+        return d.iteritems(**kw)
+
+    def iterlists(d, **kw):
+        return d.iterlists(**kw)
+
+    viewkeys = operator.methodcaller("viewkeys")
+
+    viewvalues = operator.methodcaller("viewvalues")
+
+    viewitems = operator.methodcaller("viewitems")
+
+_add_doc(iterkeys, "Return an iterator over the keys of a dictionary.")
+_add_doc(itervalues, "Return an iterator over the values of a dictionary.")
+_add_doc(iteritems,
+         "Return an iterator over the (key, value) pairs of a dictionary.")
+_add_doc(iterlists,
+         "Return an iterator over the (key, [values]) pairs of a dictionary.")
+
+
+if PY3:
+    def b(s):
+        return s.encode("latin-1")
+
+    def u(s):
+        return s
+    unichr = chr
+    import struct
+    int2byte = struct.Struct(">B").pack
+    del struct
+    byte2int = operator.itemgetter(0)
+    indexbytes = operator.getitem
+    iterbytes = iter
+    import io
+    StringIO = io.StringIO
+    BytesIO = io.BytesIO
+    del io
+    _assertCountEqual = "assertCountEqual"
+    if sys.version_info[1] <= 1:
+        _assertRaisesRegex = "assertRaisesRegexp"
+        _assertRegex = "assertRegexpMatches"
+        _assertNotRegex = "assertNotRegexpMatches"
+    else:
+        _assertRaisesRegex = "assertRaisesRegex"
+        _assertRegex = "assertRegex"
+        _assertNotRegex = "assertNotRegex"
+else:
+    def b(s):
+        return s
+    # Workaround for standalone backslash
+
+    def u(s):
+        return unicode(s.replace(r'\\', r'\\\\'), "unicode_escape")
+    unichr = unichr
+    int2byte = chr
+
+    def byte2int(bs):
+        return ord(bs[0])
+
+    def indexbytes(buf, i):
+        return ord(buf[i])
+    iterbytes = functools.partial(itertools.imap, ord)
+    import StringIO
+    StringIO = BytesIO = StringIO.StringIO
+    _assertCountEqual = "assertItemsEqual"
+    _assertRaisesRegex = "assertRaisesRegexp"
+    _assertRegex = "assertRegexpMatches"
+    _assertNotRegex = "assertNotRegexpMatches"
+_add_doc(b, """Byte literal""")
+_add_doc(u, """Text literal""")
+
+
+def assertCountEqual(self, *args, **kwargs):
+    return getattr(self, _assertCountEqual)(*args, **kwargs)
+
+
+def assertRaisesRegex(self, *args, **kwargs):
+    return getattr(self, _assertRaisesRegex)(*args, **kwargs)
+
+
+def assertRegex(self, *args, **kwargs):
+    return getattr(self, _assertRegex)(*args, **kwargs)
+
+
+def assertNotRegex(self, *args, **kwargs):
+    return getattr(self, _assertNotRegex)(*args, **kwargs)
+
+
+if PY3:
+    exec_ = getattr(moves.builtins, "exec")
+
+    def reraise(tp, value, tb=None):
+        try:
+            if value is None:
+                value = tp()
+            if value.__traceback__ is not tb:
+                raise value.with_traceback(tb)
+            raise value
+        finally:
+            value = None
+            tb = None
+
+else:
+    def exec_(_code_, _globs_=None, _locs_=None):
+        """Execute code in a namespace."""
+        if _globs_ is None:
+            frame = sys._getframe(1)
+            _globs_ = frame.f_globals
+            if _locs_ is None:
+                _locs_ = frame.f_locals
+            del frame
+        elif _locs_ is None:
+            _locs_ = _globs_
+        exec("""exec _code_ in _globs_, _locs_""")
+
+    exec_("""def reraise(tp, value, tb=None):
+    try:
+        raise tp, value, tb
+    finally:
+        tb = None
+""")
+
+
+if sys.version_info[:2] > (3,):
+    exec_("""def raise_from(value, from_value):
+    try:
+        raise value from from_value
+    finally:
+        value = None
+""")
+else:
+    def raise_from(value, from_value):
+        raise value
+
+
+print_ = getattr(moves.builtins, "print", None)
+if print_ is None:
+    def print_(*args, **kwargs):
+        """The new-style print function for Python 2.4 and 2.5."""
+        fp = kwargs.pop("file", sys.stdout)
+        if fp is None:
+            return
+
+        def write(data):
+            if not isinstance(data, basestring):
+                data = str(data)
+            # If the file has an encoding, encode unicode with it.
+            if (isinstance(fp, file) and
+                    isinstance(data, unicode) and
+                    fp.encoding is not None):
+                errors = getattr(fp, "errors", None)
+                if errors is None:
+                    errors = "strict"
+                data = data.encode(fp.encoding, errors)
+            fp.write(data)
+        want_unicode = False
+        sep = kwargs.pop("sep", None)
+        if sep is not None:
+            if isinstance(sep, unicode):
+                want_unicode = True
+            elif not isinstance(sep, str):
+                raise TypeError("sep must be None or a string")
+        end = kwargs.pop("end", None)
+        if end is not None:
+            if isinstance(end, unicode):
+                want_unicode = True
+            elif not isinstance(end, str):
+                raise TypeError("end must be None or a string")
+        if kwargs:
+            raise TypeError("invalid keyword arguments to print()")
+        if not want_unicode:
+            for arg in args:
+                if isinstance(arg, unicode):
+                    want_unicode = True
+                    break
+        if want_unicode:
+            newline = unicode("\n")
+            space = unicode(" ")
+        else:
+            newline = "\n"
+            space = " "
+        if sep is None:
+            sep = space
+        if end is None:
+            end = newline
+        for i, arg in enumerate(args):
+            if i:
+                write(sep)
+            write(arg)
+        write(end)
+if sys.version_info[:2] < (3, 3):
+    _print = print_
+
+    def print_(*args, **kwargs):
+        fp = kwargs.get("file", sys.stdout)
+        flush = kwargs.pop("flush", False)
+        _print(*args, **kwargs)
+        if flush and fp is not None:
+            fp.flush()
+
+_add_doc(reraise, """Reraise an exception.""")
+
+if sys.version_info[0:2] < (3, 4):
+    # This does exactly the same what the :func:`py3:functools.update_wrapper`
+    # function does on Python versions after 3.2. It sets the ``__wrapped__``
+    # attribute on ``wrapper`` object and it doesn't raise an error if any of
+    # the attributes mentioned in ``assigned`` and ``updated`` are missing on
+    # ``wrapped`` object.
+    def _update_wrapper(wrapper, wrapped,
+                        assigned=functools.WRAPPER_ASSIGNMENTS,
+                        updated=functools.WRAPPER_UPDATES):
+        for attr in assigned:
+            try:
+                value = getattr(wrapped, attr)
+            except AttributeError:
+                continue
+            else:
+                setattr(wrapper, attr, value)
+        for attr in updated:
+            getattr(wrapper, attr).update(getattr(wrapped, attr, {}))
+        wrapper.__wrapped__ = wrapped
+        return wrapper
+    _update_wrapper.__doc__ = functools.update_wrapper.__doc__
+
+    def wraps(wrapped, assigned=functools.WRAPPER_ASSIGNMENTS,
+              updated=functools.WRAPPER_UPDATES):
+        return functools.partial(_update_wrapper, wrapped=wrapped,
+                                 assigned=assigned, updated=updated)
+    wraps.__doc__ = functools.wraps.__doc__
+
+else:
+    wraps = functools.wraps
+
+
+def with_metaclass(meta, *bases):
+    """Create a base class with a metaclass."""
+    # This requires a bit of explanation: the basic idea is to make a dummy
+    # metaclass for one level of class instantiation that replaces itself with
+    # the actual metaclass.
+    class metaclass(type):
+
+        def __new__(cls, name, this_bases, d):
+            if sys.version_info[:2] >= (3, 7):
+                # This version introduced PEP 560 that requires a bit
+                # of extra care (we mimic what is done by __build_class__).
+                resolved_bases = types.resolve_bases(bases)
+                if resolved_bases is not bases:
+                    d['__orig_bases__'] = bases
+            else:
+                resolved_bases = bases
+            return meta(name, resolved_bases, d)
+
+        @classmethod
+        def __prepare__(cls, name, this_bases):
+            return meta.__prepare__(name, bases)
+    return type.__new__(metaclass, 'temporary_class', (), {})
+
+
+def add_metaclass(metaclass):
+    """Class decorator for creating a class with a metaclass."""
+    def wrapper(cls):
+        orig_vars = cls.__dict__.copy()
+        slots = orig_vars.get('__slots__')
+        if slots is not None:
+            if isinstance(slots, str):
+                slots = [slots]
+            for slots_var in slots:
+                orig_vars.pop(slots_var)
+        orig_vars.pop('__dict__', None)
+        orig_vars.pop('__weakref__', None)
+        if hasattr(cls, '__qualname__'):
+            orig_vars['__qualname__'] = cls.__qualname__
+        return metaclass(cls.__name__, cls.__bases__, orig_vars)
+    return wrapper
+
+
+def ensure_binary(s, encoding='utf-8', errors='strict'):
+    """Coerce **s** to six.binary_type.
+
+    For Python 2:
+      - `unicode` -> encoded to `str`
+      - `str` -> `str`
+
+    For Python 3:
+      - `str` -> encoded to `bytes`
+      - `bytes` -> `bytes`
+    """
+    if isinstance(s, binary_type):
+        return s
+    if isinstance(s, text_type):
+        return s.encode(encoding, errors)
+    raise TypeError("not expecting type '%s'" % type(s))
+
+
+def ensure_str(s, encoding='utf-8', errors='strict'):
+    """Coerce *s* to `str`.
+
+    For Python 2:
+      - `unicode` -> encoded to `str`
+      - `str` -> `str`
+
+    For Python 3:
+      - `str` -> `str`
+      - `bytes` -> decoded to `str`
+    """
+    # Optimization: Fast return for the common case.
+    if type(s) is str:
+        return s
+    if PY2 and isinstance(s, text_type):
+        return s.encode(encoding, errors)
+    elif PY3 and isinstance(s, binary_type):
+        return s.decode(encoding, errors)
+    elif not isinstance(s, (text_type, binary_type)):
+        raise TypeError("not expecting type '%s'" % type(s))
+    return s
+
+
+def ensure_text(s, encoding='utf-8', errors='strict'):
+    """Coerce *s* to six.text_type.
+
+    For Python 2:
+      - `unicode` -> `unicode`
+      - `str` -> `unicode`
+
+    For Python 3:
+      - `str` -> `str`
+      - `bytes` -> decoded to `str`
+    """
+    if isinstance(s, binary_type):
+        return s.decode(encoding, errors)
+    elif isinstance(s, text_type):
+        return s
+    else:
+        raise TypeError("not expecting type '%s'" % type(s))
+
+
+def python_2_unicode_compatible(klass):
+    """
+    A class decorator that defines __unicode__ and __str__ methods under Python 2.
+    Under Python 3 it does nothing.
+
+    To support Python 2 and 3 with a single code base, define a __str__ method
+    returning text and apply this decorator to the class.
+    """
+    if PY2:
+        if '__str__' not in klass.__dict__:
+            raise ValueError("@python_2_unicode_compatible cannot be applied "
+                             "to %s because it doesn't define __str__()." %
+                             klass.__name__)
+        klass.__unicode__ = klass.__str__
+        klass.__str__ = lambda self: self.__unicode__().encode('utf-8')
+    return klass
+
+
+# Complete the moves implementation.
+# This code is at the end of this module to speed up module loading.
+# Turn this module into a package.
+__path__ = []  # required for PEP 302 and PEP 451
+__package__ = __name__  # see PEP 366 @ReservedAssignment
+if globals().get("__spec__") is not None:
+    __spec__.submodule_search_locations = []  # PEP 451 @UndefinedVariable
+# Remove other six meta path importers, since they cause problems. This can
+# happen if six is removed from sys.modules and then reloaded. (Setuptools does
+# this for some reason.)
+if sys.meta_path:
+    for i, importer in enumerate(sys.meta_path):
+        # Here's some real nastiness: Another "instance" of the six module might
+        # be floating around. Therefore, we can't use isinstance() to check for
+        # the six meta path importer, since the other six instance will have
+        # inserted an importer with different class.
+        if (type(importer).__name__ == "_SixMetaPathImporter" and
+                importer.name == __name__):
+            del sys.meta_path[i]
+            break
+    del i, importer
+# Finally, add the importer to the meta path import hook.
+sys.meta_path.append(_importer)

docs/Makefile

@@ -0,0 +1,32 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@if [ $@ = "html" ]; then \
+		rm -rf html; \
+		rm -rf manual; \
+		cp -r build/html ./; \
+		mv html manual; \
+		echo "HTML Manual Generated"; \
+	fi
+
+	@if [ $@ = "latexpdf" ]; then \
+		cp -r build/latex/reticulumnetworkstack.pdf ./Reticulum\ Manual.pdf; \
+		echo "PDF Manual Generated"; \
+	fi

docs/index.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="refresh" content="0;URL='./manual/'" />
+  </head>
+  <body>
+  </body>
+</html>

docs/manual/.buildinfo

@@ -0,0 +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: 427f8d18d50a00634173570b6c54ba3a
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/manual/_sources/examples.rst.txt

@@ -0,0 +1,106 @@
+.. _examples-main:
+
+*************
+Code Examples
+*************
+
+A number of examples are included in the source distribution of Reticulum.
+You can use these examples to learn how to write your own programs.
+
+.. _example-minimal:
+
+Minimal
+=======
+
+The *Minimal* example demonstrates the bare-minimum setup required to connect to
+a Reticulum network from your program. In about five lines of code, you will
+have the Reticulum Network Stack initialised, and ready to pass traffic in your
+program.
+
+.. literalinclude:: ../../Examples/Minimal.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py>`_.
+
+.. _example-announce:
+
+Announce
+========
+
+The *Announce* example builds upon the previous example by exploring how to
+announce a destination on the network, and how to let your program receive
+notifications about announces from relevant destinations.
+
+.. literalinclude:: ../../Examples/Announce.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py>`_.
+
+.. _example-broadcast:
+
+Broadcast
+=========
+The *Broadcast* example explores how to transmit plaintext broadcast messages
+over the network.
+
+.. literalinclude:: ../../Examples/Broadcast.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py>`_.
+
+.. _example-echo:
+
+Echo
+====
+
+The *Echo* example demonstrates communication between two destinations using
+the Packet interface.
+
+.. literalinclude:: ../../Examples/Echo.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py>`_.
+
+.. _example-link:
+
+Link
+====
+
+The *Link* example explores establishing an encrypted link to a remote
+destination, and passing traffic back and forth over the link.
+
+.. literalinclude:: ../../Examples/Link.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py>`_.
+
+.. _example-identify:
+
+Identification
+==============
+
+The *Identify* example explores identifying an intiator of a link, once
+the link has been established.
+
+.. literalinclude:: ../../Examples/Identify.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Identify.py>`_.
+
+.. _example-request:
+
+Requests & Responses
+====================
+
+The *Request* example explores sendig requests and receiving responses.
+
+.. literalinclude:: ../../Examples/Request.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py>`_.
+
+.. _example-filetransfer:
+
+Filetransfer
+============
+
+The *Filetransfer* example implements a basic file-server program that
+allow clients to connect and download files. The program uses the Resource
+interface to efficiently pass files of any size over a Reticulum :ref:`Link<api-link>`.
+
+.. literalinclude:: ../../Examples/Filetransfer.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py>`_.

docs/manual/_sources/gettingstartedfast.rst.txt

@@ -0,0 +1,123 @@
+********************
+Getting Started Fast
+********************
+
+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.
+
+Try Using a Reticulum-based Program
+=============================================
+If you simply want to try using a program built with Reticulum, you can take
+a look at `Nomad Network <https://github.com/markqvist/nomadnet>`_, which
+provides a complete encrypted communications suite built with Reticulum.
+
+.. image:: screenshots/nomadnet_3.png
+    :target: _images/nomadnet_3.png
+
+`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
+in the development for the messaging and information-sharing protocol
+`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
+
+You can install Nomad Network via pip:
+
+.. code::
+
+   # Install ...
+   pip3 install nomadnet
+
+   # ... and run
+   nomadnet
+
+
+
+Using the Included Utilities
+=============================================
+Reticulum comes with a range of included utilities that make it easier to
+manage your network, check connectivity and make Reticulum available to other
+programs on your system.
+
+You can use ``rnsd`` to run Reticulum as a background or foreground service,
+and the ``rnstatus``, ``rnpath`` and ``rnprobe`` utilities to view and query
+network status and connectivity.
+
+To learn more about these utility programs, have a look at the
+:ref:`Using Reticulum on Your System<using-main>` chapter of this manual.
+
+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``.
+
+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 network (if there is one), and only allows you to
+communicate with other Reticulum peers within your local broadcast domain.
+
+To communicate further, you will have to add one or more interfaces. The default
+configuration includes a number of examples, ranging from using TCP over the
+internet, to LoRa and Packet Radio interfaces.
+
+Possibly, the examples in the config file are enough to get you started. If
+you want more information, you can read the :ref:`Building Networks<networks-main>`
+and :ref:`Interfaces<interfaces-main>` chapters of this manual.
+
+
+Develop a Program with Reticulum
+===========================================
+If you want to develop programs that use Reticulum, the easiest way to get
+started is to install the latest release of Reticulum via pip:
+
+.. code::
+
+   pip3 install rns
+
+The above command will install Reticulum and dependencies, and you will be
+ready to import and use RNS in your own programs. The next step will most
+likely be to look at some :ref:`Example Programs<examples-main>`.
+
+Further information can be found in the :ref:`API Reference<api-main>`.
+
+
+Participate in Reticulum Development
+==============================================
+If you want to participate in the development of Reticulum and associated
+utilities, you'll want to get the latest source from GitHub. In that case,
+don't use pip, but try this recipe:
+
+.. code::
+
+    # Install dependencies
+    pip3 install cryptography pyserial netifaces
+
+    # Clone repository
+    git clone https://github.com/markqvist/Reticulum.git
+
+    # Move into Reticulum folder and symlink library to examples folder
+    cd Reticulum
+    ln -s ../RNS ./Examples/
+
+    # Run an example
+    python3 Examples/Echo.py -s
+
+    # Unless you've manually created a config file, Reticulum will do so now,
+    # and immediately exit. Make any necessary changes to the file:
+    nano ~/.reticulum/config
+
+    # ... and launch the example again.
+    python3 Examples/Echo.py -s
+
+    # You can now repeat the process on another computer,
+    # and run the same example with -h to get command line options.
+    python3 Examples/Echo.py -h
+
+    # Run the example in client mode to "ping" the server.
+    # Replace the hash below with the actual destination hash of your server.
+    python3 Examples/Echo.py 3e12fc71692f8ec47bc5
+
+    # Have a look at another example
+    python3 Examples/Filetransfer.py -h
+
+When you have experimented with the basic examples, it's time to go read the
+:ref:`Understanding Reticulum<understanding-main>` chapter.

docs/manual/_sources/index.rst.txt

@@ -0,0 +1,25 @@
+******************************
+Reticulum Network Stack Manual
+******************************
+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.
+
+.. toctree::
+   :maxdepth: 3
+
+   whatis
+   gettingstartedfast
+   using
+   networks
+   interfaces
+   understanding
+   reference
+   examples
+
+
+Indices and Tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

docs/manual/_sources/interfaces.rst.txt

@@ -0,0 +1,346 @@
+
+.. _interfaces-main:
+
+********************
+Supported Interfaces
+********************
+
+Reticulum supports using many kinds of devices as networking interfaces, and
+allows you to mix and match them in any way you choose. The number of distinct
+network topologies you can create with Reticulum is more or less endless, but
+common to them all is that you will need to define one or more *interfaces*
+for Reticulum to use.
+
+The following sections describe the interfaces currently available in Reticulum,
+and gives example configurations for the respective interface types.
+
+For a high-level overview of how networks can be formed over different interface
+types, have a look at the :ref:`Building Networks<networks-main>` chapter of this
+manual.
+
+.. _interfaces-udp:
+
+UDP Interface
+=============
+
+A UDP interface can be useful for communicating over IP networks, both
+private and the internet. It can also allow broadcast communication
+over IP networks, so it can provide an easy way to enable connectivity
+with all other peers on a local area network.
+
+The below example is enabled by default on new Reticulum installations,
+as it provides an easy way to get started and to test Reticulum on a
+pre-existing LAN.
+
+.. code::
+
+  # This example enables communication with other
+  # local Reticulum peers over UDP.
+  
+  [[Default UDP Interface]]
+    type = UDPInterface
+    interface_enabled = True
+    outgoing = True
+    listen_ip = 0.0.0.0
+    listen_port = 4242
+    forward_ip = 255.255.255.255
+    forward_port = 4242
+
+    # The above configuration will allow communication
+    # within the local broadcast domains of all local
+    # IP interfaces. This is enabled by default as an
+    # easy way to get started, but you might want to
+    # consider altering it to something more specific.
+
+    # Instead of specifying listen_ip, listen_port,
+    # forward_ip and forward_port, you can also bind
+    # to a specific network device like below.
+
+    # device = eth0
+    # port = 4242
+
+    # Assuming the eth0 device has the address
+    # 10.55.0.72/24, the above configuration would
+    # be equivalent to the following manual setup.
+    # Note that we are both listening and forwarding to
+    # the broadcast address of the network segments.
+
+    # listen_ip = 10.55.0.255
+    # listen_port = 4242
+    # forward_ip = 10.55.0.255
+    # forward_port = 4242
+
+    # You can of course also communicate only with
+    # a single IP address
+
+    # listen_ip = 10.55.0.15
+    # listen_port = 4242
+    # forward_ip = 10.55.0.16
+    # forward_port = 4242
+
+.. _interfaces-tcps:
+
+TCP Server Interface
+====================
+
+The TCP Server interface is suitable for allowing other peers to connect over
+the Internet or private IP networks. When a TCP server interface has been
+configured, other Reticulum peers can connect to it with a TCP Client interface.
+
+.. code::
+
+  # This example demonstrates a TCP server interface.
+  # It will listen for incoming connections on the
+  # specified IP address and port number.
+  
+  [[TCP Server Interface]]
+    type = TCPServerInterface
+    interface_enabled = True
+    outgoing = True
+
+    # This configuration will listen on all IP
+    # interfaces on port 4242
+    
+    listen_ip = 0.0.0.0
+    listen_port = 4242
+
+    # Alternatively you can bind to a specific IP
+    
+    # listen_ip = 10.0.0.88
+    # listen_port = 4242
+
+    # Or a specific network device
+    
+    # device = eth0
+    # port = 4242
+
+
+.. _interfaces-tcpc:
+
+TCP Client Interface
+====================
+
+To connect to a TCP server interface, you would naturally use the TCP client
+interface. Many TCP Client interfaces from different peers can connect to the
+same TCP Server interface at the same time.
+
+.. code::
+
+  # Here's an example of a TCP Client interface. The
+  # target_host can either be an IP address or a hostname.
+
+  [[TCP Client Interface]]
+    type = TCPClientInterface
+    interface_enabled = True
+    outgoing = True
+    target_host = 127.0.0.1
+    target_port = 4242
+
+
+.. _interfaces-rnode:
+
+RNode LoRa Interface
+====================
+
+To use Reticulum over LoRa, the `RNode <https://unsigned.io/rnode/>`_ interface
+can be used, and offers full control over LoRa parameters.
+
+.. code::
+
+  # Here's an example of how to add a LoRa interface
+  # using the RNode LoRa transceiver.
+
+  [[RNode LoRa Interface]]
+    type = RNodeInterface
+
+    # Enable interface if you want use it!
+    interface_enabled = True
+
+    # Allow transmit on interface. Setting
+    # this to false will create a listen-
+    # only interface.
+    outgoing = true
+
+    # Serial port for the device
+    port = /dev/ttyUSB0
+
+    # Set frequency to 867.2 MHz
+    frequency = 867200000
+
+    # Set LoRa bandwidth to 125 KHz
+    bandwidth = 125000
+
+    # Set TX power to 7 dBm (5 mW)
+    txpower = 7
+
+    # Select spreading factor 8. Valid 
+    # range is 7 through 12, with 7
+    # being the fastest and 12 having
+    # the longest range.
+    spreadingfactor = 8
+
+    # Select coding rate 5. Valid range
+    # is 5 throough 8, with 5 being the
+    # fastest, and 8 the longest range.
+    codingrate = 5
+
+    # You can configure the RNode to send
+    # out identification on the channel with
+    # a set interval by configuring the
+    # following two parameters.
+    # id_callsign = MYCALL-0
+    # id_interval = 600
+
+    # For certain homebrew RNode interfaces
+    # with low amounts of RAM, using packet
+    # flow control can be useful. By default
+    # it is disabled.
+    flow_control = False
+
+.. _interfaces-serial:
+
+Serial Interface
+================
+
+Reticulum can be used over serial ports directly, or over any device with a
+serial port, that will transparently pass data. Useful for communicating
+directly over a wire-pair, or for using devices such as data radios and lasers.
+
+.. code::
+
+  [[Serial Interface]]
+    type = SerialInterface
+    interface_enabled = True
+    outgoing = True
+
+    # Serial port for the device
+    port = /dev/ttyUSB0
+
+    # Set the serial baud-rate and other
+    # configuration parameters.
+    speed = 115200
+    databits = 8
+    parity = none
+    stopbits = 1
+
+.. _interfaces-kiss:
+
+KISS Interface
+==============
+
+With the KISS interface, you can use Reticulum over a variety of packet
+radio modems and TNCs, including `OpenModem <https://unsigned.io/openmodem/>`_.
+KISS interfaces can also be configured to periodically send out beacons
+for station identification purposes.
+
+.. code::
+
+  [[Packet Radio KISS Interface]]
+    type = KISSInterface
+    interface_enabled = True
+    outgoing = true
+
+    # Serial port for the device
+    port = /dev/ttyUSB1
+
+    # Set the serial baud-rate and other
+    # configuration parameters.
+    speed = 115200    
+    databits = 8
+    parity = none
+    stopbits = 1
+
+    # Set the modem preamble.
+    preamble = 150
+
+    # Set the modem TX tail.
+    txtail = 10
+
+    # Configure CDMA parameters. These
+    # settings are reasonable defaults.
+    persistence = 200
+    slottime = 20
+
+    # You can configure the interface to send
+    # out identification on the channel with
+    # a set interval by configuring the
+    # following two parameters. The KISS
+    # interface will only ID if the set
+    # interval has elapsed since it's last
+    # actual transmission. The interval is
+    # configured in seconds.
+    # This option is commented out and not
+    # used by default.
+    # id_callsign = MYCALL-0
+    # id_interval = 600
+
+    # Whether to use KISS flow-control.
+    # This is useful for modems that have
+    # a small internal packet buffer, but
+    # support packet flow control instead.
+    flow_control = false
+
+.. _interfaces-ax25:
+
+AX.25 KISS Interface
+====================
+
+If you're using Reticulum on amateur radio spectrum, you might want to
+use the AX.25 KISS interface. This way, Reticulum will automatically
+encapsulate it's traffic in AX.25 and also identify your stations
+transmissions with your callsign and SSID. 
+
+Only do this if you really need to! Reticulum doesn't need the AX.25
+layer for anything, and it incurs extra overhead on every packet to
+encapsulate in AX.25.
+
+A more efficient way is to use the plain KISS interface with the
+beaconing functionality described above.
+
+.. code::
+
+  [[Packet Radio AX.25 KISS Interface]]
+    type = AX25KISSInterface
+
+    # Set the station callsign and SSID
+    callsign = NO1CLL
+    ssid = 0
+
+    # Enable interface if you want use it!
+    interface_enabled = True
+
+    # Allow transmit on interface.
+    outgoing = True
+
+    # Serial port for the device
+    port = /dev/ttyUSB2
+
+    # Set the serial baud-rate and other
+    # configuration parameters.
+    speed = 115200    
+    databits = 8
+    parity = none
+    stopbits = 1
+
+    # Set the modem preamble. A 150ms
+    # preamble should be a reasonable
+    # default, but may need to be
+    # increased for radios with slow-
+    # opening squelch and long TX/RX
+    # turnaround
+    preamble = 150
+
+    # Set the modem TX tail. In most
+    # cases this should be kept as low
+    # as possible to not waste airtime.
+    txtail = 10
+
+    # Configure CDMA parameters. These
+    # settings are reasonable defaults.
+    persistence = 200
+    slottime = 20
+
+    # Whether to use KISS flow-control.
+    # This is useful for modems with a
+    # small internal packet buffer.
+    flow_control = false

docs/manual/_sources/networks.rst.txt

@@ -0,0 +1,150 @@
+.. _networks-main:
+
+*****************
+Building Networks
+*****************
+
+This chapter will provide you with the knowledge needed to build networks with
+Reticulum, which can often be easier than using traditional stacks, since you
+don't have to worry about coordinating addresses, subnets and routing for an
+entire network that you might not know how will evolve in the future. With
+Reticulum, you can simply add more segments to your network when it becomes
+necesarry, and Reticulum will handle the convergence of the entire network
+automatically.
+
+Concepts & Overview
+--------------------
+
+There are important points that need to be kept in mind when building networks
+with Reticulum:
+
+ * | In a Reticulum network, any node can autonomously generate as many adresses
+     (called *destinations* in Reticulum terminology) as it needs, which become
+     globally reachable to the rest of the network. There is no central point of
+     control over the adress space.
+
+ * | Reticulum was designed to handle both very small, and very large networks.
+     While the adress space can support billions of endpoints, Reticulum is
+     also very useful when just a few devices needs to communicate.
+
+ * | Reticulum provides sender/initiator anonymity by default. There is no way
+     to filter traffic or discriminate it based on the source of the traffic.
+
+ * | All traffic is encrypted using ephemeral keys generated by an Elliptic Curve
+     Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic
+     contents, and no way to prioritise or throttle certain kinds of traffic.
+     All transport and routing layers are thus completely agnostic to traffic type,
+     and will pass all traffic equally.
+
+ * | Reticulum can function both with and without infrastructure. When *transport
+     nodes* are available, they can route traffic over multiple hops for other
+     nodes, and will function as a distributed cryptographic keystore. When there
+     is no transport nodes available, all nodes that are within communication range
+     can still communicate.
+
+ * | Every node can become a transport node, simply by enabling it in it's
+     configuration, but there is no need for every node on the network to be a
+     transport node. Letting every node be a transport node will in most cases
+     degrade the performance and reliability of the network.
+
+     In general terms, if a node is stationary, well-connected and kept running
+     most of the time, it is a good candidate to be a transport node. For optimal
+     performance, a network should contain the amount of transport nodes that
+     provides connectivity to the intended area / topography, and not many more
+     than that. 
+
+
+Reticulum allows you to mix very different kinds of networking mediums into a
+unified mesh, or to keep everything within one medium. You could build a "virtual
+network" running entirely over the Internet, where all nodes communicate over TCP
+and UDP "channels". You could also build such a network using MQTT or ZeroMQ as
+the underlying carrier for Reticulum.
+
+However, most real-world networks will probably involve either some form of
+wireless or direct hardline communications. To allow Reticulum to communicate
+over any type of medium, you must specify it in the configuration file, by default
+located at ``~/.reticulum/config``. See the :ref:`Supported Interfaces<interfaces-main>`
+chapter of this manual for interface configuration examples.
+
+Any number of interfaces can be configured, and Reticulum will automatically
+decide which are suitable to use in any given situation, depending on where
+traffic needs to flow.
+
+Example Scenarios
+-----------------
+
+This section illustrates a few example scenarios, and how they would, in general
+terms, be planned, implemented and configured.
+
+Interconnected LoRa Sites
+=========================
+
+An organisation wants to provide communication and information services to it's
+members, which are located mainly in three separate areas. Three suitable hill-top
+locations are found, where the organisation can install equipment: Site A, B and C.
+
+Since the amount of data that needs to be exchanged between users is mainly text-
+based, the bandwidth requirements are low, and LoRa radios are chosen to connect
+users to the network.
+
+Due to the hill-top locations found, there is radio line-of-sight between site A
+and B, and also between site B and C. Because of this, the organisation does not
+need to use the Internet to interconnect the sites, but purchases four Point-to-Point
+WiFi based radios for interconnecting the sites.
+
+At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio
+is connected to the Pi with a USB cable, and the WiFi radio is connected to the
+ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach
+both site A and site C, so an extra ethernet adapter is connected to the Pi in
+this location.
+
+Once the hardware has been installed, Reticulum is installed on all the Pis, and at
+site A and C, one interface is added for the LoRa radio, as well as one for the WiFi
+radio. At site B, an interface for the LoRa radio, and one interface for each WiFi
+radio is added to the Reticulum configuration file. The transport node option is
+enabled in the configuration of all three gateways.
+
+The network is now operational, and ready to serve users across all three areas.
+The organisation prepares a LoRa radio that is supplied to the end users, along
+with a Reticulum configuration file, that contains the right parameters for
+communicating with the LoRa radios installed at the gateway sites.
+
+Once users connect to the network, anyone will be able to communicate with anyone
+else across all three sites.
+
+Bridging Over the Internet
+==========================
+
+As the organisation grows, several new communities form in places too far away
+from the core network to be reachable over WiFi links. New gateways similar to those
+previously installed are set up for the new communities at the new sites D and E, but
+they are islanded from the core network, and only serve the local users.
+
+After investigating the options, it is found that it is possible to install an
+Internet connection at site A, and an interface on the Internet connection is
+configured for Reticulum on the Raspberry Pi at site A.
+
+A member of the organisation at site D, named Dori, is willing to help by sharing
+the Internet connection she already has in her home, and is able to leave a Raspberry
+Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly
+enabled Internet interface on the gateway at site A. Dori is now connected to both
+all the nodes at her own local site (through the hill-top LoRa gateway), and all the
+combined users of sites A, B and C. She then enables transport on her node, and
+traffic from site D can now reach everyone at site A, B and C, and vice versa.
+
+Growth and Convergence
+======================
+
+As the organisation grows, more gateways are added to keep up with the growing user
+base. Some local gateways even add VHF radios and packet modems to reach outlying users
+and communities that are out of reach for the LoRa radios and WiFi backhauls.
+
+As more sites, gateways and users are connected, the amount of coordination required
+is kept to a minimum. If one community wants to add connectivity to the next one
+over, it can simply be done without having to involve everyone or coordinate address
+space or routing tables.
+
+With the added geographical coverage, the operators at site A one day find that
+the original internet bridged interfaces are no longer utilised. The network has
+converged to be completely self-connected, and the sites that were once poorly
+connected outliers are now an integral part of the network.

docs/manual/_sources/reference.rst.txt

@@ -0,0 +1,83 @@
+.. _api-main:
+
+*************
+API Reference
+*************
+This reference guide lists and explains all classes exposed by the RNS API.
+
+Classes
+=========================
+Communication over a Reticulum network is achieved using a set of classes exposed by RNS.
+
+.. _api-reticulum:
+
+Reticulum
+---------
+
+.. autoclass:: RNS.Reticulum
+   :members:
+
+
+.. _api-identity:
+
+Identity
+--------
+
+.. autoclass:: RNS.Identity
+   :members:
+
+.. _api-destination:
+
+Destination
+-----------
+
+.. autoclass:: RNS.Destination
+   :members:
+
+.. _api-packet:
+
+Packet
+------
+
+.. autoclass:: RNS.Packet(destination, data, create_receipt = True)
+   :members:
+
+.. _api-packetreceipt:
+
+Packet Receipt
+--------------
+
+.. autoclass:: RNS.PacketReceipt()
+   :members:
+
+.. _api-link:
+
+Link
+----
+
+.. autoclass:: RNS.Link(destination, established_callback=None, closed_callback = None)
+   :members:
+
+.. _api-requestreceipt:
+
+Request Receipt
+---------------
+
+.. autoclass:: RNS.RequestReceipt()
+   :members:
+
+.. _api-resource:
+
+Resource
+--------
+
+.. autoclass:: RNS.Resource(data, link, advertise=True, auto_compress=True, callback=None, progress_callback=None, timeout=None)
+   :members:
+
+.. _api-transport:
+
+Transport
+---------
+
+.. autoclass:: RNS.Transport
+   :members:

docs/manual/_sources/understanding.rst.txt

@@ -0,0 +1,705 @@
+.. _understanding-main:
+
+***********************
+Understanding Reticulum
+***********************
+This chapter will briefly describe the overall purpose and operating principles of Reticulum, a
+networking stack designed for reliable and secure communication over high-latency, low-bandwidth
+links. It should give you an overview of how the stack works, and an understanding of how to
+develop networked applications using Reticulum.
+
+This document is not an exhaustive source of information on Reticulum, at least not yet. Currently,
+the best place to go for such information is the Python reference implementation of Reticulum, along
+with the code examples and API reference. It is however an essential resource to understanding the
+general principles of Reticulum, how to apply them when creating your own networks or software.
+
+After reading this document, you should be well-equipped to understand how a Reticulum network
+operates, what it can achieve, and how you can use it yourself. If you want to help out with the
+development, this is also the place to start, since it will provide a pretty clear overview of the
+sentiments and the philosophy behind Reticulum.
+
+.. _understanding-motivation:
+
+Motivation
+==========
+
+The primary motivation for designing and implementing Reticulum has been the current lack of
+reliable, functional and secure minimal-infrastructure modes of digital communication. It is my
+belief that it is highly desirable to create a cheap and reliable way to set up a wide-range digital
+communication network that can securely allow exchange of information between people and
+machines, with no central point of authority, control, censorship or barrier to entry.
+
+Almost all of the various networking systems in use today share a common limitation, namely that they
+require large amounts of coordination and trust to work, and to join the networks you need approval
+of gatekeepers in control. This need for coordination and trust inevitably leads to an environment of
+central control, where it's very easy for infrastructure operators or governments to control or alter
+traffic, and censor or persecute unwanted actors.
+
+Reticulum aims to require as little coordination and trust as possible. In fact, the only
+“coordination” required is to know the characteristics of physical medium carrying Reticulum traffic.
+
+Since Reticulum is completely medium agnostic, this could be whatever is best suited to the situation.
+In some cases, this might be 1200 baud packet radio links over VHF frequencies, in other cases it might
+be a microwave network using off-the-shelf radios. At the time of release of this document, the
+recommended setup for development and testing is using LoRa radio modules with an open source firmware
+(see the section :ref:`Reference System Setup<understanding-referencesystem>`), connected to a small
+computer like a Raspberry Pi. As an example, the default reference setup provides a channel capacity
+of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (indefinitely extendable
+by using multiple hops).
+
+.. _understanding-goals:
+
+Goals
+=====
+
+To be as widely usable and easy to use as possible, the following goals have been used to
+guide the design of Reticulum:
+
+
+* **Fully useable as open source software stack**
+    Reticulum must be implemented with, and be able to run using only open source software. This is
+    critical to ensuring the availability, security and transparency of the system.
+* **Hardware layer agnosticism**
+    Reticulum shall be fully hardware agnostic, and shall be useable over a wide range
+    physical networking layers, such as data radios, serial lines, modems, handheld transceivers,
+    wired ethernet, wifi, or anything else that can carry a digital data stream. Hardware made for
+    dedicated Reticulum use shall be as cheap as possible and use off-the-shelf components, so
+    it can be easily replicated.
+* **Very low bandwidth requirements**
+    Reticulum should be able to function reliably over links with a transmission capacity as low
+    as *1,000 bps*.
+* **Encryption by default**
+    Reticulum must use encryption by default where possible and applicable.
+* **Unlicensed use**
+    Reticulum shall be functional over physical communication mediums that do not require any
+    form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio
+    frequency bands, and can provide functional long distance links in such conditions, for example
+    by connecting a modem to a PMR or CB radio, or by using LoRa or WiFi modules.
+* **Supplied software**
+    Apart from the core networking stack and API, that allows a developer to build
+    applications with Reticulum, a basic communication suite using Reticulum must be
+    implemented and released at the same time as Reticulum itself. This shall serve both as a
+    functional communication suite, and as an example and learning resource to others wishing
+    to build applications with Reticulum.
+* **Ease of use**
+    The reference implementation of Reticulum is written in Python, to make it easy to use
+    and understand. A programmer with only basic experience should be able to use
+    Reticulum in their own applications.
+* **Low cost**
+    It shall be as cheap as possible to deploy a communication system based on Reticulum. This
+    should be achieved by using cheap off-the-shelf hardware that potential users might already
+    own. The cost of setting up a functioning node should be less than $100 even if all parts
+    needs to be purchased.
+
+.. _understanding-basicfunctionality:
+
+Introduction & Basic Functionality
+==================================
+
+Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
+core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint
+scenarios where alle nodes are within range of each other, as well as scenarios where packets need
+to be transported over multiple hops 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
+networking stack will need to create one or more destinations to receive data, and know the
+destinations it needs to send data to.
+
+All destinations in Reticulum are represented internally as 10 bytes, derived from truncating a full
+SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
+will be displayed as 10 bytes in hexadecimal representation, as in the following example: ``<80e29bf7cccaf31431b3>``.
+
+By default Reticulum encrypts all data using public-key cryptography. Any message sent to a
+destination is encrypted with that destinations public key. Reticulum can also set up an encrypted
+channel to a destination with *Perfect Forward Secrecy* and *Initiator Anonymity* using a elliptic
+curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In
+Reticulum terminology, this is called a *Link*.
+
+Reticulum also offers symmetric key encryption for group-oriented communications, as well as
+unencrypted packets for broadcast purposes, or situations where you need the communication to be in
+plain text. The multi-hop transport, coordination, verification and reliability layers are fully
+autonomous and based on public key cryptography.
+
+Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
+and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
+private IP networks.
+
+.. _understanding-destinations:
+
+Destinations
+------------
+
+To receive and send data with the Reticulum stack, an application needs to create one or more
+destinations. Reticulum uses three different basic destination types, and one special:
+
+
+* **Single**
+    The *single* destination type defines a public-key encrypted destination. Any data sent to this
+    destination will be encrypted with the destination’s public key, and will only be readable by
+    the creator of the destination.
+* **Group**
+    The *group* destination type defines a symmetrically encrypted destination. Data sent to this
+    destination will be encrypted with a symmetric key, and will be readable by anyone in
+    possession of the key. The *group* destination can be used just as well by only two peers, as it
+    can by many.
+* **Plain**
+    A *plain* destination type is unencrypted, and suited for traffic that should be broadcast to a
+    number of users, or should be readable by anyone. Traffic to a *plain* destination is not encrypted.
+* **Link**
+    A *link* is a special destination type, that serves as an abstract channel to a *single*
+    destination, directly connected or over multiple hops. The *link* also offers reliability and
+    more efficient encryption, forward secrecy, initiator anonymity, and as such can be useful even
+    when a node is directly reachable.
+
+.. _understanding-destinationnaming:
+
+Destination Naming
+^^^^^^^^^^^^^^^^^^
+
+Destinations are created and named in an easy to understand dotted notation of *aspects*, and
+represented on the network as a hash of this value. The hash is a SHA-256 truncated to 80 bits. The
+top level aspect should always be a unique identifier for the application using the destination.
+The next levels of aspects can be defined in any way by the creator of the application.
+
+Aspects can be as long and as plentiful as required, and a resulting long destination name will not
+impact efficiency, as names are always represented as truncated SHA-256 hashes on the network.
+
+As an example, a destination for a environmental monitoring application could be made up of the
+application name, a device type and measurement type, like this:
+
+.. code-block:: text
+
+   app name  : environmentlogger
+   aspects   : remotesensor, temperature
+
+   full name : environmentlogger.remotesensor.temperature
+   hash      : fa7ddfab5213f916dea
+
+For the *single* destination, Reticulum will automatically append the associated public key as a
+destination aspect before hashing. This is done to ensure only the correct destination is reached,
+since anyone can listen to any destination name. Appending the public key ensures that a given
+packet is only directed at the destination that holds the corresponding private key to decrypt the
+packet.
+
+**Take note!** There is a very important concept to understand here:
+
+* Anyone can use the destination name ``environmentlogger.remotesensor.temperature``
+
+* Each destination that does so will still have a unique destination hash, and thus be uniquely
+  addressable, because their public keys will differ.
+
+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 acheived by the appending the public key,
+which expands the destination into a uniquely identifyable one.
+
+Any destination on a Reticulum network can be addressed and reached simply by knowning its
+destination hash (and public key, but if the public key is not known, it can be requested from the
+network simply by knowing the destination hash). The use of app names and aspects makes it easy to
+structure Reticulum programs and makes it possible to filter what information and data your program
+receives.
+
+To recap, the different destination types should be used in the following situations:
+
+* **Single**
+    When private communication between two endpoints is needed. Supports multiple hops.
+* **Group**
+    When private communication between two or more endpoints is needed. Supports multiple hops
+    indirectly, but must first be established through a *single* destination.
+* **Plain**
+    When plain-text communication is desirable, for example when broadcasting information.
+
+To communicate with a *single* destination, you need to know it’s 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 participating nodes serve as a distributed ledger
+of public keys.
+
+Note that public key information can be shared and verified in many other ways than using the
+built-in *announce* functionality, and that it is therefore not required to use the announce/request
+functionality to obtain public keys. It is by far the easiest though, and should definitely be used
+if there is not a good reason for doing it differently.
+
+.. _understanding-keyannouncements:
+
+Public Key Announcements
+------------------------
+
+An *announce* will send a special packet over any configured interfaces, containing all needed
+information about the destination hash and public key, and can also contain some additional,
+application specific data. The entire packet is signed by the sender to ensure authenticity. It is not
+required to use the announce functionality, but in many cases it will be the simplest way to share
+public keys on the network. As an example, an announce in a simple messenger application might
+contain the following information:
+
+
+* The announcers destination hash
+* The announcers public key
+* Application specific data, in this case the users nickname and availability status
+* A random blob, making each new announce unique
+* An Ed25519 signature of the above information, verifying authenticity
+
+With this information, any Reticulum node that receives it will be able to reconstruct an outgoing
+destination to securely communicate with that destination. You might have noticed that there is one
+piece of information lacking to reconstruct full knowledge of the announced destination, and that is
+the aspect names of the destination. These are intentionally left out to save bandwidth, since they
+will be implicit in almost all cases. If a destination name is not entirely implicit, information can be
+included in the application specific data part that will allow the receiver to infer the naming.
+
+It is important to note that announces will be forwarded throughout the network according to a
+certain pattern. This will be detailed in the section
+:ref:`The Announce Mechanism in Detail<understanding-announce>`.
+
+Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic.
+
+.. _understanding-identities:
+
+Identities
+----------
+
+In Reticulum, an *identity* does not necessarily represent a personal identity, but is an abstraction that
+can represent any kind of *verified entity*. This could very well be a person, but it could also be the
+control interface of a machine, a program, robot, computer, sensor or something else entirely. In
+general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be
+represented as an identity.
+
+As we have seen, a *single* destination will always have an *identity* tied to it, but not *plain* or *group*
+destinations. Destinations and identities share a multilateral connection. You can create a
+destination, and if it is not connected to an identity upon creation, it will just create a new one to use
+automatically. This may be desirable in some situations, but often you will probably want to create
+the identity first, and then link it to created destinations.
+
+Building upon the simple messenger example, we could use an identity to represent the user of the
+application. Destinations created will then be linked to this identity to allow communication to
+reach the user. In all cases it is of great importance to store the private keys associated with any
+Reticulum Identity securely and privately.
+
+.. _understanding-gettingfurther:
+
+Getting Further
+---------------
+
+The above functions and principles form the core of Reticulum, and would suffice to create
+functional networked applications in local clusters, for example over radio links where all interested
+nodes can directly hear each other. But to be truly useful, we need a way to direct traffic over multiple
+hops in the network.
+
+In the following sections, two concepts that allow this will be introduced, *paths* and *links*.
+
+.. _understanding-transport:
+
+Reticulum Transport
+===================
+
+The term routing has been purposefully avoided until now. The current methods of routing used in IP-based
+networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle.
+These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than
+Reticulum can assume is available.
+
+Since Reticulum is designed to run over open radio spectrum, no such trust exists, and bandwidth is often
+very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
+useable over bandwidth-limited, high-latency links.
+
+To overcome such challenges, Reticulum’s *Transport* system uses public-key cryptography to
+implement the concept of *paths* that allow discovery of how to get information to a certain
+destination. It is important to note that no single node in a Reticulum network knows the complete
+path to a destination. Every Transport node participating in a Reticulum network will only
+know what the most direct way to get a packet one hop closer to it's destination is.
+
+.. _understanding-announce:
+
+The Announce Mechanism in Detail
+--------------------------------
+
+When an *announce* is transmitted by a node, it will be forwarded by any node receiving it, but
+according to some specific rules:
+
+
+* | If this exact announce has already been received before, ignore it.
+
+* | If not, record into a table which node the announce was received from, and how many times in
+    total it has been retransmitted to get here.
+
+* | If the announce has been retransmitted *m+1* times, it will not be forwarded. By default, *m* is
+    set to 18.
+
+* | The announce will be assigned a delay *d* = c\ :sup:`h` seconds, where *c* is a decay constant, and *h* is the amount of times this packet has already been forwarded.
+
+* | The packet will be given a priority *p = 1/d*.
+
+* | If at least *d* seconds has passed since the announce was received, and no other packets with a
+    priority higher than *p* are waiting in the queue (see Packet Prioritisation), and the channel is
+    not utilized by other traffic, the announce will be forwarded.
+
+* | If no other nodes are heard retransmitting the announce with a greater hop count than when
+    it left this node, transmitting it will be retried *r* times. By default, *r* is set to 1. Retries
+    follow same rules as above, with the exception that it must wait for at least *d* = c\ :sup:`h+1` +
+    t + rand(0, rw) seconds. This amount of time is equal to the amount of time it would take the next
+    node to retransmit the packet, plus a random window. By default, *t* is set to 10 seconds, and the
+    random window *rw* is set to 10 seconds.
+
+* | If a newer announce from the same destination arrives, while an identical one is already in
+    the queue, the newest announce is discarded. If the newest announce contains different
+    application specific data, it will replace the old announce, but will use *d* and *p* of the old
+    announce.
+
+Once an announce has reached a node in the network, any other node in direct contact with that
+node will be able to reach the destination the announce originated from, simply by sending a packet
+addressed to that destination. Any node with knowledge of the announce will be able to direct the
+packet towards the destination by looking up the next node with the shortest amount of hops to the
+destination.
+
+According to these rules and default constants, an announce will propagate throughout the network
+in a predictable way. In an example network utilising the default constants, and with an average link
+distance of *Lavg =* 15 kilometers, an announce will be able to propagate outwards to a radius of 180
+kilometers in 34 minutes, and a *maximum announce radius* of 270 kilometers in approximately 3
+days.
+
+.. _understanding-paths:
+
+Reaching the Destination
+------------------------
+
+In networks with changing topology and trustless connectivity, nodes need a way to establish
+*verified connectivity* with each other. Since the network is assumed to be trustless, Reticulum
+must provide a way to guarantee that the peer you are communicating with is actually who you
+expect. Reticulum offers two ways to do this.
+
+For exchanges of small amounts of information, Reticulum offers the *Packet* API, which works exactly like you would expect - on a per packet level. The following process is employed when sending a packet:
+
+* | 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.
+
+* | 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
+    key exchange locally, before sending the packet.
+
+* | The public part of the newly generated ephemeral key-pair is included with the encrypted token, and sent
+    along with the encrypted payload data in the packet.
+
+* | When the destination receives the packet, it can itself perform an ECDH key exchange and decrypt the
+    packet.
+
+* | A new ephemeral key is used for every packet sent in this way, and forward secrecy is guaranteed on a
+    per packet level.
+
+* | 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
+    public signing key.
+
+* | In case the packet is addressed to a *group* destination type, the packet will be encrypted with the
+    pre-shared AES-128 key associated with the destination. In case the packet is addressed to a *plain*
+    destination type, the payload data will not be encrypted. Neither of these two destination types offer
+    forward secrecy. In general, it is recommended to always use the *single* destination type, unless it is
+    strictly necessary to use one of the others.
+
+
+For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the *Link* API. To establish a *link*, the following process is employed:
+
+* | First, the node that wishes to establish a link will send out a special packet, that
+    traverses the network and locates the desired destination. Along the way, the nodes that
+    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
+    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.
+
+* | When the validity of the *link* has been accepted by forwarding nodes, these nodes will
+    remember the *link* , and it can subsequently be used by referring to a hash representing it.
+
+* | As a part of the *link request* , a Diffie-Hellman key exchange takes place, that sets up an
+    efficiently encrypted tunnel between the two nodes, using elliptic curve cryptography. As such,
+    this mode of communication is preferred, even for situations when nodes can directly communicate,
+    when the amount of data to be exchanged numbers in the tens of packets.
+
+* | When a *link* has been set up, it automatically provides message receipt functionality, through
+    the same *proof* mechanism discussed before, so the sending node can obtain verified confirmation
+    that the information reached the intended recipient.
+
+In a moment, we will discuss the details of how this methodology is implemented, but let’s first
+recap what purposes this methodology serves. We first ensure that the node answering our request
+is actually the one we want to communicate with, and not a malicious actor pretending to be so.
+At the same time we establish an efficient encrypted channel. The setup of this is relatively cheap in
+terms of bandwidth, so it can be used just for a short exchange, and then recreated as needed, which will
+also rotate encryption keys. The link can also be kept alive for longer periods of time, if this is
+more suitable to the application. The procedure also inserts the *link id* , a hash calculated from the link request packet, into the memory of forwarding nodes, which means that the communicating nodes can thereafter reach each other simply by referring to this *link id*.
+
+The combined bandwidth cost of setting up a link is 3 packets totalling 237 bytes (more info in the
+:ref:`Binary Packet Format<understanding-packetformat>` section). The amount of bandwidth used on keeping
+a link open is practically negligible, at 0.62 bits per second. Even on a slow 1200 bits per second packet
+radio channel, 100 concurrent links will still leave 95% channel capacity for actual data.
+
+
+Link Establishment in Detail
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After exploring the basics of the announce mechanism, finding a path through the network, and an overview
+of the link establishment procedure, this section will go into greater detail about the Reticulum link
+establishment process.
+
+The *link* in Reticulum terminology should not be viewed as a direct node-to-node link on the
+physical layer, but as an abstract channel, that can be open for any amount of time, and can span
+an arbitrary number of hops, where information will be exchanged between two nodes.
+
+
+* | When a node in the network wants to establish verified connectivity with another node, it
+    will randomly generate a new X25519 private/public key pair. It then creates a *link request*
+    packet, and broadcast it.
+  |  
+  | *It should be noted that the X25519 public/private keypair mentioned above is two separate keypairs:
+    An encryption key pair, used for derivation of a shared symmetric key, and a signing key pair, used
+    for signing and verifying messages on the link. They are sent together over the wire, and can be
+    considered as single public key for simplicity in this explanation.*
+
+* | The *link request* is addressed to the destination hash of the desired destination, and
+    contains the following data: The newly generated X25519 public key *LKi*.
+
+* | The broadcasted packet will be directed through the network according to the rules laid out
+    previously.
+
+* | Any node that forwards the link request will store a *link id* in it’s *link table* , along with the
+    amount of hops the packet had taken when received. The link id is a hash of the entire link
+    request packet. If the link request packet is not *proven* by the addressed destination within some
+    set amount of time, the entry will be dropped from the *link table* again.
+
+* | When the destination receives the link request packet, it will decide whether to accept the request.
+    If it is accepted, the destination will also generate a new X25519 private/public key pair, and
+    perform a Diffie Hellman Key Exchange, deriving a new symmetric key that will be used to encrypt the
+    channel, once it has been established.
+
+* | A *link proof* packet is now constructed and transmitted over the network. This packet is
+    addressed to the *link id* of the *link*. It contains the following data: The newly generated X25519
+    public key *LKr* and an Ed25519 signature of the *link id* and *LKr* made by the signing key of
+    the addressed destination.
+   
+* | By verifying this *link proof* packet, all nodes that originally transported the *link request*
+    packet to the destination from the originator can now verify that the intended destination received
+    the request and accepted it, and that the path they chose for forwarding the request was valid.
+    In sucessfully carrying out this verification, the transporting nodes marks the link as active.
+    An abstract bi-directional communication channel has now been established along a path in the network.
+
+* | When the source receives the *proof* , it will know unequivocally that a verified path has been
+    established to the destination. It can now also use the X25519 public key contained in the
+    *link proof* to perform it's own Diffie Hellman Key Exchange and derive the symmetric key
+    that is used to encrypt the channel. Information can now be exchanged reliably and securely.
+
+
+It’s important to note that this methodology ensures that the source of the request does not need to
+reveal any identifying information about itself. The link initiator remains completely anonymous.
+
+When using *links*, Reticulum will automatically verify all data sent over the link, and can also
+automate retransmissions if *Resources* are used.
+
+.. _understanding-resources:
+
+Resources
+---------
+
+For exchanging small amounts of data over a Reticulum network, the :ref:`Packet<api-packet>` interface
+is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate
+the transfer is needed.
+
+This is the purpose of the Reticulum :ref:`Resource<api-resource>`. A *Resource* can automatically
+handle the reliable transfer of an arbitrary amount of data over an established :ref:`Link<api-link>`.
+Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
+the transfer and reassembling the data on the other end.
+
+:ref:`Resources<api-resource>` are programmatically very simple to use, and only requires a few lines
+of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
+or stream data directly from files.
+
+.. _understanding-referencesystem:
+
+Reference System Setup
+======================
+
+This section will detail the recommended *Reference System Setup* for Reticulum. It is important to
+note that Reticulum is designed to be usable over more or less any medium that allows you to send
+and receive data in a digital form, and satisfies some very low minimum requirements. The
+communication channel must support at least half-duplex operation, and provide an average
+throughput of around 1000 bits per second, and supports a physical layer MTU of 500 bytes. The
+Reticulum software should be able to run on more or less any hardware that can provide a Python 3.x 
+runtime environment.
+
+That being said, the reference setup has been outlined to provide a common platform for anyone
+who wants to help in the development of Reticulum, and for everyone who wants to know a
+recommended setup to get started. A reference system consists of three parts:
+
+* **A channel access device**
+    Or *CAD* , in short, provides access to the physical medium whereupon the communication
+    takes place, for example a radio with an integrated modem. A setup with a separate modem
+    connected to a radio would also be termed a “channel access device”.
+* **A host device**
+    Some sort of computing device that can run the necessary software, communicates with the
+    channel access device, and provides user interaction.
+* **A software stack**
+    The software implementing the Reticulum protocol and applications using it.
+
+The reference setup can be considered a relatively stable platform to develop on, and also to start
+building networks on. While details of the implementation might change at the current stage of
+development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
+the current reference setup has been determined to provide a functional platform for many years
+into the future. The current Reference System Setup is as follows:
+
+
+* **Channel Access Device**
+    A data radio consisting of a LoRa radio module, and a microcontroller with open source
+    firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
+    MHz frequency bands. More details can be found on the `RNode Page <https://unsigned.io/rnode>`_.
+* **Host device**
+    Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
+    recommended.
+* **Software stack**
+    The current Reference Implementation Release of Reticulum, running on a Debian based
+    operating system.
+
+It is very important to note, that the reference channel access device **does not** use the LoRaWAN
+standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
+need a plain LoRa radio module connected to an MCU with the correct firmware. Full details on how to
+get or make such a device is available on the `RNode Page <https://unsigned.io/rnode>`_.
+
+With the current reference setup, it should be possible to get on a Reticulum network for around 100$
+even if you have none of the hardware already, and need to purchase everything.
+
+.. _understanding-protocolspecifics:
+
+Protocol Specifics
+==================
+
+This chapter will detail protocol specific information that is essential to the implementation of
+Reticulum, but non critical in understanding how the protocol works on a general level. It should be
+treated more as a reference than as essential reading.
+
+
+Node Types
+----------
+
+Currently Reticulum defines two node types, the *Station* and the *Peer*. A node is a *station* if it fixed
+in one place, and if it is intended to be kept online most of the time. Otherwise the node is a *peer*.
+This distinction is made by the user configuring the node, and is used to determine what nodes on the
+network will help forward traffic, and what nodes rely on other nodes for connectivity.
+
+If a node is a *Peer* it should be given the configuration directive ``enable_transport = No``.
+
+If it is a *Station*, it should be given the configuration directive ``enable_transport = Yes``.
+
+
+Packet Prioritisation
+---------------------
+
+Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
+on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
+times and priorities described earlier in this chapter.
+
+It is possible that a prioritisation engine could be added to Reticulum in the future, but in
+the light of Reticulums goal of equal access, doing so would need to be the subject of careful
+investigation of the consequences first.
+
+
+.. _understanding-packetformat:
+
+Binary Packet Format
+--------------------
+
+.. code-block:: text
+
+    == Reticulum Wire Format ======
+
+    A Reticulum packet is composed of the following fields:
+
+    [HEADER 2 bytes] [ADDRESSES 10/20 bytes] [CONTEXT 1 byte] [DATA 0-477 bytes]
+
+    * The HEADER field is 2 bytes long.
+      * Byte 1: [Header Type], [Propagation Type], [Destination Type] and [Packet Type]
+      * Byte 2: Number of hops
+
+    * The ADDRESSES field contains either 1 or 2 addresses.
+      * Each address is 10 bytes long.
+      * The Header Type flag in the HEADER field determines
+        whether the ADDRESSES field contains 1 or 2 addresses.
+      * Addresses are Reticulum hashes truncated to 10 bytes.
+
+    * The CONTEXT field is 1 byte.
+      * It is used by Reticulum to determine packet context.
+
+    * The DATA field is between 0 and 477 bytes.
+      * It contains the packets data payload.
+
+    Header Types
+    -----------------
+    type 1          00  Two byte header, one 10 byte address field
+    type 2          01  Two byte header, two 10 byte address fields
+    type 3          10  Reserved
+    type 4          11  Reserved
+
+
+    Propagation Types
+    -----------------
+    broadcast       00
+    transport       01
+    reserved        10
+    reserved        11
+
+
+    Destination Types
+    -----------------
+    single          00
+    group           01
+    plain           10
+    link            11
+
+
+    Packet Types
+    -----------------
+    data            00
+    announce        01
+    link request    10
+    proof           11
+
+
+    +- Packet Example -+
+
+       HEADER FIELD             ADDRESSES FIELD             CONTEXT FIELD  DATA FIELD
+     _______|_______   ________________|________________   ________|______   __|_
+    |               | |                                 | |               | |    |
+    01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
+     | | | |    |
+     | | | |    +-- Hops             = 4
+     | | | +------- Packet Type      = DATA
+     | | +--------- Destination Type = SINGLE
+     | +----------- Propagation Type = TRANSPORT
+     +------------- Header Type      = HEADER_2 (two byte header, two address fields)
+
+
+     +- Packet Example -+
+
+       HEADER FIELD    ADDRESSES FIELD    CONTEXT FIELD  DATA FIELD
+     _______|_______   _______|_______   ________|______   __|_
+    |               | |               | |               | |    |
+    00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]
+     | | | |    |
+     | | | |    +-- Hops             = 7
+     | | | +------- Packet Type      = DATA
+     | | +--------- Destination Type = SINGLE
+     | +----------- Propagation Type = BROADCAST
+     +------------- Header Type      = HEADER_1 (two byte header, one address field)
+
+
+     Size examples of different packet types
+     ---------------------------------------
+
+     The following table lists example sizes of various
+     packet types. The size listed are the complete on-
+     wire size including all fields.
+
+     - Path Request    :    33  bytes
+     - Announce        :    151 bytes
+     - Link Request    :    77  bytes
+     - Link Proof      :    77  bytes
+     - Link RTT packet :    83  bytes
+     - Link keepalive  :    14  bytes

docs/manual/_sources/using.rst.txt

@@ -0,0 +1,165 @@
+.. _using-main:
+
+******************************
+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.
+This means that no special privileges are required to install or use it.
+Any program or application that uses Reticulum will automatically load and
+initialise Reticulum when it starts.
+
+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 Reticulum. 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 concurrently, and is
+very easy to use, but depending on your use case, there are other options.
+
+Included Utility Programs
+-------------------------
+
+If you often use Reticulum from several different programs, or simply want
+Reticulum to stay available all the time, for example if you are hosting
+a transport node, you might want to run Reticulum as a separate service that
+other programs, applications and services can utilise.
+
+The rnsd Utility
+================
+
+To do so is very easy. Simply run the included ``rnsd`` command. When ``rnsd``
+is running, it will keep all configured interfaces open, handle transport if
+it is enabled, and allow any other programs to immediately utilise the
+Reticulum network it is configured for.
+
+You can even run multiple instances of rnsd with different configurations on
+the same system.
+
+.. code:: text
+
+  # Install Reticulum
+  pip3 install rns
+
+  # Run rnsd
+  rnsd
+
+.. code:: text
+
+  usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version]
+
+  Reticulum Network Stack Daemon
+
+  optional arguments:
+    -h, --help       show this help message and exit
+    --config CONFIG  path to alternative Reticulum config directory
+    -v, --verbose
+    -q, --quiet
+    --version        show program's version number and exit
+
+
+The rnstatus Utility
+====================
+
+Using the ``rnstatus`` utility, you can view the status of configured Reticulum
+interfaces, similar to the ``ifconfig`` program.
+
+.. code:: text
+
+  # Run rnstatus
+  rnstatus
+
+  # Example output
+  Shared Instance[37428]
+         Status: Up
+         Connected applications: 1
+         RX: 1.13 KB
+         TX: 1.07 KB
+
+  UDPInterface[Default UDP Interface/0.0.0.0:4242]
+         Status: Up
+         RX: 1.01 KB
+         TX: 1.01 KB
+
+  TCPInterface[RNS Testnet Frankfurt/frankfurt.rns.unsigned.io:4965]
+         Status: Up
+         RX: 1.37 KB
+         TX: 9.02 KB
+
+.. code:: text
+
+  usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version]
+
+  Reticulum Network Stack Daemon
+
+  optional arguments:
+    -h, --help       show this help message and exit
+    --config CONFIG  path to alternative Reticulum config directory
+    -v, --verbose
+    -q, --quiet
+    --version        show program's version number and exit
+
+
+The rnpath Utility
+====================
+
+With the ``rnpath`` utility, you can look up and view paths for
+destinations on the Reticulum network.
+
+.. code:: text
+
+  # Run rnpath
+  rnpath eca6f4e4dc26ae329e61
+
+  # Example output
+  Path found, destination <eca6f4e4dc26ae329e61> is 4 hops away via <56b115c30cd386cad69c> on TCPInterface[Testnet/frankfurt.rns.unsigned.io:4965]
+
+.. code:: text
+
+  usage: rnpath.py [-h] [--config CONFIG] [--version] [-v] [destination]
+
+  Reticulum Path Discovery Utility
+
+  positional arguments:
+    destination      hexadecimal hash of the destination
+
+  optional arguments:
+    -h, --help       show this help message and exit
+    --config CONFIG  path to alternative Reticulum config directory
+    --version        show program's version number and exit
+    -v, --verbose
+
+
+The rnprobe Utility
+====================
+
+The ``rnprobe`` utility lets you probe a destination for connectivity, similar
+to the ``ping`` program. Please note that probes will only be answered if the
+specified destination is configured to send proofs for received packets. Many
+destinations will not have this option enabled, and will not be probable.
+
+.. code:: text
+
+  # Run rnprobe
+  python3 -m RNS.Utilities.rnprobe example_utilities.echo.request 9382f334de63217a4278
+
+  # Example output
+  Sent 16 byte probe to <9382f334de63217a4278>
+  Valid reply received from <9382f334de63217a4278>
+  Round-trip time is 38.469 milliseconds over 2 hops
+
+.. code:: text
+
+  usage: rnprobe.py [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash]
+
+  Reticulum Probe Utility
+
+  positional arguments:
+    full_name         full destination name in dotted notation
+    destination_hash  hexadecimal hash of the destination
+
+  optional arguments:
+    -h, --help        show this help message and exit
+    --config CONFIG   path to alternative Reticulum config directory
+    --version         show program's version number and exit
+    -v, --verbose

docs/manual/_sources/whatis.rst.txt

@@ -0,0 +1,108 @@
+******************
+What is Reticulum?
+******************
+
+Reticulum is a cryptography-based networking stack for wide-area networks built on readily available hardware, and can operate even with very high latency and extremely low bandwidth.
+
+Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more.
+
+Reticulum is a complete networking stack, and does not need IP or higher layers, although it is easy to utilise IP (with TCP or UDP) as the underlying carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks. Reticulum is built directly on cryptographic principles, allowing resilience and stable functionality in open and trustless networks.
+
+No kernel modules or drivers are required. Reticulum runs completely in userland, and can run on practically any system that runs Python 3. Reticulum runs well even on small single-board computers like the Pi Zero.
+
+
+Current Status
+==============
+Reticulum should currently be considered beta software. All core protocol 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.
+
+
+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 privacy-breaking bugs. To be considered secure, Reticulum needs a thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch.
+
+
+What does Reticulum Offer?
+==========================
+* Coordination-less globally unique adressing and identification
+
+* Fully self-configuring multi-hop routing
+
+* Complete initiator anonymity, communicate without revealing your identity
+
+* Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
+
+* Forward Secrecy with ephemereal Elliptic Curve Diffie-Hellman keys on Curve25519
+
+* Reticulum uses the `Fernet <https://github.com/fernet/spec/blob/master/Spec.md>`_ specification for on-the-wire / over-the-air encryption
+
+  * All keys are ephemeral and derived from an ECDH key exchange on Curve25519
+
+  * AES-128 in CBC mode with PKCS7 padding
+
+  * HMAC using SHA256 for authentication
+
+  * IVs are generated through os.urandom()
+
+* Unforgeable packet delivery confirmations
+
+* A variety of supported interface types
+
+* An intuitive and developer-friendly API
+
+* Reliable and efficient transfer of arbritrary amounts of data
+
+  * Reticulum can handle a few bytes of data or files of many gigabytes
+
+  * Sequencing, transfer coordination and checksumming is automatic
+
+  * The API is very easy to use, and provides transfer progress
+
+* Efficient link establishment
+
+  * Total bandwidth cost of setting up a link is only 3 packets, totalling 237 bytes
+
+  * Low cost of keeping links open at only 0.62 bits per second
+
+
+Where can Reticulum be Used?
+============================
+Over practically any medium that can support at least a half-duplex channel
+with 500 bits per second throughput, and an MTU of 500 bytes. Data radios,
+modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes,
+ad-hoc WiFi, free-space optical links and similar systems are all examples
+of the types of interfaces Reticulum was designed for.
+
+An open-source LoRa-based interface called `RNode <https://unsigned.io/rnode>`_
+has been designed specifically for use with Reticulum. It is possible to build
+yourself, or it can be purchased as a complete transceiver that just needs a
+USB connection to the host.
+
+Reticulum can also be encapsulated over existing IP networks, so there's
+nothing stopping you from using it over wired ethernet or your local WiFi
+network, where it'll work just as well. In fact, one of the strengths of
+Reticulum is how easily it allows you to connect different mediums into a
+self-configuring, resilient and encrypted mesh.
+
+As an example, it's possible to set up a Raspberry Pi connected to both a
+LoRa radio, a packet radio TNC and a WiFi network. Once the interfaces are
+configured, Reticulum will take care of the rest, and any device on the WiFi
+network can communicate with nodes on the LoRa and packet radio sides of the
+network, and vice versa.
+
+Interface Types and Devices
+===========================
+Reticulum implements a range of generalised interface types that covers most of the communications hardware that Reticulum can run over. If your hardware is not supported, it's relatively simple to implement an interface class. Currently, the following interfaces are supported:
+
+* Any ethernet device
+
+* LoRa using `RNode <https://unsigned.io/rnode>`_
+
+* Packet Radio TNCs, such as `OpenModem <https://unsigned.io/openmodem>`_
+
+* Any device with a serial port
+
+* TCP over IP networks
+
+* UDP over IP networks
+
+For a full list and more details, see the :ref:`Supported Interfaces<interfaces-main>` chapter.

docs/manual/_static/basic.css

@@ -0,0 +1,904 @@
+/*
+ * basic.css
+ * ~~~~~~~~~
+ *
+ * Sphinx stylesheet -- basic theme.
+ *
+ * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/* -- main layout ----------------------------------------------------------- */
+
+div.clearer {
+    clear: both;
+}
+
+div.section::after {
+    display: block;
+    content: '';
+    clear: left;
+}
+
+/* -- relbar ---------------------------------------------------------------- */
+
+div.related {
+    width: 100%;
+    font-size: 90%;
+}
+
+div.related h3 {
+    display: none;
+}
+
+div.related ul {
+    margin: 0;
+    padding: 0 0 0 10px;
+    list-style: none;
+}
+
+div.related li {
+    display: inline;
+}
+
+div.related li.right {
+    float: right;
+    margin-right: 5px;
+}
+
+/* -- sidebar --------------------------------------------------------------- */
+
+div.sphinxsidebarwrapper {
+    padding: 10px 5px 0 10px;
+}
+
+div.sphinxsidebar {
+    float: left;
+    width: 230px;
+    margin-left: -100%;
+    font-size: 90%;
+    word-wrap: break-word;
+    overflow-wrap : break-word;
+}
+
+div.sphinxsidebar ul {
+    list-style: none;
+}
+
+div.sphinxsidebar ul ul,
+div.sphinxsidebar ul.want-points {
+    margin-left: 20px;
+    list-style: square;
+}
+
+div.sphinxsidebar ul ul {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+div.sphinxsidebar form {
+    margin-top: 10px;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #98dbcc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+div.sphinxsidebar #searchbox form.search {
+    overflow: hidden;
+}
+
+div.sphinxsidebar #searchbox input[type="text"] {
+    float: left;
+    width: 80%;
+    padding: 0.25em;
+    box-sizing: border-box;
+}
+
+div.sphinxsidebar #searchbox input[type="submit"] {
+    float: left;
+    width: 20%;
+    border-left: none;
+    padding: 0.25em;
+    box-sizing: border-box;
+}
+
+
+img {
+    border: 0;
+    max-width: 100%;
+}
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+    margin: 10px 0 0 20px;
+    padding: 0;
+}
+
+ul.search li {
+    padding: 5px 0 5px 20px;
+    background-image: url(file.png);
+    background-repeat: no-repeat;
+    background-position: 0 7px;
+}
+
+ul.search li a {
+    font-weight: bold;
+}
+
+ul.search li p.context {
+    color: #888;
+    margin: 2px 0 0 30px;
+    text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+    font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+    width: 90%;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+table.contentstable p.biglink {
+    line-height: 150%;
+}
+
+a.biglink {
+    font-size: 1.3em;
+}
+
+span.linkdescr {
+    font-style: italic;
+    padding-top: 5px;
+    font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable {
+    width: 100%;
+}
+
+table.indextable td {
+    text-align: left;
+    vertical-align: top;
+}
+
+table.indextable ul {
+    margin-top: 0;
+    margin-bottom: 0;
+    list-style-type: none;
+}
+
+table.indextable > tbody > tr > td > ul {
+    padding-left: 0em;
+}
+
+table.indextable tr.pcap {
+    height: 10px;
+}
+
+table.indextable tr.cap {
+    margin-top: 10px;
+    background-color: #f2f2f2;
+}
+
+img.toggler {
+    margin-right: 3px;
+    margin-top: 3px;
+    cursor: pointer;
+}
+
+div.modindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
+div.genindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
+/* -- domain module index --------------------------------------------------- */
+
+table.modindextable td {
+    padding: 2px;
+    border-collapse: collapse;
+}
+
+/* -- general body styles --------------------------------------------------- */
+
+div.body {
+    min-width: 450px;
+    max-width: 800px;
+}
+
+div.body p, div.body dd, div.body li, div.body blockquote {
+    -moz-hyphens: auto;
+    -ms-hyphens: auto;
+    -webkit-hyphens: auto;
+    hyphens: auto;
+}
+
+a.headerlink {
+    visibility: hidden;
+}
+
+a.brackets:before,
+span.brackets > a:before{
+    content: "[";
+}
+
+a.brackets:after,
+span.brackets > a:after {
+    content: "]";
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink,
+caption:hover > a.headerlink,
+p.caption:hover > a.headerlink,
+div.code-block-caption:hover > a.headerlink {
+    visibility: visible;
+}
+
+div.body p.caption {
+    text-align: inherit;
+}
+
+div.body td {
+    text-align: left;
+}
+
+.first {
+    margin-top: 0 !important;
+}
+
+p.rubric {
+    margin-top: 30px;
+    font-weight: bold;
+}
+
+img.align-left, figure.align-left, .figure.align-left, object.align-left {
+    clear: left;
+    float: left;
+    margin-right: 1em;
+}
+
+img.align-right, figure.align-right, .figure.align-right, object.align-right {
+    clear: right;
+    float: right;
+    margin-left: 1em;
+}
+
+img.align-center, figure.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+img.align-default, figure.align-default, .figure.align-default {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+    text-align: left;
+}
+
+.align-center {
+    text-align: center;
+}
+
+.align-default {
+    text-align: center;
+}
+
+.align-right {
+    text-align: right;
+}
+
+/* -- sidebars -------------------------------------------------------------- */
+
+div.sidebar,
+aside.sidebar {
+    margin: 0 0 0.5em 1em;
+    border: 1px solid #ddb;
+    padding: 7px;
+    background-color: #ffe;
+    width: 40%;
+    float: right;
+    clear: right;
+    overflow-x: auto;
+}
+
+p.sidebar-title {
+    font-weight: bold;
+}
+
+div.admonition, div.topic, blockquote {
+    clear: left;
+}
+
+/* -- topics ---------------------------------------------------------------- */
+
+div.topic {
+    border: 1px solid #ccc;
+    padding: 7px;
+    margin: 10px 0 10px 0;
+}
+
+p.topic-title {
+    font-size: 1.1em;
+    font-weight: bold;
+    margin-top: 10px;
+}
+
+/* -- admonitions ----------------------------------------------------------- */
+
+div.admonition {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    padding: 7px;
+}
+
+div.admonition dt {
+    font-weight: bold;
+}
+
+p.admonition-title {
+    margin: 0px 10px 5px 0px;
+    font-weight: bold;
+}
+
+div.body p.centered {
+    text-align: center;
+    margin-top: 25px;
+}
+
+/* -- content of sidebars/topics/admonitions -------------------------------- */
+
+div.sidebar > :last-child,
+aside.sidebar > :last-child,
+div.topic > :last-child,
+div.admonition > :last-child {
+    margin-bottom: 0;
+}
+
+div.sidebar::after,
+aside.sidebar::after,
+div.topic::after,
+div.admonition::after,
+blockquote::after {
+    display: block;
+    content: '';
+    clear: both;
+}
+
+/* -- tables ---------------------------------------------------------------- */
+
+table.docutils {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    border: 0;
+    border-collapse: collapse;
+}
+
+table.align-center {
+    margin-left: auto;
+    margin-right: auto;
+}
+
+table.align-default {
+    margin-left: auto;
+    margin-right: auto;
+}
+
+table caption span.caption-number {
+    font-style: italic;
+}
+
+table caption span.caption-text {
+}
+
+table.docutils td, table.docutils th {
+    padding: 1px 8px 1px 5px;
+    border-top: 0;
+    border-left: 0;
+    border-right: 0;
+    border-bottom: 1px solid #aaa;
+}
+
+table.footnote td, table.footnote th {
+    border: 0 !important;
+}
+
+th {
+    text-align: left;
+    padding-right: 5px;
+}
+
+table.citation {
+    border-left: solid 1px gray;
+    margin-left: 1px;
+}
+
+table.citation td {
+    border-bottom: none;
+}
+
+th > :first-child,
+td > :first-child {
+    margin-top: 0px;
+}
+
+th > :last-child,
+td > :last-child {
+    margin-bottom: 0px;
+}
+
+/* -- figures --------------------------------------------------------------- */
+
+div.figure, figure {
+    margin: 0.5em;
+    padding: 0.5em;
+}
+
+div.figure p.caption, figcaption {
+    padding: 0.3em;
+}
+
+div.figure p.caption span.caption-number,
+figcaption span.caption-number {
+    font-style: italic;
+}
+
+div.figure p.caption span.caption-text,
+figcaption span.caption-text {
+}
+
+/* -- field list styles ----------------------------------------------------- */
+
+table.field-list td, table.field-list th {
+    border: 0 !important;
+}
+
+.field-list ul {
+    margin: 0;
+    padding-left: 1em;
+}
+
+.field-list p {
+    margin: 0;
+}
+
+.field-name {
+    -moz-hyphens: manual;
+    -ms-hyphens: manual;
+    -webkit-hyphens: manual;
+    hyphens: manual;
+}
+
+/* -- hlist styles ---------------------------------------------------------- */
+
+table.hlist {
+    margin: 1em 0;
+}
+
+table.hlist td {
+    vertical-align: top;
+}
+
+/* -- object description styles --------------------------------------------- */
+
+.sig {
+	font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+}
+
+.sig-name, code.descname {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+.sig-name {
+	font-size: 1.1em;
+}
+
+code.descname {
+    font-size: 1.2em;
+}
+
+.sig-prename, code.descclassname {
+    background-color: transparent;
+}
+
+.optional {
+    font-size: 1.3em;
+}
+
+.sig-paren {
+    font-size: larger;
+}
+
+.sig-param.n {
+	font-style: italic;
+}
+
+/* C++ specific styling */
+
+.sig-inline.c-texpr,
+.sig-inline.cpp-texpr {
+	font-family: unset;
+}
+
+.sig.c   .k, .sig.c   .kt,
+.sig.cpp .k, .sig.cpp .kt {
+	color: #0033B3;
+}
+
+.sig.c   .m,
+.sig.cpp .m {
+	color: #1750EB;
+}
+
+.sig.c   .s, .sig.c   .sc,
+.sig.cpp .s, .sig.cpp .sc {
+	color: #067D17;
+}
+
+
+/* -- other body styles ----------------------------------------------------- */
+
+ol.arabic {
+    list-style: decimal;
+}
+
+ol.loweralpha {
+    list-style: lower-alpha;
+}
+
+ol.upperalpha {
+    list-style: upper-alpha;
+}
+
+ol.lowerroman {
+    list-style: lower-roman;
+}
+
+ol.upperroman {
+    list-style: upper-roman;
+}
+
+:not(li) > ol > li:first-child > :first-child,
+:not(li) > ul > li:first-child > :first-child {
+    margin-top: 0px;
+}
+
+:not(li) > ol > li:last-child > :last-child,
+:not(li) > ul > li:last-child > :last-child {
+    margin-bottom: 0px;
+}
+
+ol.simple ol p,
+ol.simple ul p,
+ul.simple ol p,
+ul.simple ul p {
+    margin-top: 0;
+}
+
+ol.simple > li:not(:first-child) > p,
+ul.simple > li:not(:first-child) > p {
+    margin-top: 0;
+}
+
+ol.simple p,
+ul.simple p {
+    margin-bottom: 0;
+}
+
+dl.footnote > dt,
+dl.citation > dt {
+    float: left;
+    margin-right: 0.5em;
+}
+
+dl.footnote > dd,
+dl.citation > dd {
+    margin-bottom: 0em;
+}
+
+dl.footnote > dd:after,
+dl.citation > dd:after {
+    content: "";
+    clear: both;
+}
+
+dl.field-list {
+    display: grid;
+    grid-template-columns: fit-content(30%) auto;
+}
+
+dl.field-list > dt {
+    font-weight: bold;
+    word-break: break-word;
+    padding-left: 0.5em;
+    padding-right: 5px;
+}
+
+dl.field-list > dt:after {
+    content: ":";
+}
+
+dl.field-list > dd {
+    padding-left: 0.5em;
+    margin-top: 0em;
+    margin-left: 0em;
+    margin-bottom: 0em;
+}
+
+dl {
+    margin-bottom: 15px;
+}
+
+dd > :first-child {
+    margin-top: 0px;
+}
+
+dd ul, dd table {
+    margin-bottom: 10px;
+}
+
+dd {
+    margin-top: 3px;
+    margin-bottom: 10px;
+    margin-left: 30px;
+}
+
+dl > dd:last-child,
+dl > dd:last-child > :last-child {
+    margin-bottom: 0;
+}
+
+dt:target, span.highlighted {
+    background-color: #fbe54e;
+}
+
+rect.highlighted {
+    fill: #fbe54e;
+}
+
+dl.glossary dt {
+    font-weight: bold;
+    font-size: 1.1em;
+}
+
+.versionmodified {
+    font-style: italic;
+}
+
+.system-message {
+    background-color: #fda;
+    padding: 5px;
+    border: 3px solid red;
+}
+
+.footnote:target  {
+    background-color: #ffa;
+}
+
+.line-block {
+    display: block;
+    margin-top: 1em;
+    margin-bottom: 1em;
+}
+
+.line-block .line-block {
+    margin-top: 0;
+    margin-bottom: 0;
+    margin-left: 1.5em;
+}
+
+.guilabel, .menuselection {
+    font-family: sans-serif;
+}
+
+.accelerator {
+    text-decoration: underline;
+}
+
+.classifier {
+    font-style: oblique;
+}
+
+.classifier:before {
+    font-style: normal;
+    margin: 0.5em;
+    content: ":";
+}
+
+abbr, acronym {
+    border-bottom: dotted 1px;
+    cursor: help;
+}
+
+/* -- code displays --------------------------------------------------------- */
+
+pre {
+    overflow: auto;
+    overflow-y: hidden;  /* fixes display issues on Chrome browsers */
+}
+
+pre, div[class*="highlight-"] {
+    clear: both;
+}
+
+span.pre {
+    -moz-hyphens: none;
+    -ms-hyphens: none;
+    -webkit-hyphens: none;
+    hyphens: none;
+}
+
+div[class*="highlight-"] {
+    margin: 1em 0;
+}
+
+td.linenos pre {
+    border: 0;
+    background-color: transparent;
+    color: #aaa;
+}
+
+table.highlighttable {
+    display: block;
+}
+
+table.highlighttable tbody {
+    display: block;
+}
+
+table.highlighttable tr {
+    display: flex;
+}
+
+table.highlighttable td {
+    margin: 0;
+    padding: 0;
+}
+
+table.highlighttable td.linenos {
+    padding-right: 0.5em;
+}
+
+table.highlighttable td.code {
+    flex: 1;
+    overflow: hidden;
+}
+
+.highlight .hll {
+    display: block;
+}
+
+div.highlight pre,
+table.highlighttable pre {
+    margin: 0;
+}
+
+div.code-block-caption + div {
+    margin-top: 0;
+}
+
+div.code-block-caption {
+    margin-top: 1em;
+    padding: 2px 5px;
+    font-size: small;
+}
+
+div.code-block-caption code {
+    background-color: transparent;
+}
+
+table.highlighttable td.linenos,
+span.linenos,
+div.doctest > div.highlight span.gp {  /* gp: Generic.Prompt */
+  user-select: none;
+  -webkit-user-select: text; /* Safari fallback only */
+  -webkit-user-select: none; /* Chrome/Safari */
+  -moz-user-select: none; /* Firefox */
+  -ms-user-select: none; /* IE10+ */
+}
+
+div.code-block-caption span.caption-number {
+    padding: 0.1em 0.3em;
+    font-style: italic;
+}
+
+div.code-block-caption span.caption-text {
+}
+
+div.literal-block-wrapper {
+    margin: 1em 0;
+}
+
+code.xref, a code {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+    background-color: transparent;
+}
+
+.viewcode-link {
+    float: right;
+}
+
+.viewcode-back {
+    float: right;
+    font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+    margin: -1px -10px;
+    padding: 0 10px;
+}
+
+/* -- math display ---------------------------------------------------------- */
+
+img.math {
+    vertical-align: middle;
+}
+
+div.body div.math p {
+    text-align: center;
+}
+
+span.eqno {
+    float: right;
+}
+
+span.eqno a.headerlink {
+    position: absolute;
+    z-index: 1;
+}
+
+div.math:hover a.headerlink {
+    visibility: visible;
+}
+
+/* -- printout stylesheet --------------------------------------------------- */
+
+@media print {
+    div.document,
+    div.documentwrapper,
+    div.bodywrapper {
+        margin: 0 !important;
+        width: 100%;
+    }
+
+    div.sphinxsidebar,
+    div.related,
+    div.footer,
+    #top-link {
+        display: none;
+    }
+}

docs/manual/_static/classic.css

@@ -0,0 +1,266 @@
+/*
+ * classic.css_t
+ * ~~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- classic theme.
+ *
+ * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+html {
+    /* CSS hack for macOS's scrollbar (see #1125) */
+    background-color: #FFFFFF;
+}
+
+body {
+    font-family: sans-serif;
+    font-size: 100%;
+    background-color: #11303d;
+    color: #000;
+    margin: 0;
+    padding: 0;
+}
+
+div.document {
+    background-color: #1c4e63;
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 230px;
+}
+
+div.body {
+    background-color: #ffffff;
+    color: #000000;
+    padding: 0 20px 30px 20px;
+}
+
+div.footer {
+    color: #ffffff;
+    width: 100%;
+    padding: 9px 0 9px 0;
+    text-align: center;
+    font-size: 75%;
+}
+
+div.footer a {
+    color: #ffffff;
+    text-decoration: underline;
+}
+
+div.related {
+    background-color: #133f52;
+    line-height: 30px;
+    color: #ffffff;
+}
+
+div.related a {
+    color: #ffffff;
+}
+
+div.sphinxsidebar {
+}
+
+div.sphinxsidebar h3 {
+    font-family: 'Trebuchet MS', sans-serif;
+    color: #ffffff;
+    font-size: 1.4em;
+    font-weight: normal;
+    margin: 0;
+    padding: 0;
+}
+
+div.sphinxsidebar h3 a {
+    color: #ffffff;
+}
+
+div.sphinxsidebar h4 {
+    font-family: 'Trebuchet MS', sans-serif;
+    color: #ffffff;
+    font-size: 1.3em;
+    font-weight: normal;
+    margin: 5px 0 0 0;
+    padding: 0;
+}
+
+div.sphinxsidebar p {
+    color: #ffffff;
+}
+
+div.sphinxsidebar p.topless {
+    margin: 5px 10px 10px 10px;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px;
+    padding: 0;
+    color: #ffffff;
+}
+
+div.sphinxsidebar a {
+    color: #98dbcc;
+}
+
+div.sphinxsidebar input {
+    border: 1px solid #98dbcc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+
+
+/* -- hyperlink styles ------------------------------------------------------ */
+
+a {
+    color: #355f7c;
+    text-decoration: none;
+}
+
+a:visited {
+    color: #355f7c;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+
+
+/* -- body styles ----------------------------------------------------------- */
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    font-family: 'Trebuchet MS', sans-serif;
+    background-color: #f2f2f2;
+    font-weight: normal;
+    color: #20435c;
+    border-bottom: 1px solid #ccc;
+    margin: 20px -20px 10px -20px;
+    padding: 3px 0 3px 10px;
+}
+
+div.body h1 { margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 160%; }
+div.body h3 { font-size: 140%; }
+div.body h4 { font-size: 120%; }
+div.body h5 { font-size: 110%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+    color: #c60f0f;
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+
+a.headerlink:hover {
+    background-color: #c60f0f;
+    color: white;
+}
+
+div.body p, div.body dd, div.body li, div.body blockquote {
+    text-align: justify;
+    line-height: 130%;
+}
+
+div.admonition p.admonition-title + p {
+    display: inline;
+}
+
+div.admonition p {
+    margin-bottom: 5px;
+}
+
+div.admonition pre {
+    margin-bottom: 5px;
+}
+
+div.admonition ul, div.admonition ol {
+    margin-bottom: 5px;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+
+div.topic {
+    background-color: #eee;
+}
+
+div.warning {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+}
+
+p.admonition-title {
+    display: inline;
+}
+
+p.admonition-title:after {
+    content: ":";
+}
+
+pre {
+    padding: 5px;
+    background-color: unset;
+    color: unset;
+    line-height: 120%;
+    border: 1px solid #ac9;
+    border-left: none;
+    border-right: none;
+}
+
+code {
+    background-color: #ecf0f3;
+    padding: 0 1px 0 1px;
+    font-size: 0.95em;
+}
+
+th, dl.field-list > dt {
+    background-color: #ede;
+}
+
+.warning code {
+    background: #efc2c2;
+}
+
+.note code {
+    background: #d6d6d6;
+}
+
+.viewcode-back {
+    font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+    background-color: #f4debf;
+    border-top: 1px solid #ac9;
+    border-bottom: 1px solid #ac9;
+}
+
+div.code-block-caption {
+    color: #efefef;
+    background-color: #1c4e63;
+}

docs/manual/_static/doctools.js

@@ -0,0 +1,321 @@
+/*
+ * doctools.js
+ * ~~~~~~~~~~~
+ *
+ * Sphinx JavaScript utilities for all documentation.
+ *
+ * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/**
+ * select a different prefix for underscore
+ */
+$u = _.noConflict();
+
+/**
+ * make the code below compatible with browsers without
+ * an installed firebug like debugger
+if (!window.console || !console.firebug) {
+  var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
+    "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
+    "profile", "profileEnd"];
+  window.console = {};
+  for (var i = 0; i < names.length; ++i)
+    window.console[names[i]] = function() {};
+}
+ */
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+  if (!x) {
+    return x
+  }
+  return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+  if (typeof s === 'undefined')
+    s = document.location.search;
+  var parts = s.substr(s.indexOf('?') + 1).split('&');
+  var result = {};
+  for (var i = 0; i < parts.length; i++) {
+    var tmp = parts[i].split('=', 2);
+    var key = jQuery.urldecode(tmp[0]);
+    var value = jQuery.urldecode(tmp[1]);
+    if (key in result)
+      result[key].push(value);
+    else
+      result[key] = [value];
+  }
+  return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+  function highlight(node, addItems) {
+    if (node.nodeType === 3) {
+      var val = node.nodeValue;
+      var pos = val.toLowerCase().indexOf(text);
+      if (pos >= 0 &&
+          !jQuery(node.parentNode).hasClass(className) &&
+          !jQuery(node.parentNode).hasClass("nohighlight")) {
+        var span;
+        var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+        if (isInSVG) {
+          span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+        } else {
+          span = document.createElement("span");
+          span.className = className;
+        }
+        span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+        node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+          document.createTextNode(val.substr(pos + text.length)),
+          node.nextSibling));
+        node.nodeValue = val.substr(0, pos);
+        if (isInSVG) {
+          var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+          var bbox = node.parentElement.getBBox();
+          rect.x.baseVal.value = bbox.x;
+          rect.y.baseVal.value = bbox.y;
+          rect.width.baseVal.value = bbox.width;
+          rect.height.baseVal.value = bbox.height;
+          rect.setAttribute('class', className);
+          addItems.push({
+              "parent": node.parentNode,
+              "target": rect});
+        }
+      }
+    }
+    else if (!jQuery(node).is("button, select, textarea")) {
+      jQuery.each(node.childNodes, function() {
+        highlight(this, addItems);
+      });
+    }
+  }
+  var addItems = [];
+  var result = this.each(function() {
+    highlight(this, addItems);
+  });
+  for (var i = 0; i < addItems.length; ++i) {
+    jQuery(addItems[i].parent).before(addItems[i].target);
+  }
+  return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+  jQuery.uaMatch = function(ua) {
+    ua = ua.toLowerCase();
+
+    var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+      /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+      /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+      /(msie) ([\w.]+)/.exec(ua) ||
+      ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+      [];
+
+    return {
+      browser: match[ 1 ] || "",
+      version: match[ 2 ] || "0"
+    };
+  };
+  jQuery.browser = {};
+  jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}
+
+/**
+ * Small JavaScript module for the documentation.
+ */
+var Documentation = {
+
+  init : function() {
+    this.fixFirefoxAnchorBug();
+    this.highlightSearchWords();
+    this.initIndexTable();
+    if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) {
+      this.initOnKeyListeners();
+    }
+  },
+
+  /**
+   * i18n support
+   */
+  TRANSLATIONS : {},
+  PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; },
+  LOCALE : 'unknown',
+
+  // gettext and ngettext don't access this so that the functions
+  // can safely bound to a different name (_ = Documentation.gettext)
+  gettext : function(string) {
+    var translated = Documentation.TRANSLATIONS[string];
+    if (typeof translated === 'undefined')
+      return string;
+    return (typeof translated === 'string') ? translated : translated[0];
+  },
+
+  ngettext : function(singular, plural, n) {
+    var translated = Documentation.TRANSLATIONS[singular];
+    if (typeof translated === 'undefined')
+      return (n == 1) ? singular : plural;
+    return translated[Documentation.PLURALEXPR(n)];
+  },
+
+  addTranslations : function(catalog) {
+    for (var key in catalog.messages)
+      this.TRANSLATIONS[key] = catalog.messages[key];
+    this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
+    this.LOCALE = catalog.locale;
+  },
+
+  /**
+   * add context elements like header anchor links
+   */
+  addContextElements : function() {
+    $('div[id] > :header:first').each(function() {
+      $('<a class="headerlink">\u00B6</a>').
+      attr('href', '#' + this.id).
+      attr('title', _('Permalink to this headline')).
+      appendTo(this);
+    });
+    $('dt[id]').each(function() {
+      $('<a class="headerlink">\u00B6</a>').
+      attr('href', '#' + this.id).
+      attr('title', _('Permalink to this definition')).
+      appendTo(this);
+    });
+  },
+
+  /**
+   * workaround a firefox stupidity
+   * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075
+   */
+  fixFirefoxAnchorBug : function() {
+    if (document.location.hash && $.browser.mozilla)
+      window.setTimeout(function() {
+        document.location.href += '';
+      }, 10);
+  },
+
+  /**
+   * highlight the search words provided in the url in the text
+   */
+  highlightSearchWords : function() {
+    var params = $.getQueryParameters();
+    var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
+    if (terms.length) {
+      var body = $('div.body');
+      if (!body.length) {
+        body = $('body');
+      }
+      window.setTimeout(function() {
+        $.each(terms, function() {
+          body.highlightText(this.toLowerCase(), 'highlighted');
+        });
+      }, 10);
+      $('<p class="highlight-link"><a href="javascript:Documentation.' +
+        'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')
+          .appendTo($('#searchbox'));
+    }
+  },
+
+  /**
+   * init the domain index toggle buttons
+   */
+  initIndexTable : function() {
+    var togglers = $('img.toggler').click(function() {
+      var src = $(this).attr('src');
+      var idnum = $(this).attr('id').substr(7);
+      $('tr.cg-' + idnum).toggle();
+      if (src.substr(-9) === 'minus.png')
+        $(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
+      else
+        $(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
+    }).css('display', '');
+    if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
+        togglers.click();
+    }
+  },
+
+  /**
+   * helper function to hide the search marks again
+   */
+  hideSearchWords : function() {
+    $('#searchbox .highlight-link').fadeOut(300);
+    $('span.highlighted').removeClass('highlighted');
+  },
+
+  /**
+   * make the url absolute
+   */
+  makeURL : function(relativeURL) {
+    return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
+  },
+
+  /**
+   * get the current relative url
+   */
+  getCurrentURL : function() {
+    var path = document.location.pathname;
+    var parts = path.split(/\//);
+    $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
+      if (this === '..')
+        parts.pop();
+    });
+    var url = parts.join('/');
+    return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
+  },
+
+  initOnKeyListeners: function() {
+    $(document).keydown(function(event) {
+      var activeElementType = document.activeElement.tagName;
+      // don't navigate when in search box, textarea, dropdown or button
+      if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT'
+          && activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey
+          && !event.shiftKey) {
+        switch (event.keyCode) {
+          case 37: // left
+            var prevHref = $('link[rel="prev"]').prop('href');
+            if (prevHref) {
+              window.location.href = prevHref;
+              return false;
+            }
+          case 39: // right
+            var nextHref = $('link[rel="next"]').prop('href');
+            if (nextHref) {
+              window.location.href = nextHref;
+              return false;
+            }
+        }
+      }
+    });
+  }
+};
+
+// quick alias for translations
+_ = Documentation.gettext;
+
+$(document).ready(function() {
+  Documentation.init();
+});

docs/manual/_static/documentation_options.js

@@ -0,0 +1,12 @@
+var DOCUMENTATION_OPTIONS = {
+    URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
+    VERSION: '0.2.8 beta',
+    LANGUAGE: 'None',
+    COLLAPSE_INDEX: false,
+    BUILDER: 'html',
+    FILE_SUFFIX: '.html',
+    LINK_SUFFIX: '.html',
+    HAS_SOURCE: true,
+    SOURCELINK_SUFFIX: '.txt',
+    NAVIGATION_WITH_KEYS: false
+};

docs/manual/_static/language_data.js

@@ -0,0 +1,297 @@
+/*
+ * language_data.js
+ * ~~~~~~~~~~~~~~~~
+ *
+ * This script contains the language-specific data used by searchtools.js,
+ * namely the list of stopwords, stemmer, scorer and splitter.
+ *
+ * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"];
+
+
+/* Non-minified version is copied as a separate JS file, is available */
+
+/**
+ * Porter Stemmer
+ */
+var Stemmer = function() {
+
+  var step2list = {
+    ational: 'ate',
+    tional: 'tion',
+    enci: 'ence',
+    anci: 'ance',
+    izer: 'ize',
+    bli: 'ble',
+    alli: 'al',
+    entli: 'ent',
+    eli: 'e',
+    ousli: 'ous',
+    ization: 'ize',
+    ation: 'ate',
+    ator: 'ate',
+    alism: 'al',
+    iveness: 'ive',
+    fulness: 'ful',
+    ousness: 'ous',
+    aliti: 'al',
+    iviti: 'ive',
+    biliti: 'ble',
+    logi: 'log'
+  };
+
+  var step3list = {
+    icate: 'ic',
+    ative: '',
+    alize: 'al',
+    iciti: 'ic',
+    ical: 'ic',
+    ful: '',
+    ness: ''
+  };
+
+  var c = "[^aeiou]";          // consonant
+  var v = "[aeiouy]";          // vowel
+  var C = c + "[^aeiouy]*";    // consonant sequence
+  var V = v + "[aeiou]*";      // vowel sequence
+
+  var mgr0 = "^(" + C + ")?" + V + C;                      // [C]VC... is m>0
+  var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$";    // [C]VC[V] is m=1
+  var mgr1 = "^(" + C + ")?" + V + C + V + C;              // [C]VCVC... is m>1
+  var s_v   = "^(" + C + ")?" + v;                         // vowel in stem
+
+  this.stemWord = function (w) {
+    var stem;
+    var suffix;
+    var firstch;
+    var origword = w;
+
+    if (w.length < 3)
+      return w;
+
+    var re;
+    var re2;
+    var re3;
+    var re4;
+
+    firstch = w.substr(0,1);
+    if (firstch == "y")
+      w = firstch.toUpperCase() + w.substr(1);
+
+    // Step 1a
+    re = /^(.+?)(ss|i)es$/;
+    re2 = /^(.+?)([^s])s$/;
+
+    if (re.test(w))
+      w = w.replace(re,"$1$2");
+    else if (re2.test(w))
+      w = w.replace(re2,"$1$2");
+
+    // Step 1b
+    re = /^(.+?)eed$/;
+    re2 = /^(.+?)(ed|ing)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      re = new RegExp(mgr0);
+      if (re.test(fp[1])) {
+        re = /.$/;
+        w = w.replace(re,"");
+      }
+    }
+    else if (re2.test(w)) {
+      var fp = re2.exec(w);
+      stem = fp[1];
+      re2 = new RegExp(s_v);
+      if (re2.test(stem)) {
+        w = stem;
+        re2 = /(at|bl|iz)$/;
+        re3 = new RegExp("([^aeiouylsz])\\1$");
+        re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+        if (re2.test(w))
+          w = w + "e";
+        else if (re3.test(w)) {
+          re = /.$/;
+          w = w.replace(re,"");
+        }
+        else if (re4.test(w))
+          w = w + "e";
+      }
+    }
+
+    // Step 1c
+    re = /^(.+?)y$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(s_v);
+      if (re.test(stem))
+        w = stem + "i";
+    }
+
+    // Step 2
+    re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      suffix = fp[2];
+      re = new RegExp(mgr0);
+      if (re.test(stem))
+        w = stem + step2list[suffix];
+    }
+
+    // Step 3
+    re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      suffix = fp[2];
+      re = new RegExp(mgr0);
+      if (re.test(stem))
+        w = stem + step3list[suffix];
+    }
+
+    // Step 4
+    re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
+    re2 = /^(.+?)(s|t)(ion)$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(mgr1);
+      if (re.test(stem))
+        w = stem;
+    }
+    else if (re2.test(w)) {
+      var fp = re2.exec(w);
+      stem = fp[1] + fp[2];
+      re2 = new RegExp(mgr1);
+      if (re2.test(stem))
+        w = stem;
+    }
+
+    // Step 5
+    re = /^(.+?)e$/;
+    if (re.test(w)) {
+      var fp = re.exec(w);
+      stem = fp[1];
+      re = new RegExp(mgr1);
+      re2 = new RegExp(meq1);
+      re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+      if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
+        w = stem;
+    }
+    re = /ll$/;
+    re2 = new RegExp(mgr1);
+    if (re.test(w) && re2.test(w)) {
+      re = /.$/;
+      w = w.replace(re,"");
+    }
+
+    // and turn initial Y back to y
+    if (firstch == "y")
+      w = firstch.toLowerCase() + w.substr(1);
+    return w;
+  }
+}
+
+
+
+
+var splitChars = (function() {
+    var result = {};
+    var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648,
+         1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702,
+         2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971,
+         2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345,
+         3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761,
+         3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823,
+         4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125,
+         8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695,
+         11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587,
+         43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141];
+    var i, j, start, end;
+    for (i = 0; i < singles.length; i++) {
+        result[singles[i]] = true;
+    }
+    var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709],
+         [722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161],
+         [1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568],
+         [1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807],
+         [1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047],
+         [2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383],
+         [2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450],
+         [2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547],
+         [2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673],
+         [2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820],
+         [2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946],
+         [2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023],
+         [3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173],
+         [3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332],
+         [3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481],
+         [3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718],
+         [3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791],
+         [3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095],
+         [4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205],
+         [4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687],
+         [4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968],
+         [4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869],
+         [5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102],
+         [6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271],
+         [6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592],
+         [6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822],
+         [6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167],
+         [7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959],
+         [7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143],
+         [8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318],
+         [8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483],
+         [8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101],
+         [10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567],
+         [11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292],
+         [12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444],
+         [12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783],
+         [12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311],
+         [19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511],
+         [42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774],
+         [42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071],
+         [43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263],
+         [43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519],
+         [43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647],
+         [43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967],
+         [44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295],
+         [57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274],
+         [64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007],
+         [65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381],
+         [65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]];
+    for (i = 0; i < ranges.length; i++) {
+        start = ranges[i][0];
+        end = ranges[i][1];
+        for (j = start; j <= end; j++) {
+            result[j] = true;
+        }
+    }
+    return result;
+})();
+
+function splitQuery(query) {
+    var result = [];
+    var start = -1;
+    for (var i = 0; i < query.length; i++) {
+        if (splitChars[query.charCodeAt(i)]) {
+            if (start !== -1) {
+                result.push(query.slice(start, i));
+                start = -1;
+            }
+        } else if (start === -1) {
+            start = i;
+        }
+    }
+    if (start !== -1) {
+        result.push(query.slice(start));
+    }
+    return result;
+}
+
+

docs/manual/_static/pygments.css

@@ -0,0 +1,74 @@
+pre { line-height: 125%; }
+td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
+span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
+td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
+span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
+.highlight .hll { background-color: #ffffcc }
+.highlight { background: #eeffcc; }
+.highlight .c { color: #408090; font-style: italic } /* Comment */
+.highlight .err { border: 1px solid #FF0000 } /* Error */
+.highlight .k { color: #007020; font-weight: bold } /* Keyword */
+.highlight .o { color: #666666 } /* Operator */
+.highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */
+.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */
+.highlight .cp { color: #007020 } /* Comment.Preproc */
+.highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */
+.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
+.highlight .gd { color: #A00000 } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #FF0000 } /* Generic.Error */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #00A000 } /* Generic.Inserted */
+.highlight .go { color: #333333 } /* Generic.Output */
+.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.highlight .gt { color: #0044DD } /* Generic.Traceback */
+.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
+.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
+.highlight .kp { color: #007020 } /* Keyword.Pseudo */
+.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #902000 } /* Keyword.Type */
+.highlight .m { color: #208050 } /* Literal.Number */
+.highlight .s { color: #4070a0 } /* Literal.String */
+.highlight .na { color: #4070a0 } /* Name.Attribute */
+.highlight .nb { color: #007020 } /* Name.Builtin */
+.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
+.highlight .no { color: #60add5 } /* Name.Constant */
+.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */
+.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */
+.highlight .ne { color: #007020 } /* Name.Exception */
+.highlight .nf { color: #06287e } /* Name.Function */
+.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */
+.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
+.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */
+.highlight .nv { color: #bb60d5 } /* Name.Variable */
+.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mb { color: #208050 } /* Literal.Number.Bin */
+.highlight .mf { color: #208050 } /* Literal.Number.Float */
+.highlight .mh { color: #208050 } /* Literal.Number.Hex */
+.highlight .mi { color: #208050 } /* Literal.Number.Integer */
+.highlight .mo { color: #208050 } /* Literal.Number.Oct */
+.highlight .sa { color: #4070a0 } /* Literal.String.Affix */
+.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */
+.highlight .sc { color: #4070a0 } /* Literal.String.Char */
+.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */
+.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
+.highlight .s2 { color: #4070a0 } /* Literal.String.Double */
+.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
+.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */
+.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
+.highlight .sx { color: #c65d09 } /* Literal.String.Other */
+.highlight .sr { color: #235388 } /* Literal.String.Regex */
+.highlight .s1 { color: #4070a0 } /* Literal.String.Single */
+.highlight .ss { color: #517918 } /* Literal.String.Symbol */
+.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */
+.highlight .fm { color: #06287e } /* Name.Function.Magic */
+.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */
+.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */
+.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */
+.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */
+.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */

docs/manual/_static/searchtools.js

@@ -0,0 +1,522 @@
+/*
+ * searchtools.js
+ * ~~~~~~~~~~~~~~~~
+ *
+ * Sphinx JavaScript utilities for the full-text search.
+ *
+ * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+if (!Scorer) {
+  /**
+   * Simple result scoring code.
+   */
+  var Scorer = {
+    // Implement the following function to further tweak the score for each result
+    // The function takes a result array [filename, title, anchor, descr, score]
+    // and returns the new score.
+    /*
+    score: function(result) {
+      return result[4];
+    },
+    */
+
+    // query matches the full name of an object
+    objNameMatch: 11,
+    // or matches in the last dotted part of the object name
+    objPartialMatch: 6,
+    // Additive scores depending on the priority of the object
+    objPrio: {0:  15,   // used to be importantResults
+              1:  5,   // used to be objectResults
+              2: -5},  // used to be unimportantResults
+    //  Used when the priority is not in the mapping.
+    objPrioDefault: 0,
+
+    // query found in title
+    title: 15,
+    partialTitle: 7,
+    // query found in terms
+    term: 5,
+    partialTerm: 2
+  };
+}
+
+if (!splitQuery) {
+  function splitQuery(query) {
+    return query.split(/\s+/);
+  }
+}
+
+/**
+ * Search Module
+ */
+var Search = {
+
+  _index : null,
+  _queued_query : null,
+  _pulse_status : -1,
+
+  htmlToText : function(htmlString) {
+      var virtualDocument = document.implementation.createHTMLDocument('virtual');
+      var htmlElement = $(htmlString, virtualDocument);
+      htmlElement.find('.headerlink').remove();
+      docContent = htmlElement.find('[role=main]')[0];
+      if(docContent === undefined) {
+          console.warn("Content block not found. Sphinx search tries to obtain it " +
+                       "via '[role=main]'. Could you check your theme or template.");
+          return "";
+      }
+      return docContent.textContent || docContent.innerText;
+  },
+
+  init : function() {
+      var params = $.getQueryParameters();
+      if (params.q) {
+          var query = params.q[0];
+          $('input[name="q"]')[0].value = query;
+          this.performSearch(query);
+      }
+  },
+
+  loadIndex : function(url) {
+    $.ajax({type: "GET", url: url, data: null,
+            dataType: "script", cache: true,
+            complete: function(jqxhr, textstatus) {
+              if (textstatus != "success") {
+                document.getElementById("searchindexloader").src = url;
+              }
+            }});
+  },
+
+  setIndex : function(index) {
+    var q;
+    this._index = index;
+    if ((q = this._queued_query) !== null) {
+      this._queued_query = null;
+      Search.query(q);
+    }
+  },
+
+  hasIndex : function() {
+      return this._index !== null;
+  },
+
+  deferQuery : function(query) {
+      this._queued_query = query;
+  },
+
+  stopPulse : function() {
+      this._pulse_status = 0;
+  },
+
+  startPulse : function() {
+    if (this._pulse_status >= 0)
+        return;
+    function pulse() {
+      var i;
+      Search._pulse_status = (Search._pulse_status + 1) % 4;
+      var dotString = '';
+      for (i = 0; i < Search._pulse_status; i++)
+        dotString += '.';
+      Search.dots.text(dotString);
+      if (Search._pulse_status > -1)
+        window.setTimeout(pulse, 500);
+    }
+    pulse();
+  },
+
+  /**
+   * perform a search for something (or wait until index is loaded)
+   */
+  performSearch : function(query) {
+    // create the required interface elements
+    this.out = $('#search-results');
+    this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
+    this.dots = $('<span></span>').appendTo(this.title);
+    this.status = $('<p class="search-summary">&nbsp;</p>').appendTo(this.out);
+    this.output = $('<ul class="search"/>').appendTo(this.out);
+
+    $('#search-progress').text(_('Preparing search...'));
+    this.startPulse();
+
+    // index already loaded, the browser was quick!
+    if (this.hasIndex())
+      this.query(query);
+    else
+      this.deferQuery(query);
+  },
+
+  /**
+   * execute search (requires search index to be loaded)
+   */
+  query : function(query) {
+    var i;
+
+    // stem the searchterms and add them to the correct list
+    var stemmer = new Stemmer();
+    var searchterms = [];
+    var excluded = [];
+    var hlterms = [];
+    var tmp = splitQuery(query);
+    var objectterms = [];
+    for (i = 0; i < tmp.length; i++) {
+      if (tmp[i] !== "") {
+          objectterms.push(tmp[i].toLowerCase());
+      }
+
+      if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i] === "") {
+        // skip this "word"
+        continue;
+      }
+      // stem the word
+      var word = stemmer.stemWord(tmp[i].toLowerCase());
+      // prevent stemmer from cutting word smaller than two chars
+      if(word.length < 3 && tmp[i].length >= 3) {
+        word = tmp[i];
+      }
+      var toAppend;
+      // select the correct list
+      if (word[0] == '-') {
+        toAppend = excluded;
+        word = word.substr(1);
+      }
+      else {
+        toAppend = searchterms;
+        hlterms.push(tmp[i].toLowerCase());
+      }
+      // only add if not already in the list
+      if (!$u.contains(toAppend, word))
+        toAppend.push(word);
+    }
+    var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
+
+    // console.debug('SEARCH: searching for:');
+    // console.info('required: ', searchterms);
+    // console.info('excluded: ', excluded);
+
+    // prepare search
+    var terms = this._index.terms;
+    var titleterms = this._index.titleterms;
+
+    // array of [filename, title, anchor, descr, score]
+    var results = [];
+    $('#search-progress').empty();
+
+    // lookup as object
+    for (i = 0; i < objectterms.length; i++) {
+      var others = [].concat(objectterms.slice(0, i),
+                             objectterms.slice(i+1, objectterms.length));
+      results = results.concat(this.performObjectSearch(objectterms[i], others));
+    }
+
+    // lookup as search terms in fulltext
+    results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms));
+
+    // let the scorer override scores with a custom scoring function
+    if (Scorer.score) {
+      for (i = 0; i < results.length; i++)
+        results[i][4] = Scorer.score(results[i]);
+    }
+
+    // now sort the results by score (in opposite order of appearance, since the
+    // display function below uses pop() to retrieve items) and then
+    // alphabetically
+    results.sort(function(a, b) {
+      var left = a[4];
+      var right = b[4];
+      if (left > right) {
+        return 1;
+      } else if (left < right) {
+        return -1;
+      } else {
+        // same score: sort alphabetically
+        left = a[1].toLowerCase();
+        right = b[1].toLowerCase();
+        return (left > right) ? -1 : ((left < right) ? 1 : 0);
+      }
+    });
+
+    // for debugging
+    //Search.lastresults = results.slice();  // a copy
+    //console.info('search results:', Search.lastresults);
+
+    // print the results
+    var resultCount = results.length;
+    function displayNextItem() {
+      // results left, load the summary and display it
+      if (results.length) {
+        var item = results.pop();
+        var listItem = $('<li></li>');
+        var requestUrl = "";
+        var linkUrl = "";
+        if (DOCUMENTATION_OPTIONS.BUILDER === 'dirhtml') {
+          // dirhtml builder
+          var dirname = item[0] + '/';
+          if (dirname.match(/\/index\/$/)) {
+            dirname = dirname.substring(0, dirname.length-6);
+          } else if (dirname == 'index/') {
+            dirname = '';
+          }
+          requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + dirname;
+          linkUrl = requestUrl;
+
+        } else {
+          // normal html builders
+          requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX;
+          linkUrl = item[0] + DOCUMENTATION_OPTIONS.LINK_SUFFIX;
+        }
+        listItem.append($('<a/>').attr('href',
+            linkUrl +
+            highlightstring + item[2]).html(item[1]));
+        if (item[3]) {
+          listItem.append($('<span> (' + item[3] + ')</span>'));
+          Search.output.append(listItem);
+          setTimeout(function() {
+            displayNextItem();
+          }, 5);
+        } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
+          $.ajax({url: requestUrl,
+                  dataType: "text",
+                  complete: function(jqxhr, textstatus) {
+                    var data = jqxhr.responseText;
+                    if (data !== '' && data !== undefined) {
+                      listItem.append(Search.makeSearchSummary(data, searchterms, hlterms));
+                    }
+                    Search.output.append(listItem);
+                    setTimeout(function() {
+                      displayNextItem();
+                    }, 5);
+                  }});
+        } else {
+          // no source available, just display title
+          Search.output.append(listItem);
+          setTimeout(function() {
+            displayNextItem();
+          }, 5);
+        }
+      }
+      // search finished, update title and status message
+      else {
+        Search.stopPulse();
+        Search.title.text(_('Search Results'));
+        if (!resultCount)
+          Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
+        else
+            Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
+        Search.status.fadeIn(500);
+      }
+    }
+    displayNextItem();
+  },
+
+  /**
+   * search for object names
+   */
+  performObjectSearch : function(object, otherterms) {
+    var filenames = this._index.filenames;
+    var docnames = this._index.docnames;
+    var objects = this._index.objects;
+    var objnames = this._index.objnames;
+    var titles = this._index.titles;
+
+    var i;
+    var results = [];
+
+    for (var prefix in objects) {
+      for (var name in objects[prefix]) {
+        var fullname = (prefix ? prefix + '.' : '') + name;
+        var fullnameLower = fullname.toLowerCase()
+        if (fullnameLower.indexOf(object) > -1) {
+          var score = 0;
+          var parts = fullnameLower.split('.');
+          // check for different match types: exact matches of full name or
+          // "last name" (i.e. last dotted part)
+          if (fullnameLower == object || parts[parts.length - 1] == object) {
+            score += Scorer.objNameMatch;
+          // matches in last name
+          } else if (parts[parts.length - 1].indexOf(object) > -1) {
+            score += Scorer.objPartialMatch;
+          }
+          var match = objects[prefix][name];
+          var objname = objnames[match[1]][2];
+          var title = titles[match[0]];
+          // If more than one term searched for, we require other words to be
+          // found in the name/title/description
+          if (otherterms.length > 0) {
+            var haystack = (prefix + ' ' + name + ' ' +
+                            objname + ' ' + title).toLowerCase();
+            var allfound = true;
+            for (i = 0; i < otherterms.length; i++) {
+              if (haystack.indexOf(otherterms[i]) == -1) {
+                allfound = false;
+                break;
+              }
+            }
+            if (!allfound) {
+              continue;
+            }
+          }
+          var descr = objname + _(', in ') + title;
+
+          var anchor = match[3];
+          if (anchor === '')
+            anchor = fullname;
+          else if (anchor == '-')
+            anchor = objnames[match[1]][1] + '-' + fullname;
+          // add custom score for some objects according to scorer
+          if (Scorer.objPrio.hasOwnProperty(match[2])) {
+            score += Scorer.objPrio[match[2]];
+          } else {
+            score += Scorer.objPrioDefault;
+          }
+          results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]);
+        }
+      }
+    }
+
+    return results;
+  },
+
+  /**
+   * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
+   */
+  escapeRegExp : function(string) {
+    return string.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string
+  },
+
+  /**
+   * search for full-text terms in the index
+   */
+  performTermsSearch : function(searchterms, excluded, terms, titleterms) {
+    var docnames = this._index.docnames;
+    var filenames = this._index.filenames;
+    var titles = this._index.titles;
+
+    var i, j, file;
+    var fileMap = {};
+    var scoreMap = {};
+    var results = [];
+
+    // perform the search on the required terms
+    for (i = 0; i < searchterms.length; i++) {
+      var word = searchterms[i];
+      var files = [];
+      var _o = [
+        {files: terms[word], score: Scorer.term},
+        {files: titleterms[word], score: Scorer.title}
+      ];
+      // add support for partial matches
+      if (word.length > 2) {
+        var word_regex = this.escapeRegExp(word);
+        for (var w in terms) {
+          if (w.match(word_regex) && !terms[word]) {
+            _o.push({files: terms[w], score: Scorer.partialTerm})
+          }
+        }
+        for (var w in titleterms) {
+          if (w.match(word_regex) && !titleterms[word]) {
+              _o.push({files: titleterms[w], score: Scorer.partialTitle})
+          }
+        }
+      }
+
+      // no match but word was a required one
+      if ($u.every(_o, function(o){return o.files === undefined;})) {
+        break;
+      }
+      // found search word in contents
+      $u.each(_o, function(o) {
+        var _files = o.files;
+        if (_files === undefined)
+          return
+
+        if (_files.length === undefined)
+          _files = [_files];
+        files = files.concat(_files);
+
+        // set score for the word in each file to Scorer.term
+        for (j = 0; j < _files.length; j++) {
+          file = _files[j];
+          if (!(file in scoreMap))
+            scoreMap[file] = {};
+          scoreMap[file][word] = o.score;
+        }
+      });
+
+      // create the mapping
+      for (j = 0; j < files.length; j++) {
+        file = files[j];
+        if (file in fileMap && fileMap[file].indexOf(word) === -1)
+          fileMap[file].push(word);
+        else
+          fileMap[file] = [word];
+      }
+    }
+
+    // now check if the files don't contain excluded terms
+    for (file in fileMap) {
+      var valid = true;
+
+      // check if all requirements are matched
+      var filteredTermCount = // as search terms with length < 3 are discarded: ignore
+        searchterms.filter(function(term){return term.length > 2}).length
+      if (
+        fileMap[file].length != searchterms.length &&
+        fileMap[file].length != filteredTermCount
+      ) continue;
+
+      // ensure that none of the excluded terms is in the search result
+      for (i = 0; i < excluded.length; i++) {
+        if (terms[excluded[i]] == file ||
+            titleterms[excluded[i]] == file ||
+            $u.contains(terms[excluded[i]] || [], file) ||
+            $u.contains(titleterms[excluded[i]] || [], file)) {
+          valid = false;
+          break;
+        }
+      }
+
+      // if we have still a valid result we can add it to the result list
+      if (valid) {
+        // select one (max) score for the file.
+        // for better ranking, we should calculate ranking by using words statistics like basic tf-idf...
+        var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]}));
+        results.push([docnames[file], titles[file], '', null, score, filenames[file]]);
+      }
+    }
+    return results;
+  },
+
+  /**
+   * helper function to return a node containing the
+   * search summary for a given text. keywords is a list
+   * of stemmed words, hlwords is the list of normal, unstemmed
+   * words. the first one is used to find the occurrence, the
+   * latter for highlighting it.
+   */
+  makeSearchSummary : function(htmlText, keywords, hlwords) {
+    var text = Search.htmlToText(htmlText);
+    var textLower = text.toLowerCase();
+    var start = 0;
+    $.each(keywords, function() {
+      var i = textLower.indexOf(this.toLowerCase());
+      if (i > -1)
+        start = i;
+    });
+    start = Math.max(start - 120, 0);
+    var excerpt = ((start > 0) ? '...' : '') +
+      $.trim(text.substr(start, 240)) +
+      ((start + 240 - text.length) ? '...' : '');
+    var rv = $('<p class="context"></p>').text(excerpt);
+    $.each(hlwords, function() {
+      rv = rv.highlightText(this, 'highlighted');
+    });
+    return rv;
+  }
+};
+
+$(document).ready(function() {
+  Search.init();
+});

docs/manual/_static/sidebar.js

@@ -0,0 +1,159 @@
+/*
+ * sidebar.js
+ * ~~~~~~~~~~
+ *
+ * This script makes the Sphinx sidebar collapsible.
+ *
+ * .sphinxsidebar contains .sphinxsidebarwrapper.  This script adds
+ * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton
+ * used to collapse and expand the sidebar.
+ *
+ * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden
+ * and the width of the sidebar and the margin-left of the document
+ * are decreased. When the sidebar is expanded the opposite happens.
+ * This script saves a per-browser/per-session cookie used to
+ * remember the position of the sidebar among the pages.
+ * Once the browser is closed the cookie is deleted and the position
+ * reset to the default (expanded).
+ *
+ * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+$(function() {
+  
+  
+  
+  
+  
+  
+  
+
+  // global elements used by the functions.
+  // the 'sidebarbutton' element is defined as global after its
+  // creation, in the add_sidebar_button function
+  var bodywrapper = $('.bodywrapper');
+  var sidebar = $('.sphinxsidebar');
+  var sidebarwrapper = $('.sphinxsidebarwrapper');
+
+  // for some reason, the document has no sidebar; do not run into errors
+  if (!sidebar.length) return;
+
+  // original margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar expanded
+  var bw_margin_expanded = bodywrapper.css('margin-left');
+  var ssb_width_expanded = sidebar.width();
+
+  // margin-left of the bodywrapper and width of the sidebar
+  // with the sidebar collapsed
+  var bw_margin_collapsed = '.8em';
+  var ssb_width_collapsed = '.8em';
+
+  // colors used by the current theme
+  var dark_color = $('.related').css('background-color');
+  var light_color = $('.document').css('background-color');
+
+  function sidebar_is_collapsed() {
+    return sidebarwrapper.is(':not(:visible)');
+  }
+
+  function toggle_sidebar() {
+    if (sidebar_is_collapsed())
+      expand_sidebar();
+    else
+      collapse_sidebar();
+  }
+
+  function collapse_sidebar() {
+    sidebarwrapper.hide();
+    sidebar.css('width', ssb_width_collapsed);
+    bodywrapper.css('margin-left', bw_margin_collapsed);
+    sidebarbutton.css({
+        'margin-left': '0',
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('»');
+    sidebarbutton.attr('title', _('Expand sidebar'));
+    document.cookie = 'sidebar=collapsed';
+  }
+
+  function expand_sidebar() {
+    bodywrapper.css('margin-left', bw_margin_expanded);
+    sidebar.css('width', ssb_width_expanded);
+    sidebarwrapper.show();
+    sidebarbutton.css({
+        'margin-left': ssb_width_expanded-12,
+        'height': bodywrapper.height()
+    });
+    sidebarbutton.find('span').text('«');
+    sidebarbutton.attr('title', _('Collapse sidebar'));
+    document.cookie = 'sidebar=expanded';
+  }
+
+  function add_sidebar_button() {
+    sidebarwrapper.css({
+        'float': 'left',
+        'margin-right': '0',
+        'width': ssb_width_expanded - 28
+    });
+    // create the button
+    sidebar.append(
+        '<div id="sidebarbutton"><span>&laquo;</span></div>'
+    );
+    var sidebarbutton = $('#sidebarbutton');
+    light_color = sidebarbutton.css('background-color');
+    // find the height of the viewport to center the '<<' in the page
+    var viewport_height;
+    if (window.innerHeight)
+ 	  viewport_height = window.innerHeight;
+    else
+	  viewport_height = $(window).height();
+    sidebarbutton.find('span').css({
+        'display': 'block',
+        'margin-top': (viewport_height - sidebar.position().top - 20) / 2
+    });
+
+    sidebarbutton.click(toggle_sidebar);
+    sidebarbutton.attr('title', _('Collapse sidebar'));
+    sidebarbutton.css({
+        'color': '#FFFFFF',
+        'border-left': '1px solid ' + dark_color,
+        'font-size': '1.2em',
+        'cursor': 'pointer',
+        'height': bodywrapper.height(),
+        'padding-top': '1px',
+        'margin-left': ssb_width_expanded - 12
+    });
+
+    sidebarbutton.hover(
+      function () {
+          $(this).css('background-color', dark_color);
+      },
+      function () {
+          $(this).css('background-color', light_color);
+      }
+    );
+  }
+
+  function set_position_from_cookie() {
+    if (!document.cookie)
+      return;
+    var items = document.cookie.split(';');
+    for(var k=0; k<items.length; k++) {
+      var key_val = items[k].split('=');
+      var key = key_val[0].replace(/ /, "");  // strip leading spaces
+      if (key == 'sidebar') {
+        var value = key_val[1];
+        if ((value == 'collapsed') && (!sidebar_is_collapsed()))
+          collapse_sidebar();
+        else if ((value == 'expanded') && (sidebar_is_collapsed()))
+          expand_sidebar();
+      }
+    }
+  }
+
+  add_sidebar_button();
+  var sidebarbutton = $('#sidebarbutton');
+  set_position_from_cookie();
+});

docs/manual/genindex.html

@@ -0,0 +1,428 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Index &#8212; Reticulum Network Stack 0.2.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <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/doctools.js"></script>
+    
+    <link rel="index" title="Index" href="#" />
+    <link rel="search" title="Search" href="search.html" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="#" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Index</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+
+<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>
+<h2 id="A">A</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Resource.advertise">advertise() (RNS.Resource method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Destination.announce">announce() (RNS.Destination method)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination.app_and_aspects_from_name">app_and_aspects_from_name() (RNS.Destination static method)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="C">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.Destination.clear_default_app_data">clear_default_app_data() (RNS.Destination 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.Identity.CURVE">CURVE (RNS.Identity attribute)</a>
+
+      <ul>
+        <li><a href="reference.html#RNS.Link.CURVE">(RNS.Link attribute)</a>
+</li>
+      </ul></li>
+  </ul></td>
+</tr></table>
+
+<h2 id="D">D</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Destination.decrypt">decrypt() (RNS.Destination method)</a>
+
+      <ul>
+        <li><a href="reference.html#RNS.Identity.decrypt">(RNS.Identity method)</a>
+</li>
+      </ul></li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Transport.deregister_announce_handler">deregister_announce_handler() (RNS.Transport static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination.deregister_request_handler">deregister_request_handler() (RNS.Destination method)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination">Destination (class in RNS)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="E">E</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Destination.encrypt">encrypt() (RNS.Destination method)</a>
+
+      <ul>
+        <li><a href="reference.html#RNS.Identity.encrypt">(RNS.Identity method)</a>
+</li>
+      </ul></li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Packet.ENCRYPTED_MDU">ENCRYPTED_MDU (RNS.Packet attribute)</a>
+</li>
+      <li><a href="reference.html#RNS.Link.ESTABLISHMENT_TIMEOUT_PER_HOP">ESTABLISHMENT_TIMEOUT_PER_HOP (RNS.Link attribute)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="F">F</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Identity.from_bytes">from_bytes() (RNS.Identity static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Identity.from_file">from_file() (RNS.Identity static method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Identity.full_hash">full_hash() (RNS.Identity static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination.full_name">full_name() (RNS.Destination static method)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="G">G</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Destination.get_private_key">get_private_key() (RNS.Destination method)</a>
+
+      <ul>
+        <li><a href="reference.html#RNS.Identity.get_private_key">(RNS.Identity method)</a>
+</li>
+      </ul></li>
+      <li><a href="reference.html#RNS.RequestReceipt.get_progress">get_progress() (RNS.RequestReceipt method)</a>
+
+      <ul>
+        <li><a href="reference.html#RNS.Resource.get_progress">(RNS.Resource method)</a>
+</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.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>
+</li>
+      <li><a href="reference.html#RNS.RequestReceipt.get_response">get_response() (RNS.RequestReceipt method)</a>
+</li>
+      <li><a href="reference.html#RNS.RequestReceipt.get_response_time">get_response_time() (RNS.RequestReceipt method)</a>
+</li>
+      <li><a href="reference.html#RNS.PacketReceipt.get_rtt">get_rtt() (RNS.PacketReceipt method)</a>
+</li>
+      <li><a href="reference.html#RNS.PacketReceipt.get_status">get_status() (RNS.PacketReceipt method)</a>
+
+      <ul>
+        <li><a href="reference.html#RNS.RequestReceipt.get_status">(RNS.RequestReceipt method)</a>
+</li>
+      </ul></li>
+  </ul></td>
+</tr></table>
+
+<h2 id="H">H</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Transport.has_path">has_path() (RNS.Transport static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination.hash">hash() (RNS.Destination static method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Destination.hash_from_name_and_identity">hash_from_name_and_identity() (RNS.Destination static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Transport.hops_to">hops_to() (RNS.Transport static method)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="I">I</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Link.identify">identify() (RNS.Link method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Identity">Identity (class in RNS)</a>
+</li>
+      <li><a href="reference.html#RNS.Link.inactive_for">inactive_for() (RNS.Link method)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="K">K</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Link.KEEPALIVE">KEEPALIVE (RNS.Link attribute)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Identity.KEYSIZE">KEYSIZE (RNS.Identity attribute)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="L">L</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Link">Link (class in RNS)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination.load_private_key">load_private_key() (RNS.Destination method)</a>
+
+      <ul>
+        <li><a href="reference.html#RNS.Identity.load_private_key">(RNS.Identity method)</a>
+</li>
+      </ul></li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Identity.load_public_key">load_public_key() (RNS.Identity method)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="M">M</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Reticulum.MTU">MTU (RNS.Reticulum attribute)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="N">N</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Transport.next_hop">next_hop() (RNS.Transport static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Transport.next_hop_interface">next_hop_interface() (RNS.Transport static method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Link.no_inbound_for">no_inbound_for() (RNS.Link method)</a>
+</li>
+      <li><a href="reference.html#RNS.Link.no_outbound_for">no_outbound_for() (RNS.Link method)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="P">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>
+      <li><a href="reference.html#RNS.PacketReceipt">PacketReceipt (class in RNS)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <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>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="R">R</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <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>
+      <li><a href="reference.html#RNS.Link.request">request() (RNS.Link method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <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>
+</li>
+      <li><a href="reference.html#RNS.Packet.resend">resend() (RNS.Packet method)</a>
+</li>
+      <li><a href="reference.html#RNS.Resource">Resource (class in RNS)</a>
+</li>
+      <li><a href="reference.html#RNS.Reticulum">Reticulum (class in RNS)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="S">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>
+      <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>
+</li>
+      <li><a href="reference.html#RNS.Destination.set_link_established_callback">set_link_established_callback() (RNS.Destination method)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination.set_packet_callback">set_packet_callback() (RNS.Destination method)</a>
+
+      <ul>
+        <li><a href="reference.html#RNS.Link.set_packet_callback">(RNS.Link method)</a>
+</li>
+      </ul></li>
+      <li><a href="reference.html#RNS.Destination.set_proof_requested_callback">set_proof_requested_callback() (RNS.Destination method)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination.set_proof_strategy">set_proof_strategy() (RNS.Destination method)</a>
+</li>
+      <li><a href="reference.html#RNS.Link.set_remote_identified_callback">set_remote_identified_callback() (RNS.Link method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Link.set_resource_callback">set_resource_callback() (RNS.Link method)</a>
+</li>
+      <li><a href="reference.html#RNS.Link.set_resource_concluded_callback">set_resource_concluded_callback() (RNS.Link method)</a>
+</li>
+      <li><a href="reference.html#RNS.Link.set_resource_started_callback">set_resource_started_callback() (RNS.Link method)</a>
+</li>
+      <li><a href="reference.html#RNS.Link.set_resource_strategy">set_resource_strategy() (RNS.Link method)</a>
+</li>
+      <li><a href="reference.html#RNS.PacketReceipt.set_timeout">set_timeout() (RNS.PacketReceipt method)</a>
+</li>
+      <li><a href="reference.html#RNS.PacketReceipt.set_timeout_callback">set_timeout_callback() (RNS.PacketReceipt method)</a>
+</li>
+      <li><a href="reference.html#RNS.Reticulum.should_use_implicit_proof">should_use_implicit_proof() (RNS.Reticulum static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination.sign">sign() (RNS.Destination method)</a>
+
+      <ul>
+        <li><a href="reference.html#RNS.Identity.sign">(RNS.Identity method)</a>
+</li>
+      </ul></li>
+  </ul></td>
+</tr></table>
+
+<h2 id="T">T</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Link.teardown">teardown() (RNS.Link method)</a>
+</li>
+      <li><a href="reference.html#RNS.Identity.to_file">to_file() (RNS.Identity method)</a>
+</li>
+      <li><a href="reference.html#RNS.Transport">Transport (class in RNS)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Reticulum.transport_enabled">transport_enabled() (RNS.Reticulum static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Identity.truncated_hash">truncated_hash() (RNS.Identity static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Identity.TRUNCATED_HASHLENGTH">TRUNCATED_HASHLENGTH (RNS.Identity attribute)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+<h2 id="V">V</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Identity.validate">validate() (RNS.Identity method)</a>
+</li>
+  </ul></td>
+</tr></table>
+
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="#" title="General Index"
+             >index</a></li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Index</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2021, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/gettingstartedfast.html

@@ -0,0 +1,215 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Getting Started Fast &#8212; Reticulum Network Stack 0.2.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <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/doctools.js"></script>
+    
+    <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" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="using.html" title="Using Reticulum on Your System"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="whatis.html" title="What is Reticulum?"
+             accesskey="P">previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Getting Started Fast</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="section" id="getting-started-fast">
+<h1>Getting Started Fast<a class="headerlink" href="#getting-started-fast" title="Permalink to this headline">¶</a></h1>
+<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>
+<div class="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 headline">¶</a></h2>
+<p>If you simply want to try using a program built with Reticulum, you can take
+a look at <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a>, which
+provides a complete encrypted communications suite built with Reticulum.</p>
+<a class="reference external image-reference" href="_images/nomadnet_3.png"><img alt="_images/nomadnet_3.png" src="_images/nomadnet_3.png" /></a>
+<p><a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> is a user-facing client
+in the development 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="c1"># ... and run</span>
+<span class="n">nomadnet</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="using-the-included-utilities">
+<h2>Using the Included Utilities<a class="headerlink" href="#using-the-included-utilities" title="Permalink to this headline">¶</a></h2>
+<p>Reticulum comes with a range of included utilities that make it easier to
+manage your network, check connectivity and make Reticulum available to other
+programs on your system.</p>
+<p>You can use <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> to run Reticulum as a background or foreground service,
+and the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>, <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> and <code class="docutils literal notranslate"><span class="pre">rnprobe</span></code> utilities to view and query
+network status and connectivity.</p>
+<p>To learn more about these utility programs, have a look at the
+<a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter of this manual.</p>
+</div>
+<div class="section" id="creating-a-network-with-reticulum">
+<h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this headline">¶</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>.</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 network (if there is one), and only allows you to
+communicate with other Reticulum peers within your local broadcast domain.</p>
+<p>To communicate further, you will have to add one or more interfaces. The default
+configuration includes a number of examples, ranging from using TCP over the
+internet, to LoRa and Packet Radio interfaces.</p>
+<p>Possibly, the examples in the config file are enough to get you started. If
+you want more information, you can read the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a>
+and <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapters of this manual.</p>
+</div>
+<div class="section" id="develop-a-program-with-reticulum">
+<h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this headline">¶</a></h2>
+<p>If you want to develop programs that use Reticulum, the easiest way to get
+started is to install the latest release of Reticulum via pip:</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">rns</span>
+</pre></div>
+</div>
+<p>The above command will install Reticulum and dependencies, and you will be
+ready to import and use RNS in your own programs. The next step will most
+likely be to look at some <a class="reference internal" href="examples.html#examples-main"><span class="std std-ref">Example Programs</span></a>.</p>
+<p>Further information can be found in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>.</p>
+</div>
+<div class="section" id="participate-in-reticulum-development">
+<h2>Participate in Reticulum Development<a class="headerlink" href="#participate-in-reticulum-development" title="Permalink to this headline">¶</a></h2>
+<p>If you want to participate in the development of Reticulum and associated
+utilities, you’ll want to get the latest source from GitHub. In that case,
+don’t use pip, but try this recipe:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install dependencies</span>
+<span class="n">pip3</span> <span class="n">install</span> <span class="n">cryptography</span> <span class="n">pyserial</span> <span class="n">netifaces</span>
+
+<span class="c1"># Clone repository</span>
+<span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">markqvist</span><span class="o">/</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">git</span>
+
+<span class="c1"># Move into Reticulum folder and symlink library to examples folder</span>
+<span class="n">cd</span> <span class="n">Reticulum</span>
+<span class="n">ln</span> <span class="o">-</span><span class="n">s</span> <span class="o">../</span><span class="n">RNS</span> <span class="o">./</span><span class="n">Examples</span><span class="o">/</span>
+
+<span class="c1"># Run an example</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="o">-</span><span class="n">s</span>
+
+<span class="c1"># Unless you&#39;ve manually created a config file, Reticulum will do so now,</span>
+<span class="c1"># and immediately exit. Make any necessary changes to the file:</span>
+<span class="n">nano</span> <span class="o">~/.</span><span class="n">reticulum</span><span class="o">/</span><span class="n">config</span>
+
+<span class="c1"># ... and launch the example again.</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="o">-</span><span class="n">s</span>
+
+<span class="c1"># You can now repeat the process on another computer,</span>
+<span class="c1"># and run the same example with -h to get command line options.</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="o">-</span><span class="n">h</span>
+
+<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="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>
+</pre></div>
+</div>
+<p>When you have experimented with the basic examples, it’s time to go read the
+<a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter.</p>
+</div>
+</div>
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Getting Started Fast</a><ul>
+<li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a></li>
+<li><a class="reference internal" href="#using-the-included-utilities">Using the Included Utilities</a></li>
+<li><a class="reference internal" href="#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li>
+<li><a class="reference internal" href="#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
+<li><a class="reference internal" href="#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
+</ul>
+</li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="whatis.html"
+                        title="previous chapter">What is Reticulum?</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="using.html"
+                        title="next chapter">Using Reticulum on Your System</a></p>
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/gettingstartedfast.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="using.html" title="Using Reticulum on Your System"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="whatis.html" title="What is Reticulum?"
+             >previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Getting Started Fast</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2021, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/index.html

@@ -0,0 +1,212 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Reticulum Network Stack Manual &#8212; Reticulum Network Stack 0.2.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <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/doctools.js"></script>
+    
+    <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" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="whatis.html" title="What is Reticulum?"
+             accesskey="N">next</a> |</li>
+        <li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Manual</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="section" id="reticulum-network-stack-manual">
+<h1>Reticulum Network Stack Manual<a class="headerlink" href="#reticulum-network-stack-manual" title="Permalink to this headline">¶</a></h1>
+<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>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="whatis.html#current-status">Current Status</a></li>
+<li class="toctree-l2"><a class="reference internal" href="whatis.html#caveat-emptor">Caveat Emptor</a></li>
+<li class="toctree-l2"><a class="reference internal" href="whatis.html#what-does-reticulum-offer">What does Reticulum Offer?</a></li>
+<li class="toctree-l2"><a class="reference internal" href="whatis.html#where-can-reticulum-be-used">Where can Reticulum be Used?</a></li>
+<li class="toctree-l2"><a class="reference internal" href="whatis.html#interface-types-and-devices">Interface Types and Devices</a></li>
+</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#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#using-the-included-utilities">Using the Included Utilities</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#creating-a-network-with-reticulum">Creating a Network With Reticulum</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#develop-a-program-with-reticulum">Develop a Program with Reticulum</a></li>
+<li class="toctree-l2"><a class="reference internal" href="gettingstartedfast.html#participate-in-reticulum-development">Participate in Reticulum Development</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="using.html#included-utility-programs">Included Utility Programs</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnsd-utility">The rnsd Utility</a></li>
+<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnstatus-utility">The rnstatus Utility</a></li>
+<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnpath-utility">The rnpath Utility</a></li>
+<li class="toctree-l3"><a class="reference internal" href="using.html#the-rnprobe-utility">The rnprobe Utility</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="networks.html#concepts-overview">Concepts &amp; Overview</a></li>
+<li class="toctree-l2"><a class="reference internal" href="networks.html#example-scenarios">Example Scenarios</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="networks.html#interconnected-lora-sites">Interconnected LoRa Sites</a></li>
+<li class="toctree-l3"><a class="reference internal" href="networks.html#bridging-over-the-internet">Bridging Over the Internet</a></li>
+<li class="toctree-l3"><a class="reference internal" href="networks.html#growth-and-convergence">Growth and Convergence</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#udp-interface">UDP Interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-server-interface">TCP Server Interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#tcp-client-interface">TCP Client Interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#rnode-lora-interface">RNode LoRa Interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#serial-interface">Serial Interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#kiss-interface">KISS Interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interfaces.html#ax-25-kiss-interface">AX.25 KISS Interface</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="understanding.html">Understanding Reticulum</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="understanding.html#motivation">Motivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="understanding.html#goals">Goals</a></li>
+<li class="toctree-l2"><a class="reference internal" href="understanding.html#introduction-basic-functionality">Introduction &amp; Basic Functionality</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#destinations">Destinations</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#public-key-announcements">Public Key Announcements</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#understanding-identities">Identities</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#getting-further">Getting Further</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="understanding.html#reticulum-transport">Reticulum Transport</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#the-announce-mechanism-in-detail">The Announce Mechanism in Detail</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#reaching-the-destination">Reaching the Destination</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#resources">Resources</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="understanding.html#reference-system-setup">Reference System Setup</a></li>
+<li class="toctree-l2"><a class="reference internal" href="understanding.html#protocol-specifics">Protocol Specifics</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#node-types">Node Types</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#packet-prioritisation">Packet Prioritisation</a></li>
+<li class="toctree-l3"><a class="reference internal" href="understanding.html#binary-packet-format">Binary Packet Format</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="reference.html#classes">Classes</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#reticulum">Reticulum</a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#api-identity">Identity</a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#destination">Destination</a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#packet">Packet</a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#packet-receipt">Packet Receipt</a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#link">Link</a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#request-receipt">Request Receipt</a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#resource">Resource</a></li>
+<li class="toctree-l3"><a class="reference internal" href="reference.html#transport">Transport</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="examples.html#minimal">Minimal</a></li>
+<li class="toctree-l2"><a class="reference internal" href="examples.html#announce">Announce</a></li>
+<li class="toctree-l2"><a class="reference internal" href="examples.html#broadcast">Broadcast</a></li>
+<li class="toctree-l2"><a class="reference internal" href="examples.html#echo">Echo</a></li>
+<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#filetransfer">Filetransfer</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="indices-and-tables">
+<h2>Indices and Tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li>
+<li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li>
+</ul>
+</div>
+</div>
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="#">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Reticulum Network Stack Manual</a><ul>
+<li><a class="reference internal" href="#indices-and-tables">Indices and Tables</a></li>
+</ul>
+</li>
+</ul>
+
+  <h4>Next topic</h4>
+  <p class="topless"><a href="whatis.html"
+                        title="next chapter">What is Reticulum?</a></p>
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/index.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="whatis.html" title="What is Reticulum?"
+             >next</a> |</li>
+        <li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Manual</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2021, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/interfaces.html

@@ -0,0 +1,421 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Supported Interfaces &#8212; Reticulum Network Stack 0.2.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <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/doctools.js"></script>
+    
+    <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="Building Networks" href="networks.html" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="understanding.html" title="Understanding Reticulum"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="networks.html" title="Building Networks"
+             accesskey="P">previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Supported Interfaces</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="section" id="supported-interfaces">
+<span id="interfaces-main"></span><h1>Supported Interfaces<a class="headerlink" href="#supported-interfaces" title="Permalink to this headline">¶</a></h1>
+<p>Reticulum supports using many kinds of devices as networking interfaces, and
+allows you to mix and match them in any way you choose. The number of distinct
+network topologies you can create with Reticulum is more or less endless, but
+common to them all is that you will need to define one or more <em>interfaces</em>
+for Reticulum to use.</p>
+<p>The following sections describe the interfaces currently available in Reticulum,
+and gives example configurations for the respective interface types.</p>
+<p>For a high-level overview of how networks can be formed over different interface
+types, have a look at the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> chapter of this
+manual.</p>
+<div class="section" id="udp-interface">
+<span id="interfaces-udp"></span><h2>UDP Interface<a class="headerlink" href="#udp-interface" title="Permalink to this headline">¶</a></h2>
+<p>A UDP interface can be useful for communicating over IP networks, both
+private and the internet. It can also allow broadcast communication
+over IP networks, so it can provide an easy way to enable connectivity
+with all other peers on a local area network.</p>
+<p>The below example is enabled by default on new Reticulum installations,
+as it provides an easy way to get started and to test Reticulum on a
+pre-existing LAN.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example enables communication with other</span>
+<span class="c1"># local Reticulum peers over UDP.</span>
+
+<span class="p">[[</span><span class="n">Default</span> <span class="n">UDP</span> <span class="n">Interface</span><span class="p">]]</span>
+  <span class="nb">type</span> <span class="o">=</span> <span class="n">UDPInterface</span>
+  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+  <span class="n">outgoing</span> <span class="o">=</span> <span class="kc">True</span>
+  <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0</span><span class="o">.</span><span class="mf">0.0</span>
+  <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span>
+  <span class="n">forward_ip</span> <span class="o">=</span> <span class="mf">255.255</span><span class="o">.</span><span class="mf">255.255</span>
+  <span class="n">forward_port</span> <span class="o">=</span> <span class="mi">4242</span>
+
+  <span class="c1"># The above configuration will allow communication</span>
+  <span class="c1"># within the local broadcast domains of all local</span>
+  <span class="c1"># IP interfaces. This is enabled by default as an</span>
+  <span class="c1"># easy way to get started, but you might want to</span>
+  <span class="c1"># consider altering it to something more specific.</span>
+
+  <span class="c1"># Instead of specifying listen_ip, listen_port,</span>
+  <span class="c1"># forward_ip and forward_port, you can also bind</span>
+  <span class="c1"># to a specific network device like below.</span>
+
+  <span class="c1"># device = eth0</span>
+  <span class="c1"># port = 4242</span>
+
+  <span class="c1"># Assuming the eth0 device has the address</span>
+  <span class="c1"># 10.55.0.72/24, the above configuration would</span>
+  <span class="c1"># be equivalent to the following manual setup.</span>
+  <span class="c1"># Note that we are both listening and forwarding to</span>
+  <span class="c1"># the broadcast address of the network segments.</span>
+
+  <span class="c1"># listen_ip = 10.55.0.255</span>
+  <span class="c1"># listen_port = 4242</span>
+  <span class="c1"># forward_ip = 10.55.0.255</span>
+  <span class="c1"># forward_port = 4242</span>
+
+  <span class="c1"># You can of course also communicate only with</span>
+  <span class="c1"># a single IP address</span>
+
+  <span class="c1"># listen_ip = 10.55.0.15</span>
+  <span class="c1"># listen_port = 4242</span>
+  <span class="c1"># forward_ip = 10.55.0.16</span>
+  <span class="c1"># forward_port = 4242</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tcp-server-interface">
+<span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Permalink to this headline">¶</a></h2>
+<p>The TCP Server interface is suitable for allowing other peers to connect over
+the Internet or private IP networks. When a TCP server interface has been
+configured, other Reticulum peers can connect to it with a TCP Client interface.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This example demonstrates a TCP server interface.</span>
+<span class="c1"># It will listen for incoming connections on the</span>
+<span class="c1"># specified IP address and port number.</span>
+
+<span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">Interface</span><span class="p">]]</span>
+  <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
+  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+  <span class="n">outgoing</span> <span class="o">=</span> <span class="kc">True</span>
+
+  <span class="c1"># This configuration will listen on all IP</span>
+  <span class="c1"># interfaces on port 4242</span>
+
+  <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0</span><span class="o">.</span><span class="mf">0.0</span>
+  <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span>
+
+  <span class="c1"># Alternatively you can bind to a specific IP</span>
+
+  <span class="c1"># listen_ip = 10.0.0.88</span>
+  <span class="c1"># listen_port = 4242</span>
+
+  <span class="c1"># Or a specific network device</span>
+
+  <span class="c1"># device = eth0</span>
+  <span class="c1"># port = 4242</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tcp-client-interface">
+<span id="interfaces-tcpc"></span><h2>TCP Client Interface<a class="headerlink" href="#tcp-client-interface" title="Permalink to this headline">¶</a></h2>
+<p>To connect to a TCP server interface, you would naturally use the TCP client
+interface. Many TCP Client interfaces from different peers can connect to the
+same TCP Server interface at the same time.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of a TCP Client interface. The</span>
+<span class="c1"># target_host can either be an IP address or a hostname.</span>
+
+<span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span>
+  <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
+  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+  <span class="n">outgoing</span> <span class="o">=</span> <span class="kc">True</span>
+  <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span>
+  <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="rnode-lora-interface">
+<span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Permalink to this headline">¶</a></h2>
+<p>To use Reticulum over LoRa, the <a class="reference external" href="https://unsigned.io/rnode/">RNode</a> interface
+can be used, and offers full control over LoRa parameters.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of how to add a LoRa interface</span>
+<span class="c1"># using the RNode LoRa transceiver.</span>
+
+<span class="p">[[</span><span class="n">RNode</span> <span class="n">LoRa</span> <span class="n">Interface</span><span class="p">]]</span>
+  <span class="nb">type</span> <span class="o">=</span> <span class="n">RNodeInterface</span>
+
+  <span class="c1"># Enable interface if you want use it!</span>
+  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+
+  <span class="c1"># Allow transmit on interface. Setting</span>
+  <span class="c1"># this to false will create a listen-</span>
+  <span class="c1"># only interface.</span>
+  <span class="n">outgoing</span> <span class="o">=</span> <span class="n">true</span>
+
+  <span class="c1"># Serial port for the device</span>
+  <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB0</span>
+
+  <span class="c1"># Set frequency to 867.2 MHz</span>
+  <span class="n">frequency</span> <span class="o">=</span> <span class="mi">867200000</span>
+
+  <span class="c1"># Set LoRa bandwidth to 125 KHz</span>
+  <span class="n">bandwidth</span> <span class="o">=</span> <span class="mi">125000</span>
+
+  <span class="c1"># Set TX power to 7 dBm (5 mW)</span>
+  <span class="n">txpower</span> <span class="o">=</span> <span class="mi">7</span>
+
+  <span class="c1"># Select spreading factor 8. Valid</span>
+  <span class="c1"># range is 7 through 12, with 7</span>
+  <span class="c1"># being the fastest and 12 having</span>
+  <span class="c1"># the longest range.</span>
+  <span class="n">spreadingfactor</span> <span class="o">=</span> <span class="mi">8</span>
+
+  <span class="c1"># Select coding rate 5. Valid range</span>
+  <span class="c1"># is 5 throough 8, with 5 being the</span>
+  <span class="c1"># fastest, and 8 the longest range.</span>
+  <span class="n">codingrate</span> <span class="o">=</span> <span class="mi">5</span>
+
+  <span class="c1"># You can configure the RNode to send</span>
+  <span class="c1"># out identification on the channel with</span>
+  <span class="c1"># a set interval by configuring the</span>
+  <span class="c1"># following two parameters.</span>
+  <span class="c1"># id_callsign = MYCALL-0</span>
+  <span class="c1"># id_interval = 600</span>
+
+  <span class="c1"># For certain homebrew RNode interfaces</span>
+  <span class="c1"># with low amounts of RAM, using packet</span>
+  <span class="c1"># flow control can be useful. By default</span>
+  <span class="c1"># it is disabled.</span>
+  <span class="n">flow_control</span> <span class="o">=</span> <span class="kc">False</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="serial-interface">
+<span id="interfaces-serial"></span><h2>Serial Interface<a class="headerlink" href="#serial-interface" title="Permalink to this headline">¶</a></h2>
+<p>Reticulum can be used over serial ports directly, or over any device with a
+serial port, that will transparently pass data. Useful for communicating
+directly over a wire-pair, or for using devices such as data radios and lasers.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Serial</span> <span class="n">Interface</span><span class="p">]]</span>
+  <span class="nb">type</span> <span class="o">=</span> <span class="n">SerialInterface</span>
+  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+  <span class="n">outgoing</span> <span class="o">=</span> <span class="kc">True</span>
+
+  <span class="c1"># Serial port for the device</span>
+  <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB0</span>
+
+  <span class="c1"># Set the serial baud-rate and other</span>
+  <span class="c1"># configuration parameters.</span>
+  <span class="n">speed</span> <span class="o">=</span> <span class="mi">115200</span>
+  <span class="n">databits</span> <span class="o">=</span> <span class="mi">8</span>
+  <span class="n">parity</span> <span class="o">=</span> <span class="n">none</span>
+  <span class="n">stopbits</span> <span class="o">=</span> <span class="mi">1</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="kiss-interface">
+<span id="interfaces-kiss"></span><h2>KISS Interface<a class="headerlink" href="#kiss-interface" title="Permalink to this headline">¶</a></h2>
+<p>With the KISS interface, you can use Reticulum over a variety of packet
+radio modems and TNCs, including <a class="reference external" href="https://unsigned.io/openmodem/">OpenModem</a>.
+KISS interfaces can also be configured to periodically send out beacons
+for station identification purposes.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span>
+  <span class="nb">type</span> <span class="o">=</span> <span class="n">KISSInterface</span>
+  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+  <span class="n">outgoing</span> <span class="o">=</span> <span class="n">true</span>
+
+  <span class="c1"># Serial port for the device</span>
+  <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB1</span>
+
+  <span class="c1"># Set the serial baud-rate and other</span>
+  <span class="c1"># configuration parameters.</span>
+  <span class="n">speed</span> <span class="o">=</span> <span class="mi">115200</span>
+  <span class="n">databits</span> <span class="o">=</span> <span class="mi">8</span>
+  <span class="n">parity</span> <span class="o">=</span> <span class="n">none</span>
+  <span class="n">stopbits</span> <span class="o">=</span> <span class="mi">1</span>
+
+  <span class="c1"># Set the modem preamble.</span>
+  <span class="n">preamble</span> <span class="o">=</span> <span class="mi">150</span>
+
+  <span class="c1"># Set the modem TX tail.</span>
+  <span class="n">txtail</span> <span class="o">=</span> <span class="mi">10</span>
+
+  <span class="c1"># Configure CDMA parameters. These</span>
+  <span class="c1"># settings are reasonable defaults.</span>
+  <span class="n">persistence</span> <span class="o">=</span> <span class="mi">200</span>
+  <span class="n">slottime</span> <span class="o">=</span> <span class="mi">20</span>
+
+  <span class="c1"># You can configure the interface to send</span>
+  <span class="c1"># out identification on the channel with</span>
+  <span class="c1"># a set interval by configuring the</span>
+  <span class="c1"># following two parameters. The KISS</span>
+  <span class="c1"># interface will only ID if the set</span>
+  <span class="c1"># interval has elapsed since it&#39;s last</span>
+  <span class="c1"># actual transmission. The interval is</span>
+  <span class="c1"># configured in seconds.</span>
+  <span class="c1"># This option is commented out and not</span>
+  <span class="c1"># used by default.</span>
+  <span class="c1"># id_callsign = MYCALL-0</span>
+  <span class="c1"># id_interval = 600</span>
+
+  <span class="c1"># Whether to use KISS flow-control.</span>
+  <span class="c1"># This is useful for modems that have</span>
+  <span class="c1"># a small internal packet buffer, but</span>
+  <span class="c1"># support packet flow control instead.</span>
+  <span class="n">flow_control</span> <span class="o">=</span> <span class="n">false</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="ax-25-kiss-interface">
+<span id="interfaces-ax25"></span><h2>AX.25 KISS Interface<a class="headerlink" href="#ax-25-kiss-interface" title="Permalink to this headline">¶</a></h2>
+<p>If you’re using Reticulum on amateur radio spectrum, you might want to
+use the AX.25 KISS interface. This way, Reticulum will automatically
+encapsulate it’s traffic in AX.25 and also identify your stations
+transmissions with your callsign and SSID.</p>
+<p>Only do this if you really need to! Reticulum doesn’t need the AX.25
+layer for anything, and it incurs extra overhead on every packet to
+encapsulate in AX.25.</p>
+<p>A more efficient way is to use the plain KISS interface with the
+beaconing functionality described above.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">AX</span><span class="o">.</span><span class="mi">25</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span>
+  <span class="nb">type</span> <span class="o">=</span> <span class="n">AX25KISSInterface</span>
+
+  <span class="c1"># Set the station callsign and SSID</span>
+  <span class="n">callsign</span> <span class="o">=</span> <span class="n">NO1CLL</span>
+  <span class="n">ssid</span> <span class="o">=</span> <span class="mi">0</span>
+
+  <span class="c1"># Enable interface if you want use it!</span>
+  <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
+
+  <span class="c1"># Allow transmit on interface.</span>
+  <span class="n">outgoing</span> <span class="o">=</span> <span class="kc">True</span>
+
+  <span class="c1"># Serial port for the device</span>
+  <span class="n">port</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">ttyUSB2</span>
+
+  <span class="c1"># Set the serial baud-rate and other</span>
+  <span class="c1"># configuration parameters.</span>
+  <span class="n">speed</span> <span class="o">=</span> <span class="mi">115200</span>
+  <span class="n">databits</span> <span class="o">=</span> <span class="mi">8</span>
+  <span class="n">parity</span> <span class="o">=</span> <span class="n">none</span>
+  <span class="n">stopbits</span> <span class="o">=</span> <span class="mi">1</span>
+
+  <span class="c1"># Set the modem preamble. A 150ms</span>
+  <span class="c1"># preamble should be a reasonable</span>
+  <span class="c1"># default, but may need to be</span>
+  <span class="c1"># increased for radios with slow-</span>
+  <span class="c1"># opening squelch and long TX/RX</span>
+  <span class="c1"># turnaround</span>
+  <span class="n">preamble</span> <span class="o">=</span> <span class="mi">150</span>
+
+  <span class="c1"># Set the modem TX tail. In most</span>
+  <span class="c1"># cases this should be kept as low</span>
+  <span class="c1"># as possible to not waste airtime.</span>
+  <span class="n">txtail</span> <span class="o">=</span> <span class="mi">10</span>
+
+  <span class="c1"># Configure CDMA parameters. These</span>
+  <span class="c1"># settings are reasonable defaults.</span>
+  <span class="n">persistence</span> <span class="o">=</span> <span class="mi">200</span>
+  <span class="n">slottime</span> <span class="o">=</span> <span class="mi">20</span>
+
+  <span class="c1"># Whether to use KISS flow-control.</span>
+  <span class="c1"># This is useful for modems with a</span>
+  <span class="c1"># small internal packet buffer.</span>
+  <span class="n">flow_control</span> <span class="o">=</span> <span class="n">false</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Supported Interfaces</a><ul>
+<li><a class="reference internal" href="#udp-interface">UDP Interface</a></li>
+<li><a class="reference internal" href="#tcp-server-interface">TCP Server Interface</a></li>
+<li><a class="reference internal" href="#tcp-client-interface">TCP Client Interface</a></li>
+<li><a class="reference internal" href="#rnode-lora-interface">RNode LoRa Interface</a></li>
+<li><a class="reference internal" href="#serial-interface">Serial Interface</a></li>
+<li><a class="reference internal" href="#kiss-interface">KISS Interface</a></li>
+<li><a class="reference internal" href="#ax-25-kiss-interface">AX.25 KISS Interface</a></li>
+</ul>
+</li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="networks.html"
+                        title="previous chapter">Building Networks</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="understanding.html"
+                        title="next chapter">Understanding Reticulum</a></p>
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/interfaces.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="understanding.html" title="Understanding Reticulum"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="networks.html" title="Building Networks"
+             >previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Supported Interfaces</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2021, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/networks.html

@@ -0,0 +1,259 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Building Networks &#8212; Reticulum Network Stack 0.2.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <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/doctools.js"></script>
+    
+    <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="Using Reticulum on Your System" href="using.html" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="interfaces.html" title="Supported Interfaces"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="using.html" title="Using Reticulum on Your System"
+             accesskey="P">previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Building Networks</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="section" id="building-networks">
+<span id="networks-main"></span><h1>Building Networks<a class="headerlink" href="#building-networks" title="Permalink to this headline">¶</a></h1>
+<p>This chapter will provide you with the knowledge needed to build networks with
+Reticulum, which can often be easier than using traditional stacks, since you
+don’t have to worry about coordinating addresses, subnets and routing for an
+entire network that you might not know how will evolve in the future. With
+Reticulum, you can simply add more segments to your network when it becomes
+necesarry, and Reticulum will handle the convergence of the entire network
+automatically.</p>
+<div class="section" id="concepts-overview">
+<h2>Concepts &amp; Overview<a class="headerlink" href="#concepts-overview" title="Permalink to this headline">¶</a></h2>
+<p>There are important points that need to be kept in mind when building networks
+with Reticulum:</p>
+<blockquote>
+<div><ul>
+<li><div class="line-block">
+<div class="line">In a Reticulum network, any node can autonomously generate as many adresses
+(called <em>destinations</em> in Reticulum terminology) as it needs, which become
+globally reachable to the rest of the network. There is no central point of
+control over the adress space.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">Reticulum was designed to handle both very small, and very large networks.
+While the adress space can support billions of endpoints, Reticulum is
+also very useful when just a few devices needs to communicate.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">Reticulum provides sender/initiator anonymity by default. There is no way
+to filter traffic or discriminate it based on the source of the traffic.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">All traffic is encrypted using ephemeral keys generated by an Elliptic Curve
+Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic
+contents, and no way to prioritise or throttle certain kinds of traffic.
+All transport and routing layers are thus completely agnostic to traffic type,
+and will pass all traffic equally.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">Reticulum can function both with and without infrastructure. When <em>transport
+nodes</em> are available, they can route traffic over multiple hops for other
+nodes, and will function as a distributed cryptographic keystore. When there
+is no transport nodes available, all nodes that are within communication range
+can still communicate.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">Every node can become a transport node, simply by enabling it in it’s
+configuration, but there is no need for every node on the network to be a
+transport node. Letting every node be a transport node will in most cases
+degrade the performance and reliability of the network.</div>
+</div>
+<blockquote>
+<div><p>In general terms, if a node is stationary, well-connected and kept running
+most of the time, it is a good candidate to be a transport node. For optimal
+performance, a network should contain the amount of transport nodes that
+provides connectivity to the intended area / topography, and not many more
+than that.</p>
+</div></blockquote>
+</li>
+</ul>
+</div></blockquote>
+<p>Reticulum allows you to mix very different kinds of networking mediums into a
+unified mesh, or to keep everything within one medium. You could build a “virtual
+network” running entirely over the Internet, where all nodes communicate over TCP
+and UDP “channels”. You could also build such a network using MQTT or ZeroMQ as
+the underlying carrier for Reticulum.</p>
+<p>However, most real-world networks will probably involve either some form of
+wireless or direct hardline communications. To allow Reticulum to communicate
+over any type of medium, you must specify it in the configuration file, by default
+located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. See the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Supported Interfaces</span></a>
+chapter of this manual for interface configuration examples.</p>
+<p>Any number of interfaces can be configured, and Reticulum will automatically
+decide which are suitable to use in any given situation, depending on where
+traffic needs to flow.</p>
+</div>
+<div class="section" id="example-scenarios">
+<h2>Example Scenarios<a class="headerlink" href="#example-scenarios" title="Permalink to this headline">¶</a></h2>
+<p>This section illustrates a few example scenarios, and how they would, in general
+terms, be planned, implemented and configured.</p>
+<div class="section" id="interconnected-lora-sites">
+<h3>Interconnected LoRa Sites<a class="headerlink" href="#interconnected-lora-sites" title="Permalink to this headline">¶</a></h3>
+<p>An organisation wants to provide communication and information services to it’s
+members, which are located mainly in three separate areas. Three suitable hill-top
+locations are found, where the organisation can install equipment: Site A, B and C.</p>
+<p>Since the amount of data that needs to be exchanged between users is mainly text-
+based, the bandwidth requirements are low, and LoRa radios are chosen to connect
+users to the network.</p>
+<p>Due to the hill-top locations found, there is radio line-of-sight between site A
+and B, and also between site B and C. Because of this, the organisation does not
+need to use the Internet to interconnect the sites, but purchases four Point-to-Point
+WiFi based radios for interconnecting the sites.</p>
+<p>At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio
+is connected to the Pi with a USB cable, and the WiFi radio is connected to the
+ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach
+both site A and site C, so an extra ethernet adapter is connected to the Pi in
+this location.</p>
+<p>Once the hardware has been installed, Reticulum is installed on all the Pis, and at
+site A and C, one interface is added for the LoRa radio, as well as one for the WiFi
+radio. At site B, an interface for the LoRa radio, and one interface for each WiFi
+radio is added to the Reticulum configuration file. The transport node option is
+enabled in the configuration of all three gateways.</p>
+<p>The network is now operational, and ready to serve users across all three areas.
+The organisation prepares a LoRa radio that is supplied to the end users, along
+with a Reticulum configuration file, that contains the right parameters for
+communicating with the LoRa radios installed at the gateway sites.</p>
+<p>Once users connect to the network, anyone will be able to communicate with anyone
+else across all three sites.</p>
+</div>
+<div class="section" id="bridging-over-the-internet">
+<h3>Bridging Over the Internet<a class="headerlink" href="#bridging-over-the-internet" title="Permalink to this headline">¶</a></h3>
+<p>As the organisation grows, several new communities form in places too far away
+from the core network to be reachable over WiFi links. New gateways similar to those
+previously installed are set up for the new communities at the new sites D and E, but
+they are islanded from the core network, and only serve the local users.</p>
+<p>After investigating the options, it is found that it is possible to install an
+Internet connection at site A, and an interface on the Internet connection is
+configured for Reticulum on the Raspberry Pi at site A.</p>
+<p>A member of the organisation at site D, named Dori, is willing to help by sharing
+the Internet connection she already has in her home, and is able to leave a Raspberry
+Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly
+enabled Internet interface on the gateway at site A. Dori is now connected to both
+all the nodes at her own local site (through the hill-top LoRa gateway), and all the
+combined users of sites A, B and C. She then enables transport on her node, and
+traffic from site D can now reach everyone at site A, B and C, and vice versa.</p>
+</div>
+<div class="section" id="growth-and-convergence">
+<h3>Growth and Convergence<a class="headerlink" href="#growth-and-convergence" title="Permalink to this headline">¶</a></h3>
+<p>As the organisation grows, more gateways are added to keep up with the growing user
+base. Some local gateways even add VHF radios and packet modems to reach outlying users
+and communities that are out of reach for the LoRa radios and WiFi backhauls.</p>
+<p>As more sites, gateways and users are connected, the amount of coordination required
+is kept to a minimum. If one community wants to add connectivity to the next one
+over, it can simply be done without having to involve everyone or coordinate address
+space or routing tables.</p>
+<p>With the added geographical coverage, the operators at site A one day find that
+the original internet bridged interfaces are no longer utilised. The network has
+converged to be completely self-connected, and the sites that were once poorly
+connected outliers are now an integral part of the network.</p>
+</div>
+</div>
+</div>
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Building Networks</a><ul>
+<li><a class="reference internal" href="#concepts-overview">Concepts &amp; Overview</a></li>
+<li><a class="reference internal" href="#example-scenarios">Example Scenarios</a><ul>
+<li><a class="reference internal" href="#interconnected-lora-sites">Interconnected LoRa Sites</a></li>
+<li><a class="reference internal" href="#bridging-over-the-internet">Bridging Over the Internet</a></li>
+<li><a class="reference internal" href="#growth-and-convergence">Growth and Convergence</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="using.html"
+                        title="previous chapter">Using Reticulum on Your System</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="interfaces.html"
+                        title="next chapter">Supported Interfaces</a></p>
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/networks.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="interfaces.html" title="Supported Interfaces"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="using.html" title="Using Reticulum on Your System"
+             >previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Building Networks</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2021, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/search.html

@@ -0,0 +1,97 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Search &#8212; Reticulum Network Stack 0.2.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    
+    <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/doctools.js"></script>
+    
+    <script src="_static/searchtools.js"></script>
+    <script src="_static/language_data.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="#" />
+  <script src="searchindex.js" defer></script>
+   
+
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Search</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <h1 id="search-documentation">Search</h1>
+  
+  <div id="fallback" class="admonition warning">
+  <script>$('#fallback').hide();</script>
+  <p>
+    Please activate JavaScript to enable the search
+    functionality.
+  </p>
+  </div>
+  
+  
+  <p>
+    Searching for multiple words only shows matches that contain
+    all words.
+  </p>
+  
+  
+  <form action="" method="get">
+    <input type="text" name="q" aria-labelledby="search-documentation" value="" />
+    <input type="submit" value="search" />
+    <span id="search-progress" style="padding-left: 10px"></span>
+  </form>
+  
+  
+  
+  <div id="search-results">
+  
+  </div>
+  
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Search</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2021, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/understanding.html

@@ -0,0 +1,865 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Understanding Reticulum &#8212; Reticulum Network Stack 0.2.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <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/doctools.js"></script>
+    
+    <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="Supported Interfaces" href="interfaces.html" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="reference.html" title="API Reference"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="interfaces.html" title="Supported Interfaces"
+             accesskey="P">previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Understanding Reticulum</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="section" id="understanding-reticulum">
+<span id="understanding-main"></span><h1>Understanding Reticulum<a class="headerlink" href="#understanding-reticulum" title="Permalink to this headline">¶</a></h1>
+<p>This chapter will briefly describe the overall purpose and operating principles of Reticulum, a
+networking stack designed for reliable and secure communication over high-latency, low-bandwidth
+links. It should give you an overview of how the stack works, and an understanding of how to
+develop networked applications using Reticulum.</p>
+<p>This document is not an exhaustive source of information on Reticulum, at least not yet. Currently,
+the best place to go for such information is the Python reference implementation of Reticulum, along
+with the code examples and API reference. It is however an essential resource to understanding the
+general principles of Reticulum, how to apply them when creating your own networks or software.</p>
+<p>After reading this document, you should be well-equipped to understand how a Reticulum network
+operates, what it can achieve, and how you can use it yourself. If you want to help out with the
+development, this is also the place to start, since it will provide a pretty clear overview of the
+sentiments and the philosophy behind Reticulum.</p>
+<div class="section" id="motivation">
+<span id="understanding-motivation"></span><h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2>
+<p>The primary motivation for designing and implementing Reticulum has been the current lack of
+reliable, functional and secure minimal-infrastructure modes of digital communication. It is my
+belief that it is highly desirable to create a cheap and reliable way to set up a wide-range digital
+communication network that can securely allow exchange of information between people and
+machines, with no central point of authority, control, censorship or barrier to entry.</p>
+<p>Almost all of the various networking systems in use today share a common limitation, namely that they
+require large amounts of coordination and trust to work, and to join the networks you need approval
+of gatekeepers in control. This need for coordination and trust inevitably leads to an environment of
+central control, where it’s very easy for infrastructure operators or governments to control or alter
+traffic, and censor or persecute unwanted actors.</p>
+<p>Reticulum aims to require as little coordination and trust as possible. In fact, the only
+“coordination” required is to know the characteristics of physical medium carrying Reticulum traffic.</p>
+<p>Since Reticulum is completely medium agnostic, this could be whatever is best suited to the situation.
+In some cases, this might be 1200 baud packet radio links over VHF frequencies, in other cases it might
+be a microwave network using off-the-shelf radios. At the time of release of this document, the
+recommended setup for development and testing is using LoRa radio modules with an open source firmware
+(see the section <a class="reference internal" href="#understanding-referencesystem"><span class="std std-ref">Reference System Setup</span></a>), connected to a small
+computer like a Raspberry Pi. As an example, the default reference setup provides a channel capacity
+of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (indefinitely extendable
+by using multiple hops).</p>
+</div>
+<div class="section" id="goals">
+<span id="understanding-goals"></span><h2>Goals<a class="headerlink" href="#goals" title="Permalink to this headline">¶</a></h2>
+<p>To be as widely usable and easy to use as possible, the following goals have been used to
+guide the design of Reticulum:</p>
+<ul class="simple">
+<li><dl class="simple">
+<dt><strong>Fully useable as open source software stack</strong></dt><dd><p>Reticulum must be implemented with, and be able to run using only open source software. This is
+critical to ensuring the availability, security and transparency of the system.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Hardware layer agnosticism</strong></dt><dd><p>Reticulum shall be fully hardware agnostic, and shall be useable over a wide range
+physical networking layers, such as data radios, serial lines, modems, handheld transceivers,
+wired ethernet, wifi, or anything else that can carry a digital data stream. Hardware made for
+dedicated Reticulum use shall be as cheap as possible and use off-the-shelf components, so
+it can be easily replicated.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Very low bandwidth requirements</strong></dt><dd><p>Reticulum should be able to function reliably over links with a transmission capacity as low
+as <em>1,000 bps</em>.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Encryption by default</strong></dt><dd><p>Reticulum must use encryption by default where possible and applicable.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Unlicensed use</strong></dt><dd><p>Reticulum shall be functional over physical communication mediums that do not require any
+form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio
+frequency bands, and can provide functional long distance links in such conditions, for example
+by connecting a modem to a PMR or CB radio, or by using LoRa or WiFi modules.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Supplied software</strong></dt><dd><p>Apart from the core networking stack and API, that allows a developer to build
+applications with Reticulum, a basic communication suite using Reticulum must be
+implemented and released at the same time as Reticulum itself. This shall serve both as a
+functional communication suite, and as an example and learning resource to others wishing
+to build applications with Reticulum.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Ease of use</strong></dt><dd><p>The reference implementation of Reticulum is written in Python, to make it easy to use
+and understand. A programmer with only basic experience should be able to use
+Reticulum in their own applications.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Low cost</strong></dt><dd><p>It shall be as cheap as possible to deploy a communication system based on Reticulum. This
+should be achieved by using cheap off-the-shelf hardware that potential users might already
+own. The cost of setting up a functioning node should be less than $100 even if all parts
+needs to be purchased.</p>
+</dd>
+</dl>
+</li>
+</ul>
+</div>
+<div class="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 headline">¶</a></h2>
+<p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
+core a <em>message oriented</em> system. It is suited for both local point-to-point or point-to-multipoint
+scenarios where alle nodes are within range of each other, as well as scenarios where packets need
+to be transported over multiple hops 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
+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 internally as 10 bytes, derived from truncating a full
+SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
+will be displayed as 10 bytes in hexadecimal representation, as in the following example: <code class="docutils literal notranslate"><span class="pre">&lt;80e29bf7cccaf31431b3&gt;</span></code>.</p>
+<p>By default Reticulum encrypts all data using public-key cryptography. Any message sent to a
+destination is encrypted with that destinations public key. Reticulum can also set up an encrypted
+channel to a destination with <em>Perfect Forward Secrecy</em> and <em>Initiator Anonymity</em> using a elliptic
+curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In
+Reticulum terminology, this is called a <em>Link</em>.</p>
+<p>Reticulum also offers symmetric key encryption for group-oriented communications, as well as
+unencrypted packets for broadcast purposes, or situations where you need the communication to be in
+plain text. The multi-hop transport, coordination, verification and reliability layers are fully
+autonomous and based on public key cryptography.</p>
+<p>Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
+and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
+private IP networks.</p>
+<div class="section" id="destinations">
+<span id="understanding-destinations"></span><h3>Destinations<a class="headerlink" href="#destinations" title="Permalink to this headline">¶</a></h3>
+<p>To receive and send data with the Reticulum stack, an application needs to create one or more
+destinations. Reticulum uses three different basic destination types, and one special:</p>
+<ul class="simple">
+<li><dl class="simple">
+<dt><strong>Single</strong></dt><dd><p>The <em>single</em> destination type defines a public-key encrypted destination. Any data sent to this
+destination will be encrypted with the destination’s public key, and will only be readable by
+the creator of the destination.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Group</strong></dt><dd><p>The <em>group</em> destination type defines a symmetrically encrypted destination. Data sent to this
+destination will be encrypted with a symmetric key, and will be readable by anyone in
+possession of the key. The <em>group</em> destination can be used just as well by only two peers, as it
+can by many.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Plain</strong></dt><dd><p>A <em>plain</em> destination type is unencrypted, and suited for traffic that should be broadcast to a
+number of users, or should be readable by anyone. Traffic to a <em>plain</em> destination is not encrypted.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Link</strong></dt><dd><p>A <em>link</em> is a special destination type, that serves as an abstract channel to a <em>single</em>
+destination, directly connected or over multiple hops. The <em>link</em> also offers reliability and
+more efficient encryption, forward secrecy, initiator anonymity, and as such can be useful even
+when a node is directly reachable.</p>
+</dd>
+</dl>
+</li>
+</ul>
+<div class="section" id="destination-naming">
+<span id="understanding-destinationnaming"></span><h4>Destination Naming<a class="headerlink" href="#destination-naming" title="Permalink to this headline">¶</a></h4>
+<p>Destinations are created and named in an easy to understand dotted notation of <em>aspects</em>, and
+represented on the network as a hash of this value. The hash is a SHA-256 truncated to 80 bits. The
+top level aspect should always be a unique identifier for the application using the destination.
+The next levels of aspects can be defined in any way by the creator of the application.</p>
+<p>Aspects can be as long and as plentiful as required, and a resulting long destination name will not
+impact efficiency, as names are always represented as truncated SHA-256 hashes on the network.</p>
+<p>As an example, a destination for a environmental monitoring application could be made up of the
+application name, a device type and measurement type, like this:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>app name  : environmentlogger
+aspects   : remotesensor, temperature
+
+full name : environmentlogger.remotesensor.temperature
+hash      : fa7ddfab5213f916dea
+</pre></div>
+</div>
+<p>For the <em>single</em> destination, Reticulum will automatically append the associated public key as a
+destination aspect before hashing. This is done to ensure only the correct destination is reached,
+since anyone can listen to any destination name. Appending the public key ensures that a given
+packet is only directed at the destination that holds the corresponding private key to decrypt the
+packet.</p>
+<p><strong>Take note!</strong> There is a very important concept to understand here:</p>
+<ul class="simple">
+<li><p>Anyone can use the destination name <code class="docutils literal notranslate"><span class="pre">environmentlogger.remotesensor.temperature</span></code></p></li>
+<li><p>Each destination that does so will still have a unique destination hash, and thus be uniquely
+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 acheived by the appending the public key,
+which expands the destination into a uniquely identifyable one.</p>
+<p>Any destination on a Reticulum network can be addressed and reached simply by knowning its
+destination hash (and public key, but if the public key is not known, it can be requested from the
+network simply by knowing the destination hash). The use of app names and aspects makes it easy to
+structure Reticulum programs and makes it possible to filter what information and data your program
+receives.</p>
+<p>To recap, the different destination types should be used in the following situations:</p>
+<ul class="simple">
+<li><dl class="simple">
+<dt><strong>Single</strong></dt><dd><p>When private communication between two endpoints is needed. Supports multiple hops.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Group</strong></dt><dd><p>When private communication between two or more endpoints is needed. Supports multiple hops
+indirectly, but must first be established through a <em>single</em> destination.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Plain</strong></dt><dd><p>When plain-text communication is desirable, for example when broadcasting information.</p>
+</dd>
+</dl>
+</li>
+</ul>
+<p>To communicate with a <em>single</em> destination, you need to know it’s 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 participating nodes serve as a distributed ledger
+of public keys.</p>
+<p>Note that public key information can be shared and verified in many other ways than using the
+built-in <em>announce</em> functionality, and that it is therefore not required to use the announce/request
+functionality to obtain public keys. It is by far the easiest though, and should definitely be used
+if there is not a good reason for doing it differently.</p>
+</div>
+</div>
+<div class="section" id="public-key-announcements">
+<span id="understanding-keyannouncements"></span><h3>Public Key Announcements<a class="headerlink" href="#public-key-announcements" title="Permalink to this headline">¶</a></h3>
+<p>An <em>announce</em> will send a special packet over any configured interfaces, containing all needed
+information about the destination hash and public key, and can also contain some additional,
+application specific data. The entire packet is signed by the sender to ensure authenticity. It is not
+required to use the announce functionality, but in many cases it will be the simplest way to share
+public keys on the network. As an example, an announce in a simple messenger application might
+contain the following information:</p>
+<ul class="simple">
+<li><p>The announcers destination hash</p></li>
+<li><p>The announcers public key</p></li>
+<li><p>Application specific data, in this case the users nickname and availability status</p></li>
+<li><p>A random blob, making each new announce unique</p></li>
+<li><p>An Ed25519 signature of the above information, verifying authenticity</p></li>
+</ul>
+<p>With this information, any Reticulum node that receives it will be able to reconstruct an outgoing
+destination to securely communicate with that destination. You might have noticed that there is one
+piece of information lacking to reconstruct full knowledge of the announced destination, and that is
+the aspect names of the destination. These are intentionally left out to save bandwidth, since they
+will be implicit in almost all cases. If a destination name is not entirely implicit, information can be
+included in the application specific data part that will allow the receiver to infer the naming.</p>
+<p>It is important to note that announces will be forwarded throughout the network according to a
+certain pattern. This will be detailed in the section
+<a class="reference internal" href="#understanding-announce"><span class="std std-ref">The Announce Mechanism in Detail</span></a>.</p>
+<p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p>
+</div>
+<div class="section" id="understanding-identities">
+<span id="identities"></span><h3>Identities<a class="headerlink" href="#understanding-identities" title="Permalink to this headline">¶</a></h3>
+<p>In Reticulum, an <em>identity</em> does not necessarily represent a personal identity, but is an abstraction that
+can represent any kind of <em>verified entity</em>. This could very well be a person, but it could also be the
+control interface of a machine, a program, robot, computer, sensor or something else entirely. In
+general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be
+represented as an identity.</p>
+<p>As we have seen, a <em>single</em> destination will always have an <em>identity</em> tied to it, but not <em>plain</em> or <em>group</em>
+destinations. Destinations and identities share a multilateral connection. You can create a
+destination, and if it is not connected to an identity upon creation, it will just create a new one to use
+automatically. This may be desirable in some situations, but often you will probably want to create
+the identity first, and then link it to created destinations.</p>
+<p>Building upon the simple messenger example, we could use an identity to represent the user of the
+application. Destinations created will then be linked to this identity to allow communication to
+reach the user. In all cases it is of great importance to store the private keys associated with any
+Reticulum Identity securely and privately.</p>
+</div>
+<div class="section" id="getting-further">
+<span id="understanding-gettingfurther"></span><h3>Getting Further<a class="headerlink" href="#getting-further" title="Permalink to this headline">¶</a></h3>
+<p>The above functions and principles form the core of Reticulum, and would suffice to create
+functional networked applications in local clusters, for example over radio links where all interested
+nodes can directly hear each other. But to be truly useful, we need a way to direct traffic over multiple
+hops in the network.</p>
+<p>In the following sections, two concepts that allow this will be introduced, <em>paths</em> and <em>links</em>.</p>
+</div>
+</div>
+<div class="section" id="reticulum-transport">
+<span id="understanding-transport"></span><h2>Reticulum Transport<a class="headerlink" href="#reticulum-transport" title="Permalink to this headline">¶</a></h2>
+<p>The term routing has been purposefully avoided until now. The current methods of routing used in IP-based
+networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle.
+These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than
+Reticulum can assume is available.</p>
+<p>Since Reticulum is designed to run over open radio spectrum, no such trust exists, and bandwidth is often
+very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
+useable over bandwidth-limited, high-latency links.</p>
+<p>To overcome such challenges, Reticulum’s <em>Transport</em> system uses public-key cryptography to
+implement the concept of <em>paths</em> that allow discovery of how to get information to a certain
+destination. It is important to note that no single node in a Reticulum network knows the complete
+path to a destination. Every Transport node participating in a Reticulum network will only
+know what the most direct way to get a packet one hop closer to it’s destination is.</p>
+<div class="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 headline">¶</a></h3>
+<p>When an <em>announce</em> is transmitted by a node, it will be forwarded by any node receiving it, but
+according to some specific rules:</p>
+<ul>
+<li><div class="line-block">
+<div class="line">If this exact announce has already been received before, ignore it.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">If not, record into a table which node the announce was received from, and how many times in
+total it has been retransmitted to get here.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">If the announce has been retransmitted <em>m+1</em> times, it will not be forwarded. By default, <em>m</em> is
+set to 18.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The announce will be assigned a delay <em>d</em> = c<sup>h</sup> seconds, where <em>c</em> is a decay constant, and <em>h</em> is the amount of times this packet has already been forwarded.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The packet will be given a priority <em>p = 1/d</em>.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">If at least <em>d</em> seconds has passed since the announce was received, and no other packets with a
+priority higher than <em>p</em> are waiting in the queue (see Packet Prioritisation), and the channel is
+not utilized by other traffic, the announce will be forwarded.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">If no other nodes are heard retransmitting the announce with a greater hop count than when
+it left this node, transmitting it will be retried <em>r</em> times. By default, <em>r</em> is set to 1. Retries
+follow same rules as above, with the exception that it must wait for at least <em>d</em> = c<sup>h+1</sup> +
+t + rand(0, rw) seconds. This amount of time is equal to the amount of time it would take the next
+node to retransmit the packet, plus a random window. By default, <em>t</em> is set to 10 seconds, and the
+random window <em>rw</em> is set to 10 seconds.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">If a newer announce from the same destination arrives, while an identical one is already in
+the queue, the newest announce is discarded. If the newest announce contains different
+application specific data, it will replace the old announce, but will use <em>d</em> and <em>p</em> of the old
+announce.</div>
+</div>
+</li>
+</ul>
+<p>Once an announce has reached a node in the network, any other node in direct contact with that
+node will be able to reach the destination the announce originated from, simply by sending a packet
+addressed to that destination. Any node with knowledge of the announce will be able to direct the
+packet towards the destination by looking up the next node with the shortest amount of hops to the
+destination.</p>
+<p>According to these rules and default constants, an announce will propagate throughout the network
+in a predictable way. In an example network utilising the default constants, and with an average link
+distance of <em>Lavg =</em> 15 kilometers, an announce will be able to propagate outwards to a radius of 180
+kilometers in 34 minutes, and a <em>maximum announce radius</em> of 270 kilometers in approximately 3
+days.</p>
+</div>
+<div class="section" id="reaching-the-destination">
+<span id="understanding-paths"></span><h3>Reaching the Destination<a class="headerlink" href="#reaching-the-destination" title="Permalink to this headline">¶</a></h3>
+<p>In networks with changing topology and trustless connectivity, nodes need a way to establish
+<em>verified connectivity</em> with each other. Since the network is assumed to be trustless, Reticulum
+must provide a way to guarantee that the peer you are communicating with is actually who you
+expect. Reticulum offers two ways to do this.</p>
+<p>For exchanges of small amounts of information, Reticulum offers the <em>Packet</em> API, which works exactly like you would expect - on a per packet level. The following process is employed when sending a packet:</p>
+<ul>
+<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>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">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 <em>announce</em>, and can thus perform the ECDH
+key exchange locally, before sending the packet.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The public part of the newly generated ephemeral key-pair is included with the encrypted token, and sent
+along with the encrypted payload data in the packet.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">When the destination receives the packet, it can itself perform an ECDH key exchange and decrypt the
+packet.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">A new ephemeral key is used for every packet sent in this way, and forward secrecy is guaranteed on a
+per packet level.</div>
+</div>
+</li>
+<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
+public signing key.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">In case the packet is addressed to a <em>group</em> destination type, the packet will be encrypted with the
+pre-shared AES-128 key associated with the destination. In case the packet is addressed to a <em>plain</em>
+destination type, the payload data will not be encrypted. Neither of these two destination types offer
+forward secrecy. In general, it is recommended to always use the <em>single</em> destination type, unless it is
+strictly necessary to use one of the others.</div>
+</div>
+</li>
+</ul>
+<p>For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the <em>Link</em> API. To establish a <em>link</em>, the following process is employed:</p>
+<ul>
+<li><div class="line-block">
+<div class="line">First, the node that wishes to establish a link will send out a special packet, that
+traverses the network and locates the desired destination. Along the way, the nodes that
+forward the packet will take note of this <em>link request</em>.</div>
+</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
+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>
+</li>
+<li><div class="line-block">
+<div class="line">When the validity of the <em>link</em> has been accepted by forwarding nodes, these nodes will
+remember the <em>link</em> , and it can subsequently be used by referring to a hash representing it.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">As a part of the <em>link request</em> , a Diffie-Hellman key exchange takes place, that sets up an
+efficiently encrypted tunnel between the two nodes, using elliptic curve cryptography. As such,
+this mode of communication is preferred, even for situations when nodes can directly communicate,
+when the amount of data to be exchanged numbers in the tens of packets.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">When a <em>link</em> has been set up, it automatically provides message receipt functionality, through
+the same <em>proof</em> mechanism discussed before, so the sending node can obtain verified confirmation
+that the information reached the intended recipient.</div>
+</div>
+</li>
+</ul>
+<p>In a moment, we will discuss the details of how this methodology is implemented, but let’s first
+recap what purposes this methodology serves. We first ensure that the node answering our request
+is actually the one we want to communicate with, and not a malicious actor pretending to be so.
+At the same time we establish an efficient encrypted channel. The setup of this is relatively cheap in
+terms of bandwidth, so it can be used just for a short exchange, and then recreated as needed, which will
+also rotate encryption keys. The link can also be kept alive for longer periods of time, if this is
+more suitable to the application. The procedure also inserts the <em>link id</em> , a hash calculated from the link request packet, into the memory of forwarding nodes, which means that the communicating nodes can thereafter reach each other simply by referring to this <em>link id</em>.</p>
+<p>The combined bandwidth cost of setting up a link is 3 packets totalling 237 bytes (more info in the
+<a class="reference internal" href="#understanding-packetformat"><span class="std std-ref">Binary Packet Format</span></a> section). The amount of bandwidth used on keeping
+a link open is practically negligible, at 0.62 bits per second. Even on a slow 1200 bits per second packet
+radio channel, 100 concurrent links will still leave 95% channel capacity for actual data.</p>
+<div class="section" id="link-establishment-in-detail">
+<h4>Link Establishment in Detail<a class="headerlink" href="#link-establishment-in-detail" title="Permalink to this headline">¶</a></h4>
+<p>After exploring the basics of the announce mechanism, finding a path through the network, and an overview
+of the link establishment procedure, this section will go into greater detail about the Reticulum link
+establishment process.</p>
+<p>The <em>link</em> in Reticulum terminology should not be viewed as a direct node-to-node link on the
+physical layer, but as an abstract channel, that can be open for any amount of time, and can span
+an arbitrary number of hops, where information will be exchanged between two nodes.</p>
+<ul>
+<li><div class="line-block">
+<div class="line">When a node in the network wants to establish verified connectivity with another node, it
+will randomly generate a new X25519 private/public key pair. It then creates a <em>link request</em>
+packet, and broadcast it.</div>
+<div class="line"><br /></div>
+<div class="line"><em>It should be noted that the X25519 public/private keypair mentioned above is two separate keypairs:
+An encryption key pair, used for derivation of a shared symmetric key, and a signing key pair, used
+for signing and verifying messages on the link. They are sent together over the wire, and can be
+considered as single public key for simplicity in this explanation.</em></div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The <em>link request</em> is addressed to the destination hash of the desired destination, and
+contains the following data: The newly generated X25519 public key <em>LKi</em>.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">The broadcasted packet will be directed through the network according to the rules laid out
+previously.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">Any node that forwards the link request will store a <em>link id</em> in it’s <em>link table</em> , along with the
+amount of hops the packet had taken when received. The link id is a hash of the entire link
+request packet. If the link request packet is not <em>proven</em> by the addressed destination within some
+set amount of time, the entry will be dropped from the <em>link table</em> again.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">When the destination receives the link request packet, it will decide whether to accept the request.
+If it is accepted, the destination will also generate a new X25519 private/public key pair, and
+perform a Diffie Hellman Key Exchange, deriving a new symmetric key that will be used to encrypt the
+channel, once it has been established.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">A <em>link proof</em> packet is now constructed and transmitted over the network. This packet is
+addressed to the <em>link id</em> of the <em>link</em>. It contains the following data: The newly generated X25519
+public key <em>LKr</em> and an Ed25519 signature of the <em>link id</em> and <em>LKr</em> made by the signing key of
+the addressed destination.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">By verifying this <em>link proof</em> packet, all nodes that originally transported the <em>link request</em>
+packet to the destination from the originator can now verify that the intended destination received
+the request and accepted it, and that the path they chose for forwarding the request was valid.
+In sucessfully carrying out this verification, the transporting nodes marks the link as active.
+An abstract bi-directional communication channel has now been established along a path in the network.</div>
+</div>
+</li>
+<li><div class="line-block">
+<div class="line">When the source receives the <em>proof</em> , it will know unequivocally that a verified path has been
+established to the destination. It can now also use the X25519 public key contained in the
+<em>link proof</em> to perform it’s own Diffie Hellman Key Exchange and derive the symmetric key
+that is used to encrypt the channel. Information can now be exchanged reliably and securely.</div>
+</div>
+</li>
+</ul>
+<p>It’s important to note that this methodology ensures that the source of the request does not need to
+reveal any identifying information about itself. The link initiator remains completely anonymous.</p>
+<p>When using <em>links</em>, Reticulum will automatically verify all data sent over the link, and can also
+automate retransmissions if <em>Resources</em> are used.</p>
+</div>
+</div>
+<div class="section" id="resources">
+<span id="understanding-resources"></span><h3>Resources<a class="headerlink" href="#resources" title="Permalink to this headline">¶</a></h3>
+<p>For exchanging small amounts of data over a Reticulum network, the <a class="reference internal" href="reference.html#api-packet"><span class="std std-ref">Packet</span></a> interface
+is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate
+the transfer is needed.</p>
+<p>This is the purpose of the Reticulum <a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resource</span></a>. A <em>Resource</em> can automatically
+handle the reliable transfer of an arbitrary amount of data over an established <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>.
+Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
+the transfer and reassembling the data on the other end.</p>
+<p><a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resources</span></a> are programmatically very simple to use, and only requires a few lines
+of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
+or stream data directly from files.</p>
+</div>
+</div>
+<div class="section" id="reference-system-setup">
+<span id="understanding-referencesystem"></span><h2>Reference System Setup<a class="headerlink" href="#reference-system-setup" title="Permalink to this headline">¶</a></h2>
+<p>This section will detail the recommended <em>Reference System Setup</em> for Reticulum. It is important to
+note that Reticulum is designed to be usable over more or less any medium that allows you to send
+and receive data in a digital form, and satisfies some very low minimum requirements. The
+communication channel must support at least half-duplex operation, and provide an average
+throughput of around 1000 bits per second, and supports a physical layer MTU of 500 bytes. The
+Reticulum software should be able to run on more or less any hardware that can provide a Python 3.x
+runtime environment.</p>
+<p>That being said, the reference setup has been outlined to provide a common platform for anyone
+who wants to help in the development of Reticulum, and for everyone who wants to know a
+recommended setup to get started. A reference system consists of three parts:</p>
+<ul class="simple">
+<li><dl class="simple">
+<dt><strong>A channel access device</strong></dt><dd><p>Or <em>CAD</em> , in short, provides access to the physical medium whereupon the communication
+takes place, for example a radio with an integrated modem. A setup with a separate modem
+connected to a radio would also be termed a “channel access device”.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>A host device</strong></dt><dd><p>Some sort of computing device that can run the necessary software, communicates with the
+channel access device, and provides user interaction.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>A software stack</strong></dt><dd><p>The software implementing the Reticulum protocol and applications using it.</p>
+</dd>
+</dl>
+</li>
+</ul>
+<p>The reference setup can be considered a relatively stable platform to develop on, and also to start
+building networks on. While details of the implementation might change at the current stage of
+development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
+the current reference setup has been determined to provide a functional platform for many years
+into the future. The current Reference System Setup is as follows:</p>
+<ul class="simple">
+<li><dl class="simple">
+<dt><strong>Channel Access Device</strong></dt><dd><p>A data radio consisting of a LoRa radio module, and a microcontroller with open source
+firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
+MHz frequency bands. More details can be found on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Host device</strong></dt><dd><p>Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
+recommended.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><strong>Software stack</strong></dt><dd><p>The current Reference Implementation Release of Reticulum, running on a Debian based
+operating system.</p>
+</dd>
+</dl>
+</li>
+</ul>
+<p>It is very important to note, that the reference channel access device <strong>does not</strong> use the LoRaWAN
+standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
+need a plain LoRa radio module connected to an MCU with the correct firmware. Full details on how to
+get or make such a device is available on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
+<p>With the current reference setup, it should be possible to get on a Reticulum network for around 100$
+even if you have none of the hardware already, and need to purchase everything.</p>
+</div>
+<div class="section" id="protocol-specifics">
+<span id="understanding-protocolspecifics"></span><h2>Protocol Specifics<a class="headerlink" href="#protocol-specifics" title="Permalink to this headline">¶</a></h2>
+<p>This chapter will detail protocol specific information that is essential to the implementation of
+Reticulum, but non critical in understanding how the protocol works on a general level. It should be
+treated more as a reference than as essential reading.</p>
+<div class="section" id="node-types">
+<h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this headline">¶</a></h3>
+<p>Currently Reticulum defines two node types, the <em>Station</em> and the <em>Peer</em>. A node is a <em>station</em> if it fixed
+in one place, and if it is intended to be kept online most of the time. Otherwise the node is a <em>peer</em>.
+This distinction is made by the user configuring the node, and is used to determine what nodes on the
+network will help forward traffic, and what nodes rely on other nodes for connectivity.</p>
+<p>If a node is a <em>Peer</em> it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">No</span></code>.</p>
+<p>If it is a <em>Station</em>, it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">Yes</span></code>.</p>
+</div>
+<div class="section" id="packet-prioritisation">
+<h3>Packet Prioritisation<a class="headerlink" href="#packet-prioritisation" title="Permalink to this headline">¶</a></h3>
+<p>Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
+on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
+times and priorities described earlier in this chapter.</p>
+<p>It is possible that a prioritisation engine could be added to Reticulum in the future, but in
+the light of Reticulums goal of equal access, doing so would need to be the subject of careful
+investigation of the consequences first.</p>
+</div>
+<div class="section" id="binary-packet-format">
+<span id="understanding-packetformat"></span><h3>Binary Packet Format<a class="headerlink" href="#binary-packet-format" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>== Reticulum Wire Format ======
+
+A Reticulum packet is composed of the following fields:
+
+[HEADER 2 bytes] [ADDRESSES 10/20 bytes] [CONTEXT 1 byte] [DATA 0-477 bytes]
+
+* The HEADER field is 2 bytes long.
+  * Byte 1: [Header Type], [Propagation Type], [Destination Type] and [Packet Type]
+  * Byte 2: Number of hops
+
+* The ADDRESSES field contains either 1 or 2 addresses.
+  * Each address is 10 bytes long.
+  * The Header Type flag in the HEADER field determines
+    whether the ADDRESSES field contains 1 or 2 addresses.
+  * Addresses are Reticulum hashes truncated to 10 bytes.
+
+* The CONTEXT field is 1 byte.
+  * It is used by Reticulum to determine packet context.
+
+* The DATA field is between 0 and 477 bytes.
+  * It contains the packets data payload.
+
+Header Types
+-----------------
+type 1          00  Two byte header, one 10 byte address field
+type 2          01  Two byte header, two 10 byte address fields
+type 3          10  Reserved
+type 4          11  Reserved
+
+
+Propagation Types
+-----------------
+broadcast       00
+transport       01
+reserved        10
+reserved        11
+
+
+Destination Types
+-----------------
+single          00
+group           01
+plain           10
+link            11
+
+
+Packet Types
+-----------------
+data            00
+announce        01
+link request    10
+proof           11
+
+
++- Packet Example -+
+
+   HEADER FIELD             ADDRESSES FIELD             CONTEXT FIELD  DATA FIELD
+ _______|_______   ________________|________________   ________|______   __|_
+|               | |                                 | |               | |    |
+01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
+ | | | |    |
+ | | | |    +-- Hops             = 4
+ | | | +------- Packet Type      = DATA
+ | | +--------- Destination Type = SINGLE
+ | +----------- Propagation Type = TRANSPORT
+ +------------- Header Type      = HEADER_2 (two byte header, two address fields)
+
+
+ +- Packet Example -+
+
+   HEADER FIELD    ADDRESSES FIELD    CONTEXT FIELD  DATA FIELD
+ _______|_______   _______|_______   ________|______   __|_
+|               | |               | |               | |    |
+00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]
+ | | | |    |
+ | | | |    +-- Hops             = 7
+ | | | +------- Packet Type      = DATA
+ | | +--------- Destination Type = SINGLE
+ | +----------- Propagation Type = BROADCAST
+ +------------- Header Type      = HEADER_1 (two byte header, one address field)
+
+
+ Size examples of different packet types
+ ---------------------------------------
+
+ The following table lists example sizes of various
+ packet types. The size listed are the complete on-
+ wire size including all fields.
+
+ - Path Request    :    33  bytes
+ - Announce        :    151 bytes
+ - Link Request    :    77  bytes
+ - Link Proof      :    77  bytes
+ - Link RTT packet :    83  bytes
+ - Link keepalive  :    14  bytes
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Understanding Reticulum</a><ul>
+<li><a class="reference internal" href="#motivation">Motivation</a></li>
+<li><a class="reference internal" href="#goals">Goals</a></li>
+<li><a class="reference internal" href="#introduction-basic-functionality">Introduction &amp; Basic Functionality</a><ul>
+<li><a class="reference internal" href="#destinations">Destinations</a><ul>
+<li><a class="reference internal" href="#destination-naming">Destination Naming</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#public-key-announcements">Public Key Announcements</a></li>
+<li><a class="reference internal" href="#understanding-identities">Identities</a></li>
+<li><a class="reference internal" href="#getting-further">Getting Further</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reticulum-transport">Reticulum Transport</a><ul>
+<li><a class="reference internal" href="#the-announce-mechanism-in-detail">The Announce Mechanism in Detail</a></li>
+<li><a class="reference internal" href="#reaching-the-destination">Reaching the Destination</a><ul>
+<li><a class="reference internal" href="#link-establishment-in-detail">Link Establishment in Detail</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#resources">Resources</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reference-system-setup">Reference System Setup</a></li>
+<li><a class="reference internal" href="#protocol-specifics">Protocol Specifics</a><ul>
+<li><a class="reference internal" href="#node-types">Node Types</a></li>
+<li><a class="reference internal" href="#packet-prioritisation">Packet Prioritisation</a></li>
+<li><a class="reference internal" href="#binary-packet-format">Binary Packet Format</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="interfaces.html"
+                        title="previous chapter">Supported Interfaces</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="reference.html"
+                        title="next chapter">API Reference</a></p>
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/understanding.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="reference.html" title="API Reference"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="interfaces.html" title="Supported Interfaces"
+             >previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Understanding Reticulum</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2021, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/using.html

@@ -0,0 +1,258 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Using Reticulum on Your System &#8212; Reticulum Network Stack 0.2.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <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/doctools.js"></script>
+    
+    <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="Getting Started Fast" href="gettingstartedfast.html" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="networks.html" title="Building Networks"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="gettingstartedfast.html" title="Getting Started Fast"
+             accesskey="P">previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Using Reticulum on Your System</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="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 headline">¶</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.
+Any program or application that uses Reticulum will automatically load and
+initialise Reticulum when it starts.</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 Reticulum. 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 concurrently, and is
+very easy to use, but depending on your use case, there are other options.</p>
+<div class="section" id="included-utility-programs">
+<h2>Included Utility Programs<a class="headerlink" href="#included-utility-programs" title="Permalink to this headline">¶</a></h2>
+<p>If you often use Reticulum from several different programs, or simply want
+Reticulum to stay available all the time, for example if you are hosting
+a transport node, you might want to run Reticulum as a separate service that
+other programs, applications and services can utilise.</p>
+<div class="section" id="the-rnsd-utility">
+<h3>The rnsd Utility<a class="headerlink" href="#the-rnsd-utility" title="Permalink to this headline">¶</a></h3>
+<p>To do so is very easy. Simply run the included <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> command. When <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>
+is running, it will keep all configured interfaces open, handle transport if
+it is enabled, and allow any other programs to immediately utilise the
+Reticulum network it is configured for.</p>
+<p>You can even run multiple instances of rnsd with different configurations on
+the same system.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Install Reticulum
+pip3 install rns
+
+# Run rnsd
+rnsd
+</pre></div>
+</div>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version]
+
+Reticulum Network Stack Daemon
+
+optional arguments:
+  -h, --help       show this help message and exit
+  --config CONFIG  path to alternative Reticulum config directory
+  -v, --verbose
+  -q, --quiet
+  --version        show program&#39;s version number and exit
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-rnstatus-utility">
+<h3>The rnstatus Utility<a class="headerlink" href="#the-rnstatus-utility" title="Permalink to this headline">¶</a></h3>
+<p>Using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility, you can view the status of configured Reticulum
+interfaces, similar to the <code class="docutils literal notranslate"><span class="pre">ifconfig</span></code> program.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnstatus
+rnstatus
+
+# Example output
+Shared Instance[37428]
+       Status: Up
+       Connected applications: 1
+       RX: 1.13 KB
+       TX: 1.07 KB
+
+UDPInterface[Default UDP Interface/0.0.0.0:4242]
+       Status: Up
+       RX: 1.01 KB
+       TX: 1.01 KB
+
+TCPInterface[RNS Testnet Frankfurt/frankfurt.rns.unsigned.io:4965]
+       Status: Up
+       RX: 1.37 KB
+       TX: 9.02 KB
+</pre></div>
+</div>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version]
+
+Reticulum Network Stack Daemon
+
+optional arguments:
+  -h, --help       show this help message and exit
+  --config CONFIG  path to alternative Reticulum config directory
+  -v, --verbose
+  -q, --quiet
+  --version        show program&#39;s version number and exit
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-rnpath-utility">
+<h3>The rnpath Utility<a class="headerlink" href="#the-rnpath-utility" title="Permalink to this headline">¶</a></h3>
+<p>With the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility, you can look up and view paths for
+destinations on the Reticulum network.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnpath
+rnpath eca6f4e4dc26ae329e61
+
+# Example output
+Path found, destination &lt;eca6f4e4dc26ae329e61&gt; is 4 hops away via &lt;56b115c30cd386cad69c&gt; on TCPInterface[Testnet/frankfurt.rns.unsigned.io:4965]
+</pre></div>
+</div>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnpath.py [-h] [--config CONFIG] [--version] [-v] [destination]
+
+Reticulum Path Discovery Utility
+
+positional arguments:
+  destination      hexadecimal hash of the destination
+
+optional arguments:
+  -h, --help       show this help message and exit
+  --config CONFIG  path to alternative Reticulum config directory
+  --version        show program&#39;s version number and exit
+  -v, --verbose
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-rnprobe-utility">
+<h3>The rnprobe Utility<a class="headerlink" href="#the-rnprobe-utility" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">rnprobe</span></code> utility lets you probe a destination for connectivity, similar
+to the <code class="docutils literal notranslate"><span class="pre">ping</span></code> program. Please note that probes will only be answered if the
+specified destination is configured to send proofs for received packets. Many
+destinations will not have this option enabled, and will not be probable.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnprobe
+python3 -m RNS.Utilities.rnprobe example_utilities.echo.request 9382f334de63217a4278
+
+# Example output
+Sent 16 byte probe to &lt;9382f334de63217a4278&gt;
+Valid reply received from &lt;9382f334de63217a4278&gt;
+Round-trip time is 38.469 milliseconds over 2 hops
+</pre></div>
+</div>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnprobe.py [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash]
+
+Reticulum Probe Utility
+
+positional arguments:
+  full_name         full destination name in dotted notation
+  destination_hash  hexadecimal hash of the destination
+
+optional arguments:
+  -h, --help        show this help message and exit
+  --config CONFIG   path to alternative Reticulum config directory
+  --version         show program&#39;s version number and exit
+  -v, --verbose
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Using Reticulum on Your System</a><ul>
+<li><a class="reference internal" href="#included-utility-programs">Included Utility Programs</a><ul>
+<li><a class="reference internal" href="#the-rnsd-utility">The rnsd Utility</a></li>
+<li><a class="reference internal" href="#the-rnstatus-utility">The rnstatus Utility</a></li>
+<li><a class="reference internal" href="#the-rnpath-utility">The rnpath Utility</a></li>
+<li><a class="reference internal" href="#the-rnprobe-utility">The rnprobe Utility</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="gettingstartedfast.html"
+                        title="previous chapter">Getting Started Fast</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="networks.html"
+                        title="next chapter">Building Networks</a></p>
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/using.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="networks.html" title="Building Networks"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="gettingstartedfast.html" title="Getting Started Fast"
+             >previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">Using Reticulum on Your System</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2021, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/manual/whatis.html

@@ -0,0 +1,196 @@
+
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>What is Reticulum? &#8212; Reticulum Network Stack 0.2.8 beta documentation</title>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
+    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
+    
+    <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/doctools.js"></script>
+    
+    <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" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="gettingstartedfast.html" title="Getting Started Fast"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="index.html" title="Reticulum Network Stack Manual"
+             accesskey="P">previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">What is Reticulum?</a></li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="section" id="what-is-reticulum">
+<h1>What is Reticulum?<a class="headerlink" href="#what-is-reticulum" title="Permalink to this headline">¶</a></h1>
+<p>Reticulum is a cryptography-based networking stack for wide-area networks built on readily available hardware, and can operate even with very high latency and extremely low bandwidth.</p>
+<p>Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more.</p>
+<p>Reticulum is a complete networking stack, and does not need IP or higher layers, although it is easy to utilise IP (with TCP or UDP) as the underlying carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks. Reticulum is built directly on cryptographic principles, allowing resilience and stable functionality in open and trustless networks.</p>
+<p>No kernel modules or drivers are required. Reticulum runs completely in userland, and can run on practically any system that runs Python 3. Reticulum runs well even on small single-board computers like the Pi Zero.</p>
+<div class="section" id="current-status">
+<h2>Current Status<a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>Reticulum should currently be considered beta software. All core protocol 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.</p>
+</div>
+<div class="section" id="caveat-emptor">
+<h2>Caveat Emptor<a class="headerlink" href="#caveat-emptor" title="Permalink to this headline">¶</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 privacy-breaking bugs. To be considered secure, Reticulum needs a thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch.</p>
+</div>
+<div class="section" id="what-does-reticulum-offer">
+<h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><p>Coordination-less globally unique adressing and identification</p></li>
+<li><p>Fully self-configuring multi-hop routing</p></li>
+<li><p>Complete initiator anonymity, communicate without revealing your identity</p></li>
+<li><p>Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication</p></li>
+<li><p>Forward Secrecy with ephemereal Elliptic Curve Diffie-Hellman keys on Curve25519</p></li>
+<li><p>Reticulum uses the <a class="reference external" href="https://github.com/fernet/spec/blob/master/Spec.md">Fernet</a> specification for on-the-wire / over-the-air encryption</p>
+<ul>
+<li><p>All keys are ephemeral and derived from an ECDH key exchange on Curve25519</p></li>
+<li><p>AES-128 in CBC mode with PKCS7 padding</p></li>
+<li><p>HMAC using SHA256 for authentication</p></li>
+<li><p>IVs are generated through os.urandom()</p></li>
+</ul>
+</li>
+<li><p>Unforgeable packet delivery confirmations</p></li>
+<li><p>A variety of supported interface types</p></li>
+<li><p>An intuitive and developer-friendly API</p></li>
+<li><p>Reliable and efficient transfer of arbritrary amounts of data</p>
+<ul>
+<li><p>Reticulum can handle a few bytes of data or files of many gigabytes</p></li>
+<li><p>Sequencing, transfer coordination and checksumming is automatic</p></li>
+<li><p>The API is very easy to use, and provides transfer progress</p></li>
+</ul>
+</li>
+<li><p>Efficient link establishment</p>
+<ul>
+<li><p>Total bandwidth cost of setting up a link is only 3 packets, totalling 237 bytes</p></li>
+<li><p>Low cost of keeping links open at only 0.62 bits per second</p></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="where-can-reticulum-be-used">
+<h2>Where can Reticulum be Used?<a class="headerlink" href="#where-can-reticulum-be-used" title="Permalink to this headline">¶</a></h2>
+<p>Over practically any medium that can support at least a half-duplex channel
+with 500 bits per second throughput, and an MTU of 500 bytes. Data radios,
+modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes,
+ad-hoc WiFi, free-space optical links and similar systems are all examples
+of the types of interfaces Reticulum was designed for.</p>
+<p>An open-source LoRa-based interface called <a class="reference external" href="https://unsigned.io/rnode">RNode</a>
+has been designed specifically for use with Reticulum. It is possible to build
+yourself, or it can be purchased as a complete transceiver that just needs a
+USB connection to the host.</p>
+<p>Reticulum can also be encapsulated over existing IP networks, so there’s
+nothing stopping you from using it over wired ethernet or your local WiFi
+network, where it’ll work just as well. In fact, one of the strengths of
+Reticulum is how easily it allows you to connect different mediums into a
+self-configuring, resilient and encrypted mesh.</p>
+<p>As an example, it’s possible to set up a Raspberry Pi connected to both a
+LoRa radio, a packet radio TNC and a WiFi network. Once the interfaces are
+configured, Reticulum will take care of the rest, and any device on the WiFi
+network can communicate with nodes on the LoRa and packet radio sides of the
+network, and vice versa.</p>
+</div>
+<div class="section" id="interface-types-and-devices">
+<h2>Interface Types and Devices<a class="headerlink" href="#interface-types-and-devices" title="Permalink to this headline">¶</a></h2>
+<p>Reticulum implements a range of generalised interface types that covers most of the communications hardware that Reticulum can run over. If your hardware is not supported, it’s relatively simple to implement an interface class. Currently, the following interfaces are supported:</p>
+<ul class="simple">
+<li><p>Any ethernet device</p></li>
+<li><p>LoRa using <a class="reference external" href="https://unsigned.io/rnode">RNode</a></p></li>
+<li><p>Packet Radio TNCs, such as <a class="reference external" href="https://unsigned.io/openmodem">OpenModem</a></p></li>
+<li><p>Any device with a serial port</p></li>
+<li><p>TCP over IP networks</p></li>
+<li><p>UDP over IP networks</p></li>
+</ul>
+<p>For a full list and more details, see the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Supported Interfaces</span></a> chapter.</p>
+</div>
+</div>
+
+
+            <div class="clearer"></div>
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">What is Reticulum?</a><ul>
+<li><a class="reference internal" href="#current-status">Current Status</a></li>
+<li><a class="reference internal" href="#caveat-emptor">Caveat Emptor</a></li>
+<li><a class="reference internal" href="#what-does-reticulum-offer">What does Reticulum Offer?</a></li>
+<li><a class="reference internal" href="#where-can-reticulum-be-used">Where can Reticulum be Used?</a></li>
+<li><a class="reference internal" href="#interface-types-and-devices">Interface Types and Devices</a></li>
+</ul>
+</li>
+</ul>
+
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="index.html"
+                        title="previous chapter">Reticulum Network Stack Manual</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="gettingstartedfast.html"
+                        title="next chapter">Getting Started Fast</a></p>
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/whatis.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" />
+      <input type="submit" value="Go" />
+    </form>
+    </div>
+</div>
+<script>$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="gettingstartedfast.html" title="Getting Started Fast"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="index.html" title="Reticulum Network Stack Manual"
+             >previous</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">Reticulum Network Stack 0.2.8 beta documentation</a> &#187;</li>
+        <li class="nav-item nav-item-this"><a href="">What is Reticulum?</a></li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2021, Mark Qvist.
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1.
+    </div>
+  </body>
+</html>

docs/source/conf.py

@@ -0,0 +1,68 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Reticulum Network Stack'
+copyright = '2021, Mark Qvist'
+author = 'Mark Qvist'
+
+# The full version, including alpha/beta/rc tags
+release = '0.2.8 beta'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    #'sphinx.ext.autosectionlabel',
+]
+
+autodoc_member_order = 'bysource'
+#latex_toplevel_sectioning = 'section'
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'classic'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+# def check_skip_member(app, what, name, obj, skip, options):
+#     print(what, " | ", name, " | ", obj, " | ", skip, " | ", options)
+#     return False
+
+# def setup(app):
+#     app.connect('autodoc-skip-member', check_skip_member)

docs/source/examples.rst

@@ -0,0 +1,106 @@
+.. _examples-main:
+
+*************
+Code Examples
+*************
+
+A number of examples are included in the source distribution of Reticulum.
+You can use these examples to learn how to write your own programs.
+
+.. _example-minimal:
+
+Minimal
+=======
+
+The *Minimal* example demonstrates the bare-minimum setup required to connect to
+a Reticulum network from your program. In about five lines of code, you will
+have the Reticulum Network Stack initialised, and ready to pass traffic in your
+program.
+
+.. literalinclude:: ../../Examples/Minimal.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py>`_.
+
+.. _example-announce:
+
+Announce
+========
+
+The *Announce* example builds upon the previous example by exploring how to
+announce a destination on the network, and how to let your program receive
+notifications about announces from relevant destinations.
+
+.. literalinclude:: ../../Examples/Announce.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py>`_.
+
+.. _example-broadcast:
+
+Broadcast
+=========
+The *Broadcast* example explores how to transmit plaintext broadcast messages
+over the network.
+
+.. literalinclude:: ../../Examples/Broadcast.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py>`_.
+
+.. _example-echo:
+
+Echo
+====
+
+The *Echo* example demonstrates communication between two destinations using
+the Packet interface.
+
+.. literalinclude:: ../../Examples/Echo.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py>`_.
+
+.. _example-link:
+
+Link
+====
+
+The *Link* example explores establishing an encrypted link to a remote
+destination, and passing traffic back and forth over the link.
+
+.. literalinclude:: ../../Examples/Link.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py>`_.
+
+.. _example-identify:
+
+Identification
+==============
+
+The *Identify* example explores identifying an intiator of a link, once
+the link has been established.
+
+.. literalinclude:: ../../Examples/Identify.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Identify.py>`_.
+
+.. _example-request:
+
+Requests & Responses
+====================
+
+The *Request* example explores sendig requests and receiving responses.
+
+.. literalinclude:: ../../Examples/Request.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py>`_.
+
+.. _example-filetransfer:
+
+Filetransfer
+============
+
+The *Filetransfer* example implements a basic file-server program that
+allow clients to connect and download files. The program uses the Resource
+interface to efficiently pass files of any size over a Reticulum :ref:`Link<api-link>`.
+
+.. literalinclude:: ../../Examples/Filetransfer.py
+
+This example can also be found at `<https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py>`_.

docs/source/gettingstartedfast.rst

@@ -0,0 +1,123 @@
+********************
+Getting Started Fast
+********************
+
+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.
+
+Try Using a Reticulum-based Program
+=============================================
+If you simply want to try using a program built with Reticulum, you can take
+a look at `Nomad Network <https://github.com/markqvist/nomadnet>`_, which
+provides a complete encrypted communications suite built with Reticulum.
+
+.. image:: screenshots/nomadnet_3.png
+    :target: _images/nomadnet_3.png
+
+`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
+in the development for the messaging and information-sharing protocol
+`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
+
+You can install Nomad Network via pip:
+
+.. code::
+
+   # Install ...
+   pip3 install nomadnet
+
+   # ... and run
+   nomadnet
+
+
+
+Using the Included Utilities
+=============================================
+Reticulum comes with a range of included utilities that make it easier to
+manage your network, check connectivity and make Reticulum available to other
+programs on your system.
+
+You can use ``rnsd`` to run Reticulum as a background or foreground service,
+and the ``rnstatus``, ``rnpath`` and ``rnprobe`` utilities to view and query
+network status and connectivity.
+
+To learn more about these utility programs, have a look at the
+:ref:`Using Reticulum on Your System<using-main>` chapter of this manual.
+
+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``.
+
+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 network (if there is one), and only allows you to
+communicate with other Reticulum peers within your local broadcast domain.
+
+To communicate further, you will have to add one or more interfaces. The default
+configuration includes a number of examples, ranging from using TCP over the
+internet, to LoRa and Packet Radio interfaces.
+
+Possibly, the examples in the config file are enough to get you started. If
+you want more information, you can read the :ref:`Building Networks<networks-main>`
+and :ref:`Interfaces<interfaces-main>` chapters of this manual.
+
+
+Develop a Program with Reticulum
+===========================================
+If you want to develop programs that use Reticulum, the easiest way to get
+started is to install the latest release of Reticulum via pip:
+
+.. code::
+
+   pip3 install rns
+
+The above command will install Reticulum and dependencies, and you will be
+ready to import and use RNS in your own programs. The next step will most
+likely be to look at some :ref:`Example Programs<examples-main>`.
+
+Further information can be found in the :ref:`API Reference<api-main>`.
+
+
+Participate in Reticulum Development
+==============================================
+If you want to participate in the development of Reticulum and associated
+utilities, you'll want to get the latest source from GitHub. In that case,
+don't use pip, but try this recipe:
+
+.. code::
+
+    # Install dependencies
+    pip3 install cryptography pyserial netifaces
+
+    # Clone repository
+    git clone https://github.com/markqvist/Reticulum.git
+
+    # Move into Reticulum folder and symlink library to examples folder
+    cd Reticulum
+    ln -s ../RNS ./Examples/
+
+    # Run an example
+    python3 Examples/Echo.py -s
+
+    # Unless you've manually created a config file, Reticulum will do so now,
+    # and immediately exit. Make any necessary changes to the file:
+    nano ~/.reticulum/config
+
+    # ... and launch the example again.
+    python3 Examples/Echo.py -s
+
+    # You can now repeat the process on another computer,
+    # and run the same example with -h to get command line options.
+    python3 Examples/Echo.py -h
+
+    # Run the example in client mode to "ping" the server.
+    # Replace the hash below with the actual destination hash of your server.
+    python3 Examples/Echo.py 3e12fc71692f8ec47bc5
+
+    # Have a look at another example
+    python3 Examples/Filetransfer.py -h
+
+When you have experimented with the basic examples, it's time to go read the
+:ref:`Understanding Reticulum<understanding-main>` chapter.

docs/source/index.rst

@@ -0,0 +1,25 @@
+******************************
+Reticulum Network Stack Manual
+******************************
+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.
+
+.. toctree::
+   :maxdepth: 3
+
+   whatis
+   gettingstartedfast
+   using
+   networks
+   interfaces
+   understanding
+   reference
+   examples
+
+
+Indices and Tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

docs/source/interfaces.rst

@@ -0,0 +1,346 @@
+
+.. _interfaces-main:
+
+********************
+Supported Interfaces
+********************
+
+Reticulum supports using many kinds of devices as networking interfaces, and
+allows you to mix and match them in any way you choose. The number of distinct
+network topologies you can create with Reticulum is more or less endless, but
+common to them all is that you will need to define one or more *interfaces*
+for Reticulum to use.
+
+The following sections describe the interfaces currently available in Reticulum,
+and gives example configurations for the respective interface types.
+
+For a high-level overview of how networks can be formed over different interface
+types, have a look at the :ref:`Building Networks<networks-main>` chapter of this
+manual.
+
+.. _interfaces-udp:
+
+UDP Interface
+=============
+
+A UDP interface can be useful for communicating over IP networks, both
+private and the internet. It can also allow broadcast communication
+over IP networks, so it can provide an easy way to enable connectivity
+with all other peers on a local area network.
+
+The below example is enabled by default on new Reticulum installations,
+as it provides an easy way to get started and to test Reticulum on a
+pre-existing LAN.
+
+.. code::
+
+  # This example enables communication with other
+  # local Reticulum peers over UDP.
+  
+  [[Default UDP Interface]]
+    type = UDPInterface
+    interface_enabled = True
+    outgoing = True
+    listen_ip = 0.0.0.0
+    listen_port = 4242
+    forward_ip = 255.255.255.255
+    forward_port = 4242
+
+    # The above configuration will allow communication
+    # within the local broadcast domains of all local
+    # IP interfaces. This is enabled by default as an
+    # easy way to get started, but you might want to
+    # consider altering it to something more specific.
+
+    # Instead of specifying listen_ip, listen_port,
+    # forward_ip and forward_port, you can also bind
+    # to a specific network device like below.
+
+    # device = eth0
+    # port = 4242
+
+    # Assuming the eth0 device has the address
+    # 10.55.0.72/24, the above configuration would
+    # be equivalent to the following manual setup.
+    # Note that we are both listening and forwarding to
+    # the broadcast address of the network segments.
+
+    # listen_ip = 10.55.0.255
+    # listen_port = 4242
+    # forward_ip = 10.55.0.255
+    # forward_port = 4242
+
+    # You can of course also communicate only with
+    # a single IP address
+
+    # listen_ip = 10.55.0.15
+    # listen_port = 4242
+    # forward_ip = 10.55.0.16
+    # forward_port = 4242
+
+.. _interfaces-tcps:
+
+TCP Server Interface
+====================
+
+The TCP Server interface is suitable for allowing other peers to connect over
+the Internet or private IP networks. When a TCP server interface has been
+configured, other Reticulum peers can connect to it with a TCP Client interface.
+
+.. code::
+
+  # This example demonstrates a TCP server interface.
+  # It will listen for incoming connections on the
+  # specified IP address and port number.
+  
+  [[TCP Server Interface]]
+    type = TCPServerInterface
+    interface_enabled = True
+    outgoing = True
+
+    # This configuration will listen on all IP
+    # interfaces on port 4242
+    
+    listen_ip = 0.0.0.0
+    listen_port = 4242
+
+    # Alternatively you can bind to a specific IP
+    
+    # listen_ip = 10.0.0.88
+    # listen_port = 4242
+
+    # Or a specific network device
+    
+    # device = eth0
+    # port = 4242
+
+
+.. _interfaces-tcpc:
+
+TCP Client Interface
+====================
+
+To connect to a TCP server interface, you would naturally use the TCP client
+interface. Many TCP Client interfaces from different peers can connect to the
+same TCP Server interface at the same time.
+
+.. code::
+
+  # Here's an example of a TCP Client interface. The
+  # target_host can either be an IP address or a hostname.
+
+  [[TCP Client Interface]]
+    type = TCPClientInterface
+    interface_enabled = True
+    outgoing = True
+    target_host = 127.0.0.1
+    target_port = 4242
+
+
+.. _interfaces-rnode:
+
+RNode LoRa Interface
+====================
+
+To use Reticulum over LoRa, the `RNode <https://unsigned.io/rnode/>`_ interface
+can be used, and offers full control over LoRa parameters.
+
+.. code::
+
+  # Here's an example of how to add a LoRa interface
+  # using the RNode LoRa transceiver.
+
+  [[RNode LoRa Interface]]
+    type = RNodeInterface
+
+    # Enable interface if you want use it!
+    interface_enabled = True
+
+    # Allow transmit on interface. Setting
+    # this to false will create a listen-
+    # only interface.
+    outgoing = true
+
+    # Serial port for the device
+    port = /dev/ttyUSB0
+
+    # Set frequency to 867.2 MHz
+    frequency = 867200000
+
+    # Set LoRa bandwidth to 125 KHz
+    bandwidth = 125000
+
+    # Set TX power to 7 dBm (5 mW)
+    txpower = 7
+
+    # Select spreading factor 8. Valid 
+    # range is 7 through 12, with 7
+    # being the fastest and 12 having
+    # the longest range.
+    spreadingfactor = 8
+
+    # Select coding rate 5. Valid range
+    # is 5 throough 8, with 5 being the
+    # fastest, and 8 the longest range.
+    codingrate = 5
+
+    # You can configure the RNode to send
+    # out identification on the channel with
+    # a set interval by configuring the
+    # following two parameters.
+    # id_callsign = MYCALL-0
+    # id_interval = 600
+
+    # For certain homebrew RNode interfaces
+    # with low amounts of RAM, using packet
+    # flow control can be useful. By default
+    # it is disabled.
+    flow_control = False
+
+.. _interfaces-serial:
+
+Serial Interface
+================
+
+Reticulum can be used over serial ports directly, or over any device with a
+serial port, that will transparently pass data. Useful for communicating
+directly over a wire-pair, or for using devices such as data radios and lasers.
+
+.. code::
+
+  [[Serial Interface]]
+    type = SerialInterface
+    interface_enabled = True
+    outgoing = True
+
+    # Serial port for the device
+    port = /dev/ttyUSB0
+
+    # Set the serial baud-rate and other
+    # configuration parameters.
+    speed = 115200
+    databits = 8
+    parity = none
+    stopbits = 1
+
+.. _interfaces-kiss:
+
+KISS Interface
+==============
+
+With the KISS interface, you can use Reticulum over a variety of packet
+radio modems and TNCs, including `OpenModem <https://unsigned.io/openmodem/>`_.
+KISS interfaces can also be configured to periodically send out beacons
+for station identification purposes.
+
+.. code::
+
+  [[Packet Radio KISS Interface]]
+    type = KISSInterface
+    interface_enabled = True
+    outgoing = true
+
+    # Serial port for the device
+    port = /dev/ttyUSB1
+
+    # Set the serial baud-rate and other
+    # configuration parameters.
+    speed = 115200    
+    databits = 8
+    parity = none
+    stopbits = 1
+
+    # Set the modem preamble.
+    preamble = 150
+
+    # Set the modem TX tail.
+    txtail = 10
+
+    # Configure CDMA parameters. These
+    # settings are reasonable defaults.
+    persistence = 200
+    slottime = 20
+
+    # You can configure the interface to send
+    # out identification on the channel with
+    # a set interval by configuring the
+    # following two parameters. The KISS
+    # interface will only ID if the set
+    # interval has elapsed since it's last
+    # actual transmission. The interval is
+    # configured in seconds.
+    # This option is commented out and not
+    # used by default.
+    # id_callsign = MYCALL-0
+    # id_interval = 600
+
+    # Whether to use KISS flow-control.
+    # This is useful for modems that have
+    # a small internal packet buffer, but
+    # support packet flow control instead.
+    flow_control = false
+
+.. _interfaces-ax25:
+
+AX.25 KISS Interface
+====================
+
+If you're using Reticulum on amateur radio spectrum, you might want to
+use the AX.25 KISS interface. This way, Reticulum will automatically
+encapsulate it's traffic in AX.25 and also identify your stations
+transmissions with your callsign and SSID. 
+
+Only do this if you really need to! Reticulum doesn't need the AX.25
+layer for anything, and it incurs extra overhead on every packet to
+encapsulate in AX.25.
+
+A more efficient way is to use the plain KISS interface with the
+beaconing functionality described above.
+
+.. code::
+
+  [[Packet Radio AX.25 KISS Interface]]
+    type = AX25KISSInterface
+
+    # Set the station callsign and SSID
+    callsign = NO1CLL
+    ssid = 0
+
+    # Enable interface if you want use it!
+    interface_enabled = True
+
+    # Allow transmit on interface.
+    outgoing = True
+
+    # Serial port for the device
+    port = /dev/ttyUSB2
+
+    # Set the serial baud-rate and other
+    # configuration parameters.
+    speed = 115200    
+    databits = 8
+    parity = none
+    stopbits = 1
+
+    # Set the modem preamble. A 150ms
+    # preamble should be a reasonable
+    # default, but may need to be
+    # increased for radios with slow-
+    # opening squelch and long TX/RX
+    # turnaround
+    preamble = 150
+
+    # Set the modem TX tail. In most
+    # cases this should be kept as low
+    # as possible to not waste airtime.
+    txtail = 10
+
+    # Configure CDMA parameters. These
+    # settings are reasonable defaults.
+    persistence = 200
+    slottime = 20
+
+    # Whether to use KISS flow-control.
+    # This is useful for modems with a
+    # small internal packet buffer.
+    flow_control = false

docs/source/networks.rst

@@ -0,0 +1,150 @@
+.. _networks-main:
+
+*****************
+Building Networks
+*****************
+
+This chapter will provide you with the knowledge needed to build networks with
+Reticulum, which can often be easier than using traditional stacks, since you
+don't have to worry about coordinating addresses, subnets and routing for an
+entire network that you might not know how will evolve in the future. With
+Reticulum, you can simply add more segments to your network when it becomes
+necesarry, and Reticulum will handle the convergence of the entire network
+automatically.
+
+Concepts & Overview
+--------------------
+
+There are important points that need to be kept in mind when building networks
+with Reticulum:
+
+ * | In a Reticulum network, any node can autonomously generate as many adresses
+     (called *destinations* in Reticulum terminology) as it needs, which become
+     globally reachable to the rest of the network. There is no central point of
+     control over the adress space.
+
+ * | Reticulum was designed to handle both very small, and very large networks.
+     While the adress space can support billions of endpoints, Reticulum is
+     also very useful when just a few devices needs to communicate.
+
+ * | Reticulum provides sender/initiator anonymity by default. There is no way
+     to filter traffic or discriminate it based on the source of the traffic.
+
+ * | All traffic is encrypted using ephemeral keys generated by an Elliptic Curve
+     Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic
+     contents, and no way to prioritise or throttle certain kinds of traffic.
+     All transport and routing layers are thus completely agnostic to traffic type,
+     and will pass all traffic equally.
+
+ * | Reticulum can function both with and without infrastructure. When *transport
+     nodes* are available, they can route traffic over multiple hops for other
+     nodes, and will function as a distributed cryptographic keystore. When there
+     is no transport nodes available, all nodes that are within communication range
+     can still communicate.
+
+ * | Every node can become a transport node, simply by enabling it in it's
+     configuration, but there is no need for every node on the network to be a
+     transport node. Letting every node be a transport node will in most cases
+     degrade the performance and reliability of the network.
+
+     In general terms, if a node is stationary, well-connected and kept running
+     most of the time, it is a good candidate to be a transport node. For optimal
+     performance, a network should contain the amount of transport nodes that
+     provides connectivity to the intended area / topography, and not many more
+     than that. 
+
+
+Reticulum allows you to mix very different kinds of networking mediums into a
+unified mesh, or to keep everything within one medium. You could build a "virtual
+network" running entirely over the Internet, where all nodes communicate over TCP
+and UDP "channels". You could also build such a network using MQTT or ZeroMQ as
+the underlying carrier for Reticulum.
+
+However, most real-world networks will probably involve either some form of
+wireless or direct hardline communications. To allow Reticulum to communicate
+over any type of medium, you must specify it in the configuration file, by default
+located at ``~/.reticulum/config``. See the :ref:`Supported Interfaces<interfaces-main>`
+chapter of this manual for interface configuration examples.
+
+Any number of interfaces can be configured, and Reticulum will automatically
+decide which are suitable to use in any given situation, depending on where
+traffic needs to flow.
+
+Example Scenarios
+-----------------
+
+This section illustrates a few example scenarios, and how they would, in general
+terms, be planned, implemented and configured.
+
+Interconnected LoRa Sites
+=========================
+
+An organisation wants to provide communication and information services to it's
+members, which are located mainly in three separate areas. Three suitable hill-top
+locations are found, where the organisation can install equipment: Site A, B and C.
+
+Since the amount of data that needs to be exchanged between users is mainly text-
+based, the bandwidth requirements are low, and LoRa radios are chosen to connect
+users to the network.
+
+Due to the hill-top locations found, there is radio line-of-sight between site A
+and B, and also between site B and C. Because of this, the organisation does not
+need to use the Internet to interconnect the sites, but purchases four Point-to-Point
+WiFi based radios for interconnecting the sites.
+
+At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio
+is connected to the Pi with a USB cable, and the WiFi radio is connected to the
+ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach
+both site A and site C, so an extra ethernet adapter is connected to the Pi in
+this location.
+
+Once the hardware has been installed, Reticulum is installed on all the Pis, and at
+site A and C, one interface is added for the LoRa radio, as well as one for the WiFi
+radio. At site B, an interface for the LoRa radio, and one interface for each WiFi
+radio is added to the Reticulum configuration file. The transport node option is
+enabled in the configuration of all three gateways.
+
+The network is now operational, and ready to serve users across all three areas.
+The organisation prepares a LoRa radio that is supplied to the end users, along
+with a Reticulum configuration file, that contains the right parameters for
+communicating with the LoRa radios installed at the gateway sites.
+
+Once users connect to the network, anyone will be able to communicate with anyone
+else across all three sites.
+
+Bridging Over the Internet
+==========================
+
+As the organisation grows, several new communities form in places too far away
+from the core network to be reachable over WiFi links. New gateways similar to those
+previously installed are set up for the new communities at the new sites D and E, but
+they are islanded from the core network, and only serve the local users.
+
+After investigating the options, it is found that it is possible to install an
+Internet connection at site A, and an interface on the Internet connection is
+configured for Reticulum on the Raspberry Pi at site A.
+
+A member of the organisation at site D, named Dori, is willing to help by sharing
+the Internet connection she already has in her home, and is able to leave a Raspberry
+Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly
+enabled Internet interface on the gateway at site A. Dori is now connected to both
+all the nodes at her own local site (through the hill-top LoRa gateway), and all the
+combined users of sites A, B and C. She then enables transport on her node, and
+traffic from site D can now reach everyone at site A, B and C, and vice versa.
+
+Growth and Convergence
+======================
+
+As the organisation grows, more gateways are added to keep up with the growing user
+base. Some local gateways even add VHF radios and packet modems to reach outlying users
+and communities that are out of reach for the LoRa radios and WiFi backhauls.
+
+As more sites, gateways and users are connected, the amount of coordination required
+is kept to a minimum. If one community wants to add connectivity to the next one
+over, it can simply be done without having to involve everyone or coordinate address
+space or routing tables.
+
+With the added geographical coverage, the operators at site A one day find that
+the original internet bridged interfaces are no longer utilised. The network has
+converged to be completely self-connected, and the sites that were once poorly
+connected outliers are now an integral part of the network.

docs/source/reference.rst

@@ -0,0 +1,83 @@
+.. _api-main:
+
+*************
+API Reference
+*************
+This reference guide lists and explains all classes exposed by the RNS API.
+
+Classes
+=========================
+Communication over a Reticulum network is achieved using a set of classes exposed by RNS.
+
+.. _api-reticulum:
+
+Reticulum
+---------
+
+.. autoclass:: RNS.Reticulum
+   :members:
+
+
+.. _api-identity:
+
+Identity
+--------
+
+.. autoclass:: RNS.Identity
+   :members:
+
+.. _api-destination:
+
+Destination
+-----------
+
+.. autoclass:: RNS.Destination
+   :members:
+
+.. _api-packet:
+
+Packet
+------
+
+.. autoclass:: RNS.Packet(destination, data, create_receipt = True)
+   :members:
+
+.. _api-packetreceipt:
+
+Packet Receipt
+--------------
+
+.. autoclass:: RNS.PacketReceipt()
+   :members:
+
+.. _api-link:
+
+Link
+----
+
+.. autoclass:: RNS.Link(destination, established_callback=None, closed_callback = None)
+   :members:
+
+.. _api-requestreceipt:
+
+Request Receipt
+---------------
+
+.. autoclass:: RNS.RequestReceipt()
+   :members:
+
+.. _api-resource:
+
+Resource
+--------
+
+.. autoclass:: RNS.Resource(data, link, advertise=True, auto_compress=True, callback=None, progress_callback=None, timeout=None)
+   :members:
+
+.. _api-transport:
+
+Transport
+---------
+
+.. autoclass:: RNS.Transport
+   :members:

docs/source/understanding.rst

@@ -0,0 +1,705 @@
+.. _understanding-main:
+
+***********************
+Understanding Reticulum
+***********************
+This chapter will briefly describe the overall purpose and operating principles of Reticulum, a
+networking stack designed for reliable and secure communication over high-latency, low-bandwidth
+links. It should give you an overview of how the stack works, and an understanding of how to
+develop networked applications using Reticulum.
+
+This document is not an exhaustive source of information on Reticulum, at least not yet. Currently,
+the best place to go for such information is the Python reference implementation of Reticulum, along
+with the code examples and API reference. It is however an essential resource to understanding the
+general principles of Reticulum, how to apply them when creating your own networks or software.
+
+After reading this document, you should be well-equipped to understand how a Reticulum network
+operates, what it can achieve, and how you can use it yourself. If you want to help out with the
+development, this is also the place to start, since it will provide a pretty clear overview of the
+sentiments and the philosophy behind Reticulum.
+
+.. _understanding-motivation:
+
+Motivation
+==========
+
+The primary motivation for designing and implementing Reticulum has been the current lack of
+reliable, functional and secure minimal-infrastructure modes of digital communication. It is my
+belief that it is highly desirable to create a cheap and reliable way to set up a wide-range digital
+communication network that can securely allow exchange of information between people and
+machines, with no central point of authority, control, censorship or barrier to entry.
+
+Almost all of the various networking systems in use today share a common limitation, namely that they
+require large amounts of coordination and trust to work, and to join the networks you need approval
+of gatekeepers in control. This need for coordination and trust inevitably leads to an environment of
+central control, where it's very easy for infrastructure operators or governments to control or alter
+traffic, and censor or persecute unwanted actors.
+
+Reticulum aims to require as little coordination and trust as possible. In fact, the only
+“coordination” required is to know the characteristics of physical medium carrying Reticulum traffic.
+
+Since Reticulum is completely medium agnostic, this could be whatever is best suited to the situation.
+In some cases, this might be 1200 baud packet radio links over VHF frequencies, in other cases it might
+be a microwave network using off-the-shelf radios. At the time of release of this document, the
+recommended setup for development and testing is using LoRa radio modules with an open source firmware
+(see the section :ref:`Reference System Setup<understanding-referencesystem>`), connected to a small
+computer like a Raspberry Pi. As an example, the default reference setup provides a channel capacity
+of 5.4 Kbps, and a usable direct node-to-node range of around 15 kilometers (indefinitely extendable
+by using multiple hops).
+
+.. _understanding-goals:
+
+Goals
+=====
+
+To be as widely usable and easy to use as possible, the following goals have been used to
+guide the design of Reticulum:
+
+
+* **Fully useable as open source software stack**
+    Reticulum must be implemented with, and be able to run using only open source software. This is
+    critical to ensuring the availability, security and transparency of the system.
+* **Hardware layer agnosticism**
+    Reticulum shall be fully hardware agnostic, and shall be useable over a wide range
+    physical networking layers, such as data radios, serial lines, modems, handheld transceivers,
+    wired ethernet, wifi, or anything else that can carry a digital data stream. Hardware made for
+    dedicated Reticulum use shall be as cheap as possible and use off-the-shelf components, so
+    it can be easily replicated.
+* **Very low bandwidth requirements**
+    Reticulum should be able to function reliably over links with a transmission capacity as low
+    as *1,000 bps*.
+* **Encryption by default**
+    Reticulum must use encryption by default where possible and applicable.
+* **Unlicensed use**
+    Reticulum shall be functional over physical communication mediums that do not require any
+    form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio
+    frequency bands, and can provide functional long distance links in such conditions, for example
+    by connecting a modem to a PMR or CB radio, or by using LoRa or WiFi modules.
+* **Supplied software**
+    Apart from the core networking stack and API, that allows a developer to build
+    applications with Reticulum, a basic communication suite using Reticulum must be
+    implemented and released at the same time as Reticulum itself. This shall serve both as a
+    functional communication suite, and as an example and learning resource to others wishing
+    to build applications with Reticulum.
+* **Ease of use**
+    The reference implementation of Reticulum is written in Python, to make it easy to use
+    and understand. A programmer with only basic experience should be able to use
+    Reticulum in their own applications.
+* **Low cost**
+    It shall be as cheap as possible to deploy a communication system based on Reticulum. This
+    should be achieved by using cheap off-the-shelf hardware that potential users might already
+    own. The cost of setting up a functioning node should be less than $100 even if all parts
+    needs to be purchased.
+
+.. _understanding-basicfunctionality:
+
+Introduction & Basic Functionality
+==================================
+
+Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
+core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint
+scenarios where alle nodes are within range of each other, as well as scenarios where packets need
+to be transported over multiple hops 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
+networking stack will need to create one or more destinations to receive data, and know the
+destinations it needs to send data to.
+
+All destinations in Reticulum are represented internally as 10 bytes, derived from truncating a full
+SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
+will be displayed as 10 bytes in hexadecimal representation, as in the following example: ``<80e29bf7cccaf31431b3>``.
+
+By default Reticulum encrypts all data using public-key cryptography. Any message sent to a
+destination is encrypted with that destinations public key. Reticulum can also set up an encrypted
+channel to a destination with *Perfect Forward Secrecy* and *Initiator Anonymity* using a elliptic
+curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In
+Reticulum terminology, this is called a *Link*.
+
+Reticulum also offers symmetric key encryption for group-oriented communications, as well as
+unencrypted packets for broadcast purposes, or situations where you need the communication to be in
+plain text. The multi-hop transport, coordination, verification and reliability layers are fully
+autonomous and based on public key cryptography.
+
+Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
+and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
+private IP networks.
+
+.. _understanding-destinations:
+
+Destinations
+------------
+
+To receive and send data with the Reticulum stack, an application needs to create one or more
+destinations. Reticulum uses three different basic destination types, and one special:
+
+
+* **Single**
+    The *single* destination type defines a public-key encrypted destination. Any data sent to this
+    destination will be encrypted with the destination’s public key, and will only be readable by
+    the creator of the destination.
+* **Group**
+    The *group* destination type defines a symmetrically encrypted destination. Data sent to this
+    destination will be encrypted with a symmetric key, and will be readable by anyone in
+    possession of the key. The *group* destination can be used just as well by only two peers, as it
+    can by many.
+* **Plain**
+    A *plain* destination type is unencrypted, and suited for traffic that should be broadcast to a
+    number of users, or should be readable by anyone. Traffic to a *plain* destination is not encrypted.
+* **Link**
+    A *link* is a special destination type, that serves as an abstract channel to a *single*
+    destination, directly connected or over multiple hops. The *link* also offers reliability and
+    more efficient encryption, forward secrecy, initiator anonymity, and as such can be useful even
+    when a node is directly reachable.
+
+.. _understanding-destinationnaming:
+
+Destination Naming
+^^^^^^^^^^^^^^^^^^
+
+Destinations are created and named in an easy to understand dotted notation of *aspects*, and
+represented on the network as a hash of this value. The hash is a SHA-256 truncated to 80 bits. The
+top level aspect should always be a unique identifier for the application using the destination.
+The next levels of aspects can be defined in any way by the creator of the application.
+
+Aspects can be as long and as plentiful as required, and a resulting long destination name will not
+impact efficiency, as names are always represented as truncated SHA-256 hashes on the network.
+
+As an example, a destination for a environmental monitoring application could be made up of the
+application name, a device type and measurement type, like this:
+
+.. code-block:: text
+
+   app name  : environmentlogger
+   aspects   : remotesensor, temperature
+
+   full name : environmentlogger.remotesensor.temperature
+   hash      : fa7ddfab5213f916dea
+
+For the *single* destination, Reticulum will automatically append the associated public key as a
+destination aspect before hashing. This is done to ensure only the correct destination is reached,
+since anyone can listen to any destination name. Appending the public key ensures that a given
+packet is only directed at the destination that holds the corresponding private key to decrypt the
+packet.
+
+**Take note!** There is a very important concept to understand here:
+
+* Anyone can use the destination name ``environmentlogger.remotesensor.temperature``
+
+* Each destination that does so will still have a unique destination hash, and thus be uniquely
+  addressable, because their public keys will differ.
+
+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 acheived by the appending the public key,
+which expands the destination into a uniquely identifyable one.
+
+Any destination on a Reticulum network can be addressed and reached simply by knowning its
+destination hash (and public key, but if the public key is not known, it can be requested from the
+network simply by knowing the destination hash). The use of app names and aspects makes it easy to
+structure Reticulum programs and makes it possible to filter what information and data your program
+receives.
+
+To recap, the different destination types should be used in the following situations:
+
+* **Single**
+    When private communication between two endpoints is needed. Supports multiple hops.
+* **Group**
+    When private communication between two or more endpoints is needed. Supports multiple hops
+    indirectly, but must first be established through a *single* destination.
+* **Plain**
+    When plain-text communication is desirable, for example when broadcasting information.
+
+To communicate with a *single* destination, you need to know it’s 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 participating nodes serve as a distributed ledger
+of public keys.
+
+Note that public key information can be shared and verified in many other ways than using the
+built-in *announce* functionality, and that it is therefore not required to use the announce/request
+functionality to obtain public keys. It is by far the easiest though, and should definitely be used
+if there is not a good reason for doing it differently.
+
+.. _understanding-keyannouncements:
+
+Public Key Announcements
+------------------------
+
+An *announce* will send a special packet over any configured interfaces, containing all needed
+information about the destination hash and public key, and can also contain some additional,
+application specific data. The entire packet is signed by the sender to ensure authenticity. It is not
+required to use the announce functionality, but in many cases it will be the simplest way to share
+public keys on the network. As an example, an announce in a simple messenger application might
+contain the following information:
+
+
+* The announcers destination hash
+* The announcers public key
+* Application specific data, in this case the users nickname and availability status
+* A random blob, making each new announce unique
+* An Ed25519 signature of the above information, verifying authenticity
+
+With this information, any Reticulum node that receives it will be able to reconstruct an outgoing
+destination to securely communicate with that destination. You might have noticed that there is one
+piece of information lacking to reconstruct full knowledge of the announced destination, and that is
+the aspect names of the destination. These are intentionally left out to save bandwidth, since they
+will be implicit in almost all cases. If a destination name is not entirely implicit, information can be
+included in the application specific data part that will allow the receiver to infer the naming.
+
+It is important to note that announces will be forwarded throughout the network according to a
+certain pattern. This will be detailed in the section
+:ref:`The Announce Mechanism in Detail<understanding-announce>`.
+
+Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic.
+
+.. _understanding-identities:
+
+Identities
+----------
+
+In Reticulum, an *identity* does not necessarily represent a personal identity, but is an abstraction that
+can represent any kind of *verified entity*. This could very well be a person, but it could also be the
+control interface of a machine, a program, robot, computer, sensor or something else entirely. In
+general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be
+represented as an identity.
+
+As we have seen, a *single* destination will always have an *identity* tied to it, but not *plain* or *group*
+destinations. Destinations and identities share a multilateral connection. You can create a
+destination, and if it is not connected to an identity upon creation, it will just create a new one to use
+automatically. This may be desirable in some situations, but often you will probably want to create
+the identity first, and then link it to created destinations.
+
+Building upon the simple messenger example, we could use an identity to represent the user of the
+application. Destinations created will then be linked to this identity to allow communication to
+reach the user. In all cases it is of great importance to store the private keys associated with any
+Reticulum Identity securely and privately.
+
+.. _understanding-gettingfurther:
+
+Getting Further
+---------------
+
+The above functions and principles form the core of Reticulum, and would suffice to create
+functional networked applications in local clusters, for example over radio links where all interested
+nodes can directly hear each other. But to be truly useful, we need a way to direct traffic over multiple
+hops in the network.
+
+In the following sections, two concepts that allow this will be introduced, *paths* and *links*.
+
+.. _understanding-transport:
+
+Reticulum Transport
+===================
+
+The term routing has been purposefully avoided until now. The current methods of routing used in IP-based
+networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle.
+These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than
+Reticulum can assume is available.
+
+Since Reticulum is designed to run over open radio spectrum, no such trust exists, and bandwidth is often
+very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
+useable over bandwidth-limited, high-latency links.
+
+To overcome such challenges, Reticulum’s *Transport* system uses public-key cryptography to
+implement the concept of *paths* that allow discovery of how to get information to a certain
+destination. It is important to note that no single node in a Reticulum network knows the complete
+path to a destination. Every Transport node participating in a Reticulum network will only
+know what the most direct way to get a packet one hop closer to it's destination is.
+
+.. _understanding-announce:
+
+The Announce Mechanism in Detail
+--------------------------------
+
+When an *announce* is transmitted by a node, it will be forwarded by any node receiving it, but
+according to some specific rules:
+
+
+* | If this exact announce has already been received before, ignore it.
+
+* | If not, record into a table which node the announce was received from, and how many times in
+    total it has been retransmitted to get here.
+
+* | If the announce has been retransmitted *m+1* times, it will not be forwarded. By default, *m* is
+    set to 18.
+
+* | The announce will be assigned a delay *d* = c\ :sup:`h` seconds, where *c* is a decay constant, and *h* is the amount of times this packet has already been forwarded.
+
+* | The packet will be given a priority *p = 1/d*.
+
+* | If at least *d* seconds has passed since the announce was received, and no other packets with a
+    priority higher than *p* are waiting in the queue (see Packet Prioritisation), and the channel is
+    not utilized by other traffic, the announce will be forwarded.
+
+* | If no other nodes are heard retransmitting the announce with a greater hop count than when
+    it left this node, transmitting it will be retried *r* times. By default, *r* is set to 1. Retries
+    follow same rules as above, with the exception that it must wait for at least *d* = c\ :sup:`h+1` +
+    t + rand(0, rw) seconds. This amount of time is equal to the amount of time it would take the next
+    node to retransmit the packet, plus a random window. By default, *t* is set to 10 seconds, and the
+    random window *rw* is set to 10 seconds.
+
+* | If a newer announce from the same destination arrives, while an identical one is already in
+    the queue, the newest announce is discarded. If the newest announce contains different
+    application specific data, it will replace the old announce, but will use *d* and *p* of the old
+    announce.
+
+Once an announce has reached a node in the network, any other node in direct contact with that
+node will be able to reach the destination the announce originated from, simply by sending a packet
+addressed to that destination. Any node with knowledge of the announce will be able to direct the
+packet towards the destination by looking up the next node with the shortest amount of hops to the
+destination.
+
+According to these rules and default constants, an announce will propagate throughout the network
+in a predictable way. In an example network utilising the default constants, and with an average link
+distance of *Lavg =* 15 kilometers, an announce will be able to propagate outwards to a radius of 180
+kilometers in 34 minutes, and a *maximum announce radius* of 270 kilometers in approximately 3
+days.
+
+.. _understanding-paths:
+
+Reaching the Destination
+------------------------
+
+In networks with changing topology and trustless connectivity, nodes need a way to establish
+*verified connectivity* with each other. Since the network is assumed to be trustless, Reticulum
+must provide a way to guarantee that the peer you are communicating with is actually who you
+expect. Reticulum offers two ways to do this.
+
+For exchanges of small amounts of information, Reticulum offers the *Packet* API, which works exactly like you would expect - on a per packet level. The following process is employed when sending a packet:
+
+* | 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.
+
+* | 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
+    key exchange locally, before sending the packet.
+
+* | The public part of the newly generated ephemeral key-pair is included with the encrypted token, and sent
+    along with the encrypted payload data in the packet.
+
+* | When the destination receives the packet, it can itself perform an ECDH key exchange and decrypt the
+    packet.
+
+* | A new ephemeral key is used for every packet sent in this way, and forward secrecy is guaranteed on a
+    per packet level.
+
+* | 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
+    public signing key.
+
+* | In case the packet is addressed to a *group* destination type, the packet will be encrypted with the
+    pre-shared AES-128 key associated with the destination. In case the packet is addressed to a *plain*
+    destination type, the payload data will not be encrypted. Neither of these two destination types offer
+    forward secrecy. In general, it is recommended to always use the *single* destination type, unless it is
+    strictly necessary to use one of the others.
+
+
+For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the *Link* API. To establish a *link*, the following process is employed:
+
+* | First, the node that wishes to establish a link will send out a special packet, that
+    traverses the network and locates the desired destination. Along the way, the nodes that
+    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
+    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.
+
+* | When the validity of the *link* has been accepted by forwarding nodes, these nodes will
+    remember the *link* , and it can subsequently be used by referring to a hash representing it.
+
+* | As a part of the *link request* , a Diffie-Hellman key exchange takes place, that sets up an
+    efficiently encrypted tunnel between the two nodes, using elliptic curve cryptography. As such,
+    this mode of communication is preferred, even for situations when nodes can directly communicate,
+    when the amount of data to be exchanged numbers in the tens of packets.
+
+* | When a *link* has been set up, it automatically provides message receipt functionality, through
+    the same *proof* mechanism discussed before, so the sending node can obtain verified confirmation
+    that the information reached the intended recipient.
+
+In a moment, we will discuss the details of how this methodology is implemented, but let’s first
+recap what purposes this methodology serves. We first ensure that the node answering our request
+is actually the one we want to communicate with, and not a malicious actor pretending to be so.
+At the same time we establish an efficient encrypted channel. The setup of this is relatively cheap in
+terms of bandwidth, so it can be used just for a short exchange, and then recreated as needed, which will
+also rotate encryption keys. The link can also be kept alive for longer periods of time, if this is
+more suitable to the application. The procedure also inserts the *link id* , a hash calculated from the link request packet, into the memory of forwarding nodes, which means that the communicating nodes can thereafter reach each other simply by referring to this *link id*.
+
+The combined bandwidth cost of setting up a link is 3 packets totalling 237 bytes (more info in the
+:ref:`Binary Packet Format<understanding-packetformat>` section). The amount of bandwidth used on keeping
+a link open is practically negligible, at 0.62 bits per second. Even on a slow 1200 bits per second packet
+radio channel, 100 concurrent links will still leave 95% channel capacity for actual data.
+
+
+Link Establishment in Detail
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After exploring the basics of the announce mechanism, finding a path through the network, and an overview
+of the link establishment procedure, this section will go into greater detail about the Reticulum link
+establishment process.
+
+The *link* in Reticulum terminology should not be viewed as a direct node-to-node link on the
+physical layer, but as an abstract channel, that can be open for any amount of time, and can span
+an arbitrary number of hops, where information will be exchanged between two nodes.
+
+
+* | When a node in the network wants to establish verified connectivity with another node, it
+    will randomly generate a new X25519 private/public key pair. It then creates a *link request*
+    packet, and broadcast it.
+  |  
+  | *It should be noted that the X25519 public/private keypair mentioned above is two separate keypairs:
+    An encryption key pair, used for derivation of a shared symmetric key, and a signing key pair, used
+    for signing and verifying messages on the link. They are sent together over the wire, and can be
+    considered as single public key for simplicity in this explanation.*
+
+* | The *link request* is addressed to the destination hash of the desired destination, and
+    contains the following data: The newly generated X25519 public key *LKi*.
+
+* | The broadcasted packet will be directed through the network according to the rules laid out
+    previously.
+
+* | Any node that forwards the link request will store a *link id* in it’s *link table* , along with the
+    amount of hops the packet had taken when received. The link id is a hash of the entire link
+    request packet. If the link request packet is not *proven* by the addressed destination within some
+    set amount of time, the entry will be dropped from the *link table* again.
+
+* | When the destination receives the link request packet, it will decide whether to accept the request.
+    If it is accepted, the destination will also generate a new X25519 private/public key pair, and
+    perform a Diffie Hellman Key Exchange, deriving a new symmetric key that will be used to encrypt the
+    channel, once it has been established.
+
+* | A *link proof* packet is now constructed and transmitted over the network. This packet is
+    addressed to the *link id* of the *link*. It contains the following data: The newly generated X25519
+    public key *LKr* and an Ed25519 signature of the *link id* and *LKr* made by the signing key of
+    the addressed destination.
+   
+* | By verifying this *link proof* packet, all nodes that originally transported the *link request*
+    packet to the destination from the originator can now verify that the intended destination received
+    the request and accepted it, and that the path they chose for forwarding the request was valid.
+    In sucessfully carrying out this verification, the transporting nodes marks the link as active.
+    An abstract bi-directional communication channel has now been established along a path in the network.
+
+* | When the source receives the *proof* , it will know unequivocally that a verified path has been
+    established to the destination. It can now also use the X25519 public key contained in the
+    *link proof* to perform it's own Diffie Hellman Key Exchange and derive the symmetric key
+    that is used to encrypt the channel. Information can now be exchanged reliably and securely.
+
+
+It’s important to note that this methodology ensures that the source of the request does not need to
+reveal any identifying information about itself. The link initiator remains completely anonymous.
+
+When using *links*, Reticulum will automatically verify all data sent over the link, and can also
+automate retransmissions if *Resources* are used.
+
+.. _understanding-resources:
+
+Resources
+---------
+
+For exchanging small amounts of data over a Reticulum network, the :ref:`Packet<api-packet>` interface
+is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate
+the transfer is needed.
+
+This is the purpose of the Reticulum :ref:`Resource<api-resource>`. A *Resource* can automatically
+handle the reliable transfer of an arbitrary amount of data over an established :ref:`Link<api-link>`.
+Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
+the transfer and reassembling the data on the other end.
+
+:ref:`Resources<api-resource>` are programmatically very simple to use, and only requires a few lines
+of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
+or stream data directly from files.
+
+.. _understanding-referencesystem:
+
+Reference System Setup
+======================
+
+This section will detail the recommended *Reference System Setup* for Reticulum. It is important to
+note that Reticulum is designed to be usable over more or less any medium that allows you to send
+and receive data in a digital form, and satisfies some very low minimum requirements. The
+communication channel must support at least half-duplex operation, and provide an average
+throughput of around 1000 bits per second, and supports a physical layer MTU of 500 bytes. The
+Reticulum software should be able to run on more or less any hardware that can provide a Python 3.x 
+runtime environment.
+
+That being said, the reference setup has been outlined to provide a common platform for anyone
+who wants to help in the development of Reticulum, and for everyone who wants to know a
+recommended setup to get started. A reference system consists of three parts:
+
+* **A channel access device**
+    Or *CAD* , in short, provides access to the physical medium whereupon the communication
+    takes place, for example a radio with an integrated modem. A setup with a separate modem
+    connected to a radio would also be termed a “channel access device”.
+* **A host device**
+    Some sort of computing device that can run the necessary software, communicates with the
+    channel access device, and provides user interaction.
+* **A software stack**
+    The software implementing the Reticulum protocol and applications using it.
+
+The reference setup can be considered a relatively stable platform to develop on, and also to start
+building networks on. While details of the implementation might change at the current stage of
+development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
+the current reference setup has been determined to provide a functional platform for many years
+into the future. The current Reference System Setup is as follows:
+
+
+* **Channel Access Device**
+    A data radio consisting of a LoRa radio module, and a microcontroller with open source
+    firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
+    MHz frequency bands. More details can be found on the `RNode Page <https://unsigned.io/rnode>`_.
+* **Host device**
+    Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
+    recommended.
+* **Software stack**
+    The current Reference Implementation Release of Reticulum, running on a Debian based
+    operating system.
+
+It is very important to note, that the reference channel access device **does not** use the LoRaWAN
+standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
+need a plain LoRa radio module connected to an MCU with the correct firmware. Full details on how to
+get or make such a device is available on the `RNode Page <https://unsigned.io/rnode>`_.
+
+With the current reference setup, it should be possible to get on a Reticulum network for around 100$
+even if you have none of the hardware already, and need to purchase everything.
+
+.. _understanding-protocolspecifics:
+
+Protocol Specifics
+==================
+
+This chapter will detail protocol specific information that is essential to the implementation of
+Reticulum, but non critical in understanding how the protocol works on a general level. It should be
+treated more as a reference than as essential reading.
+
+
+Node Types
+----------
+
+Currently Reticulum defines two node types, the *Station* and the *Peer*. A node is a *station* if it fixed
+in one place, and if it is intended to be kept online most of the time. Otherwise the node is a *peer*.
+This distinction is made by the user configuring the node, and is used to determine what nodes on the
+network will help forward traffic, and what nodes rely on other nodes for connectivity.
+
+If a node is a *Peer* it should be given the configuration directive ``enable_transport = No``.
+
+If it is a *Station*, it should be given the configuration directive ``enable_transport = Yes``.
+
+
+Packet Prioritisation
+---------------------
+
+Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
+on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
+times and priorities described earlier in this chapter.
+
+It is possible that a prioritisation engine could be added to Reticulum in the future, but in
+the light of Reticulums goal of equal access, doing so would need to be the subject of careful
+investigation of the consequences first.
+
+
+.. _understanding-packetformat:
+
+Binary Packet Format
+--------------------
+
+.. code-block:: text
+
+    == Reticulum Wire Format ======
+
+    A Reticulum packet is composed of the following fields:
+
+    [HEADER 2 bytes] [ADDRESSES 10/20 bytes] [CONTEXT 1 byte] [DATA 0-477 bytes]
+
+    * The HEADER field is 2 bytes long.
+      * Byte 1: [Header Type], [Propagation Type], [Destination Type] and [Packet Type]
+      * Byte 2: Number of hops
+
+    * The ADDRESSES field contains either 1 or 2 addresses.
+      * Each address is 10 bytes long.
+      * The Header Type flag in the HEADER field determines
+        whether the ADDRESSES field contains 1 or 2 addresses.
+      * Addresses are Reticulum hashes truncated to 10 bytes.
+
+    * The CONTEXT field is 1 byte.
+      * It is used by Reticulum to determine packet context.
+
+    * The DATA field is between 0 and 477 bytes.
+      * It contains the packets data payload.
+
+    Header Types
+    -----------------
+    type 1          00  Two byte header, one 10 byte address field
+    type 2          01  Two byte header, two 10 byte address fields
+    type 3          10  Reserved
+    type 4          11  Reserved
+
+
+    Propagation Types
+    -----------------
+    broadcast       00
+    transport       01
+    reserved        10
+    reserved        11
+
+
+    Destination Types
+    -----------------
+    single          00
+    group           01
+    plain           10
+    link            11
+
+
+    Packet Types
+    -----------------
+    data            00
+    announce        01
+    link request    10
+    proof           11
+
+
+    +- Packet Example -+
+
+       HEADER FIELD             ADDRESSES FIELD             CONTEXT FIELD  DATA FIELD
+     _______|_______   ________________|________________   ________|______   __|_
+    |               | |                                 | |               | |    |
+    01010000 00000100 [ADDR1, 10 bytes] [ADDR2, 10 bytes] [CONTEXT, 1 byte] [DATA]
+     | | | |    |
+     | | | |    +-- Hops             = 4
+     | | | +------- Packet Type      = DATA
+     | | +--------- Destination Type = SINGLE
+     | +----------- Propagation Type = TRANSPORT
+     +------------- Header Type      = HEADER_2 (two byte header, two address fields)
+
+
+     +- Packet Example -+
+
+       HEADER FIELD    ADDRESSES FIELD    CONTEXT FIELD  DATA FIELD
+     _______|_______   _______|_______   ________|______   __|_
+    |               | |               | |               | |    |
+    00000000 00000111 [ADDR1, 10 bytes] [CONTEXT, 1 byte] [DATA]
+     | | | |    |
+     | | | |    +-- Hops             = 7
+     | | | +------- Packet Type      = DATA
+     | | +--------- Destination Type = SINGLE
+     | +----------- Propagation Type = BROADCAST
+     +------------- Header Type      = HEADER_1 (two byte header, one address field)
+
+
+     Size examples of different packet types
+     ---------------------------------------
+
+     The following table lists example sizes of various
+     packet types. The size listed are the complete on-
+     wire size including all fields.
+
+     - Path Request    :    33  bytes
+     - Announce        :    151 bytes
+     - Link Request    :    77  bytes
+     - Link Proof      :    77  bytes
+     - Link RTT packet :    83  bytes
+     - Link keepalive  :    14  bytes

docs/source/using.rst

@@ -0,0 +1,165 @@
+.. _using-main:
+
+******************************
+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.
+This means that no special privileges are required to install or use it.
+Any program or application that uses Reticulum will automatically load and
+initialise Reticulum when it starts.
+
+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 Reticulum. 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 concurrently, and is
+very easy to use, but depending on your use case, there are other options.
+
+Included Utility Programs
+-------------------------
+
+If you often use Reticulum from several different programs, or simply want
+Reticulum to stay available all the time, for example if you are hosting
+a transport node, you might want to run Reticulum as a separate service that
+other programs, applications and services can utilise.
+
+The rnsd Utility
+================
+
+To do so is very easy. Simply run the included ``rnsd`` command. When ``rnsd``
+is running, it will keep all configured interfaces open, handle transport if
+it is enabled, and allow any other programs to immediately utilise the
+Reticulum network it is configured for.
+
+You can even run multiple instances of rnsd with different configurations on
+the same system.
+
+.. code:: text
+
+  # Install Reticulum
+  pip3 install rns
+
+  # Run rnsd
+  rnsd
+
+.. code:: text
+
+  usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version]
+
+  Reticulum Network Stack Daemon
+
+  optional arguments:
+    -h, --help       show this help message and exit
+    --config CONFIG  path to alternative Reticulum config directory
+    -v, --verbose
+    -q, --quiet
+    --version        show program's version number and exit
+
+
+The rnstatus Utility
+====================
+
+Using the ``rnstatus`` utility, you can view the status of configured Reticulum
+interfaces, similar to the ``ifconfig`` program.
+
+.. code:: text
+
+  # Run rnstatus
+  rnstatus
+
+  # Example output
+  Shared Instance[37428]
+         Status: Up
+         Connected applications: 1
+         RX: 1.13 KB
+         TX: 1.07 KB
+
+  UDPInterface[Default UDP Interface/0.0.0.0:4242]
+         Status: Up
+         RX: 1.01 KB
+         TX: 1.01 KB
+
+  TCPInterface[RNS Testnet Frankfurt/frankfurt.rns.unsigned.io:4965]
+         Status: Up
+         RX: 1.37 KB
+         TX: 9.02 KB
+
+.. code:: text
+
+  usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version]
+
+  Reticulum Network Stack Daemon
+
+  optional arguments:
+    -h, --help       show this help message and exit
+    --config CONFIG  path to alternative Reticulum config directory
+    -v, --verbose
+    -q, --quiet
+    --version        show program's version number and exit
+
+
+The rnpath Utility
+====================
+
+With the ``rnpath`` utility, you can look up and view paths for
+destinations on the Reticulum network.
+
+.. code:: text
+
+  # Run rnpath
+  rnpath eca6f4e4dc26ae329e61
+
+  # Example output
+  Path found, destination <eca6f4e4dc26ae329e61> is 4 hops away via <56b115c30cd386cad69c> on TCPInterface[Testnet/frankfurt.rns.unsigned.io:4965]
+
+.. code:: text
+
+  usage: rnpath.py [-h] [--config CONFIG] [--version] [-v] [destination]
+
+  Reticulum Path Discovery Utility
+
+  positional arguments:
+    destination      hexadecimal hash of the destination
+
+  optional arguments:
+    -h, --help       show this help message and exit
+    --config CONFIG  path to alternative Reticulum config directory
+    --version        show program's version number and exit
+    -v, --verbose
+
+
+The rnprobe Utility
+====================
+
+The ``rnprobe`` utility lets you probe a destination for connectivity, similar
+to the ``ping`` program. Please note that probes will only be answered if the
+specified destination is configured to send proofs for received packets. Many
+destinations will not have this option enabled, and will not be probable.
+
+.. code:: text
+
+  # Run rnprobe
+  python3 -m RNS.Utilities.rnprobe example_utilities.echo.request 9382f334de63217a4278
+
+  # Example output
+  Sent 16 byte probe to <9382f334de63217a4278>
+  Valid reply received from <9382f334de63217a4278>
+  Round-trip time is 38.469 milliseconds over 2 hops
+
+.. code:: text
+
+  usage: rnprobe.py [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash]
+
+  Reticulum Probe Utility
+
+  positional arguments:
+    full_name         full destination name in dotted notation
+    destination_hash  hexadecimal hash of the destination
+
+  optional arguments:
+    -h, --help        show this help message and exit
+    --config CONFIG   path to alternative Reticulum config directory
+    --version         show program's version number and exit
+    -v, --verbose

docs/source/whatis.rst

@@ -0,0 +1,108 @@
+******************
+What is Reticulum?
+******************
+
+Reticulum is a cryptography-based networking stack for wide-area networks built on readily available hardware, and can operate even with very high latency and extremely low bandwidth.
+
+Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more.
+
+Reticulum is a complete networking stack, and does not need IP or higher layers, although it is easy to utilise IP (with TCP or UDP) as the underlying carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks. Reticulum is built directly on cryptographic principles, allowing resilience and stable functionality in open and trustless networks.
+
+No kernel modules or drivers are required. Reticulum runs completely in userland, and can run on practically any system that runs Python 3. Reticulum runs well even on small single-board computers like the Pi Zero.
+
+
+Current Status
+==============
+Reticulum should currently be considered beta software. All core protocol 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.
+
+
+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 privacy-breaking bugs. To be considered secure, Reticulum needs a thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch.
+
+
+What does Reticulum Offer?
+==========================
+* Coordination-less globally unique adressing and identification
+
+* Fully self-configuring multi-hop routing
+
+* Complete initiator anonymity, communicate without revealing your identity
+
+* Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
+
+* Forward Secrecy with ephemereal Elliptic Curve Diffie-Hellman keys on Curve25519
+
+* Reticulum uses the `Fernet <https://github.com/fernet/spec/blob/master/Spec.md>`_ specification for on-the-wire / over-the-air encryption
+
+  * All keys are ephemeral and derived from an ECDH key exchange on Curve25519
+
+  * AES-128 in CBC mode with PKCS7 padding
+
+  * HMAC using SHA256 for authentication
+
+  * IVs are generated through os.urandom()
+
+* Unforgeable packet delivery confirmations
+
+* A variety of supported interface types
+
+* An intuitive and developer-friendly API
+
+* Reliable and efficient transfer of arbritrary amounts of data
+
+  * Reticulum can handle a few bytes of data or files of many gigabytes
+
+  * Sequencing, transfer coordination and checksumming is automatic
+
+  * The API is very easy to use, and provides transfer progress
+
+* Efficient link establishment
+
+  * Total bandwidth cost of setting up a link is only 3 packets, totalling 237 bytes
+
+  * Low cost of keeping links open at only 0.62 bits per second
+
+
+Where can Reticulum be Used?
+============================
+Over practically any medium that can support at least a half-duplex channel
+with 500 bits per second throughput, and an MTU of 500 bytes. Data radios,
+modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes,
+ad-hoc WiFi, free-space optical links and similar systems are all examples
+of the types of interfaces Reticulum was designed for.
+
+An open-source LoRa-based interface called `RNode <https://unsigned.io/rnode>`_
+has been designed specifically for use with Reticulum. It is possible to build
+yourself, or it can be purchased as a complete transceiver that just needs a
+USB connection to the host.
+
+Reticulum can also be encapsulated over existing IP networks, so there's
+nothing stopping you from using it over wired ethernet or your local WiFi
+network, where it'll work just as well. In fact, one of the strengths of
+Reticulum is how easily it allows you to connect different mediums into a
+self-configuring, resilient and encrypted mesh.
+
+As an example, it's possible to set up a Raspberry Pi connected to both a
+LoRa radio, a packet radio TNC and a WiFi network. Once the interfaces are
+configured, Reticulum will take care of the rest, and any device on the WiFi
+network can communicate with nodes on the LoRa and packet radio sides of the
+network, and vice versa.
+
+Interface Types and Devices
+===========================
+Reticulum implements a range of generalised interface types that covers most of the communications hardware that Reticulum can run over. If your hardware is not supported, it's relatively simple to implement an interface class. Currently, the following interfaces are supported:
+
+* Any ethernet device
+
+* LoRa using `RNode <https://unsigned.io/rnode>`_
+
+* Packet Radio TNCs, such as `OpenModem <https://unsigned.io/openmodem>`_
+
+* Any device with a serial port
+
+* TCP over IP networks
+
+* UDP over IP networks
+
+For a full list and more details, see the :ref:`Supported Interfaces<interfaces-main>` chapter.

setup.py

@@ -1,11 +1,13 @@
 import setuptools
 
+exec(open("RNS/_version.py", "r").read())
+
 with open("README.md", "r") as fh:
     long_description = fh.read()
 
 setuptools.setup(
     name="rns",
-    version="0.1.8",
+    version=__version__,
     author="Mark Qvist",
     author_email="mark@unsigned.io",
     description="Self-configuring, encrypted and resilient mesh networking stack for LoRa, packet radio, WiFi and everything in between",
@@ -18,6 +20,15 @@ setuptools.setup(
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
     ],
-    install_requires=['cryptography', 'pyserial'],
-    python_requires='>=3.5',
-)
+    entry_points= {
+        'console_scripts': [
+            'rnsd=RNS.Utilities.rnsd:main',
+            'rnstatus=RNS.Utilities.rnstatus:main',
+            'rnprobe=RNS.Utilities.rnprobe:main',
+            'rnpath=RNS.Utilities.rnpath:main',
+
+        ]
+    },
+    install_requires=['cryptography>=3.4.7', 'pyserial', 'netifaces>=0.10.4'],
+    python_requires='>=3.6',
+)