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