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

| Opcode | Description | |-------------------------------|--------------------------------------------------------| | NO_OPERATION | No operation (placeholder). | | SET_ADDRESS_REQUEST | Sets the device address. | | REGISTER_DEVICE_REQUEST | Registers a device/client. | | START_SESSION_REQUEST | Initiates a session. | | CLOSE_SESSION_REQUEST | Ends an existing session. | | LIST_REGISTERED_APPS_REQUEST | Lists registered apps/clients. | | UNREGISTER_DEVICE_REQUEST | Unregisters a device/client. | | CHANGE_PIN_REQUEST | Changes the device PIN code. | | GET_REMOTE_ACCESS_ID_REQUEST | Retrieves the remote access ID. | | SET_REMOTE_ACCESS_ID_REQUEST | Sets the remote access ID. | | GET_SUPPORT_ID_REQUEST | Retrieves the support ID. | | SET_SUPPORT_ID_REQUEST | Sets the support ID. | | GET_WEB_ID_REQUEST | Retrieves the web ID. | | SET_WEB_ID_REQUEST | Sets the web ID. | | SET_PUSH_ID_REQUEST | Sets the push message ID. | | DEBUG_REQUEST | Debug request. | | UPGRADE_REQUEST | Initiates firmware upgrade. | | SET_DEVICE_SETTINGS_REQUEST | Adjusts device settings. | | VERSION_REQUEST | Queries version information. | | SET_ADDRESS_CONFIRM | Confirms address setup. | | REGISTER_DEVICE_CONFIRM | Acknowledges registration. | | START_SESSION_CONFIRM | Confirms session initiation. | | CLOSE_SESSION_CONFIRM | Confirms session closure. | | LIST_REGISTERED_APPS_CONFIRM | Confirms list of registered apps. | | UNREGISTER_DEVICE_CONFIRM | Confirms device unregistration. | | CHANGE_PIN_CONFIRM | Confirms PIN change. | | GET_REMOTE_ACCESS_ID_CONFIRM | Remote access ID confirmation. | | SET_REMOTE_ACCESS_ID_CONFIRM | Remote access ID setup confirmed. | | GET_SUPPORT_ID_CONFIRM | Support ID confirmation. | | SET_SUPPORT_ID_CONFIRM | Support ID setup confirmed. | | GET_WEB_ID_CONFIRM | Web ID confirmation. | | SET_WEB_ID_CONFIRM | Web ID setup confirmed. | | SET_PUSH_ID_CONFIRM | Push ID setup confirmed. | | DEBUG_CONFIRM | Debug request confirmation. | | UPGRADE_CONFIRM | Confirms firmware upgrade. | | SET_DEVICE_SETTINGS_CONFIRM | Confirms device settings update. | | VERSION_CONFIRM | Confirms version request. | | GATEWAY_NOTIFICATION | Notification from the gateway. | | KEEP_ALIVE | Keeps the session alive. | | FACTORY_RESET | Resets the device to factory defaults. | | CN_TIME_REQUEST | Requests current time. | | CN_TIME_CONFIRM | Confirms time update. | | CN_NODE_REQUEST | Node-related request (internal). | | CN_NODE_NOTIFICATION | Node status/update notification. | | CN_RMI_REQUEST | Remote method invocation request. | | CN_RMI_RESPONSE | Response to RMI request. | | CN_RMI_ASYNC_REQUEST | Asynchronous RMI request. | | CN_RMI_ASYNC_CONFIRM | Acknowledges async RMI. | | CN_RMI_ASYNC_RESPONSE | Response to async RMI. | | CN_RPDO_REQUEST | Requests updates for a property. | | CN_RPDO_CONFIRM | Confirms property update subscription. | | CN_RPDO_NOTIFICATION | Notifies of a property update. | | CN_ALARM_NOTIFICATION | Notifies of alarms from the device. | | CN_FUP_READ_REGISTER_REQUEST | Firmware update read register request. | | CN_FUP_READ_REGISTER_CONFIRM | Confirms read register request. | | CN_FUP_PROGRAM_BEGIN_REQUEST | Begins firmware update programming. | | CN_FUP_PROGRAM_BEGIN_CONFIRM | Confirms program begin. | | CN_FUP_PROGRAM_REQUEST | Firmware update programming data request. | | CN_FUP_PROGRAM_CONFIRM | Confirms firmware programming data request. | | CN_FUP_PROGRAM_END_REQUEST | Ends firmware update programming. | | CN_FUP_PROGRAM_END_CONFIRM | Confirms end of firmware programming. | | CN_FUP_READ_REQUEST | Requests firmware read. | | CN_FUP_READ_CONFIRM | Confirms firmware read request. | | CN_FUP_RESET_REQUEST | Requests firmware reset. | | CN_FUP_RESET_CONFIRM | Confirms firmware reset. |

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.