📡 Protocols & API Reference

IntelliKeep utilizes a multi-tier communication model: ultra-compact BLE Manufacturer Advertisements at the radio physical layer, structured JSON payloads over MQTT on the local network, and authenticated HTTPS REST APIs for cloud synchronization and mobile push notifications.

1. BLE Manufacturer Advertising Payload

The BLE tag broadcasts non-connectable undirected advertising packets. The base station scanner filters for GAP packet type 0xFF (Manufacturer Specific Data) with company identifier 0x1337.

Byte Offset	Field Name	Type / Range	Format & Description
`0 – 1`	Company ID	`uint16_t`	`0x1337` (Little-endian byte order: `0x37, 0x13`). Dedicated IntelliKeep identifier.
`2`	Battery Level	`uint8_t`	Percentage value (`0–100%`). Derived from switched MOSFET ADC measurement.
`3`	Flags	`uint8_t` (Bitfield)	Bit 0: Tamper Sensor State (`0` = Normal/Sealed, `1` = Tampered/Open). Bits 1–7: Reserved.
`4`	Reason Code	`uint8_t`	Classification of the event that triggered the tag wake cycle (see table below).

Telemetry Reason Codes

Code Value	Symbolic Name	Meaning / Trigger Condition
`0`	`REASON_PERIODIC`	Standard scheduled wake from RTC deep-sleep timer (every 5 minutes).
`1`	`REASON_TAMPER`	Immediate wake fired by the VBPW34S optical comparator interrupt (enclosure opened or tag pried off).
`2`	`REASON_NFC`	Wake triggered by smartphone NFC RF field interaction during onboarding.
`3+`	`REASON_ALERT`	Low-battery emergency alert or reserved diagnostic status.

2. Presence & Missing Detection Logic

Unlike consumer trackers that rely on smartphones to discover beacons intermittently, IntelliKeep maintains continuous, deterministic coverage through the fixed ESP32-S3 base station.

📏 Signal Boundary Classification

The base station calculates RSSI on every received packet. An empirical threshold of -100 dBm cleanly delineates normal interior coverage from weak or departing assets:

RSSI ≥ -99 dBm: In Range & Present. Normal operational state.
RSSI ≤ -100 dBm: Out of Range Alert. Asset has been moved to a perimeter boundary, vehicle, or outside the structure.

11-Minute Missing Evaluation Window

Because tags advertise once every 5 minutes (300 s), an asset will normally be observed twice within any 10-minute period. IntelliKeep enforces an 11-minute missing threshold (2.2 wake cycles). If an enrolled tag fails to report within 11 minutes, the base station or server missing-checker worker immediately flags the asset as Missing and dispatches high-priority mobile alarms.

3. RF Collision Probability Mathematical Model

Because multiple tags broadcast asynchronously without listening before transmitting (ALOHA random access), packets could theoretically collide if two tags wake simultaneously.

Given an advertising burst duration of $T = 0.15\text{ s}$ (150 ms) and a sleep period of $P = 300\text{ s}$ (5 minutes), the probability $P_{coll}$ that a tag's broadcast overlaps with any of the $N - 1$ other tags is modeled by:

Collision Formula

P_coll ≈ 1 - ( 1 - 2*T / P )^(N - 1)   where T = 0.15s, P = 300s

Active Tag Fleet Size ($N$)	Single-Wake Collision Rate ($P_{coll}$)	False Missing Probability $(P_{coll})^2$
3 Tags	0.20%	0.0004% (< 1 in 250,000)
5 Tags	0.40%	0.0016% (< 1 in 60,000)
10 Tags	0.90%	0.0081% (< 1 in 12,000)
25 Tags	2.37%	0.0562% (< 1 in 1,700)
50 Tags	4.78%	0.2285% (< 1 in 430)

🛡️ Extreme False-Alarm Immunity

Because an asset is only classified as Missing after two consecutive missed wakes within the 11-minute grace window, the probability of a false missing alert due strictly to packet collision equals $(P_{coll})^2$. For a typical 5-tag deployment, the false-alarm collision rate is less than 0.0016%!

4. MQTT Local Telemetry Interface

For integration with Home Assistant, Node-RED, or local automation hubs without cloud dependencies, the base station publishes directly to a local MQTT broker.

Topic Structure

Topic

intellikeep/base/<MAC_ADDRESS>
Example: intellikeep/base/AA:BB:CC:DD:EE:FF

JSON Telemetry Payload

json

{
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "tag_name": "Living Room Sony TV",
  "battery": 92,
  "tamper": false,
  "reason": 0,
  "rssi": -68,
  "present": true,
  "timestamp": 1789574400
}

5. Base Station Cloud REST API Reference

All communication between the base station and cloud server is transmitted over HTTPS with standard authentication headers:

HTTP Headers

X-API-Key: your_32_character_base_station_key
Content-Type: application/json

A. Upload Tag Observation

Endpoint: POST /api/v1/observations (Timeout: 10s)

json

{
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "tag_name": "Living Room Sony TV",
  "battery": 85,
  "tamper": false,
  "reason": 0,
  "rssi": -62,
  "present": true
}

B. Dispatch High-Priority Alert

Endpoint: POST /api/v1/alerts (Timeout: 10s)

json

{
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "tag_name": "Living Room Sony TV",
  "status": "tampered",
  "message": "Optical tamper sensor triggered! Enclosure opened."
}

C. Periodic Base Station Heartbeat & Sync

Endpoint: GET /api/v1/base/info (Every 15s, Timeout: 10s)

Server Response (json)

{
  "base_id": 12,
  "base_name": "Main Floor Hub",
  "mac_address": "C8:C9:A3:11:22:33",
  "mqtt_configured": true,
  "last_seen": "2026-09-16T18:30:00Z",
  "trigger_reconfigure": false,
  "trigger_factory_reset": false,
  "tags": [
    {"mac_address": "AA:BB:CC:DD:EE:FF", "tag_name": "Sony TV", "active": true},
    {"mac_address": "11:22:33:44:55:66", "tag_name": "MacBook Pro", "active": true}
  ]
}

6. Local Embedded Status APIs

When accessing the base station directly over the local network (e.g., http://192.168.1.50):

GET /api/info

json

{
  "uptime_seconds": 86420,
  "wifi": {"connected": true, "ip": "192.168.1.50", "ssid": "Office_WiFi"},
  "mqtt": {"configured": true, "connected": true},
  "server": {"configured": true, "connected": true},
  "tags_registered": 4
}

GET /api/tags

json

[
  {
    "mac": "AA:BB:CC:DD:EE:FF",
    "name": "Sony TV",
    "battery": 88,
    "rssi": -60,
    "tamper": false,
    "reason": 0,
    "present": true,
    "last_seen": 1789574400
  }
]