Contact us Login LIVE DEMO FREE TRIAL

Mobile tracker

Introduction

The protocol is implemented directly on top of TCP. Client connection to the server is established and terminated as needed.

Incoming and outgoing data streams are asynchronous and must be processed in parallel and independently (except defined cases).

The protocol is binary (that means that in general case arbitrary set of bytes is transferred), all multi-byte data types (For example, long, float etc. ) should be sent as big-endian (at first most-significant bytes are transferred and then least significant ones).

Data types

The packet consists of a set of fields, each of which has a certain type.

Name Description Length, byte
unsigned byte Unsigned integer, value range from 0 (00) to 255 (FF) 1
unsigned short Unsigned integer, value range from 0 (00 00) to 65535 (FF FF) 2
long Signed integer, value range from -2^63^ to 2^63^-1 8
byte[] unsigned short, contains the length of the byte array (N), then N byte of arbitrary binary data 2+N
float Floating-point number, recorded according to IEEE 754 (single precision) standard 4
double Floating-point number, recorded according to IEEE 754 (double precision) standard 8
utf-8 string unsigned short, contains the length of the byte array (N), then N byte, containing a UTF-8 encoded string 2+N
tiny utf-8 string unsigned byte, contains the length of the byte array (N), then N byte, containing a UTF-8 encoded string 1+N
timestamp long – number of the milliseconds which passed since 01.01.1970 00:00:00 UTC 8

Packets

All transmitted information to both sides is divided into packets (you should not confuse them with TCP/IP level packets, one “logical” packet of Navixy protocol can consist several “physical” TCP/IP packets).

At the beginning of each packet unsigned short field is added when transferring a packet, this field contains the length of this packet in bytes.

For example, the package with 5 zero bytes would look as follows (HEX):

00 05 00 00 00 00 00

Thus, the maximum length of a packet makes 65535 byte.

The set of fields that are included in the packet is determined by its type. Type – is the first byte of every packet (unsigned byte).

A packet can be outgoing (if it is sent from a tracker to the server) and incoming (if on the contrary).

Backward compatibility

Packets of unknown type shouldn’t lead to mistakes, they should be ignored.

It is necessary to process all known fields in packets containing more fields than described in the protocol, extra fields should be ignored.


INIT_PACKET packet

It is sent by a tracker to the server right after TCP connection establishment. Serves for identification of a tracker and synchronization of settings with the server.

  • Direction: outgoing

Fields

Name Description Type
type 0 (for current packet) unsigned byte
deviceId The unique digital identifier of a device, usually IMEI long
protocolVersion Protocol version. In this document the protocol of the version 4 is described unsigned byte
controlsData Data on the current configuration of additional buttons (see further for more details). byte[]

Example (packet for the device with deviceId=1234 and empty controlsData):

00 00 00 00 00 00 00 04 D2 00 00

STATUS_REQUEST packet

Sent by the server to query data from the device on the battery charge level, GSM-signal, etc.

In reply the device has to send a STATUS_RESPONSE packet.

  • Direction: incoming

Fields

Name Description Type
type 2 (for this packet) unsigned byte

Packet always looks like that:

02

STATUS_RESPONSE packet

It is sent by a tracker in response to STATUS_REQUEST.

  • Direction: outgoing

Fields

Name Description Type
type 2 (for this packet) unsigned byte
battery Battery charge level, from 0.0 (minimum) to 1.0 (maximum) float
signal GSM-signal level, from 0 (absent) to 31 (maximum) unsigned byte
roaming 1, if a tracker is in roaming, 0 otherwise unsigned byte
network GSM-network name, empty string, if the network is unavailable utf-8 string

RECORDS_PACKET packet

It is sent by a tracker to transfer the data about movements. It is used both for transfer of contemporary records, and for the on-line mode.
Records about movements have to be transferred in an order “from old to new” (the oldest records are transferred at first). It is not recommended to transfer more than 10 records in one packet.

  • Direction: outgoing

