homebridge-mcz-maestro

Homebridge platform plugin for MCZ Maestro pellet stoves using the MCZ Cloud Socket.IO interface.

This plugin was initially developed and tested with an MCZ Tilda Maestro pellet stove. Other MCZ Maestro models may work, but may need adjusted feature flags or additional protocol mapping.

Features

• MCZ Cloud connection via Socket.IO
• Thermostat service with current and target temperature
• Stove on/off switch
• Automatic/manual mode switch
• Eco Stop switch
• Silent mode switch
• Manual power level 1-5
• Ambient fan with 5 levels
• Ambient fan automatic mode
• Comfort Air fan with 5 levels
• Comfort Air automatic mode
• German state names in Homebridge logs
• Child Bridge friendly HomeKit service names
• Accessory cache-safe runtime handling

Known limitations

• Alarm and fault-code decoding is not enabled yet. It will be added after real alarm telemetry samples are available.
• The MCZ Cloud API is not officially documented. Behavior may vary by stove model, firmware and MCZ cloud changes.
• HomeKit cannot represent every MCZ app control exactly; automatic fan modes are therefore represented as separate switches.

Installation

Install from npm once published:

sudo hb-service add homebridge-mcz-maestro

Or install a local .tgz package on Homebridge:

sudo -H -u homebridge env PATH=/opt/homebridge/bin:/usr/local/bin:/usr/bin:/bin \
/opt/homebridge/bin/npm install --save /var/lib/homebridge/local-tgz/homebridge-mcz-maestro-0.3.1.tgz --prefix /var/lib/homebridge

sudo hb-service restart

Configuration

Example for MCZ Tilda:

{
  "platform": "MCZMaestro",
  "name": "Tilda",
  "server": "http://app.mcz.it:9000",
  "pollInterval": 30,
  "debug": false,
  "stoves": [
    {
      "name": "Tilda",
      "model": "Tilda",
      "serialNumber": "YOUR_SERIAL_NUMBER",
      "macAddress": "YOUR_WIFI_MODULE_MAC",
      "minTemperature": 5,
      "maxTemperature": 35,
      "defaultTargetTemperature": 20,
      "maxCurrentTemperature": 130,
      "features": {
        "eco": true,
        "automaticMode": true,
        "silent": true,
        "ambientFan": true,
        "ambientFanAuto": true,
        "ductedFan1": true,
        "ductedFan1Auto": true,
        "ductedFan2": false,
        "powerLevel": true,
        "alarmReset": false,
        "activeSensor": false,
        "errorSensor": false
      }
    }
  ]
}

Configuration fields

| Field | Description | | --- | --- | | server | MCZ cloud endpoint. Default: http://app.mcz.it:9000 | | pollInterval | Polling interval in seconds. Default: 30 | | debug | Enables detailed protocol logging. Keep false for normal use. | | serialNumber | Stove serial number from the MCZ app/device. | | macAddress | WiFi module MAC address without separators, for example 86F3EB6E0074. | | model | Optional model name, for example Tilda. | | features | Enables/disables HomeKit services per stove. |

HomeKit services

Default short names:

• Heizung
• Betrieb
• Automatik
• Eco Stop
• Silent
• Leistung
• Raumluefter
• Raumluefter Auto
• Comfort Air
• Comfort Air Auto

Logs

Normal log example:

[MCZ] Tilda: Aus; current=26.5; target=14; mode=Automatik; power=1; fan=Level 1; duct1=Disabled; duct2=Disabled; eco=false; silent=false

For protocol analysis, set:

"debug": true

Safety note

Remote control of heating appliances can be dangerous. Only use this plugin with a properly installed, maintained and supervised stove. Follow MCZ safety instructions and local regulations.