GPS Tracking Platform User Guide: Events, Geofences, Trips, Permissions and Commands

This guide covers the five parts of the Open Platform at platform.crucialtracking.com.au that you will use most day to day: events and notifications, geofences, trip and stop detection, permissions and groups, and commands. Each section explains how the platform thinks first, then the settings that control it, so you can predict what it will do before you change anything. Appendix A gathers every setting in one place, and the troubleshooting checklist at the end covers the questions we hear most.

How to use this guide

• Names shown like speedLimit are settings. Names in bold are labels you will see in the web interface.
• Settings come in two kinds. Attributes such as speedLimit or color are set by you, in the platform, on a device, a group or a geofence — the most specific value wins. Server parameters such as report.trip.minimalTripDuration or geofence.polylineDistance live in the platform’s server configuration and are set by our team.
• Where a section says a setting is server-side, or that a feature has to be switched on for your account, contact us — call 0413 418 743 or email team@crucialtracking.com.au — and we will set it for you. Tell us what you are trying to achieve rather than the parameter name; there is often a simpler way.

In this guide: 1. Events and notifications · 2. Geofences · 3. Motion, trips and stops · 4. Permissions and groups · 5. Commands · Appendix A: configuration quick reference · Troubleshooting checklist

1. Events and notifications

An event is a record of something that happened to a tracker. A notification is an optional delivery of that record to a person. The two are independent: events are always recorded and can always be reviewed in the events report, whether or not anyone has subscribed to them.

Most event types are produced by the server. It examines each incoming position, compares it against the previous state of the tracker and against the thresholds you have configured, and writes an event when a condition is met. A smaller category, the alarm, works differently: the tracker itself decides that something has happened and reports it, and the server simply records what it was told.

That distinction matters in practice. Server-side detection works with every tracker, because it only needs positions. Device-side alarms are usually more precise, because the hardware sees the sensor directly rather than a sampled position stream, but they are only available if the model and protocol support them.

Figure 1.1 — Events are recorded unconditionally. Notification delivery is a separate, per-user layer on top.

Subscribing to notifications

Each user maintains their own subscriptions from the Notifications area of the settings menu. A subscription combines three choices:

• Event type — which condition you want to hear about.
• Channels — one or several delivery methods for the same subscription.
• Scope — either every tracker you can see, or a specific set of devices and groups linked to the notification.

A calendar may also be attached, which confines delivery to the hours and days defined in that schedule. This is the usual way to stop overnight or weekend alerts without disabling the subscription entirely; the events themselves continue to be recorded outside the calendar window.

Figure 1.2 — A typical subscription list. The same event type can be delivered through several channels at once and scoped differently for each user.

Event types

The table below lists the event types the server can generate. Where an event depends on a threshold, the relevant attribute is named; those attributes can be set on the device, on a group, or globally on the server, with the most specific value taking precedence.

Event	Meaning and requirements
Command result	The outcome of a command sent to the tracker. Only some protocols return results; the detail is kept in the result attribute.
Status online	The tracker has established a connection. Not tied to a position record.
Status unknown	The connection is still open but nothing has arrived for some time, which can also mean the tracker dropped the link without closing it properly.
Status offline	The tracker has disconnected from the server.
Device inactive	No location data for an extended period. Off by default; enable it with the deviceInactivityStart and deviceInactivityPeriod attributes.
Device moving	Movement has begun, according to the motion logic described in Section 3.
Device stopped	Movement has ended, according to the same logic.
Speed limit exceeded	Reported speed has passed the threshold in the speedLimit attribute.
Fuel drop	A sudden fall in fuel level greater than fuelDropThreshold. Requires a tracker that reports fuel level.
Fuel increase	A sudden rise greater than fuelIncreaseThreshold. Also requires fuel level support.
Geofence entered	The tracker has crossed into a zone that is linked to it, directly or through its group.
Geofence exited	The tracker has left such a zone.
Proximity enter	A linked device has come within proximityEnterDistance metres. A value of zero turns the check off.
Proximity exit	A linked device has moved further away than proximityExitDistance metres. Zero turns the check off.
Unaccompanied motion	The tracker began moving with no linked device within unaccompaniedDistance metres. Zero turns the check off.
Alarm	A condition reported by the tracker itself. Many subtypes exist; see the next table.
Ignition on	Ignition changed from off to on. The tracker must report ignition continuously.
Ignition off	Ignition changed from on to off, under the same condition.
Maintenance required	A scheduled service interval has come due. Requires a maintenance definition linked to a device or group.
Driver changed	The reported driver identifier has changed. The tracker must actually transmit driver identification; assigning a driver in the settings alone does not produce this event.
Media	The tracker has uploaded an image, video or audio file. Support varies by protocol.

