Understanding the raw data file

The data warehouse tool enables you to export a raw data file containing all packets received from your device, without any filtering or calculations made on the platform side. These parameters represent information initially decoded from your device's packet in protocol related format, presented in a human-readable way. You don’t need to know the protocol to read and check the information in these packets.

To learn how to download this information, you can refer to our previous article. Here, we aim to explore further how to read this file and interpret various columns within it.

Opening a file

The filename always contains the following:

• Device ID: The device ID number, often representing its IMEI.

• Device’s label on the platform: A label to facilitate file searching.

• From and to time: Representing the start and end of the file in the format day_month_year_hours_minutes_AM/PM.

• Timezone in UTC format.

You can open the raw data file with any text editor, such as WordPad, Notepad++, or Sublime Text. This format is easily understood by programs and machines but may not be as clear for people. To simplify file reading, we recommend using a table editor. Simply open the CSV file with Excel, Google Sheets, or any other table editor. In the table editor, all parameters will be in their own columns. Additionally, you can freeze the first row to see the column names throughout the file.

Raw data parameters

The file will include selected parameters in columns, along with one consistent entry - msg_time.

These parameters can be categorized as simple or complex.

Simple columns

Simple parameters provide full names and mainly represent specific tracking information.

• msg_time: Time of the message sent by the device. Always included in CSV output. Indicated according to the chosen time zone.

• server_time: Time of message receipt by the server. Indicated according to the chosen time zone.

• gps_fix_type

  • NO_FIX: GPS tracker marked location as not valid.

  • HAS_FIX: GPS tracker marked location as valid.

  • LAST_KNOWN_POSITION: In case the tracker provides current input and other states within the last known location.

  • UNKNOWN: If a device can't provide such information or didn't determine GPS fix type for this packet.

• lat: Location latitude.

• lng: Location longitude.

• speed: Speed determined by the tracker in km/h. In most cases, it is speed determined by device’s GPS.

• alt: Location altitude in meters.

• satellites: Number of connected satellites at that moment; -1 means unknown and, in most cases, represents an LBS location point.

• heading: Object heading in degrees where 0 represent North.

• precision: Location precision in meters.

• hdop: Horizontal dilution of precision - represents the accuracy of GPS tracker’s horizontal position estimates. Values range from 1 (excellent) to above 20 (poor). Values between 1 and 2 are considered good for most navigational purposes. -1 means unknown.

• pdop: Position dilution of precision - indicates the accuracy of a GPS tracker's position based on the geometry of the satellites in relation to the tracker. Lower PDOP values mean better satellite positioning, leading to more accurate location data, but -1 means unknown.

• mn_name: Mobile network name. Determined by the device.

• mn_roaming: Roaming status. Is determined by the device.

  • 0 means no roaming,

  • 1 means this point was generated by a device in roaming,

  • If the device can't provide such data or couldn't do it for this particular message, it will be -1 (unknown).

• mn_code: Mobile network operator code. Determined by the device.

• mn_csq: Mobile network signal strength, CSQ, values from 0 to 31. Determined by the device. If the device can't provide such data or couldn't do it for this particular message, it will be 99 (unknown).

• mn_type: Mobile network type. Is determined by the device.

  • If the device can't provide such data or couldn't do it for this particular message, it will be UNKNOWN

  • GSM: If the device determined GSM type.

  • CDMA: If the device determined CDMA type.

  • WCDMA: If the device determined WCDMA type.

  • LTE: If the device determined LTE type.

  • NR: If the device determined NR type.

• event_id: The platform’s event ID. Find the list of all event ID codes below.

Complex parameters

Complex parameters include both the group name and specific name. They are categorized as follows:

• flags: A bitmap of flags representing location validity and LBS:

  • Bit 0 (location_valid): Indicates the validity status of the location. It is 0 if the location is invalid, and 1 if the location is valid.

  • Bit 1 (lbs): Indicates the LBS status of the point. If 0, the point is received by GPS; if 1, the point is received by LBS.

  • Bit 2 (soft_lbs): Indicates the source of the LBS point. If 0, the point is determined by device LBS; if 1, by the platform's LBS.

• discrete_inputs: Represents information from every discrete input. Each discrete input is presented in a separate column, enumerated from 1. The possible values are 1 and 0, where 0 signifies switched off, and 1 signifies switched on.

• discrete_outputs : Shows the same as discrete inputs but for discrete outputs. Each discrete output is in a separate column, enumerated from 1.

• inputs: Represents data from different sensors, such as fuel or various measuring sensors. Each input is in a separate column, and the list of inputs depends on the device model.

• states: Displays values from state parameters. Most of them can be 1 or 0, but some have specific text values like DTC codes.

With these definitions, we hope you'll find it easy to read information in raw data files and utilize them in device troubleshooting and in programs for your customers.