bthome-logger Tool

The bthome-logger is a Python command-line tool for testing and debugging BThome V2 devices. It scans for BLE advertisements and displays decoded sensor data in real-time.

Overview

The tool helps you:

Verify your BThome V2 sensor is advertising correctly
Debug sensor data and advertisements
Monitor multiple sensors simultaneously
Check signal strength (RSSI)
View raw advertisement data

Installation

Recommended: uv

The fastest and most reliable installation method:

uv tool install bthome-logger

The tool is then globally available:

bthome-logger

Alternative: pipx

For isolated tool installation:

pipx install bthome-logger

Alternative: pip

System-wide installation:

pip install bthome-logger

From Source

For development or latest changes:

git clone https://github.com/the78mole/bthomev2.git
cd bthomev2/tools
pip install -e .

Usage

Basic Usage

Start scanning with default filter:

bthome-logger

This filters for devices with “MAKE” in their name (default).

Filter by Device Name

Show only specific devices:

# Filter by partial name
bthome-logger -f "ESP32"

# Filter for your sensor
bthome-logger -f "My-Sensor"

# Filter for multiple devices (any match)
bthome-logger -f "Living-Room"

Verbose Mode

Show all BLE advertisements, not just BThome devices:

bthome-logger -v

# Or
bthome-logger --verbose

Version Information

Check installed version:

bthome-logger --version

Help

Show all options:

bthome-logger --help

Command-Line Options

Option	Short	Description
`--filter <name>`	`-f`	Filter devices by name (partial match)
`--verbose`	`-v`	Show all BLE advertisements
`--version`		Show version and exit
`--help`	`-h`	Show help message and exit

Output Format

The tool displays advertisements in this format:

Advertisement Display

----------------------------------------------------------------------
[14:32:45.123] 📱 ESP32-Climate (E4:65:B8:12:34:56)
  RSSI: -45 dBm
  Temperature: 22.5 °C
  Humidity: 65.0 %
  Battery: 95 %

RSSI Color Coding

Signal strength is color-coded:

Green (> -60 dBm): Excellent signal
Yellow (-60 to -75 dBm): Good signal
Red (< -75 dBm): Weak signal

Supported Sensor Types

The tool automatically decodes all BThome V2 sensor types:

Environmental Sensors

Temperature (°C)
Humidity (%)
Pressure (hPa)
Dew Point (°C)
Moisture (%)

Air Quality

CO2 (ppm)
TVOC (ppb)
PM2.5 (µg/m³)
PM10 (µg/m³)

Light & Power

Illuminance (lux)
Battery (%)
Voltage (V)
Power (W)
Energy (kWh)

Binary Sensors

All binary sensors are decoded with appropriate labels:

Motion, Occupancy, Presence
Door, Window, Opening
Smoke, Gas, CO
And many more (see Supported Sensors)

Events

Button events (press, double press, triple press, long press)
Dimmer events (rotate left/right)

Practical Use Cases

Development Testing

Test your sensor during development:

# Terminal 1: Monitor serial output
pio device monitor

# Terminal 2: Watch BLE advertisements
bthome-logger -f "My-Sensor"

Verify Sensor Updates

Check that measurements update correctly:

bthome-logger -f "Climate-Sensor"

# Watch for value changes every 60 seconds
# Temperature: 22.5 °C → 22.7 °C → 23.0 °C

Signal Strength Testing

Test range and signal quality:

bthome-logger -f "Test-Sensor"

# Move device away and watch RSSI:
# RSSI: -45 dBm (1m)
# RSSI: -60 dBm (5m)
# RSSI: -75 dBm (10m)

Multiple Sensor Monitoring

Monitor several sensors at once:

# Show all your sensors
bthome-logger -f "Home-"

# Will show:
# Home-Living-Room
# Home-Bedroom
# Home-Kitchen

Debugging

Find issues with advertisements:

# Use verbose mode to see raw data
bthome-logger -v -f "Problem-Sensor"

# Check:
# - Is device advertising?
# - Is BThome company ID present (0xFCD2)?
# - Are sensor values reasonable?

Examples

Example 1: Basic Temperature Sensor

$ bthome-logger -f "ESP32-Basic"

Output:

[10:30:15] ESP32-Basic (E4:65:B8:XX:XX:XX) | RSSI: -45 dBm
  Temperature: 22.3 °C
  Humidity: 64.5 %
  Battery: 100 %

[10:30:25] ESP32-Basic (E4:65:B8:XX:XX:XX) | RSSI: -46 dBm
  Temperature: 22.4 °C
  Humidity: 64.3 %
  Battery: 100 %

Example 2: Button Events

$ bthome-logger -f "Button"

Output:

[10:31:22] ESP32-Button (E4:65:B8:XX:XX:XX) | RSSI: -42 dBm
  Button: Press
  Battery: 100 %

