Chapter 2 — Getting Started¶
2.1 Platforms¶
| Platform | Engine | Notes |
|---|---|---|
| iOS / Android | Embedded — runs inside the app | LoRa radios attach over Bluetooth (iOS BLE radio support is staged; see release notes) or USB-OTG. Background operation requires the Background mesh option (Chapter 6). |
| macOS / Windows / Linux | Companion process on the same machine | USB and Bluetooth RNode radios supported. |
| Raspberry Pi (relay node) | Headless service | See Chapter 11 — Deployment. |
2.2 Licensing at a glance¶
Stolo requires an active license (a seat) per device. There are two activation paths:
- Organization activation code — a 16-character code (formatted
XXXX-XXXX-XXXX-XXXX) issued to your organization. Enter it on the activation screen. - App Store subscription (iOS/macOS) — a monthly auto-renewing Stolo Seat subscription purchased in-app.
Licenses are verified offline on the device using public-key cryptography; the network is needed only at activation and renewal. Chapter 9 covers licensing operations in depth (seat moves, expiry behavior, renewals, deactivation).
Until a device is licensed, the app shows only the activation screen and the mesh engine does not start.
2.3 First launch and setup¶
After activation, Stolo runs a guided setup. Every step except Identity can be skipped and completed later from Settings.
- Welcome / How it works — an introduction to the mesh: WiFi/LAN auto-discovery, Bluetooth (BLE/RNode), and LoRa radio.
- Reachability & Honest delivery — a primer on the reach indicator (Direct / Through a relay / Finding…) and delivery tracking.
- Emergency — introduces the optional hold-to-broadcast SOS.
- Permissions — requests, with rationale, each of:
- Location (for the map and position sharing),
- Bluetooth (to pair LoRa radios and discover nearby nodes),
- Notifications (message and SOS alerts). Each may be allowed or skipped; denied permissions can be adjusted later in the OS Settings.
- Pair radio (optional) — scans for a powered-on RNode in pairing mode (hold its button ~3 s until the LED blinks) and saves it as this device's radio. Only genuine RNode devices are accepted by the scan. Stolo works without a radio — over WiFi and internet — and a radio can be paired later under Settings → Connections.
- Identity (required) — the only mandatory step:
- Callsign / display name — what is broadcast on the mesh (e.g.
Foreman-3,CMD-1). - Team / organization (optional) and role (Foreman, Superintendent, Safety, Operator, Engineer, Medic, Commander, or custom).
- Avatar color. Identity keys are generated locally during this step. Your private key never leaves the device. There is no account creation, e-mail, or phone number.
- First announce / Tour / Ready — previews of what happens at launch. Tapping Launch Stolo completes setup and broadcasts your first presence announcement to the mesh.
2.4 The main screens¶
Stolo has four destinations (bottom bar on phones, side rail on desktop):
| Tab | Purpose | Chapter |
|---|---|---|
| Comms | Conversations, groups, quarantine notices, the SOS button. | 3, 4 |
| Map | Geographic team map ⇄ mesh topology view. | 6 |
| Team | The personnel roster: presence, trust, blocking. | 7 |
| Settings | Appearance, connections, interfaces, network, safety, security, identity. | 12 |
A connection banner appears above the app if the UI loses its link to the engine: a quiet "Connecting…" during first startup, or a red "Cannot connect to Stolo backend" with a RETRY action if an established link drops.
2.5 First contact: seeing your team¶
Devices discover each other automatically:
- Put two or more licensed, set-up devices on the same WiFi network (or attach configured LoRa radios, or let both reach the internet gateway).
- Each device periodically announces its presence. Within moments, peers appear on the Team tab and in New message.
- Presence updates continuously: peers show active, then idle after ~6 minutes of radio silence, then offline after ~12 minutes.
To nudge discovery — for example after arriving on site — use Team → Add personnel (announce) or Settings → Network → Refresh routes, both of which broadcast a fresh announce.
First message from an unknown device? If a device that isn't yet trusted messages you, the message lands in Quarantine rather than your inbox — this is the trust system working as intended. See Chapter 7 for accepting senders, trusting organizations, and configuring strict mode.
2.6 Data locations (administrators)¶
All Stolo data lives on the device, in the profile directory:
| Platform | Profile directory |
|---|---|
| macOS / Linux / Pi | ~/.gridx (override with the GRIDX_HOME environment variable) |
| iOS / Android | The app's private container |
Key contents: the device identity keypair, the message database (messages.db), the networking configuration (reticulum/config), application config (config.json), media storage, the local API token (ws_token), and the vendor certificate (vendor.cert) if installed. Protect and back up this directory deliberately — see Chapter 10 — Security Reference and Chapter 14 — Maintenance.