V53 protocol (JT/T 808-2013 + extensions)

Sources: V53communication protocol.pdf and V53-Protocol-Data-Example_V1.1.pdf in this repository's vendor/ directory. Anything the V53 documents do not mention follows JT/T 808-2013.

Framing

7E | message id (2) | body properties (2) | terminal id BCD (6) | serial (2) | [subpackage (4)] | body | XOR | 7E

• 0x7E delimits frames; inside a frame 0x7E → 7D 02 and 0x7D → 7D 01.
• The checksum is the XOR of every byte from the message id to the end of the body, computed before escaping.
• Body properties: bits 0–9 body length (max 1023), bits 10–12 encryption (must be 0; Phimi rejects encrypted bodies), bit 13 subpackage.
• The terminal id is 12 BCD digits, for example 016053137272.
• TCP is a stream: Phimi reassembles frames split across reads and splits several frames delivered in one read.

Messages Phimi handles

Device → Phimi	Phimi → device
0x0100 registration	0x8100 registration response with auth code
0x0102 authentication	0x8001 general response
0x0200 location	0x8001
0x0704 batch locations	0x8001
0x0002 heartbeat	0x8001
0x0107 terminal attributes	0x8001 (query with 0x8107)
0x0900 passthrough reply	0x8900 passthrough command (type 0xF8)
0x0001 terminal response	0x8300 text command (flag 0x01)
0x0F02 false-shutdown heartbeat	0x8001
	0x8203 manual alarm confirmation

Every exchange in the vendor example PDF is a test fixture in phimi-platform/tests/fixtures/v53/. Phimi decodes all of them, and every platform reply it encodes is byte-identical to the vendor's.

0x0200 location

Base fields: alarm flags (u32), status (u32), latitude and longitude (u32, 10⁻⁶ degrees), altitude (m), speed (0.1 km/h), direction (degrees), time (BCD YYMMDDhhmmss).

Status bits used: 1 positioned, 2 south, 3 west, 6 armed (V53), 18 GPS used, 19 BeiDou used. Alarm bits: 0 emergency, 1 overspeed, 7 low battery, 10 SIM changed, 15 vibration, 26 light.

V53 additional items:

Id	Length	Meaning
0x01	4	mileage, 100 m units
0x04	2	charging byte, battery %
0x05	1	mode: 1 timed, 2 smart, 3 power saving, 5 sleep/flight, 6 roll call, 7 movement
0x07	2	steps
0x2B	2 (4 observed)	battery voltage, mV; the device repeats the word
0x30	1	network signal, %
0x31	1	GNSS satellites
0x54	1 + 7n	Wi-Fi: count, then MAC (6) + signal (1)
0x5D	1 + 10n	serving cell: count, then MCC (2), MNC (1), LAC (2), cell id (4), signal (1)

A Wi-Fi or LBS report has latitude and longitude 0. Phimi keeps the network observations and does not turn them into a map point; estimating a position from them needs an external geolocation service.

Heartbeat 0x0002

The V53 extends the empty JT/T 808 heartbeat with recording status (1), battery % (1) and voltage in mV (2). Phimi accepts both forms.

Known discrepancies in the vendor documents

• Charging byte: the protocol says 0 = charger connected and 1 = not connected, but the examples annotate 00 as charging and 01 as charging too. Phimi stores the raw byte until a real device settles it.
• Device clock: JT/T 808 specifies GMT+8. The V53's offset is unconfirmed; Phimi makes it configurable (PHIMI_DEVICE_UTC_OFFSET_MINUTES, default 480).
• ICCID in 0x0107 contains a hex C (898604851920C1832639), so it is decoded as hex nibbles, not strict BCD.
• Voltage item 0x2B is documented as 2 bytes but sent as 4 (the value twice).