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.

Hardware revisions:

DUCO Connectivity Board 1.0: Supported
DUCO Connectivity Board 2.0: Not tested

Compatible DucoBox models:

DucoBox Silent Connect
DucoBox Focus (from firmware version 17xxxx)
DucoBox Hygro Plus
DucoBox Energy Comfort / Energy Comfort Plus
DucoBox Energy Premium

Supported sensor modules

The following sensor module types are supported:

BOX: The main ventilation box; provides fan control, ventilation state, Wi-Fi signal strength, and temperature (measured inside the housing; disabled by default).
UCCO2: Wall-mounted CO₂ sensor unit; provides CO₂ concentration, CO₂ air quality index, and temperature.
BSRH: Humidity sensor module installed in the duct inlet of the DucoBox, wired directly to the PCB via cable; provides relative humidity, humidity air quality index, and temperature.
UCRH: Wireless humidity sensor module; provides relative humidity, humidity air quality index, and temperature.

Unsupported sensor modules

The following sensor module types are discovered but not yet supported:

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

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

The Duco system consists of multiple nodes. Each node appears as a separate device in Home Assistant, connected to the main ventilation box:

BOX: The main DucoBox (fan control, ventilation state)
UCCO2: A wall-mounted control unit with a built-in CO₂ sensor
BSRH: A humidity sensor module installed in the duct inlet of the DucoBox
UCRH: A wireless humidity sensor module

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. Setting the speed to 0% returns control to Duco (automatic mode), after which the firmware automatically resumes ventilation.

The following actions are available:

Speed 0%: Hands control back to Duco (automatic mode).
Speed 33%: Low speed manual override.
Speed 66%: Medium speed manual override.
Speed 100%: High speed manual override.
Auto preset: Same as speed 0%; hands control back to Duco.

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).

Sensors

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

Ventilation state

Available for the main ventilation box (BOX). Shows the current ventilation state, for example:

Automatic
Continuous high speed
Manual low speed (15 min)

CO₂ concentration

Available for CO₂ sensor modules. Shows the current CO₂ concentration in parts per million (ppm).

Humidity

Available for humidity sensor modules (BSRH, UCRH). Shows the current relative humidity in percent.

CO₂ air quality index

Available for CO₂ sensor modules. 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 humidity sensor modules (BSRH, UCRH). 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

Temperature

Available for the external sensor modules (UCCO2, BSRH, and UCRH). Shows the current air temperature in degrees Celsius measured by the sensor module.

The main ventilation box (BOX) also provides a temperature reading. This entity is disabled by default because it reflects the temperature inside the box housing, which is typically not representative of the room temperature.

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.
Use temperature readings from sensor modules to detect rooms that are too hot or too cold and adjust ventilation accordingly.

Examples

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.living_ventilation
      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.living_ventilation
      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.living_ventilation
      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.living_ventilation
      data:
        percentage: 66

Boost ventilation when CO₂ is high

This automation switches to high speed when the CO₂ level in the office rises above 1000 ppm, 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.office_co2_carbon_dioxide
      above: 1000
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.living_ventilation
      data:
        percentage: 100

- alias: "Return to auto when CO2 is low"
  triggers:
    - trigger: numeric_state
      entity_id: sensor.office_co2_carbon_dioxide
      below: 800
  actions:
    - action: fan.set_percentage
      target:
        entity_id: fan.living_ventilation
      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 30 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

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.

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.