API systemu Bero – ogrzewanie w inteligentnym domu

Jakiś czas temu zainstalowałem u siebie w domu polski system sterowania ogrzewaniem, który już opisywałem. Bero, bo o nim mowa, zrobił na mnie bardzo pozytywne wrażenie swoją prostotą, a jednocześnie wszechstronnością i kompletnością. Jednak to, co mi się najbardziej spodobało, to możliwości integracji z systemami automatyki domowej przez API. Dzięki temu interfejsowi przetestowałem system Bero, a także dołączyłem dane z jego czujników do pomiarów zbieranych z innych źródeł. Znamy już metody łączenia z centralką systemu ogrzewania, wiemy jak pobrać dane z wybranych rejestrów. Przyszła pora na rozwinięcie tematu o analizę dalszych danych, ale także o ich modyfikację. Dzięki API bez problemu będziemy mogli, dla każdego z pomieszczeń, zarówno zmienić harmonogram ogrzewania, jak i przestawić na jakiś czas zadaną temperaturę. Jednym słowem – mieć pełną kontrolę nad ogrzewaniem domu.

Łączenie z centralką Bero

Co prawda temat już częściowo opisywałem, jednak przypomnę w skrócie najważniejsze rzeczy i rozszerzę wiadomości. Do komunikacji służy protokół HTTP, a do autentykacji metody Basic Auth, w której login i hasło kodowane są algorytmem Base64. Dane do logowania dla trzech podstawowych użytkowników (root, admin, user) znajdziemy w panelu po zalogowaniu na stronie myBero.com lub w aplikacji myBero. Na API składają się 4 adresy, które możemy wywołać:

  • /getregister.cgi – służy do pobierania wybranych rejestrów (jak wersja oprogramowania, aktualna temperatura, zadana temperatura, harmonogram ogrzewania)
  • /setregister.cgi – pozwala ustawić wartości wybranych rejestrów (np. zmienić zadaną temperaturę pomieszczenia)
  • /syncvalues.cgi – prezentuje wartości wszystkich rejestrów w formie tekstu rozdzielonego średnikami
  • /getdevices.cgi – zwraca plik XML z listą skonfigurowanych w systemie urządzeń

Do tej pory korzystaliśmy z getregister.cgi, który zwraca wartości w formie pliku XML. Jest to najbardziej praktyczny sposób, gdy potrzebujemy pobrać jedną lub kilka wartości. Dla cyklicznego sprawdzania stanu wszystkich rejestrów najlepsze będzie użycie skryptu syncvalues.cgi.

Urządzenia i rejestry

Wszystkie urządzenia w systemie Bero mają swoje identyfikatory, nazywane vid. Centralce zawsze przypisany jest numer 0. Kolejne czujniki temperatury mają numery 1 do 20, a od 21 rozpoczynają się głowice termostatyczne. Numery 71 do 78 zajmują przekaźniki, zaś 80 do 83 – listwy do ogrzewania podłogowego. W pokoju (numeracja od 100)  jest maksymalnie jeden czujnik temperatury i wilgotności, więc mapowanie czujnik-pokój jest 1:1, natomiast głowic dla pomieszczenia może być więcej, dlatego każda z głowic posiada przypisanie do pokoju (w rejestrze room_id). Jeden przekaźnik może być wymagany do ogrzewania wielu pokoi, a jednocześnie żeby ogrzewać pokój może istnieć potrzeba uruchomienia wielu przekaźników, więc informacja o powiązanych przekaźnikach znajduje się na poziomie pokoju (w rejestrze relays). Analogicznie sytuacja wygląda z listwami do ogrzewania podłogowego (rejestry hb0 i hb1).

Każdy z rodzajów urządzeń ma przypisany zestaw rejestrów. To czy, możemy go tylko odczytywać, czy także modyfikować, zależy po pierwsze od typu rejestru (są takie tylko do odczytu), jak i od uprawnień (użytkownika, na którego jesteśmy zalogowani). Zestaw rejestrów jest szeroki, ale postaram się przedstawić najważniejsze z nich.

Rejestry centralki

