Installation

Prerequisites

• ESPHome 2024.1.0 or later
• ESP32 or nRF52840 board
• Home Assistant with BTHome integration (for receiving data)

Installation Methods

Git (Recommended)

Add the component directly from GitHub in your ESPHome configuration:

external_components:
  - source:
      type: git
      url: https://github.com/dz0ny/esphome-bthome
      ref: main
    components: [bthome]

Local

Clone the repository and reference it locally:

git clone https://github.com/dz0ny/esphome-bthome.git

Then in your ESPHome configuration:

external_components:
  - source:
      type: local
      path: /path/to/esphome-bthome/components
    components: [bthome]

Verify Installation

After adding the external component, ESPHome will automatically download and compile the BTHome component when you build your configuration.

To verify the installation is working:

1. Create a minimal configuration (see Quick Start)
2. Compile the configuration: esphome compile your_config.yaml
3. Check for any errors in the output

Home Assistant Setup

To receive BTHome broadcasts in Home Assistant:

1. Go to Settings → Devices & Services
2. Click Add Integration
3. Search for BTHome
4. Follow the setup wizard

Home Assistant will automatically discover BTHome devices broadcasting nearby.

Tip

Make sure your Home Assistant host has Bluetooth capability, either built-in or via a USB Bluetooth adapter.

Next Steps

• Quick Start - Create your first BTHome sensor
• Basic Setup - Learn about configuration options