Alarm types

Alarms arrive already classified by the tracker. The list below covers the ones you are most likely to encounter; it is not exhaustive, and the exact trigger for each depends on the hardware.

Alarm	Typical cause
General	The tracker signalled an alarm without specifying which kind.
SOS	A panic condition, normally a button press, though the trigger varies by model.
Vibration	A stationary tracker has been disturbed, usually detected by an accelerometer.
Overspeed	The tracker’s own speeding threshold was crossed. Equivalent to the server-side speed event, but measured on board and therefore more precise.
Low power	External supply voltage has fallen below the safe level.
Low battery	The internal backup battery is running down.
Geofence enter	A zone stored on the tracker was entered.
Geofence exit	A zone stored on the tracker was left.
Tampering	Interference with the unit, commonly the casing being opened. The sensor and threshold depend on the model.

2. Geofences

A geofence is a named area on the map. Once it is linked to a tracker, the platform watches for that tracker crossing the boundary and records an entry or exit event each time it does.

Three geometries are available, and the choice is not merely cosmetic — each answers a different operational question. A polygon answers “was the vehicle inside this yard?”, a polyline answers “did the vehicle stay on this route?”, and a circle answers “was the vehicle within this distance of a point?”.

Figure 2.1 — The three supported geometries. Polygons and polylines are drawn point by point on the map; a circle needs only a centre and a radius.

Corridor width for polylines

A line has no area, so the platform gives it one. A tracker counts as inside a polyline geofence while it stays within a set distance of the line, forming a corridor along the route. That distance is controlled by the server parameter geofence.polylineDistance and defaults to 25 metres.

Twenty-five metres suits urban streets. On rural roads, where positions scatter more and the drawn line may not follow the carriageway exactly, a wider corridor avoids a stream of spurious exit and re-entry events. If you find a vehicle repeatedly leaving and rejoining a route it clearly drove, the corridor is almost always the cause — ask us to widen it.

Linking and access

Two different relationships govern a geofence, and confusing them is the most common source of “the zone isn’t working” reports.

Relationship	Effect
Linked to a device	The platform monitors that tracker against the zone and generates entry and exit events for it.
Linked to a group	The same monitoring applies to every tracker in the group, including devices in nested subgroups.
Linked to a user	The user can see the zone, edit or delete it, and subscribe to its events. This has no bearing on whether events are generated.

Events therefore depend entirely on the device or group link. A user who has access to a zone but whose trackers are not linked to it will never receive an alert from it, no matter which notifications they enable.

A calendar can be attached to a geofence as well, restricting event generation to the scheduled periods. Note the difference from a calendar on a notification: here the events themselves are suppressed outside the window, not just their delivery.

Colour

Set the color attribute on a geofence to control how it is drawn on the map. Any valid HTML colour value is accepted. Colour is presentation only, but on a busy map it does real work — a consistent scheme, such as one hue for customer sites and another for restricted areas, makes an overloaded view readable again.

Supervising a route