Tylko do odczytu:

  • device_sn – numer seryjny urządzenia
  • device_type – typ urządzenia
  • device_soft_version – wersja oprogramowania
  • device_hard_version – wersja sprzętu
  • accesslevel – aktualny poziom dostępu (od 0 – root, do 2 – user)
  • eth_iface – stan połączenia z siecią ethernet (1 – połączono, 0 – nie połączono)
  • remote_server_status – status połączenia z serwerem Bero (3 – połączony poprawnie)

Modyfikowalne:

  • device_name – nazwa urządzenia
  • device_location – lokalizacja geograficzna urządzenia
  • auth_root – dane autoryzacyjne użytkownika root, w formacie Base64 (root:hasło)
  • auth_admin – dane autoryzacyjne użytkownika admin, w formacie Base64 (admin:hasło)
  • auth_user – dane autoryzacyjne użytkownika user, w formacie Base64 (user:hasło)
  • datetime – aktualny czas (timestamp)
  • localtimezone – strefa czasowa
  • eth_mac – MAC adres urządzenia (tak, można zmienić)
  • eth_ip – adres IP
  • eth_mask – maska podsieci
  • eth_mask – adres bramy sieciowej
  • eth_dhcp – włączenie (1) lub wyłączenie (0) pobierania adresu IP przez DHCP
  • trv_calib_day – dzień tygodnia kalibracji głowic
  • trv_calib_hour – godzina kalibracji głowic
  • trv_mode – tryb pracy (0 – normalny, 1 – zawsze otwarte, 2 – zawsze zamknięte)
  • wnd_hist – spadek temperatury dla wykrycia otwartego okna
  • wnd_time – czas zamknięcia głowic po wykryciu otwartego okna
  • wnd_cfg – lista pomieszczeń, w których aktywna jest funkcja wykrywania otwartego okna (pokoje jako kolejne bity liczby)

Rejestry czujników wilgotności i temperatury

Tylko do odczytu:

  • temp – aktualna temperatura
  • rh – aktualna wilgotność
  • alarm – alarmy czujnika (kolejne bity od 1: niski stan baterii, brak komunikacji, błąd czujnika temperatury, błąd czujnika wilgotności)
  • bat – poziom napięcia baterii
  • sig – poziom sygnału

Rejestry głowic

Tylko do odczytu:

  • vtemp – temperatura odczytana przez czujnik na głowicy
  • vpos – pozycja głowicy
  • vpos_min – minimalna pozycja głowicy według kalibracji
  • vpos_range – maksymalny ruch głowicy (od vpos_min) według kalibracji
  • room_id – przypisanie głowicy do pokoju
  • bat – poziom napięcia baterii
  • sig – poziom sygnału
  • alarm – alarmy głowicy (kolejne bity od 1: niski stan baterii, brak komunikacji, różne błędy sprzętowe)

Rejestry przekaźników

Tylko do odczytu:

  • pkst – stan przekaźnika (1 – włączony, 0 – wyłączony)
  • sig – poziom sygnału
  • alarm – alarmy przekaźnika

Rejestry modyfikowalne:

  • name – nazwa przekaźnika

Rejestry listew do ogrzewania podłogowego

Tylko do odczytu:

  • outs – stan wyjść listwy (jako kolejne bity liczby)
  • sig – poziom sygnału
  • alarm – alarmy listwy

Modyfikowalne:

  • name – nazwa listwy

Rejestry pomieszczeń

Tylko do odczytu:

  • heat – grzanie (0 – wyłączone, 1 – załączone), ustalane na podstawie zapotrzebowania na podwyższenie temperatury
  • temp – temperatura zadana pomieszczenia

