BAVIS SDK: własny sterownik dla każdego urządzenia
Brakuje w BAVIS protokołu Twojego urządzenia? Dzięki publicznemu SDK napiszesz sterownik komunikacyjny w Pythonie, przetestujesz go bez sprzętu i zainstalujesz jako pakiet. Nie musisz czekać na nową wersję BAVIS.
Stan: SDK API 1.0 jest częścią BAVIS 3.1. Repozytorium BAVIS-SDK jest publiczne.
from bavis.sdk import Driver, DriverSpec, FieldSpec, require_host
class ScaleDriver(Driver):
def open(self):
self.link = connect(self.conn.host, self.conn.port)
def close(self):
self.link.close()
def poll(self):
return {t.name: self.link.read(t.address)
for t in self.tags}
SPECS = [DriverSpec(
kind="my_scale", label="My scale", transport="tcp",
default_port=4001, validate=require_host,
make=lambda conn, tags, sink, data_dir:
ScaleDriver(conn, tags, sink, data_dir),
check_address=lambda a, typ:
None if a.startswith("W") else "use W1, W2 …",
fields=(FieldSpec("station", "Station", "number"),),
)]
Dlaczego SDK
Sterownik jako pakiet, a nie ingerencja w rdzeń
SDK to stabilny publiczny interfejs dla sterowników tworzonych poza rdzeniem BAVIS: przez społeczność, integratorów albo przez nas na zamówienie jednego klienta.
Stabilne API
Pakiet, który importuje BAVIS tylko przez bavis.sdk, załaduje się także po kolejnej wersji głównej rdzenia, np. z 3.x na 4.x.
Bez nowego wydania
Sterownik to pakiet .bavispkg. Wgrywasz go w System → Projekty i pakiety i od razu działa we wszystkich projektach.
Testy bez sprzętu
bavis.sdk.testing uruchamia sterownik bez serwera BAVIS na symulowanym urządzeniu. Testy nigdy nie wymagają prawdziwego przyrządu.
Resztę robi rdzeń
Sterownik zwraca surowe wartości. Skalowanie, strefę martwą, historię, alarmy i ponowne łączenie obsługuje BAVIS.
Jak zacząć
Cztery kroki do własnego sterownika
Generator tworzy działający szkielet: sterownik prostego protokołu liniowego po TCP, symulowane urządzenie do testów i pliki tłumaczeń. Potem zamieniasz protokół na własny.
Wygeneruj szkielet
Pakiet bavis_drv_<nazwa> ze sterownikiem, testami i tłumaczeniami.
python -m bavis.tools.novy_modul driver my_scale \ --label "My scale" --balicek ~/driversNapisz protokół
Nadpisz open(), poll() i ewentualnie write(). Formularz połączenia opisujesz przez FieldSpec, adresy sprawdza check_address.
def poll(self): return {t.name: self.link.read(t.address) for t in self.tags}Przetestuj
Testy na symulowanym urządzeniu na porcie przydzielonym przez system. Działają równolegle i bez sprzętu.
cd ~/drivers python -m pytest -q testsZbuduj i zainstaluj
Build odrzuci uszkodzony moduł lub nieprawidłowy opis sterownika, a jeśli podasz klucz, podpisze pakiet. Potem wgrywasz go w System → Projekty i pakiety.
python -m bavis package build ~/drivers/bavis_drv_my_scale \ --out drv_my_scale-1.0.0.bavispkg --key key.pem
Pełna dokumentacja API, zasady wersjonowania i przykłady są po angielsku w repozytorium BAVIS-SDK. Teksty dla obsługi tłumaczysz w plikach i18n (czeski, angielski, niemiecki, słowacki, polski). Od wersji 4.0 każda instalacja (Windows, Linux, Docker) ma polecenie bavis sdk z krokami new, test, check i build – kod źródłowy rdzenia nie jest potrzebny, wystarczy bezpłatna edycja Lite lub Maker. github.com/Tomoash/BAVIS-SDK
Społeczność
Sterownik dla jednego, korzyść dla wszystkich
Kto napisze sterownik dla potrzebnego urządzenia, może udostępnić go innym. Wkład przyjmujemy w publicznym repozytorium BAVIS-SDK na GitHubie.
Zgłoś błąd lub zaproponuj sterownik
W GitHub Issues repozytorium BAVIS-SDK. Podaj urządzenie, protokół i link do dokumentacji producenta. Pytania i pomysły zamieszczaj w GitHub Discussions.
Otwórz IssuesWyślij pull request
Wkład jest na licencji Apache-2.0, a każdy commit podpisujesz zgodnie z DCO (git commit -s). Procedura jest w CONTRIBUTING.
Zobacz repozytoriumZgłaszaj podatności poufnie
Nie zgłaszaj luki bezpieczeństwa w Issues. Wyślij ją e-mailem zgodnie z SECURITY.md w repozytorium.
benesl@benesl-automation.czKatalog pakietów społeczności
Od BAVIS 4.0. Administrator wybiera w aplikacji zaufane źródła pakietów. Pakiet z katalogu zainstaluje się tylko wtedy, gdy zgadza się jego odcisk SHA-256, a instalacja zostanie zapisana w audycie. Pakiety, które zweryfikowaliśmy, mają nasz podpis i oznaczenie „zweryfikowano”.
Co przyniesie BAVIS 4.0Zasady dla sterowników
- Importuj BAVIS tylko z bavis.sdk i bavis.sdk.testing.
- Tylko biblioteki z licencją zgodną z Apache-2.0 (MIT, BSD, Apache). Bibliotek na GPL nie przyjmujemy.
- Mapy rejestrów i adresy według dokumentacji producenta, z odnośnikiem do niej.
- Bezpieczny zapis: nic do tagów tylko do odczytu, zapis wyłączony tam, gdzie zła wartość może uszkodzić urządzenie, i nigdy cyklicznie do flash lub EEPROM.
- Testy z symulowanym urządzeniem; żaden test nie może wymagać prawdziwego sprzętu.
Licencja Maker
BAVIS Maker: za darmo dla domu i warsztatu
Dla pasjonatów, majsterkowiczów i twórców sterowników. Edycja Maker, bezpłatna do użytku niekomercyjnego, ukazała się wraz z wydaniem poprawkowym BAVIS 3.1.1.
- logika, skrypty i obliczenia, harmonogramy czasowe i zarządzanie energią
- protokoły dla inteligentnego domu i opomiarowania: KNX, M-Bus, wM-Bus, HTTP / REST, Home Assistant i inne
- protokoły podstawowe każdej edycji: Modbus, Siemens S7, klient OPC UA i MQTT
Jak działa Maker
Maker włączasz bezpośrednio w aplikacji, bez pliku licencji. Instalacja regularnie zgłasza się potem do BAVIS Central z danymi zbiorczymi: wersje, liczby i używane sterowniki. Nigdy nie wysyła wartości ani nazw tagów.
Użycie komercyjne wymaga licencji Standard, nawet przy małym projekcie. Mniejsze projekty niekomercyjne do 150 tagów obejmuje bezpłatna edycja Lite.
Pytania
Częste pytania o SDK
Czym jest BAVIS SDK?
Publiczny interfejs w Pythonie dla sterowników komunikacyjnych webowej SCADA BAVIS. Sterownik dostarcza się jako pakiet .bavispkg i instaluje bez nowej wersji BAVIS.
Czy mój sterownik zadziała też w BAVIS 4?
Tak, jeśli importuje BAVIS tylko przez bavis.sdk. Nowa wersja główna SDK pojawi się tylko z nową wersją główną rdzenia, a poprzednia pozostanie wspierana co najmniej przez jedno wydanie z długoterminowym wsparciem.
Czy muszę opublikować swój sterownik?
Nie. Pakietu możesz używać tylko we własnych instalacjach. Wkład do publicznego repozytorium BAVIS-SDK jest dobrowolny, na licencji Apache-2.0.
Czy instalacja cudzego pakietu jest bezpieczna?
Kod pakietu działa w procesie BAVIS z takimi samymi uprawnieniami jak rdzeń, dlatego instaluj tylko pakiety, którym ufasz. W wersji 3.1 niepodpisany pakiet zainstaluje się tylko w trybie deweloperskim. Od wersji 4.0 administrator zainstaluje niepodpisany sterownik społeczności tylko po potwierdzeniu „na własne ryzyko”, haśle i podaniu powodu (podpis elektroniczny), a instalacja zostanie zapisana w rejestrze operacji. Instalację niepodpisanych sterowników administrator może całkowicie wyłączyć.
Od kiedy dostępne są SDK i licencja Maker?
SDK jest częścią BAVIS 3.1, licencja Maker ukazała się wraz z wydaniem poprawkowym 3.1.1. Aktywujesz ją w aplikacji w System → Licencja → BAVIS Maker. W repozytorium BAVIS-SDK możesz śledzić prace i zgłaszać pomysły.
Napiszecie sterownik za mnie?
Tak, na zamówienie. Wyślij nam urządzenie, protokół i dokumentację producenta, a odezwiemy się z propozycją.
Współpraca
Piszesz sterownik albo integrujesz BAVIS?
Chętnie pomożemy z projektem sterownika, protokołem i pakietem. Integratorom pomożemy przy pierwszym projekcie.
SDK jest częścią BAVIS 3.1, licencja Maker obowiązuje od wydania poprawkowego 3.1.1. Siemens i S7 są znakami towarowymi Siemens AG.