LinuxHciSocketPacketIo

class LinuxHciSocketPacketIo(hciDeviceIndex: Int = defaultHciDeviceIndex(), preOpenedHciFd: Int? = defaultPreOpenedHciFd()) : HciPacketIo

Linux AF_BLUETOOTH / BTPROTO_HCI / HCI_CHANNEL_USER implementation of HciPacketIo.

Binds exclusively to a Linux Bluetooth controller (hciN) using HCI_CHANNEL_USER, bypassing the BlueZ bluetoothd user-space daemon while reusing the Linux kernel's hardware transport drivers (btusb for USB dongles, hci_uart / btbcm for Raspberry Pi UART controllers, etc.). Requires net.java.dev.jna:jna on the runtime classpath.

Permissions & Operating Modes

Because Linux Bluetooth controllers (hci0, hci1, ...) are kernel network-subsystem objects rather than /dev/ device nodes, the kernel gates ioctl(HCIDEVDOWN) and bind(..., HCI_CHANNEL_USER) on CAP_NET_ADMIN. Once bound, however, read() and write() on the HCI_CHANNEL_USER file descriptor do not require CAP_NET_ADMIN or CAP_NET_RAW.

LinuxHciSocketPacketIo therefore supports two operating modes:

Mode 1: Direct Bind (Process has CAP_NET_ADMIN or uid 0)

When preOpenedHciFd is null (the default unless org.multipaz.ble.hciFd or MULTIPAZ_BLE_HCI_FD is set), open brings down hci<N> via ioctl(HCIDEVDOWN) and binds a fresh HCI_CHANNEL_USER socket for each session, closing the socket in close.

The controller index <N> defaults to 0 (hci0) and can be configured via:

  • JVM system property: -Dorg.multipaz.ble.hciDeviceIndex=1 (or hci1)

  • Environment variable: MULTIPAZ_BLE_HCI_DEV=1 (or hci1)

To run without root under systemd, grant ambient CAP_NET_ADMIN:

[Service]
User=multipaz
AmbientCapabilities=CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_ADMIN

Mode 2: Pre-Opened File Descriptor (Unprivileged JVM via Privileged Launcher)

When preOpenedHciFd is provided (or configured via -Dorg.multipaz.ble.hciFd=<fd> or MULTIPAZ_BLE_HCI_FD=<fd>), open adopts that already-bound HCI_CHANNEL_USER file descriptor instead of calling socket(), ioctl(HCIDEVDOWN), or bind().

To allow the unprivileged JVM process to run multiple BLE transactions over its lifetime without needing CAP_NET_ADMIN to re-bind the controller:

  • open drains any stale HCI events left in the kernel socket receive buffer from a prior session before BleHciEngine.initializeController() issues HCI_Reset.

  • close wakes the poll() loop and writes a best-effort HCI_Reset (01 03 0c 00) to stop advertising, scanning, and active connections, without calling close(fd) on preOpenedHciFd so subsequent BLE sessions can reuse the descriptor.

Example minimal C launcher (install with sudo setcap cap_net_admin=ep hci-launch):

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/ioctl.h>
#include <sys/socket.h>
#include <unistd.h>

#define AF_BLUETOOTH 31
#define BTPROTO_HCI 1
#define HCI_CHANNEL_USER 1
#define HCIDEVDOWN 0x400448caUL

struct sockaddr_hci {
unsigned short hci_family;
unsigned short hci_dev;
unsigned short hci_channel;
};

int main(int argc, char **argv) {
if (argc < 3) {
fprintf(stderr, "Usage: %s <hci-index> <command> [args...]\n", argv[0]);
return 1;
}
int dev = atoi(argv[1]);
int ctl = socket(AF_BLUETOOTH, SOCK_RAW, BTPROTO_HCI);
if (ctl >= 0) { ioctl(ctl, HCIDEVDOWN, dev); close(ctl); }

// Open without SOCK_CLOEXEC so the fd is inherited across execvp()
int fd = socket(AF_BLUETOOTH, SOCK_RAW, BTPROTO_HCI);
struct sockaddr_hci addr = { AF_BLUETOOTH, (unsigned short)dev, HCI_CHANNEL_USER };
if (fd < 0 || bind(fd, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
perror("bind(HCI_CHANNEL_USER)");
return 1;
}
char fd_str[16];
snprintf(fd_str, sizeof(fd_str), "%d", fd);
setenv("MULTIPAZ_BLE_HCI_FD", fd_str, 1);
execvp(argv[2], &argv[2]);
perror("execvp");
return 1;
}

Constructors

Link copied to clipboard
constructor(hciDeviceIndex: Int = defaultHciDeviceIndex(), preOpenedHciFd: Int? = defaultPreOpenedHciFd())

Types

Link copied to clipboard
object Companion

Properties

Link copied to clipboard

Whether the underlying transport keeps its descriptor open across close calls for reuse.

Functions

Link copied to clipboard
open override fun close()

Closes the underlying HCI transport and unblocks any pending readPacket call.

Link copied to clipboard
open override fun markControllerResetCompleted()

Notifies the transport that HCI_Reset has already been executed and acknowledged prior to close.

Link copied to clipboard
suspend fun open()

Opens the Linux HCI_CHANNEL_USER socket (or adopts preOpenedHciFd if configured) and prepares the non-blocking poll/wake-pipe loop.

Link copied to clipboard
open suspend override fun readPacket(): ByteArray?

Reads the next H4-framed HCI packet from the controller, or returns null if closed.

Link copied to clipboard
open suspend override fun writePacket(packet: ByteArray)

Writes an H4-framed HCI packet to the controller.