From eecfbed3e4ac5b20b555f873cb4d3383bc886d67 Mon Sep 17 00:00:00 2001 From: Mark Qvist Date: Sun, 16 May 2021 19:18:21 +0200 Subject: [PATCH] Work on documentation --- docs/source/examples.rst | 3 ++ docs/source/gettingstartedfast.rst | 72 ++++++++++++++++++++++++++++++ docs/source/index.rst | 5 ++- docs/source/overview.rst | 9 ++-- 4 files changed, 82 insertions(+), 7 deletions(-) create mode 100644 docs/source/examples.rst create mode 100644 docs/source/gettingstartedfast.rst diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 0000000..5e43ae2 --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,3 @@ +******** +Examples +******** diff --git a/docs/source/gettingstartedfast.rst b/docs/source/gettingstartedfast.rst new file mode 100644 index 0000000..acf0466 --- /dev/null +++ b/docs/source/gettingstartedfast.rst @@ -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 `_, 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`. + +Further information can be found in the :ref:`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` chapter. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 25fc30c..f3fc843 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,6 @@ +************************************* 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 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 :caption: Table of Contents: + gettingstartedfast + examples reference overview diff --git a/docs/source/overview.rst b/docs/source/overview.rst index fa54ef6..cc09a96 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -1,16 +1,14 @@ *********************** Understanding Reticulum *********************** - 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 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. +the best place to go for such information is the Python reference implementation of Reticulum, along +with the API reference. 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 @@ -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 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 +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