Updated manual

.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,56 +11,67 @@ 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):
-	# We must first initialise Reticulum
-	reticulum = RNS.Reticulum(configpath)
-	
-	# If the user did not select a "channel" we use
-	# a default one called "public_information".
-	# This "channel" is added to the destination name-
-	# space, so the user can select different broadcast
-	# channels.
-	if channel == None:
-		channel = "public_information"
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
+    
+    # If the user did not select a "channel" we use
+    # a default one called "public_information".
+    # This "channel" is added to the destination name-
+    # space, so the user can select different broadcast
+    # channels.
+    if channel == None:
+        channel = "public_information"
 
-	# 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)
+    # 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
+    )
 
-	# We specify a callback that will get called every time
-	# the destination receives data.
-	broadcast_destination.packet_callback(packet_callback)
-	
-	# Everything's ready!
-	# Let's hand over control to the main loop
-	broadcastLoop(broadcast_destination)
+    # We specify a callback that will get called every time
+    # the destination receives data.
+    broadcast_destination.set_packet_callback(packet_callback)
+    
+    # Everything's ready!
+    # Let's hand over control to the main loop
+    broadcastLoop(broadcast_destination)
 
 def packet_callback(data, packet):
-	# Simply print out the received data
-	print("")
-	print("Received data: "+data.decode("utf-8")+"\r\n> ", end="")
-	sys.stdout.flush()
+    # Simply print out the received data
+    print("")
+    print("Received data: "+data.decode("utf-8")+"\r\n> ", end="")
+    sys.stdout.flush()
 
 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)")
+    # 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)"
+    )
 
-	# We enter a loop that runs until the users exits.
-	# If the user hits enter, we will send the information
-	# that the user entered into the prompt.
-	while True:
-		print("> ", end="")
-		entered = input()
+    # We enter a loop that runs until the users exits.
+    # If the user hits enter, we will send the information
+    # that the user entered into the prompt.
+    while True:
+        print("> ", end="")
+        entered = input()
+
+        if entered != "":
+            data    = entered.encode("utf-8")
+            packet  = RNS.Packet(destination, data)
+            packet.send()
 
-		if entered != "":
-			data    = entered.encode("utf-8")
-			packet  = RNS.Packet(destination, data)
-			packet.send()
 
-		
 
 ##########################################################
 #### Program Startup #####################################
@@ -70,24 +81,41 @@ def broadcastLoop(destination):
 # and parses input from the user, and then starts
 # 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)
-		args = parser.parse_args()
+    try:
+        parser = argparse.ArgumentParser(
+            description="Reticulum example demonstrating sending and receiving broadcasts"
+        )
 
-		if args.config:
-			configarg = args.config
-		else:
-			configarg = None
+        parser.add_argument(
+            "--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
 
-		if args.channel:
-			channelarg = args.channel
-		else:
-			channelarg = None
+        parser.add_argument(
+            "--channel",
+            action="store",
+            default=None,
+            help="broadcast channel name",
+            type=str
+        )
 
-		program_setup(configarg, channelarg)
+        args = parser.parse_args()
 
-	except KeyboardInterrupt:
-		print("")
-		exit()
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        if args.channel:
+            channelarg = args.channel
+        else:
+            channelarg = None
+
+        program_setup(configarg, channelarg)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()

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,56 +22,67 @@ APP_NAME = "example_utilitites"
 # 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 echo server
-	server_identity = RNS.Identity()
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
+    
+    # Randomly create a new identity for our echo server
+    server_identity = RNS.Identity()
 
-	# We create a destination that clients can query. We want
-	# to be able to verify echo replies to our clients, so we
-	# create a "single" destination that can receive encrypted
-	# 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")
+    # We create a destination that clients can query. We want
+    # to be able to verify echo replies to our clients, so we
+    # create a "single" destination that can receive encrypted
+    # 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"
+    )
 
-	# We configure the destination 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.
-	echo_destination.set_proof_strategy(RNS.Destination.PROVE_ALL)
-	
-	# 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)
+    # We configure the destination 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.
+    echo_destination.set_proof_strategy(RNS.Destination.PROVE_ALL)
+    
+    # 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.set_packet_callback(server_callback)
 
-	# Everything's ready!
-	# Let's Wait for client requests or user input
-	announceLoop(echo_destination)
+    # Everything's ready!
+    # Let's Wait for client requests or user input
+    announceLoop(echo_destination)
 
 
 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)")
+    # 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)"
+    )
 
-	# 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))
+    # 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))
 
 
 def server_callback(message, packet):
-	# 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")
+    # 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")
 
 
 ##########################################################
@@ -81,103 +92,121 @@ 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):
-	# 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 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)"
+            )
 
-	# We must first initialise Reticulum
-	reticulum = RNS.Reticulum(configpath)
+        destination_hash = bytes.fromhex(destination_hexhash)
+    except:
+        RNS.log("Invalid destination entered. Check your input!\n")
+        exit()
 
-	# We override the loglevel to provide feedback when
-	# an announce is received
-	if RNS.loglevel < RNS.LOG_INFO:
-		RNS.loglevel = RNS.LOG_INFO
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
 
-	# 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)")
+    # We override the loglevel to provide feedback when
+    # an announce is received
+    if RNS.loglevel < RNS.LOG_INFO:
+        RNS.loglevel = RNS.LOG_INFO
 
-	# We enter a loop that runs until the user exits.
-	# If the user hits enter, we will try to send an
-	# echo request to the destination specified on the
-	# command line.
-	while True:
-		input()
-		
-		# 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):
+    # 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)"
+    )
 
-			# To address the server, we need to know it's public
-			# key, so we check if Reticulum knows this destination.
-			# This is done by calling the "recall" method of the
-			# Identity module. If the destination is known, it will
-			# return an Identity instance that can be used in
-			# outgoing destinations.
-			server_identity = RNS.Identity.recall(destination_hash)
+    # We enter a loop that runs until the user exits.
+    # If the user hits enter, we will try to send an
+    # echo request to the destination specified on the
+    # command line.
+    while True:
+        input()
+        
+        # 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.has_path(destination_hash):
 
-			# We got the correct identity instance from the
-			# recall method, so let's create an outgoing
-			# destination. We use the naming convention:
-			# 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")
+            # To address the server, we need to know it's public
+            # key, so we check if Reticulum knows this destination.
+            # This is done by calling the "recall" method of the
+            # Identity module. If the destination is known, it will
+            # return an Identity instance that can be used in
+            # outgoing destinations.
+            server_identity = RNS.Identity.recall(destination_hash)
 
-			# 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())
+            # We got the correct identity instance from the
+            # recall method, so let's create an outgoing
+            # destination. We use the naming convention:
+            # 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"
+            )
 
-			# Send the packet! If the packet is successfully
-			# sent, it will return a PacketReceipt instance.
-			packet_receipt = echo_request.send()
+            # 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.get_random_hash())
 
-			# If the user specified a timeout, we set this
-			# timeout on the packet receipt, and configure
-			# a callback function, that will get called if
-			# the packet times out.
-			if timeout != None:
-				packet_receipt.set_timeout(timeout)
-				packet_receipt.timeout_callback(packet_timed_out)
+            # Send the packet! If the packet is successfully
+            # sent, it will return a PacketReceipt instance.
+            packet_receipt = echo_request.send()
 
-			# 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)
+            # If the user specified a timeout, we set this
+            # timeout on the packet receipt, and configure
+            # a callback function, that will get called if
+            # the packet times out.
+            if timeout != None:
+                packet_receipt.set_timeout(timeout)
+                packet_receipt.set_timeout_callback(packet_timed_out)
 
-			# Tell the user that the echo request was sent
-			RNS.log("Sent echo request to "+RNS.prettyhexrep(request_destination.hash))
-		else:
-			# 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)
+            # 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.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))
+        else:
+            # 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.request_path(destination_hash)
 
 # This function is called when our reply destination
 # receives a proof packet.
 def packet_delivered(receipt):
-	if receipt.status == RNS.PacketReceipt.DELIVERED:
-		rtt = receipt.rtt()
-		if (rtt >= 1):
-			rtt = round(rtt, 3)
-			rttstring = str(rtt)+" seconds"
-		else:
-			rtt = round(rtt*1000, 3)
-			rttstring = str(rtt)+" milliseconds"
+    if receipt.status == RNS.PacketReceipt.DELIVERED:
+        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"
 
-		RNS.log("Valid reply received from "+RNS.prettyhexrep(receipt.destination.hash)+", round-trip time is "+rttstring)
+        RNS.log(
+            "Valid reply received from "+
+            RNS.prettyhexrep(receipt.destination.hash)+
+            ", round-trip time is "+rttstring
+        )
 
 # This function is called if a packet times out.
 def packet_timed_out(receipt):
-	if receipt.status == RNS.PacketReceipt.FAILED:
-		RNS.log("Packet "+RNS.prettyhexrep(receipt.hash)+" timed out")
+    if receipt.status == RNS.PacketReceipt.FAILED:
+        RNS.log("Packet "+RNS.prettyhexrep(receipt.hash)+" timed out")
 
 
 ##########################################################
@@ -188,36 +217,65 @@ def packet_timed_out(receipt):
 # and parses input from the user, and then starts
 # the desired program mode.
 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)
-		args = parser.parse_args()
+    try:
+        parser = argparse.ArgumentParser(description="Simple echo server and client utility")
 
-		if args.server:
-			configarg=None
-			if args.config:
-				configarg = args.config
-			server(configarg)
-		else:
-			if args.config:
-				configarg = args.config
-			else:
-				configarg = None
+        parser.add_argument(
+            "-s",
+            "--server",
+            action="store_true",
+            help="wait for incoming packets from clients"
+        )
 
-			if args.timeout:
-				timeoutarg = float(args.timeout)
-			else:
-				timeoutarg = None
+        parser.add_argument(
+            "-t",
+            "--timeout",
+            action="store",
+            metavar="s",
+            default=None,
+            help="set a reply timeout in seconds",
+            type=float
+        )
 
-			if (args.destination == None):
-				print("")
-				parser.print_help()
-				print("")
-			else:
-				client(args.destination, configarg, timeout=timeoutarg)
-	except KeyboardInterrupt:
-		print("")
-		exit()
+        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:
+            configarg=None
+            if args.config:
+                configarg = args.config
+            server(configarg)
+        else:
+            if args.config:
+                configarg = args.config
+            else:
+                configarg = None
+
+            if args.timeout:
+                timeoutarg = float(args.timeout)
+            else:
+                timeoutarg = None
+
+            if (args.destination == None):
+                print("")
+                parser.print_help()
+                print("")
+            else:
+                client(args.destination, configarg, timeout=timeoutarg)
+    except KeyboardInterrupt:
+        print("")
+        exit()

Examples/Filetransfer.py

@@ -3,6 +3,17 @@
 # server and client program. The server will serve a     #
 # directory of files, and the clients can list and       #
 # download files from the server.                        #
+#                                                        #
+# Please note that using RNS Resources for large file    #
+# transfers is not recommended, since compression,       #
+# encryption and hashmap sequencing can take a long time #
+# on systems with slow CPUs, which will probably result  #
+# in the client timing out before the resource sender    #
+# can complete preparing the resource.                   #
+#                                                        #
+# If you need to transfer large files, use the Bundle    #
+# class instead, which will automatically slice the data #
+# into chunks suitable for packing as a Resource.        #
 ##########################################################
 
 import os
@@ -17,10 +28,10 @@ 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 = 15.0
+APP_TIMEOUT = 45.0
 
 ##########################################################
 #### Server Part #########################################
@@ -31,260 +42,293 @@ serve_path = None
 # This initialisation is executed when the users chooses
 # to run as a server
 def server(configpath, path):
-	# We must first initialise Reticulum
-	reticulum = RNS.Reticulum(configpath)
-	
-	# Randomly create a new identity for our file server
-	server_identity = RNS.Identity()
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
+    
+    # Randomly create a new identity for our file server
+    server_identity = RNS.Identity()
 
-	global serve_path
-	serve_path = path
+    global serve_path
+    serve_path = 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")
+    # 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"
+    )
 
-	# 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)
+    # 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
-	announceLoop(server_destination)
+    # Everything's ready!
+    # Let's Wait for client requests or user input
+    announceLoop(server_destination)
 
 def announceLoop(destination):
-	# Let the user know that everything is ready
-	RNS.log("File server "+RNS.prettyhexrep(destination.hash)+" running")
-	RNS.log("Hit enter to manually send an announce (Ctrl-C to quit)")
+    # Let the user know that everything is ready
+    RNS.log("File server "+RNS.prettyhexrep(destination.hash)+" running")
+    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))
+    # 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))
 
 # Here's a convenience function for listing all files
 # in our served directory
 def list_files():
-	# We add all entries from the directory that are
-	# actual files, and does not start with "."
-	global serve_path
-	return [file for file in os.listdir(serve_path) if os.path.isfile(os.path.join(serve_path, file)) and file[:1] != "."]
+    # We add all entries from the directory that are
+    # actual files, and does not start with "."
+    global serve_path
+    return [file for file in os.listdir(serve_path) if os.path.isfile(os.path.join(serve_path, file)) and file[:1] != "."]
 
 # When a client establishes a link to our server
 # destination, this function will be called with
 # a reference to the link. We then send the client
 # a list of files hosted on the server.
 def client_connected(link):
-	# Check if the served directory still exists
-	if os.path.isdir(serve_path):
-		RNS.log("Client connected, sending file list...")
+    # Check if the served directory still exists
+    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())
+        # We pack a list of files for sending in a packet
+        data = umsgpack.packb(list_files())
 
-		# Check the size of the packed data
-		if len(data) <= RNS.Link.MDU:
-			# If it fits in one packet, we will just
-			# send it as a single packet over the 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)
-		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)
-			RNS.log("Hint: The client already supports it :)", RNS.LOG_ERROR)
-			
-		# After this, we're just going to keep the 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)
-	else:
-		RNS.log("Client connected, but served path no longer exists!", RNS.LOG_ERROR)
-		link.teardown()
+        # Check the size of the packed data
+        if len(data) <= RNS.Link.MDU:
+            # If it fits in one packet, we will just
+            # send it as a single packet over the link.
+            list_packet = RNS.Packet(link, data)
+            list_receipt = list_packet.send()
+            list_receipt.set_timeout(APP_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)
+            RNS.log("Hint: The client already supports it :)", RNS.LOG_ERROR)
+            
+        # After this, we're just going to keep the 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.set_packet_callback(client_request)
+    else:
+        RNS.log("Client connected, but served path no longer exists!", RNS.LOG_ERROR)
+        link.teardown()
 
 def client_disconnected(link):
-	RNS.log("Client disconnected")
+    RNS.log("Client disconnected")
 
 def client_request(message, packet):
-	global serve_path
-	filename = message.decode("utf-8")
-	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_data = file.read()
-			file.close()
+    global serve_path
 
-			file_resource = RNS.Resource(file_data, packet.link, callback=resource_sending_concluded)
-			file_resource.filename = filename
-		except:
-			# If somethign went wrong, we close
-			# the link
-			RNS.log("Error while reading file \""+filename+"\"", RNS.LOG_ERROR)
-			packet.link.teardown()
-	else:
-		# If we don't have it, we close the link
-		RNS.log("Client requested an unknown file")
-		packet.link.teardown()
+    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.filename = filename
+        except Exception as e:
+            # If somethign went wrong, we close
+            # the link
+            RNS.log("Error while reading file \""+filename+"\"", RNS.LOG_ERROR)
+            packet.link.teardown()
+            raise e
+    else:
+        # If we don't have it, we close the link
+        RNS.log("Client requested an unknown file")
+        packet.link.teardown()
 
 # This function is called on the server when a
 # resource transfer concludes.
 def resource_sending_concluded(resource):
-	if hasattr(resource, "filename"):
-		name = resource.filename
-	else:
-		name = "resource"
+    if hasattr(resource, "filename"):
+        name = resource.filename
+    else:
+        name = "resource"
 
-	if resource.status == RNS.Resource.COMPLETE:
-		RNS.log("Done sending \""+name+"\" to client")
-	elif resource.status == RNS.Resource.FAILED:
-		RNS.log("Sending \""+name+"\" to client failed")
+    if resource.status == RNS.Resource.COMPLETE:
+        RNS.log("Done sending \""+name+"\" to client")
+    elif resource.status == RNS.Resource.FAILED:
+        RNS.log("Sending \""+name+"\" to client failed")
 
 def list_delivered(receipt):
-	RNS.log("The file list was received by the client")
+    RNS.log("The file list was received by the client")
 
 def list_timeout(receipt):
-	RNS.log("Sending list to client timed out, closing this link")
-	link = receipt.destination
-	link.teardown()
+    RNS.log("Sending list to client timed out, closing this link")
+    link = receipt.destination
+    link.teardown()
 
 ##########################################################
 #### Client Part #########################################
 ##########################################################
 
 # We store a global list of files available on the server
-server_files = []
+server_files      = []
 
 # A reference to the server link
-server_link = None
+server_link       = None
 
 # And a reference to the current download
-current_download = None
-current_filename = None
+current_download  = None
+current_filename  = None
+
+# Variables to store download statistics
+download_started  = 0
+download_finished = 0
+download_time     = 0
+transfer_size     = 0
+file_size         = 0
+
 
 # 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 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)
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
 
 
-	# Check if we know a path to the destination
-	if not RNS.Transport.hasPath(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):
-			time.sleep(0.1)
+    # 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)
+    # 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...")
+    # 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, "filetransfer", "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,
+        "filetransfer",
+        "server"
+    )
 
-	# We also want to automatically prove incoming packets
-	server_destination.set_proof_strategy(RNS.Destination.PROVE_ALL)
+    # We also want to automatically prove incoming packets
+    server_destination.set_proof_strategy(RNS.Destination.PROVE_ALL)
 
-	# And create a link
-	link = RNS.Link(server_destination)
+    # And create a link
+    link = RNS.Link(server_destination)
 
-	# 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)
+    # We expect any normal data packets on the link
+    # to contain a list of served files, so we set
+    # a callback accordingly
+    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)
+    # 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)
 
-	# 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)
+    # And set the link to automatically begin
+    # downloading advertised resources
+    link.set_resource_strategy(RNS.Link.ACCEPT_ALL)
+    link.set_resource_started_callback(download_began)
+    link.set_resource_concluded_callback(download_concluded)
 
-	menu()
+    menu()
 
 # Requests the specified file from the server
 def download(filename):
-	global server_link, menu_mode, current_filename
-	current_filename = filename
+    global server_link, menu_mode, current_filename, transfer_size, download_started
+    current_filename = filename
+    download_started = 0
+    transfer_size    = 0
 
-	# We just create a packet containing the
-	# requested filename, and send it down the
-	# link. We also specify we don't need a
-	# packet receipt.
-	request_packet = RNS.Packet(server_link, filename.encode("utf-8"), create_receipt=False)
-	request_packet.send()
-	
-	print("")
-	print(("Requested \""+filename+"\" from server, waiting for download to begin..."))
-	menu_mode = "download_started"
+    # We just create a packet containing the
+    # requested filename, and send it down the
+    # link. We also specify we don't need a
+    # packet receipt.
+    request_packet = RNS.Packet(server_link, filename.encode("utf-8"), create_receipt=False)
+    request_packet.send()
+    
+    print("")
+    print(("Requested \""+filename+"\" from server, waiting for download to begin..."))
+    menu_mode = "download_started"
 
 # This function runs a simple menu for the user
 # to select which files to download, or quit
 menu_mode = None
 def menu():
-	global server_files, server_link
-	# Wait until we have a filelist
-	while len(server_files) == 0:
-		time.sleep(0.1)
-	RNS.log("Ready!")
-	time.sleep(0.5)
+    global server_files, server_link
+    # Wait until we have a filelist
+    while len(server_files) == 0:
+        time.sleep(0.1)
+    RNS.log("Ready!")
+    time.sleep(0.5)
 
-	global menu_mode
-	menu_mode = "main"
-	should_quit = False
-	while (not should_quit):
-		print_menu()
+    global menu_mode
+    menu_mode = "main"
+    should_quit = False
+    while (not should_quit):
+        print_menu()
 
-		while not menu_mode == "main":
-			# Wait
-			time.sleep(0.25)
+        while not menu_mode == "main":
+            # Wait
+            time.sleep(0.25)
 
-		user_input = input()
-		if user_input == "q" or user_input == "quit" or user_input == "exit":
-			should_quit = True
-			print("")
-		else:
-			if user_input in server_files:
-				download(user_input)
-			else:
-				try:
-					if 0 <= int(user_input) < len(server_files):
-						download(server_files[int(user_input)])
-				except:
-					pass
+        user_input = input()
+        if user_input == "q" or user_input == "quit" or user_input == "exit":
+            should_quit = True
+            print("")
+        else:
+            if user_input in server_files:
+                download(user_input)
+            else:
+                try:
+                    if 0 <= int(user_input) < len(server_files):
+                        download(server_files[int(user_input)])
+                except:
+                    pass
 
-	if should_quit:
-		server_link.teardown()
+    if should_quit:
+        server_link.teardown()
 
 # Prints out menus or screens for the
 # various states of the client program.
@@ -292,164 +336,204 @@ def menu():
 # I won't go into detail here. Just
 # strings basically.
 def print_menu():
-	global menu_mode
+    global menu_mode, download_time, download_started, download_finished, transfer_size, file_size
 
-	if menu_mode == "main":
-		clear_screen()
-		print_filelist()
-		print("")
-		print("Select a file to download by entering name or number, or q to quit")
-		print(("> "), end=' ')
-	elif menu_mode == "download_started":
-		download_began = time.time()
-		while menu_mode == "download_started":
-			time.sleep(0.1)
-			if time.time() > download_began+APP_TIMEOUT:
-				print("The download timed out")
-				time.sleep(1)
-				server_link.teardown()
+    if menu_mode == "main":
+        clear_screen()
+        print_filelist()
+        print("")
+        print("Select a file to download by entering name or number, or q to quit")
+        print(("> "), end=' ')
+    elif menu_mode == "download_started":
+        download_began = time.time()
+        while menu_mode == "download_started":
+            time.sleep(0.1)
+            if time.time() > download_began+APP_TIMEOUT:
+                print("The download timed out")
+                time.sleep(1)
+                server_link.teardown()
 
-	if menu_mode == "downloading":
-		print("Download started")
-		print("")
-		while menu_mode == "downloading":
-			global current_download
-			percent = round(current_download.progress() * 100.0, 1)
-			print(("\rProgress: "+str(percent)+" %   "), end=' ')
-			sys.stdout.flush()
-			time.sleep(0.1)
+    if menu_mode == "downloading":
+        print("Download started")
+        print("")
+        while menu_mode == "downloading":
+            global current_download
+            percent = round(current_download.progress() * 100.0, 1)
+            print(("\rProgress: "+str(percent)+" %   "), end=' ')
+            sys.stdout.flush()
+            time.sleep(0.1)
 
-	if menu_mode == "save_error":
-		print(("\rProgress: 100.0 %"), end=' ')
-		sys.stdout.flush()
-		print("")
-		print("Could not write downloaded file to disk")
-		current_download.status = RNS.Resource.FAILED
-		menu_mode = "download_concluded"
+    if menu_mode == "save_error":
+        print(("\rProgress: 100.0 %"), end=' ')
+        sys.stdout.flush()
+        print("")
+        print("Could not write downloaded file to disk")
+        current_download.status = RNS.Resource.FAILED
+        menu_mode = "download_concluded"
 
-	if menu_mode == "download_concluded":
-		if current_download.status == RNS.Resource.COMPLETE:
-			print(("\rProgress: 100.0 %"), end=' ')
-			sys.stdout.flush()
-			print("")
-			print("The download completed! Press enter to return to the menu.")
-			input()
+    if menu_mode == "download_concluded":
+        if current_download.status == RNS.Resource.COMPLETE:
+            print(("\rProgress: 100.0 %"), end=' ')
+            sys.stdout.flush()
 
-		else:
-			print("")
-			print("The download failed! Press enter to return to the menu.")
-			input()
+            # Print statistics
+            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("\tFile size        : "+size_str(file_size))
+            print("\tData transferred : "+size_str(transfer_size))
+            print("\tEffective rate   : "+size_str(file_size/download_time, suffix='b')+"/s")
+            print("\tTransfer rate    : "+size_str(transfer_size/download_time, suffix='b')+"/s")
+            print("")
+            print("The download completed! Press enter to return to the menu.")
+            print("")
+            input()
 
-		current_download = None
-		menu_mode = "main"
-		print_menu()
+        else:
+            print("")
+            print("The download failed! Press enter to return to the menu.")
+            input()
+
+        current_download = None
+        menu_mode = "main"
+        print_menu()
 
 # This function prints out a list of files
 # on the connected server.
 def print_filelist():
-	global server_files
-	print("Files on server:")
-	for index,file in enumerate(server_files):
-		print("\t("+str(index)+")\t"+file)
+    global server_files
+    print("Files on server:")
+    for index,file in enumerate(server_files):
+        print("\t("+str(index)+")\t"+file)
 
 def filelist_received(filelist_data, packet):
