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
• Message Reactions — React with emoji to messages
• Read Receipts — See when messages are delivered
• Media Support — Share images over the mesh
• Voice Messages — Record and send audio clips

Message Delivery

Socialmesh tracks message delivery status:

• Pending — Message queued for transmission
• Sent — Transmitted by your device
• Delivered — Acknowledged by recipient
• Failed — Delivery failed after retries

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, or expiring soon
• Comments — Reply to signals and have conversations
• Save Signals — Bookmark signals before they expire
• Hide Signals — Swipe to hide signals you don't want to see

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.

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 entire mesh network on an interactive 3D globe. Perfect for understanding the global reach of your mesh network.

• 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 shows Meshtastic nodes from around the world, collected via MQTT from public networks. See the global Meshtastic community in real-time.

• Live Data — Updated in real-time from MQTT feeds
• Thousands of Nodes — Explore the worldwide mesh network
• Node Details — Tap any node to see its information

Automations

Create automated actions triggered by mesh events.

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

Widget Marketplace

Download community-created widgets or share your own creations.

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

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