Updated docs

docs/source/examples.rst

@@ -1,8 +1,9 @@
 .. _examples-main:
 
-********
-Examples
-********
+*************
+Code Examples
+*************
+
 A number of examples are included in the source distribution of Reticulum.
 You can use these examples to learn how to write your own programs.
 

docs/source/gettingstartedfast.rst

@@ -47,9 +47,9 @@ To communicate further, you will have to add one or more interfaces. The default
 configuration includes a number of examples, ranging from using TCP over the
 internet, to LoRa and Packet Radio interfaces.
 
-Possibly, the examples in the config file are enough to gen you started. If
-you want more information, you can read the :ref:`Interfaces<interfaces-main>`
-chapter of this manual.
+Possibly, the examples in the config file are enough to get you started. If
+you want more information, you can read the :ref:`Building Networks<networks-main>`
+and :ref:`Interfaces<interfaces-main>` chapters of this manual.
 
 
 Develop a Program with Reticulum

docs/source/index.rst

@@ -2,15 +2,17 @@
 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.
+understand Reticulum, build networks or develop programs using it, or
+to participate in the development of Reticulum itself.
 
 .. toctree::
    :maxdepth: 3
 
    whatis
    gettingstartedfast
+   using
    networks
+   interfaces
    understanding
    reference
    examples

docs/source/interfaces.rst

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

docs/source/networks.rst

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

docs/source/understanding.rst

@@ -52,7 +52,7 @@ by using multiple hops).
 Goals
 =====
 
-To be as widely usable and easy to implement as possible, the following goals have been used to
+To be as widely usable and easy to use as possible, the following goals have been used to
 guide the design of Reticulum:
 
 

docs/source/using.rst

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

docs/source/whatis.rst

@@ -18,7 +18,7 @@ Reticulum should currently be considered beta software. All core protocol featur
 
 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.
+Reticulum is an experimental networking stack, and should be considered as such. While it has been built with cryptography best-practices very foremost in mind, it has not been externally security audited, and there could very well be privacy-breaking bugs. To be considered secure, Reticulum needs a thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch.
 
 
 What does Reticulum Offer?
@@ -87,8 +87,8 @@ 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
-=====================================
+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
@@ -101,4 +101,6 @@ Reticulum implements a range of generalised interface types that covers most of
 
 * TCP over IP networks
 
-* UDP over IP networks
+* UDP over IP networks
+
+For a full list and more details, see the :ref:`Supported Interfaces<interfaces-main>` chapter.