pyhaseiq

Bibliothèque Python en lecture seule pour les poêles à bois Hase iQ, via leur WebSocket local. Entièrement locale : ni cloud, ni application constructeur, ni compte.

🔍 LECTURE SEULE — cette bibliothèque ne commande rien

pyhaseiq interroge le poêle : température, phase de combustion, performance. Elle n'écrit rien, ne règle rien, n'allume rien, n'éteint rien. Aucune commande d'écriture n'a été observée dans le protocole, aucune n'est implémentée, et c'est un choix permanent du projet — voir les interdits.

Un poêle à bois est un appareil à combustion : sa conduite reste manuelle et relève de son utilisateur. Cette bibliothèque observe, elle ne se substitue à aucun organe de sécurité.

⚠️ PROJET INDÉPENDANT, SANS AUCUNE AFFILIATION

pyhaseiq n'est en aucun cas affilié, soutenu, approuvé ou validé par HASE Kaminofenbau GmbH, ou l'une quelconque de ses filiales, marques, sociétés apparentées, sous-traitants ou partenaires. HASE, Hase iQ et flamemonitor sont des marques de leurs titulaires respectifs, citées uniquement pour décrire le matériel avec lequel cette bibliothèque communique, à des fins d'interopérabilité.

👉 Lisez l'avertissement complet ci-dessous avant toute utilisation. Il couvre l'absence totale de garantie, la garantie constructeur et les conditions d'usage. En utilisant cette bibliothèque, vous reconnaissez les avoir lues et acceptées.

Sommaire

• Quelle génération ?
• Démarrage rapide
• État du projet
• Installation
• Utilisation
• Logging
• Développement
• Contribuer
• Sécurité

Quelle génération ?

Deux générations de poêles portent le nom « Hase iQ », et elles ne parlent pas le même langage. Elles se distinguent à l'application que vous utilisez :

La nouvelle génération n'a pas été observée et son protocole est inconnu. Rien n'est prévu à ce sujet, et les retours sont les bienvenus.

Le protocole de l'ancienne est intégralement décrit dans docs/SPEC-PROTOCOLE-WS.md, où chaque affirmation porte un statut ✅ validé / 🟡 partiel / ❓ supposé.

Démarrage rapide

Avec uv et l'adresse IP de votre poêle :

git clone https://github.com/bbayszczak/pyhaseiq
cd pyhaseiq
uv run demo.py 192.168.1.165

uv crée l'environnement et installe les dépendances tout seul. demo.py n'écrit rien : il affiche un tableau rafraîchi en continu avec la phase du poêle et les mesures disponibles. C'est le moyen le plus rapide de vérifier que votre poêle répond.

État du projet

🚧 Alpha. La lecture fonctionne et le protocole est documenté. L'API peut encore changer.

Les changements de chaque version sont consignés dans le CHANGELOG, tenu à jour automatiquement à partir des messages de commit.

Installation

pip install pyhaseiq

Ou directement depuis le dépôt :

pip install git+https://github.com/bbayszczak/pyhaseiq

Utilisation

L'API est asynchrone : le poêle est un serveur WebSocket, et c'est le modèle qu'attend un hôte comme Home Assistant.

import asyncio

from pyhaseiq import Client, Phase


async def main() -> None:
    async with Client("192.168.1.165") as stove:
        phase = await stove.get_phase()
        print(phase)  # Phase.HEATING_UP

        if phase is Phase.HEATING_UP:
            print(await stove.get_temperature())  # 163.3 °C dans le foyer
            print(await stove.get_heat_up_percent())  # 53.5 % de la montée en chauffe
        elif phase is Phase.NOMINAL:
            print(await stove.get_performance())  # 69 % de performance de combustion


asyncio.run(main())

Les phases

get_phase() rend un Phase, qui est un IntEnum :

