Muster: offline location sharing for hiking groups with no signal

I love hiking, and the hard part of hiking in a big group is that it spreads out. A trek group ends up stretched over a couple of kilometres of trail, with some people far ahead and some far behind, and in the hills there is usually no signal to reach any of them. The plan keeps changing too, and with no network, not everyone hears about it.

Muster is a React Native app for iPhone and Android, and the source is on GitHub. The only time anyone needs the internet is to save the map before the trek.

Muster demo: a trek group with no signal

Aditi🌱@aditipolkam

you’re on a trek, your group is spread across a few kms, and there’s zero network. how do you tell everyone if the lunch plan changed?

i built muster - offline location sharing app

- save an offline map for your trek region while you have signal
- phones find each other over bluetooth
- the leader’s location and meeting points hop phone to phone over the mesh
- location details are plotted on your offline map
- you follow by route or compass, fully offline and reach the meeting point comfortably.

no server, no tower, no internet.
powered by the @OfflineProtocol sdk

The video follows one trek, the Valley of Flowers, on two phones side by side: mine as the leader and Gokul’s as a member, with four more people in the group. Both phones are in airplane mode on the trail. When I drop a pin at Pushpawati bridge and share it, it appears on Gokul’s phone with the distance and walking time to it. The bridge is 1.13 km away in a straight line, and his phone works out a 1.35 km route to it along the trails, without a network.

Joining a group with a QR code and no account

A group starts on the leader’s phone. The leader names it, and the phone shows a QR code that holds a join link: the group, the leader’s mesh address and a single-use token. The token is 128 random bits, it expires after 24 hours, and the leader’s phone stores only its hash. People join by scanning the code face to face.

Scanning sends a join request to the leader’s phone over the mesh. The leader approves each request, or turns on automatic approval for that invitation, and the new member gets a welcome with the group’s name and trip map, followed by the roster and the meeting points. There is also a nearby mode for people who can’t scan: the leader opens the group for 10 minutes, phones around can see it and ask to join, and every one of those requests still needs the leader’s approval.

Offline trail maps for a trek region

Most people forget to download the map of where they are going, and at the trailhead there is no internet left to do it. So in Muster the leader picks the trip map when creating the group: a square of up to 20 km a side, chosen on the map. It travels in the welcome each member receives, and the group screen asks each member to download it until they have. Once someone else has joined, the area is locked, so everyone stays on the same map.

The maps are vector tiles from OpenStreetMap, in single-file PMTiles archives built from the Protomaps basemap, and drawn by MapLibre. A region can come from a catalog or be cut as a custom area on the map, and it is checked after download. Muster doesn’t host any maps: tools/region-builder in the repository extracts regions with the pmtiles CLI and writes the catalog, and a release build points at your own catalog from Settings. The public OpenStreetMap tile servers are never used for offline downloads, because their policy forbids it.

Bluetooth mesh location sharing between phones

Each phone runs the Offline Protocol SDK over Bluetooth Low Energy, and the SDK relays messages across phones, so you don’t have to be next to someone to hear from them. Every member publishes one small record with their latest position, and nearby phones carry it on through the group. In airplane mode, the top of the map shows how many people from your group are in range.

The rule that keeps everyone in sync is that state is the truth and messages are only hints. Each piece of shared state, a member’s position, the roster or a meeting point, has exactly one writer and a version number, and the newest version wins on every phone, whatever order the updates arrive in. A member who walks out of range doesn’t miss anything for good. When their phone reconnects it asks the leader’s phone for anything newer than what it holds, and the leader’s phone sends the current roster and meeting points back. Duplicates are dropped by message id, even across an app restart.

Under the hood, groups run on the service subscriptions that came in SDK 0.32. Every phone provides one service for all of its groups, each group has its own topics for the roster, meeting points, acknowledgements and sync requests, and every update travels sealed in an encrypted session between the two phones. The leader’s phone follows every member and every member follows the leader. Muster checks every 30 seconds, and whenever the mesh changes, that each group has the subscriptions it needs.

Meeting points only the group leader can post

On the leader’s phone, the group feed says “Only you can post.” A group with one plan is easier to follow than one where anyone can move the meeting point, so only the leader publishes meeting points and roster changes, and members receive them. A long press on the map gives the leader a Meeting point option and gives members Acknowledge.

Every phone enforces this, not just the interface. A meeting point is accepted only when it comes from the leader recorded on that phone when it joined, the group is active, and the author named in the message is the sender of the session it arrived on. Anything else is dropped. Each point carries a version number, and removing one writes a newer version, so an older update that arrives late can never bring a removed point back. When a member’s phone gets a point, it sends an acknowledgement, and an acknowledgement that couldn’t be delivered is sent the next time the two phones connect.

Offline walking routes and compass navigation

The downloaded map already holds every path, track and road as lines, so Muster finds walking routes from it with no extra download and no server. It reads the map tiles around both ends from the file on the phone, decodes the roads layer with its own small vector tile decoder, builds a graph and runs A* on it. Paths and tracks cost the least, steps and roads a little more, big roads much more, and motorways and private ways are never used. If you walk more than 60 m off the route, it finds a new one.

Where no route exists, for example when you are far from any path, Muster draws a straight line to the target and says it is not a trail route. In the compass view, an arrow tells you which way to turn, with the distance to go: 1.13 km to the bridge in the demo.

Location privacy without a server

Muster shares a location only with your group, and sends no telemetry. The phone accepts subscriptions to a group’s topics only from that group’s active members, so someone outside the group never receives its state. Location is used only while the app is open, and coordinates are never written to the logs.

The app goes online only when you ask it to: to download a map region, or to search for a place by name with OpenStreetMap’s Nominatim. That rule is in the code as well as the docs, since network calls are allowed only in the maps manager and only on the user’s request.

Running Muster on two phones

You need Node 20 or later, and Xcode with CocoaPods for iOS or Android Studio for Android. Muster is built from source:

git clone https://github.com/aditipolkam/muster.git
cd muster
npm install --legacy-peer-deps
cd ios && pod install && cd ..
npm run ios          # or: npm run android

Install it on at least two physical phones, because the iOS Simulator and the Android emulator have no Bluetooth. Maps, navigation and the rest of the interface do work in a simulator. A debug build streams the public Protomaps planet file to show a map before you download a region, and reads a region catalog from your computer at localhost:8787, which you can build and serve with tools/region-builder/build.mjs and serve.mjs. Create a group on one phone, scan its code with the other, turn on airplane mode on both and drop a meeting point.

Muster source code and SDK integration

src/mesh/sdk.ts is the only file that imports the Offline Protocol SDK, and ESLint enforces that. The rest of the app talks to the mesh through one interface, MeshPort, so you can read the whole SDK surface Muster uses in about 80 lines. src/domain holds the pure logic, geo, routing, groups and merge rules, with no React Native and no SDK, which is why it can be tested without radios. The protocol on top of the SDK, with every topic, payload and rule, is in docs/MESH_PROTOCOL.md.

If you build your own app from Muster, change meshAppId in src/shared/config.ts, which is app.muster, and the bundle id, so your phones don’t share a mesh network with Muster’s. To build your own offline app, sign up on the developer portal, start with the SDK quickstart and the documentation, and see Muster with the other apps developers have built on Offline Protocol.