BAVIS SDK: your own driver for any device
Is the protocol of your device missing in BAVIS? With the public SDK you write a communication driver in Python, test it without hardware and install it as a package. No need to wait for a new BAVIS release.
Status: SDK API 1.0 is part of BAVIS 3.1. The BAVIS-SDK repository is public.
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"),),
)]
Why the SDK
A driver as a package, not a change to the core
The SDK is the stable public interface for drivers written outside the BAVIS core: by the community, by integrators or by us as custom work for a single customer.
Stable API
A package that imports BAVIS only through bavis.sdk keeps loading after the next major core release, for example from 3.x to 4.x.
No new release needed
A driver is a .bavispkg package. Upload it in System → Projects and packages and it works for every project right away.
Tests without hardware
bavis.sdk.testing runs a driver without a BAVIS server against a fake device. Tests never need a real instrument.
The core does the rest
A driver returns raw values. Scaling, dead band, history, alarms and reconnecting are handled by BAVIS.
Get started
Four steps to your own driver
The generator writes a working skeleton: a driver for a simple line-based TCP protocol, a fake device for the tests and translation files. Then you swap the protocol for your own.
Generate the skeleton
A bavis_drv_<name> package with the driver, tests and translations.
python -m bavis.tools.novy_modul driver my_scale \ --label "My scale" --balicek ~/driversWrite the protocol
Override open(), poll() and optionally write(). Describe the connection form with FieldSpec; check_address validates addresses.
def poll(self): return {t.name: self.link.read(t.address) for t in self.tags}Test it
Tests against a fake device on a port chosen by the OS. They run in parallel and without hardware.
cd ~/drivers python -m pytest -q testsBuild and install
The build refuses a broken module or an invalid driver description and, if you give it a key, signs the package. Then upload it in System → Projects and packages.
python -m bavis package build ~/drivers/bavis_drv_my_scale \ --out drv_my_scale-1.0.0.bavispkg --key key.pem
The full API reference, the versioning rules and the examples are in English in the BAVIS-SDK repository. Operator labels are translated in i18n files (Czech, English, German, Slovak, Polish). From version 4.0 every installation (Windows, Linux, Docker) has the bavis sdk command with the steps new, test, check and build – you do not need the core source code; the free Lite or Maker edition is enough. github.com/Tomoash/BAVIS-SDK
Community
A driver for one, useful for everyone
If you write a driver for a device you need, you can offer it to others. We accept contributions in the public BAVIS-SDK repository on GitHub.
Report a bug or suggest a driver
In the GitHub Issues of the BAVIS-SDK repository. Name the device, the protocol and link the manufacturer's documentation. Questions and ideas go to GitHub Discussions.
Open IssuesSend a pull request
Contributions are licensed under Apache-2.0 and every commit is signed off under the DCO (git commit -s). The process is in CONTRIBUTING.
View the repositoryReport vulnerabilities privately
Do not post a security issue in Issues. Send it by e-mail as described in SECURITY.md in the repository.
benesl@benesl-automation.czCatalogue of community packages
From BAVIS 4.0. The administrator chooses trusted package sources in the application. A package from the catalogue installs only if its SHA-256 fingerprint matches, and the installation is written to the audit log. Packages we have verified carry our signature and a “verified” badge.
What BAVIS 4.0 bringsRules for drivers
- Import BAVIS only from bavis.sdk and bavis.sdk.testing.
- Only libraries with a licence compatible with Apache-2.0 (MIT, BSD, Apache). We do not accept GPL libraries.
- Register maps and addresses from the manufacturer's documentation, with a reference to it.
- Safe writing: nothing to read-only tags, writes off where a wrong value can damage equipment, and never cyclic writes to flash or EEPROM.
- Tests with a fake device; no test may need real hardware.
Maker licence
BAVIS Maker: free for home and workshop
For enthusiasts, makers and driver developers. The Maker edition, free for non-commercial use, came out with the BAVIS 3.1.1 maintenance release.
- logic, scripts and calculations, time schedules and energy management
- protocols for the smart home and metering: KNX, M-Bus, wM-Bus, HTTP / REST, Home Assistant and more
- the base protocols of every edition: Modbus, Siemens S7, OPC UA client and MQTT
How Maker works
You switch Maker on right in the application, without a licence file. The installation then reports to BAVIS Central regularly with summary data: versions, counts and the drivers used. It never sends tag values or names.
Commercial use needs a Standard licence, even for a small project. Smaller non-commercial projects up to 150 tags are covered by the free Lite edition.
Questions
SDK FAQ
What is the BAVIS SDK?
A public Python interface for communication drivers of the BAVIS web SCADA. A driver ships as a .bavispkg package and installs without a new BAVIS release.
Will my driver work in BAVIS 4 too?
Yes, if it imports BAVIS only through bavis.sdk. A new major SDK version comes only with a new major core version, and the previous one stays supported for at least one long-term support release.
Do I have to publish my driver?
No. You can use the package only in your own installations. Contributing to the public BAVIS-SDK repository is voluntary, under the Apache-2.0 licence.
Is installing someone else's package safe?
Package code runs inside the BAVIS process with the same rights as the core, so install only packages you trust. In version 3.1 an unsigned package installs only in development mode. From version 4.0 the administrator can install an unsigned community driver only after confirming “at your own risk” with a password and a reason (electronic signature), and the installation is written to the operations log. The administrator can switch off installing unsigned drivers completely.
Since when are the SDK and the Maker licence available?
The SDK is part of BAVIS 3.1, the Maker licence came out with the 3.1.1 maintenance release. You activate it in the application under System → Licence → BAVIS Maker. In the BAVIS-SDK repository you can follow the work and send ideas.
Will you write the driver for me?
Yes, as custom work. Send us the device, the protocol and the manufacturer's documentation and we will come back with a proposal.
Work with us
Writing a driver or integrating BAVIS?
We are happy to help with the driver design, the protocol and the package. We help integrators with their first project.
The SDK is part of BAVIS 3.1; the Maker licence applies from the 3.1.1 maintenance release. Siemens and S7 are trademarks of Siemens AG.