mirror of
https://github.com/agessaman/meshcore-bot.git
synced 2026-03-30 12:05:38 +00:00
652712eb0c
- Renamed various documentation files to use lowercase for improved consistency, including `WEB_VIEWER.md`, `DOCKER.md`, and `PATH_COMMAND_CONFIG.md`. - Updated references in `config.ini.example`, `docker-setup.sh`, `README.md`, and multiple documentation files to reflect the new file names. - Removed obsolete documentation files related to the Discord Bridge, Map Uploader, Packet Capture, and Weather Service, streamlining the documentation structure.
168 lines
4.2 KiB
Markdown
168 lines
4.2 KiB
Markdown
# Map Uploader Service
|
||
|
||
Uploads node advertisements to [map.meshcore.dev](https://map.meshcore.dev) for network visualization.
|
||
|
||
---
|
||
|
||
## Quick Start
|
||
|
||
1. **Configure Bot** - Edit `config.ini`:
|
||
|
||
```ini
|
||
[MapUploader]
|
||
enabled = true
|
||
```
|
||
|
||
2. **Restart Bot** - The service starts automatically and uploads node adverts with GPS coordinates
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
### Basic Settings
|
||
|
||
```ini
|
||
[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:**
|
||
```ini
|
||
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
|
||
```json
|
||
{
|
||
"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:
|
||
```bash
|
||
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.
|