Firmware version

All information on this page applies to firmware R010 and later.

Emma thermostat

This page describes the Zigbee communication interface of the Plugwise Emma thermostat.

It is intended for developers integrating Emma with Zigbee-based coordinators and software platforms such as Home Assistant (ZHA) or Zigbee2MQTT.

Emma communicates using the Zigbee protocol and exposes standard Zigbee clusters and attributes, as described in this document.

Overview

Emma is a thermostat that can operate in different hardware and power configurations. Depending on the backplate, boiler connection, and available power, Emma may join the Zigbee network as either:

• a Router
• a Sleepy End Device (SED)

Emma exposes standard Zigbee Home Automation thermostat functionality as well as a small set of Plugwise manufacturer-specific attributes for advanced boiler control and diagnostics.

---

1. Device Identification

Field	Value
Manufacturer Name	Plugwise
Model Identifier	170-01
Zigbee Profile ID	0x0104 (Home Automation)
Zigbee Device Type	0x0301 — HA Thermostat (code 769)
Endpoint	1
Manufacturer Code	0x1172
Product Code	"OpenTherm" / "OnOff" / "OpenTherm/OnOff" / "Wireless" — see §3
Product URL	https://www.plugwise.com/emma-wired-pro

Product variants and network role

Product	Power source	Network role
Emma Wired Pro	OpenTherm Smart Power	Router
Emma Wired Pro	OpenTherm	SED
Emma Wired Pro	On/Off boiler: Batteries	SED
Emma Wireless	USB-C 5 V	Router
Emma Wireless	AA batteries	SED
Emma Essential	-	Can be upgraded to Emma Wired Pro to enable communication via zigbee.

Please note that role might be automatically switched from Router to SED when changing to a power source where only SED role is supported. Switching from SED to Router is only possible by removing the product from the network and joining it again to the hub.

---

2. Cluster Summary

Emma exposes the following Zigbee clusters on endpoint 1.

Cluster	Cluster ID	Side
Basic	0x0000	Server
Power Configuration	0x0001	Server
Identify	0x0003	Client + Server
Over the Air Bootloading	0x0019	Client
Poll Control	0x0020	Server
Thermostat	0x0201	Server
Thermostat UI Configuration	0x0204	Server
Temperature Measurement	0x0402	Server
Relative Humidity Measurement	0x0405	Server
Diagnostics	0x0B05	Server

Unless stated otherwise, the attributes described on this page are standard Zigbee attributes and do not require a manufacturer code.

---

3. Basic Cluster

Cluster ID: 0x0000
Side: Server

The Basic cluster identifies the device and reports runtime metadata such as power source, product code, and software build ID.

Supported attributes

Attribute	Name	Type	Access	Default	Reportable
0x0000	ZCL Version	INT8U	R	1	No
0x0001	Application Version	INT8U	R	—	No
0x0003	Hardware Version	INT8U	R	1	No
0x0004	Manufacturer Name	CHAR_STRING	R	"Plugwise"	No
0x0005	Model Identifier	CHAR_STRING	R	"170-01"	No
0x0006	Date Code	CHAR_STRING	R	—	No
0x0007	Power Source	ENUM8	R	0x00	Yes
0x000A	Product Code	OCTET_STRING	R	—	Yes
0x000B	Product URL	CHAR_STRING	R	Plugwise product URL	No
0x0012	Device Enabled	BOOLEAN	R/W	0x01	No
0x4000	SW Build ID	CHAR_STRING	R	—	No
0xFFFD	Cluster Revision	INT16U	R	3	No

Product code

The Product Code attribute (0x000A) reflects the detected hardware and boiler mode. It encodes both the backplate type and the active boiler protocol as a short OCTET_STRING code:

Product Code value	Condition
"OpenTherm"	Wired backplate, OpenTherm boiler detected
"OnOff"	Wired backplate, OnOff boiler
"OpenTherm/OnOff"	Wired backplate, protocol not yet determined (boot)
"Wireless"	Wireless backplate

This value is refreshed whenever Emma re-evaluates the boiler connection.

Product URL

The Product URL attribute (0x000B) returns:

https://www.plugwise.com/emma-wired-pro

Power source

The Power Source attribute (0x0007) reflects the currently active runtime power mode.

Value	Meaning	Typical situation
0x01	Mains	Wireless backplate powered via USB-C
0x03	Battery	Wireless/Wired backplate powered by AA batteries
0x04	DC source	Wired backplate with OpenTherm heat source

---

4. Power Configuration Cluster

