Event types - PicklX Pulse

The protocol defines five event types an event source can send. Each shares the common envelope and adds a type-specific payload.

Type	Payload	Description
`BALL_BOUNCE`	`{ x_ft, y_ft, is_in }`	A ball landing on the court.
`BALL_HIT`	`{ player_id, shot_type, swing_type? }`	A player striking the ball.
`BALL_SPEED`	`{ kmh }`	A ball-speed reading.
`PLAYER_POSITION`	`{ player_id, x_ft, y_ft }`	A player’s position on the court.
`PLAYER_IDENTITY`	`{ player_id }`	Identifies a player.

Coordinate frame

Positional payloads (BALL_BOUNCE, PLAYER_POSITION) use court feet on the receiving half:

x_ft — feet from the left sideline (expected range ≈ 0–20)
y_ft — feet from the net (expected range ≈ 0–22)

These ranges describe the expected court frame; they are not a hard validation bound. Send coordinates already mapped to the court frame. If your sensor reports a different frame, PicklX fits a per-integration adapter at the boundary.

Examples

{
  "event_id": "b7e3a91c4f25d8a0c1e6f3b2",
  "session_id": "session-court1-20260609-001",
  "venue_id": "venue-la-01",
  "court_id": "court-1",
  "eot": "2026-06-09T20:00:06.120Z",
  "type": "BALL_BOUNCE",
  "confidence": 0.95,
  "source": "your-system",
  "schema_version": "1.0",
  "revision": 0,
  "payload": { "x_ft": 4.2, "y_ft": 19.3, "is_in": true }
}

{
  "event_id": "a1c9e2d74b06f8e3a5d0c4b1",
  "session_id": "session-court1-20260609-001",
  "venue_id": "venue-la-01",
  "court_id": "court-1",
  "eot": "2026-06-09T20:00:05.480Z",
  "type": "BALL_HIT",
  "confidence": 0.98,
  "source": "your-system",
  "schema_version": "1.0",
  "revision": 0,
  "payload": { "player_id": "player-7f3a", "shot_type": "GROUNDSTROKE", "swing_type": "BACKHAND" }
}

{
  "event_id": "c4f0b6a83d17e9c2b5a8d1e0",
  "session_id": "session-court1-20260609-001",
  "venue_id": "venue-la-01",
  "court_id": "court-1",
  "eot": "2026-06-09T20:00:05.480Z",
  "type": "BALL_SPEED",
  "confidence": 0.9,
  "source": "your-system",
  "schema_version": "1.0",
  "revision": 0,
  "payload": { "kmh": 57.2 }
}

{
  "event_id": "d8a2c5e91f40b7d3a6c0e2f4",
  "session_id": "session-court1-20260609-001",
  "venue_id": "venue-la-01",
  "court_id": "court-1",
  "eot": "2026-06-09T20:00:07.900Z",
  "type": "PLAYER_POSITION",
  "confidence": 0.85,
  "source": "your-system",
  "schema_version": "1.0",
  "revision": 0,
  "payload": { "player_id": "player-7f3a", "x_ft": 9.5, "y_ft": 6.4 }
}

{
  "event_id": "e2b7d0f63a59c8e1b4d7f0a3",
  "session_id": "session-court1-20260609-001",
  "venue_id": "venue-la-01",
  "court_id": "court-1",
  "eot": "2026-06-09T20:45:00.000Z",
  "type": "PLAYER_IDENTITY",
  "confidence": 0.92,
  "source": "your-system",
  "schema_version": "1.0",
  "revision": 0,
  "payload": { "player_id": "player-7f3a" }
}