Updated utilities section of docs

RNS/Channel.py

@@ -530,6 +530,7 @@ class Channel(contextlib.AbstractContextManager):
     def _update_packet_timeouts(self):
         for envelope in self._tx_ring:
             updated_timeout = self._get_packet_timeout_time(envelope.tries)
+            if envelope.packet and envelope.packet.receipt and envelope.packet.receipt.timeout:
                 if updated_timeout > envelope.packet.receipt.timeout:
                     envelope.packet.receipt.set_timeout(updated_timeout)
 

RNS/Utilities/rncp.py

@@ -35,8 +35,9 @@ APP_NAME = "rncp"
 allow_all = False
 allowed_identity_hashes = []
 
-def receive(configdir, verbosity = 0, quietness = 0, allowed = [], display_identity = False, limit = None, disable_auth = None, announce = False):
+def listen(configdir, verbosity = 0, quietness = 0, allowed = [], display_identity = False, limit = None, disable_auth = None, announce = False):
     global allow_all, allowed_identity_hashes
+    from tempfile import TemporaryFile
     identity = None
     if announce < 0:
         announce = False
@@ -86,7 +87,7 @@ def receive(configdir, verbosity = 0, quietness = 0, allowed = [], display_ident
                         allowed = ali
                     else:
                         allowed.extend(ali)
-                if al == 1:
+                if len(ali) == 1:
                     ms = "y"
                 else:
                     ms = "ies"
@@ -113,7 +114,44 @@ def receive(configdir, verbosity = 0, quietness = 0, allowed = [], display_ident
     if len(allowed_identity_hashes) < 1 and not disable_auth:
         print("Warning: No allowed identities configured, rncp will not accept any files!")
 
-    destination.set_link_established_callback(receive_link_established)
+    def fetch_request(path, data, request_id, link_id, remote_identity, requested_at):
+        target_link = None
+        for link in RNS.Transport.active_links:
+            if link.link_id == link_id:
+                target_link = link
+
+        file_path = os.path.expanduser(data)
+        if not os.path.isfile(file_path):
+            RNS.log("Client-requested file not found: "+str(file_path), RNS.LOG_VERBOSE)
+            return False
+        else:
+            if target_link != None:
+                RNS.log("Sending file "+str(file_path)+" to client", RNS.LOG_VERBOSE)
+
+                temp_file = TemporaryFile()
+                real_file = open(file_path, "rb")
+                filename_bytes = os.path.basename(file_path).encode("utf-8")
+                filename_len = len(filename_bytes)
+
+                if filename_len > 0xFFFF:
+                    print("Filename exceeds max size, cannot send")
+                    exit(1)
+                else:
+                    print("Preparing file...", end=" ")
+
+                temp_file.write(filename_len.to_bytes(2, "big"))
+                temp_file.write(filename_bytes)
+                temp_file.write(real_file.read())
+                temp_file.seek(0)
+
+                fetch_resource = RNS.Resource(temp_file, target_link)
+                return True
+            else:
+                return None
+
+
+    destination.set_link_established_callback(client_link_established)
+    destination.register_request_handler("fetch_file", response_generator=fetch_request, allow=RNS.Destination.ALLOW_LIST, allowed_list=allowed_identity_hashes)
     print("rncp listening on "+RNS.prettyhexrep(destination.hash))
 
     if announce >= 0:
@@ -129,7 +167,7 @@ def receive(configdir, verbosity = 0, quietness = 0, allowed = [], display_ident
     while True:
         time.sleep(1)
 
-def receive_link_established(link):
+def client_link_established(link):
     RNS.log("Incoming link established", RNS.LOG_VERBOSE)
     link.set_remote_identified_callback(receive_sender_identified)
     link.set_resource_strategy(RNS.Link.ACCEPT_APP)
@@ -223,6 +261,220 @@ def sender_progress(resource):
         resource_done = True
 
 link = None
+def fetch(configdir, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False):
+    global current_resource, resource_done, link, speed
+    targetloglevel = 3+verbosity-quietness
+
+    try:
+        dest_len = (RNS.Reticulum.TRUNCATED_HASHLENGTH//8)*2
+        if len(destination) != dest_len:
+            raise ValueError("Allowed destination length is invalid, must be {hex} hexadecimal characters ({byte} bytes).".format(hex=dest_len, byte=dest_len//2))
+        try:
+            destination_hash = bytes.fromhex(destination)
+        except Exception as e:
+            raise ValueError("Invalid destination entered. Check your input.")
+    except Exception as e:
+        print(str(e))
+        exit(1)
+
+    reticulum = RNS.Reticulum(configdir=configdir, loglevel=targetloglevel)
+
+    identity_path = RNS.Reticulum.identitypath+"/"+APP_NAME
+    if os.path.isfile(identity_path):
+        identity = RNS.Identity.from_file(identity_path)
+        if identity == None:
+            RNS.log("Could not load identity for rncp. The identity file at \""+str(identity_path)+"\" may be corrupt or unreadable.", RNS.LOG_ERROR)
+            exit(2)
+    else:
+        identity = None
+
+    if identity == None:
+        RNS.log("No valid saved identity found, creating new...", RNS.LOG_INFO)
+        identity = RNS.Identity()
+        identity.to_file(identity_path)
+
+    if not RNS.Transport.has_path(destination_hash):
+        RNS.Transport.request_path(destination_hash)
+        if silent:
+            print("Path to "+RNS.prettyhexrep(destination_hash)+" requested")
+        else:
+            print("Path to "+RNS.prettyhexrep(destination_hash)+" requested  ", end=" ")
+        sys.stdout.flush()
+
+    i = 0
+    syms = "⢄⢂⢁⡁⡈⡐⡠"
+    estab_timeout = time.time()+timeout
+    while not RNS.Transport.has_path(destination_hash) and time.time() < estab_timeout:
+        if not silent:
+            time.sleep(0.1)
+            print(("\b\b"+syms[i]+" "), end="")
+            sys.stdout.flush()
+            i = (i+1)%len(syms)
+
+    if not RNS.Transport.has_path(destination_hash):
+        if silent:
+            print("Path not found")
+        else:
+            print("\r                                                            \rPath not found")
+        exit(1)
+    else:
+        if silent:
+            print("Establishing link with "+RNS.prettyhexrep(destination_hash))
+        else:
+            print("\r                                                            \rEstablishing link with "+RNS.prettyhexrep(destination_hash)+" ", end=" ")
+
+    listener_identity = RNS.Identity.recall(destination_hash)
+    listener_destination = RNS.Destination(
+        listener_identity,
+        RNS.Destination.OUT,
+        RNS.Destination.SINGLE,
+        APP_NAME,
+        "receive"
+    )
+
+    link = RNS.Link(listener_destination)
+    while link.status != RNS.Link.ACTIVE and time.time() < estab_timeout:
+        if not silent:
+            time.sleep(0.1)
+            print(("\b\b"+syms[i]+" "), end="")
+            sys.stdout.flush()
+            i = (i+1)%len(syms)
+
+    if not RNS.Transport.has_path(destination_hash):
+        if silent:
+            print("Could not establish link with "+RNS.prettyhexrep(destination_hash))
+        else:
+            print("\r                                                            \rCould not establish link with "+RNS.prettyhexrep(destination_hash))
+        exit(1)
+    else:
+        if silent:
+            print("Requesting file from remote...")
+        else:
+            print("\r                                                            \rRequesting file from remote  ", end=" ")
+
+    link.identify(identity)
+
+    request_resolved = False
+    request_status = "unknown"
+    resource_resolved = False
+    resource_status = "unrequested"
+    current_resource = None
+    def request_response(request_receipt):
+        nonlocal request_resolved, request_status
+        if request_receipt.response == False:
+            request_status = "not_found"
+        elif request_receipt.response == None:
+            request_status = "remote_error"
+        else:
+            request_status = "found"
+
+        request_resolved = True
+
+    def request_failed(request_receipt):
+        nonlocal request_resolved, request_status
+        request_status = "unknown"
+        request_resolved = True
+
+    def fetch_resource_started(resource):
+        nonlocal resource_status
+        current_resource = resource
+        current_resource.progress_callback(sender_progress)
+        resource_status = "started"
+
+    def fetch_resource_concluded(resource):
+        nonlocal resource_resolved, resource_status
+        if resource.status == RNS.Resource.COMPLETE:
+            if resource.total_size > 4:
+                filename_len = int.from_bytes(resource.data.read(2), "big")
+                filename = resource.data.read(filename_len).decode("utf-8")
+
+                counter = 0
+                saved_filename = filename
+                while os.path.isfile(saved_filename):
+                    counter += 1
+                    saved_filename = filename+"."+str(counter)
+                
+                file = open(saved_filename, "wb")
+                file.write(resource.data.read())
+                file.close()
+                resource_status = "completed"
+
+            else:
+                print("Invalid data received, ignoring resource")
+                resource_status = "invalid_data"
+
+        else:
+            print("Resource failed")
+            resource_status = "failed"
+
+        resource_resolved = True
+
+    link.set_resource_strategy(RNS.Link.ACCEPT_ALL)
+    link.set_resource_started_callback(fetch_resource_started)
+    link.set_resource_concluded_callback(fetch_resource_concluded)
+    link.request("fetch_file", data=file, response_callback=request_response, failed_callback=request_failed)
+
+    syms = "⢄⢂⢁⡁⡈⡐⡠"
+    while not request_resolved:
+        if not silent:
+            time.sleep(0.1)
+            print(("\b\b"+syms[i]+" "), end="")
+            sys.stdout.flush()
+            i = (i+1)%len(syms)
+
+    if request_status == "not_found":
+        if not silent: print("\r                                                            \r", end="")
+        print("Fetch request failed, the file "+str(file)+" was not found on the remote")
+        link.teardown()
+        time.sleep(1)
+        exit(0)
+    elif request_status == "remote_error":
+        if not silent: print("\r                                                            \r", end="")
+        print("Fetch request failed due to an error on the remote system")
+        link.teardown()
+        time.sleep(1)
+        exit(0)
+    elif request_status == "unknown":
+        if not silent: print("\r                                                            \r", end="")
+        print("Fetch request failed due to an unknown error (probably not authorised)")
+        link.teardown()
+        time.sleep(1)
+        exit(0)
+    elif request_status == "found":
+        if not silent: print("\r                                                            \r", end="")
+
+    while not resource_resolved:
+        if not silent:
+            time.sleep(0.1)
+            if current_resource:
+                prg = current_resource.get_progress()
+                percent = round(prg * 100.0, 1)
+                stat_str = str(percent)+"% - " + size_str(int(prg*current_resource.total_size)) + " of " + size_str(current_resource.total_size) + " - " +size_str(speed, "b")+"ps"
+                print("\r                                                                                  \rTransferring file "+syms[i]+" "+stat_str, end=" ")
+            else:
+                print("\r                                                                                  \rWaiting for transfer to start "+syms[i]+" ", end=" ")
+            sys.stdout.flush()
+            i = (i+1)%len(syms)
+
+    if current_resource.status != RNS.Resource.COMPLETE:
+        if silent:
+            print("The transfer failed")
+        else:
+            print("\r                                                            \rThe transfer failed")
+        exit(1)
+    else:
+        if silent:
+            print(str(file_path)+" copied to "+RNS.prettyhexrep(destination_hash))
+        else:
+            print("\r                                                                                  \r"+str(file)+" fetched from "+RNS.prettyhexrep(destination_hash))
+        link.teardown()
+        time.sleep(0.25)
+        exit(0)
+
+    link.teardown()
+    exit(0)
+
+
 def send(configdir, verbosity = 0, quietness = 0, destination = None, file = None, timeout = RNS.Transport.PATH_REQUEST_TIMEOUT, silent=False):
     global current_resource, resource_done, link, speed
     from tempfile import TemporaryFile
@@ -399,9 +651,8 @@ def main():
         parser.add_argument('-v', '--verbose', action='count', default=0, help="increase verbosity")
         parser.add_argument('-q', '--quiet', action='count', default=0, help="decrease verbosity")
         parser.add_argument("-S", '--silent', action='store_true', default=False, help="disable transfer progress output")
-        parser.add_argument('-p', '--print-identity', action='store_true', default=False, help="print identity and destination info and exit")
         parser.add_argument("-l", '--listen', action='store_true', default=False, help="listen for incoming transfer requests")
-        #parser.add_argument("-f", '--fetch', action='store_true', default=False, help="fetch file from remote listener")
+        parser.add_argument("-f", '--fetch', action='store_true', default=False, help="fetch file from remote listener instead of sending")
         parser.add_argument("-b", action='store', metavar="seconds", default=-1, help="announce interval, 0 to only announce at startup", type=int)
         parser.add_argument('-a', metavar="allowed_hash", dest="allowed", action='append', help="accept from this identity", type=str)
         parser.add_argument('-n', '--no-auth', action='store_true', default=False, help="accept files from anyone")
@@ -413,7 +664,7 @@ def main():
         args = parser.parse_args()
 
         if args.listen or args.print_identity:
-            receive(
+            listen(
                 configdir = args.config,
                 verbosity=args.verbose,
                 quietness=args.quiet,
@@ -424,6 +675,22 @@ def main():
                 announce=args.b,
             )
 
+        elif args.fetch:
+            if args.destination != None and args.file != None:
+                fetch(
+                    configdir = args.config,
+                    verbosity = args.verbose,
+                    quietness = args.quiet,
+                    destination = args.destination,
+                    file = args.file,
+                    timeout = args.w,
+                    silent = args.silent,
+                )
+            else:
+                print("")
+                parser.print_help()
+                print("")
+
         elif args.destination != None and args.file != None:
             send(
                 configdir = args.config,

docs/manual/_sources/using.rst.txt

@@ -179,28 +179,34 @@ When ``rnsd`` is running, it will keep all configured interfaces open, handle tr
 it is enabled, and allow any other programs to immediately utilise the
 Reticulum network it is configured for.
 
-You can even run multiple instances of rnsd with different configurations on
+You can even run multiple instances of ``rnsd`` with different configurations on
 the same system.
 
-.. code:: text
+**Usage Examples**
 
-  # Install Reticulum
+Run ``rnsd``:
-  pip3 install rns
-
-  # Run rnsd
-  rnsd
 
 .. code:: text
 
-  usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version]
+  $ rnsd
+
+  [2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnsd.py [-h] [--config CONFIG] [-v] [-q] [-s] [--exampleconfig] [--version]
 
   Reticulum Network Stack Daemon
 
-  optional arguments:
+  options:
     -h, --help       show this help message and exit
     --config CONFIG  path to alternative Reticulum config directory
     -v, --verbose
     -q, --quiet
+    -s, --service    rnsd is running as a service and should log to file
+    --exampleconfig  print verbose configuration example to stdout and exit
     --version        show program's version number and exit
 
 You can easily add ``rnsd`` as an always-on service by :ref:`configuring a service<using-systemd>`.
@@ -211,12 +217,14 @@ The rnstatus Utility
 Using the ``rnstatus`` utility, you can view the status of configured Reticulum
 interfaces, similar to the ``ifconfig`` program.
 
+**Usage Examples**
+
+Run ``rnstatus``:
+
 .. code:: text
 
-  # Run rnstatus
+  $ rnstatus
-  rnstatus
 
-  # Example output
   Shared Instance[37428]
      Status  : Up
      Serving : 1 program
@@ -249,17 +257,39 @@ interfaces, similar to the ``ifconfig`` program.
 
   Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running
 
+Filter output to only show some interfaces:
+
 .. code:: text
 
-  usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-v]
+  $ rnstatus rnode
+
+  RNodeInterface[RNode UHF]
+     Status  : Up
+     Mode    : Access Point
+     Rate    : 1.30 kbps
+     Access  : 64-bit IFAC by <…e702c42ba8>
+     Traffic : 8.49 KB↑
+               9.23 KB↓
+
+  Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-j] [-v] [filter]
 
   Reticulum Network Stack Status
 
-  optional arguments:
+  positional arguments:
+    filter           only display interfaces with names including filter
+
+  options:
     -h, --help       show this help message and exit
     --config CONFIG  path to alternative Reticulum config directory
     --version        show program's version number and exit
     -a, --all        show all interfaces
+    -j, --json       output in JSON format
     -v, --verbose
 
 
@@ -268,42 +298,67 @@ The rnid Utility
 
 With the ``rnid`` utility, you can generate, manage and view Reticulum Identities.
 The program can also calculate Destination hashes, and perform encryption and
-decryption of files. Using ``rnid``, it is possible to asymmetrically encrypt
+decryption of files.
-files and information for any destination hash, and also to create and verify
+
-cryptographic signatures.
+Using ``rnid``, it is possible to asymmetrically encrypt files and information for
+any Reticulum destination hash, and also to create and verify cryptographic signatures.
+
+**Usage Examples**
+
+Generate a new Identity:
 
 .. code:: text
 
-  # Generate a new Identity
+  $ rnid -g ./new_identity
-  rnid -g ./new_identity
 
-  # Display Identity key information
+Display Identity key information:
-  rnid -i ./new_identity -p
+
+.. code:: text
+
+  $ rnid -i ./new_identity -p
 
   Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id
   Public Key  : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e
   Private Key : Hidden
 
-  # Encrypt a file for an LXMF user
+Encrypt a file for an LXMF user:
-  rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
+
+.. code:: text
+
+  $ rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
 
   Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695>
   Encrypting my_file.txt
   File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe
 
-  # If the Identity for the destination is not already known,
+If the Identity for the destination is not already known, you can fetch it from the network by using the ``-R`` command-line option:
-  # you can fetch it from the network by using the -R option
+
-  rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt
+.. code:: text
+
+  $ rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt
 
   Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>...
   Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network
   Encrypting my_file.txt
   File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe
 
+Decrypt a file using the Reticulum Identity it was encrypted for:
+
 .. code:: text
 
-  usage: rnid [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] [-f] [-R] [-t seconds] [-p] [-P]
+  $ rnid -i ./my_identity -d my_file.txt.rfe
-              [--version]
+
+  Loaded Identity <2225fdeecaf6e2db4556c3c2d7637294> from ./my_identity
+  Decrypting ./my_file.txt.rfe...
+  File ./my_file.txt.rfe decrypted with <2225fdeecaf6e2db4556c3c2d7637294> to ./my_file.txt
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnid.py [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects]
+                 [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path]
+                 [-f] [-R] [-t seconds] [-p] [-P] [--version]
 
   Reticulum Identity & Encryption Utility
 
@@ -344,24 +399,29 @@ The rnpath Utility
 With the ``rnpath`` utility, you can look up and view paths for
 destinations on the Reticulum network.
 
+**Usage Examples**
+
+Resolve path to a destination:
+
 .. code:: text
 
-  # Run rnpath
+  $ rnpath c89b4da064bf66d280f0e4d8abfd9806
-  rnpath c89b4da064bf66d280f0e4d8abfd9806
 
-  # Example output
   Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965]
 
+**All Command-Line Options**
+
 .. code:: text
 
-  usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D] [-w seconds] [-v] [destination]
+  usage: rnpath.py [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D]
+                   [-w seconds] [-v] [destination]
 
   Reticulum Path Discovery Utility
 
   positional arguments:
     destination           hexadecimal hash of the destination
 
-  optional arguments:
+  options:
     -h, --help            show this help message and exit
     --config CONFIG       path to alternative Reticulum config directory
     --version             show program's version number and exit
@@ -381,16 +441,20 @@ to the ``ping`` program. Please note that probes will only be answered if the
 specified destination is configured to send proofs for received packets. Many
 destinations will not have this option enabled, and will not be probable.
 
+**Usage Examples**
+
+Probe a destination:
+
 .. code:: text
 
-  # Run rnprobe
+  $ rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
-  rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
 
-  # Example output
   Sent 16 byte probe to <2d03725b327348980d570f739a3a5708>
   Valid reply received from <2d03725b327348980d570f739a3a5708>
   Round-trip time is 38.469 milliseconds over 2 hops
 
+**All Command-Line Options**
+
 .. code:: text
 
   usage: rnprobe [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash]
@@ -414,20 +478,39 @@ The rncp Utility
 The ``rncp`` utility is a simple file transfer tool. Using it, you can transfer
 files through Reticulum.
 
-.. code:: text
+**Usage Examples**
 
-  # Run rncp on the receiving system, specifying which identities
+Run rncp on the receiving system, specifying which identities are allowed to send files:
-  # are allowed to send files
-  rncp --receive -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
-
-  # From another system, copy a file to the receiving system
-  rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
-
-You can specify as many allowed senders as needed, or complete disable authentication.
   
 .. code:: text
 
-  usage: rncp [-h] [--config path] [-v] [-q] [-p] [-r] [-b] [-a allowed_hash] [-n] [-w seconds] [--version] [file] [destination]
+  $ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
+
+You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities
+and simply running the program in listener mode:
+
+.. code:: text
+
+  $ rncp --listen
+
+From another system, copy a file to the receiving system:
+
+.. code:: text
+
+  $ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
+
+Or fetch a file from the remote system:
+
+.. code:: text
+
+  $ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rncp.py [-h] [--config path] [-v] [-q] [-S] [-l] [-f] [-b seconds]
+                 [-a allowed_hash] [-n] [-p] [-w seconds] [--version] [file] [destination]
 
   Reticulum File Transfer Utility
 
@@ -435,19 +518,20 @@ You can specify as many allowed senders as needed, or complete disable authentic
     file                  file to be transferred
     destination           hexadecimal hash of the receiver
 
-  optional arguments:
+  options:
     -h, --help            show this help message and exit
     --config path         path to alternative Reticulum config directory
     -v, --verbose         increase verbosity
     -q, --quiet           decrease verbosity
-    -p, --print-identity  print identity and destination info and exit
+    -S, --silent          disable transfer progress output
-    -r, --receive         wait for incoming files
+    -l, --listen          listen for incoming transfer requests
-    -b, --no-announce     don't announce at program start
+    -f, --fetch           fetch file from remote listener instead of sending
+    -b seconds            announce interval, 0 to only announce at startup
     -a allowed_hash       accept from this identity
-    -n, --no-auth         accept files from anyone
+    -n, --no-auth         accept files and fetches from anyone
+    -p, --print-identity  print identity and destination info and exit
     -w seconds            sender timeout before giving up
     --version             show program's version number and exit
-    -v, --verbose
 
 
 The rnx Utility
@@ -455,32 +539,43 @@ The rnx Utility
 
 The ``rnx`` utility is a basic remote command execution program. It allows you to
 execute commands on remote systems over Reticulum, and to view returned command
-output.
+output. For a fully interactive remote shell solution, be sure to also take a look
+at the `rnsh <https://github.com/acehoss/rnsh>`_ program.
+
+**Usage Examples**
+
+Run rnx on the listening system, specifying which identities are allowed to execute commands:
 
 .. code:: text
 
-  # Run rnx on the listening system, specifying which identities
+  $ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
-  # are allowed to execute commands
-  rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
 
-  # From another system, run a command 
+From another system, run a command on the remote:
-  rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
-
-  # Or enter the interactive mode pseudo-shell
-  rnx 7a55144adf826958a9529a3bcf08b149 -x
-
-  # The default identity file is stored in
-  # ~/.reticulum/identities/rnx, but you can use
-  # another one, which will be created if it does
-  # not already exist
-  rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
-
-You can specify as many allowed senders as needed, or completely disable authentication.
 
 .. code:: text
 
-  usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-a allowed_hash] [-n] [-N] [-d] [-m] [-w seconds] [-W seconds] [--stdin STDIN] [--stdout STDOUT] [--stderr STDERR] [--version]
+  $ rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
-             [destination] [command]
+
+Or enter the interactive mode pseudo-shell:
+
+.. code:: text
+
+  $ rnx 7a55144adf826958a9529a3bcf08b149 -x
+
+The default identity file is stored in ``~/.reticulum/identities/rnx``, but you can use
+another one, which will be created if it does not already exist 
+
+.. code:: text
+
+  $ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-n] [-N]
+             [-d] [-m] [-a allowed_hash] [-w seconds] [-W seconds] [--stdin STDIN]
+             [--stdout STDOUT] [--stderr STDERR] [--version] [destination] [command]
 
   Reticulum Remote Execution Utility
 
@@ -517,11 +612,19 @@ The rnodeconf Utility
 The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and
 to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices.
 
+**All Command-Line Options**
+
 .. code:: text
 
-  usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-C] [-N] [-T] [-b] [-B] [-p] [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [--version] [port]
+  usage: rnodeconf.py [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-e]
+                      [-E] [-C] [--baud-flash baud_flash] [-N] [-T] [-b] [-B] [-p] [-D i]
+                      [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate]
+                      [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [-P]
+                      [--trust-key hexbytes] [--version] [port]
 
-  RNode Configuration and firmware utility. This program allows you to change various settings and startup modes of RNode. It can also install, flash and update the firmware on supported devices.
+  RNode Configuration and firmware utility. This program allows you to change various
+  settings and startup modes of RNode. It can also install, flash and update the firmware
+  on supported devices.
 
   positional arguments:
     port                  serial port where RNode is attached
@@ -537,11 +640,14 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
     -e, --extract         Extract firmware from connected RNode for later use
     -E, --use-extracted   Use the extracted firmware for autoinstallation or update
     -C, --clear-cache     Clear locally cached firmware files
+    --baud-flash baud_flash
+                          Set specific baud rate when flashing device. Default is 921600
     -N, --normal          Switch device to normal mode
     -T, --tnc             Switch device to TNC mode
     -b, --bluetooth-on    Turn device bluetooth on
     -B, --bluetooth-off   Turn device bluetooth off
     -p, --bluetooth-pair  Put device into bluetooth pairing mode
+    -D i, --display i     Set display intensity (0-255)
     --freq Hz             Frequency in Hz for TNC mode
     --bw Hz               Bandwidth in Hz for TNC mode
     --txp dBm             TX power in dBm for TNC mode
@@ -550,6 +656,8 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
     --eeprom-backup       Backup EEPROM to file
     --eeprom-dump         Dump EEPROM to console
     --eeprom-wipe         Unlock and wipe EEPROM
+    -P, --public          Display public part of signing key
+    --trust-key hexbytes  Public key to trust for device verification
     --version             Print program version and exit
 
 For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>`

docs/manual/using.html

@@ -379,24 +379,27 @@ other programs, applications and services can utilise.</p>
 When <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> is running, it will keep all configured interfaces open, handle transport if
 it is enabled, and allow any other programs to immediately utilise the
 Reticulum network it is configured for.</p>
-<p>You can even run multiple instances of rnsd with different configurations on
+<p>You can even run multiple instances of <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> with different configurations on
 the same system.</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Install Reticulum
+<p><strong>Usage Examples</strong></p>
-pip3 install rns
+<p>Run <code class="docutils literal notranslate"><span class="pre">rnsd</span></code>:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnsd
 
-# Run rnsd
+[2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8
-rnsd
 </pre></div>
 </div>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version]
+<p><strong>All Command-Line Options</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnsd.py [-h] [--config CONFIG] [-v] [-q] [-s] [--exampleconfig] [--version]
 
 Reticulum Network Stack Daemon
 
-optional arguments:
+options:
   -h, --help       show this help message and exit
   --config CONFIG  path to alternative Reticulum config directory
   -v, --verbose
   -q, --quiet
+  -s, --service    rnsd is running as a service and should log to file
+  --exampleconfig  print verbose configuration example to stdout and exit
   --version        show program&#39;s version number and exit
 </pre></div>
 </div>
@@ -406,10 +409,10 @@ optional arguments:
 <h3>The rnstatus Utility<a class="headerlink" href="#the-rnstatus-utility" title="Permalink to this heading">#</a></h3>
 <p>Using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility, you can view the status of configured Reticulum
 interfaces, similar to the <code class="docutils literal notranslate"><span class="pre">ifconfig</span></code> program.</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnstatus
+<p><strong>Usage Examples</strong></p>
-rnstatus
+<p>Run <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code>:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus
 
-# Example output
 Shared Instance[37428]
    Status  : Up
    Serving : 1 program
@@ -443,15 +446,34 @@ RNodeInterface[RNode UHF]
 Reticulum Transport Instance &lt;5245a8efe1788c6a1cd36144a270e13b&gt; running
 </pre></div>
 </div>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-v]
+<p>Filter output to only show some interfaces:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnstatus rnode
+
+RNodeInterface[RNode UHF]
+   Status  : Up
+   Mode    : Access Point
+   Rate    : 1.30 kbps
+   Access  : 64-bit IFAC by &lt;…e702c42ba8&gt;
+   Traffic : 8.49 KB↑
+             9.23 KB↓
+
+Reticulum Transport Instance &lt;5245a8efe1788c6a1cd36144a270e13b&gt; running
+</pre></div>
+</div>
+<p><strong>All Command-Line Options</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-j] [-v] [filter]
 
 Reticulum Network Stack Status
 
-optional arguments:
+positional arguments:
+  filter           only display interfaces with names including filter
+
+options:
   -h, --help       show this help message and exit
   --config CONFIG  path to alternative Reticulum config directory
   --version        show program&#39;s version number and exit
   -a, --all        show all interfaces
+  -j, --json       output in JSON format
   -v, --verbose
 </pre></div>
 </div>
@@ -460,29 +482,32 @@ optional arguments:
 <h3>The rnid Utility<a class="headerlink" href="#the-rnid-utility" title="Permalink to this heading">#</a></h3>
 <p>With the <code class="docutils literal notranslate"><span class="pre">rnid</span></code> utility, you can generate, manage and view Reticulum Identities.
 The program can also calculate Destination hashes, and perform encryption and
-decryption of files. Using <code class="docutils literal notranslate"><span class="pre">rnid</span></code>, it is possible to asymmetrically encrypt
+decryption of files.</p>
-files and information for any destination hash, and also to create and verify
+<p>Using <code class="docutils literal notranslate"><span class="pre">rnid</span></code>, it is possible to asymmetrically encrypt files and information for
-cryptographic signatures.</p>
+any Reticulum destination hash, and also to create and verify cryptographic signatures.</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Generate a new Identity
+<p><strong>Usage Examples</strong></p>
-rnid -g ./new_identity
+<p>Generate a new Identity:</p>
-
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -g ./new_identity
-# Display Identity key information
+</pre></div>
-rnid -i ./new_identity -p
+</div>
+<p>Display Identity key information:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -i ./new_identity -p
 
 Loaded Identity &lt;984b74a3f768bef236af4371e6f248cd&gt; from new_id
 Public Key  : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e
 Private Key : Hidden
-
+</pre></div>
-# Encrypt a file for an LXMF user
+</div>
-rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
+<p>Encrypt a file for an LXMF user:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
 
 Recalled Identity &lt;bc7291552be7a58f361522990465165c&gt; for destination &lt;8dd57a738226809646089335a6b03695&gt;
 Encrypting my_file.txt
 File my_file.txt encrypted for &lt;bc7291552be7a58f361522990465165c&gt; to my_file.txt.rfe
-
+</pre></div>
-# If the Identity for the destination is not already known,
+</div>
-# you can fetch it from the network by using the -R option
+<p>If the Identity for the destination is not already known, you can fetch it from the network by using the <code class="docutils literal notranslate"><span class="pre">-R</span></code> command-line option:</p>
-rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt
 
 Requesting unknown Identity for &lt;30602def3b3506a28ed33db6f60cc6c9&gt;...
 Received Identity &lt;2b489d06eaf7c543808c76a5332a447d&gt; for destination &lt;30602def3b3506a28ed33db6f60cc6c9&gt; from the network
@@ -490,8 +515,18 @@ Encrypting my_file.txt
 File my_file.txt encrypted for &lt;2b489d06eaf7c543808c76a5332a447d&gt; to my_file.txt.rfe
 </pre></div>
 </div>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnid [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] [-f] [-R] [-t seconds] [-p] [-P]
+<p>Decrypt a file using the Reticulum Identity it was encrypted for:</p>
-            [--version]
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnid -i ./my_identity -d my_file.txt.rfe
+
+Loaded Identity &lt;2225fdeecaf6e2db4556c3c2d7637294&gt; from ./my_identity
+Decrypting ./my_file.txt.rfe...
+File ./my_file.txt.rfe decrypted with &lt;2225fdeecaf6e2db4556c3c2d7637294&gt; to ./my_file.txt
+</pre></div>
+</div>
+<p><strong>All Command-Line Options</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnid.py [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects]
+               [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path]
+               [-f] [-R] [-t seconds] [-p] [-P] [--version]
 
 Reticulum Identity &amp; Encryption Utility
 
@@ -531,21 +566,23 @@ options:
 <h3>The rnpath Utility<a class="headerlink" href="#the-rnpath-utility" title="Permalink to this heading">#</a></h3>
 <p>With the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility, you can look up and view paths for
 destinations on the Reticulum network.</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnpath
+<p><strong>Usage Examples</strong></p>
-rnpath c89b4da064bf66d280f0e4d8abfd9806
+<p>Resolve path to a destination:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnpath c89b4da064bf66d280f0e4d8abfd9806
 
-# Example output
 Path found, destination &lt;c89b4da064bf66d280f0e4d8abfd9806&gt; is 4 hops away via &lt;f53a1c4278e0726bb73fcc623d6ce763&gt; on TCPInterface[Testnet/dublin.connect.reticulum.network:4965]
 </pre></div>
 </div>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D] [-w seconds] [-v] [destination]
+<p><strong>All Command-Line Options</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnpath.py [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D]
+                 [-w seconds] [-v] [destination]
 
 Reticulum Path Discovery Utility
 
 positional arguments:
   destination           hexadecimal hash of the destination
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   --config CONFIG       path to alternative Reticulum config directory
   --version             show program&#39;s version number and exit
@@ -564,15 +601,16 @@ optional arguments:
 to the <code class="docutils literal notranslate"><span class="pre">ping</span></code> program. Please note that probes will only be answered if the
 specified destination is configured to send proofs for received packets. Many
 destinations will not have this option enabled, and will not be probable.</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnprobe
+<p><strong>Usage Examples</strong></p>
-rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
+<p>Probe a destination:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
 
-# Example output
 Sent 16 byte probe to &lt;2d03725b327348980d570f739a3a5708&gt;
 Valid reply received from &lt;2d03725b327348980d570f739a3a5708&gt;
 Round-trip time is 38.469 milliseconds over 2 hops
 </pre></div>
 </div>
+<p><strong>All Command-Line Options</strong></p>
 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnprobe [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash]
 
 Reticulum Probe Utility
@@ -593,16 +631,27 @@ optional arguments:
 <h3>The rncp Utility<a class="headerlink" href="#the-rncp-utility" title="Permalink to this heading">#</a></h3>
 <p>The <code class="docutils literal notranslate"><span class="pre">rncp</span></code> utility is a simple file transfer tool. Using it, you can transfer
 files through Reticulum.</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rncp on the receiving system, specifying which identities
+<p><strong>Usage Examples</strong></p>
-# are allowed to send files
+<p>Run rncp on the receiving system, specifying which identities are allowed to send files:</p>
-rncp --receive -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
-
-# From another system, copy a file to the receiving system
-rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
 </pre></div>
 </div>
-<p>You can specify as many allowed senders as needed, or complete disable authentication.</p>
+<p>You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rncp [-h] [--config path] [-v] [-q] [-p] [-r] [-b] [-a allowed_hash] [-n] [-w seconds] [--version] [file] [destination]
+and simply running the program in listener mode:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --listen
+</pre></div>
+</div>
+<p>From another system, copy a file to the receiving system:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
+</pre></div>
+</div>
+<p>Or fetch a file from the remote system:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
+</pre></div>
+</div>
+<p><strong>All Command-Line Options</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rncp.py [-h] [--config path] [-v] [-q] [-S] [-l] [-f] [-b seconds]
+               [-a allowed_hash] [-n] [-p] [-w seconds] [--version] [file] [destination]
 
 Reticulum File Transfer Utility
 
@@ -610,19 +659,20 @@ positional arguments:
   file                  file to be transferred
   destination           hexadecimal hash of the receiver
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   --config path         path to alternative Reticulum config directory
   -v, --verbose         increase verbosity
   -q, --quiet           decrease verbosity
-  -p, --print-identity  print identity and destination info and exit
+  -S, --silent          disable transfer progress output
-  -r, --receive         wait for incoming files
+  -l, --listen          listen for incoming transfer requests
-  -b, --no-announce     don&#39;t announce at program start
+  -f, --fetch           fetch file from remote listener instead of sending
+  -b seconds            announce interval, 0 to only announce at startup
   -a allowed_hash       accept from this identity
-  -n, --no-auth         accept files from anyone
+  -n, --no-auth         accept files and fetches from anyone
+  -p, --print-identity  print identity and destination info and exit
   -w seconds            sender timeout before giving up
   --version             show program&#39;s version number and exit
-  -v, --verbose
 </pre></div>
 </div>
 </section>
@@ -630,27 +680,30 @@ optional arguments:
 <h3>The rnx Utility<a class="headerlink" href="#the-rnx-utility" title="Permalink to this heading">#</a></h3>
 <p>The <code class="docutils literal notranslate"><span class="pre">rnx</span></code> utility is a basic remote command execution program. It allows you to
 execute commands on remote systems over Reticulum, and to view returned command
-output.</p>
+output. For a fully interactive remote shell solution, be sure to also take a look
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnx on the listening system, specifying which identities
+at the <a class="reference external" href="https://github.com/acehoss/rnsh">rnsh</a> program.</p>
-# are allowed to execute commands
+<p><strong>Usage Examples</strong></p>
-rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
+<p>Run rnx on the listening system, specifying which identities are allowed to execute commands:</p>
-
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
-# From another system, run a command
-rnx 7a55144adf826958a9529a3bcf08b149 &quot;cat /proc/cpuinfo&quot;
-
-# Or enter the interactive mode pseudo-shell
-rnx 7a55144adf826958a9529a3bcf08b149 -x
-
-# The default identity file is stored in
-# ~/.reticulum/identities/rnx, but you can use
-# another one, which will be created if it does
-# not already exist
-rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
 </pre></div>
 </div>
-<p>You can specify as many allowed senders as needed, or completely disable authentication.</p>
+<p>From another system, run a command on the remote:</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-a allowed_hash] [-n] [-N] [-d] [-m] [-w seconds] [-W seconds] [--stdin STDIN] [--stdout STDOUT] [--stderr STDERR] [--version]
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 &quot;cat /proc/cpuinfo&quot;
-           [destination] [command]
+</pre></div>
+</div>
+<p>Or enter the interactive mode pseudo-shell:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 -x
+</pre></div>
+</div>
+<p>The default identity file is stored in <code class="docutils literal notranslate"><span class="pre">~/.reticulum/identities/rnx</span></code>, but you can use
+another one, which will be created if it does not already exist</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
+</pre></div>
+</div>
+<p><strong>All Command-Line Options</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-n] [-N]
+           [-d] [-m] [-a allowed_hash] [-w seconds] [-W seconds] [--stdin STDIN]
+           [--stdout STDOUT] [--stderr STDERR] [--version] [destination] [command]
 
 Reticulum Remote Execution Utility
 
@@ -686,9 +739,16 @@ optional arguments:
 <h3>The rnodeconf Utility<a class="headerlink" href="#the-rnodeconf-utility" title="Permalink to this heading">#</a></h3>
 <p>The <code class="docutils literal notranslate"><span class="pre">rnodeconf</span></code> utility allows you to inspect and configure existing <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a>, and
 to create and provision new <a class="reference internal" href="hardware.html#rnode-main"><span class="std std-ref">RNodes</span></a> from any supported hardware devices.</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-C] [-N] [-T] [-b] [-B] [-p] [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [--version] [port]
+<p><strong>All Command-Line Options</strong></p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>usage: rnodeconf.py [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-e]
+                    [-E] [-C] [--baud-flash baud_flash] [-N] [-T] [-b] [-B] [-p] [-D i]
+                    [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate]
+                    [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [-P]
+                    [--trust-key hexbytes] [--version] [port]
 
-RNode Configuration and firmware utility. This program allows you to change various settings and startup modes of RNode. It can also install, flash and update the firmware on supported devices.
+RNode Configuration and firmware utility. This program allows you to change various
+settings and startup modes of RNode. It can also install, flash and update the firmware
+on supported devices.
 
 positional arguments:
   port                  serial port where RNode is attached
@@ -704,11 +764,14 @@ options:
   -e, --extract         Extract firmware from connected RNode for later use
   -E, --use-extracted   Use the extracted firmware for autoinstallation or update
   -C, --clear-cache     Clear locally cached firmware files
+  --baud-flash baud_flash
+                        Set specific baud rate when flashing device. Default is 921600
   -N, --normal          Switch device to normal mode
   -T, --tnc             Switch device to TNC mode
   -b, --bluetooth-on    Turn device bluetooth on
   -B, --bluetooth-off   Turn device bluetooth off
   -p, --bluetooth-pair  Put device into bluetooth pairing mode
+  -D i, --display i     Set display intensity (0-255)
   --freq Hz             Frequency in Hz for TNC mode
   --bw Hz               Bandwidth in Hz for TNC mode
   --txp dBm             TX power in dBm for TNC mode
@@ -717,6 +780,8 @@ options:
   --eeprom-backup       Backup EEPROM to file
   --eeprom-dump         Dump EEPROM to console
   --eeprom-wipe         Unlock and wipe EEPROM
+  -P, --public          Display public part of signing key
+  --trust-key hexbytes  Public key to trust for device verification
   --version             Print program version and exit
 </pre></div>
 </div>

docs/source/using.rst

@@ -179,28 +179,34 @@ When ``rnsd`` is running, it will keep all configured interfaces open, handle tr
 it is enabled, and allow any other programs to immediately utilise the
 Reticulum network it is configured for.
 
-You can even run multiple instances of rnsd with different configurations on
+You can even run multiple instances of ``rnsd`` with different configurations on
 the same system.
 
-.. code:: text
+**Usage Examples**
 
-  # Install Reticulum
+Run ``rnsd``:
-  pip3 install rns
-
-  # Run rnsd
-  rnsd
 
 .. code:: text
 
-  usage: rnsd [-h] [--config CONFIG] [-v] [-q] [--version]
+  $ rnsd
+
+  [2023-08-18 17:59:56] [Notice] Started rnsd version 0.5.8
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnsd.py [-h] [--config CONFIG] [-v] [-q] [-s] [--exampleconfig] [--version]
 
   Reticulum Network Stack Daemon
 
-  optional arguments:
+  options:
     -h, --help       show this help message and exit
     --config CONFIG  path to alternative Reticulum config directory
     -v, --verbose
     -q, --quiet
+    -s, --service    rnsd is running as a service and should log to file
+    --exampleconfig  print verbose configuration example to stdout and exit
     --version        show program's version number and exit
 
 You can easily add ``rnsd`` as an always-on service by :ref:`configuring a service<using-systemd>`.
@@ -211,12 +217,14 @@ The rnstatus Utility
 Using the ``rnstatus`` utility, you can view the status of configured Reticulum
 interfaces, similar to the ``ifconfig`` program.
 
+**Usage Examples**
+
+Run ``rnstatus``:
+
 .. code:: text
 
-  # Run rnstatus
+  $ rnstatus
-  rnstatus
 
-  # Example output
   Shared Instance[37428]
      Status  : Up
      Serving : 1 program
@@ -249,17 +257,39 @@ interfaces, similar to the ``ifconfig`` program.
 
   Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running
 
+Filter output to only show some interfaces:
+
 .. code:: text
 
-  usage: rnstatus [-h] [--config CONFIG] [--version] [-a] [-v]
+  $ rnstatus rnode
+
+  RNodeInterface[RNode UHF]
+     Status  : Up
+     Mode    : Access Point
+     Rate    : 1.30 kbps
+     Access  : 64-bit IFAC by <…e702c42ba8>
+     Traffic : 8.49 KB↑
+               9.23 KB↓
+
+  Reticulum Transport Instance <5245a8efe1788c6a1cd36144a270e13b> running
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnstatus.py [-h] [--config CONFIG] [--version] [-a] [-j] [-v] [filter]
 
   Reticulum Network Stack Status
 
-  optional arguments:
+  positional arguments:
+    filter           only display interfaces with names including filter
+
+  options:
     -h, --help       show this help message and exit
     --config CONFIG  path to alternative Reticulum config directory
     --version        show program's version number and exit
     -a, --all        show all interfaces
+    -j, --json       output in JSON format
     -v, --verbose
 
 
@@ -268,42 +298,67 @@ The rnid Utility
 
 With the ``rnid`` utility, you can generate, manage and view Reticulum Identities.
 The program can also calculate Destination hashes, and perform encryption and
-decryption of files. Using ``rnid``, it is possible to asymmetrically encrypt
+decryption of files.
-files and information for any destination hash, and also to create and verify
+
-cryptographic signatures.
+Using ``rnid``, it is possible to asymmetrically encrypt files and information for
+any Reticulum destination hash, and also to create and verify cryptographic signatures.
+
+**Usage Examples**
+
+Generate a new Identity:
 
 .. code:: text
 
-  # Generate a new Identity
+  $ rnid -g ./new_identity
-  rnid -g ./new_identity
 
-  # Display Identity key information
+Display Identity key information:
-  rnid -i ./new_identity -p
+
+.. code:: text
+
+  $ rnid -i ./new_identity -p
 
   Loaded Identity <984b74a3f768bef236af4371e6f248cd> from new_id
   Public Key  : 0f4259fef4521ab75a3409e353fe9073eb10783b4912a6a9937c57bf44a62c1e
   Private Key : Hidden
 
-  # Encrypt a file for an LXMF user
+Encrypt a file for an LXMF user:
-  rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
+
+.. code:: text
+
+  $ rnid -i 8dd57a738226809646089335a6b03695 -e my_file.txt
 
   Recalled Identity <bc7291552be7a58f361522990465165c> for destination <8dd57a738226809646089335a6b03695>
   Encrypting my_file.txt
   File my_file.txt encrypted for <bc7291552be7a58f361522990465165c> to my_file.txt.rfe
 
-  # If the Identity for the destination is not already known,
+If the Identity for the destination is not already known, you can fetch it from the network by using the ``-R`` command-line option:
-  # you can fetch it from the network by using the -R option
+
-  rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt
+.. code:: text
+
+  $ rnid -R -i 30602def3b3506a28ed33db6f60cc6c9 -e my_file.txt
 
   Requesting unknown Identity for <30602def3b3506a28ed33db6f60cc6c9>...
   Received Identity <2b489d06eaf7c543808c76a5332a447d> for destination <30602def3b3506a28ed33db6f60cc6c9> from the network
   Encrypting my_file.txt
   File my_file.txt encrypted for <2b489d06eaf7c543808c76a5332a447d> to my_file.txt.rfe
 
+Decrypt a file using the Reticulum Identity it was encrypted for:
+
 .. code:: text
 
-  usage: rnid [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects] [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path] [-f] [-R] [-t seconds] [-p] [-P]
+  $ rnid -i ./my_identity -d my_file.txt.rfe
-              [--version]
+
+  Loaded Identity <2225fdeecaf6e2db4556c3c2d7637294> from ./my_identity
+  Decrypting ./my_file.txt.rfe...
+  File ./my_file.txt.rfe decrypted with <2225fdeecaf6e2db4556c3c2d7637294> to ./my_file.txt
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnid.py [-h] [--config path] [-i identity] [-g path] [-v] [-q] [-a aspects]
+                 [-H aspects] [-e path] [-d path] [-s path] [-V path] [-r path] [-w path]
+                 [-f] [-R] [-t seconds] [-p] [-P] [--version]
 
   Reticulum Identity & Encryption Utility
 
@@ -344,24 +399,29 @@ The rnpath Utility
 With the ``rnpath`` utility, you can look up and view paths for
 destinations on the Reticulum network.
 
+**Usage Examples**
+
+Resolve path to a destination:
+
 .. code:: text
 
-  # Run rnpath
+  $ rnpath c89b4da064bf66d280f0e4d8abfd9806
-  rnpath c89b4da064bf66d280f0e4d8abfd9806
 
-  # Example output
   Path found, destination <c89b4da064bf66d280f0e4d8abfd9806> is 4 hops away via <f53a1c4278e0726bb73fcc623d6ce763> on TCPInterface[Testnet/dublin.connect.reticulum.network:4965]
 
+**All Command-Line Options**
+
 .. code:: text
 
-  usage: rnpath [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D] [-w seconds] [-v] [destination]
+  usage: rnpath.py [-h] [--config CONFIG] [--version] [-t] [-r] [-d] [-D]
+                   [-w seconds] [-v] [destination]
 
   Reticulum Path Discovery Utility
 
   positional arguments:
     destination           hexadecimal hash of the destination
 
-  optional arguments:
+  options:
     -h, --help            show this help message and exit
     --config CONFIG       path to alternative Reticulum config directory
     --version             show program's version number and exit
@@ -381,16 +441,20 @@ to the ``ping`` program. Please note that probes will only be answered if the
 specified destination is configured to send proofs for received packets. Many
 destinations will not have this option enabled, and will not be probable.
 
+**Usage Examples**
+
+Probe a destination:
+
 .. code:: text
 
-  # Run rnprobe
+  $ rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
-  rnprobe example_utilities.echo.request 2d03725b327348980d570f739a3a5708
 
-  # Example output
   Sent 16 byte probe to <2d03725b327348980d570f739a3a5708>
   Valid reply received from <2d03725b327348980d570f739a3a5708>
   Round-trip time is 38.469 milliseconds over 2 hops
 
+**All Command-Line Options**
+
 .. code:: text
 
   usage: rnprobe [-h] [--config CONFIG] [--version] [-v] [full_name] [destination_hash]
@@ -414,20 +478,39 @@ The rncp Utility
 The ``rncp`` utility is a simple file transfer tool. Using it, you can transfer
 files through Reticulum.
 
-.. code:: text
+**Usage Examples**
 
-  # Run rncp on the receiving system, specifying which identities
+Run rncp on the receiving system, specifying which identities are allowed to send files:
-  # are allowed to send files
-  rncp --receive -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
-
-  # From another system, copy a file to the receiving system
-  rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
-
-You can specify as many allowed senders as needed, or complete disable authentication.
   
 .. code:: text
 
-  usage: rncp [-h] [--config path] [-v] [-q] [-p] [-r] [-b] [-a allowed_hash] [-n] [-w seconds] [--version] [file] [destination]
+  $ rncp --listen -a 1726dbad538775b5bf9b0ea25a4079c8 -a c50cc4e4f7838b6c31f60ab9032cbc62
+
+You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities
+and simply running the program in listener mode:
+
+.. code:: text
+
+  $ rncp --listen
+
+From another system, copy a file to the receiving system:
+
+.. code:: text
+
+  $ rncp ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
+
+Or fetch a file from the remote system:
+
+.. code:: text
+
+  $ rncp --fetch ~/path/to/file.tgz 73cbd378bb0286ed11a707c13447bb1e
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rncp.py [-h] [--config path] [-v] [-q] [-S] [-l] [-f] [-b seconds]
+                 [-a allowed_hash] [-n] [-p] [-w seconds] [--version] [file] [destination]
 
   Reticulum File Transfer Utility
 
@@ -435,19 +518,20 @@ You can specify as many allowed senders as needed, or complete disable authentic
     file                  file to be transferred
     destination           hexadecimal hash of the receiver
 
-  optional arguments:
+  options:
     -h, --help            show this help message and exit
     --config path         path to alternative Reticulum config directory
     -v, --verbose         increase verbosity
     -q, --quiet           decrease verbosity
-    -p, --print-identity  print identity and destination info and exit
+    -S, --silent          disable transfer progress output
-    -r, --receive         wait for incoming files
+    -l, --listen          listen for incoming transfer requests
-    -b, --no-announce     don't announce at program start
+    -f, --fetch           fetch file from remote listener instead of sending
+    -b seconds            announce interval, 0 to only announce at startup
     -a allowed_hash       accept from this identity
-    -n, --no-auth         accept files from anyone
+    -n, --no-auth         accept files and fetches from anyone
+    -p, --print-identity  print identity and destination info and exit
     -w seconds            sender timeout before giving up
     --version             show program's version number and exit
-    -v, --verbose
 
 
 The rnx Utility
@@ -455,32 +539,43 @@ The rnx Utility
 
 The ``rnx`` utility is a basic remote command execution program. It allows you to
 execute commands on remote systems over Reticulum, and to view returned command
-output.
+output. For a fully interactive remote shell solution, be sure to also take a look
+at the `rnsh <https://github.com/acehoss/rnsh>`_ program.
+
+**Usage Examples**
+
+Run rnx on the listening system, specifying which identities are allowed to execute commands:
 
 .. code:: text
 
-  # Run rnx on the listening system, specifying which identities
+  $ rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
-  # are allowed to execute commands
-  rnx --listen -a 941bed5e228775e5a8079fc38b1ccf3f -a 1b03013c25f1c2ca068a4f080b844a10
 
-  # From another system, run a command 
+From another system, run a command on the remote:
-  rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
-
-  # Or enter the interactive mode pseudo-shell
-  rnx 7a55144adf826958a9529a3bcf08b149 -x
-
-  # The default identity file is stored in
-  # ~/.reticulum/identities/rnx, but you can use
-  # another one, which will be created if it does
-  # not already exist
-  rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
-
-You can specify as many allowed senders as needed, or completely disable authentication.
 
 .. code:: text
 
-  usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-a allowed_hash] [-n] [-N] [-d] [-m] [-w seconds] [-W seconds] [--stdin STDIN] [--stdout STDOUT] [--stderr STDERR] [--version]
+  $ rnx 7a55144adf826958a9529a3bcf08b149 "cat /proc/cpuinfo"
-             [destination] [command]
+
+Or enter the interactive mode pseudo-shell:
+
+.. code:: text
+
+  $ rnx 7a55144adf826958a9529a3bcf08b149 -x
+
+The default identity file is stored in ``~/.reticulum/identities/rnx``, but you can use
+another one, which will be created if it does not already exist 
+
+.. code:: text
+
+  $ rnx 7a55144adf826958a9529a3bcf08b149 -i /path/to/identity -x
+
+**All Command-Line Options**
+
+.. code:: text
+
+  usage: rnx [-h] [--config path] [-v] [-q] [-p] [-l] [-i identity] [-x] [-b] [-n] [-N]
+             [-d] [-m] [-a allowed_hash] [-w seconds] [-W seconds] [--stdin STDIN]
+             [--stdout STDOUT] [--stderr STDERR] [--version] [destination] [command]
 
   Reticulum Remote Execution Utility
 
@@ -517,11 +612,19 @@ The rnodeconf Utility
 The ``rnodeconf`` utility allows you to inspect and configure existing :ref:`RNodes<rnode-main>`, and
 to create and provision new :ref:`RNodes<rnode-main>` from any supported hardware devices.
 
+**All Command-Line Options**
+
 .. code:: text
 
-  usage: rnodeconf [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-C] [-N] [-T] [-b] [-B] [-p] [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate] [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [--version] [port]
+  usage: rnodeconf.py [-h] [-i] [-a] [-u] [-U] [--fw-version version] [--nocheck] [-e]
+                      [-E] [-C] [--baud-flash baud_flash] [-N] [-T] [-b] [-B] [-p] [-D i]
+                      [--freq Hz] [--bw Hz] [--txp dBm] [--sf factor] [--cr rate]
+                      [--eeprom-backup] [--eeprom-dump] [--eeprom-wipe] [-P]
+                      [--trust-key hexbytes] [--version] [port]
 
-  RNode Configuration and firmware utility. This program allows you to change various settings and startup modes of RNode. It can also install, flash and update the firmware on supported devices.
+  RNode Configuration and firmware utility. This program allows you to change various
+  settings and startup modes of RNode. It can also install, flash and update the firmware
+  on supported devices.
 
   positional arguments:
     port                  serial port where RNode is attached
@@ -537,11 +640,14 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
     -e, --extract         Extract firmware from connected RNode for later use
     -E, --use-extracted   Use the extracted firmware for autoinstallation or update
     -C, --clear-cache     Clear locally cached firmware files
+    --baud-flash baud_flash
+                          Set specific baud rate when flashing device. Default is 921600
     -N, --normal          Switch device to normal mode
     -T, --tnc             Switch device to TNC mode
     -b, --bluetooth-on    Turn device bluetooth on
     -B, --bluetooth-off   Turn device bluetooth off
     -p, --bluetooth-pair  Put device into bluetooth pairing mode
+    -D i, --display i     Set display intensity (0-255)
     --freq Hz             Frequency in Hz for TNC mode
     --bw Hz               Bandwidth in Hz for TNC mode
     --txp dBm             TX power in dBm for TNC mode
@@ -550,6 +656,8 @@ to create and provision new :ref:`RNodes<rnode-main>` from any supported hardwar
     --eeprom-backup       Backup EEPROM to file
     --eeprom-dump         Dump EEPROM to console
     --eeprom-wipe         Unlock and wipe EEPROM
+    -P, --public          Display public part of signing key
+    --trust-key hexbytes  Public key to trust for device verification
     --version             Print program version and exit
 
 For more information on how to create your own RNodes, please read the :ref:`Creating RNodes<rnode-creating>`