This package allows for communication between a Ducobox ventilation unit and an MQTT service. It was tested using Home Assistant's built-in MQTT broker.
This package supports the use of a different communication protocol for reading of parameters and control of the unit. Currently, only direct serial communication is supported for reading, and only GPIO is supported for control, but implementing further types is pretty easy. I'm open to pull requests.
There is a 5-pins serial connector on the Ducobox main board. You can create a simple cable that allows for direct communication from a Raspberry Pi or a serial UART. The port is talked about in-depth in this forum thread (in Dutch). Apparently the port uses 3.3V TTL, but is 5V tolerant. The pins are (from right to left):
- TX (from Duco)
- RX (to Duco)
- Unknown
- GND
- Vcc (3.3V)
To build a cable, I used the following parts:
- 1x JST PHR-5 (connector)
- 5x JST SPH-002T-P0.5S (crimp socket)
- 1x MOLEX 50-57-9405 (connector)
- 5x MOLEX 16-02-0107 (crimp pin)
- ca 30 cm 3M 3365-10 (ribbon-kabel)
Control of the box is not possible through the serial protocol (this was confirmed to me by Duco). So, to get around this, I added a two-channel relay board that emulates a manual 3-position switch (section 5A in the Quick Start Guide). This allows setting the box to modes CNT1, CNT2 and CNT3. I wired it up like this:
L1 goes to the power input that also goes to the main board of the ducobox, and L2 and L3 go to the 3-position switch ports, as found in the QSG. The relays are controlled by GPIO 17 and 27. With the board I'm using, the relays are active-low (they're flipped when the GPIO is driven low).
The MQTT client used is paho. It's one of the most widely-used MQTT clients for Python, so it should work on most brokers. If you're having problems with a certain type, please open an issue or send me a pull request with a fix.
The configuration for the bridge is located in config.json.
{
"duco" : {
"type": "serial",
"device": "/dev/serial0",
"baudrate": 115200
},
"control": {
"type": "gpio",
"active_low": true,
"states": {
"CNT1" : {
"17": 0,
"27": 0
},
"CNT2" : {
"17": 1,
"27": 0
},
"CNT3" : {
"17": 0,
"27": 1
}
}
},
"mqtt" : {
"client_id": "duco",
"host": "127.0.0.1",
"port": 1883,
"keepalive": 60,
"bind_address": "",
"username": null,
"password": null,
"qos": 0,
"pub_topic_namespace": "value/duco",
"sub_topic_namespace": "set/duco",
"retain": true
}
}To install this script as a daemon, run the following commands (on a Debian-based distribution):
- Install dependencies:
sudo apt install python python-serial
- Create a new folder, for example:
sudo mkdir -p /usr/lib/py-duco-mqtt cd /usr/lib/py-duco-mqtt - Clone this repository into the current directory:
sudo git clone https://github.com/martenjacobs/py-duco-mqtt.git . - Change
config.jsonwith your favorite text editor - Copy the service file to the systemd directory. If you used a different folder name than
/usr/lib/py-duco-mqttyou will need to change theWorkingDirectoryin the file first.sudo cp ./py-duco-mqtt.service /etc/systemd/system/
- Enable the service so it starts up on boot:
sudo systemctl daemon-reload sudo systemctl enable py-duco-mqtt.service - Start up the service
sudo systemctl start py-duco-mqtt.service
- View the log to see if everything works
journalctl -u py-duco-mqtt.service -f
By default, the service publishes messages to the following MQTT topics:
- value/duco => service on-line status
- value/duco/network/1/stat => state
- value/duco/network/1/info => info
- value/duco/network/4/stts => stts
- value/duco/network/1/%dbt => dbt (%)
- value/duco/network/1/trgt => target value (???)
- value/duco/network/1/cntdwn => countdown (s)
- value/duco/temp => temperature (ºC)
- value/duco/co2 => CO2 (ppm)
- value/duco/humi => Humidity (%)
- value/duco/fan/Filtered => filtered fan speed (rpm)
- value/duco/fan/Actual => actual fan speed (rpm)
If you've changed the pub_topic_namespace value in the configuration, replace
value/ducowith your configured value. TODO: Improve description of all topics
By default, the service listens to messages from the following MQTT topics:
- set/duco/state => state
If you've changed the sub_topic_namespace value in the configuration, replace
set/ducowith your configured value. TODO: Improve description of all topics
The following configuration can be used in Home Assistant:
sensor duco:
- platform: mqtt
state_topic: "value/duco"
name: "DUCO service on-line"
- platform: mqtt
state_topic: "value/duco/network/1/stat"
name: "DUCO state"
- platform: mqtt
state_topic: "value/duco/network/1/info"
name: "DUCO info"
- platform: mqtt
state_topic: "value/duco/network/4/stts"
name: "DUCO stts"
- platform: mqtt
state_topic: "value/duco/network/1/%dbt"
name: "DUCO dbt"
unit_of_measurement: '%'
- platform: mqtt
state_topic: "value/duco/network/1/trgt"
name: "DUCO target value"
unit_of_measurement: '???'
- platform: mqtt
state_topic: "value/duco/network/1/cntdwn"
name: "DUCO countdown"
unit_of_measurement: 's'
- platform: mqtt
state_topic: "value/duco/temp"
name: "DUCO temperature"
unit_of_measurement: 'ºC'
- platform: mqtt
state_topic: "value/duco/co2"
name: "DUCO CO2"
unit_of_measurement: 'ppm'
- platform: mqtt
state_topic: "value/duco/humi"
name: "DUCO Humidity"
unit_of_measurement: '%'
- platform: mqtt
state_topic: "value/duco/fan/Filtered"
name: "DUCO filtered fan speed"
unit_of_measurement: 'rpm'
- platform: mqtt
state_topic: "value/duco/fan/Actual"
name: "DUCO actual fan speed"
unit_of_measurement: 'rpm'
fan mqtt:
- platform: mqtt
name: "Ducobox"
command_topic: "set/duco"
state_topic: "value/duco"
payload_on: "online"
payload_off: "offline"
speed_state_topic: "value/duco/network/1/stat"
speed_command_topic: "set/duco/state"
qos: 0
payload_low_speed: "CNT1"
payload_medium_speed: "CNT2"
payload_high_speed: "CNT3"
speeds:
- low
- medium
- high