BAVIS SDK: vlastní driver pro každé zařízení
Chybí v BAVIS protokol vašeho zařízení? S veřejným SDK napíšete komunikační driver v Pythonu, otestujete ho bez hardwaru a nainstalujete jako balíček. Na novou verzi BAVIS čekat nemusíte.
Stav: SDK API 1.0 je součástí BAVIS 3.1. Repozitář BAVIS-SDK je veřejný.
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"),),
)]
Proč SDK
Driver jako balíček, ne jako zásah do jádra
SDK je stabilní veřejné rozhraní pro drivery, které vznikají mimo jádro BAVIS: v komunitě, u integrátorů nebo u nás na zakázku pro jednoho zákazníka.
Stabilní API
Balíček, který importuje BAVIS jen přes bavis.sdk, se načte i po další hlavní verzi jádra, třeba z 3.x na 4.x.
Bez nového vydání
Driver je balíček .bavispkg. Nahrajete ho v Systém → Projekty a balíčky a hned funguje pro všechny projekty.
Testy bez hardwaru
bavis.sdk.testing spustí driver bez serveru BAVIS proti falešnému zařízení. Testy nikdy nepotřebují skutečný přístroj.
Zbytek udělá jádro
Driver vrací surové hodnoty. Škálování, mrtvé pásmo, historii, alarmy a znovupřipojení řeší BAVIS.
Jak začít
Čtyři kroky k vlastnímu driveru
Generátor připraví funkční kostru: driver pro jednoduchý řádkový protokol přes TCP, falešné zařízení pro testy a soubory překladů. Protokol pak vyměníte za ten svůj.
Vygenerujte kostru
Balíček bavis_drv_<název> s driverem, testy a překlady.
python -m bavis.tools.novy_modul driver my_scale \ --label "My scale" --balicek ~/driversNapište protokol
Přepište open(), poll() a případně write(). Formulář spojení popíšete pomocí FieldSpec, adresy kontroluje check_address.
def poll(self): return {t.name: self.link.read(t.address) for t in self.tags}Otestujte
Testy proti falešnému zařízení na portu, který přidělí systém. Běží paralelně a bez hardwaru.
cd ~/drivers python -m pytest -q testsSestavte a nainstalujte
Build odmítne rozbitý modul i neplatný popis driveru, a když mu dáte klíč, balíček podepíše. Pak ho nahrajete v Systém → Projekty a balíčky.
python -m bavis package build ~/drivers/bavis_drv_my_scale \ --out drv_my_scale-1.0.0.bavispkg --key key.pem
Celá reference API, pravidla verzí a příklady jsou anglicky v repozitáři BAVIS-SDK. Popisky pro obsluhu překládáte v souborech i18n (čeština, angličtina, němčina, slovenština, polština). Od verze 4.0 má každá instalace (Windows, Linux, Docker) příkaz bavis sdk s kroky new, test, check a build – zdrojový kód jádra nepotřebujete, stačí bezplatná edice Lite nebo Maker. github.com/Tomoash/BAVIS-SDK
Komunita
Driver pro jednoho, užitek pro všechny
Kdo napíše driver pro zařízení, které potřebuje, může ho nabídnout ostatním. Příspěvky přijímáme ve veřejném repozitáři BAVIS-SDK na GitHubu.
Nahlaste chybu nebo navrhněte driver
V GitHub Issues repozitáře BAVIS-SDK. Napište zařízení, protokol a odkaz na dokumentaci výrobce. Dotazy a nápady patří do GitHub Discussions.
Otevřít IssuesPošlete pull request
Příspěvky jsou pod licencí Apache-2.0 a každý commit podepíšete podle DCO (git commit -s). Postup je v CONTRIBUTING.
Zobrazit repozitářHlaste zranitelnosti neveřejně
Bezpečnostní chybu nepište do Issues. Pošlete ji e-mailem podle SECURITY.md v repozitáři.
benesl@benesl-automation.czKatalog komunitních balíčků
Od BAVIS 4.0. Správce si v aplikaci vybere důvěryhodné zdroje balíčků. Balíček z katalogu se nainstaluje, jen když sedí jeho otisk SHA-256, a instalace se zapíše do auditu. Balíčky, které jsme ověřili, nesou náš podpis a značku „ověřeno“.
Co přinese BAVIS 4.0Pravidla pro drivery
- BAVIS importujte jen z bavis.sdk a bavis.sdk.testing.
- Jen knihovny s licencí slučitelnou s Apache-2.0 (MIT, BSD, Apache). Knihovny pod GPL nepřijímáme.
- Mapy registrů a adresy podle dokumentace výrobce, s odkazem na ni.
- Bezpečný zápis: nic do tagů jen pro čtení, zápis vypnutý tam, kde může špatná hodnota poškodit zařízení, a nikdy cyklicky do flash nebo EEPROM.
- Testy s falešným zařízením, žádný test nesmí potřebovat skutečný hardware.
Licence Maker
BAVIS Maker: zdarma pro domácnost a dílnu
Pro nadšence, kutily a vývojáře driverů. Edice Maker zdarma pro nekomerční použití vyšla s opravným vydáním BAVIS 3.1.1.
- logika, skripty a výpočty, časové programy a energetický management
- protokoly pro chytrou domácnost a měření: KNX, M-Bus, wM-Bus, HTTP / REST, Home Assistant a další
- základní protokoly každé edice: Modbus, Siemens S7, klient OPC UA a MQTT
Jak Maker funguje
Maker zapnete přímo v aplikaci, bez licenčního souboru. Instalace se pak pravidelně ohlásí do BAVIS Central souhrnnými údaji: verze, počty a použité drivery. Hodnoty ani názvy tagů nikdy neodesílá.
Komerční použití potřebuje licenci Standard, i u malého projektu. Menší nekomerční projekty do 150 tagů pokryje bezplatná edice Lite.
Otázky
Časté otázky k SDK
Co je BAVIS SDK?
Veřejné rozhraní v Pythonu pro komunikační drivery webové SCADA BAVIS. Driver se dodává jako balíček .bavispkg a instaluje se bez nové verze BAVIS.
Bude můj driver fungovat i v BAVIS 4?
Ano, pokud importuje BAVIS jen přes bavis.sdk. Nová hlavní verze SDK přijde jen s novou hlavní verzí jádra a předchozí zůstane podporovaná aspoň jedno vydání s dlouhodobou podporou.
Musím svůj driver zveřejnit?
Ne. Balíček můžete používat jen ve svých instalacích. Do veřejného repozitáře BAVIS-SDK přispíváte dobrovolně, pod licencí Apache-2.0.
Je instalace cizího balíčku bezpečná?
Kód balíčku běží v procesu BAVIS se stejnými právy jako jádro, proto instalujte jen balíčky, kterým důvěřujete. Ve verzi 3.1 se nepodepsaný balíček nainstaluje jen ve vývojovém režimu. Od verze 4.0 nainstaluje správce komunitní driver bez podpisu jen s potvrzením „na vlastní riziko“, heslem a důvodem (elektronický podpis) a instalace se zapíše do Záznamu operací. Instalaci nepodepsaných driverů může správce úplně vypnout.
Od kdy jsou SDK a licence Maker k dispozici?
SDK je součástí BAVIS 3.1, licence Maker vyšla s opravným vydáním 3.1.1. Aktivujete ji v aplikaci v Systém → Licence → BAVIS Maker. V repozitáři BAVIS-SDK můžete sledovat vývoj a hlásit náměty.
Napíšete driver za mě?
Ano, na zakázku. Pošlete nám zařízení, protokol a dokumentaci výrobce a ozveme se s návrhem.
Spolupráce
Píšete driver nebo integrujete BAVIS?
Rádi poradíme s návrhem driveru, s protokolem i s balíčkem. Integrátorům pomůžeme s prvním projektem.
SDK je součástí BAVIS 3.1, licence Maker platí od opravného vydání 3.1.1. Siemens a S7 jsou ochranné známky Siemens AG.