What it does
- Device registration. Record a physical tracker’s identity and bring its telemetry onto the platform.
- Device-to-asset binding. Attach a tracker to a vehicle, trailer or asset, and re-attach it when the hardware moves.
- Unified position reads. Live snapshot and history through the same tracking surface used for driver positions.
- Automation on equal terms. A tracked asset triggers geofence crossings exactly as a driver does.
- Vehicle telemetry. Where the hardware supports it, engine and diagnostic data alongside position.
How it works
Every vendor, one shape
Tracker manufacturers do not agree on anything. One pushes messages over HTTP, another holds a raw socket open, a third wants to be polled, a fourth speaks a messaging protocol of its own. The platform puts a per-vendor translator in front of each, so by the time telemetry reaches you it has one consistent shape regardless of which hardware produced it.
The practical benefit is that changing tracker vendor — or running three at once because you inherited a mixed fleet — is a platform concern, not an integration rewrite on your side.
Indistinguishable downstream
Once normalised, a tracker position is handled identically to a position from a driver’s phone. The same live snapshot, the same history, the same geofence detection, the same events. You do not learn a second API to find out where a trailer is.
The binding is data you control
A device and the thing it is attached to are separate records with a link between them. Move a tracker from one trailer to another and each trailer keeps its own history for the period the device was on it. Without that separation, moving hardware would silently rewrite where an asset appeared to have been.
Why it is not part of Realtime GPS Tracking
The two look similar — both answer “where is this right now” — but they are different commitments. Hardware trackers are bought or leased, carry SIM data costs, and are billed per device. Driver-app tracking runs on phones your drivers already own and is billed per account. Bundling them would force a decision about leasing fifty pieces of hardware onto anyone who just wants their drivers’ phones to report position. They are separate modules so you can take either one.
Permissions
This module has no permissions of its own yet. The codes below are the ones planned for it — they cannot be attached to an API credential until the module ships. Anything you build against the module today uses the base-platform permissions listed alongside them.
| Permission | What it allows | Needed |
|---|---|---|
| trackers.read | Read registered devices and their bindings to assets. Planned — not yet issuable. | Planned |
| trackers.write | Register devices and bind or re-bind them to vehicles and assets. Planned — not yet issuable. | Planned |
| tracking.read | Read live and historical position telemetry — the same surface serves tracker and driver positions. | Available |
| assets.read | Read the vehicles and trailers a tracker is attached to. | Available |
| assets.write | Create and edit the vehicles and trailers being tracked. | Available |
| geofences.read | Read the boundaries a tracked asset is evaluated against. | Available |
| subscriptions.write | Register the webhook endpoint that receives crossing events for tracked assets. | Available |
API reference
Hardware tracker integration has no public contract yet. The equivalent surface for phone-based tracking is the realtime GPS tracking read API.
| Service | What it covers | Reference | Contract |
|---|---|---|---|
| tracking-api | Driver-app position reads. Belongs to Realtime GPS Tracking, not this module. | OpenAPI description | openapi.json |
The contract above belongs to the core platform, not to this module. It is listed because it is the surface that does this work today — when the module publishes its own API, it will appear here.
Each openapi.json is the generated OpenAPI 3.1 contract, served by the service itself — it is never hand-edited, so it cannot drift from the running API. The OpenAPI description link opens the same contract as a browsable reference. Both resolve to the environment these docs are served from, so a page read on the test site links to the test contract.
Events
This module does not raise events of its own today. The events it is expected to raise are listed below so you can plan a subscription around them, but they are not yet published on the event stream.
Device-level events — a tracker going offline, a low battery, a tamper alert — are planned. What a tracked asset produces today is the same movement-derived events any tracked subject produces.
| Event | Raised when | Tells you |
|---|---|---|
| geofence.entered | A tracked asset crosses into a boundary. | The boundary, the device, the coordinates and the time. Requires the Geofences module. |
| geofence.exited | A tracked asset crosses out of a boundary. | The same detail as entry. The usual trigger for “this trailer has left the yard”. |
The envelope these arrive in, the delivery and retry guarantees, and every other event type are in Events & webhooks — or jump straight to the event catalog.