airplx.v1

First message on every connection.

This serverReplies with welcome. Anything else first, or a device_id outside 1–999999, closes 1002. Reply: welcome.

Copy{
  "type": "hello",
  "device_id": 123456
}

One 1 s audio record. Header fields: device_id, boot_seq, chunk_id, flags, monotonic_counter, utc_ms, time anchor, channel_mask, levels, audio_state, AGC, clips, payload_crc32, header_crc32.

This serverRecognised by magic and length, then logged. Not parsed or acknowledged until the header layout is known.

Header only, for a quiet second. Proposed. The Q-042 answer is heartbeats instead.

This serverRecognised and logged like upload.

Time request: seq, t1. Up to 8 after every welcome and every hour.

This serverLogged, not answered. Layout TBD.

Every 60 s. Groups: state, capture, upload, network, audio, health, storage, system, counters.

This serverStored as the box's last status. No reply.

Copy{
  "type": "status"
}

Events and alarms. De-duplicated by (device_id, boot_seq, seq).

This serverStored once per (boot_seq, seq). No reply.

Copy{
  "type": "event"
}

Associates the box with an account and location. The claim token goes backend → app → box → server.

This serverReplies with claim_result, no fields yet. Reply: claim_result.

Copy{
  "type": "claim"
}

The box left its account.

This serverLogged. No reply.

Copy{
  "type": "unclaim"
}

Onboarding test. Its frames are flagged as a test and uploaded first.

This serverReplies with test_capture_result straight away, no fields yet. Reply: test_capture_result.

Copy{
  "type": "test_capture"
}

accepted (≤ 2 s), in_progress (long commands only), then completed or failed with a code.

This serverStored with the command. No reply.

Copy{
  "type": "cmd_result",
  "request_id": "<uuid>",
  "state": "completed",
  "code": "OK",
  "data": {}
}

Reply to hello, within 2 s. Nothing is sent before it.

This serverack and config_rev are 0. pending_commands holds cmd messages queued while the box was offline.

Copy{
  "type": "welcome",
  "ack": 0,
  "config_rev": 0,
  "pending_commands": []
}

Cumulative acknowledgement: every chunk_id up to it is stored.

This serverNot sent yet. Layout TBD.

Time response: seq, t1, t2, t3. offset = ((t2 − t1) + (t3 − t4)) / 2.

This serverNot sent yet. Layout TBD.

Result of claim. Refused if the box is associated elsewhere.

This serverSent with no fields yet.

Copy{
  "type": "claim_result"
}

Sent once the test capture is stored.

This serverSent with no fields yet.

Copy{
  "type": "test_capture_result"
}

Remote command. Same names, args and codes as BLE (M2b §7). The same request_id again returns the stored result.

This serverSent from POST /api/v1/devices/{id}/cmd, or in the next welcome if the box is offline.

Copy{
  "type": "cmd",
  "request_id": "<uuid>",
  "name": "find_device",
  "args": {},
  "timeout_ms": 30000
}

A message that could not be processed. Either side can send one.

This serverSent with no fields for bad JSON or an unknown type.

Copy{
  "type": "error"
}