Skip to content

Instantly share code, notes, and snippets.

@pjobson
Last active July 22, 2024 20:20
Show Gist options
  • Save pjobson/fc3a252387367ecc49569c1a5a6ab038 to your computer and use it in GitHub Desktop.
Save pjobson/fc3a252387367ecc49569c1a5a6ab038 to your computer and use it in GitHub Desktop.
Linux Bluetooth CLI with BluetoothCTL

Linux Bluetooth CLI with BluetoothCTL

I've had a lot of problems using the built in blueman application under Ubuntu/Mint distributions. I'm not exactly sure why, frequently devices will connect then instantly disconnect. I've parsed through various StackOverflow articles and other help pages, I could never get a working answer.

WARNING

If you're having bluetooth issues, do not uninstall the libbluetooth3 package. It may uninstall your desktop environment.

Adapter

Be sure to have a good and well supported bluetooth adapter. I suspect a lot of the issues out there are from old, poor quality, improperly implemented, and/or slightly broken bluetooth adapters.

I've had great luck with the Edimax BT-8500 as of this writing it was about $13. Device info is attached below.

I was originally using an Intel Dual Band Wireless-AC 7260HMW and had nothing but problems.

CLI

With many of the great things in Linux, let's ignore the GUI for now.

bluetoothctl

This opens its own [bluetooth] shell.

Shows your adapters (controllers).

# list controllers
list
# returns one or more controllers like:
Controller FF:FF:FF:FF:FF:FF hostname [default]
# get controller information
show FF:FF:FF:FF:FF:FF

Before trying to pair, let's try scanning.

scan on
# shows:
[CHG] Controller FF:FF:FF:FF:FF:FF Discovering: yes
# followed by showing Devices within range.
[CHG] Device E8:51:77:CE:02:BB RSSI: -72
[CHG] Device E8:51:77:CE:02:BB LegacyPairing: yes

You can get a device's information with:

info E8:51:77:CE:02:BB

This should return metadata for this device such as:

Device E8:51:77:CE:02:BB (public)
  Name: Bedroom TV
  Alias: Bedroom TV
  Class: 0x0028043c
  Icon: audio-card
  Paired: no
  Trusted: no
  Blocked: yes
  Connected: no
  LegacyPairing: no
  UUID: Audio Source              (0000110a-0000-1000-8000-00805f9b34fb)
  UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)
  UUID: A/V Remote Control        (0000110e-0000-1000-8000-00805f9b34fb)
  UUID: PnP Information           (00001200-0000-1000-8000-00805f9b34fb)
  UUID: Vendor specific           (00000000-0000-0000-0000-000000000000)
  RSSI: -76

Blacklisting unwanted devices, the first thing I'm going to do is blacklist any devices which I'm never going to connect to with this machine.

Here I'm blocking the TV as above and some kind of hydrometer, which I think is at my neighbor's house.

block E8:51:77:CE:02:BB
block A4:C1:38:F6:DF:69

Now I can do devices to see what has been registered.

devices
# returns
Device E8:51:77:CE:02:BB Bedroom TV
Device A4:C1:38:F6:DF:69 Govee_H5074_DF69

And I can verify these have been blacklisted.

info E8:51:77:CE:02:BB
# returns
Device E8:51:77:CE:02:BB (public)
  Name: Bedroom TV
  Alias: Bedroom TV
  Class: 0x0028043c
  Icon: audio-card
  Paired: no
  Trusted: no
  Blocked: yes
  Connected: no
  LegacyPairing: no
  UUID: Audio Source              (0000110a-0000-1000-8000-00805f9b34fb)
  UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)
  UUID: A/V Remote Control        (0000110e-0000-1000-8000-00805f9b34fb)
  UUID: PnP Information           (00001200-0000-1000-8000-00805f9b34fb)
  UUID: Vendor specific           (00000000-0000-0000-0000-000000000000)
  RSSI: -74

Now I'll start attempting to pair a Sunwaytek H510 controller which I was previously having issues with staying connected.

To pair, hold the center circle button and one of the ABXY buttons for 2 seconds. I'm not 100% sure what the difference is, I think I used the Android pairing, but you'll have to experiement. They show the following in the manual:

  • WII: 🔘 + B
  • Android: 🔘 + A
  • Windows: 🔘 + X
  • Apple: 🔘 + Y

Hold your combination for 2 seconds, then wait for it to appear in the scanning stream.

Mine for example:

[CHG] Device 00:90:E0:12:01:37 Gamepad

Then pair it and trust it.

pair 00:90:E0:12:01:37
trust 00:90:E0:12:01:37
devices
# My list including blacklisted devices.
Device E8:51:77:CE:02:BB Bedroom TV
Device 00:90:E0:12:01:37 Gamepad
Device A4:C1:38:F6:DF:69 Govee_H5074_DF69
# info the device
info 00:90:E0:12:01:37 
# returns
Device 00:90:E0:12:01:37 (public)
  Name: Gamepad
  Alias: Gamepad
  Class: 0x00002508
  Icon: input-gaming
  Paired: yes
  Trusted: yes
  Blocked: no
  Connected: no
  WakeAllowed: yes
  LegacyPairing: no
  UUID: Human Interface Device... (00001124-0000-1000-8000-00805f9b34fb)
  UUID: PnP Information           (00001200-0000-1000-8000-00805f9b34fb)
  Modalias: usb:v1949p0402d011B

