Homebridge UE Boom (Speaker Plugin)

This is an accessory plugin for Homebridge allowing to turn on and off a UE Boom speaker and integrating it with HomeKit.

Installation

Homebridge

First, install Homebridge and gatttool via Bluez (you also need Node.js installed):

sudo npm install -g homebridge
sudo apt-get install bluez

Then install this plugin:

sudo npm install -g homebridge-ueboom

Homebridge Docker

In case you're using Homebridge Docker, add the following line to your container startup script:

apk add --no-cache bluez-deprecated

Then install this plugin:

sudo npm install -g homebridge-ueboom

Find out the MAC address

To get the plugin working you have to provide the following parameters:

speaker: MAC address of the speaker
host: MAC address of the audio source device (iPhone, ...)

In case you don't know how to retrieve the MAC address of the speaker:

Pair the speaker to your MacBook
Click on Bluetooth icon in the Menu Bar while pressing ⌥ Option
Select the speaker of which you need the address
Write down the MAC address

To retrieve the MAC address of the host, it strictly depends on the device you're using. If you're playing music from an iPhone/iPad then you can find it in Settings > General > About > Bluetooth.

Configuration

Create a ~/.homebridge/config.json file (change name, speaker and host as necessary):

{
  "bridge": {
    "name": "Homebridge",
    "username": "E5:B9:0D:64:1E:CB",
    "port": 51826,
    "pin": "031-45-154"
  },
  "description": "This is an example configuration file with homebridge-ueboom plugin.",
  "accessories": [
    {
      "accessory": "UEBoomSpeaker",
      "name": "Bathroom Speaker",
      "speaker": "C0:28:8D:45:28:55",
      "host": "4098ADA356C4"
    }
  ],
  "platforms": []
}

Breaking change: in case you're transitioning from v0.0.1 or v0.0.2, update your config file with the newly requested variables!

How does it work

Since more than one person asked me how this works and that the speaker doesn't connect to the Pi after being turned on, I thought I could spend a couple of words about.

This is the command that does the whole work, everything else is just boilerplate code for the homebridge plugin:

gatttool -i hci0 -b $SPEAKER_ADDRESS --char-write-req -a 0x0003 -n ${HOST_ADDRESS}${ON_OFF_COMMAND}

SPEAKER_ADDRESS is the MAC address of the speaker
HOST_ADDRESS is the MAC address of the audio source device (iPhone, ...)
ON_OFF_COMMAND is 01 to turn the speaker on and 02 to turn it off

The gatttool command turns the speaker on but doesn’t associate the speaker with the Raspberry Pi. The speaker connects to the host device (in my case my iPhone).

I don't know the exact specifications so this is pure speculation: the speaker itself has the usual Bluetooth 4.0 module that allows to stream music, in addition to that there's also a BLE (Bluetooth Low Energy) module that for its own nature is always on and allows to turn the speaker on and off remotely (within range). The only reason why I'm not sure this is the real reason is that the two modules would probably have two separate MAC addresses, and from what I've observed there's only one single address available.

How I did it

I knew that the speaker could be turned on remotely (within range) using the proprietary Ultimate Ears app, and it was obvious that the bluetooth command was sent by the application itself.

I first installed Apple's Bluetooth logging profile on my iPhone, then connected it to the Mac via USB and used PacketLogger to trace the packages sent from the phone (specifically ATT Send type). By opening the UE app and tapping on the remote power button in it I was able to sniff the conversation between the phone and the speaker as shown in this screenshot.

From here I retrieved the MAC address of the speaker (as described above) and used gatttool to perform a write request, and BOOM (pun intended) I can turn on the speaker from my command line.

Contributors

Special thanks go to:

Newton Barbosa, for noticing that Value is the host MAC address without semicolons followed by 01.
Donavan Becker, for adding the easy config for onzu/homebridge-config-ui-x.
Martin Kuhl, for figuring out how to turn the speaker off by replacing the final 01 with 02.