MuTrack BLE Beacon Scanner

A companion service for MuTrack that continuously scans for iBeacon advertisements and automatically logs attendance to the backend.

Features

• Continuous BLE scanning for iBeacon devices
• Automatic attendance logging for active meetings
• Unpaired beacon detection for easy member assignment
• Cross-platform support (Raspberry Pi & macOS)
• Systemd service for always-on deployment
• Configurable scan intervals and presence TTL

Requirements

• Python 3.9+
• Bluetooth LE capable device
• Raspberry Pi (recommended) or macOS

Quick Start

1. Clone the repository:

   git clone https://github.com/pmazumder3927/mutrack-scanner.git
   cd mutrack-scanner

2. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. Configure the scanner:

   cp config.example.yaml config.yaml
   # Edit config.yaml with your API key from MuTrack Admin > Scanners

4. Run the scanner:

   python -m mutrack_scanner -c config.yaml -v

Installation

Raspberry Pi (Production)

1. Clone to your Pi:

   git clone https://github.com/pmazumder3927/mutrack-scanner.git
   cd mutrack-scanner

2. Set up the environment:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   cp config.example.yaml config.yaml
   nano config.yaml  # Add your API key

3. Test the scanner:

   python -m mutrack_scanner -c config.yaml -v

4. Install as a systemd service:

   sudo cp systemd/mutrack-scanner.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable mutrack-scanner
   sudo systemctl start mutrack-scanner

5. Check status:

   sudo systemctl status mutrack-scanner
   sudo journalctl -u mutrack-scanner -f

macOS (Development)

git clone https://github.com/pmazumder3927/mutrack-scanner.git
cd mutrack-scanner
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp config.example.yaml config.yaml
# Edit config.yaml with your API key
python -m mutrack_scanner -c config.yaml -v

Configuration

Create a config.yaml file (see config.example.yaml):

api_url: https://your-app.convex.site/api/scanner
api_key: msk_your_api_key_here

scan_interval: 1.0      # Seconds between BLE scan cycles
upload_interval: 10.0   # Seconds between batch uploads
presence_ttl: 30.0      # Seconds before beacon is considered "gone"
log_level: INFO

Setting	Default	Description
api_url	(required)	Your Convex deployment URL + /api/scanner
api_key	(required)	Scanner API key from MuTrack admin
scan_interval	1.0	Seconds between BLE scan cycles
upload_interval	10.0	Seconds between batch uploads
presence_ttl	30.0	Seconds before beacon is considered "gone"
log_level	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)

Environment Variables

Override config values with environment variables:

• MUTRACK_API_URL - API URL
• MUTRACK_API_KEY - API key

Getting an API Key

1. Log into MuTrack as an admin
2. Go to Admin > Scanners
3. Click "Register Scanner"
4. Enter a name and optional location
5. Copy the API key (shown only once)

How It Works

1. The scanner continuously listens for BLE advertisements
2. When an iBeacon is detected, it's tracked in a presence buffer
3. Every upload_interval seconds, present beacons are sent to the server
4. The server matches beacons to members and logs attendance for active meetings
5. Unknown beacons are tracked for admins to pair to members later
6. If a beacon isn't seen for presence_ttl seconds, it's considered departed

Troubleshooting

No beacons detected

1. Check Bluetooth is enabled:

   # Raspberry Pi
   sudo hciconfig hci0 up
   bluetoothctl power on

2. Verify beacon is broadcasting (use a phone app like "nRF Connect")

3. Run with verbose logging:

   python -m mutrack_scanner -c config.yaml -v

Permission denied (Linux)

On Linux, you may need to run as root or add capabilities:

sudo setcap 'cap_net_raw,cap_net_admin+eip' $(which python3)

API errors

1. Verify your API key is correct
2. Check the scanner is enabled in MuTrack admin
3. Ensure your network can reach the Convex URL

SSL certificate errors (macOS)

The scanner uses certifi for SSL certificates. If issues persist:

pip install --upgrade certifi

Project Structure

mutrack-scanner/
├── mutrack_scanner/
│   ├── __init__.py       # Package version
│   ├── __main__.py       # Entry point
│   ├── config.py         # YAML config loader
│   ├── scanner.py        # BLE scanning with bleak
│   ├── ibeacon.py        # iBeacon advertisement parser
│   ├── presence.py       # Presence tracking with TTL
│   └── api.py            # HTTP client for Convex
├── systemd/
│   └── mutrack-scanner.service
├── config.example.yaml
├── requirements.txt
└── README.md

License

MIT