UnitX-L: техническое руководство
Режимы работы UnitX-L, таймеры, BTHome, внутренняя память, датчики, BLE-служба, безопасность и определение местоположения.
Как устроена работа UnitX-L
UnitX-L рассчитан на автономную работу от батареи. Большую часть времени устройство находится в энергосберегающем режиме, а затем просыпается по таймеру или по событию, измеряет датчики и выполняет запланированные действия.
У передачи текущих показаний и внутреннего журнала разные задачи:
- BTHome передаёт последнее измерение окружающим приёмникам без соединения с устройством. Это удобно для телефона, шлюза и умного дома, но доставка каждого сообщения не гарантируется.
- Внутренний журнал сохраняет измерения с отдельным интервалом. Его можно считать позже через настольную программу, даже если во время работы рядом не было ни одного приёмника Bluetooth.
Интервал выхода в эфир, интервал записи и набор сохраняемых датчиков задаются в настольной программе.
Основные сценарии
Датчик BTHome
UnitX-L периодически передаёт показания установленных датчиков и состояние батареи. Приёмник слушает сообщения и не устанавливает соединение с каждым логгером. Этот режим подходит для Home Assistant, собственного Bluetooth-шлюза или краткой проверки с телефона.
Автономный журнал
Если постоянного приёмника нет, UnitX-L записывает данные во внутреннюю память. Сотрудник подключается к нему при обходе или после перевозки, выгружает журнал и сохраняет CSV. Длительность доступной истории зависит от интервала записи, выбранных датчиков и количества событий акселерометра.
Текущие данные вместе с журналом
Оба режима можно включить одновременно. BTHome даёт текущую картину, а журнал позволяет восстановить пропуски за время, когда приёмник или сеть не работали.
Таймеры и параметры
Заводские значения:
| Параметр | Значение по умолчанию | Назначение |
|---|---|---|
| Интервал измерения и BTHome | 60 с | Период пробуждения для нового текущего значения |
| Интервал записи | 60 с | Период журнала, когда запись разрешена |
| Запись во внутреннюю память | выключена | Отдельное разрешение на ведение журнала |
| Быстрое окно Bluetooth | 20 с | Частая передача сразу после пробуждения |
| Интервал энергосберегающей передачи | 9000 мс | Пауза между пакетами на второй стадии окна |
| Длительность энергосберегающей передачи | 22 с | Продолжительность второй стадии окна |
| Таймаут неактивного соединения | 180 с | Закрытие соединения без команд |
| Диапазон акселерометра | 4000 mg | Полный диапазон измерения LIS3DH |
| Порог акселерометра | 8000 mg | Порог события резкого ускорения |
| Окно после срабатывания геркона | 30 с | Доступность для подключения в быстром режиме |
| Быстрый режим геркона | выключен | Разрешение открывать окно магнитом |
Интервал BTHome и интервал записи независимы. Например, текущие показания можно передавать раз в минуту, а журнал вести раз в десять минут. Значение интервала записи не включает журнал само по себе: должен быть включён отдельный переключатель записи.
Частые пробуждения и длинные окна Bluetooth повышают вероятность приёма, но ускоряют расход батареи. Частая запись даёт более подробный график, но быстрее заполняет память.
Подключение и геркон
UnitX-L виден для подключения только во время активного окна Bluetooth. Его можно дождаться по расписанию или открыть магнитом:
- В конфигурации включите Быстрый режим геркона.
- Поднесите магнит к зоне геркона на корпусе.
- Сразу запустите сканирование в настольной программе.
Геркон используется для пробуждения и открытия окна связи. Само поднесение или удаление магнита не создаёт отдельную запись «открыто» во внутреннем журнале.
При поиске устройство отображается под коротким именем вида UTXxxxxx.
Полное GATT-имя имеет вид UnitX-L-XXXXXXXX; Device Information Service
содержит производителя UnitX и модель UnitX-L.
Передача BTHome v2
BTHome — открытый формат для показаний датчиков в
широковещательных сообщениях Bluetooth Low Energy. UnitX-L использует BTHome
v2 с UUID службы 0xFCD2 и передаёт данные без шифрования, поэтому их может
прочитать любой совместимый приёмник поблизости.
В сообщение UnitX-L входят:
- идентификатор последовательности пакета;
- заряд батареи в процентах;
- температура;
- влажность при наличии HDC2080;
- напряжение питания.
Устройство помечает себя как источник с нерегулярными окнами передачи. Приёмник не должен считать его пропавшим сразу после окончания окна.
BTHome предназначен только для текущих показаний. Настройка, синхронизация времени и чтение накопленной истории выполняются через отдельную службу UnitX-L.
Датчики
Набор зависит от комплектации устройства.
| Компонент | Назначение |
|---|---|
| HDC2080 | основной датчик температуры и влажности |
| TMP1075 | резервный датчик температуры |
| LIS3DH | ускорение по трём осям и событие превышения порога |
| Контроль питания | напряжение и расчётный заряд батареи |
| Датчик микроконтроллера | внутренняя температура электроники |
HDC2080 хранит температуру с разрешением до сотых долей Кельвина и влажность до сотых долей процента. Для обычного пользователя программа переводит эти значения в привычные единицы.
Для LIS3DH выбирается диапазон 2g, 4g, 8g или 16g. Больший диапазон позволяет зафиксировать более сильный удар, но снижает чувствительность. При включённой записи серии измерений превышение порога пробуждает устройство и сохраняет несколько частых отсчётов акселерометра.
Внутренний журнал
Журнал хранится во флеш-памяти как кольцо: когда свободное место заканчивается, новые блоки постепенно заменяют самые старые. До начала длительной работы проверьте оценку ёмкости в разделе История программы.
Периодические записи могут содержать:
- температуру и влажность HDC2080 либо температуру TMP1075;
- один отсчёт ускорения по трём осям, если акселерометр включён в режим записи;
- отдельные серии акселерометра после превышения порога.
Через Bluetooth программа получает записи с абсолютным временем и типом, не разбирая физическую разметку флеш-памяти. Если часы устройства были переведены назад, временные метки в выгрузке могут идти не по порядку; графики перед показом сортируют их.
Каждая передаваемая страница истории содержит порядковый номер. Если Bluetooth-стек временно занят или подтверждение потерялось, клиент повторно запрашивает ту же страницу. Устройство отправляет её ещё раз и переходит к следующей только после согласованного ответа.
Служба UnitX-L для настройки и истории
Для собственной программы устройство предоставляет отдельную GATT-службу:
| Назначение | UUID |
|---|---|
| Logger Service | 9ecadc24-0ee5-a9e0-93f3-a3b50100406e |
| Запись команды | 9ecadc24-0ee5-a9e0-93f3-a3b50200406e |
| Уведомление с ответом | 9ecadc24-0ee5-a9e0-93f3-a3b50300406e |
| Поток истории | 9ecadc24-0ee5-a9e0-93f3-a3b50400406e |
| Чтение и уведомление состояния | 9ecadc24-0ee5-a9e0-93f3-a3b50500406e |
Прошивка использует версию кадров 0x06. Команды охватывают информацию об
устройстве, датчики, время, конфигурацию, состояние памяти, чтение и очистку
истории, защиту, определение местоположения и служебные операции.
В версии 0x06 запрос HISTORY_PAGE содержит номер страницы. Актуальные
настольная программа и utils/ble_check.py поддерживают этот формат; сторонний
клиент для версии 0x05 нужно обновить перед подключением к новой прошивке.
Формат запросов, ответов и страниц истории описан в файле
fw2/Docs/protocol.md,
а фактическая версия и обработчики команд находятся в
app_protocol.c.
Защита настроек
Пароль не установлен по умолчанию. При первой установке пароля поднесите магнит к геркону и удерживайте его до завершения команды в настольной программе. Назначить первый ключ только через Bluetooth без физического доступа к устройству нельзя.
После включения защиты изменение или удаление пароля требует действующего пароля и авторизованного соединения. Команды изменения настроек, очистки истории, обновления и выключения подтверждаются на основе HMAC-SHA256. Авторизация действует только до разрыва текущего Bluetooth-соединения.
Конфигурация, параметры определения местоположения и ключ авторизации хранятся в двухстраничном журнале. Новая копия получает номер поколения, контрольную сумму и отметку завершения после проверки чтением. Если запись прервётся, прошивка использует предыдущую завершённую копию. Если обе копии повреждены и достоверный ключ восстановить нельзя, устройство не возвращается в режим свободной первичной настройки; для восстановления нужен сервисный доступ, например SWD.
Защиту рекомендуется включить, если посторонний человек может подойти к устройству и открыть окно связи. Пароль нужно сохранить вместе с JSON-профилем устройства на компьютере.
Определение местоположения
Дополнительный режим передаёт сигнал Apple Offline Finding. UnitX-L хранит только открытый ключ маяка; закрытый ключ остаётся на компьютере и нужен для получения отчётов.
Доступны три режима совместной работы:
| Режим | Поведение |
|---|---|
beacon_only | передаётся только сигнал определения местоположения |
windowed_config | сигнал передаётся постоянно, а настройка доступна в отдельных окнах |
always_config | сигнал и служба настройки доступны одновременно |
UnitX-L не является сертифицированным аксессуаром Apple и не добавляется в обычное приложение «Локатор». В нём нет GPS и мобильного интернета. Отдельные точки появляются только тогда, когда сигнал увидело совместимое устройство Apple и программа UnitX-L смогла получить соответствующий отчёт.
Обновление прошивки
Основная прошивка работает вместе с отдельным загрузчиком. Команда перехода в DFU подтверждается устройством, после чего оно перезагружается в режим обновления. Эту операцию выполняют по отдельной инструкции и только с образом, предназначенным для UnitX-L.
Обновлённый загрузчик проверяет границы образа, CRC, подпись ECDSA P-256 и монотонный счётчик безопасности. Образ со счётчиком ниже уже принятого отклоняется; повторная установка с тем же счётчиком разрешена. Счётчик хранится в отдельном журнале, который обычное OTA-обновление не стирает. Защита от отката работает только после установки обновлённого загрузчика.
При первом переходе на формат протокола 0x06 одна прежняя страница истории
отводится под вторую копию настроек, а последняя страница пользовательской
флеш-памяти — под счётчик OTA. Записи на этих страницах могут быть потеряны;
остальные корректные блоки продолжают читаться. Перед обновлением выгрузите и
сохраните нужную историю на компьютере.
Диагностика
Устройство не появляется при сканировании. Оставьте поиск включённым до следующего цикла. Если быстрый режим геркона уже настроен, поднесите магнит и повторите поиск. Проверьте батарею, расстояние и отсутствие металлического экрана вокруг логгера.
BTHome виден, но программа не успевает подключиться. Увеличьте длительность сканирования в настройках программы. После подключения увеличьте активное окно Bluetooth или включите быстрый режим геркона.
Журнал остаётся пустым. Проверьте интервал записи и переключатель Запись во флэш включена. После заводского сброса запись выключена.
Время записей неверно. Перед началом работы синхронизируйте часы в Dashboard → Время. После перевода времени назад сортируйте записи по временной метке.
Команды чтения или изменения отклоняются. Проверьте, включена ли защита паролем, и выполните авторизацию заново после переподключения.
Не устанавливается первый пароль. Поднесите магнит к геркону и удерживайте его до завершения команды. Для первой установки ключа активный геркон обязателен.
Нужна собственная интеграция. Начните с BTHome для текущих показаний. Для настройки и истории используйте Logger Service и исходный код клиента из репозитория UnitX-L.