Navixy Generic Protocol 1.1a

This document describes Navixy Generic Protocol v.1.1a with a combined (simple and enhanced) custom sensor structure. The description includes the basic 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: General Availability - Standard data structures with foundational telematics and sensor data support.
2024-10-25	Version 1.1a: Early release for advanced data structures and enhanced custom attributes support. Enhanced custom attributes, available exclusively in version 1.1a, open up new possibilities for users to integrate diverse sensor data and custom configurations.

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 MQTT and HTTP/HTTPS as transport layers, ensuring flexibility and scalability for various devices and systems. These popular protocols are easy to implement, simple to debug, and don't take much time to get started.

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:

CODE

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:

CODE

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:

CODE

{
   "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: HAS_FIX NO_FIX LAST_KNOWN_POSITION FIX_2D FIX_3D 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 `GSM`, `CDMA`, `WCDMA`, `LTE` and `NR`. Default is `GSM`.
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).
Simple custom data
custom_attribute	Mixed	Root	No	Any additional custom data in simple format `“name"`: `value` where name should be instead of custom_attribute. There may be as many custom attributes as you want. This structure should be used for cases when `"name"`: `value` pair is enough. For other cases we recommend to use Enhanced custom attributes structure below.
Enhanced custom attributes
custom_attributes	Array [Object]	Root	No	All custom parameters should be put into the custom_attributes array of JSON objects.
└─ type	String	custom_attributes	Yes	Parameter that indicates the attribute’s name.
└─ id	Integer	custom_attributes	No	Identifier that shows the attribute order number.
└─ value	Mixed	custom_attributes	Yes	Value of the extended attribute that can have any data type.
└─ units	String	custom_attributes	No	If necessary units of measurement can be specified in this parameter.

Version 1.1a enables users to incorporate a wider range of custom attributes, allowing greater flexibility in how unique data points are represented.

Custom attributes

The last two sections of the table outline both simple and enhanced structures for custom attributes, which facilitate the transmission of any custom data. This enables you to extend the protocol by introducing your own custom data, which will be transmitted without alteration. Additionally, you have the flexibility to combine both approaches for utilizing custom attributes, depending on your needs.

The following example shows a message containing both structures.

CODE

{
 "message_time": "2024-09-02T12:23:45Z",
    "device_id": "857378374927457",
    "version": "1.0",
    "location": {
        ...
    },
    "custom_fuel": 86,
    "custom_attributes": [{
            "type": "engine_rpm",
            "id": 1,
            "value": 2100,
            "units": "rpm" 
            }
    ]
}

Message example

A typical GPS device telemetry message with some optional custom attributes will follow this format:

CODE

{
    "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": 34.15929687705282,
        "longitude": -118.4614133834839
        "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,
    "custom_attributes": [{
            "type": "custom_distance",
            "id": 2,
            "value": 4685,
            "units": "meters" 
            },
            {
            "type": "cold_chain_humidity",
            "id": 1,
            "value": 95,
            "units": "rh"
          }
    ]
}

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