Содержание
Основа
Что такое BTHome и зачем он нужен
BTHome — открытый формат передачи показаний датчиков и событий через Bluetooth Low Energy (BLE). Устройство отправляет небольшие радиосообщения, а Home Assistant принимает их через локальный Bluetooth-адаптер либо ESPHome Bluetooth Proxy. Для передачи температуры или влажности датчику не нужно создавать постоянное соединение с сервером.
BLE-датчик Передаёт пакет
→ Bluetooth-сканер USB или ESPHome Proxy
→ Home Assistant BTHome integration
→ Dashboard и автоматизации Измерения и события
BTHome описывает формат данных, а не конкретный бренд и не радиосеть типа Zigbee mesh. Он не гарантирует, что любой BLE-термометр или смарт-замок совместим с Home Assistant. Важны модель, версия прошивки и фактически используемый протокол.
Принципиальное отличие: BLE advertisement — радиопередача данных; Bluetooth Proxy — удалённый приёмник этих данных; Home Assistant BTHome — интеграция, которая понимает содержимое пакета. Это три разных уровня.
Радиопротокол
BLE advertisements против активного GATT-соединения
В BTHome сенсор может периодически просыпаться, измерять температуру, отправлять один или несколько коротких пакетов и возвращаться к экономичному режиму. Приёмник лишь слушает эфир. Если один пакет потерялся, следующий может быть принят через несколько секунд или минут: период зависит от устройства.
Таким образом, десяток BTHome-термометров, передающих только advertising, обычно не занимает десять GATT-слотов Bluetooth Proxy. Не путайте active scanning со включением активных GATT-соединений в настройках прокси.
Стандарт
BTHome v2: чем отличается от старого v1
Вторая версия BTHome появилась в ноябре 2022 года. Для новых проектов ориентируйтесь на BTHome v2 . В радиопакетах v2 используется сервисный идентификатор 0xFCD2 (в последовательности байтов service data — D2 FC). Далее идут Device Information и закодированные измерения.
Устаревший v1 может встречаться в старых датчиках. Не следует копировать таблицы object IDs и байты заголовка из инструкции для v1 в проект v2. Формат должен совпадать на стороне передатчика и получателя.
UUID 0xFCD2Сервис BTHome v2
Device info 0x40Пример: v2, без шифрования
Payload object ID + valueТип данных определяет декодирование
Как работают байты
Разбираем пакет температуры и влажности BTHome v2
В официальной спецификации есть пример service data D2FC4002C40903BF13. Расшифровка показывает, почему нельзя просто читать числа по позиции в пакете.
У разных измерений отличается размер, знаковость и масштаб. Одна температура может занимать два байта, уровень батареи — один. Разрешение значений в стандарте не равно заявленной точности измерительного элемента датчика.
Измерения
Что BTHome умеет передавать кроме температуры
В спецификации предусмотрены показания батареи, влажности, освещённости, напряжения, содержания CO₂ и ряд двоичных состояний. Это возможности стандарта, а не обязательный набор сенсоров любого устройства.
Если устройство поддерживает только температуру и влажность, ожидайте две соответствующие entities плюс, возможно, датчик уровня батареи. Нельзя добавить отсутствующее измерение одним YAML-параметром.
Выбор протокола
BTHome, Zigbee или Wi-Fi: чем отличаются
Для нескольких BLE-термометров BTHome может оказаться удобным выбором. Для большого дома с множеством датчиков Zigbee может лучше масштабироваться за счёт mesh — но решение зависит от расположения помещений и оборудования. Подробное сравнение: ZHA или Zigbee2MQTT .
Совместимость
Что проверить перед покупкой BLE-датчика
1 Уточните точную модель, аппаратную ревизию и установленную прошивку, а не только слова Bluetooth 5.0.
2 Найдите явное подтверждение поддержки BTHome v2 либо проверенный способ установки совместимой прошивки.
3 Проверьте, какие именно показатели передаёт модель: температуру, влажность, напряжение, батарею, событие.
4 Выясните, включено ли шифрование и где владелец получает bindkey.
5 Оцените расположение BLE-сканера и радиопокрытие у места установки.
6 Для сигналов протечки, дыма и других опасных ситуаций предусмотрите отдельную автономную защиту.
Многие Xiaomi/Mijia-термометры способны работать с несколькими форматами advertising в зависимости от прошивки: MiBeacon, ATC и BTHome не взаимозаменяемы. Не считайте, что любой термометр Xiaomi передаёт BTHome «из коробки».
Инфраструктура
Что потребуется для BTHome в Home Assistant
Минимальная конфигурация включает работающий Home Assistant, интеграцию Bluetooth , доступный BLE-сканер и совместимый BTHome-датчик. Декодирование выполняет встроенная интеграция BTHome . Для зашифрованных устройств потребуется правильный ключ bindkey.
В качестве приёмника можно использовать USB Bluetooth-адаптер непосредственно у сервера или ESPHome Bluetooth Proxy, подключённый по Wi-Fi/Ethernet. При работе в Docker или виртуальной машине сетевой прокси может быть удобнее передачи USB-адаптера в гостевую ОС.
Сам BTHome-датчик не нужно добавлять как отдельное устройство ESPHome. Bluetooth Proxy относится к интеграции ESPHome, а показания датчика появляются благодаря интеграции BTHome. Подробнее о структуре: devices, entities и helpers Home Assistant .
Пошаговая настройка
Как подключить готовый BTHome-датчик к Home Assistant
1 Проверьте Bluetooth в Settings → Devices & services . Сканер должен быть доступен Home Assistant.
2 Разместите включённый датчик рядом с исправным сканером, дождитесь рекламных пакетов.
3 Совместимые устройства обычно обнаруживаются автоматически. При необходимости выберите Add integration → BTHome .
4 При запросе ключа введите bindkey именно этого устройства: 32 шестнадцатеричных символа.
5 После добавления откройте страницу BTHome-устройства и проверьте реальные entities.
6 Проверьте несколько последовательных измерений и работу в месте постоянной установки.
Для обычного незашифрованного BTHome advertising не требуется классическое Bluetooth pairing. Если предлагается ввод PIN, проверьте, не пытаетесь ли вы подключать устройство через другую интеграцию с иным протоколом.
Расширение приёма
ESPHome Bluetooth Proxy для удалённых BTHome-датчиков
Когда сервер расположен в другой комнате, ESPHome Bluetooth Proxy принимает BLE advertisements рядом с датчиком и отправляет их в Home Assistant через локальную IP-сеть. Несколько прокси можно разместить по квартире или на разных этажах дома.
Для датчика BTHome, который вещает только advertising, не требуется активное GATT-соединение. Важнее качество радиопокрытия, стабильность питания прокси и связь с Home Assistant. Не устанавливайте приёмник внутри закрытого металлического электрощита: он экранирует BLE-сигналы.
Если у ESPHome Proxy нет доступа к серверу по сети, сначала диагностируйте Wi-Fi/Ethernet, Native API и правила firewall, а уже затем проверяйте ключи датчиков. Дополнительный материал: ESPHome без пайки: локальная автоматика .
Шифрование
Что такое bindkey BTHome и как выглядит правильный ключ
Для BTHome v2 с шифрованием используется общий 16-байтный ключ , записанный в виде 32 символов шестнадцатеричной системы (цифры 0–9 и буквы a–f). Его называют bindkey . Получатель должен знать тот же ключ, что использует передатчик.
Корректная форма 00112233445566778899aabbccddeeffУчебный пример, не настоящий ключ
Некорректная форма 123456Недостаточная длина
Bindkey не является PIN-кодом pairing, Wi-Fi-паролем или ключом ESPHome Native API. Если BTHome-датчик отправляет незашифрованные пакеты, bindkey вообще не нужен. Когда неверный ключ введён для зашифрованного устройства, обнаружение может проходить, но декодирование измерений будет завершаться ошибкой.
Настройка ключа
Где взять bindkey и что делать, если ключ потерян
Один универсальный bindkey для всех датчиков не существует. Способ получения зависит от прошивки и производителя:
Совместимая фирменная прошивка может показывать или предоставлять ключ при включении encryption. Для поддерживаемых датчиков с ATC/PVVX его можно задать или получить через предусмотренный конфигуратор. У некоторых устройств шифрование и ключи связаны с собственной системой производителя; их нельзя механически приравнивать к BTHome. При утрате ключа может потребоваться поддерживаемая устройством процедура сброса или повторной настройки, а иногда повторная прошивка. Сначала проверьте возможность восстановления, чтобы не потерять работающее устройство.
Не публикуйте ключ в комментариях, скриншотах, журналах и общедоступных репозиториях. При замене ключа соответствующую настройку нужно обновить и на стороне Home Assistant.
Риски
AES-CCM: что защищает шифрование BTHome, а чего не гарантирует
BTHome поддерживает AES-CCM: полезные данные зашифрованного пакета можно прочитать, только зная правильный bindkey. Но авторы спецификации отдельно предупреждают: шифрование не является само по себе полной защитой от подмены и повторного воспроизведения событий .
Получатель должен корректно обрабатывать счётчик сообщений и не считать любые незашифрованные объявления с тем же MAC-адресом автоматически доверенными. Без нужных проверок атакующий в зоне приёма может попытаться подменить сведения или повторить ранее принятый пакет.
Не используйте BTHome-событие как единственный фактор открытия двери, отключения охраны, включения опасного оборудования или другой критичной команды. Такие действия требуют независимых средств подтверждения и безопасной логики исполнительного устройства. Это относится и к зашифрованным датчикам.
Для локального мониторинга температуры и влажности BTHome остаётся полезным при разумной оценке точности, задержек и риска пропущенных пакетов.
Батареи и эфир
Packet ID, интервал передачи и потеря рекламных сообщений
BTHome предусматривает необязательный packet ID для фильтрации повторов. Сенсор может несколько раз отправлять одинаковые сообщения для повышения вероятности приёма. Приёмник может распознавать их как одну запись, если packet ID не изменился.
Интервал передачи устанавливается моделью и прошивкой. Для температуры это могут быть десятки секунд, для событий кнопки пакеты возникают по факту нажатия. Частое broadcasting повышает вероятность быстрой доставки, но обычно увеличивает энергопотребление устройства.
Если Home Assistant несколько раз не получил сообщение, это ещё не означает физическую неисправность. Но для ответственной автоматизации важно уметь отличить свежее измерение от последнего известного значения.
Практическая совместимость
Xiaomi/Mijia, ATC и PVVX: почему важна именно прошивка
У некоторых термометров Xiaomi/Mijia с альтернативной прошивкой PVVX можно выбрать advertising-формат BTHome v2 . В других версиях устройства передают MiBeacon либо ATC. Внешне похожие модели могут различаться аппаратной ревизией, микроконтроллером и возможностью перепрошивки.
Перед изменением firmware проверьте точную модель, совместимость загрузчика, способ восстановления, поддержку датчиков и сохранность текущих настроек. Нельзя переносить инструкцию по прошивке от одного Xiaomi-термометра на другую модель только из-за одинакового корпуса.
В ESPHome есть официальная платформа bthome_mithermometer для приёма BTHome v2 от совместимых термометров с PVVX. Это не то же самое, что компонент передачи BTHome-пакетов.
YAML
ESPHome: пример приёма BTHome v2 от совместимого MiThermometer
В следующем фрагменте предполагается, что устройство уже работает под ESPHome и имеет BLE tracker. Платформа создаёт сенсоры температуры, влажности и батареи для совместимой Xiaomi/Mijia с PVVX и форматом BTHome v2.
Фрагмент ESPHome, не полный конфиг прошивки YAML
esp32_ble_tracker:
sensor:
- platform: bthome_mithermometer
mac_address: "AA:BB:CC:DD:EE:FF"
bindkey: "00112233445566778899aabbccddeeff"
temperature:
name: "BLE Temperature"
humidity:
name: "BLE Humidity"
battery_level:
name: "BLE Battery"
MAC и bindkey в примере демонстрационные. При незашифрованной передаче удалите строку bindkey. Это специализированная платформа ESPHome, а не обязательная настройка обычного Home Assistant Bluetooth Proxy. Если датчик уже подключён через штатную BTHome integration, второй путь может создать ненужные дубли entities.
Полная конфигурация ESPHome зависит от платы, framework, питания, API и выбранного BLE tracker. Не вставляйте фрагмент поверх рабочего устройства с исполнительными GPIO, не проверив назначения существующих компонентов.
Самодельные датчики
Можно ли сделать собственный BTHome-датчик на ESP32
Да. Открытая спецификация позволяет создать прошивку, которая формирует BTHome v2 advertising и отправляет измерения или события. Но следует отличать передатчик , формирующий байты BTHome, от ESPHome Bluetooth Proxy и платформы bthome_mithermometer, которые предназначены для приёма.
Существуют сторонние external components ESPHome для BTHome transmission. Они не являются автоматически встроенной официально поддерживаемой функцией выбранной версии ESPHome. Перед использованием оценивайте исходный код, состояние репозитория, совместимость с вашим framework и последствия обновлений.
Для самодельного устройства необходимо соблюдать правила кодирования object IDs, порядка измерений, байта версии, идентификатора устройства и, при шифровании, AES-CCM. Нельзя просто отправить произвольную строку текста по Bluetooth и ожидать появления BTHome-сенсора в Home Assistant.
Практический сценарий
Автоматизация: предупредить о высокой температуре по BTHome
После подключения BTHome-сенсора Home Assistant создаёт entity, например sensor.ble_temperature. Ниже показано уведомление в интерфейсе при устойчивом превышении 30 °C. Замените примерный entity ID на реальный и выберите порог исходя из своей задачи.
Пример автоматизации Home Assistant 2026 YAML
alias: "BLE: высокая температура"
triggers:
- trigger: numeric_state
entity_id: sensor.ble_temperature
above: 30
for: "00:03:00"
conditions:
- condition: template
value_template: "{{ has_value('sensor.ble_temperature') }}"
actions:
- action: persistent_notification.create
data:
title: "Проверьте температуру"
message: >-
BLE-датчик показывает
{{ states('sensor.ble_temperature') }} °C.
mode: single
Триггер numeric_state реагирует на переход через границу. Он не будет заново срабатывать на каждом новом BLE-пакете, пока измерение остаётся выше 30 °C. Обычное ожидание for не переживает перезапуск Home Assistant или перезагрузку автоматизаций.
Это информационное уведомление, а не аварийная автоматика. Защита от перегрева, пожара, утечки газа или критичного отказа должна иметь независимый исполнительный механизм, рассчитанный на соответствующий риск.
Достоверность данных
Почему датчик показывает старую температуру и как распознать потерю связи
Потеря BLE-пакета и изменение реальной температуры — разные события. Некоторые интеграции удерживают последнее известное значение, даже если устройство временно перестало передавать данные. Другие могут переводить entity в unavailable после собственного таймаута.
Проверяйте поведение конкретной интеграции и версии прошивки , а не считайте любую последнюю цифру свежей. При необходимости добавляйте отдельный контроль поступления реальных обновлений на уровне приёмника. Нельзя обобщать таймаут одного BTHome-датчика на все BLE-устройства.
В автоматизациях различайте числовое значение, unknown и unavailable. Нельзя механически заменять исчезнувшую температуру нулём: это может вызвать ложную реакцию управления отоплением. Подробнее: Jinja и availability в Home Assistant .
Диагностика
Датчик BTHome не обнаруживается или становится unavailable
1 Проверьте батарею и реальную передачу рекламных пакетов: некоторые датчики поставляются с защитной вставкой.
2 Перенесите устройство поближе к исправному Bluetooth-сканеру и повторите проверку.
3 Убедитесь, что интеграция Bluetooth активна и видит другие совместимые BLE-устройства.
4 Проверьте BTHome v2 в настройках устройства: оно может вещать в формате MiBeacon/ATC или другого производителя.
5 Для зашифрованного устройства проверьте правильность bindkey, его длину и актуальность.
6 Если датчик подключён через Proxy, проверьте его питание, Wi-Fi/Ethernet, Native API и связь с Home Assistant.
7 Изучите System Log и кратковременный debug нужной интеграции, затем выключите DEBUG.
8 Сравните частоту реальных обновлений и уровень сигнала в целевом месте установки.
Не удаляйте автоматически все связанные entities и интеграции. Сначала определите, ошибка находится в приёме радиопакета, дешифровании или последующей обработке. Для диагностики журналов используйте статью System Log, Repairs и Debug Logging .
Приватность
Безопасность BTHome и защита личной информации
Нешифрованные рекламные сообщения доступны для чтения находящимся рядом BLE-приёмникам. Не закладывайте в открытые поля пакета персональные сведения и секреты. При включении AES-CCM защищайте bindkey, файлы конфигурации и резервные копии.
Не публикуйте ключи и журналы с идентификаторами устройств в открытых репозиториях. Не смешивайте отладочные данные, содержащие сведения о присутствии жильцов, с публичными скриншотами. Проверяйте сторонние компоненты ESPHome перед установкой. Не стройте критичную автоматику на одном BLE-событии. При передаче диагностического архива специалисту уберите из него ключи, пароли и лишние персональные данные.
Больше о ключах, токенах и безопасном удалённом доступе: защита Home Assistant .
Проверка готовности
Чек-лист перед включением BTHome в рабочую систему
✓ Модель и прошивка действительно поддерживают BTHome v2.
✓ Bluetooth-сканер или ESPHome Proxy работает стабильно.
✓ При необходимости получен корректный bindkey.
✓ Все ожидаемые entities появились без дублей.
✓ Проверены обновления показаний в целевом помещении.
✓ Определено, как интеграция ведёт себя при потере датчика.
✓ Автоматизации отдельно обрабатывают unknown/unavailable.
✓ Защитные функции не зависят только от BLE.
✓ Ключи шифрования не размещены в открытом доступе.
Для неответственного мониторинга микроклимата BTHome может быть простым локальным решением. Но при необходимости гарантированной доставки тревожных сообщений и управления критичным оборудованием применяйте специализированные независимые средства безопасности.
FAQ
Частые вопросы о BTHome, BLE и bindkey
Что такое BTHome в Home Assistant? Открытый формат BLE advertisements для передачи данных датчиков и событий. Home Assistant принимает их через Bluetooth и расшифровывает встроенной BTHome integration.
Чем BTHome v2 отличается от v1? Версия 2 использует сервисный UUID 0xFCD2 и современное кодирование типов данных. V1 считается устаревшим форматом для новых устройств.
Нужен ли Bluetooth Proxy? Нет, если у Home Assistant уже есть хороший BLE-сканер в радиусе приёма. Proxy полезен для удалённых комнат и серверов без удобного Bluetooth-адаптера.
Нужно ли GATT-подключение для BTHome-термометра? Обычно нет. Температура и влажность передаются рекламными пакетами BLE без постоянного подключения.
Какой длины должен быть bindkey? 16 байт, записанных 32 символами шестнадцатеричной системы счисления без пробелов.
Где получить bindkey? В настройках конкретного устройства или совместимой прошивки. Универсального ключа для всех датчиков нет.
Нужен ли ключ для незашифрованного BTHome? Нет. Bindkey необходим только для датчиков с включённым BTHome encryption.
Любой Xiaomi-термометр сразу работает с BTHome? Нет. Это зависит от модели, прошивки и рекламного формата. Некоторые устройства с PVVX умеют BTHome v2.
Что означает сервис UUID 0xFCD2? Это идентификатор BTHome v2. В байтах BLE service data он записывается как D2 FC.
Сколько термометров принимает один Bluetooth Proxy? Число advertising-датчиков не ограничивается числом GATT connection slots. Практический предел зависит от радиопокрытия, количества пакетов и производительности приёмника.
Почему старая температура продолжает показываться? Некоторые интеграции сохраняют последнее известное значение. Нужно проверять поступление свежих данных и поведение при потере связи.
Поддерживает ли BTHome нажатия кнопок? Да. Формат предусматривает press, double_press, long_press и другие события. Возможности Home Assistant зависят от конкретного устройства.
Гарантирует ли bindkey защиту от подмены событий? Не полностью. Спецификация предупреждает о рисках spoofing и replay, если получатель не выполняет все необходимые проверки.
Можно ли автоматически открывать замок по BTHome? Не следует использовать одно BLE-событие как достаточную авторизацию. Нужна независимая безопасная логика.
Можно ли сделать BTHome-датчик на ESP32? Да, с подходящей прошивкой-передатчиком BTHome v2. ESPHome Bluetooth Proxy и bthome_mithermometer относятся к приёму данных, не к передаче.
Техническая основа
Официальные источники и спецификации Описание формата, шифрования и настройки сверено с первичными документами на октябрь 2026 года. Перед перепрошивкой датчика проверяйте документацию именно своей аппаратной ревизии.
Консультации по умному дому
BLE-датчики не появляются или постоянно теряют связь?
Причина может быть в несовместимой прошивке, неправильном bindkey, радиопокрытии, Bluetooth Proxy или настройках Home Assistant. Лучше сначала проверить протокол и реальные данные, чем менять всё оборудование наугад.
Для удалённого разбора доступна онлайн-помощь по умному дому . Для настройки оборудования на объекте в Туле и Тульской области — системы умного дома .