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": "1.0",
  "imei": "860000000000001",
  "ts": 1715000000,
  "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",
  "id": "cmd-abc123"
}

The device MUST respond with a command_ack event referencing cmd_id.