ducoboxhttp 0.3.0

Read from and control DucoBox ventilation systems in Node-RED (legacy and public API)

npm install ducoboxhttp

ducoboxHTTP — version 0.3.0

A Node-RED palette for reading from and controlling DucoBox ventilation systems. This version supports two explicitly selectable HTTP interfaces:

• Legacy endpoints (default): preserves the existing endpoints and write commands.
• Public Duco API: uses Duco's local Public API, also used by the current Home Assistant integration. Requires Public API version 2.1 or later.

Public API mode is optional and is not enabled automatically. The data previously shared came from the legacy endpoints; this does not prove that the Public API is available on your unit. First check http://DUCOBOX-IP/api, and select Public API mode only if that API is available.

Upgrade from version 0.2.0 to 0.3.0

Version 0.3.0 adds selectable API interfaces and additional output formats. Follow these steps to upgrade an existing Node-RED installation while keeping existing flows on the legacy interface.

1. Back up your installation

Before upgrading:

1. Export your existing Node-RED flows, including configuration nodes where possible.
2. Keep a copy of your current palette files or make a backup of your Node-RED data directory.
3. Make sure you can restore the previous installation if necessary.

2. Upgrade the palette in Node-RED

1. Open the Node-RED editor.
2. Open the main menu and select Manage palette.
3. Select the Installed tab.
4. Find the installed ducoboxHTTP palette.
5. Click Update or Upgrade if version 0.3.0 is offered.
6. Wait for the update to finish. Restart Node-RED if requested.

If the palette was installed manually rather than through the Palette Manager, update the module using the same installation method that was used originally. Do not overwrite your Node-RED flow files with files from the palette repository.

3. Check the shared DucoBox configuration

Open your existing ducoboxSettings configuration node.

Verify that:

• The IP address or hostname is correct.
• Any configured port is correct.
• API interface is set to Legacy.

The IP address or hostname must not include http:// or a URL path.

Existing configurations without an apiMode setting continue to use legacy mode. Public API mode is optional and must not be enabled automatically during an upgrade.

Save the configuration node if you changed anything.

4. Check the read nodes

Open your existing ducoboxHTTP nodes and verify that they still reference the correct ducoboxSettings configuration node.

For the most compatible upgrade:

• Keep Legacy as the API interface.
• Select JSON as the output format if your existing flows expect the original payload.
• Check the node ID and polling interval.
• Check whether reading immediately when the node starts is enabled.

The default JSON output in legacy mode is intended to preserve the original top-level field names. Existing flows that read fields such as msg.payload.node, msg.payload.devtype, msg.payload.location, msg.payload.trgt or msg.payload.actl should be checked after upgrading.

Do not switch existing flows to Normalized data or Ventilation/airflow data unless you have checked how the changed output structure affects downstream nodes.

5. Deploy and verify reading

1. Click Deploy.
2. Trigger a read or wait for the configured polling interval.
3. Open the Debug sidebar and inspect the received payload.
4. Confirm that the expected node IDs and fields are present.
5. Check that polling continues at the expected interval, if enabled.

Compare the received data with a payload from version 0.2.0 if you have one available.

6. Verify write commands separately

Do not assume that a write command has been applied just because the HTTP request completed.

If you use ducoboxSend, verify the configuration and payload expected by your existing flows. Test a write only when you understand its effect on the ventilation system. Read the node again afterwards to verify its resulting state.

For example, the following legacy command requests the AUTO state:

msg.payload = {
    Operation_State: "AUTO"
};
return msg;

Use only states supported by your DucoBox and the specific node. Available states may vary by device and firmware.

7. Enable Public API mode only if required

You do not need to enable Public API mode to upgrade from 0.2.0 to 0.3.0.

If you want to use it:

1. Check whether http://DUCOBOX-IP/api responds on your local network.
2. Confirm that your DucoBox interface supports Public API version 2.1 or later.
3. Open ducoboxSettings and select Public API.
4. Deploy and test reading before attempting write commands.

Replace DUCOBOX-IP with the actual IP address of your DucoBox.

Public API mode uses different endpoints and response data. Some values provided by legacy endpoints may not be available through the Public API. The node maps available data to the selected output format; missing values may be represented as null.

Troubleshooting after an upgrade

The node cannot connect to the DucoBox

Check the IP address or hostname, port, network connectivity and selected API interface.

Existing flows receive a different payload

Check that the API interface is Legacy and the output format is JSON. Inspect the actual payload in the Debug sidebar before changing downstream nodes.

The nodes are missing or unavailable in the editor

