Casambi API to interfejs programistyczny, który pozwala łączyć sieci oświetleniowe Bluetooth Mesh z zewnętrznymi aplikacjami, dashboardami i systemami zarządzania budynkami (BMS). Jeśli szukacie sposobu na integrację sterowania oświetleniem Casambi z istniejącą infrastrukturą IT, ten przewodnik wyjaśnia architekturę API, dostępne metody komunikacji i praktyczne scenariusze wdrożenia.
Platforma deweloperska jest dostępna pod adresem developer.casambi.com.
Casambi API opiera się na dwóch mechanizmach komunikacji, z których każdy pełni inną rolę w architekturze systemu.
REST API – operacje synchroniczne
REST API służy do pobierania statycznych informacji o sieci. Za jego pomocą można odczytać konfigurację sieci i listę urządzeń, pobrać dane z czujników i liczników energii, aktywować sceny oświetleniowe oraz uzyskać dane historyczne (datapoints) zebrane przez bramkę sieciową.
Wymiana danych odbywa się w formacie JSON, co ułatwia parsowanie odpowiedzi w dowolnym języku programowania.
WebSocket – komunikacja w czasie rzeczywistym
Usługa WebSocket zapewnia dwukierunkową komunikację o niskim opóźnieniu. Programiści mogą za jej pomocą odbierać zdarzenia o zmianach stanu urządzeń w momencie ich wystąpienia, wysyłać polecenia sterujące (dimming, zmiana temperatury barwowej, aktywacja scen) i monitorować sieć bez konieczności odpytywania REST API.
Połączenie między bramką a chmurą jest zabezpieczone protokołem TLS. Cała komunikacja odbywa się przez HTTPS i WSS (Web Services Security).
Uzyskanie dostępu do API
Korzystanie z Casambi API wymaga ważnego klucza deweloperskiego (API key). Klucz można uzyskać kontaktując się z Casambi Support pod adresem support@casambi.com. Dostępność kluczy jest obecnie ograniczona – Casambi przyznaje je po weryfikacji projektu.
Po otrzymaniu klucza programiści mogą testować żądania w konsoli REST API pod adresem developer.casambi.com/console.
Typy sesji
API obsługuje dwa typy sesji uwierzytelniających:
Sesja użytkownika (Site account) – daje dostęp do wszystkich sieci i danych powiązanych z danym kontem. Przydatna dla integratorów zarządzających wieloma instalacjami.
Sesja sieciowa (Network admin) – ogranicza dostęp do jednej konkretnej sieci. Odpowiednia dla rozwiązań dedykowanych do pojedynczego obiektu.
Bramka sieciowa – wymaganie dla zdalnego dostępu
Zdalny dostęp do sieci Casambi przez API wymaga aktywnej bramki (gateway), która łączy lokalną sieć Bluetooth Mesh z chmurą Casambi Cloud.
Dostępne opcje bramki to: Casambi Cloud Gateway – dedykowane urządzenie z łącznością Ethernet i Wi-Fi, które musi być zasilone i znajdować się w zasięgu Bluetooth sieci; smartfon lub tablet z aplikacją Casambi skonfigurowany jako bramka, działający z aktywnym połączeniem internetowym i uruchomioną aplikacją; a także bramki Ethernet z ekosystemu Casambi, które umożliwiają integrację lokalną bez przesyłania danych do chmury.
Sieć musi być udostępniona w trybie Admin only lub Password protected – bramka nie zadziała na sieciach Open lub Not shared. Sieci Classic nie obsługują opcji Cloud Gateway ani Casambi Gateway (Beta).
Co można zrobić z API
Interfejs programistyczny otwiera szereg możliwości integracyjnych.
W zakresie sterowania oświetleniem API pozwala na włączanie i wyłączanie opraw, regulację jasności (0-100%), kontrolę temperatury barwowej (Tunable White), sterowanie kolorem RGB/RGBW oraz aktywację wcześniej zaprogramowanych scen.
Pod kątem monitoringu możliwy jest odczyt stanu urządzeń w sieci, pobieranie danych z czujników obecności i światła dziennego, monitorowanie liczników energii (w urządzeniach, które to wspierają), a także dostęp do danych diagnostycznych z urządzeń DALI/D4i.
API umożliwia również tworzenie niestandardowych dashboardów webowych i aplikacji mobilnych, integrację z systemami zarządzania budynkami (BMS) oraz zarządzanie wieloma sieciami z jednego punktu dostępowego.
Zbieranie danych (Data Collection)
Bramka sieciowa może zbierać i przesyłać do chmury dwa rodzaje danych. Dane z czujników (Sensor data) obejmują sygnały obecności/nieobecności, odczyty natężenia oświetlenia (lux), temperaturę, poziom baterii i wskaźniki przeciążenia. Dane o użytkowaniu urządzeń (Usage of devices) obejmują status urządzenia w sieci, parametry sterowania (dimming, CCT, kolor), liczniki energii i rozszerzoną diagnostykę urządzeń DALI.
Zbieranie danych zwiększa ruch w sieci mesh i może spowolnić jej działanie, dlatego Casambi zaleca włączanie tych opcji tylko wtedy, gdy są faktycznie potrzebne.
Integracja z systemami budynkowymi
BMS – przez Cloud API lub Ethernet Gateway
Sieci Casambi mogą komunikować się z systemami zarządzania budynkami na dwa sposoby. Pierwszy to Cloud API – integracja przez chmurę z wykorzystaniem REST API i WebSocket. Drugi to Ethernet Gateway – lokalna integracja z protokołami BACnet, MQTT, TCP/IP, Artnet i KNX, bez konieczności wysyłania danych do chmury.
Druga ścieżka jest szczególnie istotna w obiektach, gdzie polityka bezpieczeństwa zabrania przesyłania danych operacyjnych poza siedzibę. Bramki Ethernet z ekosystemu Casambi umożliwiają pełną integrację z BMS przy zachowaniu lokalności danych.
Warto podkreślić: BACnet, MQTT i inne protokoły budynkowe nie są natywną częścią Casambi API – są dostępne przez bramki Ethernet od partnerów ekosystemowych lub przez bezpośrednie podłączenie wyjść przekaźnikowych modułu BMS do sterowników Casambi ze wejściem przełącznikowym.
Home Assistant – integracja społecznościowa
Platforma Home Assistant może być zintegrowana z Casambi przez nieoficjalną integrację dostępną na GitHub (home_assistant_casambi). Integracja bazuje na bibliotece aiocasambi – asynchronicznej bibliotece Python do komunikacji z Casambi Cloud. Wykorzystuje REST API do pobierania informacji o sieci i urządzeniach oraz WebSocket do odbierania zmian stanu.
Po skonfigurowaniu system automatycznie wykrywa urządzenia w sieci Casambi. Obsługiwane są podstawowe funkcje: włączanie/wyłączanie, regulacja jasności i kontrola temperatury barwowej.
Wymagania to ważny klucz API od Casambi oraz aktywna bramka sieciowa z połączeniem internetowym. To integracja społecznościowa, nie oficjalnie wspierana przez Casambi – ale aktywnie rozwijana i wykorzystywana przez użytkowników Home Assistant.
Platformy partnerskie w ekosystemie Casambi
Ekosystem Casambi obejmuje partnerów oferujących platformy rozszerzające możliwości API o dodatkowe funkcje zarządzania i raportowania.
Adquio
Adquio to platforma kontrolerów i oprogramowania, która integruje się z Casambi Cloud API. Oferuje dwukierunkowy interfejs RESTful hostowany w chmurze, dostęp do danych z wielu sieci Casambi w czasie rzeczywistym oraz integrację z protokołami DALI, Modbus, BACnet i MQTT. Adquio jest oficjalnym partnerem w ekosystemie Casambi.
pushfusion
pushfusion to platforma chmurowa do zarządzania flotą instalacji oświetleniowych. Łączy się z sieciami Casambi przez Cloud API i oferuje agregację danych z wielu lokalizacji, raportowanie zużycia energii, proaktywne alerty o problemach oraz wsparcie dla oświetlenia awaryjnego (emergency lighting). pushfusion był nominowany do Casambi Awards 2022.
Bezpieczeństwo API
Casambi stosuje wielowarstwowe mechanizmy bezpieczeństwa obejmujące wszystkie kanały komunikacji w systemie.
Na poziomie szyfrowania system wykorzystuje AES-128 (szyfr symetryczny), AES-CMAC (uwierzytelnianie integralności danych), ECDH (wymiana kluczy na krzywych eliptycznych – nowy klucz dla każdego połączenia) oraz ECDSA (podpisy cyfrowe na krzywych eliptycznych).
Komunikacja bramka-chmura jest zabezpieczona protokołem TLS, a wszystkie żądania API przechodzą przez HTTPS i WSS.
Casambi posiada certyfikat cyberbezpieczeństwa ioXt Alliance, a usługi chmurowe są hostowane na platformie Microsoft Azure.
Dodatkowo system stosuje ochronę przed atakami typu replay (kody kroczące i dwukierunkowe uwierzytelnianie między urządzeniami), podsłuchem (pełne szyfrowanie – komunikacja unit-to-unit jest niemożliwa do odszyfrowania nawet dla administratorów sieci) oraz man-in-the-middle (dwukierunkowe uwierzytelnianie mobile-unit i unit-unit).
Przykłady zastosowań API
Oświetlenie komercyjne
W sieciach handlowych API pozwala synchronizować oświetlenie z harmonogramami pracy sklepów i automatycznie przełączać sceny w zależności od pory dnia. W biurach możliwa jest integracja z systemami rezerwacji sal i automatyczne sterowanie w oparciu o dane z czujników obecności. W hotelach API umożliwia centralne zarządzanie oświetleniem przestrzeni wspólnych z poziomu dashboardu.
Monitoring i raportowanie
Przez API można zbierać dane o statusie urządzeń z wielu lokalizacji jednocześnie, generować alerty o awariach i nieprawidłowościach, analizować zużycie energii w czasie rzeczywistym, a także pobierać dane diagnostyczne D4i z opraw LED wyposażonych w kompatybilne drivery.
Retrofit i modernizacja
Istniejące instalacje oświetleniowe można rozbudować o funkcje IoT bez wymiany okablowania. Dodanie sterowników Casambi do istniejących opraw i podłączenie bramki sieciowej otwiera dostęp do API – a tym samym do zdalnego monitoringu, automatyzacji i integracji z BMS.
W instalacjach z istniejącą infrastrukturą DALI, bramy DALI Casambi pozwalają połączyć tradycyjne sterowanie przewodowe z bezprzewodową siecią mesh i chmurą.
Podsumowanie
Casambi API (REST + WebSocket) umożliwia integrację oświetlenia Bluetooth Mesh z systemami BMS, platformami IoT i niestandardowymi aplikacjami. Kluczowym wymaganiem jest aktywna bramka sieciowa i klucz deweloperski od Casambi.
Jeśli planujecie projekt wymagający integracji Casambi z istniejącą infrastrukturą budynkową, skontaktujcie się z nami – pomożemy dobrać odpowiednie komponenty i zaprojektować architekturę sieci.
Lightworks – Value-Added Reseller Casambi w Polsce Tel: +48 514 327 427 · Email: hello@lightworks.com.pl · lightworks.com.pl/kontakt/
