GPS trackers and Route Map

The route a tracker has traveled is drawn by the Route Map dashboard widget. (The Map widget is different: it only shows the fixed positions from location metadata.)

1. Send latitude and longitude in one message

Two different numeric metrics, in one message (or one bn + bt block):

{"f": "flat", "v": 1, "id": "truck1", "t": 1790000000, "m": {"lat": -6.2088, "lon": 106.8456, "speed": 42.5}}

[{"bn": "truck1:", "bt": 1790000000, "n": "lat", "v": -6.2088},
 {"n": "lon", "v": 106.8456},
 {"n": "speed", "v": 42.5}]

• A latitude-longitude pair is formed from readings with exactly the same time from the same publisher and source. Do not send two separate messages with different timestamps.
• The metric names need not be lat and lon, but they must be two different, consistent names.
• Values outside the Earth’s range (latitude outside −90 to 90, longitude outside −180 to 180) are not drawn.
• A tracker that has not got a GPS fix should not include lat and lon at all, rather than sending 0.

2. Store through a rule

The route is read from stored data, and messages are only stored by rules. Create a Channel Subscriber → Internal DB (SenML) rule for the tracker’s channel (the quick button on the channel page). An external PostgreSQL output, Internal DB (JSON), and free-form JSON payloads are not readable by Route Map. Messages sent before the rule was created or while it was disabled have no route data.

3. Add the Route Map widget

Dashboard → Edit mode → Add widget → Route Map. For every source (one source = one line):

Field	Value
Channel	The channel the tracker sends to.
Latitude name and Longitude name	The metric names exactly as stored: bn + n for SenML, or id: + name for SenFlat (for example truck1:lat and truck1:lon). The two names must differ.
Device	Pick the sending device. Required when several trackers share the same channel and metric names, otherwise all trackers’ points mix into one line.
Source (bn)	Optional: the raw bn or id with a colon (truck1:), for a tracker behind a gateway.
Label, color	The line and legend appearance.
Time window	Realtime (the last N seconds) or a date range. For today’s route, use a range from 00:00.
Maximum points per route	500 by default, at most 1000 in the UI (2000 in the API).

Several trackers: add one source per tracker with a different color and line pattern.

What is shown

The route line, an A marker (the first point) and a B marker (the last point) with a time popup, and a legend with the number of points and the route length (the straight-line distance between points, not road distance). When older points in the window were not included, the widget says “Only the newest points are shown”; narrow the time window or raise the point limit. On a realtime window the widget refreshes itself every interval.

Limitations

• Route Map is not available in the public view because device locations are sensitive.
• The tracker’s latest position as a live marker (not a route) is not available yet. The options: a realtime Route Map line, or filling in the device’s location metadata for the Map widget.
• You must have permission to read that channel.

Troubleshooting

Symptom	Common cause
“No latitude/longitude points in this time window”	There is no storage rule; the lat/lon names are not exactly the stored ones (check Messages); lat and lon were sent in separate messages with different times; the time window is too narrow.
The line jumps or mixes	Several trackers share the same channel and metric names without picking a Device.
Points in the middle of the sea or at (0, 0)	The tracker sent 0 before getting a GPS fix.
Only part of the route is visible	The point limit was reached; see the “Only the newest points…” warning.

Test without a device: send several messages with mosquitto_pub with slightly changing lat and lon each time.