lib-comfoair v0.8.2

lib-comfoair 🌬️

lib-comfoair is a TypeScript library for interacting with Zehnder ComfoAirQ ventilation units through the ComfoConnect LAN C gateway. It enables you to discover these gateways on your local network, read and write device properties, and subscribe to property change notifications.

This library is completely written in TypeScript and strongly typed, making development more reliable and maintainable.

Features ✨

• 🔍 Discover Zehnder ComfoConnect LAN C gateways on your network.
• 📖 Read and write properties of Zehnder ComfoAirQ ventilation units.
• 🔄 Listen for real-time updates of changing properties.
• ⚙️ Strong typing ensures reliable code and easy maintainability.

Installation 📦

NPM

npm i lib-comfoair

PNPM

pnpm add lib-comfoair

Usage 🚀

Below are basic usage examples. The library can discover devices, start sessions to communicate with ventilation units, and request property updates.

Discovering Devices

Use the discovery feature to find Zehnder ComfoConnect LAN C gateways on the same network. You can await the discovery process or attach event listeners.

import { ComfoControlClient } from 'lib-comfoair';

// Discover a gateway with an optional limit:
ComfoControlClient.discover({ limit: 1 })
  .then(devices => {
    console.log('Discovered devices:', devices);
    // If desired, create a client and make requests:
    // const client = new ComfoControlClient(devices[0]);
    // await client.getServerTime();
  });

// Or listen for discovery events:
const discovery = ComfoControlClient.discover({ limit: 10 });
discovery.on('discover', device => {
  console.log('Discovered device:', device);
});
discovery.on('completed', () => {
  console.log('Discovery finished');
});

How Device Discovery Works 🕵️‍♂️

Discovery sends a broadcast message and waits for devices to respond. This works only if the gateway is on the same subnet as the host running the discovery. Most routers do not forward broadcast messages to other subnets by default.

Listening for Property Changes

After obtaining the device’s info, you can register property listeners that trigger when values change:

import { ComfoControlClient, ComfoAirProperties } from 'lib-comfoair';

// Example usage (simplified):
const client = new ComfoControlClient({
  address: '192.168.1.10',
  uuid: 'your-device-uuid-here',
});

// Register a listener for OUTDOOR_AIR_TEMPERATURE:
await client.registerPropertyListener(ComfoAirProperties.OUTDOOR_AIR_TEMPERATURE, ({ value }) => {
  console.log(`Outdoor air temperature: ${value / 10} °C`);
});

// You may then connect or make a request:
console.log(await client.getServerTime());

Available Opcodes

Strongly Typed Library

This library is strongly typed, ensuring that you benefit from autocompletion and reduced runtime errors. It adds clarity when dealing with ComfoAirQ properties and messages by leveraging TypeScript’s type system.

Credits 🙏

This project is based on the protocol specifications documented by Michaël Arnauts. Thank you to Michaël for making this information available.