Skip to content

Add HCI user channel support#56

Merged
colemancda merged 3 commits into
masterfrom
feature/user-channel
Jul 18, 2026
Merged

Add HCI user channel support#56
colemancda merged 3 commits into
masterfrom
feature/user-channel

Conversation

@colemancda

Copy link
Copy Markdown
Member

Summary

Adds support for the HCI user channel (HCI_CHANNEL_USER), which grants a process exclusive access to a Bluetooth controller while detaching the kernel's host stack:

  • HCIUserChannel — actor bound to a specific controller on the user channel. While open, all HCI traffic (commands, events, ACL and SCO data) flows through the socket. HCIUserChannel.open(device:) powers the controller off first, since the kernel requires the device to be down before the channel can be opened. Requires CAP_NET_ADMIN (root).
  • Raw packet IO — a Packet type (packet type prefix plus payload) with wire decoding, and send/receive for arbitrary HCI traffic.
  • Command helperssend(_:parameter:) fires a command without waiting; request(_:parameter:) sends a command and waits for the matching Command Complete event (returning its parameters) or Command Status event (throwing the typed HCIError on failure), skipping unrelated packets. Socket filters do not apply on the user channel, so matching is done in the receive loop.
  • HCIPacketType now conforms to Sendable (required for the packet type under strict concurrency checking).

This enables exclusive-access use cases such as broadcasting beacons from a fully controlled adapter, controller bring-up and testing, and future packet capture tooling.

Test plan

  • 6 new unit tests covering packet decoding, Command Complete and Command Status parsing, error status mapping to HCIError, truncated packet rejection, and ignoring of ACL data and LE meta events in response matching
  • Full test suite passes (56 tests)
  • swift build succeeds with no new warnings
  • Live behavior (exclusive access, device-down requirement) requires Linux with CAP_NET_ADMIN (root)

@colemancda
colemancda merged commit 167141e into master Jul 18, 2026
1 check passed
@colemancda
colemancda deleted the feature/user-channel branch July 18, 2026 05:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant