Set up vehicles, trackers and the flespi gateway

Overview#

Settings › Integrations › GPS is where you add trucks, register trackers and connect the gateway that forwards tracker positions to TradesWork. Trackers are plug-in OBD-II devices (Teltonika FMC003 class). They report through flespi, a protocol gateway. Techs without a tracker can share their phone's GPS from the field app instead, so trackers are optional.

Before you start#

• You need Owner or Admin. Other roles are sent back to the home page.

• For trackers you need a flespi account and the tracker's IMEI (the digits on its label).

• Decide which tech normally drives each truck. A truck's appointments on the map are its default tech's appointments.

• Phone-only setup needs nothing here except vehicles (optional). See the article "Location privacy, the monitoring notice and tech consent."

Steps#

Add vehicles#

1. Go to Settings › Integrations › GPS (/settings/fleet). From the Fleet map you can also click Vehicles and trackers.

2. In Vehicles, fill Add a vehicle (for example "Van 12"), optionally Year, and pick a Default tech.

3. Click Add vehicle.

4. In the table, fill in the rest of the row and click Save:

   • Name and Unit #.

   • Year, Make, Model, Plate, VIN.

   • Default tech (or "No default tech").

   • Home base: a name (for example "Shop") and latitude and longitude. Playback labels stops here.

   • Active. Untick for a truck that is sold or parked long term. It leaves the live map.

Register trackers#

1. In Trackers, enter the Tracker IMEI (8 to 20 digits).

2. Optionally add a Label (optional), such as "Under dash, driver side".

3. Pick the Vehicle it is plugged into.

4. Click Register. The message says it shows on the map within a minute of its first position.

5. To move a tracker to another truck, or turn it off, change Vehicle or Status (Active or Disabled) in its row and click Save.

Connect flespi#

1. In Tracker gateway setup (flespi), click Create token and confirm.

2. Copy the ingest URL that appears with Copy URL. It is shown only once. Click Done when you have it.

3. In flespi, create a channel for your tracker protocol (for Teltonika: teltonika). Point each tracker's server setting at the channel's host and port.

4. Plug the tracker into the truck's OBD-II port.

5. In flespi, create a stream of type http. Set the URI to the ingest URL, subscribe it to the channel, and keep the batch size (limit_messages) at 500 or less.

   • Instead of the token in the URL you can use the base ingest URI with an Authorization: Bearer <token> header.

6. Turn the ignition on. The truck appears on the Fleet map within about a minute.

Rotate the token#

1. Click Rotate token and confirm. The old token stops working right away.

2. Copy the new URL and update the flespi stream immediately.

Set retention#

1. In Privacy and retention, set Keep positions (months) (1 to 36). The default is 13 months.

2. Click Save privacy settings. Older positions, trips and geofence visits are deleted by a daily job.

Settings that change this#

• Settings › Integrations › GPS › Privacy and retention: off-duty privacy, working hours, retention.

• Settings › Integrations › GPS › Arrival detection and customer ETA: what GPS arrivals do.

• Settings › Integrations › GPS › Monitoring notice: the notice techs accept before phones share location.

Tips#

• Always set a default tech. Without one, a truck shows on the map but can't be matched to appointments or arrivals.

• A tech's phone reports for their default truck if that truck has no tracker. The map then says "via phone".

• The page lists "Phones sharing location" under the Trackers table so you can see who uses phone GPS.

• Keep the ingest token secret. flespi does not sign requests, so the token is the only proof the data is yours.

Troubleshooting#

• "That tracker is already registered." Cause: the IMEI already exists. Fix: find its row and relink it.

• "Enter the tracker's IMEI (the digits on its label)". Cause: letters or too few digits. Fix: type only the digits.

• The truck never appears. Cause: the IMEI isn't registered here, the tracker is Disabled, or the stream uses an old token. Positions from unregistered trackers are refused. Fix: check Last seen, the status and the flespi stream URI.

• "Pick a technician from your team." Cause: the default tech is no longer on the team. Fix: pick an active technician.

• I lost the ingest URL. Cause: it is shown once and only a short prefix is stored. Fix: click Rotate token and update flespi.

FAQ#

Which trackers work? Any device flespi can decode. The setup text and testing target Teltonika FMC003-class OBD trackers.

Do I need trackers at all? No. Phone GPS from the field app works for techs without a tracker.

Can I connect Samsara, Geotab or a vehicle's built-in connected-car service? Not today. flespi and phone GPS are the only sources.

Is engine data like fault codes or mileage used? Mileage is received but maintenance reminders and fault-code alerts are not built yet.

Coming from ServiceTitan#

• In ServiceTitan this was Settings › Integrations › GPS providers, connecting a third-party GPS company.

• In TradesWork you register trackers here and route them through flespi, or use the field app's phone GPS.

• Not built yet: fleet maintenance from mileage, driver scorecards and tamper alerts.