How It Works
GATT Layout
Section titled “GATT Layout”- Each hub is one characteristic with Write (client → host) and Notify (host → client).
- Every hub is a characteristic of one GATT service, set with
server.ServiceUuid(...)on the host ando.ServiceUuidon each client (they must match). Calls are routed by characteristic, so messages never carry a hub name. - The host advertises that one service UUID while any hub runs, plus an optional local name. Clients scan for it.
- Why one: two 128-bit UUIDs take 37 bytes, more than a 31 byte advertisement. Android then refuses to advertise at all, and iOS moves the extra UUID into an Apple-only overflow area that Android scanners can’t see.
- The cost: a scan can’t tell which hubs a host is running. Joining a stopped hub is refused by the handshake, and a host without your hub’s characteristic (another app on the default UUID) fails when the characteristic is looked up.
Why not reads for responses? A client can’t tell when a response is ready to read, so it would have to poll. Reads are also ambiguous with several calls in flight, and they are still capped by the MTU. Correlated, chunked notifications avoid all of that.
Messages & Framing
Section titled “Messages & Framing”A BLE write or notification can carry only MTU - 3 bytes: 20 bytes at the BLE minimum, usually 182 or more on iOS,
and up to 512. The client asks for the largest ATT MTU (517) on every new connection. Here MTU means the ATT MTU:
Shiny’s IPeripheral.Mtu is already the payload size (ATT MTU minus 3), and blehubs converts it. Every message (call,
reply, stream item, push) is split into frames that fit:
[version][kind][message id:2][sequence:2][flags][total length:4 - first frame only] + chunk- Matching replies: the receiver puts frames back together by message id, and replies are matched to calls the same way. Many calls can be in flight at once.
- Sending order: the host sends each message to a client as a whole, so frames never interleave. The client raises pushes in the order they arrived.
- Arguments are serialized one by one with their static type, which keeps everything AOT-safe.
- Handshake: when a client connects, it exchanges a handshake with the host carrying the protocol version, client name and properties, and the file transfer channel. Mismatched protocol versions are refused.
- Media channels: the handshake reply also carries the media channel’s L2CAP PSM and a random token for that
connection. The client opens the channel and sends the token as its first frame. The host answers
[0x01], or closes the channel if the token isn’t one it issued to a connected client. After that, every packet is a frame of[length:4 LE][bytes]. These fields were added without changing the protocol version: an older client ignores them, and a reply from an older host means no media channels. - Renaming: a client’s
Renameframe carries its new name, and the host answers with a completion or an error (HubRenameRefused). AHostRenamedframe carries the host’s new name to every client, in order with pushes. Both were added without changing the protocol version: an older host refuses a rename with an error, and an older client ignores a host rename and keeps the name from the handshake. - Disconnect: a
Disconnectframe carries a reason code (HubDisconnectReason) and an optional message, in both directions. The host sends it to end a client’s session (ServerDisconnectorServerShutdown). The client sends it when it leaves, before it unsubscribes, so the host can tell a client that left (ClientDisconnect) from one that dropped (ClientTimeout): iOS and Android both report a vanished client as an unsubscribe. The reason code is optional in the message, so hosts and clients from before it still work together. An older host’s disconnect reads asServerDisconnect, and an older host simply sees the client unsubscribe.
Limits
Section titled “Limits”| Default | Change with | |
|---|---|---|
| Largest message | 256 KB | server.Protocol(o => o.MaxPayloadSize = …) or a client’s o.Protocol(…) |
| Call timeout | 30s | RequestTimeout |
| Partial message lifetime | 30s | ReassemblyTimeout |
| Partial messages per client | 16 | MaxPartialMessages |
| Clients per hub | 8 | server.AddHub<T>(…, o => o.MaxClients = …) |
Throughput over GATT is a few KB/s, which is plenty for game moves, commands and state. Use file transfers for anything big.
Best Practices
Section titled “Best Practices”- Put the contract where both sides compile against it, and treat names as a public API. Add new members, and don’t rename or reorder existing ones.
- Register every wire type in a
JsonSerializerContext. A missing registration fails at runtime, not at compile time. - Keep
LocalNameshort (about 8 characters). The advertisement is only 31 bytes. - Set your own
ServiceUuidon host and client, so other apps’ hosts don’t appear in your scans. - Marshal hub events to the UI thread.
- Never store state on the hub instance. It is recreated for every call.
- Foreground only (for now). When an iOS host is in the background, it advertises without its local name, and only through the overflow area.
- Test on two real devices, in both directions (iOS host with an Android client, and the reverse).


