Home > 3rd-Party Integration

3rd-Party Integration

Biscuit is a BLE peripheral that exposes a stable, line-delimited text protocol over GATT. If you want to build your own client, you can drive a Biscuit directly without going through the official companion apps. That client could be a desktop app, a Python script, a Web Bluetooth dashboard, or an alternate mobile app.

This section documents the publicly supported BLE/GATT surface: the service and characteristic UUIDs, the wire format, the connection lifecycle, and a worked example of the wardrive flow that covers most integration use cases.

Audience: External developers and security researchers building custom tooling against a Biscuit. If you are an end user looking to control a Biscuit, install the iOS or Android companion app instead.

Pages in this section

  • GATT Reference: service and characteristic UUIDs, connection parameters, message framing, status codes, and the Status JSON schema.
  • Wardrive Integration: the wardriveall worked example, live data formats, single-radio variants, and Flock classification.
  • Commands Reference: WiFi scan/attack, Bluetooth scan/attack, Evil Portal, and device-control commands with their response and data formats.

First connection

The minimum sequence to get from “discovered” to “first command accepted”:

  1. Scan for a peripheral advertising the service UUID 4fafc201-1fb5-459e-8fcc-c5c9c331914b. The local name in the advertisement is the literal string Biscuit and is the same on every device.
  2. Connect to the peripheral.
  3. Negotiate MTU. The device requests an MTU of 517. A client MTU of at least 247 is recommended; below that, larger notifications during high-throughput scans may be fragmented across multiple ATT packets.
  4. Discover the primary service and its four characteristics. See GATT Reference for UUIDs and properties.
  5. Subscribe to notifications on the Response characteristic by writing 0x0001 to its Client Characteristic Configuration Descriptor (CCCD). Until this descriptor is written, the device sends nothing.
  6. Optionally reply to the time-sync request. Shortly after CCCD subscribe the device emits TIME:REQUEST:. Reply with TIME:SYNC: followed by an ISO-8601 local timestamp with offset, for example TIME:SYNC:2026-05-01T14:30:00-04:00. The device retries every five seconds until acknowledged. Skipping time sync does not block command processing, but timestamps embedded in scan output will fall back to the device’s last-known time.
  7. Issue commands. No mandatory hello, version, or capability handshake. The first CMD: written to the Command characteristic is processed.

Keepalive and reconnection

The device does not enforce a client-side timeout, and adding one against it has historically caused dropped links. Do not send periodic pings or connection-priority bumps.

The BLE surface is BLE 4.2. Clients should not request BT 5 link-layer features such as the 2M PHY, Coded PHY, or Extended Advertising. Some BLE stacks request these by default on connect and will see disconnects against this peripheral.

If the link drops mid-scan:

  • The notification stream stops on your side.
  • On reconnect, resend the scan or wardrive command to resume the stream. Session state is not auto-resumed.
  • The device re-emits TIME:REQUEST: once notifications are re-subscribed.