Cluster ID: 0x0001 Side: Server

This cluster is relevant primarily for battery-powered variants. On externally powered variants, battery-related attributes may be present but are not meaningful.

Supported standard attributes

Attribute ID	Name	Type	Access	Default	Reportable	Unit
0x0021	Battery Percentage Remaining	INT8U	R	0x00	Yes (change: 2 units = 1 %)	0.5 % (200 = 100 %)
0xFFFD	Cluster Revision	INT16U	R	2	No

Manufacturer-specific Power Configuration Attributes (mfgCode 0x1172)

These attributes require manufacturer code 0x1172.

Attribute ID	Name	Type	Access	Default	Reportable	Notes
0x007F	Battery Type	ENUM8	R	0x00	Yes	0x00 = Alkaline (non-rechargeable); 0x01 = NiMH (rechargeable)

---

5. Identify Cluster

Cluster ID: 0x0003
Side: Client + Server

Emma responds to an Identify command by toggling its front-light for ~8 seconds.

Server attributes:

Attribute ID	Name	Type	Access	Default
0x0000	Identify Time	INT16U	R/W	0
0xFFFD	Cluster Revision	INT16U	R	2

---

6. OTA Bootloading cluster

Cluster ID: 0x0019
Side: Client

Emma acts as OTA client. The OTA server is the coordinator or a dedicated server in the network. Standard ZCL OTA command flow applies.

Attribute ID	Name	Type	Access	Default
0x0000	OTA Upgrade Server ID	IEEE_ADDRESS	R	0xFFFFFFFFFFFFFFFF
0x0001	Offset (address) into file	INT32U	R	0xFFFFFFFF
0x0006	OTA Upgrade Status	ENUM8	R	0x00
0x0009	Minimum Block Request Period	INT16U	R (fixed)	250 ms
0xFFFD	Cluster Revision	INT16U	R	2

Notes

• Minimum Block Request Period is fixed at 250 ms and cannot be changed by the OTA server.
• OTA updates with Adam HA is supported with every firmware version.
• OTA via other hubs such as Home Assistant is supported from R0010. Serve the firmware image through your coordinator's OTA server using the standard ZCL OTA Upgrade command flow. Emma will query the server, download, and apply the update automatically.

---

7. Poll Control Cluster

Cluster ID: 0x0020
Side: Server
Availability: SED only

This cluster is only active when Emma is operating as a Sleepy End Device.

Integrations that support SED operation should bind to this cluster and handle CheckIn messages correctly. Attribute writes and commands must be issued within the fast-poll window.

Attribute ID	Name	Type	Access	Default	Notes
0x0000	Check-in Interval	INT32U	R/W	43200	Quarter-seconds (~3 hours)
0x0001	Long Poll Interval	INT32U	R/W	20	Quarter-seconds (5 s) — Zigbee spec default
0x0002	Short Poll Interval	INT16U	R/W	16	Default 16 QS (4 s); firmware enforces 4 QS (1 s) minimum for OpenTherm boilers
0x0003	Fast Poll Timeout	INT16U	R/W	96	Quarter-seconds (24 s)
0xFFFD	Cluster Revision	INT16U	R	3

---

8. Thermostat Cluster

Cluster ID: 0x0201
Side: Server

This is the primary control cluster for Emma.

Emma supports:

• heating mode
• cooling mode
• off mode
• auto mode (heat/cool)

All temperature values in this cluster use 0.01 °C units unless stated otherwise.

Example:

2000 = 20.00 °C

Attributes

