LinuxHciSocketPacketIo
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(orhci1)Environment variable:
MULTIPAZ_BLE_HCI_DEV=1(orhci1)
To run without root under systemd, grant ambient CAP_NET_ADMIN:
[Service]
User=multipaz
AmbientCapabilities=CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_ADMINMode 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()issuesHCI_Reset.close wakes the
poll()loop and writes a best-effortHCI_Reset(01 03 0c 00) to stop advertising, scanning, and active connections, without callingclose(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;
}Properties
Whether the underlying transport keeps its descriptor open across close calls for reuse.
Functions
Closes the underlying HCI transport and unblocks any pending readPacket call.
Notifies the transport that HCI_Reset has already been executed and acknowledged prior to close.
Reads the next H4-framed HCI packet from the controller, or returns null if closed.
Writes an H4-framed HCI packet to the controller.