Poptat projekt
Benešl Automation / BAVIS / SDK a komunita
BAVIS 3.1Veřejné SDK a otevřený repozitář

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ý.

1.0verze API SDK
Apache-2.0licence repozitáře
3 → 4balíček SDK přežije novou hlavní verzi
drivers/my_scale.py · minimální driver
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.

SDK 1.0

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.

SDK 1.0

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.

SDK 1.0

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.

SDK 1.0

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.

  1. 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 ~/drivers
  2. Napiš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}
  3. 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 tests
  4. Sestavte 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.

01

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 Issues
02

Poš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ář
03

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.cz
04

Katalog 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.0

Pravidla 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.

5 000tagů v projektu
zdarmapro nekomerční použití
  • 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.

Spočítat licenci

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.