View source for ScotMesh microReticulum

'''ScotMesh microReticulum''' is our build of [https://github.com/attermann/microReticulum_Firmware attermann's microReticulum firmware]. It turns a LoRa board into its own Reticulum transport node, so a board on a hill or a roof can relay for the mesh with no Raspberry Pi. On top of upstream it adds:

* the SenseCAP Solar Node P1;
* battery reporting;
* a NomadNet page you can manage the node from over the mesh;
* a small telemetry API;
* a position on [https://rmap.world rmap.world].

Source: [https://github.com/A13xB0/microReticulum_Firmware github.com/A13xB0/microReticulum_Firmware]. Firmware: [https://rnode.scotmesh.net rnode.scotmesh.net] (choose ''Standalone node'').

== Boards ==

{| class="wikitable"
|-
! Board
! Node pages &amp; API
! Firmware update over the air
|-
| Seeed SenseCAP Solar Node P1 🏴󠁧󠁢󠁳󠁣󠁴󠁿 built by ScotMesh
| Yes
| Bluetooth update window, or USB bootloader
|-
| Heltec V2/V3/V4, Heltec Wireless Tracker V2, XIAO ESP32S3, T-Beam Supreme, T-Deck
| Yes
| WiFi update window
|-
| T-Beam, T3S3, LoRa32 v1/v2/v2.1, RNode NG 2.0/2.1, Feather ESP32, generic ESP32
| Yes
| USB only (one firmware slot)
|-
| RAK4631, RAK3401, T-Echo
| Original microReticulum pages (the new ones don't fit their flash yet)
| USB
|}

== Setting a node up ==

# Open [https://rnode.scotmesh.net rnode.scotmesh.net] in Chrome or Edge on a computer. Choose '''Standalone node''', pick your board, and flash.
# On the configure step:
#* pick '''ScotMesh 868''' (or 433);
#* give the node a name;
#* choose its role (normally ''Fixed relay'');
#* paste your identity hash under ''Remote management''. That makes you its admin.
# The node restarts in transport mode and announces its NomadNet page. You can do everything else from that page over the mesh.

== Using the node's page ==

Open the node's NomadNet address in Nomad Network or MeshChatX. You'll find the address:

* at the end of the flasher;
* on the node's ''About'' page;
* in the node's announce.

Every page is small enough to arrive in '''one LoRa packet''', so it loads first time even on weak links. Most are 150–300 bytes, and the limit is 409.

''The screenshots below are the real pages, fetched over LoRa from our bench P1 (3 hops, through rns.scotmesh.net and a gateway). What you see in your browser depends on its colours.''

=== Home page ===

[[File:home.png|frameless|upright=2.2|The node's home page as a visitor sees it]]

The home page shows:

* the node's name;
* its battery, as a bar (green / amber / red) with % and voltage, plus <span style="color:#22cc55;">▲</span> while charging or <span style="color:#dd9933;">▼</span> while discharging;
* uptime and the number of known routes.

An admin can also show the radio settings, airtime and an operator line. The footer always shows the firmware version and the board. ''Not identified'' means your browser hasn't identified to the node. That's fine for visitors.

=== Routes and neighbours ===

[[File:routes.png|frameless|upright=2.2|Routes page with short addresses]]

'''Routes''' lists the node's path table: destination, hops and when it was last heard. '''Neighbours''' lists the transport nodes it hears directly, with their names where they announce one. To change the view:

* tick ''Short'' for 8-character addresses (or leave it off for full ones);
* set ''Rows'' and press ''Apply'';
* use ''next'' and ''back'' to page through.

An admin can hide both pages from visitors.

=== Becoming an admin ===

You are an admin if your identity is on the node's remote-management list (the same list <code>rnstatus -R</code> checks). In your browser, choose '''Identify''' for the node (NomadNet: the ''Identify'' option on the page; MeshChatX: ''identify to this node'') and reload. The page then shows 🛡️ ''Verified identity'' and an '''Admin''' link. There is no password to log in with: being identified is being logged in.

[[File:home-admin.png|frameless|upright=2.2|Home page seen by an admin]]

Admins see every row. A <code>*</code> marks rows that visitors don't see.

If an admin has switched on '''password registration''', a visitor who has identified sees ''Register''. Entering the password adds their identity as an admin, or puts them in a queue for an existing admin to approve.

=== The admin pages ===

[[File:admin-hub.png|frameless|upright=2.2|Admin hub]]

The hub shows battery and uptime, and warns you when a radio trial needs confirming or someone is waiting for approval. It links to three sections.

{| class="wikitable"
|-
! Section
! Pages
|-
| Settings
| '''Name &amp; announce''': renaming announces straight away. Announce every 30 min, 1 h, 3 h, 6 h or 12 h.<br />
'''Home page''': what visitors see, telemetry API on or off, and a visitor preview.<br />
'''Map''': rmap.world position.<br />
'''Radio''', '''Role''', '''Power'''
|-
| Access
| '''Admins''': add by identity hash; remove with confirmation.<br />
'''Password''' registration.<br />
'''Change log''': every admin change, with time and who made it.
|-
| Device
| '''Health''': free RAM and flash, starts and last reset reason, noise floor, last RSSI/SNR, airtime, packets, table sizes.<br />
'''Lights &amp; Bluetooth''', '''Logs''' (last five log lines), '''Maintenance''', '''Restart &amp; update''', '''About'''
|}

[[File:settings.png|frameless|upright=2.2|Settings section]]

[[File:device.png|frameless|upright=2.2|Device section]]

==== Name &amp; announce ====

[[File:name.png|frameless|upright=2.2|Name and announce page]]

Change the name, set an optional operator line (e.g. a callsign) and set how often the node announces its page. Longer intervals save airtime on a busy channel. Renaming announces at once.

==== Home page layout ====

[[File:home-layout.png|frameless|upright=2.2|Home page layout settings]]

Tick what visitors may see. ''Preview'' shows the page as a visitor would see it. ''Telemetry API'' turns the <code>/api</code> endpoints on or off.

==== Radio and role ====

[[File:radio.png|frameless|upright=2.2|Radio page]]

'''Radio changes are a trial.''' Enter new settings (or pick ''ScotMesh 868'' / ''433'') and press ''Try these''. The node uses them for five minutes. Reconnect on the new settings and press ''Keep''. If you don't, the node goes back to the old settings by itself, so a mistake can't strand a remote node.

[[File:role.png|frameless|upright=2.2|Role page]]

'''Role''':

* ''Fixed relay'': forwards for everyone. Use it for hilltop and roof nodes.
* ''Access point'': for a node that serves nearby clients.
* ''Mobile'': for a node that moves.
* ''End device'': never forwards.

A role change applies after a restart.

==== Power ====

[[File:power.png|frameless|upright=2.2|Power page]]

Below a chosen battery level, the node can lower its TX power to 10 dBm or turn its radio off until it has charged. It can also keep its radio off below 3.3 V to protect the cell.

==== Admins and password registration ====

[[File:admins.png|frameless|upright=2.2|Admins page]]

[[File:password.png|frameless|upright=2.2|Password registration page]]

* '''Admins''' (up to 8): paste a 32-character identity hash and press ''Add''. Tap an identity to remove it; you're asked to confirm. The node won't remove its last admin.
* '''Password registration''' is off by default. An admin sets a password. Someone who knows it can identify to the node and register their own identity as an admin.
** Three wrong tries lock that identity for 15 minutes.
** Ten wrong tries in an hour pause registration.
** With ''Needs approval'' ticked, new registrations wait for an existing admin.

==== Health, lights and Bluetooth ====

[[File:health.png|frameless|upright=2.2|Health page]]

[[File:lights.png|frameless|upright=2.2|Lights and Bluetooth page]]

'''Lights''':

* the activity LEDs can be on, off, or on only for the first 10 minutes after a start;
* ''Blink 30 s'' helps you find a node on a mast;
* error patterns always show.

'''Bluetooth''' can be turned off to save power on a sealed box. ''Unpair all'' forgets paired phones.

==== Maintenance ====

[[File:maintenance.png|frameless|upright=2.2|Maintenance page]]

From here you can:

* announce now;
* restart automatically every day or every week;
* clear stored routes and data;
* factory reset. This keeps the node's identity and its admins.
* full reset. The node forgets its identity too: new addresses, no admins, no settings. Use it to hand a node on, or before re-flashing it as a different node. Afterwards it needs USB to make it yours again (the flasher's ''Reconfigure'' path).

Anything disruptive asks you to confirm, with a link that works once, for two minutes.

=== Restart and firmware updates without a cable ===

[[File:update.png|frameless|upright=2.2|Restart and update page]]

Updates are started from the node's page over the mesh, but the firmware itself is too big to send over LoRa, so someone has to be near the node with a phone or laptop for the transfer. The node accepts the new image's hash by itself afterwards; you don't need <code>rnodeconf</code> or the flasher.

'''WiFi update''' (ESP32 boards with two firmware slots: Heltec V2/V3/V4, Tracker V2, XIAO ESP32S3, T-Beam Supreme, T-Deck):

# ''Device → Restart &amp; update → WiFi update → Yes, start''. The page shows a one-time WiFi password. Write it down; it is shown once.
# The node restarts as a WiFi access point called '''ScotMesh-Update''', off the mesh, for '''20 minutes'''.
# Within WiFi range, join that network with the password and open '''<nowiki><nowiki>http://192.168.4.1</nowiki></nowiki>'''.
# Choose the <code>.bin</code> from inside the board's release zip (for example <code>rnode_firmware_heltec32v3.bin</code>) and press ''Update''. The node verifies it and restarts into the new firmware.

A WiFi update leaves the node running from its second firmware slot. That's fine for the flasher (it always resets the slot choice), but if you later update by hand with <code>esptool</code> or <code>rnodeconf</code>, write <code>boot_app0.bin</code> at <code>0xE000</code> as well as the firmware, or the board keeps booting the old slot and refuses to start transport (&quot;device init failed&quot;).

If nothing is uploaded in 20 minutes, or the upload fails, the node restarts unchanged. The 4 MB boards (T-Beam, T3S3, LoRa32, RNode NG, Feather, generic ESP32) have one firmware slot and can only be updated over USB.

'''Bluetooth update''' (SenseCAP P1):

# This restarts the node with a Bluetooth firmware-update service for '''20 minutes'''. It advertises as <code>SenseCAP P1 DFU</code>.
# Within Bluetooth range, open '''nRF Device Firmware Update''' or '''nRF Connect''' on a phone.
# Send the node's <code>rnode_firmware_seeed_solar_node_p1.zip</code> from the [https://github.com/A13xB0/microReticulum_Firmware/releases releases].

If nothing connects, the node restarts normally when the window closes.

'''USB bootloader''' is for someone on site with a laptop. The node waits in its bootloader until it is flashed (for example from rnode.scotmesh.net) or reset.

None of these start below 30 % battery unless the node is charging.

=== Starting a node from scratch ===

The flasher keeps a node's identity, settings and routes across a reflash, which is what you want for an update. To wipe a node and start again (a second-hand board, or one you want new addresses for), tick '''Start from scratch: erase everything first''' on the flasher's Flash step. On ESP32 boards that erases the whole flash; on the P1 and other nRF52 boards it asks the firmware for a full reset and wipes the EEPROM. Either way the node comes back with a new identity and the flasher provisions and configures it again.

== Showing the node on rmap.world ==

[[File:map.png|frameless|upright=2.2|Map page after saving a position]]

# On ''Settings → Map'', paste the node's position straight from Google Maps. Right-click the spot and click the coordinates, e.g. <code>56.19858019391934, -3.1666195614405708</code>. Degrees-minutes-seconds works too.
# Set its height in metres.
# Choose ''Exact'' or ''~1 km''.
# Tick ''Publish'' and save.

The node then sends the standard Reticulum interface-discovery announce on the announce interval. It's the same announce a PC node sends with <code>discoverable = yes</code>. rns.scotmesh.net peers with rmap.world, so the announce reaches the map through the backbone.

The position is public once published. Use ''~1 km'' if that matters.

== Telemetry API ==

For trackers and dashboards, the node answers plain JSON requests on the same NomadNet address.

* '''No identity is needed.'''
* An admin can switch the API off under ''Home page''.
* Each reply fits in one packet.
* List endpoints page with <code>o</code> (offset) and <code>n</code> (rows), and add <code>&quot;more&quot;: true</code> when there are more rows.

{| class="wikitable"
|-
! Path
! Request data
! Reply (real examples from the bench P1)
|-
| <code>/api</code>
| —
| <code>{&quot;v&quot;:1,&quot;api&quot;:[&quot;bat&quot;,&quot;up&quot;,&quot;radio&quot;,&quot;net&quot;,&quot;sys&quot;,&quot;health&quot;,&quot;pos&quot;,&quot;paths&quot;,&quot;nbrs&quot;,&quot;all&quot;]}</code>
|-
| <code>/api/bat</code>
| —
| <code>{&quot;percent&quot;:96,&quot;voltage&quot;:4.11,&quot;charging&quot;:true}</code>
|-
| <code>/api/up</code>
| —
| <code>{&quot;uptime&quot;:134,&quot;reset&quot;:&quot;soft-reset&quot;}</code>: seconds since start, and why it last started
|-
| <code>/api/radio</code>
| —
| <code>{&quot;freq&quot;:869462500,&quot;bw&quot;:125000,&quot;sf&quot;:9,&quot;cr&quot;:5,&quot;txp&quot;:22,&quot;airtime&quot;:4.4,&quot;noise&quot;:-105,&quot;rssi&quot;:-59,&quot;snr&quot;:10}</code>
|-
| <code>/api/net</code>
| —
| <code>{&quot;routes&quot;:159,&quot;neighbours&quot;:1,&quot;rx&quot;:20,&quot;tx&quot;:18,&quot;links&quot;:1}</code>
|-
| <code>/api/sys</code>
| —
| <code>{&quot;fw&quot;:&quot;v1.86-scotmesh.3&quot;,&quot;board&quot;:&quot;SenseCAP P1&quot;,&quot;name&quot;:&quot;…&quot;,&quot;free_ram&quot;:33472,&quot;free_flash&quot;:1822720}</code>
|-
| <code>/api/health</code>
| —
| <code>{&quot;free_ram&quot;:33472,&quot;free_flash&quot;:1822720,&quot;reboots&quot;:7,&quot;reset&quot;:&quot;soft-reset&quot;,&quot;paths&quot;:159,&quot;paths_max&quot;:500,&quot;announces&quot;:0,&quot;neighbours&quot;:1}</code>
|-
| <code>/api/pos</code>
| —
| <code>{&quot;lat&quot;:56.19858,&quot;lon&quot;:-3.16662,&quot;height&quot;:310}</code>, or <code>{&quot;error&quot;:&quot;not published&quot;}</code>
|-
| <code>/api/all</code>
| —
| battery + uptime + network + airtime in one reply
|-
| <code>/api/paths</code>
| <code>{&quot;o&quot;:0,&quot;n&quot;:5,&quot;s&quot;:0}</code>
| <code><nowiki>{&quot;total&quot;:159,&quot;o&quot;:0,&quot;cols&quot;:[&quot;dest&quot;,&quot;hops&quot;,&quot;age_s&quot;,&quot;via&quot;],&quot;rows&quot;:[[…],…],&quot;more&quot;:true}</nowiki></code>
|-
| <code>/api/nbrs</code>
| <code>{&quot;o&quot;:0,&quot;n&quot;:5,&quot;s&quot;:1}</code>
| <code>{&quot;total&quot;:1,&quot;o&quot;:0,&quot;cols&quot;:[&quot;dest&quot;,&quot;age_s&quot;,&quot;name&quot;],&quot;rows&quot;:[…]}</code>
|}

<code>s=1</code> gives 8-character addresses. Unknown paths answer <code>{&quot;error&quot;:&quot;unknown endpoint&quot;,&quot;see&quot;:&quot;/api&quot;}</code>. If the node is short of memory, it answers <code>{&quot;error&quot;:&quot;busy&quot;}</code>.

Here's a tracker in Python. It needs Reticulum installed and connected to the mesh, e.g. with a TCP interface to <code>rns.scotmesh.net</code> port 4242:

<syntaxhighlight lang="text">import RNS, json, time
RNS.Reticulum()
node = bytes.fromhex(&quot;cb37c17f7280d61d66b5278a02313d25&quot;)   # the node's NomadNet address
if not RNS.Transport.has_path(node):
    RNS.Transport.request_path(node)
    while not RNS.Transport.has_path(node): time.sleep(0.5)
dest = RNS.Destination(RNS.Identity.recall(node), RNS.Destination.OUT,
                       RNS.Destination.SINGLE, &quot;nomadnetwork&quot;, &quot;node&quot;)
link = RNS.Link(dest)                                       # no identify() needed
while link.status != RNS.Link.ACTIVE: time.sleep(0.2)
link.request(&quot;/api/all&quot;, response_callback=lambda r: print(json.loads(r.response)))
link.request(&quot;/api/paths&quot;, data={&quot;o&quot;: 0, &quot;n&quot;: 5},
             response_callback=lambda r: print(json.loads(r.response)))</syntaxhighlight>
Keep one link open and poll every few minutes. Each request and reply is a single small packet (typically 3–5 s round trip over three hops).

== Good to know ==

<ul>
<li>The node keeps its settings in its own flash. Its identity and admin list survive firmware updates and a factory reset.</li>
<li>One exception: RNode NG 2.0/2.1 and LoRa32 v2.1 nodes flashed with v1.86-scotmesh.2 or earlier get a new identity when updated to .4 or later, because those boards moved to a larger app slot (2.25 MB) to fit the pages. Add the node's new identity to your admin list again afterwards. Updates after that keep the identity.</li>
<li>Memory is watched:
<ul>
<li>pages and the API never copy the route table;</li>
<li>the change log is a fixed 1.3 KB file;</li>
<li>below about 8 KB of free RAM, the node answers &quot;busy&quot; rather than risk running out.</li></ul>

''Health'' and <code>/api/health</code> show free RAM, so a slow leak shows up as a trend.</li>
<li>The LEDs on the P1:
<ul>
<li>white flash: packet received;</li>
<li>blue flash: packet sent;</li>
<li>blue and white alternating fast: the radio failed to start (the node restarts itself after a few seconds).</li></ul></li>
<li>Full debug logging stays in the firmware. Connect over USB and open a serial console at 115200 to see it.</li>
<li>Upstream differences and the full change history are in the repository's README.</li></ul>

[[Category:Hardware]]