View source for Connecting to ScotMesh

This page assumes you know nothing. If you have never heard of Reticulum, start with [[What Reticulum is|what Reticulum is]] and come back.

== What you need ==

* '''A computer or a phone.''' Windows, macOS, Linux or Android all work.
* '''An internet connection''' — home broadband, wifi or mobile data. Any of them.
* '''No radio, no hardware, no money.''' You do not need a LoRa device to join. That comes later if you want it.
* '''No account.''' There is nothing to sign up for, nobody to ask, and no approval step. This is not politeness — the network has no mechanism for registration.

== What you are actually doing ==

Reticulum is a piece of software that runs on your machine. On its own it can only talk to things on your local network, which is probably nothing.

ScotMesh runs a machine that is permanently online and connected onward to the wider Reticulum network. '''Connecting means telling your Reticulum where to find ours''' — one small block of configuration giving it a hostname and a port. After that your machine can reach everything our machine can reach.

The thing you add is called an '''interface'''. An interface is simply a way of reaching other Reticulum machines: over the internet, over a radio, over a cable. You can have several at once, and Reticulum will use whichever is working.

== Two ways to do this ==

{| class="wikitable"
|-
!  
! Use this if
|-
| '''[[#Out of the box: an app|Out of the box: an app]]'''
| You want it working in five minutes and never want to see a config file. Recommended.
|-
| '''[[#Full installation: Reticulum yourself|Full installation]]'''
| You want to run it on a server, a Raspberry Pi, or anything without a screen; or you simply prefer to understand what you are running.
|}

Both end up in the same place. The app does the same thing as the full installation, with the config file hidden from you.

-----

== Out of the box: an app ==

These apps have Reticulum built in. You install one like any other program, tell it where ScotMesh is, and you are connected; there is no config file to see. Pick by what you have:

