meshcore-bot/docs/map-uploader.md

Map Uploader Service

Uploads node advertisements to map.meshcore.dev for network visualization.

---

Quick Start

1. Configure Bot - Edit config.ini:

[MapUploader]
enabled = true

2. Restart Bot - The service starts automatically and uploads node adverts with GPS coordinates

---

Configuration

Basic Settings

[MapUploader]
enabled = true                        # Enable map uploader
api_url = https://map.meshcore.dev/api/v1/uploader/node  # API endpoint
min_reupload_interval = 3600          # Minimum seconds between re-uploads (1 hour)
verbose = false                       # Detailed debug logging

Private Key (Optional)

The service needs your device's private key to sign uploads. It will automatically fetch the key from your device if supported.

Manual Configuration:

private_key_path = /path/to/private_key.txt

---

How It Works

1. Listens for ADVERT packets on the mesh network
2. Verifies packet signature using Ed25519
3. Filters invalid packets:
   • Missing GPS coordinates (lat/lon)
   • Coordinates exactly 0.0 (invalid)
   • CHAT adverts (only nodes are uploaded)
   • Duplicate/replay attacks
4. Uploads valid node adverts to the map with your radio parameters
5. Prevents spam - Only re-uploads the same node after min_reupload_interval

---

What Gets Uploaded

Node Types Uploaded

• Repeaters
• Room servers
• Sensors
• Other non-CHAT adverts with GPS coordinates

Data Included

{
  "params": {
    "freq": 915000000,
    "cr": 8,
    "sf": 9,
    "bw": 250000
  },
  "links": ["meshcore://DEADBEEF..."]
}

What's NOT Uploaded

• CHAT adverts (companion devices)
• Nodes without GPS coordinates
• Nodes with invalid coordinates (0.0, 0.0)
• Duplicate packets (same node within min_reupload_interval)

---

Signature Verification

All uploads are signed with your device's private key to ensure authenticity:

1. Ed25519 signature proves you received the packet
2. Radio parameters show your device config
3. Raw packet data allows independent verification

Security: Map operators can verify uploads came from legitimate devices.

---

Troubleshooting

Service Not Starting

Check logs:

tail -f meshcore_bot.log | grep MapUploader

Common issues:

• enabled = false in config
• Missing dependencies: pip install aiohttp cryptography
• No private key available

No Uploads Happening

1. Check for adverts - Service only uploads when it receives ADVERT packets
2. Verify coordinates - Nodes must have valid GPS coordinates
3. Check signature - Service logs "signature verification failed" for invalid packets
4. Check interval - Same node won't re-upload within min_reupload_interval

Private Key Errors

Error: "Could not obtain private key"

Solutions:

1. Ensure your device firmware supports private key export
2. Manually provide key via private_key_path
3. Check file permissions if using file path

---

Advanced

Memory Management

The service tracks seen adverts to prevent duplicates. Old entries are automatically cleaned:

• Hourly cleanup removes entries older than 2 × min_reupload_interval
• Safety limit: Keeps only 5000 most recent entries if dictionary grows beyond 10,000

Radio Parameters

Your device's radio settings are included in all uploads:

• freq: Frequency in Hz
• cr: Coding rate
• sf: Spreading factor
• bw: Bandwidth in Hz

Packet Format

Uploads use the meshcore:// URI scheme with hex-encoded raw packet data for verification.

---

FAQ

Q: Will this upload my location? A: No. Only node adverts (repeaters, sensors) with GPS coordinates are uploaded. CHAT adverts are never uploaded.

Q: How often does it upload? A: Only when new node adverts are received. Same node won't re-upload within min_reupload_interval (default: 1 hour).

Q: What if my device doesn't support private key export? A: You'll need to manually provide the private key via private_key_path.

Q: Can I use a different map server? A: Yes, change api_url to point to your own map.meshcore.dev instance.

Q: Does it upload all packets? A: No. Only ADVERT packets from nodes with valid GPS coordinates.