How to scan for Bluetooth devices?

Configuration
1

Added a Bluetooth stick to my server, and made it reboot “a couple of times”, as per the documentation. It was already being recognised perfectly fine, but I did a few more reboots anyway because the documentation says so. No idea why though, but alas, here we are.

So now, how do I go about adding a BT device?

In any other OS, I need to start a scan for nearby devices. In HA such option isn’t available. But it also doesn’t magically scan by itself, it seems, or it would’ve found something at least - there’s always something nearby, I have neighbours with BT devices, I have a mouse, I have a lamp that I think might possibly have BT, I have a phone, a laptop, and possibly more that I don’t even realise contains BT.

Even if there are no BT devices nearby, the very least I want it to say is “I’ve scanned the area, but didn’t find anything”.

Currently, the BT is just sitting there, seemingly doing bumall.

I don’t think matters which exact BT stick I’m using, since the integration for it is working perfectly and the device’s hardware properties are detected and showing up correctly.

2

If you just want to scan for devices, Bermuda works very well, though it’s intended for room-level presence detection. It should detect nearby devices through your Bluetooth stick without the need to add any proxies.

If you want to connect to Bluetooth devices, I think you’ll need the appropriate integration for each one. The Bluetooth stick is just the hardware part - it doesn’t pair like Bluetooth on a phone.

1 Like
3

It’s always ‘scanning’. Only things that have an integration will show up (and who’s integration supports discovery, which most/all core ones do). Do you have such a device?

4

@jackjourneyman Thanks for your input, but I don’t think you quite understood my intention. I wanted to scan for devices with the intent to pair them permanently. Say for example, a Hue lamp. Presence detection appears to be a whole other beast in its own right. Something to remember for another time, for sure.

@brooksben11 Thank you. I do have such device, but in order to know for sure, wouldn’t it be useful if HA would show some kind of feedback on what it has found so far? I have plenty of BT devices, but with zero feedback I can’t tell apart:

  • Is the integration working at all?
  • Is the hardware even working?
  • Are any found BT devices supported?
  • Are my BT devices letting themselves be found (in pairing mode)?

Do you understand now why it’s important that a feature doesn’t only “just work”, because when it appears not to, you’re stuck with literally nothing to go on. The fourth point can’t be fixed by HA, but I can’t know if that’s the problem if I don’t know the answer to 1-3.

5

What device? Is the integration part of core or custom?

6

I don’t know, that’s the thing. I don’t know if scanning works if it doesn’t provide feedback of any kind.

7

You kind of seem to be talking in circles. BT only works with devices that there’s an integration for. If you don’t have one of those devices, you’re not going to see anything in HA. If you have a device you think it should be seeing, tell us what that is.

If you look at the logs for the BT Proxy, it will show you what it’s doing/seeing.

8

I think there’s something I didn’t make quite clear.

To know whether some device has an integration, it would have to show up. If it doesn’t, the whole BT mechanism could also be broken - there’s no way to tell if it doesn’t seemingly do anything. It needs to show some kind of feedback when no devices are found, so that the user knows BT itself works correctly.

To answer your question directly: I tried with a Hue lamp - I think those have BT as well. I also tried a plain vanilla BT mouse - nothing shows up.

The point is, when I scan with my laptop, I see all kinds of devices. When I scan (or rather, not-scan) with HA, I see nothing showing up, which leads back to my original point: is BT even working in the first place?

9

@thany, if you use Home Assistant OS, you can run the following in the terminal: bluetoothctl devices. It will show the Bluetooth devices discovered by the OS.

10

It says unknown command 'bluetoothctl' for 'ha'

But it doesn’t matter. From your description, I take it this shows bluetooth devices that are already discovered, but perhaps that discovery part isn’t happening. Or something else is broken.

What I want (and I don’t mean to sound like a karen or anything) is a button to start scanning for BT devices now, and have it come back to me with a clear and concise messages which devices have been found, or clearly state no devices have been found.

I keep repeating myself, but since I now have a BT device in pairing mode well within range, and should 100% be supported, and it’s not finding anything, I have no way of knowing whether BT even works in the first place, or even scanning for devices is actually happening as @brooksben11 has been alluding to. I don’t know which “link in the chain” is not working, which is frustrating.

