This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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.