Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
73c633b
Fix Unpack in DL Mode
dereisele Feb 15, 2026
dab4fbb
Use complete analog and digital domains from blnet_direct if blnet_we…
dereisele Feb 23, 2026
03f9576
Fix heat meter and unused input parsing
dereisele Oct 11, 2026
0cfd9f0
Fix fetching via BLNETDirect without web interface
dereisele Oct 11, 2026
c07adc0
Add CLAUDE.md and replace dead protocol spec link
dereisele Oct 11, 2026
6cc3be9
Update CLAUDE.md for the DL-only fixes
dereisele Oct 11, 2026
1b328ff
Start development of 0.11.0
dereisele Oct 11, 2026
bbbea24
Move to uv
dereisele Oct 11, 2026
db0842c
Require Python 3.11
dereisele Oct 11, 2026
733c26b
Apply pyupgrade rules
dereisele Oct 11, 2026
391d8d8
Add Alexander Eisele as author and copyright holder
dereisele Oct 11, 2026
a433df6
Update GitHub Actions
dereisele Oct 11, 2026
220e110
Stop publishing to PyPI, install from GitHub
dereisele Oct 11, 2026
d0537c0
Close socket after failed connection attempt
dereisele Oct 11, 2026
a8fbf28
Pass BLNET timeout to BLNETDirect
dereisele Oct 11, 2026
f472d0e
Release 0.11.0
dereisele Oct 11, 2026
86b8e10
Start development of 0.12.0
dereisele Oct 11, 2026
2b32036
Reconnect BLNETDirect after failed reads
dereisele Oct 11, 2026
0ddec28
Wait while the BL-Net has no new data
dereisele Oct 11, 2026
cc757ca
Release 0.11.1
dereisele Oct 11, 2026
e8a2d58
Start development of 0.12.0
dereisele Oct 11, 2026
f9b6788
Replace htmldom with html.parser
dereisele Oct 11, 2026
02b4e29
Report input type and unit of values
dereisele Oct 11, 2026
e0f5603
Release 0.12.0
dereisele Oct 11, 2026
a2fa1da
Start development of 0.13.0
dereisele Oct 11, 2026
75bbef8
Treat temperature inputs without sensor as unused
dereisele Oct 11, 2026
f76a7c0
Release 0.13.0
dereisele Oct 11, 2026
5caa45a
Read GET_LATEST replies completely
claude Nov 15, 2026
9b9ac61
Merge pull request #1 from dereisele/claude/occasional-values-plus-mi…
dereisele Nov 15, 2026
5c7a71c
Release 0.13.1
claude Nov 15, 2026
f61ac1b
Merge pull request #2 from dereisele/claude/occasional-values-plus-mi…
dereisele Nov 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,24 +12,22 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]

steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
- uses: actions/checkout@v7
- name: Set up uv with Python ${{ matrix.python-version }}
uses: astral-sh/setup-uv@v10.2.0
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
pip install coverage coveralls pytest
pip install -e .
run: uv sync --locked
- name: Run tests
run: coverage run --source=pyblnet -m pytest tests
run: uv run coverage run --source=pyblnet -m pytest tests
- name: Coverage report
run: |
coverage report
coveralls
uv run coverage report
uv run --with coveralls coveralls
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
COVERALLS_FLAG_NAME: ${{ matrix.python-version }}
Expand All @@ -40,11 +38,13 @@ jobs:
name: Indicate completion to coveralls.io
needs: build
runs-on: ubuntu-latest
container: python:3-slim
steps:
- name: Install coveralls
run: pip3 install --upgrade coveralls
- uses: astral-sh/setup-uv@v10.2.0
with:
# this job has no checkout
enable-cache: false
ignore-empty-workdir: true
- name: Finished
run: coveralls --finish
run: uvx coveralls --finish
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
23 changes: 14 additions & 9 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,22 +1,27 @@
name: Python package
name: Release
on:
push:
tags:
- "*.*.*"
jobs:
build:
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
# If there isn't a release for this version, create a new one.
- uses: actions/checkout@v7

