CLOSED BETAThe format and the API may still change. Talk to us before shipping it in a release: Telegram kintaxfuera.

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

2. File format (CSV, UTF-8, LF)

First line, the header:

#MMCOV1,<board>,<firmware version>,<device id>

Then one row per sample, 13 fields:

t,lat,lon,acc,age,src,kind,snr,rssi,hop,hb,len,rt
FieldMeaning
tUTC Unix seconds of the sample.
lat, lonDegrees, 5 decimals.
accEstimated accuracy in metres (we write HDOP × 5, rounded). Empty if unknown. Rows over 100 m are dropped.
ageSeconds since the fix was taken, 0–30.
srcR = the device's own radio (the only value accepted today).
kindP packet received, N nothing heard in the last 30 s.
snrdB, 1 decimal. Empty for N.
rssidBm, integer. Empty for N.
hopThe 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.
hbHash size in bytes of hop (1–3). Empty when hop is empty.
lenPath length (hops). Empty for N.
rtF 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

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}

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>}

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

CodeWhen
400Bad request: device id, name or board; an empty chunk or one over 16 KB; a first chunk that is not a MatterMap file.
404Unknown upload id.
409Wrong offset, or end before all the bytes arrived (the body says how many).
413Over 2 MB announced, or a chunk past the announced size.
429More 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>

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

Questions, a new firmware joining, or a change you need in the format: Telegram kintaxfuera, or github.com/mattermeshos/mattermesh-os.