Documentation

Everything you need to know about using Socialmesh with your Meshtastic devices.

Getting Started

Socialmesh is a companion app for Meshtastic radio devices. It allows you to send and receive messages over the mesh network, track nodes, and configure your devices.

Quick Start

1. Power on your Meshtastic device
2. Open Socialmesh and tap Connect
3. Select your device from the list
4. Wait for the connection and initial sync to complete
5. Start messaging!

Connecting Your Device

Bluetooth (BLE)

Bluetooth is the most common way to connect. Make sure your device has Bluetooth enabled in its configuration.

1. Go to the Connection screen
2. Tap Scan for Devices
3. Select your device from the discovered list
4. The app will automatically pair and connect

USB Serial (Android Only)

Android devices can connect via USB OTG cable for a more stable connection.

1. Connect your Meshtastic device via USB-C OTG adapter
2. Grant USB permission when prompted
3. The device will appear in the connection list

Messaging

Direct Messages

Send private messages to specific nodes on the mesh. Messages are encrypted end-to-end using the channel's PSK.

Channel Messages

Broadcast messages to all nodes listening on a channel. Great for group communication.

Message Features

• Quick Responses — Tap to send preset replies
• Tapback Reactions — React to messages with configurable emoji (sent as a reply over the mesh)
• Delivery Receipts — See when the recipient's device acknowledges receipt of your message

Message Delivery

Socialmesh tracks message delivery status:

• Pending — Message queued for transmission
• Sent — Transmitted by your device
• Delivered — Acknowledged by the recipient's device (this confirms radio-level receipt, not that the message was read)
• Failed — Delivery failed after retries

Behaviour & Limits

• Message payload is limited by the LoRa MTU (approximately 237 bytes UTF-8). Longer messages are truncated.
• Delivery is not guaranteed. Messages may be lost if the recipient is out of range, offline, or if the network is congested.
• Hop limit controls how far a message can travel through relay nodes. Higher hop limits increase reach but also increase airtime.
• Encryption uses AES-256 with the channel's PSK. The default channel uses a publicly known key and is not private.
• Store-and-forward (if enabled on relay nodes) may hold messages for offline recipients, but availability and duration depend on relay node configuration.

Signals (Presence)

Signals are ephemeral messages that let you share your presence with nearby mesh users. Unlike regular messages, signals automatically expire after a set time.

Signal Features

• Signal Map — View all signals with GPS on an interactive map
• Filters — Filter by saved, nearby, with media, with location, with replies (signed in), or expiring soon
• Replies — When signed in with internet, reply to signals with threaded comments and voting. Replies are stored in the cloud, not sent over the mesh.
• Save Signals — Bookmark signals before they expire
• Hide Signals — Swipe to hide signals you don't want to see
• Images — Attach photos to signals. Images require sign-in and internet; they are uploaded to cloud storage. The mesh packet carries only a flag indicating an image is available. Images cannot be sent over LoRa radio.

Behaviour & Limits

• Signal text content is limited to 140 bytes UTF-8 (a wire protocol constraint, not a UI limit).
• TTL is a client-side display hint. The mesh has no mechanism to enforce expiry or recall a broadcast. Receiving apps use the TTL to decide when to stop showing a signal.
• Delivery is best-effort. Signals are broadcast, not acknowledged. There is no guarantee every node in range receives every signal.
• Signals are sorted by proximity (hop count), not chronologically. Closer signals appear first.
• Signal binary payloads range from 21 to 159 bytes depending on content and optional fields.

Channels & Encryption

Understanding Channels

Channels define who can communicate on the mesh. Each channel has:

• Name — Human-readable identifier
• PSK (Pre-Shared Key) — Encryption key for the channel
• Role — Primary, Secondary, or Disabled

Adding Channels

You can add channels by:

• Scanning a QR code from another device
• Importing a channel URL
• Manually entering channel settings

Node Management

Node List

View all nodes discovered on the mesh. Each node shows:

• Long name and short name
• Battery level and voltage
• Signal quality (SNR/RSSI)
• Last heard time
• Distance (if location known)

Favorites

Mark frequently contacted nodes as favorites for quick access.

Node Details

Tap any node to see detailed information including hardware info, position history, and message statistics.

NodeDex (Field Journal)

NodeDex is a mesh field journal that transforms node discovery into a living record. Every node you encounter earns a unique identity — a procedurally generated sigil, a behavioral trait, and a history score. All data is generated and stored locally on your device.

What Data Does It Use?

• All NodeDex data is computed locally from mesh telemetry (encounters, positions, battery, role, uptime).
• No internet connection is required.
• NodeDex entries are persisted in a local SQLite database.
• Optional cloud sync (when signed in) backs up your NodeDex entries.

Explore the full NodeDex page →

Aether (Flight Sharing)

Aether lets you schedule Meshtastic nodes on commercial flights and share them with the community. Other users with ground stations can attempt long-range LoRa reception as the flight passes overhead.

