HeishaMon (прямой serial / RS232)

Адаптер ioBroker, который передает данные по протоколу Panasonic Aquarea CN-CNT напрямую по последовательной линии, без использования модуля HeishaMon или MQTT-брокера. Разъем CN-CNT теплового насоса использует логические уровни 5 В TTL UART . Для подключения к UART с напряжением 3,3 В, например, к GPIO UART Raspberry Pi, требуется соответствующий преобразователь уровней. Для длинных кабелей можно дополнительно установить преобразователь TTL/RS485, поскольку протокол является полудуплексным. Декодирование протокола основано на данных проекта HeishaMon .

Статус: Предварительный релиз. Библиотека протоколов, симулятор и логика адаптера находятся в процессе разработки; следующим шагом станет полевое тестирование на реальном тепловом насосе.

Поддерживаемые тепловые насосы

Тепловые насосы типа «воздух-вода» Panasonic Aquarea серий H, J, K и L.

Установка

Установите из официального репозитория ioBroker через административный интерфейс: откройте вкладку «Адаптеры» , найдите heishamon и нажмите «Установить». Затем добавьте экземпляр в разделе «Экземпляры» .

Предварительные условия для последовательного порта

Это действия на стороне хоста, которые административный интерфейс не может выполнить за вас:

• Пользователь процесса ioBroker (iobroker (В стандартной конфигурации Linux) необходимо разрешить открытие последовательных устройств. В Debian/Raspberry Pi OS это означает следующее:dialout группа:

  groups iobroker                     # must contain 'dialout'
  sudo usermod -aG dialout iobroker   # if not — then restart the whole ioBroker service
  

• Используйте стабильный путь к устройству, чтобы порт сохранял работоспособность после перезагрузки и повторного подключения. Предпочтительнее/dev/serial/by-id/... над/dev/ttyUSB0 :

  ls -l /dev/serial/by-id/
  

  На Raspberry Pi GPIO UART путь в любом случае статичен (например,/dev/ttyAMA2 ).

Для подключения теплового насоса см. раздел «Подключение» ниже.

Конфигурация

Функции

• Прямая последовательная связь с тепловыми насосами Panasonic Aquarea через порт CN-CNT. Не требуется оборудование HeishaMon или брокер MQTT.
• 157 точек данных представлены в виде состояний ioBroker с указанием соответствующих ролей, типов и единиц измерения.
• Задайте команды для всех параметров, доступных для записи и поддерживаемых протоколом CN-CNT.
• Режим только для чтения для безопасной параллельной работы с существующей установкой HeishaMon (переход на 4-й этап).
• Статистика качества соединения (входящие/исходящие кадры, ошибки CRC, тайм-ауты) в рамкахinfo.* канал.
• Дополнительный блок данных (опционально) для тепловых насосов серии K/L (6 дополнительных точек данных об энергопотреблении).

⚠️ Учет скорости записи

Механизм внутреннего хранения настроек контроллера Panasonic Aquarea не документирован. Обычное использование — ручная настройка, периодическая автоматизация умного дома — вряд ли приведет к износу; сообщество HeishaMon имеет многолетний опыт эксплуатации без сообщений о сбоях. Однако высокочастотная запись (например, ПИД-регулятор, корректирующий заданное значение каждые несколько секунд) теоретически может со временем израсходовать ячейку EEPROM, если контроллер не использует FRAM, MRAM или ОЗУ с функцией сброса данных при отключении питания.

Избегайте записи одной и той же точки данных чаще, чем каждые несколько минут, если у вас нет конкретных сведений о том, что ваша версия контроллера это допускает. Для регулирования с обратной связью предпочтительнее использовать медленный внешний контур, который управляет внутренними контроллерами теплового насоса, а не напрямую управляет исполнительным механизмом.

Что вам нужно

Никаких устройств HeishaMon, ESP, MQTT-брокера. Этот адаптер напрямую взаимодействует по протоколу Panasonic CN-CNT. Единственное, что вам нужно создать, это последовательное соединение между тепловым насосом и устройством, на котором запущен ioBroker (ПК, домашний сервер, NAS, Raspberry Pi и т. д.).

Уровень сложности — сначала прочтите это. Для установки необходимо открыть крышку электронного блока теплового насоса и подключить два провода данных и заземление к внутреннему разъему. Вы должны уметь работать с проводами малого сечения и основами электроники (логические уровни, контуры заземления, RS485). Это низковольтная (сигнализация 5 В), а не работа от сети — но неправильный разъем или перевернутая проводка все равно могут нарушить работу теплового насоса. Если это предложение вызывает у вас беспокойство, то это не лучший проект для начала работы с электроникой.

⚠️ Все действия выполняются на ваш собственный риск и под вашу ответственность — гарантия не предоставляется. Вскрытие устройства может аннулировать гарантию производителя. Перед подключением проводов отключите тепловой насос от сети. Семь раз отмерь, один раз подключи.

Сигнал и строительный блок

По сути, это всего лишь последовательное соединение между хостом ioBroker и тепловым насосом — ничего более экзотического. Вопрос лишь в том, как физически организовать это соединение.

Тепловой насос использует обычный 5-вольтовый TTL UART-интерфейс на своем разъеме. Простейший способ обеспечить связь — это 5-вольтовый USB-to-TTL UART-адаптер : всего три провода — GND ↔ GND и две линии передачи данных, перекрещенные (передатчик теплового насоса → приемник адаптера, приемник теплового насоса → передатчик адаптера) — оставляют +5 В / +12 В неподключенными. Предварительно подключенный адаптерPHR-4 Подключение пигтейла к CN-NMODE часто позволяет обойтись без пайки.

Гальваническая изоляция необязательна, но важно понимать, что поставлено на карту. Контакты RX/TX теплового насоса могут быть напрямую подключены к микроконтроллеру , практически без какой-либо защиты между ними. Чрезмерное напряжение или ток на этих линиях — контур заземления/выравнивающего тока, сбой в проводке, контакт +12 В, задетый сигнальной линией — могут вывести из строя микроконтроллер и привести к выходу из строя материнской платы теплового насоса . Если вы не уверены в наличии контура заземления/выравнивающего тока между тепловым насосом и основным устройством, дешевый USB-изолятор на стороне USB устранит этот путь. В противном случае защитите линии другим способом (например, с помощью последовательных резисторов или PTC-предохранителей) — многие установки работают нормально без какой-либо изоляции, но это решение вы принимаете осознанно.

Такой адаптер без корпуса подойдет только в том случае, если хост ioBroker действительно находится рядом с тепловым насосом — например, при стендовом тестировании или при установке небольшого одноплатного компьютера непосредственно рядом с устройством.

Рекомендуемая конфигурация — двухпроводной RS485 на расстоянии.

На практике хост ioBroker находится в другой комнате или на другом этаже, а не в 2 метрах от теплового насоса. Поэтому разумным вариантом в реальных условиях является соединение RS485 по экранированной витой паре , что также соответствует полудуплексному характеру протокола:

heat pump (5 V TTL, CN-NMODE)
   └─ TTL↔RS485 converter        ← near the heat pump
        └─ shielded twisted pair, 120 Ω termination at BOTH ends, mind A/B
             └─ RS485↔USB adapter ← at the ioBroker host
                  └─ USB → ioBroker host  →  /dev/serial/by-id/…

Вы создаете тот же TTL-интерфейс, что и выше, но вместо передачи данных по USB на всем протяжении, вы преобразуете сигнал в RS485 прямо на тепловом насосе и прокладываете два провода к хосту. Небольшие платы преобразователя TTL↔RS485 стоят всего несколько долларов в обычных интернет-магазинах и, как правило, уже имеют базовую защиту линии (TVS-диоды / резисторы смещения) — это приятный дополнительный запас прочности со стороны теплового насоса. Гальваническая изоляция остается необязательной и, если используется, проще всего применяется на стороне USB хоста.

Какой бы путь вы ни выбрали, адаптер всегда будет видеть только локальный путь к последовательному устройству — продолжите на странице «Конфигурация» .

Другие варианты (расширенные)

Проводка

⚠️ Семь раз отмерь, один раз подключи. Все представленные здесь материалы предоставляются без каких-либо гарантий и используются исключительно на ваш собственный риск и под вашу ответственность.

☠️ Неправильное подключение может вывести из строя тепловой насос. Контакты CN-CNT / CN-NMODE RX/TX могут быть подключены напрямую к микроконтроллеру теплового насоса , практически без какой-либо защиты между ними. Обратите внимание на контакты +5 В и +12 В, расположенные рядом с сигнальными линиями в таблицах ниже: попадание +12 В на сигнальный контакт, перевернутый провод или скачок тока заземления/выравнивающего тока могут вывести из строя микроконтроллер и материнскую плату. Дважды проверьте каждый контакт перед включением питания.

На материнской плате теплового насоса имеются два одинаковых разъема, которые можно использовать с этим адаптером: CN-CNT и CN-NMODE . Подойдет любой из них — выберите тот, к которому легче добраться.

CN-CNT Обычно используется разъем для облачного модуля CZ-TAW1 или дополнительной печатной платы :

• Если подключен модуль CZ-TAW1 , запустите этот адаптер в режиме только для чтения, чтобы он только прослушивал шину и никогда не управлял ею.
• При наличии дополнительной печатной платы имеется два ведущих устройства шины, поэтому возможны коллизии — в целом, система должна работать. После ошибки CRC адаптер ожидает случайного времени перед следующим доступом к шине, чтобы разорвать синхронизацию при коллизиях (см. примечания к шине, управляемой ответами, в журнале изменений).

Оба разъема передают сигнал UART TTL 5 В , поэтому для устройств с напряжением 3,3 В, таких как GPIO Raspberry Pi, требуется преобразователь уровней. Названия сигналов ниже приведены с точки зрения теплового насоса — перечеркните их на конце адаптера (передатчик теплового насоса → приемник адаптера, приемник теплового насоса → передатчик адаптера).

CN-CNT — JSTB05B-XASK-1 (сопрягаемый разъем)PAP-05V-S )

