UBT(4)

💖 UBT(4) — USB Bluetooth driver 💖

ok so bestie, you found a Kernel Interfaces Manual page and it's literally about the ubt driver. buckle up, we're getting into dongle lore 🦋

---

✨ NAME ✨

ubt — the USB Bluetooth driver, aka the little guy that makes your tiny USB Bluetooth stick actually do stuff 💅

---

🎀 SYNOPSIS 🎀

ubt* at uhub? port ? configuration ? interface ?

like, that's the whole ritual. no cap. ✨

---

🌸 DESCRIPTION 🌸

okay so the ubt driver is the one that gives the Bluetooth protocol stack support for USB Bluetooth dongles. it's giving matchmaker, honestly — it introduces your dongle to the stack 🫶

here's the cute part (and also the slightly annoying part): USB Bluetooth dongles show up with two interfaces, and the ubt driver claims both of them. yes, both. it's an all-in package deal 💖

the second interface is the one used for Isochronous data, and it has several alternate configurations regarding bandwidth consumption. you can set which one you want with the hw.ubtN.config sysctl(8) variable 🔥

wanna know how many alternate configurations exist? that number lives in the hw.ubtN.alt_config variable. and the isoc frame size for your current configuration is chillin' in the hw.ubtN.sco_rxsize and hw.ubtN.sco_txsize variables. icons only 👑

by default, configuration 0 is selected — which means no bandwidth is used on the Isochronous interface, and no SCO data can be sent. zero. none. it's giving "resting state" 😴

for the complete instructions on setting bandwidth consumption, consult the Bluetooth USB specification at https://www.bluetooth.org/ — the following extract is still useful as general guidance, though details may differ between manufacturers. (translation: don't come for me if your dongle does its own thing 🙈)

• 0 — No active voice channels
• 1 — One voice channel with 8-bit encoding
• 2 — Two voice channels with 8-bit encoding, or one voice channel with 16-bit encoding.
• 3 — Three voice channels with 8-bit encoding
• 4 — Two voice channels with 16-bit encoding
• 5 — Three voice channels with 16-bit encoding

slay, that's the whole menu 💜

---

🌈 SEE ALSO 🌈

• bluetooth(4)
• uhub(4)
• sysctl(8)

(the whole friend group fr fr 🫶)

---

🦋 HISTORY 🦋

ngl this one has a whole glow-up arc. this ubt device driver was originally a character device, written by David Sainty and Lennart Augustsson. then it got rewritten to support socket based Bluetooth access for NetBSD 4.0 by Iain Hibbert. main character energy, honestly ✨

---

💀 CAVEATS 💀

okay bestie, listen carefully, this is the part where it gets real 😭

Isochronous data is seemingly not well supported over USB in the current system, and to get SCO working you may have to calculate the SCO packet size that the stack will use. it's the sco_mtu value reported by the btconfig(8) command, and when you combine it with the SCO header (3 bytes) it should fit exactly into an integer number of Isochronous data frames — where the frame size is indicated by the ‘hw.ubtN.sco_txsize’ sysctl variable. math girl summer, unfortunately 🧮💅

for example: I want one voice channel (which is all that is supported, for now) so I'm using configuration #2, with a frame length of 17 bytes. this gives possible values of:

(17 * 1) - 3 = 14
(17 * 2) - 3 = 31
(17 * 3) - 3 = 48
(17 * 4) - 3 = 65
(17 * 5) - 3 = 82

etc. 👑

btconfig(8) shows the maximum SCO payload as 64 bytes, so I'm using the next smaller size of 48, to minimize the overhead of the 3 header bytes. see? simple. iconic. lowkey stressful. 💖

the SCO packet size can be changed using the ‘scomtu’ option to btconfig(8) 🎀

and the failure mode? the USB Bluetooth dongle locks up 😭 though generally removal/reinsertion will clear the problem. so like. unplug it and plug it back in. the ancient IT ritual. it works. 🫶

---

⭐ BUGS ⭐

The Isochronous configuration can only be changed when the device is not marked up. that's it, that's the bug note, respect the boundary 😤✨

---

and that's the tea, bestie 🍓 this page came from the Debian gang, version dated August 27, 2006 — a whole vintage moment, and yes she still ate 💅💖

UBT(4) — go forth and slay your dongle configuration 🌸🦋👑