MatterMap for developers
MatterMap is a worldwide MeshCore coverage map built from what devices hear while people walk around. Any firmware can contribute: record a small CSV file while moving, then upload it over Wi-Fi. No phone app, no account, no pings: devices only listen to the traffic that is already on the mesh.
1. Recording
- One row per packet received by the device's own radio, stamped with the current GPS fix.
- One "nothing heard" row every 30 s while recording with a fix and no packet in the last 30 s. These rows make the silent areas visible.
- Fresh fix only. No rows without a fix. A fix may be reused only while the device has moved less than about 100 m since it was taken (fix age × speed ≤ 100 m; 10 s when the speed is unknown; never more than 30 s). This keeps packets heard while entering a tunnel out of the wrong area.
- Signal lost: pause and keep the same file, then resume when the fix returns. Don't start a new file.
- Home zone: let the user set a radius around home (we use 500 m by default) where nothing is recorded.
- Own radio only. Packets relayed from a remote companion or bridge are not coverage of the place where the device is.
- Clock: times are UTC Unix seconds. Write rows only once the clock is set, preferably from GPS.
- Size: start a new file when the current one passes 1.5 MB. The server takes up to 2 MB per upload, about 50–100 hours of a normal mesh.
2. File format (CSV, UTF-8, LF)
First line, the header:
#MMCOV1,<board>,<firmware version>,<device id>
board: your board name, lowercase letters, digits and-, 2–24 characters (e.g.wio-l2).device id: 12 lowercase hex characters, stable for the device and not its MAC or public key. We use the first 12 hex of SHA-256("mmcov:"+ MAC in upper-case hex). The server uses it only to resume uploads and to rate-limit; it is never published.
Then one row per sample, 13 fields:
t,lat,lon,acc,age,src,kind,snr,rssi,hop,hb,len,rt
| Field | Meaning |
|---|---|
t | UTC Unix seconds of the sample. |
lat, lon | Degrees, 5 decimals. |
acc | Estimated accuracy in metres (we write HDOP × 5, rounded). Empty if unknown. Rows over 100 m are dropped. |
age | Seconds since the fix was taken, 0–30. |
src | R = the device's own radio (the only value accepted today). |
kind | P packet received, N nothing heard in the last 30 s. |
snr | dB, 1 decimal. Empty for N. |
rssi | dBm, integer. Empty for N. |
hop | The last path hash in lower-case hex: the repeater that delivered the packet. Empty when the packet came straight from its sender (path length 0) and for N. |
hb | Hash size in bytes of hop (1–3). Empty when hop is empty. |
len | Path length (hops). Empty for N. |
rt | F flood, D direct. The server trusts hop on flood packets only. Empty for N. |
Example:
#MMCOV1,wio-l2,solo-2.0,3f9a0c21b7e4
1794470012,45.85660,9.39770,8,1,R,P,7.5,-92,a3,1,2,F
1794470042,45.85702,9.39811,8,1,R,N,,,,,,
Repeater lines (optional, recommended)
So that repeaters show on the map as named dots, append one line per repeater contact that has a position in its advert and whose hash appeared as a flood hop in this recording. Then close the file with #END:
#RPT,<first 12 hex of the public key>,<lat>,<lon>,<name>,<advert unix t>
#END
- Name: commas and newlines removed, at most 32 bytes, cut on a UTF-8 character boundary.
- Append these lines once, before the first upload attempt, and never rebuild them. Every retry must send exactly the same bytes, or a resumed upload can't finish.
- The server shows a dot only when the hash points to a single repeater within 200 km of the recording. A 1-byte hash shared by many repeaters is never trusted.
3. Upload API
Base URL https://mattermeshos.com. HTTPS, no account. Three steps, resumable:
Begin
POST /api/coverage/begin
Content-Type: application/json
{"dev":"3f9a0c21b7e4","board":"wio-l2","fw":"solo-2.0","name":"20261113-101500","rows":830,"bytes":40213}
→ {"id":"<24 hex>","received":0,"done":false}
name: the recording's name, 1–40 characters fromA–Z a–z 0–9 _ . -. We use the UTC start time.- The same
dev+nameagain returns the sameidand how many bytes were alreadyreceived: resume from there. done:true: the server already has the whole file. Skip the chunks and mark it as sent.- If
bytesdiffers from an unfinished earlier attempt, the upload restarts from 0.
Chunks
PUT /api/coverage/<id>?offset=<bytes already received>
Content-Type: text/csv
<raw bytes: whole rows only, at most 12 KB, the header only in the first chunk>
→ {"received":<bytes>}
- Offsets count raw bytes. Always send the next chunk at the
receivedvalue the server returned. - A chunk at an offset already received is acknowledged again, not stored twice. An offset beyond
receivedreturns 409.
End
POST /api/coverage/<id>/end
→ {"done":true,"rows":<rows kept>,"cells":<areas>}
The server cleans the rows (bad values, jumps faster than 300 km/h, 300 m around the first and last point), places them in H3 cells (resolution 9, about 200 m) and merges them into the map. New data shows on the map within about 5 minutes.
Limits and errors
| Code | When |
|---|---|
| 400 | Bad request: device id, name or board; an empty chunk or one over 16 KB; a first chunk that is not a MatterMap file. |
| 404 | Unknown upload id. |
| 409 | Wrong offset, or end before all the bytes arrived (the body says how many). |
| 413 | Over 2 MB announced, or a chunk past the announced size. |
| 429 | More than 20 new uploads from the same device in 24 hours. |
Row times are accepted from 90 days back to 15 hours ahead (a clock set by hand with the wrong time zone). On a network error, retry the same chunk later. On a 4xx, stop and show the error.
4. Map API (read only, anonymous)
For devices: plain text, ready to draw
GET /api/coverage/device?bbox=<south,west,north,east>&res=<6..9>
#MMMAP1,<res>,<s>,<w>,<n>,<e>,<generated t>
C,<best snr ×10>,<samples>,<last t>,<hop:snr;hop:snr…>,<lat,lon,lat,lon… corners>
N,<samples>,<last t>,<lat,lon… corners>
R,<hop>,<lat>,<lon>,<name>,<last heard t>
C= an area where packets were heard,N= nothing heard there,R= a repeater dot. Corners are given so the device needs no H3 library (6 corners, rarely 5).- The answered area is the bbox snapped outwards to a grid (header). Suggested resolution by zoom: 9 from z12, 8 from z10, 7 from z8, 6 below.
- At most 4000
C, 4000Nand 500Rlines, about 130 bytes per area. Parse it line by line and cache it for offline use.
For web pages: JSON
GET /api/coverage/cells?bbox=s,w,n,e&res=4..9 → {"cells":[[h3,best,samples,last_t,["hop:snr",…]],…],"nothing":[[h3,samples,last_t],…]}
GET /api/coverage/repeaters?bbox=s,w,n,e → {"repeaters":[[hop,lat,lon,name,last_heard_t],…]}
GET /api/coverage/stats → {"km":…,"cells":…,"repeaters":…,"contributors":…}
Colours used on the site: best SNR ≥ 5 dB #1f9d55, ≥ −3 dB #d6a400, lower #e8590c, nothing heard #c92a2a.
5. Privacy rules
- The map and every public answer are anonymous: areas only, never who measured them, never routes, no per-device or per-upload view.
- The device id is a pseudonymous hash, never returned by the API.
- Raw recordings stay on the server 7 days (for reprocessing), then they are deleted. Areas not measured for a year disappear.
- The server drops 300 m around the first and last point of every recording, on top of the device's own home zone.
Questions, a new firmware joining, or a change you need in the format: Telegram kintaxfuera, or github.com/mattermeshos/mattermesh-os.