CN-NMODE — серия JST PH (соединительный разъем)PHR-4 (Доступны в предварительно смонтированном виде у обычных крупных интернет-магазинов)

Пример — преобразователь UART в RS485, подключенный кCN-NMODE Разъем (сторона теплового насоса варианта RS485 для дальней связи):

Поиск неисправностей

• EACCESна последовательном устройстве — пользователь процесса ioBroker не находится вdialout группа. Послеsudo usermod -aG dialout iobroker перезапустите всю службу ioBroker (sudo systemctl restart iobroker ), а не только в отдельном случае — членство в группе вступает в силу только в новой сессии.
• Адаптер запускается, но данные не отображаются — проверьте проводку на порту CN-CNT (перекрестно TX↔RX, подключите GND, следите за уровнями TTL 5 В, см. раздел «Проводка» ). При использовании преобразователя TTL↔RS485 также проверьте полярность A/B и оконечные резисторы. В исправном соединении отображается около 157 точек данных.heishamon.0.main.* через несколько секунд и устанавливаетсяheishamon.0.info.connection кtrue .
• Команды установки не имеют никакого эффекта —readOnlyMode Это намеренно установленное безопасное значение по умолчанию для первого запуска. Отключайте его только после того, как путь чтения будет пройден без ошибок.
• Подключение осуществляется через шину CZ-TAW1 — не вынимайте адаптер.readOnlyMode В противном случае это вызовет конфликты шины с облачным модулем Panasonic.

