This is the repo for Linux driver of Espressif Bluetooth devices
sudo apt install build-essential linux-headers-$(uname -r)
Run make command
A cross-compilation environment needs to be set up.
Build command example:
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- KSRC=/path/to/kernel/build
Targets copy esp_btusb.ko into the kernel module tree and refresh module metadata. When the matching Espressif Bluetooth USB device is connected, the system will normally load this module automatically (udev / modalias). See Load module for manual load and unload.
| Target | Description |
|---|---|
install |
Build if needed, install esp_btusb.ko under MODDESTDIR, run depmod |
uninstall |
Remove the installed .ko / .ko.gz / .ko.xz from MODDESTDIR, run depmod |
sign-install |
all → sign → install (build, sign, then install) |
Typical system install (needs root for default paths):
sudo make install
sudo make uninstall
| Variable | Default | Meaning |
|---|---|---|
KVER |
$(uname -r) |
Kernel version string for depmod and default KSRC (native) |
DESTDIR |
empty | Staging root (packaging); prepended to install paths |
MODDESTDIR |
$(DESTDIR)/lib/modules/$(KVER)/extra |
Directory for esp_btusb.ko |
COMPRESS_GZIP |
unset | Set to y to gzip the installed .ko |
COMPRESS_XZ |
unset | Set to y to xz-compress the installed .ko |
Example: install only for kernel 6.1.0:
sudo make install KVER=6.1.0
When the kernel enforces module signatures, sign the built module with a Machine Owner Key (MOK), enroll the public certificate via mokutil, reboot once to confirm in the blue MOK manager screen, then install or load the signed .ko.
| Target | Description |
|---|---|
sign |
Optionally generate MOK.priv / MOK.der and import with mokutil; then run kernel scripts/sign-file on esp_btusb.ko |
sign-install |
Build, sign, and install in one step |
| Variable | Default | Meaning |
|---|---|---|
KEY_GEN |
unset | Set to y to run openssl to create ./MOK.priv and ./MOK.der, then mokutil --import MOK.der (still in the source directory only) |
MOK_PRIV |
MOK.priv |
Private key path passed to sign-file |
MOK_DER |
MOK.der |
Certificate (DER) path passed to sign-file |
Typical first-time flow (run from the driver source directory; KEY_GEN=y is interactive and needs reboot after mokutil):
sudo make sign KEY_GEN=y
# Reboot and complete MOK enrollment in the firmware UI, then:
sudo make sign
sudo make install
Or in one shot after keys exist and MOK is enrolled:
sudo make sign-install
Use existing keys from another path:
sudo make sign MOK_PRIV=/path/to/key.priv MOK_DER=/path/to/cert.der
Keep MOK.priv secret. To confirm an enrolled key matches a local MOK.der, compare SHA1 fingerprints from mokutil --list-enrolled and openssl x509 -inform DER -in MOK.der -noout -fingerprint -sha1.
After a local build in the source tree:
sudo insmod esp_btusb.ko
If the module was installed with make install, load by name (handles path and dependencies):
sudo modprobe esp_btusb
Driver will load firmware file esp32e22.bin from /lib/firmware/espressif
sudo rmmod esp_btusb
dmesg
This driver can collect the device log from USB vendor interface, and the log output mode can be:
DEV_LOG_MODE_NONE: Drop device logDEV_LOG_MODE_DMESG: Print device log to kernel ring buffer, can display withdmesgcommandDEV_LOG_MODE_GENL: Send to userspace with generic netlink
log_level: Integer, control the driver log level, reuse the value oflinux/kern_levels.h
#define LOGLEVEL_ERR 3 /* error conditions */
#define LOGLEVEL_WARNING 4 /* warning conditions */
#define LOGLEVEL_INFO 6 /* informational */
#define LOGLEVEL_DEBUG 7 /* debug-level messages */
dev_log_mode: Integer, control the device log output mode.
#define DEV_LOG_MODE_NONE 0
#define DEV_LOG_MODE_DMESG 1
#define DEV_LOG_MODE_GENL 2
| Target | Description |
|---|---|
all / modules |
Build esp_btusb.ko |
clean |
Kernel make clean in the module directory |
clean-temp |
Remove leftover object / kbuild files in the source tree |