KaZa Home automation

Introduction to KaZa

KaZa is an open-source home automation platform built entirely on Qt and QML. It provides a unified object model that bridges physical devices — KNX bus sensors and actuators, MQTT topics, HTTP-based appliances — into a single namespace accessible in real time from any platform: Linux, Windows, or Android.

Unlike many home automation systems that rely on web dashboards, KaZa produces native applications. The server runs as a headless systemd daemon on Linux (a Raspberry Pi is the typical target). The client is a native Qt application compiled for each target platform. The user interface is entirely written in QML, giving integrators the full power of a declarative UI toolkit with smooth animations, hardware-accelerated rendering, and full offline capability.

Architecture Overview

KaZa is built around a client/server model with a plugin-based extension system.

┌──────────────────────────────────────────────────────────────────┐
│                       User Application                            │
│                    (integrator QML code)                          │
│                                                                   │
│   ┌─────────────┐  ┌─────────────┐  ┌───────────┐  ┌─────────┐ │
│   │  KNX Plugin │  │ MQTT Plugin │  │  Helios   │  │ Custom  │ │
│   │  org.kazoe  │  │  org.kazoe  │  │  Plugin   │  │ Plugin  │ │
│   │   .knx 1.0  │  │  .mqtt 1.0  │  │           │  │         │ │
│   └──────┬──────┘  └──────┬──────┘  └─────┬─────┘  └────┬────┘ │
│          └────────────────┴───────────────-┴─────────────┘       │
│                                   │ KaZaObject                   │
└───────────────────────────────────┼──────────────────────────────┘
                                    │
┌───────────────────────────────────┼──────────────────────────────┐
│                    KaZa Server Core (kazad)                       │
│                                   │                               │
│   ┌────────────┐        ┌─────────▼──────┐        ┌──────────┐  │
│   │ KaZaManager│◄───────│  QML Engine    │        │ systemd  │  │
│   │ (singleton)│        │ (user main.qml)│        │ notify   │  │
│   └─────┬──────┘        └────────────────┘        └──────────┘  │
│         │                                                         │
│   ┌─────┴──────────────────┬──────────────────┐                  │
│   │                        │                  │                  │
│ ┌─▼──────┐         ┌───────▼──┐      ┌────────▼────────┐        │
│ │SSL Port│         │ Control  │      │   PostgreSQL    │        │
│ │  1756  │         │Port 43500│      │ (optional log)  │        │
│ └───┬────┘         └──────────┘      └─────────────────┘        │
│     │                                                            │
└─────┼──────────────────────────────────────────────────────────--┘
      │  KaZa Protocol (binary, mutual TLS)
      │
┌─────┼─────────────────────────────────────────────────────┐
│     │            Connected Clients                         │
│  ┌──▼──────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │ Linux Client│  │  Android    │  │  Windows    │       │
│  └─────────────┘  └─────────────┘  └─────────────┘       │
└─────────────────────────────────────────────────────────--┘

Components

KaZa Server (kazad)

The server is the central piece of the system. It runs as a Linux daemon (systemd service) and is the only always-on process. It is designed to run on low-power hardware such as a Raspberry Pi, though any x86_64 or ARM Linux machine works.

The server has two responsibilities:

1. Running the user automation QML

The server embeds a QML engine that loads the integrator's main.qml file. This file is where all automation logic lives: plugin instantiation, object bindings, schedulers, database logging. The QML runs continuously for as long as the daemon is alive.

2. Serving clients

The server opens two TCP ports:

The SSL port carries the KaZa binary protocol and requires mutual TLS: both server and client must present a certificate signed by a shared Certificate Authority. On connection, the server sends the complete current state of all objects to the new client, then streams only value changes.

The control port (43500) is intended for localhost use only. It exposes text commands for querying and setting objects, and a special command that generates signed client certificates on demand (the provisioning flow for new devices).

Key C++ classes:

KaZa Client

The client is a native Qt application compiled for Linux, Windows, or Android. It connects to the server over the SSL port using mutual TLS and keeps a local mirror of all registered objects. When the server pushes a value change the client updates its mirror immediately; when the user acts on the UI the client sends a write frame to the server.

The client is a "shell": it provides the connection logic, the object mirror, and a manager singleton exposed to QML. The actual UI — every screen, widget, and navigation flow — comes from the user application's compiled .rcc resource bundle, which the server distributes over the SSL connection on first connect. This means deploying a UI update requires only replacing the .rcc file on the server; all clients download it automatically on their next connection.

Supported platforms: Linux x86_64, Windows x86_64, Android arm64.

KaZa Protocol

A compact binary protocol shared between server and client (the KaZa-Protocol submodule). All frames have a 5-byte header: 4 bytes payload length + 1 byte type.

A FRAME_OBJVALUE payload is minimal: 2 bytes for the object ID, the value serialized with Qt's QDataStream, and 1 boolean byte for the confirm flag. A typical boolean or integer update is under 10 bytes of payload. Values can be bool, int, double, QString, QDateTime, or any other type supported by QDataStream.

KaZa Control Panel

A Qt Widgets desktop application (Linux and Windows) for administration and debugging. It connects to the server's control port and displays the live value of every registered object in a table. Values can be inspected and manually overridden. The control panel also provides a GUI for generating SSL client certificates, which removes the need to use the command-line provisioning flow for day-to-day device onboarding.

Security Model

KaZa uses mutual TLS for all client connections. Both the server and every client present a certificate signed by a single private Certificate Authority that the integrator creates during initial setup.

• The CA key and certificate live on the server. The CA is never exposed to clients.
• The server generates signed client certificates on request through the control port's clientconf? command (or through the Control Panel GUI). The client's private key is encrypted with a user-chosen password before being returned.
• The control port (43500) transmits the admin password in plain text over TCP and should be firewalled to localhost or trusted network segments only.