Polylines and circles combine well when you need to confirm that a vehicle both followed a route and completed it. Draw the route itself as a polyline, then place a small circular zone at the origin and another at the destination. The polyline reports departures from the corridor; the two circles mark the beginning and the end of the journey.

Figure 2.2 — Route supervision. Circular zones confirm departure and arrival; the corridor detects any deviation in between.

3. Motion, trips and stops

Trips and stops are not reported by the tracker. They are inferred by the server from a stream of positions, using a small set of thresholds. Understanding those thresholds is the difference between reports that match the driver’s day and reports that do not.

The motion attribute

Every protocol reports movement differently, so the platform normalises it into a single motion attribute that is either true or false. Some trackers supply this value directly. For the rest, the server derives it by comparing reported speed against speedThreshold. If neither route gives a satisfactory result for a particular tracker, a computed attribute can override the value.

How the state changes

The server keeps a current state for each tracker, either stopped or moving, and changes it only when a condition holds continuously. Any interruption resets the detection and the state stays where it was. This is deliberate: it prevents a momentary GPS wobble at a traffic light from splitting one journey into three.

Figure 3.1 — State transitions. Each condition must hold without interruption; a fluctuation restarts the count.

Detection parameters

These are server parameters. The defaults below apply to your account unless we have tuned them for you.

Parameter	Default	Purpose
report.trip.minimalTripDuration	300 s	Movement shorter than this, and shorter than the minimal distance, is discarded rather than recorded as a trip.
report.trip.minimalTripDistance	500 m	The distance counterpart of the above; either threshold alone is enough to qualify.
report.trip.minimalParkingDuration	300 s	A pause must last at least this long to count as a stop.
report.trip.minimalNoDataDuration	3600 s	A silence longer than this is treated as a stop. Applies to reports only.
report.trip.useIgnition	disabled	When enabled, an ignition-off reading forces the state to stopped regardless of speed.

The alternative motion model

Enabling report.trip.newLogic replaces speed transitions with spatial clustering. Rather than asking whether the tracker is currently moving, the server asks whether it has moved away from where it last was. Motion begins once the tracker is far enough from its last reference point, and ends once it has stayed inside a small area for long enough.

The practical benefit is fewer false transitions during brief pauses, which makes the model a good fit for vehicles that spend time in dense traffic or wait with the engine running. Extended breaks in incoming data can also split a movement interval so that the resulting timeline stays realistic.

Parameter	Default	Purpose
report.trip.minDistance	200 m	How far the tracker must travel from its reference point before it counts as moving.
report.trip.minDuration	180 s	How long it must remain within a confined area before it counts as stopped.
report.trip.stopGap	3600 s	The silence after which movement may be split around the missing data.

Fast and slow report generation

Trips, stops and summary reports each have two implementations, and the server chooses between them from the length of the requested period. Beyond report.fastThreshold — one day by default — it uses the fast version; below it, the slow one.

Version	Method	Trade-off
Slow	Reprocesses every position in the period and recalculates trips and stops from scratch using the current settings.	Accurate, and it sorts positions correctly before analysing them. Costly over long periods.
Fast	Reuses the movement and stop events that were recorded live as the data arrived.	Much quicker, but some figures are missing — maximum speed comes back as zero — and any positions that arrived out of order leave the original events misplaced.

This explains a discrepancy people often notice: the same day can produce different trip lists depending on the range you request, and a configuration change will appear to have had no effect on a long report because the fast version is reading events that were recorded under the old settings.

Worked examples

Two reporting patterns account for most of the confusion around trip detection. Comparing them side by side shows why the platform needs more than a speed threshold to produce a sensible timeline.

Example 1 — a tracker that reports continuously

This is the common case: a unit with an internal battery, or one wired to a permanent supply, that keeps transmitting after the vehicle stops and may drop into a low-power mode once it has been still for a while.

Figure 3.2 — Continuous reporting. Trips are bounded by periods of zero speed, so both ends of each journey are unambiguous.

