BlueTracker Installation Guide

Note

Tested on Debian and Raspbian with Raspberry Zero W Rev 1.1 and Zero 2.

While BlueTracker should work on other Linux distributions with BlueZ installed, it has only been tested on the specified configurations.

Prerequisites

Before you begin, ensure you have the following:

• Hardware:

  • A Linux system with Bluetooth.

  • BlueZ must be installed, including the hciconfig and hcitool commands.

• Software:

  • Home Assistant with MQTT Add-on and MQTT Integration installed.

Installation on Home Assistant

Ensure following add-on and integration are installed on Home Assistant:

• MQTT Add-on: Broker to send/receive data from MQTT clients.

• MQTT Integration: Receive updates from the MQTT broker add-on.

Installation on Linux

1. Verify BlueZ Installation:

   Before proceeding, make sure that BlueZ is correctly installed on your system:

   dpkg -l | grep bluez
   

2. Verify Bluetooth is running:

   hciconfig
   

   The output should look similar to this, indicating that your Bluetooth adapter is recognized and enabled:

   hci0:     Type: Primary  Bus: UART
      BD Address: XX:XX:XX:XX:XX:XX  ACL MTU: 1021:8  SCO MTU: 64:1
      UP RUNNING
      RX bytes:2911 acl:0 sco:0 events:217 errors:0
      TX bytes:33155 acl:0 sco:0 commands:217 errors:0
   

3. Create a Virtual Environment:

   cd && mkdir bluetracker && cd bluetracker
   python -m venv .env
   source .env/bin/activate
   

4. Install BlueTracker from PyPi:

   pip install --upgrade pip setuptools bluetracker-hass-mqtt
   

Configuration

1. Create Configuration File:

   Run BlueTracker once to generate the configuration file (bluetracker_config.toml):

   bluetracker
   

2. Edit Configuration:

   • Open the config file using a text editor:

     nano bluetracker_config.toml
     

   • For more information, please refer to the complete BlueTracker configuration documentation.

Running BlueTracker

1. Start BlueTracker:

   bluetracker
   

2. Check Home Assistant:

   Once BlueTracker is running, bluetooth devices with their state (home or not_home) and attributes are automatically added to Home Assistant using the MQTT Discovery protocol.

   For more detailed information on the entities created and their attributes, refer to Entities Explained in Detail.

   Find them under the MQTT devices section in Home Assistant:

   

Running on System Startup

To guarantee that BlueTracker automatically launches every time your system boots up and continues to run without interruption, you can configure a systemd service (responsible for initiating the program at boot time) and a cron job (tasked with regularly verifying that the program remains active).

1. To run BlueTracker on system startup, create a systemd service.

   sudo nano /etc/systemd/system/bluetracker.service
   

   Note

   Replace <your_username> with the actual user

   [Unit]
   Description=BlueTracker
   After=network.target
   
   [Service]
   Type=idle
   User=<your_username>
   WorkingDirectory=/home/<your_username>/bluetracker/
   Environment="VIRTUAL_ENV=/home/<your_username>/bluetracker/.env"
   Environment="PATH=$VIRTUAL_ENV/bin:$PATH"
   ExecStart=/home/<your_username>/bluetracker/.env/bin/python .env/bin/bluetracker
   Restart=always
   KillSignal=SIGINT
   
   [Install]
   WantedBy=multi-user.target
   

2. Load the service:

   sudo systemctl daemon-reload
   sudo systemctl enable bluetracker --now
   

3. Check the status:

   sudo systemctl status bluetracker
   

4. Check the output:

   journalctl -u bluetracker -n 10
   

   journalctl -u bluetracker -f
   

5. Schedule with Cron:

   • Open your crontab file:

     sudo crontab -u root -e
     

   • Add the following line to start the service every 5 minutes, if it is not running:

     */5 * * * * pgrep -x bluetracker > /dev/null || /usr/sbin/service bluetracker start 2>&1