Fields

Name Description Type
type 1 (for this packet) unsigned byte
deviceId The unique digital identifier of a device, usually IMEI long
numRecords Number of records about location (N) unsigned byte
records N records about location, which structure is described below

Structure of one record of location

Name Description Type
lng Longitude location in degrees from -180.0 to 180.0 double
lat Latitude location in degrees from -90.0 to 90.0 double
speed Speed in km/h unsigned short
heading The direction of the movement in degrees, from 0 to 359 unsigned short
satellites Number of visible GPS satellites unsigned byte
eventId Code of the event which entailed record creation (see the table below) unsigned short
time Record creation time (according to GPS) timestamp

Protocol version 2+

inputStatus Bit mask of conditions of discrete inputs (buttons), for more details see below. Example: for active 1 and 3 inputs mask equals to 5. unsigned short

Protocol version 4+

locationSource Source of navigation data 0 – GPS, 1 – GSM LBS, 2 – unknown unsigned byte
locationRadius Accuracy of determination of location, radius in meters unsigned short

Protocol version 5+

requestedLocationSource Required source of navigation data 0 – GPS, 1 – GSM LBS unsigned byte

Codes of events

Code Description
2 Record of a track in the continuous mode
34 Record of a track in the interval mode
10+N (11…18) Change of a condition of N discrete input
83 SOS button click

Protocol version 5+

Code Description
41 Tracking switching off
42 Tracking switching on
802 Point by time
803 Point by distance
804 Point by angle

CONTROLS_PACKET packet

It is sent by the server in case the configuration of additional buttons is changed.

  • Direction: incoming

Fields

Name Description Type
type 3 (for this packet) unsigned byte
controlsData Data on the current configuration of additional buttons (for more details see further). unlike INIT_PACKET, doesn’t contain length of the array of bytes. It is necessary to read out all contents of a packet up to the end. byte…

The description of the packet connected with a chat is absent, because of incomplete support of the server functionality with the interface.


controlsData field

The field contains a set of structures of “control” type, going one after another. Each similar structure represents “a packet in a miniature”, and like packets, is preceded with unsigned short field with the length of data in structure (in bytes), and the first one-byte field always defines the type of structure (control type). Further the structure and purposes of control-elements of different types are described.

BUTTON element

Represents the simple button with an inscription, a record of location with the certain eventId is created on button click event. Typical example:”SOS” button.

Fields

Name Description Type
controlType 1 unsigned byte
eventId Event code, that creates a record on button click event unsigned short
label Button inscription tiny utf-8 string

TOGGLE_BUTTON element

Button, that has two states – active (pressed) and inactive. The button becomes attached to virtual “discrete input” with certain number and reflects its state (active/inactive), and also allows to operate it.

By pressing the button record of location has to be created with event_id = 10+N (where N – input number) with the updated mask of inputs condition.

Fields

Name Description Type
controlType 2 unsigned byte
inputNumber Input number, that is operated by the button. unsigned byte
label Button inscription tiny utf-8 string

CHAT element

Defines availability of a chat for this device. If “control” is present on the list, there has to be a Chat button providing access to messages exchange.

Fields

Name Description Type
controlType 3 unsigned byte

SERVER_TIME_PACKET packet

Protocol version 5+.
It is sent by the server in response to INIT_PACKET.

  • Direction: outgoing

Fields

Name Description Type
type 8 (for this packet) unsigned byte
server timestamp UNIX timestamp (seconds from the Java epoch of 1970-01-01T00:00:00Z.) of current server time long

If you have more questions please contact our support team

Contacts

USA: +1 858 815 9045

Mexico: +52 334 1642158

UK: +44 808 1641499

Germany: +49 1573 5988250

Russia: +7 495 223 0427

Log in

Login

[clean-login]

CLOSE
Register

[clean-login-register]

CLOSE
Loading...