Requirements & Constraints

• Sharing a flight requires internet (the Aether API stores shared flight data).
• Live flight tracking (Sky Scanner) requires internet and uses the OpenSky Network API, which has its own rate limits and availability constraints.
• LoRa reception from altitude is not guaranteed. Range depends on ground station antenna, terrain, frequency, and aircraft position.
• Flight data you share is public. Other Socialmesh users can see your scheduled flight details.

Explore the full Aether page →

Map & Location

Node Map

Visualize all nodes with known positions on an interactive map. Supports multiple map styles including satellite and terrain views.

Position Sharing

Share your location with the mesh. Configure how often your position is broadcast in Device Settings → Position.

Traceroute

Discover the path messages take through the mesh network to reach distant nodes.

3D Globe & World Mesh

3D Globe View

Visualize your local mesh network on an interactive 3D globe.

• Rotate & Zoom — Explore the globe from any angle
• Node Markers — See all nodes plotted on the globe
• Connection Lines — Visualize mesh connections between nodes

World Mesh Map

The World Mesh displays Meshtastic nodes from around the world, collected via MQTT from public Meshtastic networks. It is a read-only view of the global network — you can browse node positions and details, but you cannot send messages to or interact with remote nodes through the World Mesh.

• Live Data — Updated from public MQTT topics. Reflects nodes that have opted in to MQTT uplink on their local networks.
• Browse Nodes — Explore node positions, telemetry, and network topology worldwide
• Node Details — Tap any node to see its reported information

Behaviour & Limits

• World Mesh data comes from nodes whose local networks uplink to public MQTT topics. Not all Meshtastic nodes appear — only those on MQTT-enabled networks.
• Node positions shown are as reported by the source network. Accuracy depends on the node's GPS and its operator's privacy settings.
• Data may be delayed. Real-time updates depend on MQTT connectivity and collector processing.
• The World Mesh is view-only. You cannot send messages, trigger actions, or interact with nodes shown on it.

Automations

Create automated actions triggered by mesh events. Automations run locally on your phone while the app is connected to a device.

Behaviour & Limits

• Automations execute on the phone, not on the mesh device. The app must be running and connected to a device for triggers to fire.
• Battery Low triggers use hysteresis — they fire only when the threshold is crossed (not repeatedly while below it).
• Geofence triggers depend on the node reporting accurate GPS positions. Nodes without GPS or with position sharing disabled will not trigger geofence rules.
• IFTTT integration requires internet and a valid IFTTT webhook URL.
• Silent Node triggers fire when a node has not been heard for a configured duration. This does not necessarily mean the node is offline — it may be out of range.

Dashboard Widgets

Customize your dashboard with widgets showing real-time mesh data.

Built-in Widgets

• Node Status — Online/offline indicators
• Battery Monitor — Track device power levels
• Message Stats — Communication metrics
• Signal Quality — Network health visualization
• Position Tracker — Mini map view

Community Sharing

The Widget Pack includes access to a community widget library where you can browse widgets shared by other users or publish your own creations. Community submissions are reviewed before appearing in the library.

Themes & Ringtones

Theme Pack

Customize the look of your app with premium themes. Choose from a variety of color schemes and visual styles to match your preferences.

Ringtone Pack

Access over 5,300 notification sounds organized by category:

• Classic Ringtones — Traditional phone sounds
• Nature Sounds — Birds, water, wind
• Sci-Fi — Futuristic alerts and beeps
• Musical — Short melodies and tunes
• Retro Gaming — 8-bit and arcade sounds

Set different ringtones for different nodes or channels to know who's messaging without looking.

Device Configuration

Configure all aspects of your Meshtastic device directly from the app.

Radio Settings

• Region — Set your regulatory region
• Modem Preset — Balance range vs speed
• Hop Limit — Maximum message hops
• TX Power — Transmission power level

Module Configuration

• Position — GPS and location settings
• Telemetry — Sensor data broadcasting
• Store & Forward — Message relay settings
• Range Test — Signal testing mode
• MQTT — Internet gateway settings

Mesh Protocol

Socialmesh extends Meshtastic with compact binary packet types for presence beacons, signals, and node identity exchange — all without modifying firmware.

Troubleshooting

Device Won't Connect

• Ensure Bluetooth is enabled on both phone and device
• Power cycle the Meshtastic device
• Forget the device in phone's Bluetooth settings and re-pair
• Check that device firmware is up to date

Messages Not Sending

• Verify you're connected to a device
• Check that channel settings match other nodes
• Ensure you're within radio range of mesh nodes
• Try reducing hop limit for testing

No Nodes Appearing

• Wait a few minutes for node discovery
• Verify your region setting is correct
• Check that other nodes are powered on and in range
• Ensure channel PSK matches the network

App Crashes or Freezes

• Force close and restart the app
• Clear app cache (Android)
• Reinstall the app if issues persist
• Report the issue via Support