Join the Global Mesh Network

💾 Flash Raspberry Pi OS

Download Raspberry Pi Imager from raspberrypi.com/software and install it on your computer.

Open Imager and make these exact selections:

1. Choose Device → Raspberry Pi 4 (or your model)
2. Choose OS → Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit)
3. Choose Storage → your MicroSD card
4. Click the gear icon ⚙ before writing:
   • Hostname: meshcore-gw
   • Enable SSH ✅
   • Username: pi
   • Set a strong password — write it down
   • Configure Wi-Fi if not using Ethernet
5. Click Write and wait for verification to complete

🔌 First Boot

Insert MicroSD into Pi, connect Ethernet, connect power. Wait 90 seconds.

Find your Pi's IP address in your router's connected devices list, then SSH in from your computer:

# From Windows PowerShell, Mac Terminal, or Linux terminal
ssh pi@192.168.1.xxx   # use your Pi's actual IP
# or try the hostname:
ssh pi@meshcore-gw.local

Once logged in, update the system:

sudo apt update && sudo apt upgrade -y
sudo reboot

Wait 60 seconds, then SSH back in — you are ready for the installer.

📡 Choose Your Reflector

Pick the reflector that best matches your location and use case. You can change this later with a single command.

Selected: MESH-GLOBAL-01

👤 Operator Account

The installer creates your operator account automatically using the email and password you provide with --fed-email and --fed-pass. No separate signup step needed.

If you prefer to register first (e.g. to claim a specific username), run this on any computer:

# Optional: pre-register via API
curl -X POST https://mesh.meshcorefederationnetwork.org/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username":     "your-username",
    "email":        "you@example.com",
    "password":     "StrongPassword123!",
    "display_name": "Your Name",
    "country":      "US"
  }'

# Response:
{
  "token": "eyJhbGci...jwt-token...",
  "operator": {"id": "uuid", "username": "your-username"}
}

📥 Download the Installer to Your Pi

SSH into your Pi and run:

# Download installer
curl -L https://mesh.meshcorefederationnetwork.org/install.sh -o meshcore-all-in-one.sh
chmod +x meshcore-all-in-one.sh

# Or use wget:
wget https://mesh.meshcorefederationnetwork.org/install.sh -O meshcore-all-in-one.sh
chmod +x meshcore-all-in-one.sh

🚀 Run the Installer

Replace the values below with your actual information, then run on your Pi:

sudo bash meshcore-all-in-one.sh \
  --install gateway \
  --region us \                        # your region code from Step 1
  --site-name "MyGateway" \            # your gateway name
  --federation-server mesh.meshcorefederationnetwork.org \   # this federation server
  --reflector "MESH-GLOBAL-01" \    # your chosen reflector
  --fed-email "you@example.com" \      # your email (creates account)
  --fed-pass "StrongPass123!" \        # choose a strong password
  -y

📻 Flash Your Gateway Radio

The RAK4631 plugged into your Pi needs MeshCore Companion firmware:

1. Go to flasher.meshcore.io
2. Connect your gateway RAK4631 to your computer via USB
3. Select: RAK4631 → Companion → latest version
4. Click Flash and wait for completion
5. Plug the flashed radio into your Pi via USB

✅ Check Everything is Running

On your Pi via SSH:

# Check all services
sudo systemctl status meshcore-gateway
sudo systemctl status meshcore-fed-client
sudo systemctl status meshcore-roomserver
sudo systemctl status mosquitto

# All should show: active (running) in green

# Watch live federation client logs
sudo tail -f /var/log/meshcore/fed-client.log

# Should see:
Federation client starting | server=mesh.meshcorefederationnetwork.org
Connected to mesh.meshcorefederationnetwork.org reflector=MESH-GLOBAL-01
Local MQTT connected

🌐 Confirm Gateway on the Federation

Check that your gateway appears in the public gateway list:

# From any computer
curl -s https://mesh.meshcorefederationnetwork.org/api/gateways/list | python3 -m json.tool

# Should show your gateway with "is_online": true

🗺️ Check the Global Map

Open your browser and go to:

https://mesh.meshcorefederationnetwork.org/map

Your gateway will appear in the sidebar list immediately. To show as a pin on the map, set your coordinates when re-running the installer or update your gateway record via the API.

💬 Send a Test Message

Open the MeshCore companion app, connect to your Pi, and send a message. It will route through the federation to all gateways on MESH-GLOBAL-01 within 1-2 seconds.

You can also test message routing via the reflector API:

# Check recent messages on your reflector
curl -s "https://mesh.meshcorefederationnetwork.org/api/reflectors/MESH-GLOBAL-01/messages" \
  | python3 -m json.tool

🎉 Welcome to the Global Mesh Network!

Your gateway is now part of the worldwide MeshCore federation. Your field radios can reach any connected mesh on earth.

• Gateway running on Raspberry Pi
• Connected to mesh.meshcorefederationnetwork.org
• Joined reflector MESH-GLOBAL-01
• Appearing in the global gateway list
• Messages routing to all connected gateways

🔧 Useful Commands

# Check federation client status
sudo systemctl status meshcore-fed-client
sudo tail -f /var/log/meshcore/fed-client.log

# Switch to a different reflector
GW_TOKEN=$(python3 -c "import json; print(json.load(open('/opt/meshcore-gateway/federation.json'))['gateway_token'])")
curl -X GET https://mesh.meshcorefederationnetwork.org/api/gateways/join/MESH-EMCOMM \
  -H "X-Gateway-Token: $GW_TOKEN"
sudo systemctl restart meshcore-fed-client

# View all MQTT traffic on your Pi
mosquitto_sub -h localhost -t '#' -v

# Restart all gateway services
sudo systemctl restart meshcore-gateway meshcore-fed-client meshcore-roomserver

🆘 Troubleshooting