⚠️ Toutes les mesures ne sont pas lisibles dans toutes les phases. L'application constructeur ne demande appT et appAufheiz qu'en phase HEATING_UP, et appP qu'en phase NOMINAL. On ignore si le poêle répond quand même hors de ces phases ou s'il reste muet — auquel cas l'appel se solde par un ResponseTimeoutError. Testez la phase avant de lire, comme le fait l'exemple ci-dessus.

Les erreurs

Toutes dérivent de HaseIQError, ce qui permet de rattraper la bibliothèque entière d'un seul except :

Le client ne se reconnecte jamais tout seul : il ne conserve aucun état, et la politique de reprise appartient à l'appelant. Une connexion perdue reste perdue — ouvrez un nouveau client.

Requêtes brutes

Les requêtes documentées mais non exposées par une méthode typée — les séries de mesures, les versions du micrologiciel — restent joignables :

await stove.get("_wversion")  # '1.4'
await stove.get("appP30Tx")  # '30'
await stove.get("appP30T[15;29]")  # '41;40;40;40;40;39;...'

Les noms sont listés dans docs/SPEC-PROTOCOLE-WS.md.

Essayer sans écrire de code

uv run demo.py 192.168.1.165                      # tableau rafraîchi en continu
uv run demo.py 192.168.1.165 --once               # une seule lecture
uv run demo.py 192.168.1.165 --request _wversion  # une requête brute, répétable
uv run demo.py 192.168.1.165 --debug              # afficher le dialogue WebSocket

Exemple de sortie :

┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ parameter        ┃ value                 ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ Last update      │ 09/21/26 - 08:51:12   │
│ Phase            │ heating up (1)        │
│ Temperature (°C) │ 163.3                 │
│ Heat-up (%)      │ 53.5                  │
│ Performance (%)  │ —                     │
└──────────────────┴───────────────────────┘

Logging

La bibliothèque utilise le module logging standard et ne configure rien : ni handler, ni niveau, ni format. C'est l'application hôte qui décide. Chaque module a son logger, nommé d'après le paquet — pyhaseiq.client — ce qui permet de filtrer au paquet entier comme au module.

Tout est en DEBUG : l'ouverture de la connexion et chaque couple requête / réponse. Les erreurs ne sont pas loguées, elles sont levées ; c'est à l'appelant de décider ce qu'il en fait.

Dans Home Assistant, via configuration.yaml :

logger:
  logs:
    pyhaseiq: debug

En script autonome :

import logging

logging.basicConfig(level=logging.DEBUG)

Exemple de trace :

DEBUG pyhaseiq.client: connecting to ws://192.168.1.165:8080
DEBUG pyhaseiq.client: appPhase = 1
DEBUG pyhaseiq.client: appT = 163.3
DEBUG pyhaseiq.client: appAufheiz = 53.5

Le poêle n'expose ni identifiant, ni clé, ni donnée personnelle : une trace DEBUG peut être jointe telle quelle à un rapport de bug.

Développement

uv run ruff check .      # lint
uv run ruff format .     # formatage
uv run pytest            # tests — aucun matériel requis, le poêle est simulé

Contribuer

Les retours sont bienvenus, en particulier sur d'autres modèles de poêles et sur la génération pilotée par l'application HASE iQ, jamais observée.

• Signaler un bug ou proposer une évolution — ouvrir une issue, en précisant l'application avec laquelle vous pilotez habituellement votre poêle.
• Proposer du code — périmètre, conventions et interdits sont décrits dans CONTRIBUTING.md, à lire avant d'ouvrir une pull request.

Sécurité

Le poêle expose un WebSocket non chiffré et sans aucune authentification sur le port 8080 : toute machine de votre réseau local peut l'interroger. Ce n'est pas un choix de cette bibliothèque, c'est ainsi que le poêle est conçu.

N'exposez jamais ce port sur Internet, et ne le redirigez pas depuis votre box. Laissez le poêle sur le réseau local, derrière votre routeur.

Pour signaler une faille dans cette bibliothèque, utilisez le signalement privé — jamais une issue publique.