- uses: astral-sh/setup-uv@v10.2.0

- name: Build
run: uv build

# If there isn't a release for this version, create a new one
# with the wheel and sdist attached
- uses: ncipollo/release-action@v1
with:
artifacts: "dist/*"
generateReleaseNotes: true
makeLatest: true
prerelease: false
skipIfReleaseExists: true

- name: To PyPI using Flit
uses: AsifArmanRahman/to-pypi-using-flit@v1
with:
password: ${{ secrets.PYPI_TOKEN }}
49 changes: 49 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

PyBLNET is a Python client for the BL-NET gateway by Technische Alternative, which sits in front of a UVR1611 heating controller. It reads analog/digital values and can set switches to ON/OFF/AUTO. Managed with uv: `uv_build` backend, dev tools in the `dev` dependency group, and `uv.lock` committed. The only runtime dependency is `requests`. CI tests Python 3.11–3.15 with `uv sync --locked`, so run `uv lock` after changing dependencies. Pushing a `*.*.*` tag triggers the release workflow: `uv build`, then a GitHub release with the wheel and sdist attached. This fork is not published to PyPI (the `PyBLNET` package there belongs to upstream); users install from GitHub. When releasing, bump the version in both `pyproject.toml` and `VERSION` in `pyblnet/__init__.py`.

## Commands

```bash
uv sync # create .venv with package + dev group
uv run pytest tests # full suite
uv run pytest tests/test_web.py::BLNETWebTest::test_blnet_fetch # single test
uv run coverage run --source=pyblnet -m pytest tests && uv run coverage report # what CI runs
uv run --isolated --python 3.11 pytest tests # oldest supported Python, leaves .venv alone
uv run ruff check pyblnet tests # ruff defaults + pyupgrade (UP); UP is clean, other default rules still report issues; CI does not run ruff
uv build # sdist + wheel into dist/
```

## Architecture

Two independent transports, plus a facade over both:

- **`BLNETWeb`** (`blnet_web.py`) scrapes the device's German-language HTTP interface with `requests` and the standard library's `html.parser` (`_element_texts()` keeps entities like `&nbsp;` as written and turns `<br>` into newlines, which the value regexes rely on). Login POSTs to `/main.html` and stores the `TAID` cookie. `logged_in()` works by checking whether a restricted page sends back `Set-Cookie`. Use it as a context manager: `__enter__`/`__exit__` call `log_in`/`log_out`. Logging out matters because the device blocks all web access for about 150s after a session that wasn't logged out. The constructor calls `blnet_test()` and raises `ValueError` if no BL-NET answers. Switch values use the device's German strings `"EIN"`, `"AUS"`, `"AUTO"`. Only this transport can set switches, read manual/auto mode, and select a CAN node.
- **`BLNETDirect`** (`blnet_conn.py`) speaks TA's binary bootloader protocol over TCP (port 40000). It is a Python port of berwinter's PHP `blnet-connection.inc.php`. On construction it queries the device mode: `CAN_MODE`, `DL_MODE` or `DL2_MODE`. That mode decides frame counts, dataset sizes and how `_split_latest`/`_split_datasets` slice the response. The README still calls this transport buggy and discourages it. The `timeout` is set on each socket it opens, not process-wide. `get_latest()` lists frames that never arrived in `info["timeout"]` and raises `ConnectionError` if no frame arrived. Read paths (`get_latest`, `get_count`, `_get_data`, `_check_mode`) are wrapped in `_reset_on_error`: on any error the socket is closed and the read state is reset, so the next call reconnects; empty or malformed replies are raised as `ConnectionError`. Errors reaching callers are therefore `OSError` subclasses (`ConnectionError` or `TimeoutError`). A one-byte `0xAB` reply means the device has no new data yet (real devices say so for up to ~5 s after a read); `get_latest()` then waits `NO_DATA_WAIT` seconds before the next try. `_query_latest()` derives the reply length from its first byte and reads the reply completely, because BL-NETs sometimes send the first byte in a TCP segment of its own; reading only part of it shifted all following replies by one byte, and the weak sum checksum let some of those shifted datasets through as garbage values. After a reply with a bad checksum `get_latest()` reconnects so stray bytes can't reach the next reply.
- **`BLNETParser`** (`blnet_parser.py`) decodes one binary dataset (55 bytes, or 61 with a timestamp) into `{'analog','digital','speed','energy','power'}` dicts keyed by 1-based ID. Inactive values are `None`: unused inputs (type bits `000`), temperature inputs without sensor (raw `0x2FFF` = 409.5 °C, `TEMP_NO_SENSOR`), inactive speed controls and inactive heat meters. `analog_types` maps each input to `"temperature"`, `"volume_flow"`, `"radiation"`, `"digital"` or `None` (`ANALOG_TYPES`, units in `ANALOG_UNITS`). It is used only by `BLNETDirect`.
- **`BLNET`** (`blnet.py`) is the high-level facade, with each transport switched on by `use_web` (default on) and `use_ta` (default off). `fetch()` returns a dict with all five domains. The web transport supplies analog/digital entries as dicts (`id`, `name`, `value`, `mode`). Direct data then overwrites `value` on those entries. If web is disabled ("DL-only" mode), `fetch()` creates entries from direct data alone and skips `None` values; analog entries carry `type` and `unit_of_measurement`, digital ones only `value`. Web analog entries get `type` derived from their unit (`WEB_UNIT_TYPES`). `speed`/`energy`/`power` come only from direct, with `unit_of_measurement` `None` (speed is a level 0-30), `"kWh"` and `"kW"`. `get_value()` matches on `name` (when given) or on the id key, so it works for both entry shapes.

