Коротко:
ha-joplin-bridge add-on для home assistant который запускает joplin cli внутри расширения и позволяет вам автоматизировать работу с заметками joplin из home assistant. Всё!
Длинно (нет, очень длинно):
Про joplin
Система заметок, списков (to-do), которая есть под практически всё, что сложнее калькулятора, основные десктопные системы, телефоны, есть web клиент (в экспериментальной стадии и грозится умереть) и есть cli версия для терминала (это важно).
Есть же obsidian, воскликнет не равнодушный читатель, да есть, но во первых joplin был у меня первым, я к нему привык, моя семья к нему привыкла, он работает без нареканий, но главное он поддаётся автоматизациям, я не утверждаю, что obsidian не поддается, но проприетарность его клиента мне не дает покоя, нужно станцевать с бубном для синхронизации, а потом еще и с общими заметками, ну так заведено у меня в семье, что супруга составляет список покупок, а я либо дети исполняют и это функционал joplin изкаропки (при условии своего сервера синхронизации). Я не создаю второй мозг, я не улучшаю свою систему ведения заметок и дел, я просто ею пользуюсь.
Что важно для понимания следующего текста, Joplin силен своим клиентом, каждый клиент полноценный и самостоятельный боец, со всем функционалом. Но как заведено в нашем мире, у нас не одно устройство, обычно это свзяка из дестопа/ноутбука и телефона и нужна синхронизация между клиентами. Вот тут и вступает в действие сервер синхронизации joplin у него всего 4 задачи:
- Вести учет пользователей
- Синхронизировать заметки между разными клиентами одного пользователя
- Шарить общие блокноты между пользователями
- Шарить выбранные заметки в мир, т.е. можно выбрать заметку и отдать всем, сервер сформирует общедоступный url и преобразует markdown в html для этой заметки (естественно при условии, что у вас настроен reverse proxy, есть домен и т.п.)
Чего НЕ делает сервер: он не общается с клиентами для предоставления им заметок, он не поддерживает crud (create update delete) операций с заметками в привычном понимании, т.е. нельзя обратиться к серверу не клиентом и запросить у него заметки определенного блокнота или сказать, а измени мне вот эту заметку, это только пакетная синхронизация.
О какой автоматизации тогда может идти речь, если сервер у нас такой каличный, опять же клиенты - это мощнейшие инструменты. Дело в том, что каждый клиент умеет поднимать свой локальный сервер обычно на порту 41184, сделано это во первых для внешних интеграций , тот же Joplin Web Clipper - расширение для браузера, которое позволяет вам скраппить страницу сразу в joplin общается с клиентом именно через этот локальный сервер. Уже у локального сервера мощнейшее REST api, от авторизации до полного crud.
Есть один нюанс, клиент поднимает сервер по адресу localhost (127.0.0.1) и отвергает все подключения которые идут не с локалхоста, даже рядом стоящий компьютер в одной сети не может слать запросы к этому локальному серверу, связано это с вопросами безопасности.
Что сделал я, для связки Home Assistant - Joplin? Home Assistan (далее HA) у меня установлен в режиме supervisor…
Что не так с Home Assistant (HA)
Первое что нужно понять, любые дополнения HA технически - это контейнеры Docker, отсюда пляшем.
До недавнего времени HA поддерживал четыре способа установки:
- Container - в качестве контейнера Docker, понятно что нет дополнений т.к. контейнер который управляет контейнерами, ну такое.
- Core - HA как простое приложение в системе, тоже никаких дополнений
- Supervised - Это продвинутый Core, он ставится как linux приложение, но берет на себя управление контейнерами в системе и очень, очень сильно ругается вплоть до того, что отказывается работать если контейнеры начать ставить в его обход. Т.е. уже с дополнениями.
- HAOS - высшая степень эволюции, HA - statless операционная система на базе debian, она царь и бог в системе (никто не мешает запустить в proxmox).
Так вот у меня HA установлен в режиме Supervised, в качестве основной системы Debian 12, это позволяло мне рядом с HA ставить все что душе угодно (но не контейнеры), поэтому я рядом с HA поставил nodejs и водрузил Joplin CLI (консольного клиента), настроил его на синхронизацию, включил сервер clippera и из HA мог спокойно по REST api слать запросы к Joplin автоматизациями, создавать, запрашивать, модифицировать заметки.
Единственной проблемой встала синхронизация, клиенты Joplin могут автоматически инициировать синхронизацию по таймауту, но когда я беру телефон наговариваю заметку в HA (да его можно поставить как минимум на Android в качестве голосового ассистента по умолчанию вместо Google Assistant), у меня HA через speach-to-text ее распознает и раскладывает по блокнотам в зависимости от ключевых слов, то я сразу ее хочу видеть в мобильном клиенте а ждать таймаут пока Joplin Cli, что принял эту заметку не синхронизирует ее. Поэтому на своем любимом C# я написал еще один сервер с один единственным эндпоинтом /sync, который можно вызвать по rest а он уже запускл процесс joplin sync, зарегистрировал сервачок в качестве демона в системе и жил не тужил до обновления HA 2025.6.
Что случилось?
В обновлении Home Assistant 2025.6 объявили, что деприкейтят (признают устаревшими) 32 битные архитектуры процессоров, ну и поделом, туда им и дорога, но самое главное деприкейтятся типы установок Core и Supervised (мой вариант). Остаются только Docker и HAOS, Docker тип установки не позволяет ставить дополнения, а это 90% смысла существования HA, так что не мой вариант. В декабре 2025 года поддержка будет окончательно прекращена и не будут выходить обновления для этих типов установок. Нужно переезжать на HAOS.
Как я говорил выше HAOS это стейтлесс Debian, что такое statless система? У вас два набора заделов под систему, вы не можете что-то поменять в текущей установке, любые обновления, добавления пакетов применяются к второму набору разделов, потом вы перезагружаетесь и оказываетесь на втором разделе, обновления только на, только что освобожденный, раздел. А нафига? Безопасность и стабильность, если что-то пойдет не так при обновлении и вы не сможете загрузиться, HA попробует три раза и откатится на предыдущий набор разделов где все работало до обновлений. Куто? Круто!
В замен мы получаем, что фиг вам не поставить рядом свой пакет в виде Joplin Cli, а тем более свой сервер, как демон, никто в systemctl копаться не даст.
Рождение ha-joplin-bridge
Нельзя поставить рядом, тогда вспоминаем, что дополнения HA (add-on`s) это контейнеры, просто оформлены определенным образом, чтобы HA мог ими управлять, а туда можно хоть черта лысого запихнуть, правда базовый образ это тоже HA, так что ограниченных чертов. HA у нас написан на python, а в ptyhon я как свинья в апельсинах, поэтому был применен нынче модный способ программирования вайб кодинга, берем llm описываем задачу, боремся с его тупостью и стараемся чтобы это все заработало и не было отломано, что уже до этого работало. Один чат claude 4, я загнал как лошадь, он окончательно потерял связь с реальностью и под конец вообще перестал отвечать. Со вторым мы вроде допинали проект до рабочего состояния.
Внутри контейнера стоит Joplin CLI который внутри контейнера работает на своем стандартном порту 41184, но наружу контейнера его проксирует socat на 41185 порт. На 41186 порту обновленный близнец моего сервачка (ну тот который joplin sync вызывал) но с более широким функционалом, у него можно запросить токен, запросить состояние сервер, ну и естественно запустить синхронизацию (см. документацию репозитория).
Тип синхронизации, я ничего кроме сервера синхронизации Jopin (тип 9) не проверял, но то что проверял оно работает. В коде еще есть тип синхронизации Web-Dav (тип 5), а больше вроде ничего и нет :)).
Не малую часть работы отняла на себя ci (система сборки) на GitHub, llm напридумывала себе же проверок с которым потом сама же доблестно боролась. Оказывается у python есть дурацкая проверка - последняя строка в файле должна быть пустой, сколько же она мне крови попила :)).
Тестировал я это на резервной машине на N5105, которую уже перевел на HAOS, все завелось, все работало, но при переносе на боевой сервер, конфигурация не работала и расширение останавливалось с ошибкой. Методом научного тыка я выяснил, что проблема с полями типа password (пароль для авторизации на сервере синхронизации), в методе установки supervised HA просто не может им задать значение, хотя на HAOS все работает. Сейчас временно оставил их прямым текстом, да знаю, безопасность, все дела, но мы говорим о HA, а это система в вашем контуре, которую только вы контролируете (ну я надеюсь).
В Joplin себе добавил напоминание, что в декабре нужно переделать поля на правильный тип со скрытием в интерфейсе и надеюсь HAOS их хранит в защищенном хранилище.
Дополнение сразу разрабатывалось с поддержкой только 64 бит.
В общем, кому нужно пользуйтесь, кому не нужно не пользуйтесь. Кому интересно исправляйте, контрибудьте.
p.s. Ну и хостите свои ресурсы только на своих мощностях!
p.s.s. Этот текст был написан в Joplin.