Certificate files are stored in /var/lib/kazad/:

Plugin Ecosystem

Plugins are standard Qt QML extension modules. They are installed into the system Qt QML path (e.g. /usr/lib/qml/org/kazoe/<name>/) and imported in user QML with a normal import statement. Plugins are packaged as Debian .deb files and installed alongside the server package.

KNX (org.kazoe.knx)

Integrates a KNX installation via knxd. The integrator provides an ETS .knxproj export file; the plugin parses it and creates one KaZaObject per group address. Group address values flow bidirectionally: a KNX telegram updates the object and propagates to clients; a client write sends a KNX telegram to the bus.

import org.kazoe.knx 1.0

KnxBus {
    knxd:    "ip:192.168.1.250"
    knxProj: "/etc/kaza/home.knxproj"
}

After instantiation, all group addresses from the ETS project are accessible by name as KzObject bindings. The object names are taken from the ETS group address names.

Dependencies: knxd daemon running and reachable at the configured address.

MQTT (org.kazoe.mqtt)

Connects to a Mosquitto (or any compatible MQTT) broker. Each MqttTopic child maps a topic to a KaZaObject; incoming messages update the object's value; writing to the object publishes to the topic.

import org.kazoe.mqtt 1.0

MqttClient {
    hostname: "localhost"
    port:     1883
    clientId: "kaza-server"

    MqttTopic { topic: "home/sensors/temperature" }
    MqttTopic { topic: "home/sensors/humidity" }
}

Dependencies: A running MQTT broker (Mosquitto recommended).

Helios (org.kazoe.helios)

Integrates a Helios Easycontrol controlled ventilation unit (VMC/HRV) via its HTTP API. Exposes: - Fan speed (supply and extract) - Ventilation mode - Inside and outside temperature sensors - Filter status

Dependencies: Helios Easycontrol unit accessible on the local network.

Palazzetti (org.kazoe.palazzetti)

Integrates a Palazzetti pellet stove via its ConnBox HTTP/JSON interface. Exposes: - Stove on/off state - Target temperature - Fan speed - Pellet feed status - Alarm codes

Dependencies: Palazzetti ConnBox connected to the stove and accessible on the local network.

Server Installation

Requirements

• Debian 11+ / Ubuntu 22.04+ / Raspberry Pi OS 64-bit
• Qt 6.2+ runtime libraries
• OpenSSL 1.1+ or 3.0+
• systemd
• PostgreSQL 12+ (optional, for logging and graphs)

From the Debian Repository

# Add the KaZa repository
echo "deb https://repo.kazoe.org/kaza stable main" | \
    sudo tee /etc/apt/sources.list.d/kaza.list
sudo apt update

# Install server
sudo apt install kaza-server-bin

# Install plugins as needed
sudo apt install kaza-knx kaza-mqtt kaza-helios kaza-palazzetti

Systemd Service

The package installs a systemd service (kazad.service). After configuring /etc/kazad.conf, enable and start:

sudo systemctl enable kazad
sudo systemctl start kazad
sudo journalctl -u kazad -f    # tail logs

Configuration: /etc/kazad.conf

[ssl]
port=1756
keypassword="server_key_password"
hostname="home.example.com"      # Hostname clients will connect to

[control]
port=43500
password="admin_password"
enable=true

[database]                       # Optional — remove section if not used
driver="QPSQL"
hostname="127.0.0.1"
port=5432
dbName="kaza"
username="kaza"
password="db_password"

[qml]
server=/opt/kaza/main.qml        # Integrator's server-side QML
client=/opt/kaza/app.rcc         # Integrator's compiled client bundle

Generating Certificates

# From the server — generates CA, server cert, and an initial client cert
sudo /usr/share/kazad/make_certificate.sh \
    "home.example.com" \
    "client_key_password" \
    "server_key_password"

Generated files are placed in /var/lib/kazad/. For additional client devices, use the control port or the KaZa Control Panel.

Packaging and Distribution

All KaZa components are distributed as Debian .deb packages targeting Debian 11+ and Ubuntu 22.04+. The build system uses CMake with CPack.

Target platforms:

Real-World Example: KaZaExample

KaZaExample is a production home automation installation that demonstrates the full KaZa stack. It integrates:

• KNX — lights, shutters, presence detectors, power meters for 20+ individual circuits, hot water boiler temperature sensors, EDF tariff mode actuators
• Helios — controlled ventilation (VMC) with inside temperature monitoring and automation
• Victron Energy — solar inverter and battery system (state of charge, grid export/import, solar production)
• Tesla — electric vehicle charge state and smart charging control
• Palazzetti (via custom HTTP) — swimming pool controller (Ines: water temperature, filtration, pH, robot)
• HTTP REST — French electricity Tempo tariff API (next-day tariff color) for smart scheduling
• Internal objects — WiFi-based presence detection for household members
• PostgreSQL — time-series logging of power consumption per circuit, temperatures, water levels

The server-side QML spans 10 files:

The client-side QML provides a mobile-friendly UI (360×668 portrait layout) with:

• Home page — temperatures, battery level, rain water tank, EDF tariff indicator, mode buttons (TV mode, night mode)
• Floor plan views — ground floor and upper floor touch targets for lights and shutters, room by room
• Energy screens — power consumption by circuit, solar production history, grid exchange graphs
• Device screens — EV charging, ventilation, pool status
• History screens — min/average/max trends for any object, selectable time range
• Debug page — live list of all object values for troubleshooting
• Settings — SSL connection configuration, certificate management

The client widget library (Widget/) includes over 15 reusable components: light switches, dimmers, shutter controls, temperature sensors, power meters, battery indicators, tank level gauges, and presence dots.