{| class="wikitable"
! App !! Runs on !! Get it
|-
| '''MeshChatX''' || Windows, macOS, Linux, Android || [https://meshchatx.com meshchatx.com]
|-
| '''Sideband''' || Android, Windows, macOS, Linux || [https://github.com/markqvist/Sideband/releases GitHub releases]
|-
| '''Retichat''' or '''Columba''' || iPhone || [https://apps.apple.com/us/app/retichat/id6762225314 App Store], [https://github.com/torlando-tech/Columba-iOS GitHub]
|}

=== MeshChatX (recommended) ===

[https://meshchatx.com MeshChatX] does messaging, files, voice calls, chat rooms and Nomad Network pages, and runs on everything but iPhone. If in doubt, use this.

==== 1. Download it ====

Go to the [https://github.com/Quad4-Software/MeshChatX/releases releases page] and pick the file for your system:

{| class="wikitable"
|-
! System
! File to download
|-
| Windows
| the <code>win-installer.exe</code>
|-
| macOS, Apple Silicon (M1 and later)
| the <code>mac-arm64.dmg</code>
|-
| macOS, Intel
| the <code>mac-x64.dmg</code>
|-
| Linux
| the <code>.deb</code> on Debian or Ubuntu, otherwise the <code>.AppImage</code>
|-
| Android
| the <code>android-universal.apk</code>
|}

==== 2. Install and open it ====

Normal installation. On Android you will need to allow installing from outside the Play Store. On macOS you may need to right-click the app and choose Open the first time, because it is not from the App Store.

==== 3. Add ScotMesh ====

# Open the '''Interfaces''' page.
# Click '''Add Interface'''.
# For the type, choose '''TCPClientInterface'''. (“TCP client” just means it reaches out over the internet to a machine that is listening.)
# '''Target Host''': <code>rns.scotmesh.net</code>
# '''Target Port''': <code>4242</code>
# Save. Restart the app when it asks.

Within a few seconds the interface should show as connected. Skip to [[#Did it work?|did it work]].

=== Sideband ===

[https://github.com/markqvist/Sideband Sideband] is a messaging client by Reticulum's author; best on Android, especially with an [[RNode]] paired over Bluetooth.

# Install it from the [https://github.com/markqvist/Sideband/releases releases page] (an <code>.apk</code> for Android; packages for Windows, macOS and Linux).
# Open '''Settings''', then '''Connectivity'''.
# Turn on '''Connect via TCP''' and enter host <code>rns.scotmesh.net</code>, port <code>4242</code>.
# Go back; Sideband reconnects by itself. Your address and an announce button are on the main screen.

=== iPhone ===

Reticulum on iPhone is newer than on the other platforms. [https://apps.apple.com/us/app/retichat/id6762225314 Retichat] is on the App Store and [https://github.com/torlando-tech/Columba-iOS Columba] is on GitHub; both are messaging clients. In either, add a connection of type TCP with host <code>rns.scotmesh.net</code> and port <code>4242</code>. We have not used them ourselves yet; if you do, tell us how it went.

-----

== Full installation: Reticulum yourself ==

=== 1. Install it ===

Reticulum is a Python program. If you have Python and <code>pip</code>, this is one command in a terminal:

<syntaxhighlight lang="text">pip install rns</syntaxhighlight>
'''On Ubuntu 24.04 and other recent Linux systems''' that command will refuse, with a message about an “externally managed environment”. This is deliberate on their part, not an error you caused. Use a virtual environment instead:

<syntaxhighlight lang="text">sudo apt install python3-venv
python3 -m venv ~/reticulum
~/reticulum/bin/pip install rns</syntaxhighlight>
Your commands then become <code>~/reticulum/bin/rnsd</code> and <code>~/reticulum/bin/rnstatus</code> instead of plain <code>rnsd</code> and <code>rnstatus</code>.

'''On Android or iPhone''', do not do this — install one of the apps above instead. Running Reticulum by hand on Android needs Termux and is a lot of work for no gain.

=== 2. Run it once, to create the config file ===

'''The config file does not exist yet.''' This trips people up: guides tell you to edit it, and you go looking, and there is nothing there. Reticulum writes it the first time it starts.

<syntaxhighlight lang="text">rnsd</syntaxhighlight>
It will print a few lines and keep running. Leave it a few seconds, then stop it with '''Ctrl+C'''. It has now created a config file and a couple of folders.

=== 3. Find the config file ===

{| class="wikitable"
|-
! System
! Where it is
|-
| Linux, macOS
| <code>~/.reticulum/config</code>
|-
| Windows
| <code>C:\Users\&lt;you&gt;\.reticulum\config</code>
|}

The folder starts with a dot, which means it is hidden. On Linux and macOS use <code>ls -a</code> to see it, or just open the path directly. On Windows, paste the path into Explorer's address bar.

It is a plain text file with no extension. Open it with any text editor — <code>nano ~/.reticulum/config</code> on Linux, TextEdit on macOS, Notepad on Windows.

=== 4. Look at what is already there ===

Near the bottom you will find a section that looks like this:

<syntaxhighlight lang="text">[interfaces]

  [[Default Interface]]
    type = AutoInterface
    enabled = Yes</syntaxhighlight>
That is one interface already configured. <code>AutoInterface</code> finds other Reticulum machines on your own local network, which is useful but probably finds nothing today.

'''Note the indentation.''' <code>[interfaces]</code> is at the left margin, <code><nowiki>[[Default Interface]]</nowiki></code> is indented two spaces, and its settings are indented four. This matters — the file will not load correctly if you get it wrong, and Reticulum will silently ignore the interface.

=== 5. Add ScotMesh ===

Underneath the existing interface, still inside <code>[interfaces]</code>, add:

<syntaxhighlight lang="text">  [[ScotMesh Backbone]]
    type = TCPClientInterface
    enabled = yes
    target_host = rns.scotmesh.net
    target_port = 4242</syntaxhighlight>
So the whole section now reads:

<syntaxhighlight lang="text">[interfaces]

  [[Default Interface]]
    type = AutoInterface
    enabled = Yes

  [[ScotMesh Backbone]]
    type = TCPClientInterface
    enabled = yes
    target_host = rns.scotmesh.net
    target_port = 4242</syntaxhighlight>
The name in double brackets is yours to choose — it is only a label. Save the file.

=== 6. Start it again ===

<syntaxhighlight lang="text">rnsd</syntaxhighlight>
Leave this running. Reticulum only works while it is running — close the terminal and you are off the network. See [[#Keeping it running|keeping it running]] for how to make it start by itself.

-----

== Did it work? ==

Open a ''second'' terminal, leaving <code>rnsd</code> running in the first, and run:

<syntaxhighlight lang="text">rnstatus</syntaxhighlight>
You are looking for something like:

<syntaxhighlight lang="text">TCPInterface[ScotMesh Backbone/rns.scotmesh.net:4242]
   Status  : Up
   Traffic : ↑1.2 KB  ↓14.8 KB</syntaxhighlight>
'''Status: Up''' means connected. Traffic counters climbing means the network is talking to you. If it says Down, see below.

To confirm you can actually reach something, ask for a path to our chat hub:

<syntaxhighlight lang="text">rnpath -t 004e5a15da221d9a236b0e8d74195f13</syntaxhighlight>
A reply mentioning a number of hops means you are properly on the network. That long string is a '''destination hash''' — Reticulum's equivalent of an address, except it is derived from a cryptographic key rather than handed out by anybody.

== Now what? ==

Being connected is not obviously exciting on its own. Things you can now do:

* '''Join the chat room.''' Our hub hosts a room called <code>scotmesh</code>. See [[The chat room|the chat room]].
* '''Message people.''' Install a client and you have an address others can reach. See [[Choosing a client|choosing a client]].
* '''Browse pages hosted inside the network.''' See [[Nomad Network]].
* '''Send and receive messages while offline''', via our [[Propagation node|propagation node]].

Give it a few minutes before judging it. Other nodes announce themselves periodically, so your view of the network fills in gradually rather than instantly.

== Keeping it running ==

On Linux, run it as a service so it survives a reboot:

<syntaxhighlight lang="text">sudo tee /etc/systemd/system/rnsd.service &gt;/dev/null &lt;&lt;'EOF'
[Unit]
Description=Reticulum Network Stack Daemon
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/usr/local/bin/rnsd
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now rnsd</syntaxhighlight>
Replace <code>YOUR_USERNAME</code> with your own, and check the <code>ExecStart</code> path matches where <code>rnsd</code> actually is — <code>which rnsd</code> will tell you, and it will be different if you used a virtual environment.

On Windows and macOS, or if you used MeshChatX, just leave the application running.

-----

== Other ways in ==

Only read these if the ordinary route above does not suit you.

=== Behind CGNAT, or a firewall you do not control ===

Mobile networks, student halls and workplace wifi usually still allow outbound TCP, so try the normal route first. If it is blocked, I2P will almost certainly get through, because it needs no inbound connections at either end.

Install an I2P router first:

<syntaxhighlight lang="text">sudo apt install i2pd
sudo systemctl enable --now i2pd</syntaxhighlight>
Then add, alongside your other interfaces:

<syntaxhighlight lang="text">  [[ScotMesh I2P]]
    type = I2PInterface
    enabled = yes
    peers = a3pswrtvpuro62ijhb7lwdt2n6aqgajglof27ynbonynmolzlz7q.b32.i2p</syntaxhighlight>
'''Be patient.''' I2P builds tunnels before it can carry anything, which takes five to ten minutes on a fresh install. The interface showing Down for that long is expected, not broken. It is slower than TCP; that is the trade for getting through.

=== Over LoRa radio ===

ScotMesh's first LoRa gateway is on air in Fife; if you are within range of it, or of another ScotMesh relay, a radio with the right settings reaches the whole network with no internet at all. Coverage is small so far, so this section also covers using LoRa between your own machines.

You need an [[RNode]]: a supported LoRa board flashed with RNode firmware. It is not a Meshtastic or MeshCore radio, though a lot of the same hardware can be reflashed into one.

<syntaxhighlight lang="text">  [[RNode LoRa]]
    type = RNodeInterface
    enabled = yes
    port = /dev/ttyUSB0
    frequency = 869462500
    bandwidth = 125000
    txpower = 22
    spreadingfactor = 9
    codingrate = 5</syntaxhighlight>
Two things that catch everyone:

* '''Every radio must match exactly''' on frequency, bandwidth, spreading factor and coding rate. These are not negotiated. A radio with different settings is not “weakly connected” — it is completely deaf to you, with no error to tell you so. If two of your own radios cannot hear each other, check these four lines before anything else.
* '''Transmit time is legally limited''' in the licence-free bands, and it is easy to exceed. Set <code>airtime_limit_short</code> and <code>airtime_limit_long</code>. If you are a licensed amateur operating under your callsign, set <code>id_callsign</code> and <code>id_interval</code> too.

Higher spreading factors reach further and are dramatically slower — SF12 may carry a few hundred bits per second. Do not reach for it by default.

=== Another machine on your network already has Reticulum ===

Then you need no configuration at all. The <code>Default Interface</code> already in your config finds it automatically. This is the tidy way to share one radio: put the LoRa hardware on a Raspberry Pi, and everything else in the house reaches the mesh through it.

-----

== When it does not work ==

{| class="wikitable"
|-
! What you see
! What it usually means
|-
| No config file to edit
| You have not run <code>rnsd</code> yet. It creates the file on first start.
|-
| <code>rnsd: command not found</code>
| Installed into a virtual environment — use the full path, e.g. <code>~/reticulum/bin/rnsd</code>.
|-
| <code>error: externally-managed-environment</code>
| Expected on modern Linux. Use the virtual environment method above.
|-
| Interface missing from <code>rnstatus</code>
| Indentation is wrong, or it is outside the <code>[interfaces]</code> section.
|-
| Status: Down on the TCP interface
| No route out, or a typo in the hostname. Check with <code>ping rns.scotmesh.net</code>.
|-
| Status: Down on I2P, for ages
| Normal for the first five to ten minutes.
|-
| Up, but no traffic at all
| Fine for the first minute or two. Longer than that, something upstream is filtering.
|-
| No path to a destination
| Wait a couple of minutes. Nodes announce periodically and you cannot reach what has not announced.
|-
| A client hangs on “securing link”
| See [[Known bugs and workarounds|known bugs]] — this one has bitten us.
|-
| Two LoRa radios cannot hear each other
| Mismatched frequency, bandwidth, spreading factor or coding rate.
|}

== Going further: carry traffic for other people ==

Everything above makes you a '''client''': you use the network, but nothing routes through you. A '''transport node''' also relays other people's traffic and announces the paths it knows.

This is how the network stops depending on any one machine — including ours. If your computer is always on and has a decent connection, it is worth doing.

The switch itself is one line, in the <code>[reticulum]</code> section at the top of the config:

<syntaxhighlight lang="text">[reticulum]
  enable_transport = Yes</syntaxhighlight>
Two things matter beyond that. Others must be able to '''reach''' you, which means either opening a port with a <code>TCPServerInterface</code> or using I2P if you cannot. And you must '''announce often enough to be found''' — the default is six hours, which in practice means nobody discovers you at all.

The full walkthrough is in [[Running your own transport node|running your own transport node]]. If you set one up, tell us and we will peer with you.


[[Category:Getting Started]]