Mesh Radio Companion App
Connect to your Meshtastic radio, message off-grid, map your nodes, and explore the mesh — no internet required.
Status • Features • NodeDex • Signals • Getting Started • Build • Contributing
Website • iOS App • Android App • Issues
Connect to your mesh radio, message off-grid, discover nodes, and explore the mesh — all without internet.
SocialMesh works fully offline over BLE and USB. Firebase is optional for cloud sync and social features.
- The iOS and Android releases on the App Store and Play Store are the current stable builds. All features listed in the Features section below are available in these releases.
- The offline-first architecture, mesh communication, NodeDex, Signals, TAK integration, and all companion-app capabilities are shipped and stable.
- See Architecture Overview for the current system design and Releasing for the release process.
Mesh node registry and discovery journal.
Every node discovered on the mesh is automatically catalogued in the NodeDex — a persistent, queryable registry of all mesh nodes and their observed history. NodeDex serves as the authoritative record of what devices have been seen, how they behave, and where they have been observed. Each node receives a unique procedural Sigil (a geometric glyph derived deterministically from its identity) and a behavioral classification inferred from real observed data. Accessible from the drawer menu.
Every node gets a unique constellation-style geometric identity generated from its node number. The same node always produces the same sigil — no randomness, no variation. Sigils are built from outer polygons (3-8 vertices), optional inner rings, radial lines, and a unique 3-color palette drawn from 16 curated colors.
Traits are never user-assigned — they are passively inferred from observable telemetry and behavior:
| Trait | Description |
|---|---|
| Relay | Router role with high throughput — forwards traffic for the mesh |
| Wanderer | Seen across multiple distinct positions or regions |
| Sentinel | Fixed position, long-lived, high encounter count |
| Beacon | Always active, very frequent encounters |
| Ghost | Rarely seen relative to age — elusive presence |
| Courier | High message volume relative to encounters |
| Anchor | Persistent hub with many co-seen connections |
| Drifter | Irregular timing, unpredictable appearance pattern |
Each trait includes a confidence score and evidence lines explaining the classification.
A numerical measure (0-100) of how much observable history a node has accumulated, computed across six axes: tenure, encounters, geographic reach, signal depth, social connections, and recency. Early gains are meaningful; diminishing returns prevent runaway scores.
Information is revealed as observation accumulates — new nodes start sparse, detail unlocks over time:
| Tier | Name | What appears |
|---|---|---|
| 0 | Trace | Sigil, name, hex ID only |
| 1 | Noted | Primary trait badge |
| 2 | Logged | Trait evidence and field note |
| 3 | Inked | Full trait list and patina stamp |
| 4 | Etched | Identity overlay at full density |
Sigils visually mature as patina accumulates — subtle line weight changes, color deepening, and micro-etch detail that progresses through five stages: Seed, Marked, Inscribed, Heraldic, and Legacy.
Collectible trading-card-style renders of a node's full identity — rarity-tiered borders, dramatic sigil display, RPG-style stat grids, and shareable PNG export. Accessible from the NodeDex detail screen and the Nodes screen.
Deterministic single-line observations that read like entries in a naturalist's field journal. The same node always gets the same note. Template families are selected by trait and filled with concrete values from the node's history.
User-assigned labels for discovered nodes: Contact, Trusted Node, Known Relay, and Frequent Peer. Filter and sort the NodeDex by tag.
Records which nodes have been observed together on the mesh, building a social graph of node relationships over time.
Structured mesh persistence with location and time context.
Signals is the mesh-native persistence layer. Publish status updates, check-ins, and hazard markers that are received by all mesh members in range. Signals carry configurable TTL, GPS location stamps, and image attachments. Sorted by proximity and expiry. Designed for groups that need structured, time-bounded awareness without internet.
| Feature | Description |
|---|---|
| Channel Messaging | Send and receive on multiple channels simultaneously |
| Direct Messages | Private, encrypted node-to-node communication |
| Quick Responses | Pre-configured canned messages for fast replies |
| Message Search | Full-text search across all conversations |
| Offline Queue | Messages queued when disconnected, sent automatically on reconnect |
| Reactions | React to messages with emoji responses |
| Feature | Description |
|---|---|
| Node Discovery | See all nodes with signal strength, battery, and location |
| NodeDex | Mesh node registry with procedural sigils and behavioral classification |
| Network Topology | Visual graph showing mesh interconnections |
| Traceroute | Trace the exact path packets take through the mesh |
| Signal History | SNR and RSSI charts over time |
| Favorites | Pin important nodes for quick access |
| Node Profiles | Rich profiles with user info, social links, and custom avatars |
| Presence | Track when nodes are online, their activity patterns, and last seen times |
| Feature | Description |
|---|---|
| Node Map | Interactive map with all GPS-enabled nodes |
| Waypoints | Drop, share, and navigate to waypoints |
| Location Sharing | Broadcast your position to the mesh |
| Map Styles | Street, satellite, and terrain views |
| Route Recording | Record and save your routes with GPS tracks |
| Feature | Description |
|---|---|
| Activity Timeline | Chronological feed of mesh activity and events with identity resolution |
| Group Profiles | View group member profiles with role, assignment, and contact details |
| Signals Feed | Structured status updates sorted by proximity and expiry |
- Emergency SOS — One-tap broadcast with optional GPS coordinates
- Geofence Alerts — Notifications when nodes leave defined areas
- Battery Alerts — Low battery warnings for tracked nodes
| Feature | Description |
|---|---|
| Mesh Health | Real-time network health metrics, utilization graphs, and issue detection |
| Reachability | Probabilistic assessment of node reachability based on observed data |
| Presence | Track when nodes are online, their activity patterns, and last seen times |
| Route Analysis | View discovered routes and packet paths through the mesh |
| Telemetry Logs | Device metrics, environment sensors, air quality, position history |
Full control over your Meshtastic device:
- LoRa — Region, modem preset, hop limit, frequency slot
- Power — Sleep mode, shutdown timeout, power saving
- Position — GPS mode, broadcast interval, smart position
- Bluetooth — Pairing mode, PIN code, power settings
- Network — WiFi, Ethernet, MQTT bridge
- Display — Timeout, brightness, flip screen, OLED burn-in protection
- Detection Sensor — Motion and door sensor triggers
- Canned Messages — On-device quick responses
- IFTTT Webhooks — Trigger automations on node events and geofence alerts
- MQTT Bridge — Internet uplink configuration
- QR Codes — Import/export channels and share node info instantly
- 7,000+ RTTTL Ringtones — Organized by category, preview before sending
- Custom Compositions — Create and save your own ringtones
| Feature | Description |
|---|---|
| World Map | Global view of Meshtastic nodes from the public MQTT network |
| Timeline | Chronological feed of all mesh activity and events |
- Sigil Cards — Collectible trading-card-style renders of node identities with shareable PNG export
These features are available via one-time in-app purchases:
| Feature | Description |
|---|---|
| Theme Pack | 12 accent colors to personalize the entire app |
| Ringtone Pack | 7,000+ searchable RTTTL ringtones — classic tunes, TV themes, games |
| Widgets | Build custom dashboard widgets with live data, charts, and gauges |
| Automations | Create rules that trigger alerts, send messages, and react to events |
| IFTTT Integration | Connect your mesh to 700+ apps and services via webhooks |
| Layer | Technology |
|---|---|
| UI Framework | Flutter 3.10+ |
| State Management | Riverpod 3.x |
| Protocol | Meshtastic Protobufs |
| Local Storage | SQLite |
| Analytics | Firebase (optional) |
| Sigil Generation | Deterministic geometric identity |
| Trait Inference | Passive behavioral classification |
- Architecture Overview — How the app is structured
- Backend Boundary — What requires cloud services
- Releasing — How to cut a release
| Requirement | Version |
|---|---|
| Flutter SDK | 3.10+ |
| Xcode | 15+ (iOS) |
| Android Studio | SDK 34+ |
| Protocol Buffers | brew install protobuf |
| CocoaPods | sudo gem install cocoapods (iOS) |
Run the app without backend configuration using demo mode:
# Clone and bootstrap
git clone https://github.com/gotnull/socialmesh.git
cd socialmesh
./tool/dev_bootstrap.sh
# Run in demo mode (no backend required)
flutter run --dart-define=SOCIALMESH_DEMO=1Demo mode provides sample nodes and messages so you can explore the UI immediately.
For production builds, demo mode is disabled by default. Configure Firebase and other services as documented below.
# Install dependencies
flutter pub get
# Generate Meshtastic protobufs
./scripts/generate_protos.sh
# Run on connected device
flutter runlib/
├── core/ # Theme, shared widgets, constants, safety utilities
├── features/ # Feature modules
│ ├── automations/# Rule-based event automation engine
│ ├── channels/ # Channel messaging
│ ├── dashboard/ # Custom widget dashboard
│ ├── device/ # Device configuration
│ ├── map/ # Interactive node map
│ ├── mesh_health/# Network health analytics
│ ├── messaging/ # Direct and channel messaging
│ ├── nodedex/ # Mesh node registry (sigils, classifications, patina)
│ ├── presence/ # Node presence tracking
│ ├── reachability/# Node reachability analysis
│ ├── signals/ # Structured mesh persistence
│ ├── social/ # Activity timeline, team profiles
│ ├── widget_builder/ # Custom dashboard widget editor
│ ├── world_mesh/ # Global MQTT node map
│ └── ... # Additional feature modules
├── generated/ # Meshtastic protobuf code
├── models/ # Data models
├── providers/ # Riverpod state management
├── services/ # Protocol, storage, transport layers
└── utils/ # Utilities and helpers
- BLE and USB connection to Meshtastic devices
- All mesh communication (messaging, node discovery, channels)
- Local SQLite storage (NodeDex, signals, routes, packet deduplication)
- Protobuf encoding/decoding
- NodeDex with procedural sigils and trait inference
The app uses Firebase for optional cloud features. Without configuration:
| Feature | Behavior |
|---|---|
| Analytics/Crashlytics | Disabled silently |
| Cloud sync | Falls back to local-only |
| Authentication | Sign-in unavailable |
| Social features | Local-only mode |
To enable, add your own google-services.json (Android) and GoogleService-Info.plist (iOS).
# Install dependencies
flutter pub get
# Generate Meshtastic protobufs
./scripts/generate_protos.sh
# iOScd ios && pod install &&cd ..
flutter build ios
# Android
flutter build apk # Debug APK
flutter build apk --release # Release APK
flutter build appbundle --release # Play Store bundle| Platform | Location |
|---|---|
| iOS | build/ios/ipa/ |
| Android APK | build/app/outputs/flutter-apk/ |
| Android Bundle | build/app/outputs/bundle/release/ |
SocialMesh registers socialmesh:// for deep linking:
socialmesh://channel/<base64> # Import channel configuration
socialmesh://node/<base64> # Import node information
SocialMesh is a fully functional Meshtastic companion app available on iOS and Android. The codebase is stable and actively maintained.
- Bug fixes and performance improvements
- New device configuration options as Meshtastic firmware evolves
- UI/UX polish and accessibility improvements
- Documentation and translations
- Test coverage
The following are intentionally excluded from this repository:
- Backend services, cloud functions, and APIs (proprietary)
- Payment processing and subscription infrastructure
- App Store/Play Store publishing workflows
- Marketing materials and promotional content
We welcome contributions. Please read our Contributing Guide before submitting a PR.
All code must pass the project linter (scripts/hooks/socialmesh-lint.sh) with zero errors. The linter enforces banned patterns, required headers, async safety, and UI consistency rules automatically. PRs that fail the linter will not be accepted. See the Contributing Guide for the full list of enforced rules.
See SECURITY.md for reporting vulnerabilities.
This mobile application is licensed under the GNU General Public License v3.0 (GPL-3.0-or-later).
You are free to use, modify, and distribute this software under the terms of the GPL-3.0. See LICENSE for details.
| Component | License |
|---|---|
| Mobile app (this repository) | GPL-3.0 — source code provided here |
| Backend services | Proprietary — not included |
See NOTICE.md for attribution of third-party components including Meshtastic protobufs.
For repository maintainers:
- Enable branch protection on
main - Require pull requests with at least one approval
- Require CI status checks to pass before merging
- Disallow force pushes to
main
Built for the mesh. Built for the outdoors.