-	global server_files, menu_mode
-	try:
-		# Unpack the list and extend our
-		# local list of available files
-		filelist = umsgpack.unpackb(filelist_data)
-		for file in filelist:
-			if not file in server_files:
-				server_files.append(file)
+    global server_files, menu_mode
+    try:
+        # Unpack the list and extend our
+        # local list of available files
+        filelist = umsgpack.unpackb(filelist_data)
+        for file in filelist:
+            if not file in server_files:
+                server_files.append(file)
 
-		# If the menu is already visible,
-		# we'll update it with what was
-		# just received
-		if menu_mode == "main":
-			print_menu()
-	except:
-		RNS.log("Invalid file list data received, closing link")
-		packet.link.teardown()
+        # If the menu is already visible,
+        # we'll update it with what was
+        # just received
+        if menu_mode == "main":
+            print_menu()
+    except:
+        RNS.log("Invalid file list data received, closing link")
+        packet.link.teardown()
 
 # This function is called when a link
 # has been established with the server
 def link_established(link):
-	# We store a reference to the link
-	# instance for later use
-	global server_link
-	server_link = link
+    # 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")
-	RNS.log("Waiting for filelist...")
+    # Inform the user that the server is
+    # connected
+    RNS.log("Link established with server")
+    RNS.log("Waiting for filelist...")
 
-	# And set up a small job to check for
-	# a potential timeout in receiving the
-	# file list
-	thread = threading.Thread(target=filelist_timeout_job)
-	thread.setDaemon(True)
-	thread.start()
+    # And set up a small job to check for
+    # a potential timeout in receiving the
+    # file list
+    thread = threading.Thread(target=filelist_timeout_job)
+    thread.setDaemon(True)
+    thread.start()
 
 # This job just sleeps for the specified
 # time, and then checks if the file list
 # was received. If not, the program will
 # exit.
 def filelist_timeout_job():
-	time.sleep(APP_TIMEOUT)
+    time.sleep(APP_TIMEOUT)
 
-	global server_files
-	if len(server_files) == 0:
-		RNS.log("Timed out waiting for filelist, exiting")
-		os._exit(0)
+    global server_files
+    if len(server_files) == 0:
+        RNS.log("Timed out waiting for filelist, exiting")
+        os._exit(0)
 
 
 # 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)
+    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 RNS detects that the download has
 # started, we'll update our menu state
 # so the user can be shown a progress of
 # the download.
 def download_began(resource):
-	global menu_mode, current_download
-	current_download = resource
-	menu_mode = "downloading"
+    global menu_mode, current_download, download_started, transfer_size, file_size
+    current_download = resource
+    
+    if download_started == 0:
+        download_started = time.time()
+    
+    transfer_size += resource.size
+    file_size = resource.total_size
+    
+    menu_mode = "downloading"
 
 # When the download concludes, successfully
 # or not, we'll update our menu state and 
 # inform the user about how it all went.
 def download_concluded(resource):
-	global menu_mode, current_filename
-	saved_filename = current_filename
+    global menu_mode, current_filename, download_started, download_finished, download_time
+    download_finished = time.time()
+    download_time = download_finished - download_started
 
-	if resource.status == RNS.Resource.COMPLETE:
-		counter = 0
-		while os.path.isfile(saved_filename):
-			counter += 1
-			saved_filename = current_filename+"."+str(counter)
+    saved_filename = current_filename
 
-		try:
-			file = open(saved_filename, "wb")
-			file.write(resource.data)
-			file.close()
-			menu_mode = "download_concluded"
-		except:
-			menu_mode = "save_error"
-	else:
-		menu_mode = "download_concluded"
+    if resource.status == RNS.Resource.COMPLETE:
+        counter = 0
+        while os.path.isfile(saved_filename):
+            counter += 1
+            saved_filename = current_filename+"."+str(counter)
 
+        try:
+            file = open(saved_filename, "wb")
+            file.write(resource.data.read())
+            file.close()
+            menu_mode = "download_concluded"
+        except:
+            menu_mode = "save_error"
+    else:
+        menu_mode = "download_concluded"
+
+# 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)
 
 # A convenience function for clearing the screen
 def clear_screen():
@@ -463,31 +547,55 @@ def clear_screen():
 # and parses input of from the user, and then
 # 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)
-		args = parser.parse_args()
+    try:
+        parser = argparse.ArgumentParser(
+            description="Simple file transfer server and client utility"
+        )
 
-		if args.config:
-			configarg = args.config
-		else:
-			configarg = None
+        parser.add_argument(
+            "-s",
+            "--serve",
+            action="store",
+            metavar="dir",
+            help="serve a directory of files to clients"
+        )
 
-		if args.serve:
-			if os.path.isdir(args.serve):
-				server(configarg, args.serve)
-			else:
-				RNS.log("The specified directory does not exist")
-		else:
-			if (args.destination == None):
-				print("")
-				parser.print_help()
-				print("")
-			else:
-				client(args.destination, configarg)
+        parser.add_argument(
+            "--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
 
-	except KeyboardInterrupt:
-		print("")
-		exit()
+        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.serve:
+            if os.path.isdir(args.serve):
+                server(configarg, args.serve)
+            else:
+                RNS.log("The specified directory does not exist")
+        else:
+            if (args.destination == None):
+                print("")
+                parser.print_help()
+                print("")
+            else:
+                client(args.destination, configarg)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()

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 #########################################
@@ -25,65 +25,76 @@ 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 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, "linkexample")
+    # 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"
+    )
 
-	# 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)
+    # 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)
+    # Everything's ready!
+    # Let's Wait for client requests or user input
+    server_loop(server_destination)
 
 def server_loop(destination):
-	# Let the user know that everything is ready
-	RNS.log("Link example "+RNS.prettyhexrep(destination.hash)+" running, waiting for a connection.")
-	RNS.log("Hit enter to manually send an announce (Ctrl-C to quit)")
+    # Let the user know that everything is ready
+    RNS.log(
+        "Link example "+
+        RNS.prettyhexrep(destination.hash)+
+        " running, waiting for a connection."
+    )
 
-	# 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))
+    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
+    global latest_client_link
 
-	RNS.log("Client connected")
-	link.link_closed_callback(client_disconnected)
-	link.packet_callback(server_packet_received)
-	latest_client_link = link
+    RNS.log("Client connected")
+    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")
+    RNS.log("Client disconnected")
 
 def server_packet_received(message, packet):
-	global latest_client_link
+    global latest_client_link
 
-	# 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 on the link: "+text)
-	
-	reply_text = "I received \""+text+"\" over the link"
-	reply_data = reply_text.encode("utf-8")
-	RNS.Packet(latest_client_link, reply_data).send()
+    # 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 on the link: "+text)
+    
+    reply_text = "I received \""+text+"\" over the link"
+    reply_data = reply_text.encode("utf-8")
+    RNS.Packet(latest_client_link, reply_data).send()
 
 
 ##########################################################
@@ -96,112 +107,128 @@ 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 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)
+    # We must first initialise Reticulum
+    reticulum = RNS.Reticulum(configpath)
 
-	# Check if we know a path to the destination
-	if not RNS.Transport.hasPath(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):
-			time.sleep(0.1)
+    # 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)
+    # 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...")
+    # 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, "linkexample")
+    # 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"
+    )
 
-	# And create a link
-	link = RNS.Link(server_destination)
+    # 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.packet_callback(client_packet_received)
+    # 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.link_established_callback(link_established)
-	link.link_closed_callback(link_closed)
+    # 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()
+    # 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
+    global server_link
 
-	# Wait for the link to become active
-	while not server_link:
-		time.sleep(0.1)
+    # 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()
+    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()
+            # 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")
-				RNS.Packet(server_link, data).send()
-		except Exception as e:
-			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
-	server_link = 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, enter some text to send, or \"quit\" to quit")
+    # Inform the user that the server is
+    # connected
+    RNS.log("Link established with server, enter some text to send, or \"quit\" to quit")
 
 # When a link is closed, we'll inform the
 # user, and exit the program
 def link_closed(link):
-	if link.teardown_reason == RNS.Link.TIMEOUT:
-		RNS.log("The link timed out, exiting now")
-	elif link.teardown_reason == RNS.Link.DESTINATION_CLOSED:
-		RNS.log("The link was closed by the server, exiting now")
-	else:
-		RNS.log("Link closed, exiting now")
-	
-	RNS.Reticulum.exit_handler()
-	time.sleep(1.5)
-	os._exit(0)
+    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()
+    text = message.decode("utf-8")
+    RNS.log("Received data on the link: "+text)
+    print("> ", end=" ")
+    sys.stdout.flush()
 
 
 ##########################################################
@@ -212,28 +239,49 @@ def client_packet_received(message, packet):
 # 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()
+    try:
+        parser = argparse.ArgumentParser(description="Simple link example")
 
-		if args.config:
-			configarg = args.config
-		else:
-			configarg = None
+        parser.add_argument(
+            "-s",
+            "--server",
+            action="store_true",
+            help="wait for incoming link requests from clients"
+        )
 
-		if args.server:
-			server(configarg)
-		else:
-			if (args.destination == None):
-				print("")
-				parser.print_help()
-				print("")
-			else:
-				client(args.destination, configarg)
+        parser.add_argument(
+            "--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
 
-	except KeyboardInterrupt:
-		print("")
-		exit()
+        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/Minimal.py

@@ -11,49 +11,59 @@ 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):
-	# We must first initialise Reticulum
-	reticulum = RNS.Reticulum(configpath)
-	
-	# Randomly create a new identity for our example
-	identity = RNS.Identity()
+    # 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 a destination.
-	# 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 = RNS.Destination(identity, RNS.Destination.IN, RNS.Destination.SINGLE, APP_NAME, "minimalsample")
+    # Using the identity we just created, we create a destination.
+    # 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 = 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
-	# 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.set_proof_strategy(RNS.Destination.PROVE_ALL)
-	
-	# Everything's ready!
-	# Let's hand over control to the announce loop
-	announceLoop(destination)
+    # We configure the destination 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.set_proof_strategy(RNS.Destination.PROVE_ALL)
+    
+    # Everything's ready!
+    # Let's hand over control to the announce loop
+    announceLoop(destination)
 
 
 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)")
+    # 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)"
+    )
 
-	# 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))
+    # 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))
 
 
 ##########################################################
@@ -64,18 +74,28 @@ def announceLoop(destination):
 # and parses input from the user, and then starts
 # 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)
-		args = parser.parse_args()
+    try:
+        parser = argparse.ArgumentParser(
+            description="Minimal example to start Reticulum and create a destination"
+        )
 
-		if args.config:
-			configarg = args.config
-		else:
-			configarg = None
+        parser.add_argument(
+            "--config",
+            action="store",
+            default=None,
+            help="path to alternative Reticulum config directory",
+            type=str
+        )
 
-		program_setup(configarg)
+        args = parser.parse_args()
 
-	except KeyboardInterrupt:
-		print("")
-		exit()
+        if args.config:
+            configarg = args.config
+        else:
+            configarg = None
+
+        program_setup(configarg)
+
+    except KeyboardInterrupt:
+        print("")
+        exit()

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()

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 for extended header format
-
-
-Propagation Types
------------------
-broadcast       00
-transport       01
-relay           10
-tunnel          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,837 +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 high-latency, wide-area networks built on readily available hardware. 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, resource caching, unforgeable packet acknowledgements and much more.</p>
-<p>Reticulum is a complete networking stack, and does not use IP or higher layers, although it can be easily tunnelled through conventional IP networks. This frees 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-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, 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 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 experimental at this stage. Most features are implemented and working, but at this point the protocol may still change significantly, and is made publicly available for development collaboration, previewing and testing.</p>
-<p>An API- and wireformat-stable alpha release is coming in the near future. Until then expect things to change unexpectedly if something warrants it.</p>
-<h2>
-<a id="user-content-what-is-implemented-at-this-point" class="anchor" href="#what-is-implemented-at-this-point" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>What is implemented at this point?</h2>
-<ul>
-<li>Adressing and identification</li>
-<li>Fully self-configuring multi-hop routing</li>
-<li>RSA assymetric encryption and signatures as basis for all communication</li>
-<li>AES-128 symmetric encryption for group destinations</li>
-<li>Elliptic curve encryption for links (on the SECP256R1 curve)</li>
-<li>Perfect Forward Secrecy on links with ephemereal ECDH keys</li>
-<li>Unforgeable packet delivery confirmations</li>
-<li>A variety of supported interface types</li>
-<li>Efficient and easy resource transfers</li>
-<li>A simple and easy-to-use API</li>
-<li>Some basic programming examples</li>
-</ul>
-<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 tolerant bundle transfers</li>
-<li>Useful example programs and utilities</li>
-<li>API documentation</li>
-<li>A messaging 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 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 alpha software, and should be considered experimental. 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,40 +1,53 @@
-Reticulum Network Stack α
+Reticulum Network Stack β
 ==========
 
-Reticulum is a cryptography-based networking stack for high-latency, wide-area networks built on readily available hardware. 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, resource caching, unforgeable packet acknowledgements and much more.
+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 can be easily tunnelled through conventional IP networks. This frees 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.
+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.
+
+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/)
 
-## 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, free-space optical links and similar systems are all examples of the types of interfaces Reticulum was designed for.
+## Notable Features
+ - Coordination-less globally unique adressing and identification
+ - Fully self-configuring multi-hop routing
+ - 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 encryption
+    - AES-128 in CBC mode with PKCS7 padding
+    - HMAC using SHA256 for authentication
+    - IVs are generated through os.urandom()
+    - Keys are ephemeral and derived from an ECDH key exchange on Curve25519
+ - Unforgeable packet delivery confirmations
+ - A variety of supported interface types
+ - An intuitive and easy-to-use 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
+ - Lightweight, flexible and expandable Request/Response mechanism
+ - Efficient link establishment
+    - Total bandwidth cost of setting up a link is 3 packets totalling 240 bytes
+    - Low cost of keeping links open at only 0.62 bits per second
 
-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 can be purchased as a complete transceiver that just needs a USB connection to the host.
+## Where can Reticulum be used?
+Over practically any medium 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.
+
+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.
 
 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.
 
 ## Current Status
-Consider Reticulum experimental at this stage. Most features are implemented and working, but at this point the protocol may still change significantly, and is made publicly available for development collaboration, previewing and testing.
-
-An API- and wireformat-stable alpha release is coming in the near future. Until then expect things to change unexpectedly if something warrants it.
-
-## What is implemented at this point?
- - Adressing and identification
- - Fully self-configuring multi-hop routing
- - RSA assymetric encryption and signatures as basis for all communication
- - AES-128 symmetric encryption for group destinations
- - Elliptic curve encryption for links (on the SECP256R1 curve)
- - Perfect Forward Secrecy on links with ephemereal ECDH keys
- - Unforgeable packet delivery confirmations
- - A variety of supported interface types
- - Efficient and easy resource transfers
- - A simple and easy-to-use API
- - Some basic programming examples
+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
 
@@ -48,10 +61,9 @@ Reticulum implements a range of generalised interface types that covers most of
  - UDP over IP networks
 
 ## What is currently being worked on?
- - Delay/disruption tolerant bundle transfers
- - Useful example programs and utilities
  - API documentation
- - A messaging protocol built on Reticulum, see [LXMF](https://github.com/markqvist/lxmf)
+ - Useful example programs and utilities
+ - A delay and disruption tolerant 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?
@@ -63,52 +75,18 @@ 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 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.
 
 ## Caveat Emptor
-Reticulum is alpha software, and should be considered experimental. 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

@@ -5,233 +5,398 @@ 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):
-		self.link_established = None
-		self.packet = None
-		self.proof_requested = None
+    def __init__(self):
+        self.link_established = None
+        self.packet = None
+        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.
 
-	# Constants
-	SINGLE     = 0x00
-	GROUP      = 0x01
-	PLAIN      = 0x02
-	LINK       = 0x03
-	types      = [SINGLE, GROUP, PLAIN, LINK]
+    :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.
+    """
 
-	PROVE_NONE = 0x21
-	PROVE_APP  = 0x22
-	PROVE_ALL  = 0x23
-	proof_strategies = [PROVE_NONE, PROVE_APP, PROVE_ALL]
+    # Constants
+    SINGLE     = 0x00
+    GROUP      = 0x01
+    PLAIN      = 0x02
+    LINK       = 0x03
+    types      = [SINGLE, GROUP, PLAIN, LINK]
 
-	IN         = 0x11;
-	OUT        = 0x12;
-	directions = [IN, OUT]
+    PROVE_NONE = 0x21
+    PROVE_APP  = 0x22
+    PROVE_ALL  = 0x23
+    proof_strategies = [PROVE_NONE, PROVE_APP, PROVE_ALL]
 
-	@staticmethod
-	def getDestinationName(app_name, *aspects):
-		# Check input values and build name string
-		if "." in app_name: raise ValueError("Dots can't be used in app names")
+    ALLOW_NONE = 0x00
+    ALLOW_ALL  = 0x01
+    ALLOW_LIST = 0x02
+    request_policies = [ALLOW_NONE, ALLOW_ALL, ALLOW_LIST]
 
-		name = app_name
-		for aspect in aspects:
-			if "." in aspect: raise ValueError("Dots can't be used in aspects")
-			name = name + "." + aspect
+    IN         = 0x11;
+    OUT        = 0x12;
+    directions = [IN, OUT]
 
-		return name
+    @staticmethod
+    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")
+
+        name = app_name
+        for aspect in aspects:
+            if "." in aspect: raise ValueError("Dots can't be used in aspects")
+            name = name + "." + aspect
+
+        return name
 
 
-	@staticmethod
-	def getDestinationHash(app_name, *aspects):
-		name = Destination.getDestinationName(app_name, *aspects)
+    @staticmethod
+    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())
-		digest.update(name.encode("UTF-8"))
+        # Create a digest for the destination
+        digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
+        digest.update(name.encode("UTF-8"))
 
-		return digest.finalize()[:10]
+        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
+        if "." in app_name: raise ValueError("Dots can't be used in app names") 
+        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
+        self.mtu = 0
+
+        self.links = []
+
+        if identity != None and type == Destination.SINGLE:
+            aspects = aspects+(identity.hexhash,)
+
+        if identity == None and direction == Destination.IN and self.type != Destination.PLAIN:
+            identity = RNS.Identity()
+            aspects = aspects+(identity.hexhash,)
+
+        self.identity = identity
+
+        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.register_destination(self)
 
 
-	def __init__(self, identity, direction, type, app_name, *aspects):
-		# Check input values and build name string
-		if "." in app_name: raise ValueError("Dots can't be used in app names") 
-		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.type = type
-		self.direction = direction
-		self.proof_strategy = Destination.PROVE_NONE
-		self.mtu = 0
-
-		self.links = []
-
-		if identity != None and type == Destination.SINGLE:
-			aspects = aspects+(identity.hexhash,)
-
-		if identity == None and direction == Destination.IN and self.type != Destination.PLAIN:
-			identity = RNS.Identity()
-			aspects = aspects+(identity.hexhash,)
-
-		self.identity = identity
-
-		self.name = Destination.getDestinationName(app_name, *aspects)		
-		self.hash = Destination.getDestinationHash(app_name, *aspects)
-		self.hexhash = self.hash.hex()
-
-		self.callback = None
-		self.proofcallback = None
-
-		RNS.Transport.registerDestination(self)
+    def __str__(self):
+        """
+        :returns: A human-readable representation of the destination including addressable hash and full name.
+        """
+        return "<"+self.name+"/"+self.hexhash+">"
 
 
-	def __str__(self):
-		return "<"+self.name+"/"+self.hexhash+">"
+    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()
+
+        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 link_established_callback(self, callback):
-		self.callbacks.link_established = callback
+    def set_link_established_callback(self, callback):
+        """
+        Registers a function to be called when a link has been established to
+        this destination.
 
-	def packet_callback(self, callback):
-		self.callbacks.packet = callback
+        :param callback: A function or method to be called.
+        """
+        self.callbacks.link_established = callback
 
-	def proof_requested_callback(self, callback):
-		self.callbacks.proof_requested = callback
+    def set_packet_callback(self, callback):
+        """
+        Registers a function to be called when a packet has been received by
+        this destination.
 
-	def set_proof_strategy(self, proof_strategy):
-		if not proof_strategy in Destination.proof_strategies:
-			raise TypeError("Unsupported proof strategy")
-		else:
-			self.proof_strategy = proof_strategy
+        :param callback: A function or method to be called.
+        """
+        self.callbacks.packet = callback
 
-	def receive(self, packet):
-		plaintext = self.decrypt(packet.data)
-		if plaintext != None:
-			if packet.packet_type == RNS.Packet.LINKREQUEST:
-				self.incomingLinkRequest(plaintext, packet)
+    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.
 
-			if packet.packet_type == RNS.Packet.DATA:
-				if self.callbacks.packet != None:
-					self.callbacks.packet(plaintext, packet)
+        :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 incomingLinkRequest(self, data, packet):
-		link = RNS.Link.validateRequest(self, data, packet)
-		if link != None:
-			self.links.append(link)
+    def set_proof_strategy(self, proof_strategy):
+        """
+        Sets the destinations proof strategy.
 
-	def createKeys(self):
-		if self.type == Destination.PLAIN:
-			raise TypeError("A plain destination does not hold any keys")
-
-		if self.type == Destination.SINGLE:
-			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)
+        :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 getPrivateKey(self):
-		if self.type == Destination.PLAIN:
-			raise TypeError("A plain destination does not hold any keys")
-		elif self.type == Destination.SINGLE:
-			raise TypeError("A single destination holds keys through an Identity instance")
-		else:
-			return self.prv_bytes
+    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 loadPrivateKey(self, key):
-		if self.type == Destination.PLAIN:
-			raise TypeError("A plain destination does not hold any keys")
+    def deregister_request_handler(self, path):
+        """
+        Deregisters a request handler.
 
-		if self.type == Destination.SINGLE:
-			raise TypeError("A single destination holds keys through an Identity instance")
+        :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
 
-		if self.type == Destination.GROUP:
-			self.prv_bytes = key
-			self.prv = Fernet(self.prv_bytes)
+        
 
-	def loadPublicKey(self, key):
-		if self.type != Destination.SINGLE:
-			raise TypeError("Only the \"single\" destination type can hold a public key")
-		else:
-			raise TypeError("A single destination holds keys through an Identity instance")
+    def receive(self, 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:
+                        self.callbacks.packet(plaintext, packet)
+
+    def incoming_link_request(self, data, packet):
+        link = RNS.Link.validate_request(self, data, packet)
+        if link != None:
+            self.links.append(link)
+
+    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")
+
+        if self.type == Destination.SINGLE:
+            raise TypeError("A single destination holds keys through an Identity instance")
+
+        if self.type == Destination.GROUP:
+            self.prv_bytes = base64.urlsafe_b64decode(Fernet.generate_key())
+            self.prv = Fernet(base64.urlsafe_b64encode(self.prv_bytes))
 
 
-	def encrypt(self, plaintext):
-		if self.type == Destination.PLAIN:
-			return plaintext
+    def get_private_key(self):
+        """
+        For a ``RNS.Destination.GROUP`` type destination, returns the symmetric private key.
 
-		if self.type == Destination.SINGLE and self.identity != None:
-			return self.identity.encrypt(plaintext)
+        :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:
+            raise TypeError("A single destination holds keys through an Identity instance")
+        else:
+            return self.prv_bytes
 
-		if self.type == Destination.GROUP:
-			if hasattr(self, "prv") and self.prv != None:
-				try:
-					return base64.urlsafe_b64decode(self.prv.encrypt(plaintext))
-				except Exception as e:
-					RNS.log("The GROUP destination could not encrypt data", RNS.LOG_ERROR)
-					RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
-			else:
-				raise ValueError("No private key held by GROUP destination. Did you create or load one?")
+
+    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")
+
+        if self.type == Destination.SINGLE:
+            raise TypeError("A single destination holds keys through an Identity instance")
+
+        if self.type == Destination.GROUP:
+            self.prv_bytes = key
+            self.prv = Fernet(base64.urlsafe_b64encode(self.prv_bytes))
+
+    def load_public_key(self, key):
+        if self.type != Destination.SINGLE:
+            raise TypeError("Only the \"single\" destination type can hold a public key")
+        else:
+            raise TypeError("A single destination holds keys through an Identity instance")
+
+
+    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
+
+        if self.type == Destination.SINGLE and self.identity != None:
+            return self.identity.encrypt(plaintext)
+
+        if self.type == Destination.GROUP:
+            if hasattr(self, "prv") and self.prv != None:
+                try:
+                    return base64.urlsafe_b64decode(self.prv.encrypt(plaintext))
+                except Exception as e:
+                    RNS.log("The GROUP destination could not encrypt data", RNS.LOG_ERROR)
+                    RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+            else:
+                raise ValueError("No private key held by GROUP destination. Did you create or load one?")
 
 
 
