Location tracking

Location actions capture a position and write it directly to an entity — no rule chain and no custom JavaScript required. You configure a target entity and a set of data keys once, and the platform saves latitude, longitude and the other location fields under those keys as server attributes or time series.

The Target panel and the Keys that are saved to entity table are configured the same way in every action that writes a position. Accuracy and Session limits are available in Start live location tracking only.

Every location action writes to exactly one entity, configured in the Target panel. The panel has two modes, selected with the toggle in its top-right corner.

The target is the entity itself. Pick it in the Save to drop-down:

The target is not the entity itself, but a second entity, whose id is stored in a server attribute of the first. Use this when the widget shows one entity but the location belongs to another — for example, a technician’s dashboard row pointing at the vehicle assigned to them.

1. Switch the Target toggle to From attribute.
2. In Read attribute from, choose the entity that holds the attribute — Entity from widget datasource, Current user, or Entity alias. For Entity alias, enter its name in Alias name.
3. In Server attribute key, enter the attribute name.

The attribute must hold an Entity Id object with both fields, for example:

{
  "entityType": "DEVICE",
  "id": "784f394c-42b6-435a-983c-b7beff2784f9"
}

A plain id string is not accepted.

The Keys that are saved to entity table maps each location field to a Data key name and a Type — Server attribute or Time series.

A new action starts with Latitude and Longitude only. Add the rest with Add key, and remove any optional key with the bin icon. Latitude and longitude cannot be removed, and data keys must be unique within one action. Altitude, Speed, Heading, GPS active, and GPS tracked by user can only be added to a Start live location tracking action.

Rename a data key whenever the target entity already uses a different convention — a map widget reading lat and lng, for example. Choosing Time series instead of Server attribute keeps the full history of a value rather than only its latest state, which is what you want for a track you intend to plot.

Available in Start live location tracking only, under Advanced settings. Accuracy is the trade-off between how precise each position is and how much battery tracking consumes.

Available in Start live location tracking only, under Advanced settings. Each limit has its own toggle; the value field and its Units drop-down appear only once the toggle is on.

Leaving every limit off means the app reports positions as fast as the device produces them and keeps the session running until someone stops it — accurate, and the most expensive option for the battery.

Reads the browser’s geolocation once when the action is triggered and saves it to the target entity. The mobile app is not involved, so this action works in any widget on any dashboard opened in a browser.

1. Open the widget in edit mode, go to the Actions tab, and click +.
2. Select the action source, enter a name, and choose an icon.
3. Select Save browser location as the action type.
4. Configure the Target panel and the Keys that are saved to entity table.
5. Click Add, then Apply to save the widget settings.
6. Click Save in the dashboard toolbar.

The browser asks the user for location permission the first time the action runs.

On success the user sees a Browser location saved notification. Failures are reported as:

An existing mobile action that reads the phone’s current position and passes it to a JavaScript function. It now also has an optional Save location to entity toggle.

1. Open the widget in edit mode, go to the Actions tab, and click +.
2. Select the action source, enter a name, and choose an icon.
3. Select Mobile action as the type, then Get phone location as the mobile action type.
4. Turn on Save location to entity, then configure the Target panel and the Keys that are saved to entity table.
5. Click Add, then Apply, then Save in the dashboard toolbar.

With the toggle off the action behaves exactly as before — the coordinates reach your processLocation function and nothing is written. Existing actions are unaffected by the upgrade.

Hands a fully resolved configuration to the ThingsBoard Mobile Application, which then owns the session: it streams GPS fixes — including while the app is in the background — and writes each one to the target entity itself.

1. Open the widget in edit mode, go to the Actions tab, and click +.
2. Select the action source, enter a name, and choose an icon.
3. Select Mobile action as the type, then Start live location tracking as the mobile action type.
4. Configure the Target panel and the Keys that are saved to entity table.
5. Expand Advanced settings to set the accuracy and the session limits. All three limits are off by default.
6. Click Add, then Apply, then Save in the dashboard toolbar.

Ends the tracking session currently running in the mobile app. It has no target or key configuration of its own — the session already knows where it writes.

1. Open the widget in edit mode, go to the Actions tab, and click +.
2. Select the action source, enter a name, and choose an icon.
3. Select Mobile action as the type, then Stop live location tracking as the mobile action type.
4. Click Add, then Apply, then Save in the dashboard toolbar.

A session can also be stopped from the app itself, so a stop action on the dashboard is a convenience rather than a requirement.

Both live tracking actions come with a default result-handler function that shows a confirmation dialog. The function receives launched — whether the session actually started or stopped — and, for the start action, trackingInfo with the target entity name. Replace the body with your own logic, or empty it to show nothing.