Connecting

Discover a BattleCore device, connect to it, and locate the API service and its characteristics.

1. Discovery

BattleCore devices advertise a name with a BattleCore prefix. Scan for peripherals and match on that prefix:

Device	Advertised name
Tagger	`BattleCore TR: <mac>`
Headset	`BattleCore HS: <mac>`

Match on the name, not the service UUID

The API service UUID is not reliably included in the advertising packet (particularly on iOS). Filter scan results by the BattleCore name prefix, then connect and discover services to confirm the peripheral is a BattleCore device.

2. The GATT service

After connecting, discover services and characteristics. Everything lives under one primary service:

Service UUID

ba771ec0-12e1-4e78-8a49-c16503f00ae1

3. Characteristics

The service exposes three characteristics. You write requests to one and receive responses and events on the other two.

Characteristic	UUID	Properties	Purpose
`CMD_IN`	ba771ec0-12e2-4e78-8a49-c16503f00ae1	Write	Send commands to the device. Write one frame at a time; a long request spans several.
`CMD_OUT`	ba771ec0-12e3-4e78-8a49-c16503f00ae1	Read · Notify	Command responses. Each response echoes the id of the request that produced it.
`EVENTS_OUT`	ba771ec0-12e4-4e78-8a49-c16503f00ae1	Read · Notify	Unsolicited events — live state changes, game-state transitions, OTA progress.

4. Payload encoding

Every characteristic value is one frame: a 4-byte header (format marker 0xC1, frame id, part index, part count) and up to 146 bytes of a CBOR message. A message longer than that spans several frames, in both directions, and the receiver joins them by frame id. Names travel as small integers from a shared dictionary. The Wire Format page has the byte layout, the CBOR subset and a worked example.

A frame is sized to fit the default MTU an iPhone negotiates, so no MTU negotiation is required. (Some BLE libraries hand values across their API boundary as base64 strings; that is a library detail, not part of this protocol.)

5. Recommended connect flow

1.  Scan for peripherals whose name starts with "BattleCore".
2.  Connect to the chosen device.
3.  Discover services + characteristics.
4.  Subscribe (enable notifications) on CMD_OUT and EVENTS_OUT
    BEFORE sending any command, so no response is missed.
5.  Announce yourself so the device streams live state:
        set deviceState / DEVICE_APP_CONNECTED = true
6.  Encode a request as a CBOR envelope, split it into frames, and write
    them to CMD_IN in order; correlate replies by "id".

Turn on the live event stream

The device only pushes deviceState change events while an app is connected. Set DEVICE_APP_CONNECTED to true right after connecting (see the Protocol page) to start receiving them.