## Device documentation

- Official BL-NET manual (German, v2.19): https://www.ta.co.at/download/datei/416. Its "Zugriff per Browser" chapter describes the web interface that `BLNETWeb` scrapes. Facts from it that the code relies on:
- Only one user can be logged in at a time.
- A session ends after 2.5 minutes without traffic. If a session isn't logged out, nobody can log in for those 2.5 minutes.
- There are three access levels: Experte, Anwender and "nur ansehen". The login form field `blu=1` selects Experte.
- From the factory no password is set. Code passes `password=None` to skip login.
- The default ports are HTTP 80 and TA port 40000.
- For CAN data logging, one UVR1611 must be node 1.
- The binary protocol used by `BLNETDirect` isn't in that manual. TA's spec "Schnittstelle Winsol <> Bootloader" (2006) describes it. The haus-terra link in the README is dead (404); an archived copy is at http://web.archive.org/web/20160122124754/http://www.haus-terra.at:80/heizung/download/Schnittstelle/Schnittstelle_PC_Bootloader.pdf. The spec covers:
- The DL modes only: 1DL `0xA8` and 2DL `0xD1`.
- The commands `0x81` (mode), `0x82` (firmware), `0xAA` (header), `0xAB` (latest data), `0xAC` (read logged block), `0xAD` (end read) and `0xAF` (reset logged data).
- The dataset layouts.
- Not in the spec: CAN mode (`0xDC`), the `0xBA` "wait" response, and the frame-number byte sent after `0xAB`. These come from berwinter's reverse-engineered PHP code. In DL mode the spec's `0xAB` request is one byte, but the code sends two, and a real device accepts that.

## Tests

