Home ▸ Integrations

Duco

The Duco integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to monitor and control Duco demand-controlled ventilation (DCV) systems from Home Assistant. Duco produces ventilation boxes for residential buildings that regulate air quality based on CO₂ and humidity sensors. This integration communicates locally with the Duco box over your home network, requiring no cloud connection.

Supported devices

This integration communicates with the DUCO Connectivity Board (article 0000-4810) via its local REST API over Wi-Fi or Ethernet.

To set up the integration, your Duco system must expose the DUCO Connectivity Board API with public API version 2.1 or newer.

Hardware revisions:

DUCO Connectivity Board 1.0: Supported
DUCO Connectivity Board 2.0: Supported

Validated DucoBox models:

DucoBox Silent Connect

Older Duco systems using the Communication Board V1 are not supported because they do not expose the required API surface.

Other Duco systems that expose public API version 2.1 or newer can be set up, but some model-specific functionality may still be limited until it has been validated and implemented.

Supported node types

The following node types are supported:

BOX: The main ventilation box; provides fan control, ventilation state, target flow level, state end time, and Wi-Fi signal strength.
UCCO2: Wall-mounted CO₂ sensor unit; provides CO₂ concentration and CO₂ air quality index.
BSRH: Humidity sensor module installed in the duct inlet of the DucoBox, wired directly to the PCB via cable; provides relative humidity and humidity air quality index.
UCRH: Wireless humidity sensor module; provides relative humidity and humidity air quality index.
VLVCO2: Valve actuator with a built-in CO₂ sensor; provides CO₂ concentration and CO₂ air quality index.
VLVRH: Valve actuator with a built-in humidity sensor; provides relative humidity and humidity air quality index.
VLVCO2RH: Valve actuator with built-in CO₂ and humidity sensors; provides CO₂ concentration, CO₂ air quality index, relative humidity, and humidity air quality index.

Unsupported node types

The following node types are discovered but not yet supported:

UC: Universal control unit (no sensor data exposed)
UCBAT: Battery-powered sensor module
VLV: Valve actuator without exposed sensor data

When Home Assistant discovers a node with an unsupported type, it logs a warning and skips that node. All other nodes continue to work normally.

Prerequisites

A Duco ventilation box with a DUCO Connectivity Board connected to your local network.

Configuration

To add the Duco hub to your Home Assistant instance, use this My button:

Duco can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.

Manual configuration steps

If it wasn’t discovered automatically, don’t worry! You can set up a manual integration entry:

Browse to your Home Assistant instance.
Go to Settings > Devices & services.
In the bottom right corner, select the Add Integration button.
From the list, select Duco.
Follow the instructions on screen to complete the setup.

Host

The IP address or hostname of your DUCO Connectivity Board on the local network, for example 192.168.1.10. Only needed when setting up the integration manually.

Supported functionality

Each supported node appears as a separate device in Home Assistant, connected to the main ventilation box. The sections below describe which entities Home Assistant creates for those supported node types.

Fan

The fan entity lets you control the ventilation speed of a node. You can set the speed as a percentage or switch back to automatic mode.

The fan is always on. Turning off the fan is not supported.

Setting a speed percentage to 33%, 66%, or 100% activates a continuous override with no time limit. Setting it to 0% clears the override and hands control back to Duco:

Speed 0%: Clears the override and returns to automatic mode.
Speed 33%: Continuous low speed override.
Speed 66%: Continuous medium speed override.
Speed 100%: Continuous high speed override.
Auto preset: Same as speed 0%. Clears the override and returns to automatic mode.

When a connected wall unit (such as a UCCO2) triggers a timed speed override on the Duco box, Home Assistant reflects the current ventilation level as a percentage. These timed states cannot be set from Home Assistant; writing a speed always uses the permanent manual mode (a continuous override with no time limit).

Note

The percentages 33%, 66%, and 100% are abstract speed levels used in the Home Assistant fan UI and do not match the actual airflow percentages configured in the Duco firmware. To see the real airflow target, use the Target flow level sensor.

Sensors

The following sensor entities are created per node, depending on the node type:

Target flow level

Available for the main ventilation box (BOX). Shows the actual airflow target as reported by the Duco box, as a percentage (0–100%). This value reflects the real airflow configured in the Duco firmware and differs from the abstract speed levels (33%, 66%, or 100%) shown in the fan entity. For example, if your Duco system is configured with manual speed levels of 15%, 30%, and 100%, this sensor shows those values.

Ventilation state

Available for the main ventilation box (BOX). Shows the ventilation state using the Duco state codes shown by the device and app, instead of friendly labels with fixed meanings.

