ha-bt-proximity

Distributed Bluetooth Room Presence for Home Assistant

This is a complete DIY solution for room presence/proximity detection in Home Assistant. It uses a Raspberry Zero W to track the proximity of phones, smartwatches, etc. via bluetooth. The relative proximity is determined by querying the RSSI (signal strength) of the tracked device using a combination of hcitool commands executed via a Node.js script.

Once the signal strength is retrieved, a proximity value ranging from 0 (closest proximity) to -100 (undetectable) is calculated and pushed to a MQTT Broker (Mosquitto) running in Home Assistant. From there, you can setup sensors to determine the presence in a room (or relative distance) of a particular user. These sensors can be useful for triggering Automations based on presence (like turning lights on when someone walks into a room, turning an AC off when a room is empty, and more).

NOTE: This approach is suitable for Bluetooth Classic and is not compatible with Bluetooth Low Energy (BLE) devices.

Requirements

Raspberry Pi Zero W (~$30 USD)
Micro SD Card (2GB size minimum)
A Home Assistant installation up and running.

Home Assistant Configuration

Install Mosquitto MQTT Broker in Home Assistant. Instructions here.
Add a new MQTT sensor in your Home Assistant configuration.yaml file. Make sure to replace the value in state_topic to match the name of the room you will place the Raspberry Pi Zero at (bedroom, living room, kitchen, etc.) and replace 00:00:00:00:00:00 for the actual Bluetooth MAC address of the device you want to track:
```
sensor:
    - platform: mqtt
      state_topic: 'location/bedroom/00:00:00:00:00:00'
      value_template: '{{ value_json.proximity }}'
      unit_of_measurement: 'level'
      name: 'Xavier Bedroom Proximity'
```
NOTE: You can add multiple mqtt sensors if you want to track more devices.
Save configuration.yaml and restart Home Assistant.

Raspberry Pi Zero W OS Setup

Download latest version of Raspbian Jessie Lite Stretch
Download balenaEtcher.
Copy the image to the SD card using balenaEtcher. Instructions here.
Remove the SD Card and re-insert it. There will be 2 partitions on the SD card, including one named boot.
To enable SSH, in the boot partition create blank file (without any extension) in the root directory called ssh

To setup the Wifi network, in the boot partition, create file named a wpa_supplicant.conf in the root directory and enter your wi-fi network details:

country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="Your Network Name"
    psk="Your Network Password"
    key_mgmt=WPA-PSK
}

Insert the SD card and power on your Raspberry Pi Zero W. You will probably need to find the IP address of the Raspberry Pi via your router.

Raspberry Pi Zero W Configuration

SSH into the Raspberry Pi (username: pi password: raspberry)
Change the default password:
```
sudo passwd pi
```

Upgrade packages and Raspbian to the latest version:

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get dist-upgrade -y
sudo reboot

Setup Bluetooth:

Install the latest bluetooth drivers and firmware:
```
# Install BT drivers
sudo apt-get install pi-bluetooth -y

# Check that BT is working
sudo service bluetooth start
sudo service bluetooth status
```
To avoid running the script using sudo, modify permissions for hcitool.
```
sudo setcap cap_net_raw+ep /usr/bin/hcitool
```
Add SP profile to the bluetooth daemon.
```
sudo nano /etc/systemd/system/dbus-org.bluez.service 
```
Add ' -C' at the end of the 'ExecStart=' line, to start the bluetooth daemon in 'compatibility' mode. Add a new 'ExecStartPost=' immediately after that line, to add the SP Profile. The two lines should look like this:
```
ExecStart=/usr/lib/bluetooth/bluetoothd -C
ExecStartPost=/usr/bin/sdptool add SP
```
Save and reboot
```
sudo reboot
```

Install Mosquitto MQTT Broker client:

# Get repository key
wget http://repo.mosquitto.org/debian/mosquitto-repo.gpg.key

# Add repository
sudo apt-key add mosquitto-repo.gpg.key

# Download lists file 
cd /etc/apt/sources.list.d/
sudo wget http://repo.mosquitto.org/debian/mosquitto-stretch.list

# Update cache and install 
apt-cache search mosquitto
sudo apt-get update
sudo apt-get install libmosquitto-dev mosquitto mosquitto-clients -y

