Reference Guide

1 Timestamps

2 Data Types (Realtime vs Historical)

3 Location Data

4 Status Flags (32-bit)

Status is a 32-bit integer from packet bytes 4-7. Each bit represents a different status.

5 Alarm Flags (32-bit)

Alarm is a 32-bit integer from packet bytes 0-3. Each bit represents a different alarm condition.

6 Additional Information Fields

Optional TLV (Type-Length-Value) fields appended after the main location data (starting at byte 28).

7 Protocol Structure (JT808/IMZ)

8 Conversion Formulas & Code Examples

def decode_bcd_timestamp(bcd: bytes) -> datetime:
    def bcd_to_int(b):
        return ((b >> 4) * 10) + (b & 0x0F)

    return datetime(
        2000 + bcd_to_int(bcd[0]),  # Year (00-99 → 2000-2099)
        bcd_to_int(bcd[1]),          # Month (01-12)
        bcd_to_int(bcd[2]),          # Day (01-31)
        bcd_to_int(bcd[3]),          # Hour (00-23)
        bcd_to_int(bcd[4]),          # Minute (00-59)
        bcd_to_int(bcd[5]),          # Second (00-59)
        tzinfo=timezone.utc
    )

# Read raw values (Big Endian unsigned 32-bit)
lat_raw = struct.unpack(">I", body[8:12])[0]
lon_raw = struct.unpack(">I", body[12:16])[0]

# Convert to degrees
latitude = lat_raw / 1_000_000
longitude = lon_raw / 1_000_000

# Apply hemisphere correction from status flags
if status & (1 << 2):  # Bit 2: South
    latitude = -latitude
if status & (1 << 3):  # Bit 3: West
    longitude = -longitude

# Read 32-bit status (Big Endian)
status = struct.unpack(">I", body[4:8])[0]

# Extract individual flags
acc_on = bool(status & (1 << 0))
gps_valid = bool(status & (1 << 1))
motion_static = bool(status & (1 << 6))
sealed = bool(status & (1 << 14))
shackle_closed = bool(status & (1 << 15))

# Extract multi-bit values
charge_status = (status >> 16) & 0x03  # Bits 16-17
network_type = (status >> 18) & 0x03   # Bits 18-19

def calculate_checksum(data: bytes) -> int:
    checksum = 0
    for byte in data:
        checksum ^= byte
    return checksum

# Verify: calculated checksum should match last byte before 0x7E

// Parse timestamp (handles both ISO and SQLite formats)
function parseTimestamp(timestamp) {
    let ts = timestamp;
    // If no timezone marker, assume UTC
    if (!ts.includes('Z') && !/[+-]\d{2}:\d{2}$/.test(ts)) {
        ts = ts.replace(' ', 'T') + 'Z';
    }
    return new Date(ts);
}

// Convert to IST (UTC+5:30)
const istOffset = 5.5 * 60 * 60 * 1000;
const istDate = new Date(utcDate.getTime() + istOffset);

Data Flow Overview