BThomeV2 - BLE Sensor Library & Testing Tool

BThomeV2 is a comprehensive solution for developing BLE sensors following the BThome V2 standard. The project consists of two tightly integrated components:

BThomeV2 Arduino Library - PlatformIO/Arduino library for ESP32 and nRF52
bthome-logger - Python-based testing and monitoring tool

Warning

nRF52 Implementation Currently Broken

The nRF52 platform is currently non-functional due to runtime issues with Bluefruit initialization. ESP32 works fully.

Status: ✅ ESP32 fully functional | ❌ nRF52 broken (runtime hang)

Overview

The BThomeV2 library provides a unified interface for BLE advertising using the BThome V2 format, designed for efficient transmission of sensor data over Bluetooth Low Energy. The library abstracts platform-specific BLE implementations, making it easy to develop BThome V2-compatible devices on different hardware platforms.

The bthome-logger tool complements the library perfectly by decoding received BLE advertisements and displaying them in human-readable format. Both components are versioned synchronously to ensure compatibility.

Main Features

Arduino Library

✅ BThome V2 protocol support
✅ Multiple sensor types (temperature, humidity, pressure, CO2, etc.)
✅ Binary sensor support (motion, door, window, etc.)
✅ Event support (button actions)
✅ Platform abstraction (ESP32 and nRF52)
✅ Easy-to-use API
✅ Encryption support (framework in place)
✅ Low-power BLE advertising

Python Testing Tool

✅ BLE advertisement monitoring
✅ BThome V2 decoding
✅ Device filtering
✅ RSSI display
✅ Human-readable output
✅ Live monitoring

Supported Platforms

ESP32 ✅ - Uses ArduinoBLE library (fully tested and functional)
nRF52 ❌ - Uses Adafruit Bluefruit library (currently broken - runtime hang)

Quick Start

Library Installation:

[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps =
    the78mole/BThomeV2

Testing Tool Installation:

uv tool install bthome-logger

Simple Example:

#include <Arduino.h>
#include <BThomeV2.h>

BThomeV2Device bthome;

void setup() {
  bthome.begin("My-BThome-Device");
  bthome.addTemperature(22.5);
  bthome.addHumidity(65.0);
  bthome.startAdvertising();
}

void loop() {
  delay(60000);
  bthome.clearMeasurements();
  bthome.addTemperature(23.0);
  bthome.updateAdvertising();
}

Testing:

bthome-logger -f "My-BThome-Device"

Documentation

Getting Started

Additional Information