Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AngelAmoSanchez/TFG-RaspberryPi-BLE/llms.txt

Use this file to discover all available pages before exploring further.

The BLE people-counter agent runs as a Python process on a Raspberry Pi. The install.sh script handles everything from system package installation to creating a systemd service that starts the agent automatically on boot.

​
Hardware and OS requirements

Raspberry Pi

Any Raspberry Pi model with an onboard Bluetooth adapter (Pi 3, Pi 4, Pi 5) or a USB Bluetooth 4.0+ dongle. Raspberry Pi OS (Bookworm or Bullseye) recommended.

Software prerequisites

Python 3.10 or later, bluez Bluetooth stack, git. All installed automatically by install.sh.
The installer grants the Python binary raw network capabilities via setcap so BLE scanning works without running the entire process as root.

​
Installation

Clone the repository to your Raspberry Pi, then run the install script from inside the raspberry-pi/ directory.
1

Clone the repository

git clone https://github.com/AngelAmoSanchez/TFG-RaspberryPi-BLE.git
cd TFG-RaspberryPi-BLE/raspberry-pi
2

Run the installer

The script must be executed from the raspberry-pi/ directory because it resolves paths relative to $(pwd).
bash install.sh
Internally, install.sh performs these operations in order:
# 1. Update package lists and install system dependencies
sudo apt-get update -qq
sudo apt-get install -y \
    python3 \
    python3-pip \
    python3-venv \
    bluetooth \
    bluez \
    git

# 2. Enable and start the Bluetooth service
sudo systemctl enable bluetooth
sudo systemctl start bluetooth

# 3. Create a fresh Python virtual environment
python3 -m venv --copies venv
source venv/bin/activate
pip install --upgrade pip -q
pip install -r requirements.txt -q

# 4. Grant BLE raw-socket capabilities to the venv Python binary
sudo setcap cap_net_raw,cap_net_admin+eip "$PROJECT_ROOT/venv/bin/python3"

# 5. Create working directories
mkdir -p logs data
3

Create your .env configuration file

If no .env file exists the installer copies .env.example automatically:
cp .env.example .env
Open the file and set at minimum DEVICE_ID and your MQTT credentials. See the configuration reference for all available variables.
nano .env
The agent will refuse to start if DEVICE_ID is missing or shorter than three characters. Set it before proceeding.
4

Test the agent manually

Verify that scanning and MQTT publishing work before enabling the service:
./run.sh
The run.sh wrapper activates the virtual environment and launches src/main.py:
#!/bin/bash
cd "$(dirname "$0")"
source venv/bin/activate
exec python3 src/main.py
You should see output similar to:
2024-03-01 12:00:00 - __main__ - INFO - OK - MQTT conectado exitosamente
2024-03-01 12:00:00 - __main__ - INFO - Ciclo de Escaneo #1 ...
5

Enable the systemd service

The installer already wrote the unit file to /etc/systemd/system/ble-scanner.service. Enable and start it:
sudo systemctl enable ble-scanner
sudo systemctl start ble-scanner

​
The systemd service unit

The installer writes the following unit file to /etc/systemd/system/ble-scanner.service: 
[Unit]
Description=Bluetooth People Counter Service
Documentation=https://github.com/AngelAmoSanchez/TFG-RaspberryPi-BLE
After=network.target bluetooth.target
Wants=bluetooth.target
BindsTo=bluetooth.target

[Service]
Type=exec
User=pi
WorkingDirectory=/home/pi/TFG-RaspberryPi-BLE/raspberry-pi

ExecStartPre=/bin/sleep 5
ExecStart=/home/pi/TFG-RaspberryPi-BLE/raspberry-pi/venv/bin/python3 src/main.py

Restart=always
RestartSec=15
StartLimitBurst=10
StartLimitInterval=200

Environment="PYTHONUNBUFFERED=1"

TimeoutStartSec=30
TimeoutStopSec=10

[Install]
WantedBy=multi-user.target
Key points:
  • BindsTo=bluetooth.target — the service stops automatically if the Bluetooth adapter disappears.
  • ExecStartPre=/bin/sleep 5 — a 5-second delay lets the BT stack settle after boot.
  • Restart=always with RestartSec=15 — the agent restarts within 15 seconds after any crash.
  • StartLimitBurst=10 / StartLimitInterval=200 — systemd stops retrying after 10 failures in 200 seconds to prevent a restart storm.

​
Managing the service

sudo systemctl status ble-scanner

sudo journalctl -u ble-scanner -f
To see logs from the current boot only:
sudo journalctl -u ble-scanner -b

sudo systemctl stop ble-scanner
sudo systemctl restart ble-scanner

sudo systemctl disable ble-scanner
Rotating log files are also written to ./logs/iot-agent.log (up to three 5 MB files). Use tail -f logs/iot-agent.log for a quick look without journalctl.

Build docs developers (and LLMs) love

Get started for freeTalk to us