Work on documentation

This commit is contained in:
Mark Qvist 2021-05-16 19:18:21 +02:00
parent 90881e0d47
commit eecfbed3e4
4 changed files with 82 additions and 7 deletions

3
docs/source/examples.rst Normal file
View File

@ -0,0 +1,3 @@
********
Examples
********

View File

@ -0,0 +1,72 @@
********************
Getting Started Fast
********************
What do we want to do? Something! When do want to do it? Right now!
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.
Develop a Program with Reticulum
===========================================
If you want to develop programs that use Reticulum, the easiest way to get
started is to install 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>`.
Further information can be found in the :ref:`API Reference<API Reference>`.
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 Reticulum>` chapter.

View File

@ -1,5 +1,6 @@
*************************************
Reticulum Network Stack Documentation Reticulum Network Stack Documentation
===================================== *************************************
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 cryptography-based networking stack for wide-area networks built on readily available hardware, and can operate even with very high latency and extremely low bandwidth. Reticulum allows you to build very wide-area networks with off-the-shelf tools, and offers end-to-end encryption, autoconfiguring cryptographically backed multi-hop transport, efficient addressing, unforgeable packet acknowledgements and more.
Reticulum is a complete networking stack, and does not use IP or higher layers, although it is easy to utilise IP (with TCP or UDP) as the underlying carrier for Reticulum. It is therefore trivial to tunnel Reticulum over the Internet or private IP networks. Reticulum is a complete networking stack, and does not 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.
@ -8,6 +9,8 @@ Reticulum is a complete networking stack, and does not use IP or higher layers,
:maxdepth: 3 :maxdepth: 3
:caption: Table of Contents: :caption: Table of Contents:
gettingstartedfast
examples
reference reference
overview overview

View File

@ -1,16 +1,14 @@
*********************** ***********************
Understanding Reticulum Understanding Reticulum
*********************** ***********************
This document will briefly describe the overall purpose and operating principles of Reticulum, a This document 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 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 links. It should give you an overview of how the stack works, and an understanding of how to
develop networked applications using Reticulum. develop networked applications using Reticulum.
This document is not an exhaustive source of information on Reticulum, at least not yet. Currently, 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 best place to go for such information is the Python reference implementation of Reticulum, along
the reference implementation and this document may (and will) change rapidly in the current phase with the API reference.
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 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 operates, what it can achieve, and how you can use it yourself. If you want to help out with the
@ -423,14 +421,13 @@ note that Reticulum is designed to be usable over more or less any medium that a
and receive data in a digital form, and satisfies some very low minimum requirements. The 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 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 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 Reticulum software should be able to run on more or less any hardware that can provide a Python 3.x
runtime environment. runtime environment.
That being said, the reference setup has been outlined to provide a common platform for anyone 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 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: recommended setup to get started. A reference system consists of three parts:
* **A channel access device** * **A channel access device**
Or *CAD* , in short, provides access to the physical medium whereupon the communication 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 takes place, for example a radio with an integrated modem. A setup with a separate modem