Contact us LoginLIVE DEMOFREE 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.

NameDescriptionLength, byte
unsigned byteUnsigned integer, value range from 0 (00) to 255 (FF)1
unsigned shortUnsigned integer, value range from 0 (00 00) to 65535 (FF FF)2
longSigned integer, value range from -2^63^ to 2^63^-18
byte[]unsigned short, contains the length of the byte array (N), then N byte of arbitrary binary data2+N
floatFloating-point number, recorded according to IEEE 754 (single precision) standard4
doubleFloating-point number, recorded according to IEEE 754 (double precision) standard8
utf-8 stringunsigned short, contains the length of the byte array (N), then N byte, containing a UTF-8 encoded string2+N
tiny utf-8 stringunsigned byte, contains the length of the byte array (N), then N byte, containing a UTF-8 encoded string1+N
timestamplong – number of the milliseconds which passed since 01.01.1970 00:00:00 UTC8

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

NameDescriptionType
type0 (for current packet)unsigned byte
deviceIdThe unique digital identifier of a device, usually IMEIlong
protocolVersionProtocol version. In this document the protocol of the version 4 is describedunsigned byte
controlsDataData 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

NameDescriptionType
type2 (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

NameDescriptionType
type2 (for this packet)unsigned byte
batteryBattery charge level, from 0.0 (minimum) to 1.0 (maximum)float
signalGSM-signal level, from 0 (absent) to 31 (maximum)unsigned byte
roaming1, if a tracker is in roaming, 0 otherwiseunsigned byte
networkGSM-network name, empty string, if the network is unavailableutf-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

NameDescriptionType
type1 (for this packet)unsigned byte
deviceIdThe unique digital identifier of a device, usually IMEIlong
numRecordsNumber of records about location (N)unsigned byte
recordsN records about location, which structure is described below

Structure of one record of location

NameDescriptionType
lngLongitude location in degrees from -180.0 to 180.0double
latLatitude location in degrees from -90.0 to 90.0double
speedSpeed in km/hunsigned short
headingThe direction of the movement in degrees, from 0 to 359unsigned short
satellitesNumber of visible GPS satellitesunsigned byte
eventIdCode of the event which entailed record creation (see the table below)unsigned short
timeRecord creation time (according to GPS)timestamp

Protocol version 2+

inputStatusBit 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+

locationSourceSource of navigation data 0 – GPS, 1 – GSM LBS, 2 – unknownunsigned byte
locationRadiusAccuracy of determination of location, radius in metersunsigned short

Protocol version 5+

requestedLocationSourceRequired source of navigation data 0 – GPS, 1 – GSM LBSunsigned byte

Codes of events

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

Protocol version 5+

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

CONTROLS_PACKET packet

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

  • Direction: incoming

Fields

NameDescriptionType
type3 (for this packet)unsigned byte
controlsDataData 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

NameDescriptionType
controlType1unsigned byte
eventIdEvent code, that creates a record on button click eventunsigned short
labelButton inscriptiontiny 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

NameDescriptionType
controlType2unsigned byte
inputNumberInput number, that is operated by the button.unsigned byte
labelButton inscriptiontiny 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

NameDescriptionType
controlType3unsigned byte

SERVER_TIME_PACKET packet

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

  • Direction: outgoing

Fields

NameDescriptionType
type8 (for this packet)unsigned byte
server timestampUNIX timestamp (seconds from the Java epoch of 1970-01-01T00:00:00Z.) of current server timelong

If you have more questions please contact our support team

Contacts

USA: +1 858 225 46 88

Mexico: +52 558 526 11 25

UK: +44 203 807 64 62

Russia: +7 495 128 35 56

Navixy team is heading to Latin America! Schedule a meeting with us here>>

We use сookies to improve our website, products and related services, analyze site traffic, and serve targeted advertisements. If you continue to use our services, you consent to our use of сookies. Read more

Log in