Attribute ID	Name	Type	Access	Default	Reportable
0x0000	Local Temperature	INT16S	R	—	Yes (change: 10 = 0.10 °C; max 870 s)
0x0001	Outdoor Temperature	INT16S	R	0	Yes (change: 10 = 0.10 °C; max 870 s)
0x0003	Abs Min Heat Setpoint Limit	INT16S	R	-2000 (-20 °C)	No
0x0004	Abs Max Heat Setpoint Limit	INT16S	R	9000 (90 °C)	No
0x0005	Abs Min Cool Setpoint Limit	INT16S	R	-2000 (-20 °C)	No
0x0006	Abs Max Cool Setpoint Limit	INT16S	R	9000 (90 °C)	No
0x0007	PI Cooling Demand	INT8U	R	—	Yes (change: 1; max 870 s)
0x0008	PI Heating Demand	INT8U	R	—	Yes (change: 1; max 870 s)
0x0010	Local Temperature Calibration	INT8S	R/W	0	Yes (change: 0; max 870 s)
0x0011	Occupied Cooling Setpoint	INT16S	R/W	2600 (26 °C)	Yes (change: 50 = 0.50 °C; max 870 s)
0x0012	Occupied Heating Setpoint	INT16S	R/W	2000 (20 °C)	Yes (change: 50 = 0.50 °C; max 870 s)
0x0015	Min Heat Setpoint Limit	INT16S	R/W	500 (5 °C)	Yes
0x0016	Max Heat Setpoint Limit	INT16S	R/W	3000 (30 °C)	Yes
0x0017	Min Cool Setpoint Limit	INT16S	R/W	0 (0 °C)	Yes
0x0018	Max Cool Setpoint Limit	INT16S	R/W	3000 (30 °C)	Yes
0x0019	Min Setpoint Dead Band	INT8S	R/W	20 (2.0 °C)	Yes (change: 0; max 870 s)
0x001C	System Mode	ENUM8	R/W	0x04 (Heat)	Yes (change: 0; max 870 s)
0x0029	HVAC Relay State	BITMAP16	R	—	Yes (change: 0; max 870 s)
0xFFFD	Cluster Revision	INT16U	R	3	No

System Mode (0x001C):

Value	Mode	Active setpoint(s)
0x00	Off	—
0x01	Auto (Heat + Cool)	Both — heating and cooling setpoints with deadband
0x03	Cool	Occupied Cooling Setpoint (0x0011)
0x04	Heat	Occupied Heating Setpoint (0x0012)

PI Heating Demand

The interpretation of PI Heating Demand (0x0008) depends on the boiler type.

OpenTherm

For OpenTherm systems, this attribute reports the intended boiler water temperature in °C, not a percentage.

Example:

70 = 70 °C target boiler water temperature

OnOff

For OnOff systems:

• 100 means boiler on
• 0 means boiler off

HVAC Relay State

Emma uses HVAC Relay State (0x0029) to expose the current operating state. Only the following values are used:

Value	Meaning
0x0000	Idle — boiler not active
0x0001	Heating active (bit 0 set)
0x0002	Cooling active (bit 1 set)

Manufacturer-specific Thermostat Attributes

Emma exposes additional Plugwise thermostat attributes in cluster 0x0201. These attributes require manufacturer code 0x1172.

Attribute ID	Name	Type	Access	Default	Notes
0xF000	External Heat Demand	INT16U	R/W	0	Hundredths of °C for OT; any non-zero = relay ON for OnOff — see §14. Requires Unlocked External Control.
0xF001	External Heat Demand Timeout	INT16U	R/W	900	Watchdog timeout in seconds; range 300–3600 — see §14. Requires Unlocked External Control.
0xF002	Boiler Water Temperature	INT16S	R	0	Current boiler supply water temperature in hundredths of °C; 0 = not available
0xF003	DHW Temperature	INT16S	R	0	Domestic hot water temperature in hundredths of °C; 0 = not available
0xF004	Return Water Temperature	INT16S	R	0	Boiler return water temperature in hundredths of °C; 0 = not available
0xF005	Application Specific Fault Code	BITMAP8	R	0x00	OpenTherm fault flag byte (ID 5 high byte): bit 0 = Service request, bit 1 = Lockout reset, bit 2 = Low water pressure, bit 3 = Gas/flame fault, bit 4 = Air pressure fault, bit 5 = Water over-temperature
0xF006	OEM Fault Code	INT8U	R	0x00	OpenTherm OEM-specific fault code
0xF007	Max DHW Setpoint	INT16S	R/W	0	Maximum domestic hot water setpoint in hundredths of °C as reported by the boiler; 0 = not available. Writing requires Unlocked External Control.
0xF008	Max Boiler Setpoint	INT16S	R/W	0	Maximum central heating water setpoint in hundredths of °C as reported by the boiler; 0 = not available. Writing requires Unlocked External Control.

Temperature attributes (0xF002–0xF004, 0xF007–0xF008) are reported when the value changes by ≥ 0.50 °C (50 hundredths) from the last reported value. A value of 0 means the boiler has not yet provided that reading over OpenTherm. Values are signed to correctly represent sub-zero readings.

Fault attributes (0xF005–0xF006) are reported on every change. Both are initialised and reported once on first OpenTherm communication, then only on change.

---

9. Thermostat UI Configuration cluster

Cluster ID: 0x0204
Side: Server

Emma supports keypad lockout through this cluster.

