This example can be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py.
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.
+##########################################################
+# This RNS example demonstrates a minimal setup, that #
+# will start up the Reticulum Network Stack, generate a #
+# new destination, and let the user send an announce. #
+##########################################################
+
+import argparse
+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"
+
+# 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 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)
+
+
+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)")
+
+ # 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))
+
+
+##########################################################
+#### 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="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()
+
+ if args.config:
+ configarg = args.config
+ else:
+ configarg = None
+
+ program_setup(configarg)
+
+ except KeyboardInterrupt:
+ print("")
+ exit()
+This example can also be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py.
This example can be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py.
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.
+##########################################################
+# 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", "Passion fruit", "Prune", "Cranberry", "Strawberry", "Papaya", "Pomegranate", "Avocado", "Mango"]
+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()
+This example can also be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py.
This example can be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py.
The Broadcast example explores how to transmit plaintext broadcast messages over the network.
+##########################################################
+# This RNS example demonstrates broadcasting unencrypted #
+# information to any listening destinations. #
+##########################################################
+
+import sys
+import argparse
+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"
+
+# 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 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)
+
+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()
+
+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)")
+
+ # 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()
+
+
+
+##########################################################
+#### Program Startup #####################################
+##########################################################
+
+# This part of the program gets run at startup,
+# 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="broadcast channel name", type=str)
+ args = parser.parse_args()
+
+ 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()
+This example can also be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py.
This example can be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py.
The Echo example demonstrates communication between two destinations using the Packet interface.
+##########################################################
+# This RNS example demonstrates a simple client/server #
+# echo utility. A client can send an echo request to the #
+# server, and the server will respond by proving receipt #
+# of the packet. #
+##########################################################
+
+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 #########################################
+##########################################################
+
+# 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 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)
+
+ # 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)")
+
+ # 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")
+
+
+##########################################################
+#### Client Part #########################################
+##########################################################
+
+# 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 must first initialise Reticulum
+ reticulum = RNS.Reticulum(configpath)
+
+ # We override the loglevel to provide feedback when
+ # an announce is received
+ if RNS.loglevel < RNS.LOG_INFO:
+ RNS.loglevel = RNS.LOG_INFO
+
+ # 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 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):
+
+ # 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 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")
+
+ # 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())
+
+ # Send the packet! If the packet is successfully
+ # sent, it will return a PacketReceipt instance.
+ packet_receipt = echo_request.send()
+
+ # 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)
+
+ # 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)
+
+ # 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"
+
+ 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")
+
+
+##########################################################
+#### 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="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()
+
+ 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()
+This example can also be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py.
This example can be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py.
The Link example explores establishing an encrypted link to a remote destination, and passing traffic back and forth over the link.
+##########################################################
+# This RNS example demonstrates how to set up a link to #
+# a destination, and pass data back and forth over it. #
+##########################################################
+
+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, "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)
+
+ # 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)")
+
+ # 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.link_closed_callback(client_disconnected)
+ link.packet_callback(server_packet_received)
+ latest_client_link = link
+
+def client_disconnected(link):
+ RNS.log("Client disconnected")
+
+def server_packet_received(message, packet):
+ 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()
+
+
+##########################################################
+#### 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, "linkexample")
+
+ # 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'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)
+
+ # 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")
+ RNS.Packet(server_link, data).send()
+ except Exception as 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
+
+ # 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)
+
+# 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()
+This example can also be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py.
This example can be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py.
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 Link.
+##########################################################
+# This RNS example demonstrates a simple filetransfer #
+# 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
+import sys
+import time
+import threading
+import argparse
+import RNS
+import RNS.vendor.umsgpack as umsgpack
+
+# 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"
+
+# We'll also define a default timeout, in seconds
+APP_TIMEOUT = 45.0
+
+##########################################################
+#### Server Part #########################################
+##########################################################
+
+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()
+
+ 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 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)
+
+ # 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)")
+
+ # 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] != "."]
+
+# 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...")
+
+ link.link_closed_callback(client_disconnected)
+
+ # 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()
+
+def client_disconnected(link):
+ 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_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 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")
+
+def list_timeout(receipt):
+ 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 = []
+
+# A reference to the server link
+server_link = None
+
+# And a reference to the current download
+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 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, "filetransfer", "server")
+
+ # 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)
+
+ # 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'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)
+
+ # 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)
+
+ menu()
+
+# Requests the specified file from the server
+def download(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"
+
+# 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 menu_mode
+ menu_mode = "main"
+ should_quit = False
+ while (not should_quit):
+ print_menu()
+
+ 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
+
+ if should_quit:
+ server_link.teardown()
+
+# Prints out menus or screens for the
+# various states of the client program.
+# It's simple and quite uninteresting.
+# I won't go into detail here. Just
+# strings basically.
+def print_menu():
+ 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 == "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 == "download_concluded":
+ if current_download.status == RNS.Resource.COMPLETE:
+ print(("\rProgress: 100.0 %"), end=' ')
+ sys.stdout.flush()
+
+ # 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()
+
+ 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)
+
+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)
+
+ # 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
+
+ # 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()
+
+# 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)
+
+ 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)
+
+# 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, 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, download_started, download_finished, download_time
+ download_finished = time.time()
+ download_time = download_finished - download_started
+
+ saved_filename = current_filename
+
+
+ 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():
+ os.system('cls' if os.name=='nt' else 'clear')
+
+##########################################################
+#### 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 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()
+
+ 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()
+This example can also be found at https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py.
The curve used for Elliptic Curve DH key exchanges
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 API reference.
+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 also provide a pretty clear overview of 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.
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 and trust 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.
-This need for coordination and trust inevitably leads to an environment of control, where it’s very -easy for infrastructure operators or governments to control or alter traffic.
+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 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).
+“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 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).
To be as widely usable and easy to implement as possible, the following goals have been used to guide the design of Reticulum:
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.
+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.
Reticulum shall be fully hardware agnostic, and should be useable over a wide range +
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 @@ -94,8 +95,8 @@ it can be easily replicated.
Reticulum should be able to function reliably over links with a data capacity as low as 1, -bps.
+Reticulum should be able to function reliably over links with a transmission capacity as low +as 1,000 bps.
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.
+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.Apart from the core networking stack and API, that allows any developer to build +
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 @@ -121,8 +123,8 @@ to build applications with Reticulum.
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 +
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.
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.
+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.
-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.
+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.
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:
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.
+number of users, or should be readable by anyone. Traffic to a plain destination is not encrypted.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.
+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.
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. +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. 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
+a destination for a environmental monitoring application could be made up of the application name, a
+device type and measurement type, like this:
+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. 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:
+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:
When private communication between two endpoints is needed. Supports routing.
+When private communication between two endpoints is needed. Supports multiple hops.
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.
+data usage than single destinations. Supports multiple hops indirectly, but must first be +established through a single destination.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.
+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 methodology, and that it is therefore not required to use the announce/request functionality. +It is by far the easiest though, and should definitely be used if there is not a good reason for +doing it differently.
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 @@ -262,11 +287,11 @@ the aspect names of the destination. These are intentionally left out to save ba 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.
+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.
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 @@ -283,173 +308,184 @@ reach the user. In such a case it is of great importance to store the user’s i privately.
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.
+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 next sections, two concepts that allow this will be introduced, paths and +links.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.
+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, and resources that help alleviate congestion and make reliable communication more -efficient and less bandwidth-hungry.
-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:
-traverses the network and locates the desired destination. Along the way, the nodes that -forward the packet will take note of this link request.
-authenticity of it’s identity (and the receipt of the link request) to the initiating node. All +
remember the link , and it can subsequently be used by referring to a hash representing it.
-efficient symmetrically encrypted tunnel between the two nodes, using elliptic curve +
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
+bandwidth, so it can be used just for a short exchange, and then recreated as needed, which will also +rotate encryption keys, 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. +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.
total it has been retransmitted to get here.
-set to 18.
-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.
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.
-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 queue, the newest announce is discarded. If the newest announce contains different +
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.
+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 +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
+days. +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.
-will create a link request packet, and broadcast it.
-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.
-previously.
-amount of hops the packet had taken when received. The link id is a hash of the entire link +
request. If it is accepted, it will create a special packet called a proof. A proof is a simple +
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 @@ -463,16 +499,10 @@ of Reticulum, such a retransmission does not need to travel the entire length of 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.
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.
TODO: Write
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 @@ -501,7 +531,7 @@ code.
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 @@ -541,13 +571,12 @@ into the future. The current Reference System Setup is as follows:
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.
+MHz frequency bands. More details can be found on the RNode Page.Any computer device running Linux and Python. A Raspberry Pi with Raspbian is +
Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is recommended.
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.
+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. +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.
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.
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 +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.
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.
-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.
+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.
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.
+== 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)
+Coordination-less globally unique adressing and identification
Fully self-configuring multi-hop routing
Asymmetric RSA encryption and signatures as basis for all communication
Perfect Forward Secrecy on links with ephemereal Elliptic Curve Diffie-Hellman keys (on the SECP256R1 curve)
Perfect Forward Secrecy on links with ephemereal Elliptic Curve Diffie-Hellman keys (on Curve25519)
Reticulum uses the Fernet specification for encryption on links and to group destinations
AES-128 in CBC mode with PKCS7 padding