Structured device metadata in detection JSON

[dougborg]

Problem

The current detection JSON uses is_raven (boolean) and raven_fw (string) to identify Raven gunshot detectors:

{
  "event": "detection",
  "is_raven": true,
  "raven_fw": "v2.1.3",
  ...
}

This bakes in knowledge of one specific device type and one metadata field. As detection heuristics improve, we'll want to surface more of what we can learn about a device — make/model, firmware version, hardware revision, capability flags, etc. The current schema doesn't have a clean place for that.

Proposal

Replace is_raven / raven_fw with a device object that collects all discovered metadata about the target:

{
  "event": "detection",
  "detection_method": "mac_prefix",
  "protocol": "bluetooth_le",
  "mac_address": "58:8e:81:fd:9b:ca",
  "device_name": "FS Ext Battery",
  "rssi": -65,
  "device": {
    "make": "Flock Safety",
    "model": "External Battery",
    "fw_version": "",
    "hw_revision": ""
  }
}

Some options for structuring this:

Option A: Flat device object (shown above)

Known keys with empty-string defaults when unknown. Simple to parse, easy to extend by adding new keys. Companion apps can ignore keys they don't understand.

Option B: device object with type discriminator

"device": {
  "type": "flock_safety_camera",
  "make": "Flock Safety",
  "model": "Falcon",
  "fw_version": "v3.2.1",
  "hw_revision": "rev2"
}

A type enum gives parsers a fast switch target while still carrying the richer metadata. New types (e.g. "raven_gunshot_detector", "unknown") are just new enum values.

Option C: Free-form device.meta bag

"device": {
  "make": "Raven Industries",
  "model": "SST",
  "meta": {
    "fw_version": "v2.1.3",
    "hw_revision": "rev1",
    "capabilities": ["audio", "lte"]
  }
}

Top-level fields for the basics, then meta for anything device-specific. Most flexible, but parsers need to handle arbitrary keys.

---

Leaning toward Option B — the type discriminator keeps parser logic simple while the flat fields cover what we can realistically discover from BLE advertisements and scan responses (device name patterns, OUI lookups, service UUIDs, manufacturer-specific data). Fields are empty strings when not determined.

Fields to consider

Field	Source	Example
type	Heuristic classification	"flock_safety_camera", "raven_gunshot_detector", "unknown"
make	OUI / name pattern lookup	"Flock Safety", "Raven Industries"
model	Device name parsing	"Falcon", "External Battery", "SST"
fw_version	BLE Device Information Service or name pattern	"v2.1.3"
hw_revision	BLE Device Information Service	"rev2"

Migration

Both the firmware (src/main.cpp JSON output) and the DeFlock app parser (DroneDetection.fromFlockyou()) would need updates. The existing is_raven / raven_fw fields would be replaced by the device object.