The first trip qualifies because the tracker was stopped beforehand, the journey exceeded the minimum distance or duration, and it was followed by a pause longer than the minimal parking duration. That pause becomes a stop for the same reasons. The short burst in the middle of it exceeds neither threshold, so it starts no trip and merely resets the detection counter; the second trip begins once movement is sustained.

Example 2 — a tracker powered only with the ignition

Units without a backup battery lose power when the engine is switched off. Each restart is a cold start, and the first positions typically arrive after the vehicle is already under way, so the trip begins at a speed well above zero. Applying the previous logic to this pattern would produce one endless trip.

Figure 3.3 — Ignition-powered reporting. With minimalNoDataDuration lowered to 600 seconds for this example, the silence itself is interpreted as a stop.

The preceding trip is detected correctly, because the gap supplies the ending that the speed data never does. The movement after the gap is not recorded: the period closes while the vehicle is still moving, so the server cannot tell when that journey ended, and only complete trips and stops are written to a report.

4. Permissions and groups

Nearly every object in the platform — devices, geofences, notifications, drivers, saved commands, calendars, maintenance schedules — carries its own permissions and can be attached to user accounts. Two kinds of relationship exist, and keeping them apart resolves most access problems.

Linking versus granting access

Linking an object to a device or group is a functional statement: it tells the platform what to do. Linking a geofence to a vehicle is what makes the platform watch that vehicle against that zone.

Linking an object to a user is an access statement: it says who may see, edit and subscribe to it. It never changes system behaviour.

The two are independent, and both are usually needed. A geofence linked only to a vehicle will generate events that nobody can see; a geofence linked only to a user is visible but inert.

Figure 4.1 — The two link types answer different questions. Neither substitutes for the other.

Where to manage links

All linking is done through the Connections option, which appears in the row menu of each list in the settings area. The list you start from determines what you are linking:

Start from	Use it to
Users list	Grant a user access to devices, groups, geofences, notifications and other objects. Available to administrators and managers.
Devices list	Attach objects to a single tracker, so that the platform applies them to that tracker alone.
Groups list	Attach objects to a whole group at once.

Shared objects

When an object is shared between several users, each of them holds full rights over it, deletion included. There is no read-only variant of a shared object. Where that is unacceptable, give each user their own copy instead of sharing one.

Devices are the exception, since two trackers cannot hold the same unique identifier and so cannot be duplicated. For this case there is a dedicated Device readonly setting on the user account, which lets a user see and use a tracker without being able to modify it.

Groups

A group is a collection of devices, and only devices — there is no equivalent grouping for other object types. Groups can be nested to any depth, and links applied to a parent flow down to trackers in its subgroups.

• To place a tracker in a group, edit the device and choose the Group field under Extra.
• To nest one group inside another, edit the child group and choose its parent Group in the same place.

Figure 4.2 — Nested groups. Links applied to a parent group reach every device beneath it, however deep the tree.

Nesting is the most economical way to manage a fleet of any size. A speed limit set on the top-level group applies everywhere; a stricter one set on a subgroup overrides it for those vehicles only. Building the hierarchy to match how the fleet is actually supervised — by region, by contract, by vehicle class — keeps the number of individual links small.

5. Commands

Commands run in the opposite direction to everything else in this guide: instead of the tracker reporting to the server, the server instructs the tracker. They are used to change configuration, alter the state of an output, or request information on demand.

Two delivery paths

A command can travel over the same network connection the tracker uses to upload data, or it can be sent as an SMS. Many trackers accept both, and the choice usually comes down to whether the unit is currently online.

SMS delivery has two prerequisites. The messaging service must be enabled on the server (ask us), and the device record must carry a correct value in its phone field. Without both, the option is unavailable.

Figure 5.1 — Delivery paths. Only network commands are queued; an SMS is dispatched immediately.

Protocol support and custom commands

