Reticulum/docs/source/gettingstartedfast.rst

174 lines
6.1 KiB
ReStructuredText
Raw Normal View History

2021-05-16 19:18:21 +02:00
********************
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
2021-10-08 18:30:17 +02:00
provides a complete encrypted communications suite built with Reticulum.
2021-05-16 19:18:21 +02:00
2021-09-18 16:29:47 +02:00
.. image:: screenshots/nomadnet_3.png
:target: _images/nomadnet_3.png
2021-05-17 20:01:53 +02:00
`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
2021-12-06 14:10:22 +01:00
for the messaging and information-sharing protocol
2021-05-17 20:01:53 +02:00
`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
2021-09-18 16:29:47 +02:00
You can install Nomad Network via pip:
.. code::
2021-09-25 21:39:31 +02:00
# Install ...
2021-09-18 16:29:47 +02:00
pip3 install nomadnet
2021-09-25 21:39:31 +02:00
# ... and run
2021-09-18 16:29:47 +02:00
nomadnet
2021-10-08 18:30:17 +02:00
Using the Included Utilities
2021-09-25 21:39:31 +02:00
=============================================
2021-10-08 18:30:17 +02:00
Reticulum comes with a range of included utilities that make it easier to
manage your network, check connectivity and make Reticulum available to other
programs on your system.
You can use ``rnsd`` to run Reticulum as a background or foreground service,
and the ``rnstatus``, ``rnpath`` and ``rnprobe`` utilities to view and query
network status and connectivity.
To learn more about these utility programs, have a look at the
:ref:`Using Reticulum on Your System<using-main>` chapter of this manual.
2021-09-25 21:39:31 +02:00
2021-10-08 18:30:17 +02:00
Creating a Network With Reticulum
=============================================
2021-09-25 21:39:31 +02:00
To create a network, you will need to specify one or more *interfaces* for
Reticulum to use. This is done in the Reticulum configuration file, which by
2021-12-06 14:10:22 +01:00
default is located at ``~/.reticulum/config``. You can edit this file by hand,
or use the interactive ``rnsconfig`` utility.
2021-09-25 21:39:31 +02:00
When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses
your existing ethernet network (if there is one), and only allows you to
communicate with other Reticulum peers within your local broadcast domain.
To communicate further, you will have to add one or more interfaces. The default
configuration includes a number of examples, ranging from using TCP over the
internet, to LoRa and Packet Radio interfaces.
2021-09-25 23:22:33 +02:00
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.
2021-09-25 21:39:31 +02:00
2021-05-16 19:18:21 +02:00
Develop a Program with Reticulum
===========================================
If you want to develop programs that use Reticulum, the easiest way to get
2021-05-20 16:06:12 +02:00
started is to install the latest release of Reticulum via pip:
2021-05-16 19:18:21 +02:00
.. 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
2021-05-16 21:58:11 +02:00
likely be to look at some :ref:`Example Programs<examples-main>`.
2021-05-16 19:18:21 +02:00
2021-12-02 18:33:00 +01:00
For extended functionality, you can install optional dependencies:
.. code::
pip3 install pyserial netifaces
2021-05-16 21:58:11 +02:00
Further information can be found in the :ref:`API Reference<api-main>`.
2021-05-16 19:18:21 +02:00
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
2021-09-25 21:39:31 +02:00
pip3 install cryptography pyserial netifaces
2021-05-16 19:18:21 +02:00
# 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
2021-12-05 23:24:30 +01:00
:ref:`Understanding Reticulum<understanding-main>` chapter.
Reticulum on Android
==============================================
Reticulum can be used on Android in different ways. The easiest way to get
started is using the `Termux app <https://termux.com/>`_, at the time of writing
2021-12-05 23:26:52 +01:00
available on `F-droid <https://f-droid.org>`_.
Termux is a terminal emulator and Linux environment for Android based devices,
which includes the ability to use many different programs and libraries,
including Reticulum.
2021-12-05 23:24:30 +01:00
Since the Python cryptography.io module does not offer pre-built wheels for
Android, the standard one-line install of Reticulum does not work on Android,
and a few extra commands are required.
From within Termux, execute the following:
.. code::
# First, make sure indexes and packages are up to date.
pkg update
pkg upgrade
2021-12-06 14:10:22 +01:00
# Then install dependencies for the cryptography library.
2021-12-05 23:24:30 +01:00
pkg install python build-essential openssl libffi rust
2021-12-05 23:28:15 +01:00
# Make sure pip is up to date, and install the wheel module.
2021-12-05 23:24:30 +01:00
pip3 install wheel pip --upgrade
# Start the install process for the cryptography module.
# Depending on your device, this can take several minutes,
# since the module must be compiled locally on your device.
pip3 install cryptography
# If the above installation succeeds, you can now install
# Reticulum and any related software
pip3 install rns
It is also possible to include Reticulum in apps compiled and distributed as
Android APKs. A detailed tutorial and example source code will be included
here at a later point.