-	def decrypt(self, ciphertext):
-		if self.type == Destination.PLAIN:
-			return ciphertext
+    def decrypt(self, ciphertext):
+        """
+        Decrypts information for ``RNS.Destination.SINGLE`` or ``RNS.Destination.GROUP`` type destination.
 
-		if self.type == Destination.SINGLE and self.identity != None:
-			return self.identity.decrypt(ciphertext)
+        :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
 
-		if self.type == Destination.GROUP:
-			if hasattr(self, "prv") and self.prv != None:
-				try:
-					return self.prv.decrypt(base64.urlsafe_b64encode(ciphertext))
-				except Exception as e:
-					RNS.log("The GROUP destination could not decrypt data", RNS.LOG_ERROR)
-					RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
-			else:
-				raise ValueError("No private key held by GROUP destination. Did you create or load one?")
+        if self.type == Destination.SINGLE and self.identity != None:
+            return self.identity.decrypt(ciphertext)
+
+        if self.type == Destination.GROUP:
+            if hasattr(self, "prv") and self.prv != None:
+                try:
+                    return self.prv.decrypt(base64.urlsafe_b64encode(ciphertext))
+                except Exception as e:
+                    RNS.log("The GROUP destination could not decrypt data", RNS.LOG_ERROR)
+                    RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+            else:
+                raise ValueError("No private key held by GROUP destination. Did you create or load one?")
 
 
-	def sign(self, message):
-		if self.type == Destination.SINGLE and self.identity != None:
-			return self.identity.sign(message)
-		else:
-			return None
+    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
 
-	# 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
+    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.
 
-		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,323 +4,484 @@ 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.
 
-	# Non-configurable constants
-	PADDINGSIZE = 336		# In bits
-	HASHLENGTH  = 256		# In bits
-	SIGLENGTH   = KEYSIZE
+    :param create_keys: Specifies whether new encryption and signing keys should be generated.
+    """
 
-	ENCRYPT_CHUNKSIZE = (KEYSIZE-PADDINGSIZE)//8
-	DECRYPT_CHUNKSIZE = KEYSIZE//8
+    CURVE = "Curve25519"
+    """
+    The curve used for Elliptic Curve DH key exchanges
+    """
 
-	TRUNCATED_HASHLENGTH = 80 # In bits
+    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.
+    """   
 
-	# Storage
-	known_destinations = {}
+    # Non-configurable constants
+    AES_HMAC_OVERHEAD = 58    # In bytes
+    AES128_BLOCKSIZE = 16     # In bytes
+    HASHLENGTH  = 256         # In bits
+    SIGLENGTH   = KEYSIZE     # In bits
 
-	@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]
+    TRUNCATED_HASHLENGTH = 80 # In bits
+    """
+    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):
+        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)
-		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)
-			return identity
-		else:
-			RNS.log("Could not find "+RNS.prettyhexrep(destination_hash)+" in known destinations", RNS.LOG_EXTREME)
-			return None
+    @staticmethod
+    def recall(destination_hash):
+        """
+        Recall identity for a destination hash.
 
-	@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)
+        :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.
+        """
+        RNS.log("Searching for "+RNS.prettyhexrep(destination_hash)+"...", RNS.LOG_EXTREME)
+        if destination_hash in Identity.known_destinations:
+            identity_data = Identity.known_destinations[destination_hash]
+            identity = Identity(create_keys=False)
+            identity.load_public_key(identity_data[2])
+            identity.app_data = identity_data[3]
+            RNS.log("Found "+RNS.prettyhexrep(destination_hash)+" in known destinations", RNS.LOG_EXTREME)
+            return identity
+        else:
+            RNS.log("Could not find "+RNS.prettyhexrep(destination_hash)+" in known destinations", RNS.LOG_EXTREME)
+            return None
 
-	@staticmethod
-	def loadKnownDestinations():
-		if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
-			try:
-				file = open(RNS.Reticulum.storagepath+"/known_destinations","rb")
-				Identity.known_destinations = umsgpack.load(file)
-				file.close()
-				RNS.log("Loaded "+str(len(Identity.known_destinations))+" known destination from storage", RNS.LOG_VERBOSE)
-			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)
+    @staticmethod
+    def recall_app_data(destination_hash):
+        """
+        Recall last heard app_data for a destination hash.
 
-	@staticmethod
-	def fullHash(data):
-		digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
-		digest.update(data)
+        :param destination_hash: Destination hash as *bytes*.
+        :returns: *Bytes* containing app_data, or *None* if the destination is unknown.
+        """
+        RNS.log("Searching for app_data for "+RNS.prettyhexrep(destination_hash)+"...", RNS.LOG_EXTREME)
+        if destination_hash in Identity.known_destinations:
+            app_data = Identity.known_destinations[destination_hash][3]
+            RNS.log("Found "+RNS.prettyhexrep(destination_hash)+" app_data in known destinations", RNS.LOG_EXTREME)
+            return app_data
+        else:
+            RNS.log("Could not find "+RNS.prettyhexrep(destination_hash)+" app_data in known destinations", RNS.LOG_EXTREME)
+            return None
 
-		return digest.finalize()
+    @staticmethod
+    def save_known_destinations():
+        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)
 
-	@staticmethod
-	def truncatedHash(data):
-		digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
-		digest.update(data)
+    @staticmethod
+    def load_known_destinations():
+        if os.path.isfile(RNS.Reticulum.storagepath+"/known_destinations"):
+            try:
+                file = open(RNS.Reticulum.storagepath+"/known_destinations","rb")
+                Identity.known_destinations = umsgpack.load(file)
+                file.close()
+                RNS.log("Loaded "+str(len(Identity.known_destinations))+" known destination from storage", RNS.LOG_VERBOSE)
+            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)
 
-		return digest.finalize()[:(Identity.TRUNCATED_HASHLENGTH//8)]
+    @staticmethod
+    def full_hash(data):
+        """
+        Get a SHA-256 hash of passed data.
 
-	@staticmethod
-	def getRandomHash():
-		return Identity.truncatedHash(os.urandom(10))
+        :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)
 
-	@staticmethod
-	def validateAnnounce(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]
-			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:]
+        return digest.finalize()
 
-			signed_data = destination_hash+public_key+random_hash+app_data
+    @staticmethod
+    def truncated_hash(data):
+        """
+        Get a truncated SHA-256 hash of passed data.
 
-			announced_identity = Identity(public_only=True)
-			announced_identity.loadPublicKey(public_key)
+        :param data: Data to be hashed as *bytes*.
+        :returns: Truncated SHA-256 hash as *bytes*
+        """
+        return Identity.full_hash(data)[:(Identity.TRUNCATED_HASHLENGTH//8)]
 
-			if announced_identity.pub != None and announced_identity.validate(signature, signed_data):
-				RNS.Identity.remember(packet.getHash(), destination_hash, public_key)
-				RNS.log("Stored valid announce from "+RNS.prettyhexrep(destination_hash), RNS.LOG_DEBUG)
-				del announced_identity
-				return True
-			else:
-				RNS.log("Received invalid announce", RNS.LOG_DEBUG)
-				del announced_identity
-				return False
+    @staticmethod
+    def get_random_hash():
+        """
+        Get a random SHA-256 hash.
 
-	@staticmethod
-	def exitHandler():
-		Identity.saveKnownDestinations()
+        :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 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[: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.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
+
+            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.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
+            else:
+                RNS.log("Received invalid announce", RNS.LOG_DEBUG)
+                del announced_identity
+                return False
+
+    @staticmethod
+    def exit_handler():
+        Identity.save_known_destinations()
 
 
-	@staticmethod
-	def from_file(path):
-		identity = Identity(public_only=True)
-		if identity.load(path):
-			return identity
-		else:
-			return 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.
+
+        :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
+
+    @staticmethod
+    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 not 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
+    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
 
-		if not public_only:
-			self.createKeys()
+        self.pub           = None
+        self.pub_bytes     = None
+        self.sig_pub       = None
+        self.sig_pub_bytes = None
 
-	def createKeys(self):
-		self.prv = rsa.generate_private_key(
-			public_exponent=65337,
-			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
-		)
+        self.hash          = None
+        self.hexhash       = None
 
-		self.updateHashes()
+        if create_keys:
+            self.create_keys()
 
-		RNS.log("Identity keys created for "+RNS.prettyhexrep(self.hash), RNS.LOG_VERBOSE)
+    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()
+        )
 
-	def getPrivateKey(self):
-		return self.prv_bytes
+        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()
+        )
 
-	def getPublicKey(self):
-		return self.pub_bytes
+        self.pub           = self.prv.public_key()
+        self.pub_bytes     = self.pub.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw
+        )
 
-	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()
+        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
+        )
 
-			return True
+        self.update_hashes()
 
-		except Exception as e:
-			RNS.log("Failed to load identity key", RNS.LOG_ERROR)
-			RNS.log("The contained exception was: "+str(e))
-			return False
+        RNS.log("Identity keys created for "+RNS.prettyhexrep(self.hash), RNS.LOG_VERBOSE)
 
-	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 get_private_key(self):
+        """
+        :returns: The private key as *bytes*
+        """
+        return self.prv_bytes+self.sig_prv_bytes
 
-	def updateHashes(self):
-		self.hash = Identity.truncatedHash(self.pub_bytes)
-		self.hexhash = self.hash.hex()
+    def get_public_key(self):
+        """
+        :returns: The public key as *bytes*
+        """
+        return self.pub_bytes+self.sig_pub_bytes
 
-	def save(self, path):
-		try:
-			with open(path, "wb") as key_file:
-				key_file.write(self.prv_bytes)
-				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 load_private_key(self, prv_bytes):
+        """
+        Load a private key into the instance.
 
-	def load(self, path):
-		try:
-			with open(path, "rb") as key_file:
-				prv_bytes = key_file.read()
-				return self.loadPrivateKey(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))
+        :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
+            )
 
-	def encrypt(self, plaintext):
-		if self.pub != None:
-			chunksize = Identity.ENCRYPT_CHUNKSIZE
-			chunks = int(math.ceil(len(plaintext)/(float(chunksize))))
+            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
+            )
 
-			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
-		else:
-			raise KeyError("Encryption failed because identity does not hold a public key")
+            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 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.
+
+        :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.get_public_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 load(self, path):
+        try:
+            with open(path, "rb") as key_file:
+                prv_bytes = key_file.read()
+                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 get_salt(self):
+        return self.hash
+
+    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):
-		if self.prv != None:
-			plaintext = None
-			try:
-				chunksize = Identity.DECRYPT_CHUNKSIZE
-				chunks = int(math.ceil(len(ciphertext)/(float(chunksize))))
+    def decrypt(self, ciphertext_token):
+        """
+        Decrypts information for the identity.
 
-				plaintext = b"";
-				for chunk in range(chunks):
-					start = chunk*chunksize
-					end = (chunk+1)*chunksize
-					if (chunk+1)*chunksize > len(ciphertext):
-						end = len(ciphertext)
+        :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:
+            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 += 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;
-		else:
-			raise KeyError("Decryption failed because identity does not hold a private key")
+                    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)
+
+                    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
-		else:
-			raise KeyError("Signing failed because identity does not hold a private key")
+    def sign(self, message):
+        """
+        Signs information by the identity.
 
-	def validate(self, signature, message):
-		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()
-				)
-				return True
-			except Exception as e:
-				return False
-		else:
-			raise KeyError("Signature validation failed because identity does not hold a public key")
+        :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 prove(self, packet, destination=None):
-		signature = self.sign(packet.packet_hash)
-		if RNS.Reticulum.should_use_implicit_proof():
-			proof_data = signature
-		else:
-			proof_data = packet.packet_hash + signature
-		
-		if destination == None:
-			destination = packet.generateProofDestination()
+    def validate(self, signature, message):
+        """
+        Validates the signature of a signed message.
 
-		proof = RNS.Packet(destination, proof_data, RNS.Packet.PROOF, attached_interface = packet.receiving_interface)
-		proof.send()
+        :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.sig_pub.verify(signature, message)
+                return True
+            except Exception as e:
+                return False
+        else:
+            raise KeyError("Signature validation failed because identity does not hold a public key")
 
-	def __str__(self):
-		return RNS.prettyhexrep(self.hash)
+    def prove(self, packet, destination=None):
+        signature = self.sign(packet.packet_hash)
+        if RNS.Reticulum.should_use_implicit_proof():
+            proof_data = signature
+        else:
+            proof_data = packet.packet_hash + signature
+        
+        if destination == None:
+            destination = packet.generate_proof_destination()
+
+        proof = RNS.Packet(destination, proof_data, RNS.Packet.PROOF, attached_interface = packet.receiving_interface)
+        proof.send()
+
+    def __str__(self):
+        return RNS.prettyhexrep(self.hash)

RNS/Interfaces/AX25KISSInterface.py

@@ -8,298 +8,298 @@ import time
 import RNS
 
 class KISS():
-	FEND			  = 0xC0
-	FESC			  = 0xDB
-	TFEND			  = 0xDC
-	TFESC			  = 0xDD
-	CMD_UNKNOWN		  = 0xFE
-	CMD_DATA		  = 0x00
-	CMD_TXDELAY		  = 0x01
-	CMD_P			  = 0x02
-	CMD_SLOTTIME	  = 0x03
-	CMD_TXTAIL		  = 0x04
-	CMD_FULLDUPLEX	  = 0x05
-	CMD_SETHARDWARE	  = 0x06
-	CMD_READY         = 0x0F
-	CMD_RETURN		  = 0xFF
+    FEND              = 0xC0
+    FESC              = 0xDB
+    TFEND             = 0xDC
+    TFESC             = 0xDD
+    CMD_UNKNOWN       = 0xFE
+    CMD_DATA          = 0x00
+    CMD_TXDELAY       = 0x01
+    CMD_P             = 0x02
+    CMD_SLOTTIME      = 0x03
+    CMD_TXTAIL        = 0x04
+    CMD_FULLDUPLEX    = 0x05
+    CMD_SETHARDWARE   = 0x06
+    CMD_READY         = 0x0F
+    CMD_RETURN        = 0xFF
 
-	@staticmethod
-	def escape(data):
-		data = data.replace(bytes([0xdb]), bytes([0xdb, 0xdd]))
-		data = data.replace(bytes([0xc0]), bytes([0xdb, 0xdc]))
-		return data
+    @staticmethod
+    def escape(data):
+        data = data.replace(bytes([0xdb]), bytes([0xdb, 0xdd]))
+        data = data.replace(bytes([0xc0]), bytes([0xdb, 0xdc]))
+        return data
 
 class AX25():
-	PID_NOLAYER3	= 0xF0
-	CTRL_UI			= 0x03
-	CRC_CORRECT     = bytes([0xF0])+bytes([0xB8])
-	HEADER_SIZE		= 16
+    PID_NOLAYER3    = 0xF0
+    CTRL_UI         = 0x03
+    CRC_CORRECT     = bytes([0xF0])+bytes([0xB8])
+    HEADER_SIZE     = 16
 
 
 class AX25KISSInterface(Interface):
-	MAX_CHUNK = 32768
+    MAX_CHUNK = 32768
 
-	owner    = None
-	port     = None
-	speed    = None
-	databits = None
-	parity   = None
-	stopbits = None
-	serial   = None
+    owner    = None
+    port     = None
+    speed    = None
+    databits = None
+    parity   = None
+    stopbits = None
+    serial   = None
 
-	def __init__(self, owner, name, callsign, ssid, port, speed, databits, parity, stopbits, preamble, txtail, persistence, slottime, flow_control):
-		self.serial   = None
-		self.owner    = owner
-		self.name	  = name
-		self.src_call = callsign.upper().encode("ascii")
-		self.src_ssid = ssid
-		self.dst_call = "APZRNS".encode("ascii")
-		self.dst_ssid = 0
-		self.port     = port
-		self.speed    = speed
-		self.databits = databits
-		self.parity   = serial.PARITY_NONE
-		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
+    def __init__(self, owner, name, callsign, ssid, port, speed, databits, parity, stopbits, preamble, txtail, persistence, slottime, flow_control):
+        self.serial   = None
+        self.owner    = owner
+        self.name     = name
+        self.src_call = callsign.upper().encode("ascii")
+        self.src_ssid = ssid
+        self.dst_call = "APZRNS".encode("ascii")
+        self.dst_ssid = 0
+        self.port     = port
+        self.speed    = speed
+        self.databits = databits
+        self.parity   = serial.PARITY_NONE
+        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.packet_queue    = []
+        self.flow_control    = flow_control
+        self.interface_ready = False
 
-		if (len(self.src_call) < 3 or len(self.src_call) > 6):
-			raise ValueError("Invalid callsign for "+str(self))
+        if (len(self.src_call) < 3 or len(self.src_call) > 6):
+            raise ValueError("Invalid callsign for "+str(self))
 
-		if (self.src_ssid < 0 or self.src_ssid > 15):
-			raise ValueError("Invalid SSID for "+str(self))
+        if (self.src_ssid < 0 or self.src_ssid > 15):
+            raise ValueError("Invalid SSID for "+str(self))
 
-		self.preamble    = preamble if preamble != None else 350;
-		self.txtail      = txtail if txtail != None else 20;
-		self.persistence = persistence if persistence != None else 64;
-		self.slottime    = slottime if slottime != None else 20;
+        self.preamble    = preamble if preamble != None else 350;
+        self.txtail      = txtail if txtail != None else 20;
+        self.persistence = persistence if persistence != None else 64;
+        self.slottime    = slottime if slottime != None else 20;
 
-		if parity.lower() == "e" or parity.lower() == "even":
-			self.parity = serial.PARITY_EVEN
+        if parity.lower() == "e" or parity.lower() == "even":
+            self.parity = serial.PARITY_EVEN
 
-		if parity.lower() == "o" or parity.lower() == "odd":
-			self.parity = serial.PARITY_ODD
+        if parity.lower() == "o" or parity.lower() == "odd":
+            self.parity = serial.PARITY_ODD
 
-		try:
-			RNS.log("Opening serial port "+self.port+"...")
-			self.serial = serial.Serial(
-				port = self.port,
-				baudrate = self.speed,
-				bytesize = self.databits,
-				parity = self.parity,
-				stopbits = self.stopbits,
-				xonxoff = False,
-				rtscts = False,
-				timeout = 0,
-				inter_byte_timeout = None,
-				write_timeout = None,
-				dsrdtr = False,
-			)
-		except Exception as e:
-			RNS.log("Could not open serial port for interface "+str(self), RNS.LOG_ERROR)
-			raise e
+        try:
+            RNS.log("Opening serial port "+self.port+"...")
+            self.serial = serial.Serial(
+                port = self.port,
+                baudrate = self.speed,
+                bytesize = self.databits,
+                parity = self.parity,
+                stopbits = self.stopbits,
+                xonxoff = False,
+                rtscts = False,
+                timeout = 0,
+                inter_byte_timeout = None,
+                write_timeout = None,
+                dsrdtr = False,
+            )
+        except Exception as e:
+            RNS.log("Could not open serial port for interface "+str(self), RNS.LOG_ERROR)
+            raise e
 
-		if self.serial.is_open:
-			# Allow time for interface to initialise before config
-			sleep(2.0)
-			thread = threading.Thread(target=self.readLoop)
-			thread.setDaemon(True)
-			thread.start()
-			self.online = True
-			RNS.log("Serial port "+self.port+" is now open")
-			RNS.log("Configuring AX.25 KISS interface parameters...")
-			self.setPreamble(self.preamble)
-			self.setTxTail(self.txtail)
-			self.setPersistence(self.persistence)
-			self.setSlotTime(self.slottime)
-			self.setFlowControl(self.flow_control)
-			self.interface_ready = True
-			RNS.log("AX.25 KISS interface configured")
-			sleep(2)
-		else:
-			raise IOError("Could not open serial port")
+        if self.serial.is_open:
+            # Allow time for interface to initialise before config
+            sleep(2.0)
+            thread = threading.Thread(target=self.readLoop)
+            thread.setDaemon(True)
+            thread.start()
+            self.online = True
+            RNS.log("Serial port "+self.port+" is now open")
+            RNS.log("Configuring AX.25 KISS interface parameters...")
+            self.setPreamble(self.preamble)
+            self.setTxTail(self.txtail)
+            self.setPersistence(self.persistence)
+            self.setSlotTime(self.slottime)
+            self.setFlowControl(self.flow_control)
+            self.interface_ready = True
+            RNS.log("AX.25 KISS interface configured")
+            sleep(2)
+        else:
+            raise IOError("Could not open serial port")
 
 
-	def setPreamble(self, preamble):
-		preamble_ms = preamble
-		preamble = int(preamble_ms / 10)
-		if preamble < 0:
-			preamble = 0
-		if preamble > 255:
-			preamble = 255
+    def setPreamble(self, preamble):
+        preamble_ms = preamble
+        preamble = int(preamble_ms / 10)
+        if preamble < 0:
+            preamble = 0
+        if preamble > 255:
+            preamble = 255
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXDELAY])+bytes([preamble])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("Could not configure AX.25 KISS interface preamble to "+str(preamble_ms)+" (command value "+str(preamble)+")")
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXDELAY])+bytes([preamble])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("Could not configure AX.25 KISS interface preamble to "+str(preamble_ms)+" (command value "+str(preamble)+")")
 
-	def setTxTail(self, txtail):
-		txtail_ms = txtail
-		txtail = int(txtail_ms / 10)
-		if txtail < 0:
-			txtail = 0
-		if txtail > 255:
-			txtail = 255
+    def setTxTail(self, txtail):
+        txtail_ms = txtail
+        txtail = int(txtail_ms / 10)
+        if txtail < 0:
+            txtail = 0
+        if txtail > 255:
+            txtail = 255
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXTAIL])+bytes([txtail])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("Could not configure AX.25 KISS interface TX tail to "+str(txtail_ms)+" (command value "+str(txtail)+")")
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXTAIL])+bytes([txtail])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("Could not configure AX.25 KISS interface TX tail to "+str(txtail_ms)+" (command value "+str(txtail)+")")
 
-	def setPersistence(self, persistence):
-		if persistence < 0:
-			persistence = 0
-		if persistence > 255:
-			persistence = 255
+    def setPersistence(self, persistence):
+        if persistence < 0:
+            persistence = 0
+        if persistence > 255:
+            persistence = 255
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_P])+bytes([persistence])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("Could not configure AX.25 KISS interface persistence to "+str(persistence))
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_P])+bytes([persistence])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("Could not configure AX.25 KISS interface persistence to "+str(persistence))
 
-	def setSlotTime(self, slottime):
-		slottime_ms = slottime
-		slottime = int(slottime_ms / 10)
-		if slottime < 0:
-			slottime = 0
-		if slottime > 255:
-			slottime = 255
+    def setSlotTime(self, slottime):
+        slottime_ms = slottime
+        slottime = int(slottime_ms / 10)
+        if slottime < 0:
+            slottime = 0
+        if slottime > 255:
+            slottime = 255
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_SLOTTIME])+bytes([slottime])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("Could not configure AX.25 KISS interface slot time to "+str(slottime_ms)+" (command value "+str(slottime)+")")
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_SLOTTIME])+bytes([slottime])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("Could not configure AX.25 KISS interface slot time to "+str(slottime_ms)+" (command value "+str(slottime)+")")
 
-	def setFlowControl(self, flow_control):
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_READY])+bytes([0x01])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			if (flow_control):
-				raise IOError("Could not enable AX.25 KISS interface flow control")
-			else:
-				raise IOError("Could not enable AX.25 KISS interface flow control")
+    def setFlowControl(self, flow_control):
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_READY])+bytes([0x01])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            if (flow_control):
+                raise IOError("Could not enable AX.25 KISS interface flow control")
+            else:
+                raise IOError("Could not enable AX.25 KISS interface flow control")
 
 
-	def processIncoming(self, data):
-		if (len(data) > AX25.HEADER_SIZE):
-			self.owner.inbound(data[AX25.HEADER_SIZE:], self)
+    def processIncoming(self, data):
+        if (len(data) > AX25.HEADER_SIZE):
+            self.owner.inbound(data[AX25.HEADER_SIZE:], self)
 
 
-	def processOutgoing(self,data):
-		if self.online:
-			if self.interface_ready:
-				if self.flow_control:
-					self.interface_ready = False
+    def processOutgoing(self,data):
+        if self.online:
+            if self.interface_ready:
+                if self.flow_control:
+                    self.interface_ready = False
 
-				encoded_dst_ssid = bytes([0x60 | (self.dst_ssid << 1)])
-				encoded_src_ssid = bytes([0x60 | (self.src_ssid << 1) | 0x01])
+                encoded_dst_ssid = bytes([0x60 | (self.dst_ssid << 1)])
+                encoded_src_ssid = bytes([0x60 | (self.src_ssid << 1) | 0x01])
 
-				addr = b""
+                addr = b""
 
-				for i in range(0,6):
-					if (i < len(self.dst_call)):
-						addr += bytes([self.dst_call[i]<<1])
-					else:
-						addr += bytes([0x20])
-				addr += encoded_dst_ssid
+                for i in range(0,6):
+                    if (i < len(self.dst_call)):
+                        addr += bytes([self.dst_call[i]<<1])
+                    else:
+                        addr += bytes([0x20])
+                addr += encoded_dst_ssid
 
