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 JSON request at a time.
`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, keyboard requests.

4. Payload encoding

Characteristic values are plain UTF-8 JSON strings — there is no additional framing or encoding. (Some BLE libraries require you to base64-encode values at their API boundary; that is a library detail, not part of this protocol. The bytes on the wire are the JSON text.)

Keep each message within the connection's ATT MTU. Negotiate a larger MTU after connecting if you plan to send or receive larger payloads (for example, setting all RGB pixels at once).

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.  Send commands by writing JSON to CMD_IN; 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.