Other attributes defined by the standard Thermostat UI Configuration cluster may appear in descriptors but are not acted on by the firmware.

Attribute ID	Name	Type	Access	Default	Reportable
0x0001	Keypad Lockout	ENUM8	R/W	0x00	Yes
0xFFFD	Cluster Revision	INT16U	R	1	No

Keypad Lockout values:

Value	Meaning
0x00	No lockout
0x01	Partial lockout: Normal operation allowed, menu blocked. Setpoint change via slider still allowed.
0x02	Full lockout: All buttons and slider blocked.
> 0x02	Treated as full lockout

When Emma leaves the Zigbee network, the lockout level is reset to 0x00.

---

10. Temperature Measurement Cluster

Cluster ID: 0x0402
Side: Server

This cluster reports the measured ambient temperature from the internal sensor. All values use 0.01 °C units.

Attribute ID	Name	Type	Access	Default	Reportable
0x0000	Measured Value	INT16S	R	—	Yes (change: 0.1 °C)
0x0001	Min Measured Value	INT16S	R	-4000 (-40 °C)	Yes
0x0002	Max Measured Value	INT16S	R	12000 (120 °C)	No
0xFFFD	Cluster Revision	INT16U	R	3	No

---

11. Relative Humidity Measurement

Cluster ID: 0x0405
Side: Server

This cluster reports the measured ambient relative humidity from the internal sensor.

All values use 0.01 %RH units.

Example:

5000 = 50.00 %RH

Attribute ID	Name	Type	Access	Default	Reportable
0x0000	Measured Value	INT16U	R	—	Yes (change: 300 = 3.00 %RH; max 870 s)
0x0001	Min Measured Value	INT16U	R	0	No
0x0002	Max Measured Value	INT16U	R	10000	No
0xFFFD	Cluster Revision	INT16U	R	2	No

---

12. Diagnostics Cluster — 0x0B05 (Server)

Cluster ID: 0x0B05
Side: Server

Attribute ID	Name	Type	Access
0x011C	Last Message LQI	INT8U	R
0x011D	Last Message RSSI	INT8S	R

---

13. Router / Sleepy End Device Lifecycle

Emma can change its Zigbee node type at runtime without leaving the network. Plugins must handle this transition correctly.

Join behaviour

At join time, Emma selects its node type based on the detected power source.

• Router
  • Emma Wired Pro with OpenTherm Smart Power heat source
  • Emma Wireless with USB-C power
• Sleepy End Device
  • Emma Wireless on batteries
  • Emma Wired Pro with OnOff heat source
  • Emma Wired Pro with OpenTherm heat source

The selected type is stored in non-volatile memory and restored after reboot.

Runtime Router → SED Transition

Emma can demote itself from Router to SED after joining when its power source changes.

This occurs when:

• Emma Wireless detects a valid battery voltage while currently operating as a Router. Then it automatically transitions to SED mode. The Basic cluster Power Source attribute (0x0007) is updated to 0x03 (Battery).
• Emma Wired Pro establishes OpenTherm communication with a heat source that does not provide OpenTherm smart power, it transitions from Router to SED mode.

In that case, Emma performs a secured rejoin — it rejoins the existing network as a Sleepy End Device without leaving, preserving its short address, network key, and all attribute values. After rejoining, Emma sends a ZDO Device Announcement to notify the coordinator of the node type change.

Integration requirements

When Emma sends a ZDO Device Announcement (0x0013):

1. Issue a Node Descriptor Request to retrieve the updated node descriptor.
2. If Emma is now a SED, bind to the Poll Control cluster (0x0020) to receive CheckIn messages.

If the node type is not refreshed after the announcement, the integration may continue to treat Emma as a Router and direct unicast messages to a sleeping device.

SED → Router Transition

There is no automatic SED → Router transition.

To restore Router operation, remove Emma from the network and join it again while the required powered configuration is active.

SED Polling Timing

Parameter	Default value	Converted
Check-in Interval	43200 quarter-seconds	~3 hours
Long Poll Interval	20 quarter-seconds	5 s
Short Poll Interval	4 QS (OpenTherm) / 16 QS (OnOff or wireless/battery)	1 s / 4 s
Fast Poll Timeout	96 quarter-seconds	24 s

---

14. External Control

Emma supports manufacturer-specific external boiler control through thermostat cluster 0x0201 using manufacturer code 0x1172.

This functionality allows a gateway or integration to control:

• the boiler target temperature for OpenTherm systems
• the boiler on/off state for OnOff systems