Modyfikowalne:

  • t_lo – wartość temperatury ekonomicznej (zielonej)
  • t_norm – wartość temperatury komfortowej (zółtej)
  • t_hi – wartość temperatury komfortowej plus (czerwonej)
  • temp_pre – aktualna temperatura zadana (0 – ochrony, 1 – ekonomiczna, 2 – komfort, 3 – komfort plus, +4 – temperatura zablokowana na stałe, +16 – temperatura zblokowana na godzinę, +32 – temperatura zablokowana na 2 godziny)
  • tbl – harmonogram ogrzewania – ciąg znaków składający się z liczb w zapisie szesnastkowym, o formacie napiszę później
  • relays – konfiguracja przekaźników potrzebnych do ogrzania pomieszczenia (kolejne bity liczby jako maska)
  • hb0 – konfiguracja wyjść listew ogrzewania podłogowego potrzebnych do ogrzania pomieszczenia – listwy 1 i 2 (kolejne bity liczby 32-bitowej jako maska)
  • hb1 – konfiguracja wyjść listew ogrzewania podłogowego potrzebnych do ogrzania pomieszczenia – listwy 3 i 4 (kolejne bity liczby 32-bitowej jako maska)
  • enable – czy pokój jest skonfigurowany w systemie, a jeżeli tak, to w jakiej kolejności pojawi się na liście  (0 – nie, liczba od 100 wzwyż – priorytet)
  • name – nazwa pokoju
  • alarm – alarmy pomieszczenia (1 – wykryto otwarcie okna)

Harmonogram ogrzewania

Rejestr tbl, dostępny na poziomie pomieszczenia, zawiera harmonogram ogrzewania. Jest to ciąg znaków, w zapisie szesnastkowym, określających ustawienia kolejnych godzin harmonogramu, poczynając od północy z niedzieli na poniedziałek, czyli od początku tygodnia. Każda liczba (2 znaki) odnoszą się do przedziału dwugodzinnego. Mniej znaczące 4 bity (czyli drugi znak) określają pierwszą godzinę, a bardziej znaczące (czyli pierwszy znak) – drugą. Mając dane dla godziny – mniej znaczące 2 bity oznaczają stan w pierwszej połówce godziny, a bardziej znaczące – w drugiej. Otrzymując 2-bitową liczbę możemy określić stan ogrzewania dla konkretnego pół godziny: 0 – temperatura ochrony, 1 – ekonomiczna, 2 – komfortowa, 3 – komfortowa plus.

Skomplikowane? Proste, tylko wytłumaczenie było może trochę złożone. Posłużmy się więc przykładem. Weźmy pierwsze dwa znaki harmonogramu, odpowiadające za okres od północy do drugiej w nocy w poniedziałek, czyli 2 godziny. Gdy mamy np. 01, pierwszy znak odpowiada okresowi od godziny 1 do 2. Jest 0, więc przez całą godzinę mamy temperaturę ochrony. Drugi znak – od północy do godziny pierwszej – 1, czyli binarnie 00 01, czyli 0 i 1. Więc dla przedziału czasu 0:00 do 0:30 mamy temperaturę ekonomiczną, a dla 0:30 do 1:00 – ochrony.

Inny przykład – 79, czyli | 01 11 | 10 01 |. Pierwszy znak oznacza drugą godzinę (1:00-2:00). Jest to 7, czyli 01 11, czyli 1:00-1:30 mamy komfort plus (3, czyli 11), a dla 1:30-2:00 – ekonomiczną (1, czyli 01). W kolei dla pierwszej godziny mamy 9, więc 10 01, co przekłada się na ekonomiczną (1) od 0:00 do 0:30 i komfortową od 0:30 do 1:00.

Pobieranie danych rejestrów

Dane rejestrów pobieramy dzięki zapytaniu do skryptu getregister.cgi, czyli łącząc się przez http z adresem:

http://adres_centralki/getregister.cgi?parametry

Na parametry składa się lista par – numer_urządzenia@rejstr, rozdzielonych znakami &. Przykładowo, dla pobrania aktualnej zadanej temperatury dla pokoi 100 i 101, wywołujemy zapytanie:

/getregister.cgi?100@temp&101@temp

Jako odpowiedź zwracany jest plik XML:

<cmd status="ok"><device id="0">
<reg vid="100" tid="temp" v="7.00" min="0.00" max="0.00"/>
<reg vid="101" tid="temp" v="7.00" min="0.00" max="0.00"/>
</device></cmd>

Modyfikacja rejestrów

Zmiana wartości rejestrów jest bardzo podobna do odczytu, tylko dodajemy dla każdego z nich znam równości i wartość. Przykładowo dla zmiany ustawień temperatury na ekonomiczną w pokojach 100 i 101 wywołamy zapytanie:

/setregister.cgi?100@temp_pre=1&101@temp_pre=1

