Read and write data on a BSB (Boiler System Bus).

Functionalities offered:

• Commandline interface. Enter help to get list of commands, help <cmd> for documentation of a specific command.
• Web interface at port :8082 (e.g. http://localhost:8082)
• Logging of fields with preset interval. The logs are written in ASCII .trace files and can be loaded with trace/load_trace.py into numpy arrays.

The project underwent significant modernizations at the beginning of 2026. Be sure to read the installation docs. The old config.py is obsolete and has to be replaced by the new bsbgateway.ini. There is now an interactive configuration menu to help with this.

You need hardware to interface with the bus. In principle, a serial port and a level converter / galvanic decoupler is required. The circuit that I use is drawn here, but not recommended for rebuilding.

The serial port driver evaluates the CTS (clear-to-send) pin of the RS232 in order to check if the bus is free. Depending on your circuit, you may want to change the settings (esp. invert/no invert) in the configuration.

The easiest way is to install using pipx:

pipx install bsbgateway

Alternatively and/or for hacking, you can clone the repository, then run bsbgateway.sh. It will automatically setup a local venv, install the project in editable mode and run it.

In both cases, you get bsbgateway as user-mode-program. In order to set it up and configure as system service, use the management mode (bsbgateway manage). See following sections.

You will need a device description file. See devices

In the terminal, run bsbgateway manage. This will show a menu with the options:

• Configure: Interactive configuration;
• Run: run the gateway within the terminal (for testing). Same happens if you just start bsbgateway without parameters.
• Install / uninstall / restart service: to manage system service.

The default config file is bsbgateway.ini.

Upon start, it will be searched in (in this order):

• working dir
• ~/.config/bsbgateway/ (recommended location)
• /etc/bsbgateway/

You can give the --config /path/to/something.ini switch to use a specific ini file instead of the default.

After editing the file, it is saved back to the same location. If it doesn't yet exist, ~/.config/bsbgateway/bsbgateway.ini is created.

In a fresh installation, configure at least the following:

• Gateway / Device - point to your device json file (see below)
• Adapter - if using a serial adapter, check at least the "Adapter Device" and "Invert bytes" settings.

Config is saved when you return to the main menu, unless you discard the changes with x.

Here's what a minimal bsbgateway.ini might look like for a Broetje ISR heater connected via USB-to-RS232 adapter:

[gateway]
; "broetje_isr_plus.json" expected in config directory!
device = broetje_isr_plus

[adapter]
adapter_type = serial
adapter_device = /dev/ttyUSB0
invert_bytes = True
port_parity = odd
expect_cts_state = None

[web_interface]
enable = True
port = 8082

[cmd_interface]
enable = True

For other configurations or detailed parameter descriptions, use bsbgateway manage and select "Configure" to see all available options with inline help.

The set of available fields, datatypes and additional information comes from a "device definition" file. See the devices directory here in the repository. Currently there is a file for my own heater, broetje_isr_plus.json, that you can use as starting point. Download and modify it with your editor of choice.

Some words of caution

The list of fields in broetje_isr_plus.json was gathered mostly from bus-sniffing my own heating system. In the meantime, the guys at the BSB_LAN project did an incredible job of gathering this information for hundreds of devices.

As it turns out, there is no real standardization of the device data. The parameters available differ in meaning, telegram structure and scope significantly, sometimes even within the same controller model, but across different firmware versions. The big issue here is that one telegram structure might work on a different heater without an issue, but the conversion factor might be 2 instead of 1, 5 instead of 10 or vice versa or something completely different. While this will not immediately damage your heating system, it can make it run very inefficiently or strain the components, and you might not even notice where the problem comes from, because, on the web-interface, it still says that the minimum break betweek burner starts is 10 minutes, whereas your heater actually thinks of the same value as 1 minute, for example. (More information)

So, please check all fields of interest against your device. Compare what bsbgateway tells you with what you see on the local control panel. That applies especially if you intend to set data and not only monitor it. Use the dump command for sniffing, and edit your device json file accordingly.

'nuff said...

To get the necessary information, scroll through the menus on your heater and dump the traffic in the command interface (using dump on command). (This might get easier in the future...)

Once you have the device file ready, put it alongside bsbgateway.ini (recommendation: as ~/.config/bsbgateway/my_name.json). In the configuration, put the file name without extension (e.g. my_name) as "Gateway / Device" setting.

Choose "run" in the management menu, or run bsbgateway without parameters. It will log messages in the terminal.

You should now be able to access the Web interface as well as enter Commands in the terminal. If things don't work as expected, check the Troubleshooting section.

Once the program works as you like, you will probably want it to start automatically and run in the background. For this, you can install it as systemd service. Run bsbgateway manage and choose "Install service".

• This will prompt you for the sudo password.
• The service will run bsbgateway from the location and with the user account that are currently active. If you are using a local venv, moving it will break the service.
• On success, you should see a message like "Status:Running".

You can view log messages using journalctl -u bsbgateway.service.

Using the management mode, you can also restart and uninstall the service.

Look in manage.py if you want to know the exact commands that are executed.

• Commandline Interface - Query fields, set values, sniff the bus
• Web Interface - Browser-based control and monitoring
• Logging - Data logging with configurable intervals
• Protocol Reference - BSB protocol details
• Hardware - Adapter circuit specifications
• TCP Bridging - how to expose the bus via TCP
• API & Advanced usage - Programmatic access, custom modules, TCP bridging
• Troubleshooting - Common issues and solutions

If something doesn't work:

1. Run with verbose logging: bsbgateway manage → "Configure" → enable debug logging
2. Use dump on in the command interface to monitor bus traffic
3. Check the Troubleshooting guide
4. Contact me via Github.

Significant modernization happened in 2026.

Planned:

• Test correct reading+writing of all datatypes with actual device
• Add "edit-model" mode with automatic sniffing + adding of fields
• MQTT endpoint for Home Assistant

Done: (version 1.0 @ 2026-01-31)

• Do not configure in .py files anymore (config.py, "device".py). Instead, use ini / json files.
• Completely replace device model and packet reader/writer code.
• Replaced near-dead web.py framework by Flask / Jinja2.
• Add support for all datatypes (esp. date/time input) to web interface.
• Add TCP forwarder and TCP adapter modules.
• Refactor Core code, decouple modules and introduce welldefined interfaces.
• Management mode (bsbgateway manage) for interactive configuration and installation as service.
• Proper packaging, using pyproject.toml