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 such as speedLimit or color are applied by you, in the platform, on a device, a group or a geofence — the most specific value wins.
• Where a section says 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 up for you. Tell us what you are trying to achieve; 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 or on a group, 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.

Two 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?”, and a polyline answers “did the vehicle stay on this route?”.

To watch a single site — a depot, a customer’s premises, a worksite — draw a polygon around it. A handful of points that follow the boundary is easier to maintain than a detailed outline and works just as well: the platform only needs to know whether a position falls inside the shape.

Figure 2.1 — The two supported geometries. Both are drawn point by point on the map: a polygon closes back on itself to enclose an area, while a polyline stays open and is given its width by the corridor setting below.

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 25 metres by default.

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 a vehicle repeatedly leaves and rejoins a route it clearly drove, the drawn line is usually the cause — redraw the polyline so it follows the carriageway closely.

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

Polygons and polylines 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 draw a small polygon around the origin and another around the destination. The polyline reports departures from the corridor; the two polygons mark the beginning and the end of the journey.

Figure 2.2 — Route supervision. Polygon 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 worked out by the platform from the stream of positions, using a small set of rules. Knowing those rules is the difference between reports that match the driver’s day and reports that do not.

Moving or stopped

The platform keeps a simple state for each tracker: moving or stopped. Some trackers report movement directly. For the rest, the platform judges it from the speed they report. The speedThreshold attribute sets the speed above which the platform counts a tracker as moving.

How the state changes

The state changes only when a condition holds continuously. A stopped tracker becomes moving once its movement is sustained — by default about five minutes or about 500 metres, whichever comes first. A moving tracker becomes stopped once it has been still for about five minutes. Any interruption resets the count 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.

Two further rules cover what speed alone cannot. A long silence from the tracker — about an hour by default — is treated as a stop in reports, so a unit that loses power still gets a sensible end to its trip. And on trackers that report ignition, we can set the platform to end a trip the moment the ignition goes off.

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

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. In this example the platform treats a silence of ten minutes as a stop, so the gap itself is read as the 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.

How commands reach the tracker

A command travels over the same data connection the tracker uses to upload its positions. If the tracker is online, it receives the command straight away. If it is offline, the command is queued and delivered when the tracker next connects — see “Queued commands” below.

Figure 5.1 — Delivery. A command to an offline tracker is queued and released the moment it reconnects.

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. These are attributes you apply to a group, an individual device or a geofence, with the most specific value winning.

Motion and trip detection

Attribute	Controls
speedThreshold	Whether a tracker counts as moving, for trackers that do not report movement themselves

Geofences

Attribute	Controls
color	Map colour of a geofence

Event thresholds

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.
• 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.