Stop scanning.

scan off

Power off the device, then power it back on and it should automatically connect and keep the connection.

Bus 003 Device 003: ID 7392:c611 Edimax Technology Co., Ltd Edimax Bluetooth Adapter
Device Descriptor:
bLength 18
bDescriptorType 1
bcdUSB 1.10
bDeviceClass 224 Wireless
bDeviceSubClass 1 Radio Frequency
bDeviceProtocol 1 Bluetooth
bMaxPacketSize0 64
idVendor 0x7392 Edimax Technology Co., Ltd
idProduct 0xc611
bcdDevice 2.00
iManufacturer 1 Realtek
iProduct 2 Edimax Bluetooth Adapter
iSerial 3 00E04C239987
bNumConfigurations 1
Configuration Descriptor:
bLength 9
bDescriptorType 2
wTotalLength 0x00b1
bNumInterfaces 2
bConfigurationValue 1
iConfiguration 0
bmAttributes 0xe0
Self Powered
Remote Wakeup
MaxPower 500mA
Interface Descriptor:
bLength 9
bDescriptorType 4
bInterfaceNumber 0
bAlternateSetting 0
bNumEndpoints 3
bInterfaceClass 224 Wireless
bInterfaceSubClass 1 Radio Frequency
bInterfaceProtocol 1 Bluetooth
iInterface 4 Bluetooth Radio
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x81 EP 1 IN
bmAttributes 3
Transfer Type Interrupt
Synch Type None
Usage Type Data
wMaxPacketSize 0x0010 1x 16 bytes
bInterval 1
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x02 EP 2 OUT
bmAttributes 2
Transfer Type Bulk
Synch Type None
Usage Type Data
wMaxPacketSize 0x0040 1x 64 bytes
bInterval 0
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x82 EP 2 IN
bmAttributes 2
Transfer Type Bulk
Synch Type None
Usage Type Data
wMaxPacketSize 0x0040 1x 64 bytes
bInterval 0
Interface Descriptor:
bLength 9
bDescriptorType 4
bInterfaceNumber 1
bAlternateSetting 0
bNumEndpoints 2
bInterfaceClass 224 Wireless
bInterfaceSubClass 1 Radio Frequency
bInterfaceProtocol 1 Bluetooth
iInterface 4 Bluetooth Radio
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x03 EP 3 OUT
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0000 1x 0 bytes
bInterval 1
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x83 EP 3 IN
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0000 1x 0 bytes
bInterval 1
Interface Descriptor:
bLength 9
bDescriptorType 4
bInterfaceNumber 1
bAlternateSetting 1
bNumEndpoints 2
bInterfaceClass 224 Wireless
bInterfaceSubClass 1 Radio Frequency
bInterfaceProtocol 1 Bluetooth
iInterface 4 Bluetooth Radio
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x03 EP 3 OUT
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0009 1x 9 bytes
bInterval 1
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x83 EP 3 IN
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0009 1x 9 bytes
bInterval 1
Interface Descriptor:
bLength 9
bDescriptorType 4
bInterfaceNumber 1
bAlternateSetting 2
bNumEndpoints 2
bInterfaceClass 224 Wireless
bInterfaceSubClass 1 Radio Frequency
bInterfaceProtocol 1 Bluetooth
iInterface 4 Bluetooth Radio
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x03 EP 3 OUT
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0011 1x 17 bytes
bInterval 1
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x83 EP 3 IN
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0011 1x 17 bytes
bInterval 1
Interface Descriptor:
bLength 9
bDescriptorType 4
bInterfaceNumber 1
bAlternateSetting 3
bNumEndpoints 2
bInterfaceClass 224 Wireless
bInterfaceSubClass 1 Radio Frequency
bInterfaceProtocol 1 Bluetooth
iInterface 4 Bluetooth Radio
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x03 EP 3 OUT
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0019 1x 25 bytes
bInterval 1
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x83 EP 3 IN
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0019 1x 25 bytes
bInterval 1
Interface Descriptor:
bLength 9
bDescriptorType 4
bInterfaceNumber 1
bAlternateSetting 4
bNumEndpoints 2
bInterfaceClass 224 Wireless
bInterfaceSubClass 1 Radio Frequency
bInterfaceProtocol 1 Bluetooth
iInterface 4 Bluetooth Radio
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x03 EP 3 OUT
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0021 1x 33 bytes
bInterval 1
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x83 EP 3 IN
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0021 1x 33 bytes
bInterval 1
Interface Descriptor:
bLength 9
bDescriptorType 4
bInterfaceNumber 1
bAlternateSetting 5
bNumEndpoints 2
bInterfaceClass 224 Wireless
bInterfaceSubClass 1 Radio Frequency
bInterfaceProtocol 1 Bluetooth
iInterface 4 Bluetooth Radio
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x03 EP 3 OUT
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0031 1x 49 bytes
bInterval 1
Endpoint Descriptor:
bLength 7
bDescriptorType 5
bEndpointAddress 0x83 EP 3 IN
bmAttributes 1
Transfer Type Isochronous
Synch Type None
Usage Type Data
wMaxPacketSize 0x0031 1x 49 bytes
bInterval 1
Device Status: 0x0001
Self Powered
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment