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ść.