View source for ScotMesh firmware

'''ScotMesh firmware''' is our build of [https://github.com/attermann/microReticulum_Firmware microReticulum], the firmware that turns a LoRa board into a self-contained Reticulum [[Glossary#Transport node|transport node]]: a relay that carries traffic for everyone around it, with no Raspberry Pi or computer attached. We add the things a node needs when nobody can get to it: a page to look after it from anywhere on the mesh, a small telemetry feed, and firmware updates without a cable.

This page explains why we build it and what it adds. The complete guide to every page and setting is [[ScotMesh microReticulum]].

== Why Scotland needs it ==

Scotland is a big country for its population. The places that most need a network that does not depend on the internet or the mobile networks are glens, islands, hill farms and villages at the end of single-track roads. They are also the places where a relay has to sit on a hilltop or a mast, run on sunlight, and get through a winter without anyone visiting.

That changes what a node's firmware has to do. A relay in a city can be walked to in ten minutes. A solar node on a Highland hill or an island can be hours away by road and ferry, and in bad weather out of reach for weeks. So for us:

* '''Every visit is expensive.''' Anything that would normally need a laptop and a USB cable should be possible over the mesh instead.
* '''Nodes run on batteries and sunlight.''' Their owners need to see battery and charging from far away, and the node should protect itself when the sun does not come out.
* '''Settings change after installation.''' A radio gets retuned, a node gets renamed, looking after it passes to someone else. None of that should mean a trip up a hill.
* '''Firmware needs updating''' without taking the node down from the mast, and without any risk of leaving it dead if an update goes wrong.

Upstream microReticulum is an excellent base, but it assumes the owner is nearby with a USB cable. The ScotMesh build adds the remote side. The more of Scotland the network reaches, the more of its nodes will be remote ones, which is why this matters more here than in most places.

== What it adds ==

{| class="wikitable"
! Feature !! What it does
|-
| '''The node's own page''' || A [[Nomad Network]] page served from the radio board: name, battery bar with charging arrow, uptime, routes and neighbours. Every page fits in a single LoRa packet, so it loads first time even over a weak link.
|-
| '''Remote management''' || Admin pages for the node's owners: name and announce interval, radio settings (tried for five minutes, then kept or undone automatically), role, power saving, admins and password registration, a change log, health, lights and Bluetooth, logs, maintenance and restart.
|-
| '''Telemetry''' || A small JSON feed (battery, uptime, radio, routes, neighbours, position) that anyone can read without an identity, for dashboards and trackers.
|-
| '''Updates without a cable''' || A 20-minute update window opened from the admin page: over Bluetooth on the SenseCAP Solar Node P1, over WiFi on ESP32 boards with two firmware slots.
|-
| '''rmap.world''' || Puts the node on the Reticulum network map, with an exact or approximate position.
|-
| '''Full reset''' || Wipes the node back to a new identity, from its page or from the [https://rnode.scotmesh.net flasher].
|-
| '''SenseCAP Solar Node P1''' || Support for Seeed's solar node: battery reporting, charging, the solar-friendly power settings above.
|}

== Looking after a node from home ==

[[File:scotmesh-remote-management.svg|center|frameless|1000px|How an admin reaches a remote node: laptop, internet, the ScotMesh backbone, a LoRa gateway, then the solar node]]

You open the node's address in a Nomad Network browser, exactly like any other node. Your request crosses the internet to the [[The ScotMesh node|ScotMesh backbone]], goes out over LoRa through one or more radio hops, and the node answers with a page small enough to fit in one radio packet.

Anyone can read the public page and the telemetry. The admin pages only open for identities on the node's admin list: you add yourself when you set the node up with the [https://rnode.scotmesh.net flasher], and admins can add others from the page itself. There is no password to type over the radio; being [[Glossary#Identity|identified]] is being logged in.

== The node's own page ==

<gallery mode="packed" heights="230px">
File:home.png|The home page, as a visitor sees it
File:admin-hub.png|The admin hub
File:health.png|Health: memory, starts, radio, tables
File:radio.png|Radio changes are a five-minute trial
File:map.png|Position for rmap.world, pasted from Google Maps
File:update.png|Restart and firmware update
</gallery>

These are the real pages, fetched over LoRa from our bench SenseCAP P1 through three hops. The [[ScotMesh microReticulum]] guide goes through every one.

== Updating without a cable ==

[[File:scotmesh-update-flow.svg|center|frameless|upright=3.6|Update flow: open the window from home, someone nearby uploads, the node checks the image and comes back]]

Firmware images are far too big to send over LoRa, so an update still needs someone within Bluetooth or WiFi range of the node, with a phone. What it no longer needs is a cable, a laptop, or taking the node down from where it is mounted.

[[File:wifi-update-page.png|right|frameless|upright=0.9|The upload page a WiFi update window serves at 192.168.4.1]]

* '''SenseCAP Solar Node P1:''' the node advertises as ''SenseCAP P1 DFU'' for 20 minutes. Send it the release zip with Nordic's free '''nRF Device Firmware Update''' app ([https://play.google.com/store/apps/details?id=no.nordicsemi.android.dfu Android], [https://apps.apple.com/app/nrf-device-firmware-update/id1624454660 iPhone]).
* '''Heltec V2/V3/V4, Wireless Tracker V2, XIAO ESP32S3, T-Beam Supreme, T-Deck:''' the node becomes a WiFi hotspot called ''ScotMesh-Update'' for 20 minutes, protected by a one-time password shown on the admin page. Join it, open <code><nowiki>http://192.168.4.1</nowiki></code> and upload the <code>.bin</code> from the release.
* '''T-Beam, T3S3, LoRa32, RNode NG, Feather and generic ESP32:''' these boards have a single firmware slot, so they update over USB with the [https://rnode.scotmesh.net flasher].

The step-by-step guide, with app links, is at [https://rnode.scotmesh.net/update.html rnode.scotmesh.net/update.html].

'''Why it is safe.''' Every node checks at start-up that its firmware is the image its owner installed, and refuses to carry traffic if it is not. An update started from the admin page tells the node to accept the next image once, so it comes straight back on the mesh with its identity, admins and settings intact. If nothing is uploaded within 20 minutes, or an upload fails, the node restarts on the firmware it already had.
<div style="clear:both"></div>

== Boards ==

{| class="wikitable"
! Boards !! Node page and remote management !! Update without a cable
|-
| SenseCAP Solar Node P1 || Yes || Bluetooth window
|-
| Heltec V2, V3, V4, Wireless Tracker V2, XIAO ESP32S3, T-Beam Supreme, T-Deck || Yes || WiFi window
|-
| T-Beam, T3S3, LoRa32 v1, v2, v2.1, RNode NG 2.0, 2.1, Feather ESP32, generic ESP32 || Yes || No: one firmware slot, update over USB
|-
| RAK4631, RAK3401, T-Echo || Upstream microReticulum page || No
|}

== Getting it ==

* '''Flash it from a browser:''' [https://rnode.scotmesh.net rnode.scotmesh.net], choose ''Standalone node''. It fetches the firmware, flashes it, and walks you through naming the node, choosing its radio profile and adding yourself as its admin.
* '''Releases:''' [https://github.com/ScotMesh/microReticulum_Firmware/releases github.com/ScotMesh/microReticulum_Firmware/releases]
* '''Source and changes from upstream:''' [https://github.com/ScotMesh/microReticulum_Firmware github.com/ScotMesh/microReticulum_Firmware]

[[Category:Hardware]]