Navixy Generic Protocol 1.0
This document outlines the Navixy Generic Protocol, covering its fundamental data structures, format, and transport layer.
The Navixy Generic Protocol is freely available and can be adopted by manufacturers of GPS and IoT devices as the primary protocol for transmitting data between their hardware and telematics platforms.
Change log
Date | Description |
|---|---|
2024-09-03 | Version 1.0 |
Purpose
The primary function of this protocol is to facilitate the efficient transmission of telematics data, particularly location information, between clients and servers. Its straightforward and adaptable message structure allows for easy expansion with various data types.
Additionally, this protocol can be employed to send data from a wide range of devices, including IoT devices, GPS trackers, terminals, and gateways that aggregate messages from other devices.
Transport layer
The Navixy Generic Protocol supports both MQTT and HTTP/HTTPS as transport layers, ensuring flexibility and scalability for various devices and systems.
HTTP/HTTPS
Navixy Generic Protocol supports HTTP/HTTPS version 1.1 and 2.0 as a transport method. This is a common, well-known, and user-friendly option for developers and technicians. Below are the HTTP/HTTPS parameters and headers used for Navixy Generic Protocol:
Method: POST
Body: UTF-8 encoded JSON text
Content-Type: application/json
Moreover Navixy Generic Protocol supports response codes for HTTP that telematics platform can send in reply to the HTTP request:
200 OK - message received successfully.
400 BAD_REQUEST - invalid request body, e.g. broken JSON of incorrect format.
403 FORBIDDEN - unknown device identifier. Please check the device identifier that is specified in the data packet.
500 INTERNAL_SERVER_ERROR - unexpected server error. Something went wrong on the server. Please contact the technical support team of the recipient’s side.
For your convenience below you can find the CURL example of possible HTTP request:
curl --location 'tracker.navixy.com:47642' \
--header 'Content-Type: application/json' \
--data '{
"message_time": "2024-10-10T06:00:11Z",
"device_id": "1112312212",
"location": {
"latitude": 34.15929687705282,
"longitude": -118.4614133834839
},
"battery_level": 68
}'MQTT
The Navixy Generic Protocol uses MQTT, a proven, lightweight, and scalable messaging protocol, to ensure reliable data delivery over TCP.
The protocol supports MQTT 5.0 and MQTT 3.1.1, offering flexibility and compatibility with various devices and systems. To guarantee message delivery, two Quality of Service (QoS) levels are available:
QoS 0: Messages are delivered at most once, suitable for applications where occasional message loss is acceptable.
QoS 1: Messages are delivered at least once, ensuring reliable delivery.
All message bodies must be encoded as UTF-8 JSON text, containing a single JSON object per message. Responses to messages are not currently supported. To maintain data integrity, Navixy strictly validates incoming messages, discarding those with invalid JSON or attributes that exceed defined value ranges.
As a reference you can use example of sending a message via Mosquitto client:
mosquitto_pub -h mqtt.eu.navixy.com -p 1883 -u ngp_device -P secretword -t "ngp/1112312212" -m "{ \"message_time\": \"2024-10-10T07:09:11Z\", \"device_id\": \"1112312212\", \"version\": \"1.0\", \"location\": { \"fix_type\": \"HAS_FIX\", \"latitude\": 34.15929687705282, \"longitude\": -118.4614133834839, \"altitude\": 244, \"satellites\": 8, \"speed\": 43, \"heading\": 77 }, \"battery_level\": 68, \"input_status\": 7, \"output_status\": 5, \"custom_parameter_int\": 123}""Data types
Type | JSON | Description | Examples | Limitations |
|---|---|---|---|---|
Integer | Number | Integer numeric values | Bit masks, counters, impulses, passengers and RPM | From 1 to 8 byte signed or unsigned integer number |
Float | Number | Numeric floating-point values | Coordinates, telemetry, speed, altitude, mileage | Up to 8 byte signed float number (IEEE 754) |
String | String | UTF-8 encoded text string | Driver's name, registration number, driver ID | Up to 10KB escaped text |
Boolean | Boolean | Values true or false | CAN attributes states: ignition state, doors state, presence of movement, etc. | True or false |
Timestamp | String | Date and time value in ISO 8601 UTC format | Date and time when the coordinate was received by the device | ISO 8601 related restrictions |
Blob | String | Binary data in Base-64 format | Photo, raw data from sensors, BLE data, Voice | Up to 1 MB encoded binary data |
Array | Array | A list of objects with identical types | Mobile cells, Wi-fi points | No limitations |
Object | Object | Structures that consist of several attributes | Location data, Mobile cell, Wi-fi point | No limitations |
Timestamps and data encoding
All timestamps must adhere to the ISO 8601 format.
Example:
"message_time": "2024-09-02T23:59:59Z"
For raw data such as sensor readings, tachograph logs, images, or audio, binary transmission is supported. When transmitting binary data, it must be Base64-encoded.
Examples:
"my_sensor_data": "SGVsbG8gd29ybGQh""tachograph_log": "U29tZSB0YWNoZW9nIGxvZw==""photo": "/9j/4AAQSkZJRgABAQEAYABgAAD...""audio": "UklGRjIAAABXRUJQVlA4WAoAAAAQAAAA..."
By adhering to these standards, the protocol ensures universal understanding of timestamps and reliable transmission of binary data. Keep in mind, the protocol is not optimized for large binary payloads within messages.
Message processing and structure
Messages are processed sequentially and follow a straightforward JSON structure. Each message includes two mandatory attributes: device_id and message_time.
Minimum possible message:
{
"message_time": "...",
"device_id": "..."
}This example demonstrates the basic structure of a message with only the mandatory attributes. You can then add optional attributes as needed based on the specific protocol and device type.
Attributes
Attribute | Type | Object | Required for object | Description |
|---|---|---|---|---|
Basic attributes | ||||
message_time | Timestamp | Root | Yes | Date and time the message was sent by a device. |
device_id | String | Root | Yes | A unique device identifier. Max size 64 characters. |
version | String | Root | No | Version of this protocol (JSON structure). If the version attribute is not specified, v1.0 will be used by default. |
Location information | ||||
location | Object | Root | No | Contains details about the device's GPS location. |
└─ gnss_time | String | location | No | Time when coordinates were registered by the device. |
└─ latitude | Float | location | No | Latitude in degrees (-90.0 to 90.0). |
└─ longitude | Float | location | No | Longitude in degrees (-180.0 to 180.0). |
└─ altitude | Float | location | No | Altitude above sea level in meters (-1000 to 10000). |
└─ fix_type | String | location | No | Location fixation type. Possible values are:
Default is HAS_FIX. |
└─ satellites | Integer | location | No | Number of satellites involved in positioning (0 to 64). |
└─ hdop | Float | location | No | Horizontal dilution of precision, a measure of GPS accuracy. |
└─ vdop | Float | location | No | Vertical dilution of precision, a measure of altitude accuracy in GPS. |
└─ pdop | Float | location | No | 3D position dilution of precision, combining horizontal and vertical accuracy. |
└─ speed | Float | location | No | Device's speed in km/h (positive value). |
└─ heading | Integer | location | No | Heading in degrees, azimuth, direction of movement (1 to 360). |
Event information | ||||
event_id | Integer | Root | No | Platform event identifier. For a full list of possible values, see Appendix 1. |
Mobile cells | ||||
mobile_cells | Array [Object] | Root | No | List of visible cell towers. |
└─ mcc | Integer | mobile_cells | Yes | Mobile Country Code that identifies the country of the mobile network. |
└─ mnc | Integer | mobile_cells | Yes | Mobile Network Code that identifies the specific mobile operator in the country. |
└─ lac | Integer | mobile_cells | Yes | Location Area Code, which helps identify the area in the mobile network. |
└─ cell_id | Integer | mobile_cells | Yes | Unique identifier of the mobile cell tower. |
└─ rssi | Integer | mobile_cells | No | Signal strength from the mobile tower, measured in dBm (negative values). |
└─ type | String | mobile_cells | No | The mobile radio type. Supported values are |
Wi-Fi points | ||||
wifi_points | Array [Object] | Root | No | List of visible Wi-Fi access points. |
└─ mac | String | wifi_points | Yes | MAC address (hardware identifier) of the Wi-Fi access point. Each byte is delimited with a colon (e.g., 12:33:FF:45:04:33). |
└─ rssi | Integer | wifi_points | Yes | Signal strength from the Wi-Fi access point, measured in dBm (negative values). |
└─ age | Integer | wifi_points | No | Time in milliseconds since this Wi-Fi access point was last discovered. |
└─ channel | Integer | wifi_points | No | Radio channel number used by the Wi-Fi access point. |
Device motion and status | ||||
is_moving | Boolean | Root | No | Indicates whether the device is currently moving (True or False). |
hardware_mileage | Float | Root | No | Mileage counted by the device's hardware in kilometers. |
battery_voltage | Float | Root | No | Built-in battery voltage in volts. |
battery_level | Integer | Root | No | Current built-in battery level as a percentage (0 to 100). |
board_voltage | Float | Root | No | Voltage supplied by the external power source in volts. |
Input/Output status | ||||
input_status | Integer | Root | No | Current status of the device's discrete inputs, represented as a bitmask. |
output_status | Integer | Root | No | Current status of the device's outputs, represented as a bitmask. |
Sensor data | ||||
analog_n | Float | Root | No | Analog input voltage (volts). Where n stands for the ordinal number of the attribute and n = 1..16. |
temperature_internal | Float | Root | No | Temperature from the built-in hardware sensor (degrees Celsius). |
temperature_n | Float | Root | No | External temperature sensor (degrees Celsius). Where n stands for the ordinal number of the attribute and n = 1..16. |
humidity_internal | Float | Root | No | Relative humidity from the built-in hardware sensor (percentage). |
humidity_n | Float | Root | No | External relative humidity sensor (percentage). Where n stands for the ordinal number of the attribute and n = 1..16. |
fuel_level_n | Float | Root | No | Fuel level from fuel sensor (liters or percentage). Where n stands for the ordinal number of the attribute and n = 1..16. |
fuel_temperature_n | Float | Root | No | Fuel temperature from fuel sensor (degrees Celsius). Where n stands for the ordinal number of the attribute and n = 1..16. |
impulse_counter_n | Integer | Root | No | Impulse counter sensor. Where n stands for the ordinal number of the attribute and n = 1..16. |
Identification data | ||||
hardware_key | String | Root | No | Driver ID, typically read via RFID, iButton, or other identification methods. |
vin | String | Root | No | Vehicle Identification Number (VIN). |
Custom data | ||||
custom_attribute | Mixed | Root | No | Any additional custom data described below. |
Custom attributes
The table's final section refers to custom data. The protocol allows for hardware-specific attributes like avl_io_n or flex_id, which are transmitted without alteration.
You can also expand the protocol by adding your own custom data, which will be passed through unchanged.
The following example shows a message containing a custom data attribute. Custom attributes, like the custom_attribute in the example, are added directly to the root of the message structure.
{
"message_time": "2024-09-02T12:23:45Z",
"device_id": "857378374927457",
"version": "1.0",
"location": {
...
},
"custom_attribute": 123.44
}Message example
A typical GPS device telemetry message will follow this format:
{
"message_time": "2024-09-02T10:03:43Z",
"device_id": "857378374927457",
"version": "1.0",
"location": {
"gnss_time": "2024-09-02T10:03:41Z",
"fix_type": "HAS_FIX",
"latitude": 56.348579,
"longitude": 60.12344,
"altitude": 271,
"satellites": 8,
"hdop": 0.41,
"pdop": 2.0,
"speed": 43,
"heading": 77
},
"event_id": 2,
"mobile_cells": [{
"mcc": 250,
"mnc": 0,
"lac": 32445,
"cell_id": 343455,
"rssi": -54,
"type": "LTE"
}
],
"wifi_points": [{
"mac": "12:33:FF:45:04:33",
"rssi": -54,
"age": 4002,
"channel": 11
}
],
"is_moving": true,
"hardware_mileage": 7382.3,
"battery_voltage": 4.12,
"battery_level": 93,
"board_voltage": 13.9,
"input_status": 23424,
"output_status": 23424,
"hardware_key": "12FFABC54234",
"temperature_internal": 12.3,
"temperature_2": -13.7,
"custom_attribute": 123.44
}Appendix 1. Predefined event identifiers
The following event identifiers (event_id) are recommended. For events not listed below, it's advised to use identifiers starting from 10,000 and increase them sequentially.
Power
The range for power alerts is 1 – 100.
Event id | Description |
|---|---|
1 | Low battery |
2 | Power lost or external power cut |
3 | Power On button pressed |
4 | Power recovered or external power connected |
5 | OBD Unplug from the car’s connector |
6 | OBD Plug in |
7 | Device’s backup battery low |
8 | Device wakes up from a sleep mode |
9 | Sleep mode start |
10 | Timer wakeup |
11 | Motion wakeup |
12 | External power wakeup |
13 | Power Off button pressed |
14 | Device power Off |
15 | Device power On |
Security
The range for security alerts is 101 – 200.
Identifier | Description |
|---|---|
101 | Unauthorized movement event determined by the device (tow detection) |
102 | Unauthorized movement end |
103 | Device detached from the tracked object |
104 | Car alarm |
105 | Device’s case closed |
106 | Device’s case opened |
107 | Unplug from the tracked object |
108 | Attach device to the tracked object |
109 | Door alarm |
110 | Device’s lock closed |
111 | Device’s lock opened |
112 | Vibration end |
113 | Vibration start |
114 | Strap bolt Inserted |
115 | Strap bolt cut |
116 | GPS jamming |
117 | GSM signal jamming alarm |
118 | Bracelet open |
119 | Bracelet closed |
120 | G sensor alert |
Safety
The range for safety alerts is 201 – 300.
Identifier | Description |
|---|---|
201 | Emergency contact number called |
202 | SOS button pressed event |
203 | Cruise control switched on |
204 | Cruise control switched off |
205 | DMS. Driver not identified |
206 | DMS. Driver identified |
207 | ADAS. Frequent lane change |
208 | DMS. Device can't detect human face |
209 | Seat belt unbuckled |
210 | DMS. Driver is drinking |
211 | DMS. Driver eyes are closed |
212 | DMS. Report new driver detection |
213 | DMS. Driver enters cabin |
214 | DMS. Start driver absence |
215 | DMS. Driver stopped smoking (Driver distraction) |
216 | DMS. Driver started smoking (Driver distraction) |
217 | DMS. Driver finished using the phone (Driver distraction) |
218 | DMS. Driver started using the phone (Driver distraction) |
219 | DMS. Yawning detected (Fatigue driving) |
220 | DMS. Driver stopped distraction (Driver distraction) |
221 | DMS. Driver started distraction (Driver distraction) |
222 | DMS. Driver stop drowsiness (Fatigue driving) |
223 | DMS. Driver start drowsiness (Fatigue driving) |
224 | Over speeding |
225 | Unexpected movement start |
226 | Unexpected movement end |
227 | ADAS. Peds in danger zone |
228 | ADAS. Traffic sign recognition |
229 | ADAS. Peds collision warning |
230 | Fatigue driving |
231 | ADAS. Headway warning |
232 | ADAS. Right lane departure |
233 | ADAS. Left lane departure |
234 | ADAS. Lane departure |
235 | ADAS. Forward collision warning |
236 | Harsh driving quick lane change |
237 | Harsh driving acceleration and turn |
238 | Harsh driving braking and turn |
239 | Harsh driving turn |
240 | Harsh driving acceleration |
241 | Harsh driving braking |
242 | Crash alarm |
243 | Harsh driving |
244 | Call button pressed |
Vehicle efficiency
The range for vehicle efficiency alerts is 301 – 400.
Identifier | Description |
|---|---|
301 | Idle end |
302 | Idle start |
303 | Check engine light |
Track information
The range for track information alerts is 401 – 500.
Identifier | Description |
|---|---|
401 | Track. No specific event, just a track point |
402 | GSM LBS point report |
403 | Track point by time |
404 | Track point by distance |
405 | Track point by angle |
406 | Track movement start |
407 | Track movement end |
408 | Non-track message |
409 | Tracker entered auto geofence |
410 | Tracker exited auto geofence |
Inputs
The range for inputs is 501 – 550.
Identifier | Description |
|---|---|
501 | Input 1 state changed |
502 | Input 2 state changed |
503 | Input 3 state changed |
504 | Input 4 state changed |
505 | Input 5 state changed |
506 | Input 6 state changed |
507 | Input 7 state changed |
508 | Input 8 state changed |
Outputs
The range for outputs is 551 – 600.
Identifier | Description |
|---|---|
551 | Output 1 state changed |
552 | Output 2 state changed |
553 | Output 3 state changed |
554 | Output 4 state changed |
555 | Output 5 state changed |
556 | Output 6 state changed |
557 | Output 7 state changed |
558 | Output 8 state changed |
Peripherals and other
The range for inputs and outputs alerts is 601 – 700.
Identifier | Description |
|---|---|
601 | Antenna disconnected |
602 | Accessory disconnected |
603 | Accessory connected |
604 | Ignition Off |
605 | Ignition On |
606 | Light sensor determined dark |
607 | Light Sensor determined bright |
608 | GPS signal recovered |
609 | GPS signal lost |