W odpowiedzi zostanie zwrócony plik XML ze statusem i nowymi wartościami:

<cmd status="ok"><device id="0">
<reg vid="100" tid="temp_pre" v="1" status="ok"/>
<reg vid="101" tid="temp_pre" v="1" status="ok"/>
</device></cmd>

Wszystkie rejestry razem

Do pobrania wszystkich danych za jednym razem służy skrypt /syncvalues.cgi, który zwraca plik zawierający w kolejnych liniach stan poszczególnych urządzeń. Wartości w linii rozdzielone są średnikami. Jako pierwszy podany jest identyfikator urządzenia, następnie następuje znacznik czasu ostatniej komunikacji z urządzeniem (pamiętajmy, że jest to system radiowy, a dla oszczędności energii komunikacja nie jest ciągła), a następnie rejestry w formacie rejestr:wartność. Poza rejestrami opisanymi powyżej przekazywane są także dodatkowe wartości zmiennych s i t, które zawierają informacje czy urządzenie jest zdefiniowane w systemie i jaki jest jego typ (model).

Podsumowanie

Powyższe wiadomości wystarczą do pełnej integracji systemu sterowania ogrzewaniem Bero z inteligentnym domem. Scenariuszy integracji może być wiele. Zwykle sprowadzają się do dwóch rzeczy – odczytu stanu systemu ogrzewania i wykorzystania informacji w automatyce domowej oraz ustawiania stanu ogrzewania na podstawie informacji pochodzących z systemu domowego. Możemy więc zarówno wykorzystywać dane z czujników temperatury i wilgotności Bero, jak i np. sterować temperaturą w domu na podstawie informacji o obecności mieszkańców w domu czy wcześniej dostosowywać stan ogrzewania (szczególnie podłogowego) do prognozy pogody.

Gdy będzie zainteresowanie, w kolejnych tekstach mogę omówić praktyczną stronę integracji Bero z systemem alarmowym Satel Integra i moim „inteligentnym domem”. Mam nadzieję, że te informacje pomogą wszystkim, którzy chcą używać API Bero, niezależnie od tego, z jakim systemem chcą połączyć sterownik ogrzewania. Liczę, że ten wpis znajdą też osoby, które dopiero szukają systemu sterowania ogrzewaniem do swojego inteligentnego domu, a opis API pozwoli im poznać możliwości systemu. Bo, w mojej ocenie, to właśnie API powoduje, że Bero jest najbardziej wszechstronnym systemem na rynku. W integracji różnych systemów, automatyzacji i centralnym zarządzaniu jest przyszłość.

Ten wpis został opublikowany w kategorii Inteligentny Dom i oznaczony tagami , , , . Dodaj zakładkę do bezpośredniego odnośnika.