The set of named commands a tracker accepts is determined by its protocol, so the list you see will differ from one model to another. Every protocol supports at least the custom command, which passes a raw string straight through to the tracker. Text-based protocols take it as plain text; binary protocols expect hexadecimal.

Results are returned by only some protocols. Where a result is received and decoded, the platform records a command result event, with the detail held in the result attribute. On protocols without result support, a command that was sent successfully will simply produce no confirmation, which is not in itself a sign of failure.

Queued commands

A network command addressed to an offline tracker is held in a queue and released the moment the tracker reconnects. The whole queue is then sent.

Saved commands

Any command that is sent regularly can be stored with its parameters already filled in, which is particularly valuable for custom commands whose syntax is long and easy to mistype. A saved command is created from the settings menu, linked to a device or a group, and then chosen by name from the send screen.

Figure 5.2 — The saved command workflow: define it once, attach it to the devices that should receive it, then select it by name.

Restricting who may send commands

By default every ordinary user can send any command their trackers support, including arbitrary custom strings. The Limit commands setting on a user account narrows this considerably: such a user may only send saved commands that have been linked to their account, and cannot compose new ones.

This is the standard arrangement for dispatchers and other front-line staff. They keep the ability to act — requesting a position, triggering an output — without any route to reconfiguring hardware, which is a category of mistake that usually requires physical access to undo.

Appendix A — configuration quick reference

Every setting introduced in this guide, in one place. Server parameters are set by our team in the platform’s server configuration; attributes can be applied by you to a group, an individual device or a geofence, with the most specific value winning.

Motion and trip detection

Parameter	Default	Applies to	Set by
report.trip.minimalTripDuration	300 s	Classic motion model	Our team (server)
report.trip.minimalTripDistance	500 m	Classic motion model	Our team (server)
report.trip.minimalParkingDuration	300 s	Classic motion model	Our team (server)
report.trip.minimalNoDataDuration	3600 s	Reports only	Our team (server)
report.trip.useIgnition	disabled	Classic motion model	Our team (server)
report.trip.newLogic	disabled	Selects the clustering model	Our team (server)
report.trip.minDistance	200 m	Clustering model	Our team (server)
report.trip.minDuration	180 s	Clustering model	Our team (server)
report.trip.stopGap	3600 s	Clustering model	Our team (server)
report.fastThreshold	86400 s	Report generation method	Our team (server)
speedThreshold	—	Deriving motion from speed	You (attribute)

Geofences

Parameter	Default	Applies to	Set by
geofence.polylineDistance	25 m	Polyline corridor width	Our team (server)
color	—	Map colour of a geofence	You (attribute)

Event thresholds (attributes — set by you)

Attribute	Controls
speedLimit	Speed limit exceeded event
fuelDropThreshold	Fuel drop event
fuelIncreaseThreshold	Fuel increase event
deviceInactivityStart	Device inactive event — when checking begins
deviceInactivityPeriod	Device inactive event — repeat interval
proximityEnterDistance	Proximity enter event; zero disables it
proximityExitDistance	Proximity exit event; zero disables it
unaccompaniedDistance	Unaccompanied motion event; zero disables it

Account settings

Setting	Effect
Device readonly	The user may view and use devices but not modify them.
Limit commands	The user may only send saved commands linked to their account.

If you manage other users for your fleet you can set these on their accounts; otherwise contact us and we will set them for you.

Troubleshooting checklist

• No geofence events? Confirm the zone is linked to the device or its group, not only to the user.
• Constant entry and exit on a route? Ask us to increase the polyline corridor width.
• Trips merged together? Ask us to lower the minimal trip duration and distance.
• A journey missing from a report? Extend the period past the point where the vehicle stopped.
• Duplicate alerts? Subscribe to either the server event or the device alarm, not both.
• Command had no effect? Check whether the tracker was online and whether the protocol returns results at all.

Still stuck? Call us on 0413 418 743 during business hours, email team@crucialtracking.com.au or request a callback and we’ll walk you through it.