Daikin DZK Zoning (BACnet)

Local BACnet/IP integration for the Daikin DZK zoning kit through its BACnet interface. The interface is made by Airzone and is listed by its BACnet vendor name, "Altra". One DZK hub controls up to 6 zones on a single indoor unit. The daikin_dzk driver makes each DZK zone look like an ordinary thermostat (room temperature, heat and cool setpoints, system_mode), so the climate_default zone control, voice commands and macros drive it like any other climate zone.

The driver is a superset of BACnet / IP. Discovery, the raw read/write commands, COV and the attribute-mapped zones all keep working on the same device. It can sit alongside a BACnet / IP device in the same GEM: devices on the same interface and port share one UDP socket (see Sharing the BACnet port). One daikin_dzk device can also serve several DZK hubs.

Status: beta

The object numbering follows the DZK manual and matches a live unit's object list. The driver has not been tested in every operation mode on real hardware, or with more than one hub on a single device. Setpoint units, mode writes on VRV slave units, and the DZK error encoding (see Limitations) also need confirming on site.

What this integration covers

• Per-zone thermostat: room temperature, heat and cool setpoints, humidity, cooling/heating/auxiliary-heating demand, damper position, and the zone's own ON/OFF.
• Mode: the hub's operation mode (auto, cool, heat, dry, emergency heat) combined with each zone's ON/OFF into one system_mode per zone.
• Fan mode per zone: on runs the zone's fan without heating or cooling (the DZK's local ventilation), auto leaves the fan to the heating and cooling demand. Plus the vacation and unoccupied override flags for each zone.
• System zone (optional): user mode (stop, comfort, unoccupied, night, eco, vacation), the indoor-unit setpoint, fan speed, running state, alarm input, auxiliary heat stages, communication error, the decoded indoor-unit error code and the DZK error.
• Polling with ReadPropertyMultiple. The driver falls back to single reads if the hub rejects ReadPropertyMultiple, and backs off when a hub stops answering.

Prerequisites

• The DZK BACnet interface installed and on the same IP subnet as the GEM host. A hub on another subnet can be reached by adding its IP to bacnet_static_peers or by using a BBMD.
• The hub's BACnet device instance. The factory default is 1000. who_is lists it.
• The BACnet product in your license.

Setup steps

1. Go to System → Devices → Add Device and choose Daikin DZK Zoning (BACnet). Leave the IP blank to pick the network interface automatically, or enter the local interface to bind to.
2. Save, then run who_is, or wait for the first discovery pass. Confirm the hub's device id appears.
3. If more than one BACnet device answers, set dzk_device_id to the hub's device id. With exactly one device on the network, the driver uses it automatically.
4. Open the device's Setup tab. It lists every installed zone on each DZK hub, plus each hub's system zone, and shows which already have a GEM zone. Click Sync from device to create the missing ones, or run the sync_zones command. See Creating zones automatically.
5. About 30 seconds after connecting, the first poll fills in temperatures, setpoints and modes.

To create zones by hand instead, add a climate zone per DZK zone with address 1 to 6 and the climate_default control, and optionally one with address system for the hub-wide mode and indoor-unit status.

Creating zones automatically

list_zones finds the DZK hubs among the devices that answered Who-Is: the one set in dzk_device_id, and any whose BACnet model name contains "DZK". For each hub it reads the six zone temperature inputs. A zone whose input reports out of service has no thermostat installed and is left out. Each hub's system zone is always listed.

Every zone left out is explained under the list on the Setup tab:

• Out of service above the highest installed zone — unused zone slots, listed together on one line.
• Out of service below an installed zone — for example zone 2 on a hub with zones 1, 3 and 4. The hub has lost that thermostat, or the thermostat is set to another zone's number. Check that it is powered, wired to the DZK board and set to the right zone, then run discovery again.
• Temperature read failed — the hub didn't return the zone's temperature input. The note gives the BACnet error.

sync_zones creates a climate zone with the climate_default control for every listed zone that has no GEM zone yet:

• Labels come from the hub's BACnet device name, for example East Wing Zone 1 and East Wing System. A hub with no name is labelled DZK <device id>.
• Addresses are 1 to 6 and system on the default hub, and <device id>:<n> on any other hub. A bare address already used by an ordinary BACnet / IP zone is also given the <device id>: form.
• Existing zones are never changed. A zone already serving that hub and zone number, under either address form, is skipped, and so is one you have disabled. Running it again creates nothing new.
• Pass include_system: false to leave out the system zones.