Install Node.js:
```
sudo apt-get install nodejs npm -y
```

Install the ha-bt-proximity script:

# Install git
cd ~
sudo apt-get install git -y

# Clone ha-bt-proximity repository
git clone git://github.com/jxlarrea/ha-bt-proximity

# Enter ha-bt-proximity directory
cd ha-bt-proximity

# Install dependencies
npm install

Configure the ha-bt-proximity script:

nano index.js

Then edit the first few lines with your own values for the MQTT Broker connection and Bluetooth MAC addressed that you want tracked:

// MQTT Broker details

var mqtt_host = "192.168.1.x"; // Your MTTQ broker IP address
var mqtt_port = 1883; // Your MTTQ broker port
var mqtt_user = "mqtt_user"; // Your MQTT broker username
var mqtt_password = "mqtt_pwd"; // Your MQTT broker password
var mqtt_room = "bedroom"; // Location where the Raspberry Pi device will be located


// Tracked BT mac addresses

var owners = [
"00:00:00:00:00:00", // Pixel 2 Bluetooth Mac Address;
"11:11:11:11:11:11" // You can track multiple devices, just keep adding them to the array;
];

NOTE: The mac addresses MUST match those entered previously in the Home Assistant sensor definition.

Setup the script to run as a service

sudo nano /etc/systemd/system/ha-bt-proximity.service

Add the following service definition:

[Unit]
Description=HA BT Proximity Service

[Service]
User=root
ExecStart=/usr/bin/node /home/pi/ha-bt-proximity/index.js
WorkingDirectory=/home/pi/ha-bt-proximity
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Finally, enable and start the newly created service:

sudo systemctl enable ha-bt-proximity.service
sudo systemctl start ha-bt-proximity.service

NOTE: If you need to modify the index.js script in the future, make sure to restart the service using:

sudo systemctl restart ha-bt-proximity.service

You are done!

If all went well, you will now see in Home Assistant the previously added sensor showing the relative proximity of your tracked devices. The sensor proximity value ranges from 0 (closest proximity possible) to -100 (undetectable).

You can use this proximity value to setup Automations based on room presence in your home or even place multiple Raspberry Pi Zero W's around your place to triangulate your position.

For example, you can create a room presence binary sensor in Home Assistant like this:

binary_sensor:
  - platform: template
    sensors:
      xavier_bedroom_presence:
        friendly_name: "Xavier Bedroom Presence"
        device_class: occupancy
        delay_off:
          seconds: 30 
        value_template: >-
          {% if not (states('sensor.xavier_bedroom_proximity') == 'unknown') and (states('sensor.xavier_bedroom_proximity')|int > -10) %}
            true
          {% else %}
            false
          {% endif %}

You will have to figure out the optimal proximity value (-10 above) to consider the device as "present" in the room. This will vary greatly based on the strength of your device's BT signal, room size, line of sight, etc.

Once you setup binary sensors like the above for multiple rooms in your house, you can create a separate sensor to show the location of the tracked device:

sensor:
  - platform: template
    sensors:
      xavier_home_location:
        friendly_name: "Xavier Home Location"
        value_template: >-
          {% if is_state('binary_sensor.xavier_bedroom_presence', 'on') %}
            Bedroom
          {% elif is_state('binary_sensor.xavier_office_presence', 'on') %}
            Office
          {% elif is_state('binary_sensor.xavier_living_room_presence', 'on') %}
            Living Room        
          {% else %}
            Unknown
          {% endif %}

Acknowledgements

Before working on this, I tried to find an already existing room presence detection solution for Home Assistant. I came across 2 in particular that became the inspiration to create this:

@andrewjfreyer's presence: This seemed like the solutions I was looking for. Unfortunately, his approach only works as a binary sensor: If multiple Raspberry Pi Zero W in different rooms around your house detect your tracked device bluetooth signal, they will all mark as if you are present in their respective rooms at the same time. You can check out his repository here.
@seangreen2's Google Home approach: This was the first solution I looked into. It uses Google Home to basically do the same thing I'm doing. Unfortunately, it relied on an unofficial Google Home API that stopped working a long time ago. He updated his solution and now adds Samsung Smartthings to the equation. You can read more about it in his Reddit post.

Hope some of you find this useful!