Common values include:

AUTO: Automatic mode.
AUT1, AUT2, AUT3: Automatic mode currently running at low, medium, or high airflow.
CNT1, CNT2, CNT3: Continuous low, medium, or high speed override.
MAN1, MAN2, MAN3: Timed manual low, medium, or high speed override.
EMPT: Empty house mode.

CNT states are continuous overrides.

MAN states are timed overrides, but the timer duration is configured on the Duco system and is not encoded in the raw state value itself. Some systems may also report compatibility values like MAN1x2 or MAN1x3 for timed manual modes.

To see when a timed state ends, use the State end time sensor.

State end time

Available for the main ventilation box (BOX). Shows the time at which the current timed ventilation state ends. When no timer is active, this sensor is unavailable.

CO₂ concentration

Available for CO₂ sensor modules and valve actuators with a built-in CO₂ sensor. Shows the current CO₂ concentration in parts per million (ppm).

Humidity

Available for the supported node types with a built-in humidity sensor listed in Supported node types. Shows the current relative humidity in percent.

CO₂ air quality index

Available for CO₂ sensor modules and valve actuators with a built-in CO₂ sensor. Shows the CO₂ air quality score as a percentage (0–100%). This entity is disabled by default.

Indoor air quality ranges for CO₂:

90–100%: Very good
75–85%: Good
50–70%: Temporarily acceptable
35–45%: Poor

Humidity air quality index

Available for the supported node types with a built-in humidity sensor listed in Supported node types. Shows the humidity air quality score as a percentage (0–100%). This entity is disabled by default.

Indoor air quality ranges for humidity:

95–100%: Very good
65–90%: Good
35–50%: Temporarily acceptable
5–20%: Poor

Wi-Fi signal strength

Available for the main ventilation box (BOX). Shows the Wi-Fi signal strength in dBm. This entity is disabled by default.

Use cases

Switch to high ventilation automatically when cooking or showering.
Return to auto mode when everyone leaves home using a presence-based automation.
Monitor ventilation activity over time via the logbook.
Trigger automations based on CO₂ levels or humidity reported by connected Duco modules.

Examples

The example entity IDs below use the default naming that Home Assistant assigns on a new Home Assistant installation. Replace them with the entity IDs from your own system.

Activate high ventilation while cooking

This automation switches the ventilation to high speed when the kitchen hood is turned on, and returns it to automatic mode five minutes after the hood is switched off.

- alias: "High ventilation while cooking"
  triggers:
    - trigger: state
      entity_id: switch.kitchen_hood
      to: "on"
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.node_1
      data:
        percentage: 100

- alias: "Return to auto after cooking"
  triggers:
    - trigger: state
      entity_id: switch.kitchen_hood
      to: "off"
      for: "00:05:00"
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.node_1
      data:
        percentage: 0

Reduce ventilation when nobody is home

When the last person leaves home, the ventilation hands control back to Duco (automatic mode). When someone returns, it switches to medium speed.

- alias: "Ventilation auto mode on leave"
  triggers:
    - trigger: numeric_state
      entity_id: zone.home
      below: 1
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.node_1
      data:
        percentage: 0

- alias: "Ventilation medium speed on arrive"
  triggers:
    - trigger: numeric_state
      entity_id: zone.home
      above: 0
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.node_1
      data:
        percentage: 66

Boost ventilation when CO₂ is high

This automation switches to high speed when the CO₂ level rises above 1000 ppm on a UCCO2 sensor module, and returns to automatic mode when it drops back below 800 ppm.

- alias: "Boost ventilation on high CO2"
  triggers:
    - trigger: numeric_state
      entity_id: sensor.node_2_carbon_dioxide
      above: 1000
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.node_1
      data:
        percentage: 100

- alias: "Return to auto when CO2 is low"
  triggers:
    - trigger: numeric_state
      entity_id: sensor.node_2_carbon_dioxide
      below: 800
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.node_1
      data:
        percentage: 0

Boost ventilation when humidity is high

This automation switches to medium speed when relative humidity rises above 70% on a UCRH or BSRH sensor module, and returns to automatic mode when it drops back below 60%.

- alias: "Boost ventilation on high humidity"
  triggers:
    - trigger: numeric_state
      entity_id: sensor.node_113_humidity
      above: 70
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.node_1
      data:
        percentage: 66

- alias: "Return to auto when humidity is normal"
  triggers:
    - trigger: numeric_state
      entity_id: sensor.node_113_humidity
      below: 60
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.node_1
      data:
        percentage: 0

Data updates

