Firmware Product Guide
Firmware versions are published from one of three branches: Stable Release, Release Candidate, and Beta. The firmware branches are considered three separate copies of the firmware code base. The Stable Release branch, the most stable branch, aims to fix critical issues. The Release Candidate branch aims to fix issues to increase stability and may accept new features, when appropriate. The Beta branch, the most unstable branch, accepts all new features but may introduce instabilities. Please refer to the Firmware Release Notes document to review the release notes.
✱ NOTE: The Release Candidate branch will eventually become the Stable Release branch, and the Beta branch will eventually become the Release Candidate branch. Your telematics provider will create a new Beta branch when this occurs. This process occurs approximately every two months. See the Firmware Rollout Process for more details. |
The telematics device must be correctly installed to ensure functionality. For specific installation requirements, please refer to the Vehicle Specific Installation Notes.
In general and where appropriate, most data is saved through curve logging. Curve logging is a patented method of moving data efficiently from vehicle to server based on the Ramer-Douglas-Peucker algorithm. The purpose of the algorithm is to identify useless points and discard them, while preserving the most important information.
The device has three LEDs to indicate the status of the device:
When the device powers on for the first time after installation, it enters the Troubleshooting Beeping Mode to assist with the installation for the first two trips. The Troubleshooting Beeping Mode has various beep indications:
✱ NOTE: Device beeping can be enabled and configured through the Fleet Management Application. |
When the vehicle ignition is turned off, the device powers down and enters Sleep Mode. In Sleep Mode, the device periodically pings the server — similar to a heartbeat to ensure the device remains connected and checks for any pending firmware updates. The device heartbeats every 30 minutes for the first 72 hours. After three days, the device heartbeats once every 23 hours.
Firmware updates occur after an ignition off event or during heartbeats. The request for firmware update starts once the device has uploaded all of its data and the modem is about to go offline.
The device enters Disabled Mode by downloading a parameter while in Suspend or Terminate Mode. Upon entering the disabled state, the device resets and erases log data, accident data, and timestamp data from the flash memory. While disabled, the device does not create logs, update firmware, or detect ignition. The device does however, periodically connect to the Gateway servers in order to download new parameters. When a disabled device connects to the Gateway servers, it logs a disabled fault. The connection frequency of a disabled device is 12 hours after entering the disabled state, then every 23 hours thereafter. If a device is in Terminate Mode, the cellular account is canceled and the device is permanently disabled. In Suspend mode, the cellular account remains active so that it can download new parameters, and exit Disabled Mode once an active rate plan is applied.
For information about the engine status data collected by the telematics device, please refer to the Full List of Supported Engine Status Data sheet. The Vehicle Type and Engine Data sheet represents an overview of engine data for Odometer, Driver Seat Belt, Fuel Usage, and Fuel Level supported by the telematics device.
✱ NOTE: The percentages in the engine data columns are calculated based on the total number of vehicles in the field with telematics devices. |
Vehicles often use multiple sources to report data. When powered on, the device identifies all existing source variations, then selects the one most likely to provide accurate data. For engine data displayed on the instrument cluster (i.e. odometer, cruise control etc.), the firmware prioritizes the instrument cluster computer above other computers. The instrument cluster computer is prioritized because the end user often wants to see a representation of what is visually available in the vehicle rather than what is available in the engine computer.
Some vehicle data types are broadcasted by the vehicle while other data types require the device to send a request to the vehicle. If a device detects a connection issue with the vehicle, the device enters Listen Only Mode. In the Listen Only Mode, the device will not request any data, and therefore no longer log any vehicle data that must be requested.
✱ NOTE: A small number of vehicles sound an alert if any On-Board Diagnostic (OBD) third-party device requests data via the OBD port while the vehicle is locked and the ignition is off. As of firmware version x.27.x, Telematics Device version 9 disables this alert by default in order to provide full access to data according to the rate plan, without risk of sounding the alert. For more information, including how to verify and control the alert’s status, please consult the OBD Port Audible Alert FAQ. |
The VIN is a standard request and is available on most vehicle types. Some vehicles do not reply to the VIN request or reply with an invalid VIN number. If we do not receive a valid VIN from the vehicle, we save the VIN as 0 s.
The Fleet Management Application uses Device Total Fuel and Device Total Idle Fuel to calculate fuel economy, and Fuel Level (percentage or volume) to calculate fill up events.
The device flash memory saves the Device Total Fuel values to ensure the data is retained after a firmware update or power cycle of the telematics device. If the telematics device is moved to a new vehicle — detected by a change in VIN — the Total Fuel values are reset to 0. The Device Total Fuel is both curved logged and logged after ignition is turned OFF.
The telematics device goes through a comprehensive Seat Belt data detection and verification process. The process normally takes three trips for the seat belt data to validate. Each trip must last longer than one minute and include driving — at a speed greater than 10 km/hr — to consider the data as part of the validation process. For data detection, the device needs to recognize seatbelt changes. Seat belt changes occur during ignition events.
✱ NOTE: The Seat Belt data detection and verification process may take longer if there are multiple sources of seat belt data on a particular vehicle type. |
When the telematics device first powers on, a seat belt value of -1 indicates the value is unknown and prevents the Fleet Management Application from creating an ongoing Seat Belt Unbuckled exception — until the seat belt is re-detected. On every ignition change event, if the seatbelt was previously in a buckled or unbuckled state, the seat belt status is set to Unknown. Setting the seat belt data to unknown ensures that the data from previous trips is not carried over to the present trip.
The Telematics Device has a three-stage odometer detection process. In the first stage, the device attempts to locate the odometer information. Once a possible source for the odometer is found, the device begins the second stage to ensure that the data values increment properly. The second stage requires at least 0.5 km of driving to complete verification. In the third stage, the device uses GPS data to verify the odometer unit over at least 5 km of driving. Stage 2 and 3 can be done over multiple trips.
The Odometer is logged for every ignition ON, ignition OFF, and at every two (2) km or every one (1) km — if the GPS is invalid. Odometer validation occurs every time we receive an odometer value to ensure the odometer does not jump 15 km forwards or backwards between readings. If this happens twice during two trips with no recovery — i.e. the odometer does not return to its value within 15 km — an invalid odometer fault is logged and the telematics device stops reporting the odometer values.
To record the vehicle’s crank voltage curve, 10 seconds of instantaneous voltage logs are saved using the curve algorithm at every ignition ON event. An average voltage value is saved whenever it changes by 250 mV or more. If the vehicle voltage falls below 11.6 V for five minutes, the device logs a Low voltage warning fault and forces a heartbeat to ensure the low voltage value is communicated. 11.6 V is the default value and can be changed through a parameter. Heartbeats switch to every 23 hours once this has occurred to help preserve battery power. If the vehicle voltage is consistently lower than 7 V, the telematics device remains in Low Power Mode and will not operate until the voltage rises above 8V.
Oil pressure is saved using curve logic under the following conditions:
Vehicle ignition status is detected by the device using one of the following three methods:
The device first wakes up by detecting voltage spikes or accelerometer-based movement and then uses RPM or Engine Road Speed to determine ignition status.
The device is connected via the special three-wire harness: power, ground, and ignition. The harness ignition connection is responsible for setting the ignition state.
If the device does not receive engine data or is not connected to a three-wire harness, then the device attempts to determine ignition based on a logic called Trip Tracking. Another logic, called Two-Wire, is more voltage-focused and can be used to determine ignition — enabled through a custom parameter.
The accelerometer is calibrated while the vehicle is driven. As a result, there are no orientation restrictions when installing a telematics device for the accelerometer to work. The device must be securely installed for the accelerometer data to remain consistent. Because of real-time calibration, it can take one or two trips to calibrate the accelerometer. In addition, calibration relies on GPS data and may take longer to calibrate if the device is in an area with weak GPS signals. Accelerometer data is sampled at 100 Hz and saved using the curve-based algorithm. The accelerometer ranges from −8 g to +8 g with a resolution of 4 mg/bit for version 8 devices and earlier, and 0.244 mg/bit for version 9 devices.
Telematics devices that are not securely installed have less reliable accelerometer behavior and may potentially not calibrate. Mounting the device to a surface with excessive vibration or contact may generate immoderate and/or incorrect accelerometer data. The telematics device can detect excessive accelerometer data and stops logging accelerometer data when excessive data collection occurs. A telematics device fault is saved at the time of the excessive logging detection.
Once calibrated, the accelerometer is virtually oriented as follows:
The accelerometer constantly logs events over 300mg in the X-axis (front/back) or Y-axis (side/side) direction using the curve-based logging algorithm. The constant logging ensures that as long as you set your rules to a minimum of 300 mg, the events are always observed.
Beeping for driver feedback on harsh driving events is configured in the Fleet Management Application. Different thresholds are available for acceleration, braking, and cornering. No feedback is provided when the vehicle is traveling under 10 km/h.
A separate accident data memory buffer is used to store second-by-second data. The data is only uploaded when there is an accelerometer event with a combined X/Y magnitude over 2.5 g. Also, if the Z-axis values becomes negative, the device detects a possible rollover event which triggers an accident event. Only four accident data buffer uploads can occur per trip. Custom parameters can be used to change the value of 2.5 g, but please note that the value cannot be set to less than 1.9 g. Although accelerometer data may be disabled due to excessive logging, accident level accelerometer data is still logged.
Accelerometer data during an accident is logged using the curve, with no accident-specific logic. The curve logic detects that there is a change in acceleration and sends the appropriate accelerometer points. Accelerometer data logic must be enabled as part of the Rate Plan (i.e accident accelerometer data is not available on the Base Plan but the fault will be logged).
The accelerometer can be used to detect reverse if you do not receive gear data from the vehicle’s engine computer. The device determines that the vehicle is out-of-reverse if the vehicle is stopped for five seconds or if the vehicle starts moving forward. Reverse detect is logged as follows:
Curve-based logging is performed for both GPS position and GPS road speed to ensure the best fit on the map, as well as an accurate speed profile and idle time.
The following are default error values for the curve logging:
✱ NOTE: An estimate error is used to predict where the value should be based on the last saved GPS record, and then compares the current point with the estimated point to determine if it should be logged. |
If GPS data is invalid, the road speed curve logging is performed using engine-based road speed. Latitude and longitude are used to validate GPS-based road speed.
If movement is detected by the accelerometer while ignition is off, the GPS is turned on and checks if the latitude or longitude changes by a sufficient amount (approximately 100 m). If the device detects a sufficient change in distance, the trip is tracked and the modem connects (if it’s a live unit), and remains connected until the device stops moving.
The telematics device obtains the latitude and longitude directly from the GPS module. To consider a GPS position from the GPS module valid, the following conditions must be met:
Please refer to this document for a list of notices for included firmware/software libraries.