Message Envelope – TAD101 | Track Any Device – TAD101

Inbound event (Device → Server)

Every event sent by any TAD101 device MUST conform to this JSON envelope.

json

{
  "tad": "101",
  "v": "1.0",
  "imei": "860000000000001",
  "event": "update",
  "ts": 1715000000,
  "seq": 42,
  "payload": { ... }
}

Field	Type	Required	Description
tad	string	✓	Always "101"
v	string	✓	Protocol version, e.g. "1.0"
imei	string	✓	Device hardware ID
event	string	✓	Event type (see below)
ts	integer	✓	Unix timestamp (UTC, device clock)
seq	integer	✓	Sequence number (for dedup)
payload	object	✓	Sensor data (see below)

event	Meaning
update	Regular telemetry / location update
heartbeat	Keepalive with battery / mode info
punch_in	Worker clock-in
punch_out	Worker clock-out
sos	Emergency alert
intercom	PTT voice / audio event
registration	First connect / re-registration
alarm	Generic alarm (subtype in payload)
command_ack	Response to a server-sent command
config_report	Device reports its current config
custom	Device-defined event (with payload.custom_type)

All fields are optional. Devices send only what they have; the server maps non-null fields onto the signals schema.

json

{
  "lat": 31.5497,
  "lng": 74.3436,
  "alt": 215,
  "speed": 0,
  "direction": 0,
  "battery_pct": 87,
  "gsm_signal": -73
}

json

{
  "cmd": "ping",
  "cmd_id": "cmd-abc123"
}

The device MUST respond with a command_ack event referencing cmd_id.