-				for i in range(0,6):
-					if (i < len(self.src_call)):
-						addr += bytes([self.src_call[i]<<1])
-					else:
-						addr += bytes([0x20])
-				addr += encoded_src_ssid
+                for i in range(0,6):
+                    if (i < len(self.src_call)):
+                        addr += bytes([self.src_call[i]<<1])
+                    else:
+                        addr += bytes([0x20])
+                addr += encoded_src_ssid
 
-				data = addr+bytes([AX25.CTRL_UI])+bytes([AX25.PID_NOLAYER3])+data
+                data = addr+bytes([AX25.CTRL_UI])+bytes([AX25.PID_NOLAYER3])+data
 
-				data = data.replace(bytes([0xdb]), bytes([0xdb])+bytes([0xdd]))
-				data = data.replace(bytes([0xc0]), bytes([0xdb])+bytes([0xdc]))
-				kiss_frame = bytes([KISS.FEND])+bytes([0x00])+data+bytes([KISS.FEND])
+                data = data.replace(bytes([0xdb]), bytes([0xdb])+bytes([0xdd]))
+                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)
+                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)
-				if written != len(kiss_frame):
-					if self.flow_control:
-						self.interface_ready = True
-					raise IOError("AX.25 interface only wrote "+str(written)+" bytes of "+str(len(kiss_frame)))
-			else:
-				self.queue(data)
+                written = self.serial.write(kiss_frame)
+                if written != len(kiss_frame):
+                    if self.flow_control:
+                        self.interface_ready = True
+                    raise IOError("AX.25 interface only wrote "+str(written)+" bytes of "+str(len(kiss_frame)))
+            else:
+                self.queue(data)
 
-	def queue(self, data):
-		self.packet_queue.append(data)
+    def queue(self, data):
+        self.packet_queue.append(data)
 
-	def process_queue(self):
-		if len(self.packet_queue) > 0:
-			data = self.packet_queue.pop(0)
-			self.interface_ready = True
-			self.processOutgoing(data)
-		elif len(self.packet_queue) == 0:
-			self.interface_ready = True
+    def process_queue(self):
+        if len(self.packet_queue) > 0:
+            data = self.packet_queue.pop(0)
+            self.interface_ready = True
+            self.processOutgoing(data)
+        elif len(self.packet_queue) == 0:
+            self.interface_ready = True
 
-	def readLoop(self):
-		try:
-			in_frame = False
-			escape = False
-			command = KISS.CMD_UNKNOWN
-			data_buffer = b""
-			last_read_ms = int(time.time()*1000)
+    def readLoop(self):
+        try:
+            in_frame = False
+            escape = False
+            command = KISS.CMD_UNKNOWN
+            data_buffer = b""
+            last_read_ms = int(time.time()*1000)
 
-			while self.serial.is_open:
-				if self.serial.in_waiting:
-					byte = ord(self.serial.read(1))
-					last_read_ms = int(time.time()*1000)
+            while self.serial.is_open:
+                if self.serial.in_waiting:
+                    byte = ord(self.serial.read(1))
+                    last_read_ms = int(time.time()*1000)
 
-					if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
-						in_frame = False
-						self.processIncoming(data_buffer)
-					elif (byte == KISS.FEND):
-						in_frame = True
-						command = KISS.CMD_UNKNOWN
-						data_buffer = b""
-					elif (in_frame and len(data_buffer) < RNS.Reticulum.MTU+AX25.HEADER_SIZE):
-						if (len(data_buffer) == 0 and command == KISS.CMD_UNKNOWN):
-							# We only support one HDLC port for now, so
-							# strip off the port nibble
-							byte = byte & 0x0F
-							command = byte
-						elif (command == KISS.CMD_DATA):
-							if (byte == KISS.FESC):
-								escape = True
-							else:
-								if (escape):
-									if (byte == KISS.TFEND):
-										byte = KISS.FEND
-									if (byte == KISS.TFESC):
-										byte = KISS.FESC
-									escape = False
-								data_buffer = data_buffer+bytes([byte])
-						elif (command == KISS.CMD_READY):
-							# TODO: add timeout and reset if ready
-							# command never arrives
-							self.process_queue()
-				else:
-					time_since_last = int(time.time()*1000) - last_read_ms
-					if len(data_buffer) > 0 and time_since_last > self.timeout:
-			 			data_buffer = b""
-			 			in_frame = False
-			 			command = KISS.CMD_UNKNOWN
-			 			escape = False
-					sleep(0.08)
+                    if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
+                        in_frame = False
+                        self.processIncoming(data_buffer)
+                    elif (byte == KISS.FEND):
+                        in_frame = True
+                        command = KISS.CMD_UNKNOWN
+                        data_buffer = b""
+                    elif (in_frame and len(data_buffer) < RNS.Reticulum.MTU+AX25.HEADER_SIZE):
+                        if (len(data_buffer) == 0 and command == KISS.CMD_UNKNOWN):
+                            # We only support one HDLC port for now, so
+                            # strip off the port nibble
+                            byte = byte & 0x0F
+                            command = byte
+                        elif (command == KISS.CMD_DATA):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                data_buffer = data_buffer+bytes([byte])
+                        elif (command == KISS.CMD_READY):
+                            # TODO: add timeout and reset if ready
+                            # command never arrives
+                            self.process_queue()
+                else:
+                    time_since_last = int(time.time()*1000) - last_read_ms
+                    if len(data_buffer) > 0 and time_since_last > self.timeout:
+                        data_buffer = b""
+                        in_frame = False
+                        command = KISS.CMD_UNKNOWN
+                        escape = False
+                    sleep(0.08)
 
-		except Exception as e:
-			self.online = False
-			RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
-			RNS.log("The interface "+str(self.name)+" is now offline. Restart Reticulum to attempt reconnection.", RNS.LOG_ERROR)
+        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)
 
-	def __str__(self):
-		return "AX25KISSInterface["+self.name+"]"
+    def __str__(self):
+        return "AX25KISSInterface["+self.name+"]"

RNS/Interfaces/Interface.py

@@ -11,5 +11,5 @@ class Interface:
         pass
 
     def get_hash(self):
-    	# TODO: Maybe expand this to something more unique
-    	return RNS.Identity.fullHash(str(self).encode("utf-8"))
+        # TODO: Maybe expand this to something more unique
+        return RNS.Identity.full_hash(str(self).encode("utf-8"))

RNS/Interfaces/KISSInterface.py

@@ -7,250 +7,277 @@ import time
 import RNS
 
 class KISS():
-	FEND			  = 0xC0
-	FESC			  = 0xDB
-	TFEND			  = 0xDC
-	TFESC			  = 0xDD
-	CMD_UNKNOWN		  = 0xFE
-	CMD_DATA		  = 0x00
-	CMD_TXDELAY		  = 0x01
-	CMD_P			  = 0x02
-	CMD_SLOTTIME	  = 0x03
-	CMD_TXTAIL		  = 0x04
-	CMD_FULLDUPLEX	  = 0x05
-	CMD_SETHARDWARE	  = 0x06
-	CMD_READY         = 0x0F
-	CMD_RETURN		  = 0xFF
+    FEND              = 0xC0
+    FESC              = 0xDB
+    TFEND             = 0xDC
+    TFESC             = 0xDD
+    CMD_UNKNOWN       = 0xFE
+    CMD_DATA          = 0x00
+    CMD_TXDELAY       = 0x01
+    CMD_P             = 0x02
+    CMD_SLOTTIME      = 0x03
+    CMD_TXTAIL        = 0x04
+    CMD_FULLDUPLEX    = 0x05
+    CMD_SETHARDWARE   = 0x06
+    CMD_READY         = 0x0F
+    CMD_RETURN        = 0xFF
 
-	@staticmethod
-	def escape(data):
-		data = data.replace(bytes([0xdb]), bytes([0xdb, 0xdd]))
-		data = data.replace(bytes([0xc0]), bytes([0xdb, 0xdc]))
-		return data
+    @staticmethod
+    def escape(data):
+        data = data.replace(bytes([0xdb]), bytes([0xdb, 0xdd]))
+        data = data.replace(bytes([0xc0]), bytes([0xdb, 0xdc]))
+        return data
 
 class KISSInterface(Interface):
-	MAX_CHUNK = 32768
+    MAX_CHUNK = 32768
 
-	owner    = None
-	port     = None
-	speed    = None
-	databits = None
-	parity   = None
-	stopbits = None
-	serial   = None
+    owner    = None
+    port     = None
+    speed    = None
+    databits = None
+    parity   = None
+    stopbits = None
+    serial   = None
 
-	def __init__(self, owner, name, port, speed, databits, parity, stopbits, preamble, txtail, persistence, slottime, flow_control):
-		self.serial   = None
-		self.owner    = owner
-		self.name     = name
-		self.port     = port
-		self.speed    = speed
-		self.databits = databits
-		self.parity   = serial.PARITY_NONE
-		self.stopbits = stopbits
-		self.timeout  = 100
-		self.online   = False
+    def __init__(self, owner, name, port, speed, databits, parity, stopbits, preamble, txtail, persistence, slottime, flow_control, beacon_interval, beacon_data):
+        if beacon_data == None:
+            beacon_data = ""
 
-		self.packet_queue    = []
-		self.flow_control    = flow_control
-		self.interface_ready = False
+        self.serial   = None
+        self.owner    = owner
+        self.name     = name
+        self.port     = port
+        self.speed    = speed
+        self.databits = databits
+        self.parity   = serial.PARITY_NONE
+        self.stopbits = stopbits
+        self.timeout  = 100
+        self.online   = False
+        self.beacon_i = beacon_interval
+        self.beacon_d = beacon_data.encode("utf-8")
+        self.first_tx = None
 
-		self.preamble    = preamble if preamble != None else 350;
-		self.txtail      = txtail if txtail != None else 20;
-		self.persistence = persistence if persistence != None else 64;
-		self.slottime    = slottime if slottime != None else 20;
+        self.packet_queue    = []
+        self.flow_control    = flow_control
+        self.interface_ready = False
+        self.flow_control_timeout = 10
+        self.flow_control_locked  = time.time()
 
-		if parity.lower() == "e" or parity.lower() == "even":
-			self.parity = serial.PARITY_EVEN
+        self.preamble    = preamble if preamble != None else 350;
+        self.txtail      = txtail if txtail != None else 20;
+        self.persistence = persistence if persistence != None else 64;
+        self.slottime    = slottime if slottime != None else 20;
 
-		if parity.lower() == "o" or parity.lower() == "odd":
-			self.parity = serial.PARITY_ODD
+        if parity.lower() == "e" or parity.lower() == "even":
+            self.parity = serial.PARITY_EVEN
 
-		try:
-			RNS.log("Opening serial port "+self.port+"...")
-			self.serial = serial.Serial(
-				port = self.port,
-				baudrate = self.speed,
-				bytesize = self.databits,
-				parity = self.parity,
-				stopbits = self.stopbits,
-				xonxoff = False,
-				rtscts = False,
-				timeout = 0,
-				inter_byte_timeout = None,
-				write_timeout = None,
-				dsrdtr = False,
-			)
-		except Exception as e:
-			RNS.log("Could not open serial port "+self.port, RNS.LOG_ERROR)
-			raise e
+        if parity.lower() == "o" or parity.lower() == "odd":
+            self.parity = serial.PARITY_ODD
 
-		if self.serial.is_open:
-			# Allow time for interface to initialise before config
-			sleep(2.0)
-			thread = threading.Thread(target=self.readLoop)
-			thread.setDaemon(True)
-			thread.start()
-			self.online = True
-			RNS.log("Serial port "+self.port+" is now open")
-			RNS.log("Configuring KISS interface parameters...")
-			self.setPreamble(self.preamble)
-			self.setTxTail(self.txtail)
-			self.setPersistence(self.persistence)
-			self.setSlotTime(self.slottime)
-			self.setFlowControl(self.flow_control)
-			self.interface_ready = True
-			RNS.log("KISS interface configured")
-		else:
-			raise IOError("Could not open serial port")
+        try:
+            RNS.log("Opening serial port "+self.port+"...")
+            self.serial = serial.Serial(
+                port = self.port,
+                baudrate = self.speed,
+                bytesize = self.databits,
+                parity = self.parity,
+                stopbits = self.stopbits,
+                xonxoff = False,
+                rtscts = False,
+                timeout = 0,
+                inter_byte_timeout = None,
+                write_timeout = None,
+                dsrdtr = False,
+            )
+        except Exception as e:
+            RNS.log("Could not open serial port "+self.port, RNS.LOG_ERROR)
+            raise e
+
+        if self.serial.is_open:
+            # Allow time for interface to initialise before config
+            sleep(2.0)
+            thread = threading.Thread(target=self.readLoop)
+            thread.setDaemon(True)
+            thread.start()
+            self.online = True
+            RNS.log("Serial port "+self.port+" is now open")
+            RNS.log("Configuring KISS interface parameters...")
+            self.setPreamble(self.preamble)
+            self.setTxTail(self.txtail)
+            self.setPersistence(self.persistence)
+            self.setSlotTime(self.slottime)
+            self.setFlowControl(self.flow_control)
+            self.interface_ready = True
+            RNS.log("KISS interface configured")
+        else:
+            raise IOError("Could not open serial port")
 
 
-	def setPreamble(self, preamble):
-		preamble_ms = preamble
-		preamble = int(preamble_ms / 10)
-		if preamble < 0:
-			preamble = 0
-		if preamble > 255:
-			preamble = 255
+    def setPreamble(self, preamble):
+        preamble_ms = preamble
+        preamble = int(preamble_ms / 10)
+        if preamble < 0:
+            preamble = 0
+        if preamble > 255:
+            preamble = 255
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXDELAY])+bytes([preamble])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("Could not configure KISS interface preamble to "+str(preamble_ms)+" (command value "+str(preamble)+")")
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXDELAY])+bytes([preamble])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("Could not configure KISS interface preamble to "+str(preamble_ms)+" (command value "+str(preamble)+")")
 
-	def setTxTail(self, txtail):
-		txtail_ms = txtail
-		txtail = int(txtail_ms / 10)
-		if txtail < 0:
-			txtail = 0
-		if txtail > 255:
-			txtail = 255
+    def setTxTail(self, txtail):
+        txtail_ms = txtail
+        txtail = int(txtail_ms / 10)
+        if txtail < 0:
+            txtail = 0
+        if txtail > 255:
+            txtail = 255
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXTAIL])+bytes([txtail])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("Could not configure KISS interface TX tail to "+str(txtail_ms)+" (command value "+str(txtail)+")")
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXTAIL])+bytes([txtail])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("Could not configure KISS interface TX tail to "+str(txtail_ms)+" (command value "+str(txtail)+")")
 
-	def setPersistence(self, persistence):
-		if persistence < 0:
-			persistence = 0
-		if persistence > 255:
-			persistence = 255
+    def setPersistence(self, persistence):
+        if persistence < 0:
+            persistence = 0
+        if persistence > 255:
+            persistence = 255
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_P])+bytes([persistence])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("Could not configure KISS interface persistence to "+str(persistence))
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_P])+bytes([persistence])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("Could not configure KISS interface persistence to "+str(persistence))
 
-	def setSlotTime(self, slottime):
-		slottime_ms = slottime
-		slottime = int(slottime_ms / 10)
-		if slottime < 0:
-			slottime = 0
-		if slottime > 255:
-			slottime = 255
+    def setSlotTime(self, slottime):
+        slottime_ms = slottime
+        slottime = int(slottime_ms / 10)
+        if slottime < 0:
+            slottime = 0
+        if slottime > 255:
+            slottime = 255
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_SLOTTIME])+bytes([slottime])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("Could not configure KISS interface slot time to "+str(slottime_ms)+" (command value "+str(slottime)+")")
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_SLOTTIME])+bytes([slottime])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("Could not configure KISS interface slot time to "+str(slottime_ms)+" (command value "+str(slottime)+")")
 
-	def setFlowControl(self, flow_control):
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_READY])+bytes([0x01])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			if (flow_control):
-				raise IOError("Could not enable KISS interface flow control")
-			else:
-				raise IOError("Could not enable KISS interface flow control")
+    def setFlowControl(self, flow_control):
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_READY])+bytes([0x01])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            if (flow_control):
+                raise IOError("Could not enable KISS interface flow control")
+            else:
+                raise IOError("Could not enable KISS interface flow control")
 
 
-	def processIncoming(self, data):
-		self.owner.inbound(data, self)
+    def processIncoming(self, data):
+        self.owner.inbound(data, self)
 
 
-	def processOutgoing(self,data):
-		if self.online:
-			if self.interface_ready:
-				if self.flow_control:
-					self.interface_ready = False
+    def processOutgoing(self,data):
+        if self.online:
+            if self.interface_ready:
+                if self.flow_control:
+                    self.interface_ready = False
+                    self.flow_control_locked = time.time()
 
-				data = data.replace(bytes([0xdb]), bytes([0xdb])+bytes([0xdd]))
-				data = data.replace(bytes([0xc0]), bytes([0xdb])+bytes([0xdc]))
-				frame = bytes([KISS.FEND])+bytes([0x00])+data+bytes([KISS.FEND])
+                data = data.replace(bytes([0xdb]), bytes([0xdb])+bytes([0xdd]))
+                data = data.replace(bytes([0xc0]), bytes([0xdb])+bytes([0xdc]))
+                frame = bytes([KISS.FEND])+bytes([0x00])+data+bytes([KISS.FEND])
 
-				written = self.serial.write(frame)
-				if written != len(frame):
-					raise IOError("Serial interface only wrote "+str(written)+" bytes of "+str(len(data)))
+                written = self.serial.write(frame)
 
-			else:
-				self.queue(data)
+                if data == self.beacon_d:
+                    self.first_tx = None
+                else:
+                    if self.first_tx == None:
+                        self.first_tx = time.time()
 
-	def queue(self, data):
-		self.packet_queue.append(data)
+                if written != len(frame):
+                    raise IOError("Serial interface only wrote "+str(written)+" bytes of "+str(len(data)))
 
-	def process_queue(self):
-		if len(self.packet_queue) > 0:
-			data = self.packet_queue.pop(0)
-			self.interface_ready = True
-			self.processOutgoing(data)
-		elif len(self.packet_queue) == 0:
-			self.interface_ready = True
+            else:
+                self.queue(data)
 
-	def readLoop(self):
-		try:
-			in_frame = False
-			escape = False
-			command = KISS.CMD_UNKNOWN
-			data_buffer = b""
-			last_read_ms = int(time.time()*1000)
+    def queue(self, data):
+        self.packet_queue.append(data)
 
-			while self.serial.is_open:
-				if self.serial.in_waiting:
-					byte = ord(self.serial.read(1))
-					last_read_ms = int(time.time()*1000)
+    def process_queue(self):
+        if len(self.packet_queue) > 0:
+            data = self.packet_queue.pop(0)
+            self.interface_ready = True
+            self.processOutgoing(data)
+        elif len(self.packet_queue) == 0:
+            self.interface_ready = True
 
-					if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
-						in_frame = False
-						self.processIncoming(data_buffer)
-					elif (byte == KISS.FEND):
-						in_frame = True
-						command = KISS.CMD_UNKNOWN
-						data_buffer = b""
-					elif (in_frame and len(data_buffer) < RNS.Reticulum.MTU):
-						if (len(data_buffer) == 0 and command == KISS.CMD_UNKNOWN):
-							# We only support one HDLC port for now, so
-							# strip off the port nibble
-							byte = byte & 0x0F
-							command = byte
-						elif (command == KISS.CMD_DATA):
-							if (byte == KISS.FESC):
-								escape = True
-							else:
-								if (escape):
-									if (byte == KISS.TFEND):
-										byte = KISS.FEND
-									if (byte == KISS.TFESC):
-										byte = KISS.FESC
-									escape = False
-								data_buffer = data_buffer+bytes([byte])
-						elif (command == KISS.CMD_READY):
-							# TODO: add timeout and reset if ready
-							# command never arrives
-							self.process_queue()
-				else:
-					time_since_last = int(time.time()*1000) - last_read_ms
-					if len(data_buffer) > 0 and time_since_last > self.timeout:
-						data_buffer = b""
-						in_frame = False
-						command = KISS.CMD_UNKNOWN
-						escape = False
-					sleep(0.08)
+    def readLoop(self):
+        try:
+            in_frame = False
+            escape = False
+            command = KISS.CMD_UNKNOWN
+            data_buffer = b""
+            last_read_ms = int(time.time()*1000)
 
-		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)
+            while self.serial.is_open:
+                if self.serial.in_waiting:
+                    byte = ord(self.serial.read(1))
+                    last_read_ms = int(time.time()*1000)
 
-	def __str__(self):
-		return "KISSInterface["+self.name+"]"
+                    if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
+                        in_frame = False
+                        self.processIncoming(data_buffer)
+                    elif (byte == KISS.FEND):
+                        in_frame = True
+                        command = KISS.CMD_UNKNOWN
+                        data_buffer = b""
+                    elif (in_frame and len(data_buffer) < RNS.Reticulum.MTU):
+                        if (len(data_buffer) == 0 and command == KISS.CMD_UNKNOWN):
+                            # We only support one HDLC port for now, so
+                            # strip off the port nibble
+                            byte = byte & 0x0F
+                            command = byte
+                        elif (command == KISS.CMD_DATA):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                data_buffer = data_buffer+bytes([byte])
+                        elif (command == KISS.CMD_READY):
+                            self.process_queue()
+                else:
+                    time_since_last = int(time.time()*1000) - last_read_ms
+                    if len(data_buffer) > 0 and time_since_last > self.timeout:
+                        data_buffer = b""
+                        in_frame = False
+                        command = KISS.CMD_UNKNOWN
+                        escape = False
+                    sleep(0.08)
+
+                    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)
+                                self.process_queue()
+
+                    if self.beacon_i != None and self.beacon_d != None:
+                        if self.first_tx != None:
+                            if time.time() > self.first_tx + self.beacon_i:
+                                RNS.log("Interface "+str(self)+" is transmitting beacon data: "+str(self.beacon_d.decode("utf-8")), RNS.LOG_DEBUG)
+                                self.first_tx = None
+                                self.processOutgoing(self.beacon_d)
+
+        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)
+
+    def __str__(self):
+        return "KISSInterface["+self.name+"]"

RNS/Interfaces/RNodeInterface.py

@@ -9,433 +9,462 @@ import math
 import RNS
 
 class KISS():
-	FEND			= 0xC0
-	FESC			= 0xDB
-	TFEND			= 0xDC
-	TFESC			= 0xDD
-	
-	CMD_UNKNOWN		= 0xFE
-	CMD_DATA		= 0x00
-	CMD_FREQUENCY	= 0x01
-	CMD_BANDWIDTH	= 0x02
-	CMD_TXPOWER		= 0x03
-	CMD_SF			= 0x04
-	CMD_CR          = 0x05
-	CMD_RADIO_STATE = 0x06
-	CMD_RADIO_LOCK	= 0x07
-	CMD_DETECT		= 0x08
-	CMD_READY       = 0x0F
-	CMD_STAT_RX		= 0x21
-	CMD_STAT_TX		= 0x22
-	CMD_STAT_RSSI	= 0x23
-	CMD_STAT_SNR	= 0x24
-	CMD_BLINK		= 0x30
-	CMD_RANDOM		= 0x40
-	CMD_FW_VERSION  = 0x50
-	CMD_ROM_READ    = 0x51
+    FEND            = 0xC0
+    FESC            = 0xDB
+    TFEND           = 0xDC
+    TFESC           = 0xDD
+    
+    CMD_UNKNOWN     = 0xFE
+    CMD_DATA        = 0x00
+    CMD_FREQUENCY   = 0x01
+    CMD_BANDWIDTH   = 0x02
+    CMD_TXPOWER     = 0x03
+    CMD_SF          = 0x04
+    CMD_CR          = 0x05
+    CMD_RADIO_STATE = 0x06
+    CMD_RADIO_LOCK  = 0x07
+    CMD_DETECT      = 0x08
+    CMD_READY       = 0x0F
+    CMD_STAT_RX     = 0x21
+    CMD_STAT_TX     = 0x22
+    CMD_STAT_RSSI   = 0x23
+    CMD_STAT_SNR    = 0x24
+    CMD_BLINK       = 0x30
+    CMD_RANDOM      = 0x40
+    CMD_FW_VERSION  = 0x50
+    CMD_ROM_READ    = 0x51
 