Документация

Документация проекта находится в папке docs/ :

• docs/plan/ — план этапов и дорожная карта.
• docs/protocol/ — Анализ протокола CN-CNT.
• docs/decisions/ — записи о решениях в области архитектуры.

Указание авторства и лицензирование исходного сырья

Декодирование протокола основано на работе сообщества HeishaMon . Карта регистров CN-CNT и многие подсказки по реализации берут свое начало именно там.

На момент написания статьи в репозитории HeishaMon отсутствует явный файл лицензии .LICENSE В исходном коде нет заголовка, в файле README нет четкого указания. Согласно законодательству США и ЕС об авторском праве, по умолчанию используется формулировка «все права защищены», поэтому мы не можем копировать или напрямую переносить оригинальный код. Чтобы избежать проблем:

• Исходный код HeishaMon на C++ служит лишь справочным материалом для понимания протокола Panasonic CN-CNT.
• Этот адаптер — это полностью переработанная реализация на TypeScript : мы изучили исходный код, перевели протокол в папку docs/protocol/ и реализовали его на основе этой документации, а не оригинального кода.
• Файлы документации протокола в репозитории HeishaMon (MQTT-Topics.md ,OptionalPCB.md ,ProtocolByteDecrypt.md Они описывают наблюдаемый физический протокол — то есть фактическую информацию, не подлежащую защите авторским правом; в соответствующих случаях они приводятся в качестве источников.

Сам протокол CN-CNT не опубликован компанией Panasonic; открытия HeishaMon основаны на эмпирических наблюдениях. Факты не подлежат защите авторским правом, но конкретная реализация этих открытий на C++ подлежит.

Changelog

0.0.14 (2026-06-29)

• (Tobias Hanss) Corrected the maintainer email address in the package metadata (package.json, io-package.json)
• (Tobias Hanss) extraPollEnabled now defaults to off (opt-in) — the K/L-series extra data block is only polled when explicitly enabled, so a fresh install never polls datapoints that H/J pumps cannot provide. Existing instances keep their current setting
• (Tobias Hanss) Documentation: reworked the hardware/wiring section — clarified that only a plain serial link is needed (no HeishaMon device), made 2-wire RS485 the recommended real-world path, added a Raspberry Pi GPIO UART step-by-step, and a dead-mainboard warning at the wiring pinouts

0.0.13 (2026-06-28)

• (Tobias Hanss) Release now uses npm trusted publishing (provenance via OIDC) on Node 24 — fixes repository-checker E2008/E3019/E3022
• (Tobias Hanss) Removed the redundant mocha dev-dependency (it ships with @iobroker/testing) — E0063; the CI adapter-tests job now declares needs: check-and-lint — E3014
• (Tobias Hanss) Lint-config cleanup: dropped .prettierignore in favour of // prettier-ignore markers on the datapoint tables — W0084/W5048. No functional change

0.0.12 (2026-06-28)

• (Tobias Hanss) Resilient startup: a failed serial open no longer terminates the adapter — it stays alive, sets info.connection=false and retries
• (Tobias Hanss) Polling reworked to a setTimeout-at-end-of-tick scheme so poll ticks can never overrun or pile up in the wire queue, even under sustained communication failure
• (Tobias Hanss) validateConfig() now validates and safely clamps the user-configurable timeouts/gaps (responseTimeoutMs, setCommandGapMs, sendMaxRetries) to the Node.js timer ceiling
• (Tobias Hanss) info channel name fully translated (all 11 languages); setup help texts clarified
• (Tobias Hanss) Documentation: folded the install notes into the README and removed the separate INSTALL.md
• (Tobias Hanss) Tooling: adopted the standard ioBroker test-and-release workflow (testing-action-check / -adapter / -deploy) and migrated to @iobroker/eslint-config. No change to the heat-pump protocol

0.0.11 (2026-06-21)

• (Tobias Hanss) Object state roles for writable datapoints are now level instead of value (the value role requires write=false), fixing the repository checker's object-structure errors (E1011)
• (Tobias Hanss) State objects are now updated on upgrade (extendObject) so existing installations pick up the corrected roles
• (Tobias Hanss) Added the recommended i18n translations for the info.connection state name (W1001)

0.0.10 (2026-06-21)

• (Tobias Hanss) Published from CI with npm provenance (signed build attestation). No change to the adapter itself

0.0.9 (2026-06-21)

• (Tobias Hanss) CI: the release workflow's npm-publish step is now idempotent — it skips publishing when the version is already on npm, so a manual publish no longer makes the tagged release run fail. No change to the adapter itself

0.0.8 (2026-06-20)

• (Tobias Hanss) Maintenance for ioBroker repository acceptance: adapter-managed timers for clean shutdown, Node.js >=22 required, CI runs the adapter tests on Linux, Windows and macOS. No functional change to the heat-pump communication

0.0.7 (2026-05-30)

• (Tobias Hanss) Response-driven half-duplex bus: every send now waits for the heat pump's reply (or a timeout) before the next frame goes out, and retries up to 3 times on timeout or CRC error
• (Tobias Hanss) After a CRC error a randomised backoff precedes the next bus access to avoid lock-step collisions with a second master (Option-PCB)
• (Tobias Hanss) New "Diagnostics" setting toggles the set-command response logging (off by default)

0.0.6 (2026-05-30)

• (Tobias Hanss) Diagnostic logging to reverse-engineer the heat pump's SET acknowledgement: logs the sent frame and the heat pump's reply (frame type, timing, hexdump) at info level

0.0.5 (2026-05-30)

• (Tobias Hanss) Wire-queue gap is now enforced between every pair of sends, including across idle periods (previously the gap only applied while multiple tasks were already stacked in the queue — so polls and isolated sets bypassed it entirely)
• (Tobias Hanss) Queue is hard-capped at 100 pending entries; overflows are logged at warn level and the dropped send is skipped instead of silently piling up

0.0.3 (2026-05-26)

• (Tobias Hanss) Serialize all wire writes through a FIFO queue with a configurable inter-frame gap (default 200 ms). Fixes lost set commands when a script writes several datapoints at once
• (Tobias Hanss) Pump_Duty / Max_Pump_Duty unit removed (raw value 65-254, no physical unit)

0.0.2 (2026-05-25)

• (Tobias Hanss) Lower Node.js engine requirement to >= 20 (was 22) so the adapter installs on current ioBroker LTS hosts

0.0.1 (2026-05-25)

• (Tobias Hanss) Initial adapter release

License

MIT License

Copyright (c) 2026 Tobias Hanss t.dev@familie-hanss.de

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE DEALINGS IN THE SOFTWARE.