10 odpowiedzi na API systemu Bero – ogrzewanie w inteligentnym domu

  1. Paweł Ł. pisze:

    Hmm.. To wszystko wygląda na dość skomplikowane dla takiego szarego człowieka jak ja ;P

    • techniczny pisze:

      Dla kogoś patrzącego z boku, nie mającego doświadczeń z programowaniem, pewnie tak. Ale jak ktoś nie buduje sam swojego systemu inteligentnego domu, to API jest mu potrzebne wyłącznie dla nabycia świadomości, że w przyszłości system ogrzewania da się dowolnie rozszerzać i rozbudowywać. Natomiast do tego czasu w pełni wystarczą funkcje przewidziane przez projektantów Bero.

  2. Paweł pisze:

    System Bero wydaje się być ciekawym rozwiązaniem. Czy masz może jakieś doświadczenia z powiązaniem go z Domoticzem? PS. Liczę, że jednak doczekamy się w końcu postu, odnośnie powiązania systemu Bero z systemem alarmowym Satela. Czekam z niecierpliwością 🙂

    • techniczny pisze:

      Niestety nie mam doświadczenia z Domoticzem. Skończył nam się sezon grzewczy i ostatnio cierpię na brak czasu, natomiast z pewnością wrócimy do tematu Satela i Bero.

  3. Piotr pisze:

    Witam,

    wykorzystuję głowice grzejnikowe oraz czujniki temperatury i wilgotności BERO wraz ze sterownikiem kotła CO BRULI. Oprócz tego przez API łączę się z home assistant dzięki informacją zawartym na techniczny 🙂 (WIELKIE DZIĘKI)

    … do pełni szczęścia brakuje mi jeszcze możliwości zmiany zakresów napięć przy którym głowica wyłącza sterowanie – obecnie jest to ok 2,5V, czyli zakładam, że zakres 0%-100% odpowiada (2,5 do 3 V). Niestety napięcie 2,5V odpowiada ok 1,25V na jedną baterię, a to z kolei jest normalne napięcie dla akumulatorków Ni-MH. Przy pełnym naładowaniu akumulatorków Ni-MH poziom baterii pokazywany jest na ok 30% i dość szybko spadają do 0% a akumulatorki mają jeszcze ok 60-70% zmagazynowanej energii.

    Moje pytania są następujące:

    1. czy znasz możliwość programowej zmiany zakresu pomiarowego poziomu baterii 0-100% odpowiadającego np. napięciu 2-2,5V?
    2. czy zastosowane układy elektroniczne są w stanie pracować na tak niskim napięciu (większość procesorów od 1,8V – spokojnie) i układ wykonawczy ( tutaj nie wiem jaki silniczek jest zastosowany)?

    Jeżeli powyższe jest możliwe to bardzo prosiłbym o krótką instrukcję – jak znasz lub o kontakt z Gośćmi od BERO.
    Jeżeli wymagało by to zmiany jakiegoś rezystora SMD z dzielnika pomiarowego to jestem w stanie to wykonać bez problemu (proszę tylko o info który to rezystor i na jaki go wymienić) lub wycinek schematu z obwodem pomiarowym to sam go dobiorę ( bo zakładam, że całego schematu nie dadzą).
    Jeżeli wymagało by to zmiany kodu źródłowego – to fajnie by było jakby BERo zmieniło to i przesłali plik wsadowy.

    za pomoc w rozwiązaniu problemu z góry bardzo dziękuję i pozdrawiam

    Piotr

    • Anonim pisze:

      Cześć Piotr,
      czy możesz podać jak skonfigurowałeś HA z Bruli? dokładniej to chodzi mi o wyciągniecie danych z głowicy th2 i czujnika temp.

      Pozdrawiam
      Maciej

  4. Bero & DS18b20 pisze:

    Witam,
    dosyć późno znalazłem ten świetny blog, ponieważ od pewnego czasu rozglądam się za komponentami do zbudowania inteligentnego systemu sterowania ogrzewaniem domu – głównie głowice termostatyczne sterowane i jakaś centralka która odczytywała by ich stan i wysyłała „włącz ogrzewanie” do pieca, a z drugiej strony możliwa byłaby integracja z moim istniejącym systemem, bardzo zainteresował mnie temat Bero i jego możliwości, w związku z tym chciałbym zapytać czy po tych kilku latach w dalszym ciągu jesteś zadowolony z systemu Bero ? jak sprawują się głowice termostatyczne – głównie pod względem mechanicznym ? Czy jest możliwość odczytywania przez Bero „moich” czujników temperatury (DS18B20) rozmieszczonych w pokojach ? Mam jeszcze kilka innych pytań ale może narazie tyle…
    Mam nadzieję, że znajdziesz kilka chwil żeby odpowiedzieć na moje pytania.
    Pozdrawiam
    Florian.

    • techniczny pisze:

      Tak, nadal jestem zadowolony, a w różnych miejscach przetestowałem kilka różnych głowic. Bero po prostu działa – bez awarii, bez problemów, tak jak się uruchomiło. Tańszą alternatywą są głowice bluetooth Eqiva, ale wygoda, obsługa, zasięg i kultura pracy odstają od Bero. Innym pomysłem mogą być coraz popularniejsze tanie głowice na Zigbee, ale tu z kolei bardzo dużo osób zgłasza nieakceptowalnie częste wymiany baterii. Przyglądam się temu, ale na pewno nie jest to tak bezobsługowe jak Bero.

  5. PHA pisze:

    Witaj
    jak skonfigurowałeś HA z BERO?

Dodaj komentarz

Twój adres e-mail nie zostanie opublikowany. Wymagane pola są oznaczone *