As an analogy, say you connect a monitor to a pc, and it doesn’t work. Wouldn’t you want to investigate which part doesn’t work? Wouldn’t you want to make it give some kind of feedback and/or eliminate the variables? It could be the pc, the video card, the cable, the monitor itself. No idea. And allthewhile the vendor is just saying “nope, just keep trying, it should work”. If it bloody well doesn’t, it just leaves you between a rock and a hard place.

Either way, no feedback of any kind whatsoever, in a system that consists of multiple possible points of failure, is a dark pattern.

So I feel HA should become better at this, in several key points:

  • There needs to be a “scan for devices” button to give the user confidence that the process of scanning for devices is occurring.
  • There needs to be a message at the end of it, telling the user how many devices were found, and of what type. Just like literally every other OS.
  • The “scan for devices” button should result in an error message if BT is somehow not set up correctly, like if the BT radio isn’t working despite being added as an integration. Error message should also display a code that is useful for further investigation.

Another key point to make is the above will create a certain level of familiarity with the user. Since every OS on the planet works this way, the user can be more familiar with the same functionality on their HA box.

Btw, I’m also seeing this is the terminal:

image
image1404×122 25.1 KB

So it’s not able to stop scanning. But that doesn’t neccesarily mean it has been able to start scanning. Maybe it can’t stop scanning because it never started. Who knows. It’s a black box to me.

11

I got another device, a shelly temperature monitor. This one definitely has BT and has it enabled and it broadcasting for pairing.

HA detects nothing. Not this sensor, nor any of the other devices that my phone detects perfectly fine.

I said it before and I will say it again. I have no way of knowing which part in the chain isn’t functioning. So again, how do I trigger scanning for devices, and/or get to a message explaining what has been found or what is broken?

This is a silent fail. Whoever thought it was a good idea to make it like this, has made a collosal mistake. I don’t even know where to start. And you don’t know either, because I don’t know what information to give you, what with absolutely nothing happening. So now what.

12

I think I understand the confusion.
Let’s try this, go into settings and then to devices then to Bluetooth make sure passive scanning is turned off.
Maybe a reboot is needed not sure but why not do it to be on the safe side.
Now once it comes up go to devices and see if it sees your Bluetooth device. Make sure it’s in pairing mode if it is needed.
Now, if it doesn’t find it, there may be an integration needed to scan and add it to home assistant.
See if that works for you.

13

I disabled passive scanning, and gave it a reboot just in case.

Then, as I understand it, you do absolutely nothing for it to start scanning. It does not find my Hue lamp which is confirmed to be in pairing mode.

But you hit the nail right on the head: “there may be”. Wel I don’t know, this is the problem. There may be something missing, something not working, I have no friggen clue! Nothing is telling me that BT is scanning at the moment, and so I don’t know if even that is working properly.

If there was a UI to deliberately go and scan for new devices, like there is for ZHA, that UI could tell me about any problems. But either there’s no device, or some part in the chain doesn’t work.

So how do I diagnose this?

14

By chance have you installed the Philips hue integration?

I don’t know if you have other ble devices that Passive BLE monitor integration supports, but it is a great way to see if your Bluetooth is scanning.

15

You need to install the Bluetooth Tracker integration, the Bluetooth LE Tracker integration or some other integration that will track devices, like Bermuda, or possibly the Theengs Gateway add-on.

Bluetooth Tracker and Bluetooth LE Tracker will list the devices they discover in known_devices.yaml.

16

The integrations above should be installed, including BLE. Many “bluetooh” devices are actually BLE, so you need that integration too. But those two integrations are just low level basics. They do little or nothing on their own, except see the transmissions.

As said, you need to find the integration that supports a device you want to add. If that is a core integration, the device may be autodiscovered if you have bluetooth and ble, but it may not be.

There’s no indication that hue bulbs are supported though bluetooth, only zigbee or the hue hub. So that will probably not work. With all devices it is recommended to see if they are supported and though what integration. Then follow instructions given by that integration.

Temperature sensors often do not need pairing. The BLE integration will likely be able to discover them IF the integration for the device is present in HA. But it will require at least the BLE integration too.

If devices do require pairing, it is the integration for that device that should initiate the process by adding the integration and follow its instructions. The bluetooth integration is NOT a generic way of integrating devices but a service the integrations use. Think of the device specific integrations as drivers that rely on the bluetooth integration for talking to the bluetooth adapter.

For instance, if you want to add a bluetooth switch ot curtain, you add the Switchbot integration to connect. Just to get an idea, see the integration docs how that works for this particular device:

