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.

👤 Create Your Operator Account

Register as a gateway operator. This gives you a JWT token that the installer uses to automatically register your gateway.

# Register via API (run on your computer — not the Pi)
curl -X POST mesh.meshcorefederationnetwork.org/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username":     "yourname",
    "email":        "you@example.com",
    "password":     "StrongPassword123",
    "display_name": "Your Name",
    "country":      "US"
  }'

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

# Copy the token value — you need it in Step 4

Or log in if you already have an account:

curl -X POST mesh.meshcorefederationnetwork.org/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"yourname","password":"yourpassword"}'

📡 Choose Your Reflector

Pick the reflector that best matches your location and use case. You can change this later at any time.

Selected: MESH-GLOBAL-01

📥 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 \
  --lora-iface serial \          # or: spi (for GPIO HAT)
  --region us \                  # your region code from Step 1
  --site-name "MyGateway" \      # your gateway name
  --federation \
  --fed-server "https://mesh.meshcorefederationnetwork.org" \
  --fed-reflector "MESH-GLOBAL-01" \   # your chosen reflector
  --fed-location "City, Country" \
  --fed-operator-token "eyJhbGci..." \ # your JWT token from Step 3
  -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 → v1.15.0
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-federation
sudo systemctl status meshcore-roomserver
sudo systemctl status mosquitto

# All should show: active (running) in green

# Watch live federation logs
sudo journalctl -u meshcore-federation -f

# Should see:
Federation Client starting
  Server   : https://mesh.meshcorefederationnetwork.org
  Site     : MyGateway
  Reflector: MESH-GLOBAL-01
Connected to federation server

🗺️ Check the Global Map

Open your browser and go to:

https://mesh.meshcorefederationnetwork.org/map

Your gateway should appear as a green pin on the map within 60 seconds of the federation client connecting. Click your pin to see your gateway details.

💬 Send a Test Message

Open your Pi dashboard and send a message from the Send tab:

http://<your-pi-ip>:8080

The message should appear in the reflector's message feed and be delivered to all other gateways on MESH-GLOBAL-01 within 1-2 seconds.

You can also check with the MeshCore CLI on your Pi:

# Connect to companion and send a test message
meshcli -t localhost msg "Hello from MyGateway!"

🎉 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 on global map
• Messages routing to all connected gateways

📱 Connect Field Radios

Field radios carried by your operators need our custom firmware for GPS tracking and long battery life:

1. Download meshcore-field-firmware.zip from the portal
2. Install VS Code + PlatformIO on your computer
3. Edit include/config.h — set NODE_NAME for each radio
4. Flash via PlatformIO → each radio shows on the global map with GPS

🔧 Useful Commands

# Dashboard (all services, messages, map)
http://<your-pi-ip>:8080

# Check federation status
sudo systemctl status meshcore-federation
sudo journalctl -u meshcore-federation -f

# Switch reflector
curl -X GET https://mesh.meshcorefederationnetwork.org/api/gateways/join/MESH-EMCOMM \
  -H "X-Gateway-Token: $(cat /opt/meshcore-gateway/federation_token.txt)"
sudo systemctl restart meshcore-federation

# View all MQTT traffic
mosquitto_sub -h localhost -u meshcore \
  -P $(grep PASS /opt/meshcore-gateway/mqtt.credentials | cut -d= -f2) \
  -t '#' -v

🆘 Troubleshooting