socialmesh

KO | EN

gitlite — search

#python #typescript #llm #golang #android #rust #deep-learning #docker #java #nodejs #windows #kubernetes #vue #pytorch

(★ 26)

Connect to your Meshtastic radio, message off-grid, map your nodes, and explore the mesh - no internet required.

socialmesh Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">SocialMesh</h1>

Mesh Radio Companion App 
 Connect to your Meshtastic radio, message off-grid, map your nodes, and explore the mesh — no internet required.

<a href="#status">Status</a> •
 <a href="#features">Features</a> •
 <a href="#nodedex">NodeDex</a> •
 <a href="#signals">Signals</a> •
 <a href="#getting-started">Getting Started</a> •
 <a href="#building-from-source">Build</a> •
 <a href="#contributing">Contributing</a>

<a href="https://socialmesh.app">Website</a> •
 <a href="https://apps.apple.com/app/id6742694642">iOS App</a> •
 <a href="https://play.google.com/store/apps/details?id=com.gotnull.socialmesh">Android App</a> •
 <a href="https://github.com/gotnull/socialmesh/issues">Issues</a>

---

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.

---

## Status

- The **iOS and Android releases** on the App Store and Play Store are the current stable builds. All features listed in the [Features](#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](docs/ARCHITECTURE.md) for the current system design and [Releasing](docs/RELEASING.md) for the release process.

---

## NodeDex

> _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.

### Procedural Sigils

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.

### Personality Traits

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.

### Patina Score

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.

### Progressive Disclosure

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 |

### Sigil Evolution

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**.

### Sigil Cards

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.

### Field Notes

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.

### Social Tags

User-assigned labels for discovered nodes: **Contact**, **Trusted Node**, **Known Relay**, and **Frequent Peer**. Filter and sort the NodeDex by tag.

### Co-Seen Tracking

Records which nodes have been observed together on the mesh, building a social graph of node relationships over time.

---

## Signals

> _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.

---

## Features

### Communication & Coordination

#### Messaging

| 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                             |

#### Network and Nodes

| 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 |

#### Maps and Location

| 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 |

#### Team Coordination

| 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                |

#### Safety

- **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

#### Analytics and Monitoring

| 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        |

#### Device Configuration

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

#### Integrations

- **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

### Community, Visualization & Extras

#### Audio

- **7,000+ RTTTL Ringtones** — Organized by category, preview before sending
- **Custom Compositions** — Create and save your own ringtones

#### Visualization

| Feature          | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| **World Map**    | Global view of Meshtastic nodes from the public MQTT network |
| **Timeline**     | Chronological feed of all mesh activity and events           |

#### Extras

- **Sigil Cards** — Collectible trading-card-style renders of node identities with shareable PNG export

#### Premium Features

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             |

---

## Tech Stack

| 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 |

---

## Documentation

- [Architecture Overview](docs/ARCHITECTURE.md) — How the app is structured
- [Backend Boundary](docs/BACKEND.md) — What requires cloud services
- [Releasing](docs/RELEASING.md) — How to cut a release

---

## Getting Started

### Prerequisites

| Requirement      | Version                            |
| ---------------- | ---------------------------------- |
| Flutter SDK      | 3.10+                              |
| Xcode            | 15+ (iOS)                          |
| Android Studio   | SDK 34+                            |
| Protocol Buffers | `brew install protobuf`            |
| CocoaPods        | `sudo gem install cocoapods` (iOS) |

### Quick Start (Demo Mode)

Run the app without backend configuration using demo mode:

```bash
# 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=1
```

Demo mode provides sample nodes and messages so you can explore the UI immediately.

### Production Build

For production builds, demo mode is disabled by default. Configure Firebase and other services as documented below.

```bash
# Install dependencies
flutter pub get

# Generate Meshtastic protobufs
./scripts/generate_protos.sh

# Run on connected device
flutter run
```

### Project Structure

```
lib/
├── 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
```

---

## Building from Source

### What works out of the box

- 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

### Optional: Firebase

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).

### Build Commands

```bash
# Install dependencies
flutter pub get

# Generate Meshtastic protobufs
./scripts/generate_protos.sh

# iOS
cd 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
```

### Build Outputs

| Platform       | Location                            |
| -------------- | ----------------------------------- |
| iOS            | `build/ios/ipa/`                    |
| Android APK    | `build/app/outputs/flutter-apk/`    |
| Android Bundle | `build/app/outputs/bundle/release/` |

---

## URL Scheme

SocialMesh registers `socialmesh://` for deep linking:

```
socialmesh://channel/<base64> # Import channel configuration
socialmesh://node/<base64> # Import node information
```

---

## Project Status

SocialMesh is a fully functional Meshtastic companion app available on iOS and Android. The codebase is stable and actively maintained.

### Contributions Welcome

- Bug fixes and performance improvements
- New device configuration options as Meshtastic firmware evolves
- UI/UX polish and accessibility improvements
- Documentation and translations
- Test coverage

### Out of Scope

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

---

## Contributing

We welcome contributions. Please read our [Contributing Guide](CONTRIBUTING.md) 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](CONTRIBUTING.md) for the full list of enforced rules.

See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.

---

## License

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](LICENSE) for details.

### Scope

| Component                        | License                             |
| -------------------------------- | ----------------------------------- |
| **Mobile app** (this repository) | GPL-3.0 — source code provided here |
| **Backend services**             | Proprietary — not included          |

### Third-Party Notices

See [NOTICE.md](NOTICE.md) for attribution of third-party components including Meshtastic protobufs.

---

## Maintainer Setup

For repository maintainers:

1. Enable branch protection on `main`
2. Require pull requests with at least one approval
3. Require CI status checks to pass before merging
4. Disallow force pushes to `main`

---

## Resources

- [Architecture Overview](docs/ARCHITECTURE.md)
- [Backend Boundary](docs/BACKEND.md)
- [Contributing Guide](CONTRIBUTING.md)
- [Security Policy](SECURITY.md)

---

Built for the mesh. Built for the outdoors.

socialmesh

socialmesh Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

socialmesh

socialmesh Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README