- `tests/test_parser.py` checks `BLNETParser` against raw byte fixtures.
- `tests/test_web.py` runs `BLNETWeb`/`BLNET` against a local mock HTTP server (`tests/test_structure/blnet_mock_server.py`, started in a thread by `server_control.py`). The mock serves the saved device pages in `tests/test_structure/*.htm` and emulates login cookies, password (`0123`), node switching and a "blocked" state. Expected parse results live in `tests/web_raw/web_state.py`.
- `tests/test_direct.py` runs `BLNET` in DL-only mode against a fake TCP BL-NET (`tests/test_structure/blnet_direct_mock_server.py`). The fake replays mode, header and latest-data responses recorded from a real device in DL mode. Only `GET_MODE`, `GET_HEADER`, `GET_LATEST` and `END_READ` are emulated; CAN/DL2 modes and reading stored data (`_get_data`) are untested.
1 change: 1 addition & 0 deletions LICENSE.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
Copyright (c) 2017 Niels Mündler
Copyright (c) 2026 Alexander Eisele

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
Expand Down
13 changes: 0 additions & 13 deletions Pipfile

This file was deleted.

27 changes: 20 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
# PyBLNET - a very basic python BL-NET bridge
![PyPI - Version](https://img.shields.io/pypi/v/pyblnet)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyblnet)
[![Build status](https://github.com/nielstron/pyblnet/actions/workflows/build.yml/badge.svg)](https://github.com/nielstron/pyblnet/actions/workflows/build.yml)
[![Coverage Status](https://coveralls.io/repos/github/nielstron/pyblnet/badge.svg?branch=master)](https://coveralls.io/github/nielstron/pyblnet?branch=master)
[![Build status](https://github.com/dereisele/pyblnet/actions/workflows/build.yml/badge.svg)](https://github.com/dereisele/pyblnet/actions/workflows/build.yml)
[![Coverage Status](https://coveralls.io/repos/github/dereisele/pyblnet/badge.svg?branch=master)](https://coveralls.io/github/dereisele/pyblnet?branch=master)

A package that connects to the BL-NET that is connected itself to a UVR1611 device by Technische Alternative.
It is able to read digital and analog values as well as to set switches to ON/OFF/AUTO.
Expand All @@ -13,14 +11,29 @@ Two interfaces to BLNet exist and both are supported:
- Webinterface - Class BLnetWeb
- BLNet-Direct protocol [1] - Class BLNETDirect

However, as of now, there is no testing on the BLNet-Direct protocol *of any kind*, so enabling it is discouraged until the interface is fixed.
Parsing the data via the web interface is the preferred way of accessing the BLNet for now.
BLNet-Direct is tested against responses recorded from a real BL-NET in DL mode (one UVR1611).
CAN and 2DL mode as well as reading logged data are still untested, so the web interface remains the safer choice there.

The class BLNET is a wrapper around the two classes. When initializing the class, the two interfaces can be activated/deactivated.
BLNetDirect provides 'analog', 'digital', 'speed', 'energy', 'power', whereas BLnetWeb supports 'analog' and 'digital' only.
If both are active, BLNetDirect has priority.
Setting switches and reading their manual/auto state is only possible via the BLNetWeb interface.

### Installation

This fork is not published on PyPI. The `PyBLNET` package on PyPI is released by the upstream project and doesn't contain the changes made here.
Install it from GitHub instead (Python 3.11 or newer):

```bash
pip install git+https://github.com/dereisele/pyblnet.git
# or a specific release
pip install git+https://github.com/dereisele/pyblnet.git@0.11.0
# or with uv
uv add git+https://github.com/dereisele/pyblnet.git
```

Each [release](https://github.com/dereisele/pyblnet/releases) also has the wheel and sdist attached.

### Usage

```python
Expand Down Expand Up @@ -67,4 +80,4 @@ print(blnet._get_data(1))
```


[1] https://www.haus-terra.at/heizung/download/Schnittstelle/Schnittstelle_PC_Bootloader.pdf
[1] Technische Alternative, "Schnittstelle Winsol <> Bootloader" (2006), archived copy: http://web.archive.org/web/20160122124754/http://www.haus-terra.at:80/heizung/download/Schnittstelle/Schnittstelle_PC_Bootloader.pdf
3 changes: 1 addition & 2 deletions pyblnet/__init__.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
#!/usr/bin/env python
# -*- coding: utf-8 -*-

import warnings

Expand All @@ -10,5 +9,5 @@
except ImportError as e:
warnings.warn(ImportWarning(e))

VERSION = (0, 10, 0)
VERSION = (0, 13, 1)

42 changes: 30 additions & 12 deletions pyblnet/blnet.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
Created on 13.08.2018

Expand All @@ -12,11 +11,18 @@
"""
from .blnet_web import BLNETWeb
from .blnet_conn import BLNETDirect
from .blnet_parser import ANALOG_UNITS

from urllib.parse import urlparse


class BLNET(object):
# Units of the values only available via BLNETDirect, speed is a level 0-30
UNITS = {"speed": None, "energy": "kWh", "power": "kW"}
# Analog input type for the units shown by the web interface
WEB_UNIT_TYPES = {unit: input_type for input_type, unit in ANALOG_UNITS.items() if unit is not None}


class BLNET:
"""
General high-level BLNET interface.

Expand Down Expand Up @@ -61,14 +67,14 @@ def __init__(
self.blnet_direct = None
if use_web:
self.blnet_web = BLNETWeb(
"{}:{}".format(address, web_port), password, timeout
f"{address}:{web_port}", password, timeout
)
if use_ta:
# The address might not have a resulting hostname
# especially not if not prefixed with http://
# see https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlparse
host = urlparse(address).hostname or address
self.blnet_direct = BLNETDirect(host, ta_port)
self.blnet_direct = BLNETDirect(host, ta_port, timeout=timeout)

def fetch(self, node=None):
"""
Expand All @@ -88,6 +94,8 @@ def fetch(self, node=None):
blnet_session.set_node(node)
data["analog"] = self._convert_web(blnet_session.read_analog_values())
data["digital"] = self._convert_web(blnet_session.read_digital_values())
for entry in data["analog"].values():
entry["type"] = WEB_UNIT_TYPES.get(entry.get("unit_of_measurement"))
if self.blnet_direct:
direct = self.blnet_direct.get_latest(self.max_retries)[0]
# Override values for analog and digital as values are
Expand All @@ -96,11 +104,20 @@ def fetch(self, node=None):
for id, value in direct[domain].items():
if data[domain].get(id) is not None:
data[domain][id]["value"] = value
elif not self.blnet_web:
if value is None:
continue
data[domain][id] = {"value": value}
if domain == "analog":
input_type = direct["analog_types"][id]
data[domain][id]["type"] = input_type
data[domain][id]["unit_of_measurement"] = ANALOG_UNITS.get(input_type)

for domain in ["speed", "energy", "power"]:
for id, value in direct[domain].items():
if value is None:
continue
data[domain][id] = {"value": value}
data[domain][id] = {"value": value, "unit_of_measurement": UNITS[domain]}
return data

def turn_on(self, digital_id, can_node=None):
Expand Down Expand Up @@ -132,17 +149,15 @@ def _turn(self, digital_id, value, can_node=None):
if can_node is not None:
if not blnet_session.set_node(can_node):
raise ConnectionError(
"Could not set can node to {}".format(can_node)
f"Could not set can node to {can_node}"
)
if not blnet_session.set_digital_value(digital_id, value):
raise ConnectionError(
"Failed to set digital switch {} to value {}".format(
digital_id, value
)
f"Failed to set digital switch {digital_id} to value {value}"
)
return True
else:
raise EnvironmentError("Can't set values with blnet web disabled")
raise OSError("Can't set values with blnet web disabled")

def get_value(self, name=None, id=None, type="digital", ret="value", cached=None):
"""
Expand All @@ -162,8 +177,11 @@ def get_value(self, name=None, id=None, type="digital", ret="value", cached=None
if cached is None:
cached = self.fetch()
for key, v in cached[type].items():
if str(v["name"]) == str(name) or str(v["id"]) == str(id):
val = v[ret]
# values fetched only via blnet_direct have no name
if (name is not None and str(v.get("name")) == str(name)) or (
id is not None and str(key) == str(id)
):
val = v.get(ret)
dic = v

return val, dic, cached
Expand Down
Loading