-	DETECT_REQ      = 0x73
-	DETECT_RESP     = 0x46
-	
-	RADIO_STATE_OFF = 0x00
-	RADIO_STATE_ON	= 0x01
-	RADIO_STATE_ASK = 0xFF
-	
-	CMD_ERROR		    = 0x90
-	ERROR_INITRADIO     = 0x01
-	ERROR_TXFAILED	    = 0x02
-	ERROR_EEPROM_LOCKED	= 0x03
+    DETECT_REQ      = 0x73
+    DETECT_RESP     = 0x46
+    
+    RADIO_STATE_OFF = 0x00
+    RADIO_STATE_ON  = 0x01
+    RADIO_STATE_ASK = 0xFF
+    
+    CMD_ERROR           = 0x90
+    ERROR_INITRADIO     = 0x01
+    ERROR_TXFAILED      = 0x02
+    ERROR_EEPROM_LOCKED = 0x03
 
-	@staticmethod
-	def escape(data):
-		data = data.replace(bytes([0xdb]), bytes([0xdb, 0xdd]))
-		data = data.replace(bytes([0xc0]), bytes([0xdb, 0xdc]))
-		return data
-	
+    @staticmethod
+    def escape(data):
+        data = data.replace(bytes([0xdb]), bytes([0xdb, 0xdd]))
+        data = data.replace(bytes([0xc0]), bytes([0xdb, 0xdc]))
+        return data
+    
 
 class RNodeInterface(Interface):
-	MAX_CHUNK = 32768
+    MAX_CHUNK = 32768
 
-	owner    = None
-	port     = None
-	speed    = None
-	databits = None
-	parity   = None
-	stopbits = None
-	serial   = None
+    owner    = None
+    port     = None
+    speed    = None
+    databits = None
+    parity   = None
+    stopbits = None
+    serial   = None
 
-	FREQ_MIN = 137000000
-	FREQ_MAX = 1020000000
+    FREQ_MIN = 137000000
+    FREQ_MAX = 1020000000
 
-	RSSI_OFFSET = 157
-	SNR_OFFSET  = 128
+    RSSI_OFFSET = 157
 
-	def __init__(self, owner, name, port, frequency = None, bandwidth = None, txpower = None, sf = None, cr = None, flow_control = False):
-		self.serial      = None
-		self.owner       = owner
-		self.name        = name
-		self.port        = port
-		self.speed       = 115200
-		self.databits    = 8
-		self.parity      = serial.PARITY_NONE
-		self.stopbits    = 1
-		self.timeout     = 100
-		self.online      = False
+    CALLSIGN_MAX_LEN    = 32
 
-		self.frequency   = frequency
-		self.bandwidth   = bandwidth
-		self.txpower     = txpower
-		self.sf          = sf
-		self.cr          = cr
-		self.state       = KISS.RADIO_STATE_OFF
-		self.bitrate     = 0
+    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.serial      = None
+        self.owner       = owner
+        self.name        = name
+        self.port        = port
+        self.speed       = 115200
+        self.databits    = 8
+        self.parity      = serial.PARITY_NONE
+        self.stopbits    = 1
+        self.timeout     = 100
+        self.online      = False
 
-		self.r_frequency = None
-		self.r_bandwidth = None
-		self.r_txpower   = None
-		self.r_sf        = None
-		self.r_cr        = None
-		self.r_state     = None
-		self.r_lock      = None
-		self.r_stat_rx   = None
-		self.r_stat_tx   = None
-		self.r_stat_rssi = None
-		self.r_random	 = None
+        self.frequency   = frequency
+        self.bandwidth   = bandwidth
+        self.txpower     = txpower
+        self.sf          = sf
+        self.cr          = cr
+        self.state       = KISS.RADIO_STATE_OFF
+        self.bitrate     = 0
 
-		self.packet_queue    = []
-		self.flow_control    = flow_control
-		self.interface_ready = False
+        self.last_id     = 0
+        self.first_tx    = None
 
-		self.validcfg  = True
-		if (self.frequency < RNodeInterface.FREQ_MIN or self.frequency > RNodeInterface.FREQ_MAX):
-			RNS.log("Invalid frequency configured for "+str(self), RNS.LOG_ERROR)
-			self.validcfg = False
+        self.r_frequency = None
+        self.r_bandwidth = None
+        self.r_txpower   = None
+        self.r_sf        = None
+        self.r_cr        = None
+        self.r_state     = None
+        self.r_lock      = None
+        self.r_stat_rx   = None
+        self.r_stat_tx   = None
+        self.r_stat_rssi = None
+        self.r_random    = None
 
-		if (self.txpower < 0 or self.txpower > 17):
-			RNS.log("Invalid TX power configured for "+str(self), RNS.LOG_ERROR)
-			self.validcfg = False
+        self.packet_queue    = []
+        self.flow_control    = flow_control
+        self.interface_ready = False
 
-		if (self.bandwidth < 7800 or self.bandwidth > 500000):
-			RNS.log("Invalid bandwidth configured for "+str(self), RNS.LOG_ERROR)
-			self.validcfg = False
+        self.validcfg  = True
+        if (self.frequency < RNodeInterface.FREQ_MIN or self.frequency > RNodeInterface.FREQ_MAX):
+            RNS.log("Invalid frequency configured for "+str(self), RNS.LOG_ERROR)
+            self.validcfg = False
 
-		if (self.sf < 7 or self.sf > 12):
-			RNS.log("Invalid spreading factor configured for "+str(self), RNS.LOG_ERROR)
-			self.validcfg = False
+        if (self.txpower < 0 or self.txpower > 17):
+            RNS.log("Invalid TX power configured for "+str(self), RNS.LOG_ERROR)
+            self.validcfg = False
 
-		if (self.cr < 5 or self.sf > 8):
-			RNS.log("Invalid coding rate configured for "+str(self), RNS.LOG_ERROR)
-			self.validcfg = False
+        if (self.bandwidth < 7800 or self.bandwidth > 500000):
+            RNS.log("Invalid bandwidth configured for "+str(self), RNS.LOG_ERROR)
+            self.validcfg = False
 
-		if (not self.validcfg):
-			raise ValueError("The configuration for "+str(self)+" contains errors, interface is offline")
+        if (self.sf < 7 or self.sf > 12):
+            RNS.log("Invalid spreading factor configured for "+str(self), RNS.LOG_ERROR)
+            self.validcfg = False
 
-		try:
-			RNS.log("Opening serial port "+self.port+"...")
-			self.serial = serial.Serial(
-				port = self.port,
-				baudrate = self.speed,
-				bytesize = self.databits,
-				parity = self.parity,
-				stopbits = self.stopbits,
-				xonxoff = False,
-				rtscts = False,
-				timeout = 0,
-				inter_byte_timeout = None,
-				write_timeout = None,
-				dsrdtr = False,
-			)
-		except Exception as e:
-			RNS.log("Could not open serial port for interface "+str(self), RNS.LOG_ERROR)
-			raise e
+        if (self.cr < 5 or self.cr > 8):
+            RNS.log("Invalid coding rate configured for "+str(self), RNS.LOG_ERROR)
+            self.validcfg = False
 
-		if self.serial.is_open:
-			sleep(2.0)
-			thread = threading.Thread(target=self.readLoop)
-			thread.setDaemon(True)
-			thread.start()
-			self.online = True
-			RNS.log("Serial port "+self.port+" is now open")
-			RNS.log("Configuring RNode interface...", RNS.LOG_VERBOSE)
-			self.initRadio()
-			if (self.validateRadioState()):
-				self.interface_ready = True
-				RNS.log(str(self)+" is configured and powered up")
-				sleep(1.0)
-			else:
-				RNS.log("After configuring "+str(self)+", the reported radio parameters did not match your configuration.", RNS.LOG_ERROR)
-				RNS.log("Make sure that your hardware actually supports the parameters specified in the configuration", RNS.LOG_ERROR)
-				RNS.log("Aborting RNode startup", RNS.LOG_ERROR)
-				self.serial.close()
-				raise IOError("RNode interface did not pass validation")
-		else:
-			raise IOError("Could not open serial port")
+        if id_interval != None and id_callsign != None:
+            if (len(id_callsign.encode("utf-8")) <= RNodeInterface.CALLSIGN_MAX_LEN):
+                self.should_id = True
+                self.id_callsign = id_callsign.encode("utf-8")
+                self.id_interval = id_interval
+            else:
+                RNS.log("The encoded ID callsign for "+str(self)+" exceeds the max length of "+str(RNodeInterface.CALLSIGN_MAX_LEN)+" bytes.", RNS.LOG_ERROR)
+                self.validcfg = False
+        else:
+            self.id_interval = None
+            self.id_callsign = None
+
+        if (not self.validcfg):
+            raise ValueError("The configuration for "+str(self)+" contains errors, interface is offline")
+
+        try:
+            RNS.log("Opening serial port "+self.port+"...")
+            self.serial = serial.Serial(
+                port = self.port,
+                baudrate = self.speed,
+                bytesize = self.databits,
+                parity = self.parity,
+                stopbits = self.stopbits,
+                xonxoff = False,
+                rtscts = False,
+                timeout = 0,
+                inter_byte_timeout = None,
+                write_timeout = None,
+                dsrdtr = False,
+            )
+        except Exception as e:
+            RNS.log("Could not open serial port for interface "+str(self), RNS.LOG_ERROR)
+            raise e
+
+        if self.serial.is_open:
+            sleep(2.0)
+            thread = threading.Thread(target=self.readLoop)
+            thread.setDaemon(True)
+            thread.start()
+            self.online = True
+            RNS.log("Serial port "+self.port+" is now open")
+            RNS.log("Configuring RNode interface...", RNS.LOG_VERBOSE)
+            self.initRadio()
+            if (self.validateRadioState()):
+                self.interface_ready = True
+                RNS.log(str(self)+" is configured and powered up")
+                sleep(1.0)
+            else:
+                RNS.log("After configuring "+str(self)+", the reported radio parameters did not match your configuration.", RNS.LOG_ERROR)
+                RNS.log("Make sure that your hardware actually supports the parameters specified in the configuration", RNS.LOG_ERROR)
+                RNS.log("Aborting RNode startup", RNS.LOG_ERROR)
+                self.serial.close()
+                raise IOError("RNode interface did not pass validation")
+        else:
+            raise IOError("Could not open serial port")
 
 
-	def initRadio(self):
-		self.setFrequency()
-		self.setBandwidth()
-		self.setTXPower()
-		self.setSpreadingFactor()
-		self.setRadioState(KISS.RADIO_STATE_ON)
+    def initRadio(self):
+        self.setFrequency()
+        self.setBandwidth()
+        self.setTXPower()
+        self.setSpreadingFactor()
+        self.setCodingRate()
+        self.setRadioState(KISS.RADIO_STATE_ON)
 
-	def setFrequency(self):
-		c1 = self.frequency >> 24
-		c2 = self.frequency >> 16 & 0xFF
-		c3 = self.frequency >> 8 & 0xFF
-		c4 = self.frequency & 0xFF
-		data = KISS.escape(bytes([c1])+bytes([c2])+bytes([c3])+bytes([c4]))
+    def setFrequency(self):
+        c1 = self.frequency >> 24
+        c2 = self.frequency >> 16 & 0xFF
+        c3 = self.frequency >> 8 & 0xFF
+        c4 = self.frequency & 0xFF
+        data = KISS.escape(bytes([c1])+bytes([c2])+bytes([c3])+bytes([c4]))
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_FREQUENCY])+data+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("An IO error occurred while configuring frequency for "+self(str))
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_FREQUENCY])+data+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while configuring frequency for "+self(str))
 
-	def setBandwidth(self):
-		c1 = self.bandwidth >> 24
-		c2 = self.bandwidth >> 16 & 0xFF
-		c3 = self.bandwidth >> 8 & 0xFF
-		c4 = self.bandwidth & 0xFF
-		data = KISS.escape(bytes([c1])+bytes([c2])+bytes([c3])+bytes([c4]))
+    def setBandwidth(self):
+        c1 = self.bandwidth >> 24
+        c2 = self.bandwidth >> 16 & 0xFF
+        c3 = self.bandwidth >> 8 & 0xFF
+        c4 = self.bandwidth & 0xFF
+        data = KISS.escape(bytes([c1])+bytes([c2])+bytes([c3])+bytes([c4]))
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_BANDWIDTH])+data+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("An IO error occurred while configuring bandwidth for "+self(str))
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_BANDWIDTH])+data+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while configuring bandwidth for "+self(str))
 
-	def setTXPower(self):
-		txp = bytes([self.txpower])
+    def setTXPower(self):
+        txp = bytes([self.txpower])
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXPOWER])+txp+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while configuring TX power for "+self(str))
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_TXPOWER])+txp+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("An IO error occurred while configuring TX power for "+self(str))
+    def setSpreadingFactor(self):
+        sf = bytes([self.sf])
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_SF])+sf+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while configuring spreading factor for "+self(str))
 
-	def setSpreadingFactor(self):
-		sf = bytes([self.sf])
+    def setCodingRate(self):
+        cr = bytes([self.cr])
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_CR])+cr+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while configuring coding rate for "+self(str))
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_SF])+sf+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("An IO error occurred while configuring spreading factor for "+self(str))
+    def setRadioState(self, state):
+        kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_RADIO_STATE])+bytes([state])+bytes([KISS.FEND])
+        written = self.serial.write(kiss_command)
+        if written != len(kiss_command):
+            raise IOError("An IO error occurred while configuring radio state for "+self(str))
 
-	def setCodingRate(self):
-		cr = bytes([self.cr])
+    def validateRadioState(self):
+        RNS.log("Validating radio configuration for "+str(self)+"...", RNS.LOG_VERBOSE)
+        sleep(0.25);
+        if (self.frequency != self.r_frequency):
+            RNS.log("Frequency mismatch", RNS.LOG_ERROR)
+            self.validcfg = False
+        if (self.bandwidth != self.r_bandwidth):
+            RNS.log("Bandwidth mismatch", RNS.LOG_ERROR)
+            self.validcfg = False
+        if (self.txpower != self.r_txpower):
+            RNS.log("TX power mismatch", RNS.LOG_ERROR)
+            self.validcfg = False
+        if (self.sf != self.r_sf):
+            RNS.log("Spreading factor mismatch", RNS.LOG_ERROR)
+            self.validcfg = False
 
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_CR])+cr+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("An IO error occurred while configuring coding rate for "+self(str))
-
-	def setRadioState(self, state):
-		kiss_command = bytes([KISS.FEND])+bytes([KISS.CMD_RADIO_STATE])+bytes([state])+bytes([KISS.FEND])
-		written = self.serial.write(kiss_command)
-		if written != len(kiss_command):
-			raise IOError("An IO error occurred while configuring radio state for "+self(str))
-
-	def validateRadioState(self):
-		RNS.log("Validating radio configuration for "+str(self)+"...", RNS.LOG_VERBOSE)
-		sleep(0.25);
-		if (self.frequency != self.r_frequency):
-			RNS.log("Frequency mismatch", RNS.LOG_ERROR)
-			self.validcfg = False
-		if (self.bandwidth != self.r_bandwidth):
-			RNS.log("Bandwidth mismatch", RNS.LOG_ERROR)
-			self.validcfg = False
-		if (self.txpower != self.r_txpower):
-			RNS.log("TX power mismatch", RNS.LOG_ERROR)
-			self.validcfg = False
-		if (self.sf != self.r_sf):
-			RNS.log("Spreading factor mismatch", RNS.LOG_ERROR)
-			self.validcfg = False
-
-		if (self.validcfg):
-			return True
-		else:
-			return False
+        if (self.validcfg):
+            return True
+        else:
+            return False
 
 
-	def updateBitrate(self):
-		try:
-			self.bitrate = self.r_sf * ( (4.0/self.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_DEBUG)
-		except:
-			self.bitrate = 0
+    def updateBitrate(self):
+        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)
+        except:
+            self.bitrate = 0
 
-	def processIncoming(self, data):
-		self.owner.inbound(data, self)
+    def processIncoming(self, data):
+        self.owner.inbound(data, self)
 
 
-	def processOutgoing(self,data):
-		if self.online:
-			if self.interface_ready:
-				if self.flow_control:
-					self.interface_ready = False
+    def processOutgoing(self,data):
+        if self.online:
+            if self.interface_ready:
+                if self.flow_control:
+                    self.interface_ready = False
 
-				data = KISS.escape(data)
-				frame = bytes([0xc0])+bytes([0x00])+data+bytes([0xc0])
-				written = self.serial.write(frame)
-				if written != len(frame):
-					raise IOError("Serial interface only wrote "+str(written)+" bytes of "+str(len(data)))
-			else:
-				self.queue(data)
+                if data == self.id_callsign:
+                    self.first_tx = None
+                else:
+                    if self.first_tx == None:
+                        self.first_tx = time.time()
 
-	def queue(self, data):
-		self.packet_queue.append(data)
+                data    = KISS.escape(data)
+                frame   = bytes([0xc0])+bytes([0x00])+data+bytes([0xc0])
 
-	def process_queue(self):
-		if len(self.packet_queue) > 0:
-			data = self.packet_queue.pop(0)
-			self.interface_ready = True
-			self.processOutgoing(data)
-		elif len(self.packet_queue) == 0:
-			self.interface_ready = True
+                written = self.serial.write(frame)
 
-	def readLoop(self):
-		try:
-			in_frame = False
-			escape = False
-			command = KISS.CMD_UNKNOWN
-			data_buffer = b""
-			command_buffer = b""
-			last_read_ms = int(time.time()*1000)
+                if written != len(frame):
+                    raise IOError("Serial interface only wrote "+str(written)+" bytes of "+str(len(data)))
+            else:
+                self.queue(data)
 
-			while self.serial.is_open:
-				if self.serial.in_waiting:
-					byte = ord(self.serial.read(1))
-					last_read_ms = int(time.time()*1000)
+    def queue(self, data):
+        self.packet_queue.append(data)
 
-					if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
-						in_frame = False
-						self.processIncoming(data_buffer)
-						data_buffer = b""
-						command_buffer = b""
-					elif (byte == KISS.FEND):
-						in_frame = True
-						command = KISS.CMD_UNKNOWN
-						data_buffer = b""
-						command_buffer = b""
-					elif (in_frame and len(data_buffer) < RNS.Reticulum.MTU):
-						if (len(data_buffer) == 0 and command == KISS.CMD_UNKNOWN):
-							command = byte
-						elif (command == KISS.CMD_DATA):
-							if (byte == KISS.FESC):
-								escape = True
-							else:
-								if (escape):
-									if (byte == KISS.TFEND):
-										byte = KISS.FEND
-									if (byte == KISS.TFESC):
-										byte = KISS.FESC
-									escape = False
-								data_buffer = data_buffer+bytes([byte])
-						elif (command == KISS.CMD_FREQUENCY):
-							if (byte == KISS.FESC):
-								escape = True
-							else:
-								if (escape):
-									if (byte == KISS.TFEND):
-										byte = KISS.FEND
-									if (byte == KISS.TFESC):
-										byte = KISS.FESC
-									escape = False
-								command_buffer = command_buffer+bytes([byte])
-								if (len(command_buffer) == 4):
-									self.r_frequency = command_buffer[0] << 24 | command_buffer[1] << 16 | command_buffer[2] << 8 | command_buffer[3]
-									RNS.log(str(self)+" Radio reporting frequency is "+str(self.r_frequency/1000000.0)+" MHz", RNS.LOG_DEBUG)
-									self.updateBitrate()
+    def process_queue(self):
+        if len(self.packet_queue) > 0:
+            data = self.packet_queue.pop(0)
+            self.interface_ready = True
+            self.processOutgoing(data)
+        elif len(self.packet_queue) == 0:
+            self.interface_ready = True
 
-						elif (command == KISS.CMD_BANDWIDTH):
-							if (byte == KISS.FESC):
-								escape = True
-							else:
-								if (escape):
-									if (byte == KISS.TFEND):
-										byte = KISS.FEND
-									if (byte == KISS.TFESC):
-										byte = KISS.FESC
-									escape = False
-								command_buffer = command_buffer+bytes([byte])
-								if (len(command_buffer) == 4):
-									self.r_bandwidth = command_buffer[0] << 24 | command_buffer[1] << 16 | command_buffer[2] << 8 | command_buffer[3]
-									RNS.log(str(self)+" Radio reporting bandwidth is "+str(self.r_bandwidth/1000.0)+" KHz", RNS.LOG_DEBUG)
-									self.updateBitrate()
+    def readLoop(self):
+        try:
+            in_frame = False
+            escape = False
+            command = KISS.CMD_UNKNOWN
+            data_buffer = b""
+            command_buffer = b""
+            last_read_ms = int(time.time()*1000)
 
-						elif (command == KISS.CMD_TXPOWER):
-							self.r_txpower = byte
-							RNS.log(str(self)+" Radio reporting TX power is "+str(self.r_txpower)+" dBm", RNS.LOG_DEBUG)
-						elif (command == KISS.CMD_SF):
-							self.r_sf = byte
-							RNS.log(str(self)+" Radio reporting spreading factor is "+str(self.r_sf), RNS.LOG_DEBUG)
-							self.updateBitrate()
-						elif (command == KISS.CMD_CR):
-							self.r_cr = byte
-							RNS.log(str(self)+" Radio reporting coding rate is "+str(self.r_cr), RNS.LOG_DEBUG)
-							self.updateBitrate()
-						elif (command == KISS.CMD_RADIO_STATE):
-							self.r_state = byte
-						elif (command == KISS.CMD_RADIO_LOCK):
-							self.r_lock = byte
-						elif (command == KISS.CMD_STAT_RX):
-							if (byte == KISS.FESC):
-								escape = True
-							else:
-								if (escape):
-									if (byte == KISS.TFEND):
-										byte = KISS.FEND
-									if (byte == KISS.TFESC):
-										byte = KISS.FESC
-									escape = False
-								command_buffer = command_buffer+bytes([byte])
-								if (len(command_buffer) == 4):
-									self.r_stat_rx = ord(command_buffer[0]) << 24 | ord(command_buffer[1]) << 16 | ord(command_buffer[2]) << 8 | ord(command_buffer[3])
+            while self.serial.is_open:
+                if self.serial.in_waiting:
+                    byte = ord(self.serial.read(1))
+                    last_read_ms = int(time.time()*1000)
 
-						elif (command == KISS.CMD_STAT_TX):
-							if (byte == KISS.FESC):
-								escape = True
-							else:
-								if (escape):
-									if (byte == KISS.TFEND):
-										byte = KISS.FEND
-									if (byte == KISS.TFESC):
-										byte = KISS.FESC
-									escape = False
-								command_buffer = command_buffer+bytes([byte])
-								if (len(command_buffer) == 4):
-									self.r_stat_tx = ord(command_buffer[0]) << 24 | ord(command_buffer[1]) << 16 | ord(command_buffer[2]) << 8 | ord(command_buffer[3])
+                    if (in_frame and byte == KISS.FEND and command == KISS.CMD_DATA):
+                        in_frame = False
+                        self.processIncoming(data_buffer)
+                        data_buffer = b""
+                        command_buffer = b""
+                    elif (byte == KISS.FEND):
+                        in_frame = True
+                        command = KISS.CMD_UNKNOWN
+                        data_buffer = b""
+                        command_buffer = b""
+                    elif (in_frame and len(data_buffer) < RNS.Reticulum.MTU):
+                        if (len(data_buffer) == 0 and command == KISS.CMD_UNKNOWN):
+                            command = byte
+                        elif (command == KISS.CMD_DATA):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                data_buffer = data_buffer+bytes([byte])
+                        elif (command == KISS.CMD_FREQUENCY):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                command_buffer = command_buffer+bytes([byte])
+                                if (len(command_buffer) == 4):
+                                    self.r_frequency = command_buffer[0] << 24 | command_buffer[1] << 16 | command_buffer[2] << 8 | command_buffer[3]
+                                    RNS.log(str(self)+" Radio reporting frequency is "+str(self.r_frequency/1000000.0)+" MHz", RNS.LOG_DEBUG)
+                                    self.updateBitrate()
 
-						elif (command == KISS.CMD_STAT_RSSI):
-							self.r_stat_rssi = byte-RNodeInterface.RSSI_OFFSET
-						elif (command == KISS.CMD_STAT_SNR):
-							self.r_stat_snr = byte-RNodeInterface.SNR_OFFSET
-						elif (command == KISS.CMD_RANDOM):
-							self.r_random = byte
-						elif (command == KISS.CMD_ERROR):
-							if (byte == KISS.ERROR_INITRADIO):
-								RNS.log(str(self)+" hardware initialisation error (code "+RNS.hexrep(byte)+")", RNS.LOG_ERROR)
-							elif (byte == KISS.ERROR_INITRADIO):
-								RNS.log(str(self)+" hardware TX error (code "+RNS.hexrep(byte)+")", RNS.LOG_ERROR)
-							else:
-								RNS.log(str(self)+" hardware error (code "+RNS.hexrep(byte)+")", RNS.LOG_ERROR)
-						elif (command == KISS.CMD_READY):
-							self.process_queue()
-						
-				else:
-					time_since_last = int(time.time()*1000) - last_read_ms
-					if len(data_buffer) > 0 and time_since_last > self.timeout:
-						RNS.log(str(self)+" serial read timeout", RNS.LOG_DEBUG)
-						data_buffer = b""
-						in_frame = False
-						command = KISS.CMD_UNKNOWN
-						escape = False
-					sleep(0.08)
+                        elif (command == KISS.CMD_BANDWIDTH):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                command_buffer = command_buffer+bytes([byte])
+                                if (len(command_buffer) == 4):
+                                    self.r_bandwidth = command_buffer[0] << 24 | command_buffer[1] << 16 | command_buffer[2] << 8 | command_buffer[3]
+                                    RNS.log(str(self)+" Radio reporting bandwidth is "+str(self.r_bandwidth/1000.0)+" KHz", RNS.LOG_DEBUG)
+                                    self.updateBitrate()
 
