Home > 3rd-Party Integration > GATT Reference

GATT Reference

The complete BLE GATT surface a 3rd-party client needs to drive a Biscuit. Every value on this page is stable across the public firmware line and matches what the iOS and Android companion apps consume.

Advertising

Field	Value
Local name	`Biscuit`
Service UUID in advertisement	`4fafc201-1fb5-459e-8fcc-c5c9c331914b`

The local name is identical on every device; match on the service UUID. Biscuit does not include a per-device suffix in the advertised name.

Primary Service

Service UUID: 4fafc201-1fb5-459e-8fcc-c5c9c331914b

Characteristic	UUID	Properties	Direction	Use
Command	`beb5483e-36e1-4688-b7f5-ea07361b26a8`	Write, Write Without Response	Central to device	Send `CMD:` lines
Response	`beb5483e-36e1-4688-b7f5-ea07361b26a9`	Notify	Device to central	Receive `RSP`, `STATUS`, `DATA`, `ERROR`, `TIME` lines
Status	`beb5483e-36e1-4688-b7f5-ea07361b26aa`	Read	Device to central	Pollable JSON snapshot of device health
Settings	`beb5483e-36e1-4688-b7f5-ea07361b26ab`	Read, Write, Notify	Bidirectional	Read or update device configuration as JSON

Notifications must be enabled. Until the Response characteristic’s CCCD is set to 0x0001, the device does not send anything in response to commands. Subscribing is a prerequisite, not optional.

Device Information Service

Standard BLE Device Information Service (0x180A) exposes:

Characteristic	UUID	Content
Manufacturer Name	`2A29`	`Biscuit Shop`
Model Number	`2A24`	Board name (`Biscuit Pro`, `Biscuit Ultra`, `Biscuit DIY`)
Firmware Revision	`2A26`	Primary firmware version, e.g. `v1.4.5`
Software Revision	`2A28`	Scanner firmware version
Serial Number	`2A25`	Per-device serial

Connection Parameters

Parameter	Value
MTU requested by device	517
Recommended client MTU	At least 247
Data Length Extension	Device requests 251-byte PDUs on connect
Connection interval	30 to 60 ms preferred
Slave latency	0
Supervision timeout	8000 ms

Below an MTU of 247, large notifications during wardrive streams will be fragmented across multiple ATT packets. Most BLE stacks reassemble these transparently, but throughput drops.

Message Framing

Every text-carrying characteristic uses the same line-oriented format:

TYPE:SUBTYPE:PAYLOAD\n

Every line ends with a single line-feed (\n, 0x0A). The payload may be empty; the trailing colon is still present (for example, CMD:stopscan:).

Message types

Type	Direction	Meaning
`CMD`	Central to device	A command
`RSP`	Device to central	Acceptance of a `CMD` (sent within 100 ms)
`STATUS`	Device to central	Execution-state change
`DATA`	Device to central	Live scan record
`ERROR`	Device to central	Command rejected or runtime error
`TIME`	Device to central	Time-sync request

A RSP means “command accepted”, not “command finished”. For commands that produce output (scans, attacks, wardrive), the actual completion signal arrives as a subsequent STATUS: line.

Status codes

STATUS: lines carry a numeric code in the SUBTYPE position:

Code	Meaning
`0`	Booting
`1`	Ready
`2`	Busy (a scan or attack is running)
`3`	OK
`4`	Warning
`5`	Error
`6`	Scan complete

STATUS:1:Ready is the signal that no further DATA: lines will arrive for the previous operation.

Notification Packing

During wardrive and other high-throughput scans, the device packs multiple DATA: records into a single BLE notification to reduce radio overhead. Records inside a packed notification are newline-delimited:

DATA:AP:Network1,AA:BB:CC:DD:EE:FF,6,-58,WPA2_PSK
DATA:BT:Device1,11:22:33:44:55:66,-72,BLE
DATA:AP:Network2,22:33:44:55:66:77,11,-65,WPA3_SAE

The pack buffer flushes on any of:

Trigger	What happens
Buffer reaches 240 bytes	Immediate flush
50 ms elapsed since first buffered record	Timer-based flush
A non-`DATA` message is queued	Immediate flush, preserving order

Always split each notification on \n and process each line independently. Never assume one notification equals one record.

Status Characteristic JSON

The Status characteristic returns a JSON object summarizing current device health. It is safe to read at any time; the official apps poll it about once per second.

Initial value just after connect:

{"status":0,"battery":-1,"c5Connected":false,"c5State":0}

Full schema (optional keys appear only once the relevant subsystem reports):

Key	Type	Meaning
`status`	int	Overall health: `0` Ready, `1` Warning, `2` Error
`battery`	int	Battery percentage 0 to 100, or `-1` if not yet measured
`c5Connected`	bool	Scanner subsystem link alive
`c5State`	int	Scanner state: `0` Booting, `1` Ready, `2` Busy, `6` Scan complete
`wroomHeap`	`[free, total]`	Optional. Present when the device is reporting heap.
`c5Heap`	`[free, total]`	Optional
`sd`	bool	Optional. Present and `true` when an SD card is mounted.
`op`	string	Optional. `pktmon` or `eapol` while an SD-backed capture is running.

Treat the JSON keys as opaque string identifiers. Field values may evolve across firmware releases; the keys themselves are stable across the public firmware line.