Restart Node-RED and inspect the Node-RED startup log for palette installation or loading errors.

A write command reports an error

Inspect the Node-RED log and the error message. Verify the node ID, command name, value and compatibility of the node type. Read the node again to check the resulting state.

Nodes

ducoboxSettings

• IP address or hostname, optionally with a port; do not include http:// or a path.
• API interface: legacy or public.
• Existing configurations without apiMode continue to use legacy mode.

ducoboxHTTP

• Legacy mode: reads one node using /nodeinfoget?node=<id>.
• Public API mode: reads one node using /info/nodes/<id>, or all nodes using node ID all via /info/nodes.
• Automatic polling at an interval in seconds; 0 disables polling.
• Optionally read immediately when the node starts.
• A read request is not started while a previous request is still running.
• When the node closes, the timer and active HTTP requests are stopped.

Output options:

1. JSON — legacy mode preserves the old payload format. Public API mode maps available values to the same top-level fields; values not provided by the Public API are explicitly set to null.
2. Normalized data — a stable structure containing device fields, sensor readings, and targetFlowLevelPercent.
3. Ventilation/airflow data — target percentage, available valve/motor position, and source data. actualAirflowM3h remains null.

In Public API mode, node ID all sends one message for each discovered node. all is not available in legacy mode. The default JSON output retains the same field names; only legacy mode can add the extra legacy boxinfo fields.

ducoboxSend

• Legacy mode preserves Operation_State, CO2Setpoint, and RHSetpoint.
• Ventilation_State is an alias for Operation_State.
• Public API mode supports Operation_State / Ventilation_State via POST /action/nodes/<id> with the SetVentilationState action.
• Setpoints are deliberately rejected in Public API mode; the current Home Assistant integration does not provide a corresponding setpoint command through the node-action interface.
• Write commands are serialized per host/IP. The queue is limited to 20 commands, including the active command.
• CO2Setpoint is accepted only for VLVCO2 and VLVCO2RH; RHSetpoint is accepted only for VLVRH and VLVCO2RH.
• A successful HTTP response in legacy mode does not guarantee that the setting was applied. Read the node again after writing to verify its state.

Airflow: important limitation

The current Home Assistant integration publishes Target flow level from Ventilation.FlowLvlTgt as a percentage. This is the target/balancing percentage reported by the DucoBox, not a measured air volume in m³/h. The legacy endpoint value trgt is therefore exposed in normalized output as targetFlowLevelPercent.

actl is not interpreted as m³/h. In legacy mode it is preserved separately as legacyActl and is not used to calculate airflow.

Pressure and power fields from /boxinfoget remain raw source values. Without a validated valve characteristic, pressure/airflow relationship, or balancing information, no conversion into m³/h is performed.

The supplied example contained PressureTotal twice in the same JSON object. JSON objects should use unique keys; JSON.parse generally retains only the last value when keys are duplicated. Check the raw response if both values matter.

Examples

Legacy: write a state or setpoint

msg.payload = {
    Operation_State: "AUTO"
};
return msg;

msg.payload = {
    CO2Setpoint: 800
};
return msg;

Public API: set the ventilation state

msg.payload = {
    Ventilation_State: "CNT2"
};
return msg;

Use only states supported by your DucoBox and the specific node. Available states may vary by device and firmware.

Installation

1. Back up your current palette and flows.
2. Install the folder as a Node-RED palette module or place the files in your local Node-RED module directory.
3. Restart Node-RED.
4. Existing configurations default to legacy mode; verify the DucoBox connection before enabling automatic polling on new nodes.
5. Test reading first. Test write commands separately, using a safe state.

For upgrading an existing installation, follow the Upgrade from version 0.2.0 to 0.3.0 instructions above.

Tests and limitations

Run in the development environment:

• node --check ducoboxHTTP.js
• npm test (mock HTTP-server tests for legacy normalization, Public API target level, Public API writes and legacy write behavior)

The automated tests use a mock HTTP server and do not require a physical DucoBox.

Not tested: operation against every physical DucoBox model or firmware, or every possible live Node-RED installation. Public API mode must therefore be validated against your specific board/firmware first.

The current code does not calculate actual airflow in m³/h and does not implement CO₂/RH setpoints through the Public API.

Compatibility notes

• Legacy mode is the default for existing configurations without apiMode.
• JSON is the recommended output format for existing flows.
• Normalized and ventilation/airflow formats have different payload structures; check downstream nodes before switching.
• Public API availability depends on the DucoBox hardware and firmware.
• Actual airflow in m³/h is not calculated by this palette.