Next wednesday’s release of Home Assistant will add functionality to see if the bluetooh integration sees bluetooth devices, but you will still need other integrations to interpret the bluetooth data or send commands. Google the device you want to add in combination with Home Assistant to see if a bluetooth integration is supported.

1 Like
17

Okay, now we’re getting somewhere.

So I dove into the documentation for both, and immediately, I get stuck on their configuration. First of all, both integrations require:

device_tracker:
  - platform: bluetooth_tracker

Or

device_tracker:
  - platform: bluetooth_le_tracker

So it looks to me like I can’t have both. Or I should ask, what does the config look like, when both need to be enabled?

Secondly, it lists some neat config options, but it’s not clear how or where to add them. For example, do I do this?

device_tracker:
  - platform: bluetooth_le_tracker
  - track_battery: true

Or this?

device_tracker:
  - platform: bluetooth_le_tracker
    track_battery: true

Or this?

device_tracker:
  - platform: bluetooth_le_tracker
    - track_battery: true

Or something else? The issue is that it’s not made clear what the expected syntax (structure, rather) is for these integrations.

That’s that for the configuration. Now as for the documentation, I have some confusion there as well. It states:

The integration is now shown on the integrations page under Settings > Devices & services.

First of all, no it’s not. I’ve added the example config for the non-LE integration, and restarted HA. That should be it.

But it also says:

In some cases it can be that your device is not discovered. In that case let your phone scan for Bluetooth devices while you restart Home Assistant. Just hit Scan on your phone…

What does my phone have to do with it? Why does the documentation seemingly out of the blue start talking about phones?

And for clarity, I haven’t got any device yet, that I want to add. Of course not! I mean other than stuff I happen to have laying around for testing purposes. I’m not about to purchase BT smarthome devices before the whole bluetooth menagery provably works. So in short, I just want to see something happening that indicates BT is working in the first place.

For Zigbee and Z-Wave, you can absolutely do so. You can do a number of tests quite easily to see that the hardware is doing at least something, even if no devices are found.

18

Also I noticed I’m now getting this error in the log:

2025-02-10 12:56:52.508 ERROR (SyncWorker_3) [homeassistant.util.package] Unable to install package PyBluez==0.22: × Failed to build `pybluez==0.22`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit
      status: 1)

      [stdout]
      running bdist_wheel
      running build
      running build_py
      creating build/lib.linux-x86_64-cpython-313/bluetooth
      copying bluetooth/ble.py -> build/lib.linux-x86_64-cpython-313/bluetooth
      copying bluetooth/bluez.py ->
      build/lib.linux-x86_64-cpython-313/bluetooth
      copying bluetooth/btcommon.py ->
      build/lib.linux-x86_64-cpython-313/bluetooth
      copying bluetooth/msbt.py -> build/lib.linux-x86_64-cpython-313/bluetooth
      copying bluetooth/osx.py -> build/lib.linux-x86_64-cpython-313/bluetooth
      copying bluetooth/widcomm.py ->
      build/lib.linux-x86_64-cpython-313/bluetooth
      copying bluetooth/__init__.py ->
      build/lib.linux-x86_64-cpython-313/bluetooth
      running build_ext
      building 'bluetooth._bluetooth' extension
      creating build/temp.linux-x86_64-cpython-313/bluez
      gcc -fno-strict-overflow -Wsign-compare -DNDEBUG -g -O3 -Wall
      -fno-semantic-interposition -fno-builtin-malloc -fno-builtin-calloc
      -fno-builtin-realloc -fno-builtin-free -DTHREAD_STACK_SIZE=0x100000
      -fPIC -I./port3 -I/tmp/.tmpCtuTcM/builds-v0/.tmpqFC0ey/include
      -I/usr/local/include/python3.13 -c bluez/btmodule.c -o
      build/temp.linux-x86_64-cpython-313/bluez/btmodule.o

      [stderr]
      error: command 'gcc' failed: No such file or directory

      hint: This usually indicates a problem with the package or the build
      environment.

Googling the error…

Apparently it’s an error many people are seeing, and the issue is closed as not planned:

Or just closed without even so much as a meaningful response, nevermind a solution:

Here people are saying the integration is deprecated. But deprecated in favour of what, is unclear to me:

In short, I wonder why I am being recommended the bluetooth_tracker integration, seeing how it is apparently deprecated and also just straight up broken.

And, by extension, seeing how utterly it fails with that error, why is it listed under the Add Integration button?

1 Like