-		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)
+                        elif (command == KISS.CMD_TXPOWER):
+                            self.r_txpower = byte
+                            RNS.log(str(self)+" Radio reporting TX power is "+str(self.r_txpower)+" dBm", RNS.LOG_DEBUG)
+                        elif (command == KISS.CMD_SF):
+                            self.r_sf = byte
+                            RNS.log(str(self)+" Radio reporting spreading factor is "+str(self.r_sf), RNS.LOG_DEBUG)
+                            self.updateBitrate()
+                        elif (command == KISS.CMD_CR):
+                            self.r_cr = byte
+                            RNS.log(str(self)+" Radio reporting coding rate is "+str(self.r_cr), RNS.LOG_DEBUG)
+                            self.updateBitrate()
+                        elif (command == KISS.CMD_RADIO_STATE):
+                            self.r_state = byte
+                        elif (command == KISS.CMD_RADIO_LOCK):
+                            self.r_lock = byte
+                        elif (command == KISS.CMD_STAT_RX):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                command_buffer = command_buffer+bytes([byte])
+                                if (len(command_buffer) == 4):
+                                    self.r_stat_rx = ord(command_buffer[0]) << 24 | ord(command_buffer[1]) << 16 | ord(command_buffer[2]) << 8 | ord(command_buffer[3])
 
-	def __str__(self):
-		return "RNodeInterface["+self.name+"]"
+                        elif (command == KISS.CMD_STAT_TX):
+                            if (byte == KISS.FESC):
+                                escape = True
+                            else:
+                                if (escape):
+                                    if (byte == KISS.TFEND):
+                                        byte = KISS.FEND
+                                    if (byte == KISS.TFESC):
+                                        byte = KISS.FESC
+                                    escape = False
+                                command_buffer = command_buffer+bytes([byte])
+                                if (len(command_buffer) == 4):
+                                    self.r_stat_tx = ord(command_buffer[0]) << 24 | ord(command_buffer[1]) << 16 | ord(command_buffer[2]) << 8 | ord(command_buffer[3])
+
+                        elif (command == KISS.CMD_STAT_RSSI):
+                            self.r_stat_rssi = byte-RNodeInterface.RSSI_OFFSET
+                        elif (command == KISS.CMD_STAT_SNR):
+                            self.r_stat_snr = int.from_bytes(bytes([byte]), byteorder="big", signed=True) * 0.25
+                        elif (command == KISS.CMD_RANDOM):
+                            self.r_random = byte
+                        elif (command == KISS.CMD_ERROR):
+                            if (byte == KISS.ERROR_INITRADIO):
+                                RNS.log(str(self)+" hardware initialisation error (code "+RNS.hexrep(byte)+")", RNS.LOG_ERROR)
+                            elif (byte == KISS.ERROR_INITRADIO):
+                                RNS.log(str(self)+" hardware TX error (code "+RNS.hexrep(byte)+")", RNS.LOG_ERROR)
+                            else:
+                                RNS.log(str(self)+" hardware error (code "+RNS.hexrep(byte)+")", RNS.LOG_ERROR)
+                        elif (command == KISS.CMD_READY):
+                            self.process_queue()
+                        
+                else:
+                    time_since_last = int(time.time()*1000) - last_read_ms
+                    if len(data_buffer) > 0 and time_since_last > self.timeout:
+                        RNS.log(str(self)+" serial read timeout", RNS.LOG_DEBUG)
+                        data_buffer = b""
+                        in_frame = False
+                        command = KISS.CMD_UNKNOWN
+                        escape = False
+
+                    if self.id_interval != None and self.id_callsign != None:
+                        if self.first_tx != None:
+                            if time.time() > self.first_tx + self.id_interval:
+                                RNS.log("Interface "+str(self)+" is transmitting beacon data: "+str(self.id_callsign.decode("utf-8")), RNS.LOG_DEBUG)
+                                self.processOutgoing(self.id_callsign)
+
+                    sleep(0.08)
+
+        except Exception as e:
+            self.online = False
+            RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
+            RNS.log("The interface "+str(self.name)+" is now offline. Restart Reticulum to attempt reconnection.", RNS.LOG_ERROR)
+
+    def __str__(self):
+        return "RNodeInterface["+self.name+"]"
 

RNS/Interfaces/SerialInterface.py

@@ -7,130 +7,130 @@ import time
 import RNS
 
 class HDLC():
-	# The Serial Interface packetizes data using
-	# simplified HDLC framing, similar to PPP
-	FLAG			  = 0x7E
-	ESC               = 0x7D
-	ESC_MASK          = 0x20
+    # The Serial Interface packetizes data using
+    # simplified HDLC framing, similar to PPP
+    FLAG              = 0x7E
+    ESC               = 0x7D
+    ESC_MASK          = 0x20
 
-	@staticmethod
-	def escape(data):
-		data = data.replace(bytes([HDLC.ESC]), bytes([HDLC.ESC, HDLC.ESC^HDLC.ESC_MASK]))
-		data = data.replace(bytes([HDLC.FLAG]), bytes([HDLC.ESC, HDLC.FLAG^HDLC.ESC_MASK]))
-		return data
+    @staticmethod
+    def escape(data):
+        data = data.replace(bytes([HDLC.ESC]), bytes([HDLC.ESC, HDLC.ESC^HDLC.ESC_MASK]))
+        data = data.replace(bytes([HDLC.FLAG]), bytes([HDLC.ESC, HDLC.FLAG^HDLC.ESC_MASK]))
+        return data
 
 class SerialInterface(Interface):
-	MAX_CHUNK = 32768
+    MAX_CHUNK = 32768
 
-	owner    = None
-	port     = None
-	speed    = None
-	databits = None
-	parity   = None
-	stopbits = None
-	serial   = None
+    owner    = None
+    port     = None
+    speed    = None
+    databits = None
+    parity   = None
+    stopbits = None
+    serial   = None
 
-	def __init__(self, owner, name, port, speed, databits, parity, stopbits):
-		self.serial   = None
-		self.owner    = owner
-		self.name     = name
-		self.port     = port
-		self.speed    = speed
-		self.databits = databits
-		self.parity   = serial.PARITY_NONE
-		self.stopbits = stopbits
-		self.timeout  = 100
-		self.online   = False
+    def __init__(self, owner, name, port, speed, databits, parity, stopbits):
+        self.serial   = None
+        self.owner    = owner
+        self.name     = name
+        self.port     = port
+        self.speed    = speed
+        self.databits = databits
+        self.parity   = serial.PARITY_NONE
+        self.stopbits = stopbits
+        self.timeout  = 100
+        self.online   = False
 
-		if parity.lower() == "e" or parity.lower() == "even":
-			self.parity = serial.PARITY_EVEN
+        if parity.lower() == "e" or parity.lower() == "even":
+            self.parity = serial.PARITY_EVEN
 
-		if parity.lower() == "o" or parity.lower() == "odd":
-			self.parity = serial.PARITY_ODD
+        if parity.lower() == "o" or parity.lower() == "odd":
+            self.parity = serial.PARITY_ODD
 
-		try:
-			RNS.log("Opening serial port "+self.port+"...")
-			self.serial = serial.Serial(
-				port = self.port,
-				baudrate = self.speed,
-				bytesize = self.databits,
-				parity = self.parity,
-				stopbits = self.stopbits,
-				xonxoff = False,
-				rtscts = False,
-				timeout = 0,
-				inter_byte_timeout = None,
-				write_timeout = None,
-				dsrdtr = False,
-			)
-		except Exception as e:
-			RNS.log("Could not open serial port for interface "+str(self), RNS.LOG_ERROR)
-			raise e
+        try:
+            RNS.log("Opening serial port "+self.port+"...")
+            self.serial = serial.Serial(
+                port = self.port,
+                baudrate = self.speed,
+                bytesize = self.databits,
+                parity = self.parity,
+                stopbits = self.stopbits,
+                xonxoff = False,
+                rtscts = False,
+                timeout = 0,
+                inter_byte_timeout = None,
+                write_timeout = None,
+                dsrdtr = False,
+            )
+        except Exception as e:
+            RNS.log("Could not open serial port for interface "+str(self), RNS.LOG_ERROR)
+            raise e
 
-		if self.serial.is_open:
-			sleep(0.5)
-			thread = threading.Thread(target=self.readLoop)
-			thread.setDaemon(True)
-			thread.start()
-			self.online = True
-			RNS.log("Serial port "+self.port+" is now open")
-		else:
-			raise IOError("Could not open serial port")
+        if self.serial.is_open:
+            sleep(0.5)
+            thread = threading.Thread(target=self.readLoop)
+            thread.setDaemon(True)
+            thread.start()
+            self.online = True
+            RNS.log("Serial port "+self.port+" is now open")
+        else:
+            raise IOError("Could not open serial port")
 
 
-	def processIncoming(self, data):
-		self.owner.inbound(data, self)
+    def processIncoming(self, data):
+        self.owner.inbound(data, self)
 
 
-	def processOutgoing(self,data):
-		if self.online:
-			data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
-			written = self.serial.write(data)
-			if written != len(data):
-				raise IOError("Serial interface only wrote "+str(written)+" bytes of "+str(len(data)))
+    def processOutgoing(self,data):
+        if self.online:
+            data = bytes([HDLC.FLAG])+HDLC.escape(data)+bytes([HDLC.FLAG])
+            written = self.serial.write(data)
+            if written != len(data):
+                raise IOError("Serial interface only wrote "+str(written)+" bytes of "+str(len(data)))
 
 
-	def readLoop(self):
-		try:
-			in_frame = False
-			escape = False
-			data_buffer = b""
-			last_read_ms = int(time.time()*1000)
+    def readLoop(self):
+        try:
+            in_frame = False
+            escape = False
+            data_buffer = b""
+            last_read_ms = int(time.time()*1000)
 
-			while self.serial.is_open:
-				if self.serial.in_waiting:
-					byte = ord(self.serial.read(1))
-					last_read_ms = int(time.time()*1000)
+            while self.serial.is_open:
+                if self.serial.in_waiting:
+                    byte = ord(self.serial.read(1))
+                    last_read_ms = int(time.time()*1000)
 
-					if (in_frame and byte == HDLC.FLAG):
-						in_frame = False
-						self.processIncoming(data_buffer)
-					elif (byte == HDLC.FLAG):
-						in_frame = True
-						data_buffer = b""
-					elif (in_frame and len(data_buffer) < RNS.Reticulum.MTU):
-						if (byte == HDLC.ESC):
-							escape = True
-						else:
-							if (escape):
-								if (byte == HDLC.FLAG ^ HDLC.ESC_MASK):
-									byte = HDLC.FLAG
-								if (byte == HDLC.ESC  ^ HDLC.ESC_MASK):
-									byte = HDLC.ESC
-								escape = False
-							data_buffer = data_buffer+bytes([byte])
-						
-				else:
-					time_since_last = int(time.time()*1000) - last_read_ms
-					if len(data_buffer) > 0 and time_since_last > self.timeout:
-						data_buffer = b""
-						in_frame = False
-						escape = False
-					sleep(0.08)
-		except Exception as e:
-			self.online = False
-			RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
-			RNS.log("The interface "+str(self.name)+" is now offline. Restart Reticulum to attempt reconnection.", RNS.LOG_ERROR)
+                    if (in_frame and byte == HDLC.FLAG):
+                        in_frame = False
+                        self.processIncoming(data_buffer)
+                    elif (byte == HDLC.FLAG):
+                        in_frame = True
+                        data_buffer = b""
+                    elif (in_frame and len(data_buffer) < RNS.Reticulum.MTU):
+                        if (byte == HDLC.ESC):
+                            escape = True
+                        else:
+                            if (escape):
+                                if (byte == HDLC.FLAG ^ HDLC.ESC_MASK):
+                                    byte = HDLC.FLAG
+                                if (byte == HDLC.ESC  ^ HDLC.ESC_MASK):
+                                    byte = HDLC.ESC
+                                escape = False
+                            data_buffer = data_buffer+bytes([byte])
+                        
+                else:
+                    time_since_last = int(time.time()*1000) - last_read_ms
+                    if len(data_buffer) > 0 and time_since_last > self.timeout:
+                        data_buffer = b""
+                        in_frame = False
+                        escape = False
+                    sleep(0.08)
+        except Exception as e:
+            self.online = False
+            RNS.log("A serial port error occurred, the contained exception was: "+str(e), RNS.LOG_ERROR)
+            RNS.log("The interface "+str(self.name)+" is now offline. Restart Reticulum to attempt reconnection.", RNS.LOG_ERROR)
 
-	def __str__(self):
-		return "SerialInterface["+self.name+"]"
+    def __str__(self):
+        return "SerialInterface["+self.name+"]"

RNS/Interfaces/TCPInterface.py

@@ -1,6 +1,7 @@
 from .Interface import Interface
 import socketserver
 import threading
+import netifaces
 import socket
 import time
 import sys
@@ -127,12 +128,21 @@ 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.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

RNS/Interfaces/UDPInterface.py

@@ -1,22 +1,34 @@
 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):
+class UDPInterface(Interface):
+
+    @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.IN  = True
         self.OUT = False
-
-        # TODO: Optimise so this is not needed
-        self.transmit_delay = 0.001
-
         self.name = name
 
+        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
             self.bind_ip = bindip
@@ -24,7 +36,7 @@ class UdpInterface(Interface):
 
             def handlerFactory(callback):
                 def createHandler(*args, **keys):
-                    return UdpInterfaceHandler(callback, *args, **keys)
+                    return UDPInterfaceHandler(callback, *args, **keys)
                 return createHandler
 
             self.owner = owner
@@ -45,16 +57,15 @@ class UdpInterface(Interface):
         self.owner.inbound(data, self)
 
     def processOutgoing(self,data):
-        time.sleep(self.transmit_delay)
         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))
 
 
     def __str__(self):
-        return "UdpInterface["+self.name+"/"+self.bind_ip+":"+str(self.bind_port)+"]"
+        return "UDPInterface["+self.name+"/"+self.bind_ip+":"+str(self.bind_port)+"]"
 
-class UdpInterfaceHandler(socketserver.BaseRequestHandler):
+class UDPInterfaceHandler(socketserver.BaseRequestHandler):
     def __init__(self, callback, *args, **keys):
         self.callback = callback
         socketserver.BaseRequestHandler.__init__(self, *args, **keys)

RNS/Packet.py

@@ -5,407 +5,479 @@ import time
 import RNS
 
 class Packet:
-	# Packet types
-	DATA         = 0x00		# Data packets
-	ANNOUNCE     = 0x01		# Announces
-	LINKREQUEST  = 0x02		# Link requests
-	PROOF        = 0x03		# Proofs
-	types        = [DATA, ANNOUNCE, LINKREQUEST, PROOF]
+    """
+    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>`.
 
-	# Header types
-	HEADER_1     = 0x00		# Normal header format
-	HEADER_2     = 0x01		# Header format used for packets in transport
-	HEADER_3     = 0x02		# Reserved
-	HEADER_4     = 0x03		# Reserved
-	header_types = [HEADER_1, HEADER_2, HEADER_3, HEADER_4]
+    For ``RNS.Destination.GROUP`` destinations, Reticulum will use the
+    pre-shared key configured for the destination.
 
-	# Data packet context types
-	NONE 		   = 0x00	# Generic data packet
-	RESOURCE       = 0x01	# Packet is part of a resource
-	RESOURCE_ADV   = 0x02	# Packet is a resource advertisement
-	RESOURCE_REQ   = 0x03	# Packet is a resource part request
-	RESOURCE_HMU   = 0x04	# Packet is a resource hashmap update
-	RESOURCE_PRF   = 0x05	# Packet is a resource proof
-	RESOURCE_ICL   = 0x06	# Packet is a resource initiator cancel message
-	RESOURCE_RCL   = 0x07	# Packet is a resource receiver cancel message
-	CACHE_REQUEST  = 0x08	# Packet is a cache request
-	REQUEST        = 0x09	# Packet is a request
-	RESPONSE       = 0x0A	# Packet is a response to a request
-	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
-	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
-	LRPROOF        = 0xFF	# Packet is a link request proof
+    For ``RNS.Destination.SINGLE`` destinations and :ref:`RNS.Link<api-link>`
+    destinations, reticulum will use ephemeral keys, and offers **Forward Secrecy**.
 
-	# This is used to calculate allowable
-	# payload sizes
-	HEADER_MAXSIZE = 23
-	MDU            = RNS.Reticulum.MDU
+    :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.
+    :param type: Internal use by :ref:`RNS.Transport<api-transport>`. Defaults to ``RNS.Packet.DATA``, and should not be specified.
+    :param context: Internal use by :ref:`RNS.Transport<api-transport>`. Ignore.
+    :param transport_type: Internal use by :ref:`RNS.Transport<api-transport>`. Ignore.
+    :param transport_id: Internal use by :ref:`RNS.Transport<api-transport>`. Ignore.
+    :param attached_interface: Internal use by :ref:`RNS.Transport<api-transport>`. Ignore.
+    """
 
-	# 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
+    # Packet types
+    DATA         = 0x00     # Data packets
+    ANNOUNCE     = 0x01     # Announces
+    LINKREQUEST  = 0x02     # Link requests
+    PROOF        = 0x03     # Proofs
+    types        = [DATA, ANNOUNCE, LINKREQUEST, PROOF]
 
-	# TODO: This should be calculated
-	# more intelligently
-	# Default packet timeout
-	TIMEOUT 	 = 60
+    # Header types
+    HEADER_1     = 0x00     # Normal header format
+    HEADER_2     = 0x01     # Header format used for packets in transport
+    HEADER_3     = 0x02     # Reserved
+    HEADER_4     = 0x03     # Reserved
+    header_types = [HEADER_1, HEADER_2, HEADER_3, HEADER_4]
 
-	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:
-			if transport_type == None:
-				transport_type = RNS.Transport.BROADCAST
+    # Packet context types
+    NONE           = 0x00   # Generic data packet
+    RESOURCE       = 0x01   # Packet is part of a resource
+    RESOURCE_ADV   = 0x02   # Packet is a resource advertisement
+    RESOURCE_REQ   = 0x03   # Packet is a resource part request
+    RESOURCE_HMU   = 0x04   # Packet is a resource hashmap update
+    RESOURCE_PRF   = 0x05   # Packet is a resource proof
+    RESOURCE_ICL   = 0x06   # Packet is a resource initiator cancel message
+    RESOURCE_RCL   = 0x07   # Packet is a resource receiver cancel message
+    CACHE_REQUEST  = 0x08   # Packet is a cache request
+    REQUEST        = 0x09   # Packet is a request
+    RESPONSE       = 0x0A   # Packet is a response to a request
+    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      = 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
+    LRPROOF        = 0xFF   # Packet is a link request proof
 
-			self.header_type    = header_type
-			self.packet_type    = packet_type
-			self.transport_type = transport_type
-			self.context        = context
+    # This is used to calculate allowable
+    # payload sizes
+    HEADER_MAXSIZE = RNS.Reticulum.HEADER_MAXSIZE
+    MDU            = RNS.Reticulum.MDU
 
-			self.hops           = 0;
-			self.destination    = destination
-			self.transport_id   = transport_id
-			self.data           = data
-			self.flags          = self.getPackedFlags()
+    # 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.AES_HMAC_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 
+    """
 
-			self.raw            = None
-			self.packed         = False
-			self.sent           = False
-			self.create_receipt = create_receipt
-			self.receipt        = None
-			self.fromPacked     = False
-		else:
-			self.raw            = data
-			self.packed         = True
-			self.fromPacked     = True
-			self.create_receipt = False
+    # TODO: This should be calculated
+    # more intelligently
+    # Default packet timeout
+    TIMEOUT      = 60
 
-		self.MTU         = RNS.Reticulum.MTU
-		self.sent_at     = None
-		self.packet_hash = None
+    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:
+            if transport_type == None:
+                transport_type = RNS.Transport.BROADCAST
 
-		self.attached_interface = attached_interface
+            self.header_type    = header_type
+            self.packet_type    = packet_type
+            self.transport_type = transport_type
+            self.context        = context
 
-	def getPackedFlags(self):
-		if self.context == Packet.LRPROOF:
-			packed_flags = (self.header_type << 6) | (self.transport_type << 4) | RNS.Destination.LINK | self.packet_type
-		else:
-			packed_flags = (self.header_type << 6) | (self.transport_type << 4) | (self.destination.type << 2) | self.packet_type
-		return packed_flags
+            self.hops           = 0;
+            self.destination    = destination
+            self.transport_id   = transport_id
+            self.data           = data
+            self.flags          = self.get_packed_flags()
 
-	def pack(self):
-		self.destination_hash = self.destination.hash
-		self.header = b""
-		self.header += struct.pack("!B", self.flags)
-		self.header += struct.pack("!B", self.hops)
+            self.raw            = None
+            self.packed         = False
+            self.sent           = False
+            self.create_receipt = create_receipt
+            self.receipt        = None
+            self.fromPacked     = False
+        else:
+            self.raw            = data
+            self.packed         = True
+            self.fromPacked     = True
+            self.create_receipt = False
 
-		if self.context == Packet.LRPROOF:
-			self.header += self.destination.link_id
-			self.ciphertext = self.data
-		else:
-			if self.header_type == Packet.HEADER_1:
-				self.header += self.destination.hash
+        self.MTU         = RNS.Reticulum.MTU
+        self.sent_at     = None
+        self.packet_hash = None
 
-				if self.packet_type == Packet.ANNOUNCE:
-					# Announce 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
-				elif self.packet_type == Packet.PROOF and self.destination.type == RNS.Destination.LINK:
-					# Packet proofs over links are not encrypted
-					self.ciphertext = self.data
-				elif self.context == Packet.RESOURCE:
-					# A resource takes care of symmetric
-					# encryption by itself
-					self.ciphertext = self.data
-				elif self.context == Packet.KEEPALIVE:
-					# Keepalive packets contain no actual
-					# data
-					self.ciphertext = self.data
-				else:
-					# In all other cases, we encrypt the packet
-					# with the destination's public key
-					self.ciphertext = self.destination.encrypt(self.data)
+        self.attached_interface = attached_interface
+        self.receiving_interface = None
 
-			if self.header_type == Packet.HEADER_2:
-				if self.transport_id != None:
-					self.header += self.transport_id
-					self.header += self.destination.hash
+    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:
+            packed_flags = (self.header_type << 6) | (self.transport_type << 4) | (self.destination.type << 2) | self.packet_type
+        return packed_flags
 
-					if self.packet_type == Packet.ANNOUNCE:
-						# Announce packets are not encrypted
-						self.ciphertext = self.data
-				else:
-					raise IOError("Packet with header type 2 must have a transport ID")
+    def pack(self):
+        self.destination_hash = self.destination.hash
+        self.header = b""
+        self.header += struct.pack("!B", self.flags)
+        self.header += struct.pack("!B", self.hops)
+
+        if self.context == Packet.LRPROOF:
+            self.header += self.destination.link_id
+            self.ciphertext = self.data
+        else:
+            if self.header_type == Packet.HEADER_1:
+                self.header += self.destination.hash
+
+                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
+                elif self.packet_type == Packet.PROOF and self.destination.type == RNS.Destination.LINK:
+                    # Packet proofs over links are not encrypted
+                    self.ciphertext = self.data
+                elif self.context == Packet.RESOURCE:
+                    # A resource takes care of symmetric
+                    # encryption by itself
+                    self.ciphertext = self.data
+                elif self.context == Packet.KEEPALIVE:
+                    # Keepalive packets contain no actual
+                    # data
+                    self.ciphertext = self.data
+                elif self.context == Packet.CACHE_REQUEST:
+                    # Cache-requests are not encrypted
+                    self.ciphertext = self.data
+                else:
+                    # In all other cases, we encrypt the packet
+                    # with the destination's encryption method
+                    self.ciphertext = self.destination.encrypt(self.data)
+
+            if self.header_type == Packet.HEADER_2:
+                if self.transport_id != None:
+                    self.header += self.transport_id
+                    self.header += self.destination.hash
+
+                    if self.packet_type == Packet.ANNOUNCE:
+                        # Announce packets are not encrypted
+                        self.ciphertext = self.data
+                else:
+                    raise IOError("Packet with header type 2 must have a transport ID")
 
 
-		self.header += bytes([self.context])
-		self.raw = self.header + self.ciphertext
+        self.header += bytes([self.context])
+        self.raw = self.header + self.ciphertext
 
-		if len(self.raw) > self.MTU:
-			raise IOError("Packet size of "+str(len(self.raw))+" exceeds MTU of "+str(self.MTU)+" bytes")
+        if len(self.raw) > self.MTU:
+            raise IOError("Packet size of "+str(len(self.raw))+" exceeds MTU of "+str(self.MTU)+" bytes")
 
-		self.packed = True
-		self.updateHash()
+        self.packed = True
+        self.update_hash()
 
-	def unpack(self):
-		self.flags = self.raw[0]
-		self.hops  = self.raw[1]
 
-		self.header_type      = (self.flags & 0b11000000) >> 6
-		self.transport_type   = (self.flags & 0b00110000) >> 4
-		self.destination_type = (self.flags & 0b00001100) >> 2
-		self.packet_type      = (self.flags & 0b00000011)
+    def unpack(self):
+        self.flags = self.raw[0]
+        self.hops  = self.raw[1]
 
-		if self.header_type == Packet.HEADER_2:
-			self.transport_id = self.raw[2:12]
-			self.destination_hash = self.raw[12:22]
-			self.context = ord(self.raw[22:23])
-			self.data = self.raw[23:]
-		else:
-			self.transport_id = None
-			self.destination_hash = self.raw[2:12]
-			self.context = ord(self.raw[12:13])
-			self.data = self.raw[13:]
+        self.header_type      = (self.flags & 0b11000000) >> 6
+        self.transport_type   = (self.flags & 0b00110000) >> 4
+        self.destination_type = (self.flags & 0b00001100) >> 2
+        self.packet_type      = (self.flags & 0b00000011)
 
-		self.packed = False
-		self.updateHash()
+        if self.header_type == Packet.HEADER_2:
+            self.transport_id = self.raw[2:12]
+            self.destination_hash = self.raw[12:22]
+            self.context = ord(self.raw[22:23])
+            self.data = self.raw[23:]
+        else:
+            self.transport_id = None
+            self.destination_hash = self.raw[2:12]
+            self.context = ord(self.raw[12:13])
+            self.data = self.raw[13:]
 
-	# 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):
-		if not self.sent:
-			if self.destination.type == RNS.Destination.LINK:
-				if self.destination.status == RNS.Link.CLOSED:
-					raise IOError("Attempt to transmit over a closed link")
-				else:
-					self.destination.last_outbound = time.time()
-					self.destination.tx += 1
-					self.destination.txbytes += len(self.data)
+        self.packed = False
+        self.update_hash()
 
-			if not self.packed:
-				self.pack()
-	
-			if RNS.Transport.outbound(self):
-				return self.receipt
-			else:
-				RNS.log("No interfaces could process the outbound packet", RNS.LOG_ERROR)
-				self.sent = False
-				self.receipt = None
-				return False
-				
-		else:
-			raise IOError("Packet was already 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:
+                    raise IOError("Attempt to transmit over a closed link")
+                else:
+                    self.destination.last_outbound = time.time()
+                    self.destination.tx += 1
+                    self.destination.txbytes += len(self.data)
 
-	def resend(self):
-		if self.sent:
-			if RNS.Transport.outbound(self):
-				return self.receipt
-			else:
-				RNS.log("No interfaces could process the outbound packet", RNS.LOG_ERROR)
-				self.sent = False
-				self.receipt = None
-				return False
-		else:
-			raise IOError("Packet was not sent yet")
+            if not self.packed:
+                self.pack()
+    
+            if RNS.Transport.outbound(self):
+                return self.receipt
+            else:
+                RNS.log("No interfaces could process the outbound packet", RNS.LOG_ERROR)
+                self.sent = False
+                self.receipt = None
+                return False
+                
+        else:
+            raise IOError("Packet was already sent")
 
-	def prove(self, destination=None):
-		if self.fromPacked and hasattr(self, "destination") and self.destination:
-			if self.destination.identity and self.destination.identity.prv:
-				self.destination.identity.prove(self, destination)
-		elif self.fromPacked and hasattr(self, "link") and self.link:
-			self.link.prove_packet(self)
-		else:
-			RNS.log("Could not prove packet associated with neither a destination nor a link", RNS.LOG_ERROR)
+    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
+            else:
+                RNS.log("No interfaces could process the outbound packet", RNS.LOG_ERROR)
+                self.sent = False
+                self.receipt = None
+                return False
+        else:
+            raise IOError("Packet was not sent yet")
 
-	# Generates a special destination that allows Reticulum
-	# to direct the proof back to the proved packet's sender
-	def generateProofDestination(self):
-		return ProofDestination(self)
+    def prove(self, destination=None):
+        if self.fromPacked and hasattr(self, "destination") and self.destination:
+            if self.destination.identity and self.destination.identity.prv:
+                self.destination.identity.prove(self, destination)
+        elif self.fromPacked and hasattr(self, "link") and self.link:
+            self.link.prove_packet(self)
+        else:
+            RNS.log("Could not prove packet associated with neither a destination nor a link", RNS.LOG_ERROR)
 
-	def validateProofPacket(self, proof_packet):
-		return self.receipt.validateProofPacket(proof_packet)
+    # Generates a special destination that allows Reticulum
+    # to direct the proof back to the proved packet's sender
+    def generate_proof_destination(self):
+        return ProofDestination(self)
 
-	def validateProof(self, proof):
-		return self.receipt.validateProof(proof)
+    def validate_proof_packet(self, proof_packet):
+        return self.receipt.validate_proof_packet(proof_packet)
 
-	def updateHash(self):
-		self.packet_hash = self.getHash()
+    def validate_proof(self, proof):
+        return self.receipt.validate_proof(proof)
 
-	def getHash(self):
-		return RNS.Identity.fullHash(self.getHashablePart())
+    def update_hash(self):
+        self.packet_hash = self.get_hash()
 
-	def getTruncatedHash(self):
-		return RNS.Identity.truncatedHash(self.getHashablePart())
+    def get_hash(self):
+        return RNS.Identity.full_hash(self.get_hashable_part())
 
-	def getHashablePart(self):
-		hashable_part = bytes([self.raw[0] & 0b00001111])
-		if self.header_type == Packet.HEADER_2:
-			hashable_part += self.raw[12:]
-		else:
-			hashable_part += self.raw[2:]
+    def getTruncatedHash(self):
+        return RNS.Identity.truncated_hash(self.get_hashable_part())
 
-		return hashable_part
+    def get_hashable_part(self):
+        hashable_part = bytes([self.raw[0] & 0b00001111])
+        if self.header_type == Packet.HEADER_2:
+            hashable_part += self.raw[12:]
+        else:
+            hashable_part += self.raw[2:]
+
+        return hashable_part
 
 class ProofDestination:
-	def __init__(self, packet):
-		self.hash = packet.getHash()[:10];
-		self.type = RNS.Destination.SINGLE
+    def __init__(self, packet):
+        self.hash = packet.get_hash()[:10];
+        self.type = RNS.Destination.SINGLE
 
-	def encrypt(self, plaintext):
-		return plaintext
+    def encrypt(self, plaintext):
+        return plaintext
 
 
 class PacketReceipt:
-	# Receipt status constants
-	FAILED    = 0x00
-	SENT	  = 0x01
-	DELIVERED = 0x02
-	CULLED    = 0xFF
+    """
+    The PacketReceipt class is used to receive notifications about
+    :ref:`RNS.Packet<api-packet>` instances sent over the network. Instances
+    of this class should never be created manually, but always returned
+    from a the *send()* method of a :ref:`RNS.Packet<api-packet>` instance.
+    """
+    # Receipt status constants
+    FAILED    = 0x00
+    SENT      = 0x01
+    DELIVERED = 0x02
+    CULLED    = 0xFF
 
 
-	EXPL_LENGTH = RNS.Identity.HASHLENGTH//8+RNS.Identity.SIGLENGTH//8
-	IMPL_LENGTH = RNS.Identity.SIGLENGTH//8
+    EXPL_LENGTH = RNS.Identity.HASHLENGTH//8+RNS.Identity.SIGLENGTH//8
+    IMPL_LENGTH = RNS.Identity.SIGLENGTH//8
 
-	# 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
+    # Creates a new packet receipt from a sent packet
+    def __init__(self, packet):
+        self.hash           = packet.get_hash()
+        self.truncated_hash = packet.getTruncatedHash()
+        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
 
-	# Validate a proof packet
-	def validateProofPacket(self, proof_packet):
-		if hasattr(proof_packet, "link") and proof_packet.link:
-			return self.validate_link_proof(proof_packet.data, proof_packet.link)
-		else:
-			return self.validateProof(proof_packet.data)
+    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 raw proof for a link
-	def validate_link_proof(self, proof, link):
-		# TODO: Hardcoded as explicit proofs for now
-		if True or len(proof) == PacketReceipt.EXPL_LENGTH:
-			# This is an explicit proof
-			proof_hash = proof[:RNS.Identity.HASHLENGTH//8]
-			signature = proof[RNS.Identity.HASHLENGTH//8:RNS.Identity.HASHLENGTH//8+RNS.Identity.SIGLENGTH//8]
-			if proof_hash == self.hash:
-				proof_valid = link.validate(signature, self.hash)
-				if proof_valid:
-					self.status = PacketReceipt.DELIVERED
-					self.proved = True
-					self.concluded_at = time.time()
-					if self.callbacks.delivery != None:
-						self.callbacks.delivery(self)
-					return True
-				else:
-					return False
-			else:
-				return False
-		elif len(proof) == PacketReceipt.IMPL_LENGTH:
-			pass
-			# TODO: Why is this disabled?
-			# signature = proof[:RNS.Identity.SIGLENGTH//8]
-			# proof_valid = self.link.validate(signature, self.hash)
-			# if proof_valid:
-			# 		self.status = PacketReceipt.DELIVERED
-			# 		self.proved = True
-			# 		self.concluded_at = time.time()
-			# 		if self.callbacks.delivery != None:
-			# 			self.callbacks.delivery(self)
-			# 		RNS.log("valid")
-			# 		return True
-			# else:
-			# 	RNS.log("invalid")
-			# 	return False
-		else:
-			return False
+    # Validate a 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)
+        else:
+            return self.validate_proof(proof_packet.data)
 
-	# Validate a raw proof
-	def validateProof(self, proof):
-		if len(proof) == PacketReceipt.EXPL_LENGTH:
-			# This is an explicit proof
-			proof_hash = proof[:RNS.Identity.HASHLENGTH//8]
-			signature = proof[RNS.Identity.HASHLENGTH//8:RNS.Identity.HASHLENGTH//8+RNS.Identity.SIGLENGTH//8]
-			if proof_hash == self.hash:
-				proof_valid = self.destination.identity.validate(signature, self.hash)
-				if proof_valid:
-					self.status = PacketReceipt.DELIVERED
-					self.proved = True
-					self.concluded_at = time.time()
-					if self.callbacks.delivery != None:
-						self.callbacks.delivery(self)
-					return True
-				else:
-					return False
-			else:
-				return False
-		elif len(proof) == PacketReceipt.IMPL_LENGTH:
-			# This is an implicit proof
-			if self.destination.identity == None:
-				return False
+    # Validate a raw proof for a link
+    def validate_link_proof(self, proof, link):
+        # TODO: Hardcoded as explicit proofs for now
+        if True or len(proof) == PacketReceipt.EXPL_LENGTH:
+            # This is an explicit proof
+            proof_hash = proof[:RNS.Identity.HASHLENGTH//8]
+            signature = proof[RNS.Identity.HASHLENGTH//8:RNS.Identity.HASHLENGTH//8+RNS.Identity.SIGLENGTH//8]
+            if proof_hash == self.hash:
+                proof_valid = link.validate(signature, self.hash)
+                if proof_valid:
+                    self.status = PacketReceipt.DELIVERED
+                    self.proved = True
+                    self.concluded_at = time.time()
+                    if self.callbacks.delivery != None:
+                        self.callbacks.delivery(self)
+                    return True
+                else:
+                    return False
+            else:
+                return False
+        elif len(proof) == PacketReceipt.IMPL_LENGTH:
+            pass
+            # TODO: Why is this disabled?
+            # signature = proof[:RNS.Identity.SIGLENGTH//8]
+            # proof_valid = self.link.validate(signature, self.hash)
+            # if proof_valid:
+            #       self.status = PacketReceipt.DELIVERED
+            #       self.proved = True
+            #       self.concluded_at = time.time()
+            #       if self.callbacks.delivery != None:
+            #           self.callbacks.delivery(self)
+            #       RNS.log("valid")
+            #       return True
+            # else:
+            #   RNS.log("invalid")
+            #   return False
+        else:
+            return False
 
-			signature = proof[:RNS.Identity.SIGLENGTH//8]
-			proof_valid = self.destination.identity.validate(signature, self.hash)
-			if proof_valid:
-					self.status = PacketReceipt.DELIVERED
-					self.proved = True
-					self.concluded_at = time.time()
-					if self.callbacks.delivery != None:
-						self.callbacks.delivery(self)
-					return True
-			else:
-				return False
-		else:
-			return False
+    # Validate a raw proof
+    def validate_proof(self, proof):
+        if len(proof) == PacketReceipt.EXPL_LENGTH:
+            # This is an explicit proof
+            proof_hash = proof[:RNS.Identity.HASHLENGTH//8]
+            signature = proof[RNS.Identity.HASHLENGTH//8:RNS.Identity.HASHLENGTH//8+RNS.Identity.SIGLENGTH//8]
+            if proof_hash == self.hash:
+                proof_valid = self.destination.identity.validate(signature, self.hash)
+                if proof_valid:
+                    self.status = PacketReceipt.DELIVERED
+                    self.proved = True
+                    self.concluded_at = time.time()
+                    if self.callbacks.delivery != None:
+                        self.callbacks.delivery(self)
+                    return True
+                else:
+                    return False
+            else:
+                return False
+        elif len(proof) == PacketReceipt.IMPL_LENGTH:
+            # This is an implicit proof
+            if self.destination.identity == None:
+                return False
 
-	def rtt(self):
-		return self.concluded_at - self.sent_at
+            signature = proof[:RNS.Identity.SIGLENGTH//8]
+            proof_valid = self.destination.identity.validate(signature, self.hash)
+            if proof_valid:
+                    self.status = PacketReceipt.DELIVERED
+                    self.proved = True
+                    self.concluded_at = time.time()
+                    if self.callbacks.delivery != None:
+                        self.callbacks.delivery(self)
+                    return True
+            else:
+                return False
+        else:
+            return False
 
-	def is_timed_out(self):
-		return (self.sent_at+self.timeout < time.time())
+    def get_rtt(self):
+        """
+        :returns: The round-trip-time in seconds
+        """
+        return self.concluded_at - self.sent_at
 
-	def check_timeout(self):
-		if self.is_timed_out():
-			if self.timeout == -1:
-				self.status = PacketReceipt.CULLED
-			else:
-				self.status = PacketReceipt.FAILED
+    def is_timed_out(self):
+        return (self.sent_at+self.timeout < time.time())
 
-			self.concluded_at = time.time()
+    def check_timeout(self):
+        if self.is_timed_out():
+            if self.timeout == -1:
+                self.status = PacketReceipt.CULLED
+            else:
+                self.status = PacketReceipt.FAILED
 
-			if self.callbacks.timeout:
-				thread = threading.Thread(target=self.callbacks.timeout, args=(self,))
-				thread.setDaemon(True)
-				thread.start()
-				#self.callbacks.timeout(self)
+            self.concluded_at = time.time()
+
+            if self.callbacks.timeout:
+                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):
-		self.timeout = float(timeout)
+    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):
-		self.callbacks.delivery = callback
+    def set_delivery_callback(self, callback):
+        """
+        Sets a function that gets called if a successfull delivery has been proven.
 
-	# Set a function that gets called if the
-	# delivery times out
-	def timeout_callback(self, callback):
-		self.callbacks.timeout = callback
+        :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 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:
-	def __init__(self):
-		self.delivery = None
-		self.timeout  = None
+    def __init__(self):
+        self.delivery = None
+        self.timeout  = None

RNS/Reticulum.py

@@ -9,383 +9,484 @@ import os.path
 import os
 import RNS
 
-#import traceback
-
 class Reticulum:
-	MTU            = 500
-	HEADER_MAXSIZE = 23
-	MDU            = MTU - HEADER_MAXSIZE
+    """
+    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.
 
-	router         = None
-	config         = None
-	
-	configdir    = os.path.expanduser("~")+"/.reticulum"
-	configpath   = ""
-	storagepath  = ""
-	cachepath    = ""
-	
-	@staticmethod
-	def exit_handler():
-		RNS.Transport.exitHandler()
-		RNS.Identity.exitHandler()
+    As soon as an instance of this class is created, Reticulum will start
+    opening and configuring any hardware devices specified in the supplied
+    configuration.
 
-	def __init__(self,configdir=None):
-		if configdir != None:
-			Reticulum.configdir = configdir
-		
-		Reticulum.configpath   = Reticulum.configdir+"/config"
-		Reticulum.storagepath = Reticulum.configdir+"/storage"
-		Reticulum.cachepath = Reticulum.configdir+"/storage/cache"
+    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).
 
-		Reticulum.__allow_unencrypted = False
-		Reticulum.__transport_enabled = False
-		Reticulum.__use_implicit_proof = True
+    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.
+    """
 
-		self.local_interface_port = 37428
-		self.share_instance = True
+    # The default RNS MTU is 500 bytes. This number has been chosen as
+    # a balance between compatibility with existing hardware devices
+    # on one hand, and the ability to use sufficiently high cryptographic
+    # key sizes on the other. In custom RNS network implementations, it
+    # is possible to raise 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.
+    MTU            = 500
+    HEADER_MAXSIZE = 23
+    MDU            = MTU - HEADER_MAXSIZE
 
-		self.is_shared_instance = False
-		self.is_connected_to_shared_instance = False
-		self.is_standalone_instance = False
+    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  = ""
+    cachepath    = ""
+    
+    @staticmethod
+    def exit_handler():
+        # 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.
 
-		if not os.path.isdir(Reticulum.storagepath):
-			os.makedirs(Reticulum.storagepath)
+        RNS.Transport.exit_handler()
+        RNS.Identity.exit_handler()
 
-		if not os.path.isdir(Reticulum.cachepath):
-			os.makedirs(Reticulum.cachepath)
+    def __init__(self,configdir=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.
 
-		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()
-			RNS.log("Default config file created. Make any necessary changes in "+Reticulum.configdir+"/config and start Reticulum again.")
-			RNS.log("Exiting now!")
-			exit(1)
+        :param configdir: Full path to a Reticulum configuration directory.
+        """
 
-		self.applyConfig()
-		RNS.Identity.loadKnownDestinations()
+        if configdir != None:
+            Reticulum.configdir = configdir
+        
+        Reticulum.configpath    = Reticulum.configdir+"/config"
+        Reticulum.storagepath   = Reticulum.configdir+"/storage"
+        Reticulum.cachepath     = Reticulum.configdir+"/storage/cache"
+        Reticulum.resourcepath  = Reticulum.configdir+"/storage/resources"
 
-		RNS.Transport.start(self)
+        Reticulum.__allow_unencrypted = False
+        Reticulum.__transport_enabled = False
+        Reticulum.__use_implicit_proof = True
 
-		atexit.register(Reticulum.exit_handler)
+        self.local_interface_port = 37428
+        self.share_instance = True
 
-	def start_local_interface(self):
-		if self.share_instance:
-			try:
-				interface = LocalInterface.LocalServerInterface(
-					RNS.Transport,
-					self.local_interface_port
-				)
-				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:
-				try:
-					interface = LocalInterface.LocalClientInterface(
-						RNS.Transport,
-						"Local shared instance",
-						self.local_interface_port)
-					interface.target_port = self.local_interface_port
-					interface.OUT = True
-					RNS.Transport.interfaces.append(interface)
-					self.is_shared_instance = False
-					self.is_standalone_instance = False
-					self.is_connected_to_shared_instance = True
-					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)
-					RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
-					self.is_shared_instance = False
-					self.is_standalone_instance = True
-					self.is_connected_to_shared_instance = False
-		else:
-			self.is_shared_instance = False
-			self.is_standalone_instance = True
-			self.is_connected_to_shared_instance = False
+        self.is_shared_instance = False
+        self.is_connected_to_shared_instance = False
+        self.is_standalone_instance = False
 
-	def applyConfig(self):
-		if "logging" in self.config:
-			for option in self.config["logging"]:
-				value = self.config["logging"][option]
-				if option == "loglevel":
-					RNS.loglevel = int(value)
-					if RNS.loglevel < 0:
-						RNS.loglevel = 0
-					if RNS.loglevel > 7:
-						RNS.loglevel = 7
+        if not os.path.isdir(Reticulum.storagepath):
+            os.makedirs(Reticulum.storagepath)
 
-		if "reticulum" in self.config:
-			for option in self.config["reticulum"]:
-				value = self.config["reticulum"][option]
-				if option == "share_instance":
-					value = self.config["reticulum"].as_bool(option)
-					self.share_instance = value
-				if option == "shared_instance_port":
-					value = int(self.config["reticulum"][option])
-					self.local_interface_port = value
-				if option == "enable_transport":
-					v = self.config["reticulum"].as_bool(option)
-					if v == True:
-						Reticulum.__transport_enabled = 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
+        if not os.path.isdir(Reticulum.cachepath):
+            os.makedirs(Reticulum.cachepath)
 
-		self.start_local_interface()
+        if not os.path.isdir(Reticulum.resourcepath):
+            os.makedirs(Reticulum.resourcepath)
 
-		if self.is_shared_instance or self.is_standalone_instance:
-			interface_names = []
-			for name in self.config["interfaces"]:
-				if not name in interface_names:
-					c = self.config["interfaces"][name]
+        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.__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)
 
-					try:
-						if ("interface_enabled" in c) and c.as_bool("interface_enabled") == True:
-							if c["type"] == "UdpInterface":
-								interface = UdpInterface.UdpInterface(
-									RNS.Transport,
-									name,
-									c["listen_ip"],
-									int(c["listen_port"]),
-									c["forward_ip"],
-									int(c["forward_port"])
-								)
+        self.__apply_config()
+        RNS.Identity.load_known_destinations()
 
-								if "outgoing" in c and c.as_bool("outgoing") == True:
-									interface.OUT = True
-								else:
-									interface.OUT = False
+        RNS.Transport.start(self)
 
-								RNS.Transport.interfaces.append(interface)
+        atexit.register(Reticulum.exit_handler)
+
+    def __start_local_interface(self):
+        if self.share_instance:
+            try:
+                interface = LocalInterface.LocalServerInterface(
+                    RNS.Transport,
+                    self.local_interface_port
+                )
+                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:
+                try:
+                    interface = LocalInterface.LocalClientInterface(
+                        RNS.Transport,
+                        "Local shared instance",
+                        self.local_interface_port)
+                    interface.target_port = self.local_interface_port
+                    interface.OUT = True
+                    RNS.Transport.interfaces.append(interface)
+                    self.is_shared_instance = False
+                    self.is_standalone_instance = False
+                    self.is_connected_to_shared_instance = True
+                    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)
+                    RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                    self.is_shared_instance = False
+                    self.is_standalone_instance = True
+                    self.is_connected_to_shared_instance = False
+        else:
+            self.is_shared_instance = False
+            self.is_standalone_instance = True
+            self.is_connected_to_shared_instance = False
+
+    def __apply_config(self):
+        if "logging" in self.config:
+            for option in self.config["logging"]:
+                value = self.config["logging"][option]
+                if option == "loglevel":
+                    RNS.loglevel = int(value)
+                    if RNS.loglevel < 0:
+                        RNS.loglevel = 0
+                    if RNS.loglevel > 7:
+                        RNS.loglevel = 7
+
+        if "reticulum" in self.config:
+            for option in self.config["reticulum"]:
+                value = self.config["reticulum"][option]
+                if option == "share_instance":
+                    value = self.config["reticulum"].as_bool(option)
+                    self.share_instance = value
+                if option == "shared_instance_port":
+                    value = int(self.config["reticulum"][option])
+                    self.local_interface_port = value
+                if option == "enable_transport":
+                    v = self.config["reticulum"].as_bool(option)
+                    if v == True:
+                        Reticulum.__transport_enabled = 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()
+
+        if self.is_shared_instance or self.is_standalone_instance:
+            interface_names = []
+            for name in self.config["interfaces"]:
+                if not name in interface_names:
+                    c = self.config["interfaces"][name]
+
+                    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,
+                                    device,
+                                    listen_ip,
+                                    listen_port,
+                                    forward_ip,
+                                    forward_port
+                                )
+
+                                if "outgoing" in c and c.as_bool("outgoing") == True:
+                                    interface.OUT = True
+                                else:
+                                    interface.OUT = False
+
+                                RNS.Transport.interfaces.append(interface)
 
 
-							if c["type"] == "TCPServerInterface":
-								interface = TCPInterface.TCPServerInterface(
-									RNS.Transport,
-									name,
-									c["listen_ip"],
-									int(c["listen_port"])
-								)
+                            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 "outgoing" in c and c.as_bool("outgoing") == True:
-									interface.OUT = True
-								else:
-									interface.OUT = False
+                                if port != None:
+                                    listen_port = port
 
-								RNS.Transport.interfaces.append(interface)
+                                interface = TCPInterface.TCPServerInterface(
+                                    RNS.Transport,
+                                    name,
+                                    device,
+                                    listen_ip,
+                                    listen_port
+                                )
+
+                                if "outgoing" in c and c.as_bool("outgoing") == True:
+                                    interface.OUT = True
+                                else:
+                                    interface.OUT = False
+
+                                RNS.Transport.interfaces.append(interface)
 
 
-							if c["type"] == "TCPClientInterface":
-								interface = TCPInterface.TCPClientInterface(
-									RNS.Transport,
-									name,
-									c["target_host"],
-									int(c["target_port"])
-								)
+                            if c["type"] == "TCPClientInterface":
+                                interface = TCPInterface.TCPClientInterface(
+                                    RNS.Transport,
+                                    name,
+                                    c["target_host"],
+                                    int(c["target_port"])
+                                )
 
-								if "outgoing" in c and c.as_bool("outgoing") == True:
-									interface.OUT = True
-								else:
-									interface.OUT = False
+                                if "outgoing" in c and c.as_bool("outgoing") == True:
+                                    interface.OUT = True
+                                else:
+                                    interface.OUT = False
 
-								RNS.Transport.interfaces.append(interface)
+                                RNS.Transport.interfaces.append(interface)
 
 
-							if c["type"] == "SerialInterface":
-								port = c["port"] if "port" in c else None
-								speed = int(c["speed"]) if "speed" in c else 9600
-								databits = int(c["databits"]) if "databits" in c else 8
-								parity = c["parity"] if "parity" in c else "N"
-								stopbits = int(c["stopbits"]) if "stopbits" in c else 1
+                            if c["type"] == "SerialInterface":
+                                port = c["port"] if "port" in c else None
+                                speed = int(c["speed"]) if "speed" in c else 9600
+                                databits = int(c["databits"]) if "databits" in c else 8
+                                parity = c["parity"] if "parity" in c else "N"
+                                stopbits = int(c["stopbits"]) if "stopbits" in c else 1
 
-								if port == None:
-									raise ValueError("No port specified for serial interface")
+                                if port == None:
+                                    raise ValueError("No port specified for serial interface")
 
-								interface = SerialInterface.SerialInterface(
-									RNS.Transport,
-									name,
-									port,
-									speed,
-									databits,
-									parity,
-									stopbits
-								)
+                                interface = SerialInterface.SerialInterface(
+                                    RNS.Transport,
+                                    name,
+                                    port,
+                                    speed,
+                                    databits,
+                                    parity,
+                                    stopbits
+                                )
 
-								if "outgoing" in c and c["outgoing"].lower() == "true":
-									interface.OUT = True
-								else:
-									interface.OUT = False
+                                if "outgoing" in c and c["outgoing"].lower() == "true":
+                                    interface.OUT = True
+                                else:
+                                    interface.OUT = False
 
-								RNS.Transport.interfaces.append(interface)
+                                RNS.Transport.interfaces.append(interface)
 
-							if c["type"] == "KISSInterface":
-								preamble = int(c["preamble"]) if "preamble" in c else None
-								txtail = int(c["txtail"]) if "txtail" in c else None
-								persistence = int(c["persistence"]) if "persistence" in c else None
-								slottime = int(c["slottime"]) if "slottime" in c else None
-								flow_control = (True if c["flow_control"] == "true" else False) if "flow_control" in c else False
+                            if c["type"] == "KISSInterface":
+                                preamble = int(c["preamble"]) if "preamble" in c else None
+                                txtail = int(c["txtail"]) if "txtail" in c else None
+                                persistence = int(c["persistence"]) if "persistence" in c else None
+                                slottime = int(c["slottime"]) if "slottime" in c else None
+                                flow_control = c.as_bool("flow_control") if "flow_control" in c else False
+                                port = c["port"] if "port" in c else None
+                                speed = int(c["speed"]) if "speed" in c else 9600
+                                databits = int(c["databits"]) if "databits" in c else 8
+                                parity = c["parity"] if "parity" in c else "N"
+                                stopbits = int(c["stopbits"]) if "stopbits" in c else 1
+                                beacon_interval = int(c["id_interval"]) if "id_interval" in c else None
+                                beacon_data = c["id_callsign"] if "id_callsign" in c else None
 
-								port = c["port"] if "port" in c else None
-								speed = int(c["speed"]) if "speed" in c else 9600
-								databits = int(c["databits"]) if "databits" in c else 8
-								parity = c["parity"] if "parity" in c else "N"
-								stopbits = int(c["stopbits"]) if "stopbits" in c else 1
+                                if port == None:
+                                    raise ValueError("No port specified for serial interface")
 
-								if port == None:
-									raise ValueError("No port specified for serial interface")
+                                interface = KISSInterface.KISSInterface(
+                                    RNS.Transport,
+                                    name,
+                                    port,
+                                    speed,
+                                    databits,
+                                    parity,
+                                    stopbits,
+                                    preamble,
+                                    txtail,
+                                    persistence,
+                                    slottime,
+                                    flow_control,
+                                    beacon_interval,
+                                    beacon_data
+                                )
 
-								interface = KISSInterface.KISSInterface(
-									RNS.Transport,
-									name,
-									port,
-									speed,
-									databits,
-									parity,
-									stopbits,
-									preamble,
-									txtail,
-									persistence,
-									slottime,
-									flow_control
-								)
+                                if "outgoing" in c and c["outgoing"].lower() == "true":
+                                    interface.OUT = True
+                                else:
+                                    interface.OUT = False
 
-								if "outgoing" in c and c["outgoing"].lower() == "true":
-									interface.OUT = True
-								else:
-									interface.OUT = False
+                                RNS.Transport.interfaces.append(interface)
 
-								RNS.Transport.interfaces.append(interface)
+                            if c["type"] == "AX25KISSInterface":
+                                preamble = int(c["preamble"]) if "preamble" in c else None
+                                txtail = int(c["txtail"]) if "txtail" in c else None
+                                persistence = int(c["persistence"]) if "persistence" in c else None
+                                slottime = int(c["slottime"]) if "slottime" in c else None
+                                flow_control = c.as_bool("flow_control") if "flow_control" in c else False
+                                port = c["port"] if "port" in c else None
+                                speed = int(c["speed"]) if "speed" in c else 9600
+                                databits = int(c["databits"]) if "databits" in c else 8
+                                parity = c["parity"] if "parity" in c else "N"
+                                stopbits = int(c["stopbits"]) if "stopbits" in c else 1
 
-							if c["type"] == "AX25KISSInterface":
-								preamble = int(c["preamble"]) if "preamble" in c else None
-								txtail = int(c["txtail"]) if "txtail" in c else None
-								persistence = int(c["persistence"]) if "persistence" in c else None
-								slottime = int(c["slottime"]) if "slottime" in c else None
-								flow_control = (True if c["flow_control"] == "true" else False) if "flow_control" in c else False
+                                callsign = c["callsign"] if "callsign" in c else ""
+                                ssid = int(c["ssid"]) if "ssid" in c else -1
 
-								port = c["port"] if "port" in c else None
-								speed = int(c["speed"]) if "speed" in c else 9600
-								databits = int(c["databits"]) if "databits" in c else 8
-								parity = c["parity"] if "parity" in c else "N"
-								stopbits = int(c["stopbits"]) if "stopbits" in c else 1
+                                if port == None:
+                                    raise ValueError("No port specified for serial interface")
 
-								callsign = c["callsign"] if "callsign" in c else ""
-								ssid = int(c["ssid"]) if "ssid" in c else -1
+                                interface = AX25KISSInterface.AX25KISSInterface(
+                                    RNS.Transport,
+                                    name,
+                                    callsign,
+                                    ssid,
+                                    port,
+                                    speed,
+                                    databits,
+                                    parity,
+                                    stopbits,
+                                    preamble,
+                                    txtail,
+                                    persistence,
+                                    slottime,
+                                    flow_control
+                                )
 
-								if port == None:
-									raise ValueError("No port specified for serial interface")
+                                if "outgoing" in c and c["outgoing"].lower() == "true":
+                                    interface.OUT = True
+                                else:
+                                    interface.OUT = False
 
-								interface = AX25KISSInterface.AX25KISSInterface(
-									RNS.Transport,
-									name,
-									callsign,
-									ssid,
-									port,
-									speed,
-									databits,
-									parity,
-									stopbits,
-									preamble,
-									txtail,
-									persistence,
-									slottime,
-									flow_control
-								)
+                                RNS.Transport.interfaces.append(interface)
 
-								if "outgoing" in c and c["outgoing"].lower() == "true":
-									interface.OUT = True
-								else:
-									interface.OUT = False
+                            if c["type"] == "RNodeInterface":
+                                frequency = int(c["frequency"]) if "frequency" in c else None
+                                bandwidth = int(c["bandwidth"]) if "bandwidth" in c else None
+                                txpower = int(c["txpower"]) if "txpower" in c else None
+                                spreadingfactor = int(c["spreadingfactor"]) if "spreadingfactor" in c else None
+                                codingrate = int(c["codingrate"]) if "codingrate" in c else None
+                                flow_control = c.as_bool("flow_control") if "flow_control" in c else False
+                                id_interval = int(c["id_interval"]) if "id_interval" in c else None
+                                id_callsign = c["id_callsign"] if "id_callsign" in c else None
 
-								RNS.Transport.interfaces.append(interface)
+                                port = c["port"] if "port" in c else None
+                                
+                                if port == None:
+                                    raise ValueError("No port specified for RNode interface")
 
-							if c["type"] == "RNodeInterface":
-								frequency = int(c["frequency"]) if "frequency" in c else None
-								bandwidth = int(c["bandwidth"]) if "bandwidth" in c else None
-								txpower = int(c["txpower"]) if "txpower" in c else None
-								spreadingfactor = int(c["spreadingfactor"]) if "spreadingfactor" in c else None
-								codingrate = int(c["codingrate"]) if "codingrate" in c else None
-								flow_control = (True if c["flow_control"] == "true" else False) if "flow_control" in c else False
+                                interface = RNodeInterface.RNodeInterface(
+                                    RNS.Transport,
+                                    name,
+                                    port,
+                                    frequency = frequency,
+                                    bandwidth = bandwidth,
+                                    txpower = txpower,
+                                    sf = spreadingfactor,
+                                    cr = codingrate,
+                                    flow_control = flow_control,
+                                    id_interval = id_interval,
+                                    id_callsign = id_callsign
+                                )
 
-								port = c["port"] if "port" in c else None
-								
-								if port == None:
-									raise ValueError("No port specified for RNode interface")
+                                if "outgoing" in c and c["outgoing"].lower() == "true":
+                                    interface.OUT = True
+                                else:
+                                    interface.OUT = False
 
-								interface = RNodeInterface.RNodeInterface(
-									RNS.Transport,
-									name,
-									port,
-									frequency,
-									bandwidth,
-									txpower,
-									spreadingfactor,
-									flow_control
-								)
+                                RNS.Transport.interfaces.append(interface)
+                        else:
+                            RNS.log("Skipping disabled interface \""+name+"\"", RNS.LOG_NOTICE)
 
-								if "outgoing" in c and c["outgoing"].lower() == "true":
-									interface.OUT = True
-								else:
-									interface.OUT = False
+                    except Exception as e:
+                        RNS.log("The interface \""+name+"\" could not be created. Check your configuration file for errors!", RNS.LOG_ERROR)
+                        RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
+                        RNS.panic()
+                else:
+                    RNS.log("The interface name \""+name+"\" was already used. Check your configuration file for errors!", RNS.LOG_ERROR)
+                    RNS.panic()
+                
 
-								RNS.Transport.interfaces.append(interface)
-						else:
-							RNS.log("Skipping disabled interface \""+name+"\"", RNS.LOG_VERBOSE)
+    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.__apply_config()
 
-					except Exception as e:
-						RNS.log("The interface \""+name+"\" could not be created. Check your configuration file for errors!", RNS.LOG_ERROR)
-						RNS.log("The contained exception was: "+str(e), RNS.LOG_ERROR)
-						RNS.panic()
-				else:
-					RNS.log("The interface name \""+name+"\" was already used. Check your configuration file for errors!", RNS.LOG_ERROR)
-					RNS.panic()
-				
+    @staticmethod
+    def should_allow_unencrypted():
+        """
+        Returns whether unencrypted links are allowed by the
+        current configuration.
 
-	def createDefaultConfig(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()
+        :returns: True if the current running configuration allows downgrading links to plaintext. False if not.
+        """
+        return Reticulum.__allow_unencrypted
 
-	@staticmethod
-	def should_allow_unencrypted():
-		return Reticulum.__allow_unencrypted
+    @staticmethod
+    def should_use_implicit_proof():
+        """
+        Returns whether proofs sent are explicit or implicit.
 
-	@staticmethod
-	def should_use_implicit_proof():
-		return Reticulum.__use_implicit_proof
+        :returns: True if the current running configuration specifies to use implicit proofs. False if not.
+        """
+        return Reticulum.__use_implicit_proof
 
-	@staticmethod
-	def transport_enabled():
-		return Reticulum.__transport_enabled
+    @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:
 __default_rns_config__ = '''# This is the default Reticulum config file.
@@ -404,10 +505,10 @@ 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
 
@@ -455,20 +556,37 @@ 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
+    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
+    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 network segments broadcast address.
+    
+    # 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.
@@ -479,9 +597,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
@@ -533,7 +665,26 @@ loglevel = 4
     # 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. The trans-
+    # ceiver 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
 
+    # 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
+    
+    
   # An example KISS modem interface. Useful for running
   # Reticulum over packet radio hardware.
 
@@ -546,7 +697,7 @@ loglevel = 4
     # Allow transmit on interface.
     outgoing = true
 
-	# Serial port for the device
+    # Serial port for the device
     port = /dev/ttyUSB1
 
     # Set the serial baud-rate and other
@@ -556,11 +707,6 @@ loglevel = 4
     parity = none
     stopbits = 1
 
-    # Whether to use KISS flow-control.
-    # This is useful for modems with a
-    # small internal packet buffer.
-    flow_control = false
-
     # Set the modem preamble. A 150ms
     # preamble should be a reasonable
     # default, but may need to be
@@ -579,6 +725,25 @@ loglevel = 4
     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
+
 
   # If you're using Reticulum on amateur radio spectrum,
   # you might want to use the AX.25 KISS interface. This
@@ -589,6 +754,9 @@ loglevel = 4
   # 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.
 
   [[Packet Radio AX.25 KISS Interface]]
     type = AX25KISSInterface
@@ -603,7 +771,7 @@ loglevel = 4
     # Allow transmit on interface.
     outgoing = true
 
-	# Serial port for the device
+    # Serial port for the device
     port = /dev/ttyUSB2
 
     # Set the serial baud-rate and other

RNS/__init__.py

@@ -3,6 +3,9 @@ import sys
 import glob
 import time
 import random
+import threading
+
+from ._version import __version__
 
 from .Reticulum import Reticulum
 from .Identity import Identity
@@ -11,7 +14,7 @@ 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')]
@@ -25,65 +28,84 @@ LOG_VERBOSE  = 5
 LOG_DEBUG    = 6
 LOG_EXTREME  = 7
 
-LOG_STDOUT	 = 0x91
+LOG_STDOUT   = 0x91
 LOG_FILE     = 0x92
 
-loglevel 	 = LOG_NOTICE
+loglevel     = LOG_NOTICE
 logfile      = None
 logdest      = LOG_STDOUT
 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"
-	if (level == LOG_ERROR):
-		return "Error"
-	if (level == LOG_WARNING):
-		return "Warning"
-	if (level == LOG_NOTICE):
-		return "Notice"
-	if (level == LOG_INFO):
-		return "Info"
-	if (level == LOG_VERBOSE):
-		return "Verbose"
-	if (level == LOG_DEBUG):
-		return "Debug"
-	if (level == LOG_EXTREME):
-		return "Extra"
-	
-	return "Unknown"
+    if (level == LOG_CRITICAL):
+        return "Critical"
+    if (level == LOG_ERROR):
+        return "Error"
+    if (level == LOG_WARNING):
+        return "Warning"
+    if (level == LOG_NOTICE):
+        return "Notice"
+    if (level == LOG_INFO):
+        return "Info"
+    if (level == LOG_VERBOSE):
+        return "Verbose"
+    if (level == LOG_DEBUG):
+        return "Debug"
+    if (level == LOG_EXTREME):
+        return "Extra"
+    
+    return "Unknown"
 
-def log(msg, level=3):
-	# TODO: not thread safe
-	if loglevel >= level:
-		timestamp = time.time()
-		logstring = "["+time.strftime(logtimefmt)+"] ["+loglevelname(level)+"] "+msg
+def version():
+    return __version__
 
-		if (logdest == LOG_STDOUT):
-			print(logstring)
+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_FILE and logfile != None):
-			file = open(logfile, "a")
-			file.write(logstring+"\n")
-			file.close()
+        if (logdest == LOG_STDOUT or _always_override_destination or _override_destination):
+            print(logstring)
+            logging_lock.release()
+
+        elif (logdest == LOG_FILE and logfile != None):
+            try:
+                file = open(logfile, "a")
+                file.write(logstring+"\n")
+                file.close()
+                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()
-	return result
+    result = random.random()
+    return result
 
 def hexrep(data, delimit=True):
-	delimiter = ":"
-	if not delimit:
-		delimiter = ""
-	hexrep = delimiter.join("{:02x}".format(c) for c in data)
-	return hexrep
+    delimiter = ":"
+    if not delimit:
+        delimiter = ""
+    hexrep = delimiter.join("{:02x}".format(c) for c in data)
+    return hexrep
 
 def prettyhexrep(data):
-	delimiter = ""
-	hexrep = "<"+delimiter.join("{:02x}".format(c) for c in data)+">"
-	return hexrep
+    delimiter = ""
+    hexrep = "<"+delimiter.join("{:02x}".format(c) for c in data)+">"
+    return hexrep
 
 def panic():
-	os._exit(255)
+    os._exit(255)

RNS/_version.py

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

RNS/vendor/__init__.py

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

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: 966ae7177c1d48c9ee15971994c623b5
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/manual/_sources/examples.rst.txt

@@ -0,0 +1,105 @@
+.. _examples-main:
+
+********
+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,78 @@
+********************
+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 basic encrypted communications suite built completely on Reticulum.
+
+.. image:: screenshots/nomadnet3.png
+    :target: _images/nomadnet3.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.
+
+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
+
+    # 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,22 @@
+******************************
+Reticulum Network Stack Manual
+******************************
+This manual aims to provide you with all the information you need to
+understand Reticulum, develop programs using it, or to participate in
+the development of Reticulum itself.
+
+.. toctree::
+   :maxdepth: 3
+
+   whatis
+   gettingstartedfast
+   understanding
+   reference
+   examples
+
+
+Indices and Tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

docs/manual/_sources/reference.rst.txt

@@ -0,0 +1,75 @@
+.. _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
+   :members:
+
+.. _api-packetreceipt:
+
+Packet Receipt
+--------------
+
+.. autoclass:: RNS.PacketReceipt
+   :members:
+
+.. _api-link:
+
+Link
+----
+
+.. autoclass:: RNS.Link
+   :members:
+
+.. _api-resource:
+
+Resource
+--------
+
+.. autoclass:: RNS.Resource
+   :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 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 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 240 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 :    86  bytes
+     - Link keepalive  :    14  bytes

docs/manual/_sources/whatis.rst.txt

@@ -0,0 +1,104 @@
+******************
+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 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 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.
+
+
+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 even remotely secure, Reticulum needs a very 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
+
+* 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 encryption
+
+  * AES-128 in CBC mode with PKCS7 padding
+
+  * HMAC using SHA256 for authentication
+
+  * IVs are generated through os.urandom()
+
+  * Keys are ephemeral and derived from an ECDH key exchange on Curve25519
+
+* 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 240 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 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.
+
+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.
+
+Supported 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

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.2 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,399 @@
+
+<!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.2 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.2 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="#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>
+      <li><a href="reference.html#RNS.Link.DEFAULT_TIMEOUT">DEFAULT_TIMEOUT (RNS.Link attribute)</a>
+</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>
+      <li><a href="reference.html#RNS.Link.disable_encryption">disable_encryption() (RNS.Link method)</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>
+  </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.Identity.get_public_key">get_public_key() (RNS.Identity method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Identity.get_random_hash">get_random_hash() (RNS.Identity static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Link.get_remote_identity">get_remote_identity() (RNS.Link method)</a>
+</li>
+      <li><a href="reference.html#RNS.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>
+</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>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Destination.hash">hash() (RNS.Destination static method)</a>
+</li>
+      <li><a href="reference.html#RNS.Destination.hash_from_name_and_identity">hash_from_name_and_identity() (RNS.Destination 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="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.Link.no_inbound_for">no_inbound_for() (RNS.Link method)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <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.Packet.PLAIN_MDU">PLAIN_MDU (RNS.Packet attribute)</a>
+</li>
+      <li><a href="reference.html#RNS.Resource.progress">progress() (RNS.Resource method)</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>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="reference.html#RNS.Link.request">request() (RNS.Link method)</a>
+</li>
+      <li><a href="reference.html#RNS.Transport.request_path">request_path() (RNS.Transport static method)</a>
+</li>
+      <li><a href="reference.html#RNS.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_allow_unencrypted">should_allow_unencrypted() (RNS.Reticulum static 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.2 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,178 @@
+
+<!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.2 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="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="understanding.html" title="Understanding Reticulum"
+             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.2 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 basic encrypted communications suite built completely on Reticulum.</p>
+<a class="reference external image-reference" href="_images/nomadnet3.png"><img alt="_images/nomadnet3.png" src="_images/nomadnet3.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>
+</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="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="#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="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/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="understanding.html" title="Understanding Reticulum"
+             >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.2 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,179 @@
+
+<!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.2 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.2 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, 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#supported-interface-types-and-devices">Supported 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#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="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#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">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.2 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/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.2 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.2 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.2 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.2 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="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="reference.html" title="API Reference"
+             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.2 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 implement 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 240 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 :    86  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="gettingstartedfast.html"
+                        title="previous chapter">Getting Started Fast</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="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.2 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/whatis.html

@@ -0,0 +1,194 @@
+
+<!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.2 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.2 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 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 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>
+<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 even remotely secure, Reticulum needs a very 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>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 encryption</p>
+<ul>
+<li><p>AES-128 in CBC mode with PKCS7 padding</p></li>
+<li><p>HMAC using SHA256 for authentication</p></li>
+<li><p>IVs are generated through os.urandom()</p></li>
+<li><p>Keys are ephemeral and derived from an ECDH key exchange on Curve25519</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 240 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 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 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="supported-interface-types-and-devices">
+<h2>Supported Interface Types and Devices<a class="headerlink" href="#supported-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>
+</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="#supported-interface-types-and-devices">Supported 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.2 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.2 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,105 @@
+.. _examples-main:
+
+********
+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,78 @@
+********************
+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 basic encrypted communications suite built completely on Reticulum.
+
+.. image:: screenshots/nomadnet3.png
+    :target: _images/nomadnet3.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.
+
+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
+
+    # 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,22 @@
+******************************
+Reticulum Network Stack Manual
+******************************
+This manual aims to provide you with all the information you need to
+understand Reticulum, develop programs using it, or to participate in
+the development of Reticulum itself.
+
+.. toctree::
+   :maxdepth: 3
+
+   whatis
+   gettingstartedfast
+   understanding
+   reference
+   examples
+
+
+Indices and Tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

docs/source/reference.rst

@@ -0,0 +1,75 @@
+.. _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
+   :members:
+
+.. _api-packetreceipt:
+
+Packet Receipt
+--------------
+
+.. autoclass:: RNS.PacketReceipt
+   :members:
+
+.. _api-link:
+
+Link
+----
+
+.. autoclass:: RNS.Link
+   :members:
+
+.. _api-resource:
+
+Resource
+--------
+
+.. autoclass:: RNS.Resource
+   :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 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 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 240 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 :    86  bytes
+     - Link keepalive  :    14  bytes

docs/source/whatis.rst

@@ -0,0 +1,104 @@
+******************
+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 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 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.
+
+
+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 even remotely secure, Reticulum needs a very 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
+
+* 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 encryption
+
+  * AES-128 in CBC mode with PKCS7 padding
+
+  * HMAC using SHA256 for authentication
+
+  * IVs are generated through os.urandom()
+
+  * Keys are ephemeral and derived from an ECDH key exchange on Curve25519
+
+* 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 240 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 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.
+
+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.
+
+Supported 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

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.1",
+    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,6 @@ setuptools.setup(
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
     ],
-    install_requires=['cryptography', 'pyserial'],
-    python_requires='>=3.6',
+    install_requires=['cryptography>=3.4.7', 'pyserial', 'netifaces>=0.10.4'],
+    python_requires='>=3.5',
 )