Nothing runs automatically. Zones are only created when you sync.

Zone addressing

Address	Meaning
1 … 6	DZK zone on the default hub (dzk_device_id, or the only device found).
<device id>:<n>	DZK zone n on another hub, for example 1001:2.
system	System zone of the default hub.
<device id>:system	System zone of another hub, for example 1001:system.
anything else	An ordinary BACnet/IP zone mapped with bacnet_*_read / bacnet_*_write attributes. See BACnet / IP.

A zone that has bacnet_*_read / bacnet_*_write point attributes is always treated as an ordinary BACnet/IP zone, even if its address is a number from 1 to 6.

Attribute reference

Device attributes

Name	Type	Description
dzk_device_id	int	BACnet device instance of the default hub (factory default 1000). If it is unset and exactly one BACnet device has answered Who-Is, the driver uses that device.
dzk_poll_interval	int	How often each hub is read, in ms. Default 10000, minimum 2000.
priority	int	BACnet write priority for DZK writes (default 16). A zone's own priority attribute (1–16) overrides it for that zone.
port, bacnet_static_peers, bbmd_address, …		Inherited from BACnet / IP.

Thermostat zone attributes

Name	Type	Source	Description
temperature	int / float	AI n−1	Room temperature, in the hub's units.
heat_setpoint	int / float	AV 2n−1	Heating setpoint (hub range 59–86 °F / 15–30 °C).
cool_setpoint	int / float	AV 2n	Cooling setpoint (hub range 64–86 °F / 18–30 °C).
humidity	int / float	AV 32+n	Relative humidity, %.
cooling_demand / heating_demand / aux_heating_demand	int	AV 12+3n / 13+3n / 14+3n	Demand, %.
power	string	BV 4n−1	on / off: the zone's own ON/OFF.
system_mode	string	composed	off when the zone is off, otherwise the hub's operation mode (auto, cool, heat, dry, emergency_heat).
fan_mode	string	BV 4n	on when the zone's local ventilation is enabled, otherwise auto.
vacation_override / unoccupied_override	bool	BV 4n+1 / 4n+2	Override flags (read only).
damper_position	int	MSV n−1	Damper opening: 0, 25, 50, 75 or 100 %.
system_modes	json	seeded	The modes the climate control offers. Set once to {"0":"off","1":"auto","2":"cool","3":"heat","4":"dry","5":"emergency_heat"} if the zone has none.
fan_modes	json	seeded	Set to {"0":"auto","1":"on"} if the zone has none, so the climate control shows Auto and On fan buttons. Remove on to hide the On button.
min / max	int	seeded	Setpoint limits. Set once, if unset, from the hub's units: 59/86 for °F, 15/30 for °C.

Temperatures and setpoints are rounded to whole numbers unless the zone or device sets decimal_places.

system_modes maps numbers to names on purpose, because the climate control shows a mode button only when the name appears among the map's values. To hide modes, remove entries, for example delete "5" to hide emergency heat. The driver never overwrites an existing value. If the attribute is deleted, the driver seeds it again.

System zone attributes

Name	Type	Description
system_mode	string	off when the user mode is stop, otherwise the operation mode.
system_modes	json	Seeded the same way as on thermostat zones.
user_mode	string	stop, comfort, unoccupied, night, eco or vacation.
iu_setpoint	int / float	Indoor-unit setpoint (read only).
iu_fan_speed	string	low, medium or high (status only).
iu_running	bool	Indoor unit running.
alarm_input	bool	System alarm input. While it is active the system is held in stop.
global_ventilation, aux_heat1, aux_heat2	bool	Hub-wide outputs (read only).
comm_error	bool	Communication error between the DZK board and the BACnet board.
iu_error	string	Daikin indoor-unit error code, for example U4. Empty when there is no error. If the value falls outside the code table, this shows the raw number.
iu_error_raw	int	The raw indoor-unit error value.
dzk_error	int	0 normal, 9 DZK control board ↔ interface board communication, 10 BACnet interface fault, 11 indoor unit ↔ interface board communication.
dzk_error_text	string	Description of dzk_error.

Zones are marked disconnected when their reads fail. A thermostat zone is also marked disconnected when its temperature input reports out-of-service, which is how the hub reports a zone with no thermostat installed. Values from such a zone are not written.

