Android¶
An Android app is being built: rettui itself, with its whole Reticulum stack, running on the phone, and its web UI as the app's screen. It's an early test version.
Getting it¶
From a release (from v1.10.0
on): download rettui-<version>-android-arm64-v8a.apk, copy it to the
phone and open it. Android asks once to allow installing apps from the app
you opened it with (Files, a browser). It installs over a test build, and a
later release installs over it, keeping everything.
Test builds¶
- On GitHub, go to Actions > Android > Run workflow. Pick the phones it's
for (
arm64-v8acovers almost every phone;x86_64is for the emulator). Every push to thefeature/androidbranch builds one too. - When the run is done, download the APK from its Artifacts. It comes
zipped: unzip it to get
rettui-<version>-<commit>-arm64-v8a.apk. - Copy it to the phone and open it. Android asks once to allow installing apps from the app you opened it with (Files, a browser).
Unless the repository has a signing key (below), each build is signed with a different key. Android won't install one over another then: uninstall the app first, which deletes its identity and messages.
One key for every build¶
With a signing key in the repository's secrets, each build installs over the last and keeps everything. Make a key once:
keytool -genkeypair -keystore rettui.keystore -alias androiddebugkey \
-keyalg RSA -keysize 2048 -validity 10000 \
-storepass android -keypass android -dname "CN=rettui test builds"
base64 -w0 rettui.keystore # on macOS: base64 -i rettui.keystore
Then, in Settings > Secrets and variables > Actions, add the output as
ANDROID_KEYSTORE. If you chose other passwords or another alias, add them
as ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_PASSWORD and
ANDROID_KEY_ALIAS. Keep rettui.keystore somewhere safe and out of the
repository.
Using it¶
- Opening the app starts rettui, then shows the web UI. Everything else is the same as in a browser. The bars above and below the page (the phone's clock, its buttons) follow the web UI's theme (Status, Theme).
- rettui keeps running when the app is closed, so messages keep arriving. Its notification ("Reticulum is running") says so; Stop in it stops rettui.
- Messages and mentions show as Android notifications while the app isn't on screen. Tapping one opens what it's about. Reply answers from the notification (a message goes the way set for that conversation), and Mark read marks it read without opening rettui. A conversation's notification shows its last few messages, one under another, until it's read or swiped aside.
- A person's messages are a conversation to Android (11 and later): their picture (the same face as in rettui) is by the messages, and Android lists them with your other conversations, with settings of their own. After a reply, the notification shows what was sent for a moment, then goes. Rooms (channels) and games have notification settings of their own too, apart from Messages, so one can be turned off or made quiet without the others (Android's settings for rettui, Notifications).
- A challenge to a game has Accept and Decline in its notification while it waits for an answer, and answers it as the Games tab does.
- With two or more notifications waiting, Android shows them as one stack ("3 notifications") that opens to each of them.
- On Android 11 and later, a conversation's notification can float as a bubble (the button in the notification, or Android's settings for rettui, Bubbles): the conversation opens over other apps, and stays there while you read it.
- Attaching a file offers the camera beside the files. A photo taken goes into the message, and isn't kept in the phone's gallery.
- With rettui's notifications turned off, the app says so once, with Turn them on. Messages still arrive; they show when you open it.
- Recording voice messages, sharing your location and scanning a QR code with the camera ask for the microphone, location or camera the first time.
- Downloads (exports, backups, files from messages and NomadNet pages) go in Downloads. Where files are saved (Status, under Backup) changes that: pick a folder once with Android's own folder picker, or turn on Ask each time to get its Save as screen for every file.
- The back button closes what's open on top (a ⋯ sheet, a dialog), then goes back from a conversation, room or page to its list.
- Joins and leaves in RRC rooms start hidden on the phone. Show joins and leaves (behind ⋯ in a room) shows them.
- After Stop (in the notification, or Stop rettui in the web UI), the app says rettui is stopped, with Start and Close the app. If rettui stops by itself, the app shows what it printed, with Start again and Close the app.
- Sharing with rettui: share text, pictures or files from another app to
rettui. A link on its own (
lxma://,lxmf@…, a NomadNet page,rrc://) opens. Anything else asks which conversation it's for, and goes in that conversation's message box, not sent yet (up to 40 MB of files at once). Reticulum links tapped in other apps (lxma://,lxmf://,nomadnetwork://,rrc://) open in rettui too, after it asks whether to load the page, start the conversation or join the room. A shared file is copied only up to that 40 MB; a bigger one is refused and the partial copy removed. A shared address that points at rettui's own files is refused. - The web UI uses port 8740 on the phone. If another app has that port, rettui takes a free one, and keeps it from then on.
Some phones stop background apps to save battery, and with rettui, Reticulum: messages then only arrive while the app is open. The first time it starts, rettui asks to be allowed to run in the background. To change that later: Settings > Apps > rettui > Battery > Unrestricted (the wording differs between phones).
Battery¶
rettui keeps running with the screen off, so it tries to use as little as it can then:
- AutoInterface stays off mobile data. Before Reticulum starts, rettui
adds the phone's mobile data interfaces (
rmnet…,ccmni…and so on) to Ignored devices of each AutoInterface that's on. AutoInterface finds no one there, and its messages every few seconds kept the mobile radio from sleeping: on a Pixel, most of the battery rettui used. The change is in the Reticulum config's history, and an AutoInterface limited to chosen Devices is left as it is. - The phone may sleep. rettui doesn't keep the processor awake, unless Keep the phone awake (Status, under System) is on. Messages still arrive while the phone sleeps, since incoming traffic wakes it; turn the setting on if they come late, or links drop while the screen is off. It takes effect within 15 seconds.
- Wi-Fi multicast only for AutoInterface. The app asks Wi-Fi to pass multicast, which costs power, only while an AutoInterface is on.
- AutoInterface needs the other side's firewall open. The phone finds another rettui or Reticulum on the same Wi-Fi only if that computer's firewall lets in UDP ports 29716 (discovery) and 42671 (data), or the ones set as Discovery port and Data port. A blocked port shows as nothing coming through the phone's Default Interface in Status.
- On a network you share with strangers, give AutoInterface a Group ID of your own. Everyone on the same Wi-Fi with the same group ID becomes a peer, and the default is the same for everyone. Someone there can then send the phone traffic and take up its peer slots (a limited number per network), which keeps your own devices out. Set the same Group ID on each of your devices (Reticulum, the interface's options) and only they find each other.
- The page rests in the background. Out of sight, the web UI fetches nothing; it catches up when you open the app again. Notifications come from the service meanwhile, which hears only about notifications, not every peer or announce heard.
- Less trying again. An RRC hub that can't be reached is tried less and less often, up to every 15 minutes, and a propagation node search that finds none up to every 6 hours: each try goes out over the network.
- TCP connections and mobile data. Reticulum's TCP interfaces check that the other end is still there after 5 seconds of quiet (as Reticulum does everywhere), which keeps mobile data busy while the phone is awake. On mobile data, fewer TCP interfaces use less.
- Back to Wi-Fi when it's back. A TCP interface that reconnects while Wi-Fi is away for a moment goes over mobile data, and the phone keeps mobile data up in the background after Wi-Fi returns. When the phone switches back to Wi-Fi (or any network that isn't mobile data), the app drops rettui's connections still on mobile data, and they reconnect over Wi-Fi within seconds; a transfer over one may have to start again.
To see what rettui uses, Settings > Battery > Battery usage, or
adb shell dumpsys batterystats org.zevaryx.rettui on a computer.
Identity and backups¶
The web UI never reads or saves identity keys, since anyone with its login link could then copy yours. The app has a screen of its own for them, Identity and backups. Open it from 🔑 Identity and backups in the web UI's Status section, by long-pressing the app's icon, or from the screen shown when rettui stops. On it:
- Save a copy of the identity in use: pick where (Downloads, a USB stick, a cloud folder). Keep the copy private: whoever has it can pose as you and read what's sent to you.
- Keep another identity from a file: an identity file from Sideband, NomadNet, MeshChat or another rettui, kept beside yours under a name you give it. Switch to it in Status > 👤 Identities.
- Save a full backup: settings, contacts, messages and the identity in
use, in one file. It asks for a passphrase to seal it with first (leave
it empty for none): a sealed backup can't be restored without it.
rettui restorerestores it on a computer. - Restore a backup: one saved here or by rettui on a computer (a
sealed one asks for its passphrase). rettui
stops, the backup takes the place of what's here (moved aside into a
before-restore-<time>folder, not deleted), and rettui starts again. -
Settings: a copy of the settings on their own (no messages or identity), or the settings file rettui couldn't read, and Use settings from a file. If the settings file is damaged when rettui starts, it sets the file aside as
settings-unreadable-<time>.jsonin its folder, keeps the settings it can read (a file cut short keeps what came before the cut; a setting of the wrong kind is left at its default) and says so in the log. Save the set-aside file here to mend it on a computer and bring it back with Use settings from a file, which refuses a file rettui can't read and changes nothing. Settings that decide which programs run aren't taken from a file or a backup in the app. A saved settings file can hold an MQTT password and your location: keep it private. -
Backups on a schedule: choose a folder, then Every day or Every week. The first time, it asks for a passphrase to seal them with (leave it empty for none). The phone keeps only a key made from it, which seals backups but can't open them: you type the passphrase to restore one. Change the passphrase… changes it for the next ones. Android makes a full backup there while the phone charges, and keeps the newest 5 it made; older ones it made are deleted, and nothing else in the folder is touched. Make one now makes one straight away. If one fails, a notification says why. Each holds the identity: seal them, or keep the folder private.
Back up the identity before uninstalling the app: uninstalling deletes everything the app keeps. Nothing of rettui's goes to Android's cloud backups, nor to a new phone set up from this one: save a full backup here and restore it there. (A copied identity would leave two phones answering for the same address.)
RNodes¶
The RNodes screen adds an RNode as an interface, over USB or Bluetooth. Open it with 📻 RNode in the web UI's Reticulum section, or by long-pressing the app's icon.
- Over USB: plug the RNode in (a USB-C cable, or an OTG adapter).
Android asks whether to open rettui for it: say yes, and rettui may use it
from then on. On the screen, tap it, allow rettui to use it if asked, and
give it a name. It's added on an
androidusb://port, with its USB IDs (and serial number) so it's found again after it's unplugged. - Over Bluetooth: turn the RNode's Bluetooth on (its Bluetooth button,
or
rnodeconf --bluetooth-on). Tap Find RNodes nearby, allow rettui to find and connect to Bluetooth devices if asked, then tap the RNode and give it a name. It's added on able://port by its name (such asRNode 3B87). The first time rettui connects, Android asks to pair: type the PIN the RNode shows.
Before restarting Reticulum, set the interface's frequency, bandwidth, spreading factor, coding rate and TX power in the Reticulum section. Use what people near you use, and what your country allows. A new interface starts from an example, which may not be right where you are.
What it can't do yet¶
- No terminal UI.
- It hasn't been tested on many phones yet. Reports of what does and doesn't work are welcome in the issues.
How it works¶
The APK carries rettui built for Android as a library,
lib/<abi>/librettui.so. A foreground service loads it in a process of its
own and runs it as rettui would run on a computer:
Since rettui runs inside the app, rsReticulum can call Android through Java.
It does that to find the network interfaces for AutoInterface and to open
USB RNodes. Bluetooth RNodes go through btleplug, whose Java classes the app
carries (android/btleplug, copied from the btleplug crate in Cargo.lock by
build-rust.sh). Stop asks rettui to save everything and stop, and then its
process ends, so each start begins fresh. The Identity and backups screen
calls rettui's own commands (identity export, identity import, backup,
restore) the same way.
The app's screen is a WebView of http://127.0.0.1:8740, logged in with
the token rettui keeps in its data directory. Only this phone can reach
it. The service also follows the web UI's live events to show rettui's
notifications.
Building it yourself¶
You need the Android SDK with NDK 28.2.13676358, JDK 17 or later, and the Rust target:
rustup target add aarch64-linux-android
cd android
ANDROID_HOME=~/Android/Sdk ./build-rust.sh # or: ./build-rust.sh arm64-v8a x86_64
./gradlew assembleDebug # app/build/outputs/apk/debug/app-debug.apk
build-rust.sh cross-builds rettui as a library (cargo rustc --lib
--crate-type cdylib) with the NDK's compilers and puts it in
app/src/main/jniLibs. Android Studio can open android/ as a project
once that's done.