This feature lets Home Assistant directly control the boiler target temperature (OpenTherm) or boiler state (OnOff boiler) from the gateway, bypassing Emma's own regulation.

The following attributes all require Unlocked External Control before they can be accessed:

Attribute ID	Cluster	Name	Type	mfgCode
0xF000	0x0201	External Heat Demand	INT16U	0x1172
0xF001	0x0201	External Heat Demand Timeout	INT16U	0x1172
0xF007	0x0201	Max DHW Setpoint	INT16S	0x1172
0xF008	0x0201	Max Boiler Setpoint	INT16S	0x1172

Reads or writes attempted before unlock is active return ZCL status NOT_AUTHORIZED (0x7e).

Writing any of 0xF000, 0xF001, 0xF007, or 0xF008 on an un-unlocked device triggers the unlock screen on the thermostat display so the user can complete the unlock flow.

External Heat Demand - OpenTherm

Write 0xF000 with the desired boiler water temperature in hundredths of °C (e.g. 7000 = 70.00 °C). Valid range: 0–9000 (0–90 °C); values above 9000 are rejected with INVALID_VALUE.

• Emma immediately overrides the Regulation with the written value. A watchdog timer is started. If no new write to 0xF000 arrives before it expires, Emma reverts to its own regulation.
• Writing 0 disables external heat demand immediately.

Timeout (0xF001): Read/Write, INT16U, seconds. Default 900 (15 min). Allowed range: 300–3600 (5 min – 60 min); values outside this range are rejected.

Max Setpoint Clamping (0xF007, 0xF008): When Max DHW Setpoint (0xF007) and Max Boiler Setpoint (0xF008) are configured, Emma clamps the values written to 0xF000 so that the boiler water temperature does not exceed the Max Boiler Setpoint and the domestic hot water temperature does not exceed the Max DHW Setpoint. These limits are not applicable to OnOff boilers.

External Heat Demand - OnOff

Write 0xF000 with any non-zero value to turn the boiler ON, or 0 to turn it OFF. The value itself is not used as a temperature; the boiler is driven solely by zero vs non-zero.

• The same watchdog (0xF001) applies. On expiry, Emma reverts to its own Regulation

Max DHW Setpoint and Max Boiler Setpoint

These two read-only attributes report the maximum setpoints supported by the boiler, as communicated over OpenTherm. They are only meaningful on OpenTherm boiler variants.

Attr ID	Name	Description
0xF007	Max DHW Setpoint	Maximum domestic hot water setpoint the boiler supports, in hundredths of °C
0xF008	Max Boiler Setpoint	Maximum central heating water setpoint the boiler supports, in hundredths of °C

A value of 0 means the boiler has not yet reported the limit over OpenTherm. Both attributes report on change ≥ 0.50 °C (50 hundredths).

---

15. Reporting Configuration Restrictions

Emma validates ConfigureReporting requests for selected attributes. If a requested configuration falls outside the supported limits, Emma returns:

INVALID_VALUE

Temperature Measured Value

Parameter	Allowed value
Reportable change	1–10 (0.01–0.10 °C)
Min interval	must be exactly 1 s
Max interval	must be exactly 870 s

Thermostat Local Temperature

Parameter	Allowed value
Reportable change	1–10 (0.01–0.10 °C)
Min / Max interval	no restriction

Relative Humidity Measured Value

Parameter	Allowed value
Reportable change	10–300 (0.10–3.00 %RH)
Min interval	must be exactly 1 s
Max interval	must be exactly 870 s

Battery Percentage Remaining

Parameter	Allowed value
Min interval	≥ 1 s
Max interval	≥ 43200 s (~12 hours)

Restricted Thermostat Attributes

The following thermostat attributes enforce a maximum reporting interval of 870 s:

Attr ID	Name	Max interval
0x0007	PI Cooling Demand	870 s
0x0008	PI Heating Demand	870 s
0x0010	Local Temperature Calibration	870 s
0x0011	Occupied Cooling Setpoint	870 s
0x0012	Occupied Heating Setpoint	870 s
0x001C	System Mode	870 s
0x0029	HVAC Relay State	870 s

Attributes not listed above accept any interval the hub specifies.

Poll Control Short Poll Interval

The minimum allowed Short Poll Interval depends on the heat source connection detected at runtime:

Boiler connection	Minimum Short Poll Interval
Emma Wired Pro + OpenTherm heat source	4 quarter-seconds (1 s)
Emma Wired Pro + OnOff heat source, Emma Wireless	16 quarter-seconds (4 s)