Commands

Command	Args	Notes
system_mode	address, mode	See Mode semantics. mode is off, on, auto, cool, heat, dry, emergency_heat, or 1–5.
on / off	address	On a DZK zone, switches that zone. On the system zone, off sets user mode stop and on leaves stop for comfort.
setpoint	address, setpoint, mode	mode heat or cool picks the setpoint. Without a mode, the hub's operation mode decides: heat or emergency heat writes the heat setpoint, and cool writes the cool setpoint. In auto or dry the command returns an error asking for a mode. Values outside the zone's min/max are rejected.
fan_mode	address, mode	auto or on (0 / 1). Any other mode is rejected. Not available on the system zone.
user_mode	address, mode	stop, comfort, unoccupied, night, eco, vacation, or 1–6. Accepts any address on the hub.
get_status	address	Reads the hub now and returns the zone's values.
list_zones	—	Lists each DZK hub's installed zones and system zone, with the address each would get and whether a GEM zone already has it. Creates nothing.
sync_zones	include_system	Creates the missing zones. See Creating zones automatically.
get_temperature / get_system_mode / get_setpoint / get_fan_mode	address	Return the last polled values for a DZK zone.

Every other command (who_is, read_value, write_value, get_objects, COV, alarms, …) works exactly as on BACnet / IP. On an ordinary BACnet/IP zone, system_mode and setpoint keep their BACnet/IP behaviour, including the occupancy and priority arguments.

After each write, the driver updates the zone at once and reads the hub again about 1.5 seconds later to confirm.

Mode semantics

The DZK has one operation mode for the whole system, shared by every zone, and a separate ON/OFF for each zone. The hub has no "off" operation mode. GEM combines these into a single system_mode per zone:

• Turning a zone off turns off only that zone. Its damper stays open, but the zone stops calling for heating or cooling.
• Choosing a mode on any zone (cool, heat, …) changes the operation mode for every zone on that hub, and also turns on the zone you changed. Other zones that are on show the new mode straight away. Zones that are off stay off.
• The system zone controls the whole system. off sets the user mode to stop, which holds every zone off. Choosing a mode while stopped also switches the user mode to comfort, so the system starts.

Limitations

• Fan mode is on or auto only. A zone's fan mode is its local-ventilation switch. The DZK interface reports the indoor-unit fan speed (iu_fan_speed on the system zone) but does not let you change it, so there is no low/medium/high. Ventilation only runs if the DZK installer has enabled it for the zone.
• On VRV systems, a slave unit's mode may be restricted by the master indoor unit. If the hub refuses a mode write, the command returns an error.
• The DZK error is documented two ways. The manual's object list gives the DZK error states as 1/2/3, and its text gives the raw values 9/10/11. The driver accepts both and reports 9/10/11.
• There are no push updates yet. The hub supports COV, but the driver polls on dzk_poll_interval. A change made at a DZK thermostat appears at the next poll.
• Setpoint limits depend on the hub's units. The driver seeds min/max only after it has read the hub's temperature units. If that read fails, set min/max on each zone yourself, because the climate control otherwise assumes 60–90.
• The BACnet Explorer lists DZK devices alongside BACnet / IP ones. Use it to browse the hub's objects, read their properties and check the Diagnostics tab.

Troubleshooting

Symptom	Check
All zones stay disconnected	Run who_is and confirm the hub answers. If more than one device is listed, set dzk_device_id.
One zone stays disconnected	No thermostat is installed on that zone number, so the hub reports it out of service. Check the address.
Mode buttons are missing	Delete the zone's system_modes attribute so the driver seeds it again, or make sure it maps numbers to mode names.
setpoint needs mode heat or cool	The hub is in auto or dry. Send mode heat or cool. The climate control does this automatically when the zone has both setpoints.
Bind error on port 47808	Another program on the GEM host, not a GEM device, owns the port. GEM devices share it. Stop the other program, or give this device a different port.
Writes fail	Check the write priority and the hub's setpoint range (heat 59–86 °F / 15–30 °C, cool 64–86 °F / 18–30 °C).

Example

A single hub at the factory device id, two zones and the system zone:

Zone	Address	Control
Living Room	1	climate_default
Bedroom	2	climate_default
DZK System	system	climate_default

Device attributes: dzk_device_id = 1000. If the hub is on another subnet, also set bacnet_static_peers = 192.0.2.40.