The integration pollsData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] the Duco box every 10 seconds. If you add a new sensor module (such as a CO₂ or humidity sensor) to your Duco system after the integration is already set up, it will automatically appear in Home Assistant the next time the integration polls for data. No restart or reconfiguration required.

Known limitations

New setup requires a DUCO Connectivity Board that exposes public API 2.1 or later. Older systems using the Communication Board V1 are not supported. Other systems on the same API surface can be set up, but some model-specific functionality may still be limited until it has been validated and implemented.
The Duco box enforces a rate limit of 200 write requests per day. When the limit is reached, the integration shows a notification and stops sending write requests until the quota resets automatically around midnight.
Timed speed overrides set by a connected wall unit (such as a UCCO2) cannot be triggered from Home Assistant. They are read-only: the current ventilation level is shown as a percentage, but setting a speed from Home Assistant always uses the permanent manual mode (a continuous override with no time limit).
When you deregister a sensor module via the Duco app or firmware, the node disappears from the Duco API and Home Assistant removes it automatically on the next data update. However, a BSRH humidity sensor that is physically disconnected from the box PCB (rather than deregistered via software) is not treated as deregistered by the firmware. Its node remains in the API indefinitely, so its entities will stay in Home Assistant until you deregister it through the Duco app.

Troubleshooting

Device is not automatically discovered

If your Duco ventilation box is not automatically discovered:

Ensure the device is powered on and connected to the same network as Home Assistant.
Check that mDNS/Bonjour traffic is not blocked by your router or firewall. If it is, the integration can still discover the device automatically via DHCP the next time the device renews its IP address lease.
Verify the device name shows as “DUCO [MAC address]” in your router’s device list or network scanner.
Manually add the integration using the device’s IP address if discovery continues to fail.

Cannot connect to the Duco box

Symptom

The integration setup fails with a “Cannot connect” error, or all entities show as unavailable after the integration was working correctly.

Description

Home Assistant cannot reach the Duco box at the configured address. This can happen during initial setup or later during operation if the box is restarted, loses power, or its IP address changes.

Resolution

Check that the Duco box is powered on and connected to your local network.
Confirm the IP address or hostname is correct by opening http://<host> in a browser on your local network.
If the box is reachable but entities are still unavailable, reload the integration via Settings > Devices & services > Duco > Reload.
If the Duco box received a new IP address from your router, Home Assistant updates the address automatically the next time the box is discovered via mDNS/Bonjour (zeroconf). If that does not happen, see Reconfiguring the integration.

Setup says this Duco system is not supported

Symptom

Manual setup stops with this message:

This Duco system is not supported by this integration. The integration requires a Duco Connectivity Board running public API 2.1 or newer.

Description

Home Assistant could reach the Duco device, but the detected system does not expose the required API surface for setup. The integration requires a DUCO Connectivity Board with public API version 2.1 or later.

This can happen when your system uses an older Communication Board V1, or when the board firmware does not expose public API 2.1 or later.

Resolution

Confirm that your system uses a DUCO Connectivity Board.
Check whether the board firmware exposes public API 2.1 or later.
If your system uses the older Communication Board V1, Home Assistant cannot set up the integration for that system.
If your system does not meet these requirements, Home Assistant cannot set up a new integration for that system.
If your system should be supported, collect diagnostics and open an issue in Home Assistant Core with your Duco model, board details, and firmware information.

Failed to set ventilation state (rate limit)

Symptom

Setting the fan speed or preset mode fails with a notification in the Home Assistant UI:

The Duco device has reached its daily write limit. Try again tomorrow.

Description

The Duco box enforces a write rate limit of 200 write requests per day. When the limit is reached, the box rejects further write requests until the quota resets around midnight.

Resolution

Wait until midnight for the quota to reset. To avoid hitting the limit, reduce the frequency of automations that change the ventilation state.

Reconfiguring the integration

If your Duco ventilation box gets a new IP address, you can update it without removing and re-adding the integration.

When zeroconf discovery is available, Home Assistant updates the address automatically. If that does not happen, you can update it manually:

Go to Settings > Devices & services.
Find the Duco integration and select it.
Select the three dots menu next to the integration and choose Reconfigure.
Enter the new IP address or hostname and select Submit.

Home Assistant verifies that the new address belongs to the same Duco box. If you enter the address of a different device, the reconfiguration is aborted.

Removing the integration

This integration follows standard integration removal, no extra steps are required.

To remove an integration instance from Home Assistant

Go to Settings > Devices & services and select the integration card.
From the list of devices, select the integration instance you want to remove.
Next to the entry, select the three dots menu. Then, select Delete.

Help us improve our documentation

Suggest an edit to this page, or provide/view feedback for this page.