[10:31:30] ESP32-Button (E4:65:B8:XX:XX:XX) | RSSI: -42 dBm
  Button: Long Press
  Battery: 100 %

Example 3: Multiple Sensors

$ bthome-logger -f "Multi-Sensor"

Output:

[10:32:45] Multi-Sensor (E4:65:B8:XX:XX:XX) | RSSI: -48 dBm
  Temperature: 24.2 °C
  Humidity: 58.3 %
  Pressure: 1015.3 hPa
  Illuminance: 623.5 lux
  CO2: 456 ppm
  Battery: 100 %

Example 4: Verbose Mode

$ bthome-logger -v

Output shows ALL BLE advertisements:

[10:33:10] Random-Device (AA:BB:CC:DD:EE:FF) | RSSI: -55 dBm
  (No BThome data)

[10:33:11] ESP32-Basic (E4:65:B8:XX:XX:XX) | RSSI: -45 dBm
  Temperature: 22.5 °C
  Battery: 100 %

[10:33:12] iPhone (11:22:33:44:55:66) | RSSI: -60 dBm
  (No BThome data)

Troubleshooting

Tool doesn’t start

Problem: Command not found

Solution:

# Reinstall
uv tool install bthome-logger --force

# Or check installation
uv tool list

No devices found

Problem: Scanner starts but no devices appear

Check:

Is Bluetooth enabled?

# Linux
bluetoothctl power on

# macOS
# Check System Settings > Bluetooth

Is device actually advertising?

Check serial monitor for “Advertising started!”
Is device in range?

Move device closer (<5m for testing)
Try verbose mode:
```
bthome-logger -v
```

Wrong device name filter

Problem: Your device doesn’t appear but others do

Solution:

# Check exact device name in your code
# Then use matching filter
bthome-logger -f "Exact-Name"

Permission errors (Linux)

Problem: Permission denied when scanning

Solution:

# Add user to bluetooth group
sudo usermod -a -G bluetooth $USER

# Restart session or reboot

Values not updating

Problem: Same values shown repeatedly

Check:

Device is calling updateAdvertising()
Update interval is reasonable (30+ seconds)
Device hasn’t crashed (check serial monitor)

Incorrect values displayed

Problem: Values don’t match expected

Check:

Units in your code match sensor documentation
Resolution is correct (e.g., temperature in °C not °F)
Data type is correct (float vs int)

Version Compatibility

The tool and library share version numbers:

Tool Version	Library Version	Notes
0.2.x	0.2.x	Current, fully compatible
0.1.x	0.1.x	Initial release

Recommendation: Always use matching versions.

# Check versions
bthome-logger --version
# Compare with library version in platformio.ini

System Requirements

Operating Systems

Linux: Ubuntu 20.04+, Debian 11+, other distributions with BlueZ
macOS: 10.15+ (Catalina or newer)
Windows: 10+ with Bluetooth LE support

Python

Python 3.8 or higher
pip or uv package manager

Hardware

Bluetooth LE 4.0+ adapter (built-in or USB)
For USB adapters: Must support Bluetooth LE

Dependencies

Automatically installed:

bleak - Bluetooth LE library
colorama - Terminal colors (Windows)

Advanced Usage

Integration with Scripts

Use in shell scripts:

#!/bin/bash
# Check if sensor is alive
timeout 30 bthome-logger -f "My-Sensor" | grep -q "Temperature"
if [ $? -eq 0 ]; then
  echo "Sensor is alive"
else
  echo "Sensor not responding"
fi

Continuous Monitoring

Run as a service or in background:

# With logging
bthome-logger -f "Production-Sensor" >> sensor.log 2>&1

# In screen session
screen -S bthome
bthome-logger -f "My-Sensor"
# Ctrl+A, D to detach

bthome-logger Tool

Overview

Installation

Recommended: uv

Alternative: pipx

Alternative: pip

From Source

Usage

Basic Usage

Filter by Device Name

Verbose Mode

Version Information

Help

Command-Line Options

Output Format

Header

Advertisement Display

RSSI Color Coding

Supported Sensor Types

Environmental Sensors

Air Quality

Light & Power

Binary Sensors

Events

Practical Use Cases

Development Testing

Verify Sensor Updates

Signal Strength Testing

Multiple Sensor Monitoring

Debugging

Examples

Example 1: Basic Temperature Sensor

Example 2: Button Events

Example 3: Multiple Sensors

Example 4: Verbose Mode

Troubleshooting

Tool doesn’t start

No devices found

Wrong device name filter

Permission errors (Linux)

Values not updating

Incorrect values displayed

Version Compatibility

System Requirements

Operating Systems

Python

Hardware

Dependencies

Advanced Usage

Integration with Scripts

Continuous Monitoring

See Also