matterbridge-dyson-care 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +149 -67
  3. package/apps/frontend/build/app.js +1 -1
  4. package/apps/frontend/build/app.js.map +2 -2
  5. package/apps/frontend/build/styles.css +2 -1
  6. package/dist/accessory/pendingCommand.js +4 -18
  7. package/dist/errors.js +1 -1
  8. package/npm-shrinkwrap.json +2 -2
  9. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
4
4
 
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.2.0] - 2026-10-20
8
+
9
+ ### Added
10
+
11
+ - [docs]: Add screenshots of the guided setup, a comparison with the other Dyson plugins, and bring the README up to date with the code.
12
+ - [dev]: Add `npm run screenshots`, which takes the screenshots of the README from the setup page in front of simulated machines.
13
+
14
+ ### Changed
15
+
16
+ - [devices]: Leave whether a machine that is off turns on to dyson-control, which turns it on with nearly every control, as the MyDyson app does. The plugin no longer sends the power off with every control but the power, a fan speed or the auto mode, the heating, the humidifying and find and follow, and a setpoint turns the heating on and the auto humidifying the humidifying, as in the app.
17
+ - [setup]: Call the Dyson app the MyDyson app, as Dyson names it, in the setup page and the README.
18
+
19
+ ### Fixed
20
+
21
+ - [setup]: Show the descriptions of the auto mode choices in the Options step in the same weight as every other choice, not bold.
22
+
7
23
  ## [0.1.0] - 2026-10-20
8
24
 
9
25
  ### Added
package/README.md CHANGED
@@ -12,23 +12,25 @@
12
12
 
13
13
  Control your Dyson purifiers, fans, heaters and humidifiers from Apple Home, Google Home, Alexa, Home Assistant and other Matter apps.
14
14
 
15
- It is a [Matterbridge](https://matterbridge.io) plugin built on [dyson-control](https://www.npmjs.com/package/dyson-control), which reaches each machine through the Dyson cloud with your Dyson account, the way the Dyson app does. It covers the environmental care machines dyson-control knows: see its [machines](https://github.com/cheziyi/dyson-control#machines) and its [coverage and limitations](https://github.com/cheziyi/dyson-control#coverage--limitations).
15
+ It is a [Matterbridge](https://matterbridge.io) plugin built on [dyson-control](https://www.npmjs.com/package/dyson-control), which reaches each machine through the Dyson cloud with your Dyson account, the way the MyDyson app does. It covers the environmental care machines dyson-control knows: see its [machines](https://github.com/cheziyi/dyson-control#machines) and its [coverage and limitations](https://github.com/cheziyi/dyson-control#coverage--limitations).
16
16
 
17
17
  ## Why this plugin
18
18
 
19
19
  - **It finds your machines for you.** Sign in once in the setup page and it lists every machine of your Dyson account, with whether it can control each one. There is no serial number, credential or configuration file to look up: see [Guided setup](#guided-setup).
20
- - **It fits the Matter app you use.** Matter apps differ in what they show, so you choose how each control appears: the oscillation, the night mode and the airflow direction on the fan itself or as switches, the auto mode as a fan mode, a switch or a step, and a mode select for the oscillation angle or the target humidity. Presets for Apple Home and Google Home give you a starting point: see [Presets](#presets).
21
- - **It offers only what your machine can do.** The plugin reads which controls each machine carries from its type, its variant and its firmware, and builds its device in Matter from that. A heater gets a thermostat, a humidifier its humidifying, a purifier its air quality sensor.
20
+ - **It fits the Matter app you use.** Matter apps differ in what they show, so you choose how each control appears: the oscillation, the night mode and the airflow direction on the fan itself or as switches, the auto mode as a fan mode, a switch or a step, and a mode select for the oscillation angle or the target humidity. Presets for Apple Home, Google Home and the apps with full Matter support give you a starting point: see [Presets](#presets).
21
+ - **It offers only what your machine can do.** The plugin reads which controls each machine carries from its type, its model, its variant and its firmware, and builds its device in Matter from that. A heater gets a thermostat, a humidifier its humidifying, a purifier its air quality sensor.
22
+ - **It reaches more of the machine than the power and the fan.** Besides the fan speed, the auto mode, the oscillation and the night mode, you get the oscillation angle, the tilt, the heating, the humidifying, find and follow, the filters, and switches for the child lock, the jet focus, the UV light, the ioniser and the like: see the [comparison](#compared-with-other-dyson-plugins).
22
23
  - **It shows the air quality.** A purifier gets an air quality sensor with the air quality of its worst pollutant and each pollutant it measures: PM2.5, PM10, VOC, NO₂, formaldehyde and CO₂.
23
- - **You name each machine.** The Dyson app names a machine after its room, which several machines can share: the setup page starts from that name and lets you give each machine a name of its own in Matter. A machine whose firmware gains a control gets it.
24
- - **It says when a machine stops answering.** After two reads in a row fail, your Matter app shows the machine as unreachable, and it comes back by itself on the first read that works.
24
+ - **You name each machine.** The MyDyson app names a machine after its room, which several machines can share: the setup page starts from that name and lets you give each machine a name of its own in Matter. A machine whose firmware gains a control gets it.
25
+ - **It says when a machine stops answering.** After two reads in a row fail, or when its connection to the Dyson cloud does not open again, your Matter app shows the machine as unreachable, and it comes back by itself as soon as the machine answers again.
25
26
  - **Nothing needs a restart.** Sign in, add, change and remove machines while Matterbridge keeps running.
26
27
 
27
28
  ## Requirements
28
29
 
29
30
  - Matterbridge 3.10.10 or later.
30
31
  - Node.js 22.13 or later (22, 24 or 26). Node.js 20 is not supported, because dyson-control needs Node.js 22.
31
- - A Dyson account, signed in with an email address, and a route to the internet: the machines are reached through the Dyson cloud, not over the local network.
32
+ - A Dyson account that signs in with an email address, with your machines added to it in the MyDyson app. The plugin finds the machines of that account: it does not create an account or add a machine itself, so set each machine up in the MyDyson app first.
33
+ - A route to the internet: the machines are reached through the Dyson cloud, not over the local network.
32
34
 
33
35
  ## Installation
34
36
 
@@ -45,30 +47,68 @@ Then set up your machines in the plugin's own page: see [Guided setup](#guided-s
45
47
 
46
48
  ## Guided setup
47
49
 
48
- Open the plugin frontend from the plugin's row on the Matterbridge home page. It walks through four steps:
49
-
50
- 1. **Sign in.** Enter the email address and the country of your Dyson account. Dyson emails you a code: enter it with your password. The password is used once and not stored.
51
- 2. **Find.** The page lists the machines of your account, and says why it cannot control one, such as a robot vacuum or a machine of a type dyson-control does not know yet.
52
- 3. **Connect.** For each machine you picked, the plugin checks that it answers through the Dyson cloud, and reads which sensors it has.
53
- 4. **Options.** The name the machine gets in Matter, starting from its room name in the Dyson app, and how the fan, the oscillation or the tilt, the night mode, the airflow direction, the find and follow, the heating, the humidifying, the water hardness, the filters and the readings appear in Matter, from what the machine can do. Start from a [preset](#presets) or choose each one yourself.
54
-
55
- Afterwards the same page lists your machines with their status: online, connecting while a machine just added or rebuilt connects through the cloud, not answering, or not started. Under each machine it shows the life left in its filters, when its next clean cycle is due, and the faults it reports, such as a filter to replace or an empty tank. From there you can add more, change the options of one, reconnect one that stopped answering, remove one, sign in again, or sign out. None of this needs a Matterbridge restart.
50
+ Open the plugin frontend from the plugin's row on the Matterbridge home page. The first time, it asks you to sign in:
51
+
52
+ - **Sign in.** Enter the email address and the country of your Dyson account, the one you use in the MyDyson app. Dyson emails you a code: enter it with your password. The password is used once and not stored.
53
+
54
+ Then it walks through three steps:
55
+
56
+ 1. **Find.** The page lists the machines of your account and marks those already set up. It says why it cannot control one: a robot vacuum or another machine that is not a purifier, a fan, a heater or a humidifier, a machine of a type dyson-control does not know yet, or one reached through a Dyson cloud service it cannot connect to yet.
57
+ 2. **Connect.** For each machine you picked, the plugin checks that it answers through the Dyson cloud, and reads which sensors it has.
58
+ 3. **Options.** The name the machine gets in Matter, starting from its room name in the MyDyson app, whether it appears as an air purifier or a fan, and how the fan, the oscillation or the tilt, the night mode, the airflow direction, the find and follow, the heating, the humidifying, the clean cycle, the [more controls](#more-controls) and the readings appear in Matter, from what the machine can do, and whether they are one device or several. Start from a [preset](#presets) or choose each one yourself.
59
+
60
+ Afterwards the same page lists your machines with their status: online, connecting while a machine just added or rebuilt connects through the cloud, not answering, or not started. Under each machine it shows how it appears in Matter, the life left in its filters, its clean cycle, such as when the next one is due or how long one that runs has left, how long the drying of its wick has left, and the faults it reports, such as a filter to replace or an empty tank. From there you can add more, change the options of one, reconnect one that stopped answering, remove one, switch to another account, sign in again when the Dyson cloud no longer accepts the sign-in, or sign out. None of this needs a Matterbridge restart.
61
+
62
+ <table>
63
+ <tr>
64
+ <td width="50%" valign="top">
65
+ <img src="screenshots/sign-in.png" alt="The sign in asks for the code Dyson emailed and the password of the account, which is not stored">
66
+ <br><b>Sign in.</b> The code Dyson emails you, and your password, used once.
67
+ </td>
68
+ <td width="50%" valign="top">
69
+ <img src="screenshots/find.png" alt="The Find step lists the machines of the account, with those already set up, a machine on a cloud service the plugin cannot reach yet, and a robot vacuum it does not control">
70
+ <br><b>Find.</b> The machines of your account, and why the plugin cannot control one.
71
+ </td>
72
+ </tr>
73
+ <tr>
74
+ <td valign="top">
75
+ <img src="screenshots/options-presets-fan.png" alt="The Options step for a Big+Quiet with the Apple Home preset chosen, the machine as an air purifier, the fan speed as a percentage and the auto mode as a native fan mode">
76
+ <br><b>Options.</b> Start from a preset, then choose how the machine and its fan appear.
77
+ </td>
78
+ <td valign="top">
79
+ <img src="screenshots/options-oscillation.png" alt="The Options step for a Purifier Cool with the oscillation as a mode select of its angles, the night mode as a switch, the airflow direction native and find and follow as a switch">
80
+ <br><b>Options.</b> The oscillation as a select of its angles, and find and follow.
81
+ </td>
82
+ </tr>
83
+ <tr>
84
+ <td valign="top">
85
+ <img src="screenshots/options-humidifier.png" alt="The Options step for a Humidify+Cool with the humidifying as switches and an optional mode select for the water hardness">
86
+ <br><b>Options.</b> The humidifying and the clean cycle of a humidifier.
87
+ </td>
88
+ <td valign="top">
89
+ <img src="screenshots/home.png" alt="The home page lists four machines with their status, how each appears in Matter, the life left in their filters, a clean cycle due, the faults they report and one that is not answering">
90
+ <br><b>Afterwards.</b> Your machines, their status, their filters and their faults.
91
+ </td>
92
+ </tr>
93
+ </table>
94
+
95
+ The screenshots show the setup page with simulated machines: the plugin's own setup API in front of a fake Dyson account, which is why the serial numbers run `NK6-EU-MHA0001A` and on. See [Development](#development) to take them again.
56
96
 
57
97
  ## How a machine appears in Matter
58
98
 
59
99
  | In Matter | From the machine |
60
100
  | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
61
101
  | Air purifier | The machine, with its power and its fan speed. You can make it a fan instead: see [Air purifier or fan](#air-purifier-or-fan) |
62
- | Fan speed | Speeds 1 to 10, as steps or as a percentage |
102
+ | Fan speed | Speeds 1 to 10, as steps or as a percentage: see [Fan speed](#fan-speed) |
63
103
  | Auto mode | Your choice, on a machine that has one: see [Auto mode](#auto-mode) |
64
- | Oscillation | Your choice, or the tilt of a machine that tilts: see [Oscillation](#oscillation) and [Tilt](#tilt) |
104
+ | Oscillation | Your choice, or the tilt of a machine that tilts, on a machine that has one: see [Oscillation](#oscillation) and [Tilt](#tilt) |
65
105
  | Night mode | Your choice: see [Night mode and airflow direction](#night-mode-and-airflow-direction) |
66
106
  | Airflow direction | Your choice, on a machine that blows its air to the front or the back |
67
107
  | Find and follow | A switch or a mode select, on a machine that follows the people it finds: see [Find and follow](#find-and-follow) |
68
108
  | Heating | A thermostat or a switch, on a heater: see [Heating](#heating) |
69
109
  | Humidifying | Switches or a mode select, on a humidifier: see [Humidifying](#humidifying) |
70
110
  | Water hardness | A mode select, on a humidifier that runs a clean cycle: see [Humidifying](#humidifying) |
71
- | Filters | The life left in each filter, on every air purifier: see [Filters](#filters) |
111
+ | Filters | The life left in each filter, on an air purifier that reports it: see [Filters](#filters) |
72
112
  | More controls | Switches or mode selects for the child lock, the UV light and the like, on a machine that has them: see [More controls](#more-controls) |
73
113
  | Readings | An air quality sensor, a temperature sensor and a humidity sensor, each once the machine gives its reading: see [Readings](#readings) |
74
114
 
@@ -82,10 +122,10 @@ Matter describes a device as endpoints. Each endpoint has one or more device typ
82
122
  flowchart TD
83
123
  bridge["Matterbridge<br/>Aggregator"]
84
124
  subgraph device["One device in a Matter app"]
85
- main["<b>Living Room</b><br/>Air Purifier or Fan, Bridged Node, Power Source<br/>On/Off, Fan Control, with Rocking, Wind and Airflow Direction when they are there<br/>HEPA and Activated Carbon Filter Monitoring on an air purifier"]
86
- thermostat["Thermostat<br/>Thermostat, heating only"]
125
+ main["<b>Living Room</b><br/>Air Purifier or Fan, Bridged Node, Power Source<br/>On/Off, Fan Control with Wind, and with Rocking and Airflow Direction when they are there<br/>HEPA and Activated Carbon Filter Monitoring on an air purifier that reports its filters"]
126
+ thermostat["Thermostat<br/>Thermostat, heating only, and Thermostat User Interface Configuration on a heater with a temperature unit"]
87
127
  switches["On/Off Plug-in Unit, one for each switch<br/>tagged 1 Auto Mode, 2 Night Mode and so on<br/>On/Off"]
88
- selects["Mode Select, one for each select: the oscillation or the tilt,<br/>the find and follow, the target humidity and the water hardness<br/>Mode Select"]
128
+ selects["Mode Select, one for each select: the oscillation or the tilt,<br/>the find and follow, the target humidity, the water hardness,<br/>the air quality target and the wick drying speed<br/>Mode Select"]
89
129
  air["Air Quality Sensor<br/>Air Quality, and a concentration measurement for each pollutant"]
90
130
  sensors["Temperature Sensor, Humidity Sensor<br/>Temperature Measurement, Relative Humidity Measurement"]
91
131
  end
@@ -97,7 +137,7 @@ flowchart TD
97
137
  main -.-> sensors
98
138
  ```
99
139
 
100
- A solid line is always there. A dashed one is there when you choose it in the setup and the machine has it, and for a sensor once the machine gives its reading. The main endpoint also has the Bridged Node and Power Source device types, with the Identify, Bridged Device Basic Information and Power Source clusters: the name and the serial number of the machine, whether it is reachable, and that it runs on mains power. Its parts have none of these, because in Matter they belong to the device. The setup can also make each part a device of its own: see [One device or several](#one-device-or-several).
140
+ A solid line is always there. A dashed one is there when you choose it in the setup and the machine has it, and for a sensor once the machine gives its reading. The main endpoint also has the Bridged Node and Power Source device types, with the Identify, Bridged Device Basic Information and Power Source clusters: the name and the serial number of the machine, whether it is reachable, and that it runs on mains power. Its parts have the Identify cluster alone, because in Matter the rest belongs to the device. The setup can also make each part a device of its own: see [One device or several](#one-device-or-several).
101
141
 
102
142
  | Device type | ID | Stands for |
103
143
  | ------------------- | ------ | ----------------------------------------------------- |
@@ -115,6 +155,8 @@ A solid line is always there. A dashed one is there when you choose it in the se
115
155
 
116
156
  An air purifier also has the HEPA Filter Monitoring (0x0071) and Activated Carbon Filter Monitoring (0x0072) clusters for its filters: see [Filters](#filters).
117
157
 
158
+ The names below, such as `<name> Night Mode`, are those of the parts as devices of their own, as the Apple Home and Google Home presets make them. As parts of the main device they have no name in Matter: a switch or a mode select is tagged with what it is, such as `Night Mode`, and a Matter app shows each part in its own way: see [One device or several](#one-device-or-several).
159
+
118
160
  ### Air purifier or fan
119
161
 
120
162
  | Option | In Matter |
@@ -131,7 +173,7 @@ Both have an on/off and a fan control. Setting the fan to off or 0 turns the mac
131
173
  | Steps | Ten steps, one for each speed, and a percentage beside them |
132
174
  | Percentage | A slider from 0 to 100. The plugin rounds it to the nearest speed: 10 % is speed 1, and 100 % speed 10 |
133
175
 
134
- Matter also has the fan modes Low, Medium and High, which apps show as buttons or reach by voice. Matterbridge sets a fan mode picked to the middle percentage of its third, 17 %, 50 % or 84 %, which the plugin rounds to the nearest speed as it does any percentage: Low is speed 2, Medium speed 5 and High speed 8.
176
+ Matter also has the fan modes Low, Medium and High, which apps show as buttons or reach by voice. Each stands for a third of the percentage: Low up to 33 %, Medium up to 66 % and High above. A fan mode picked while the fan already runs in its third keeps the speed it has. Otherwise Matterbridge sets the middle percentage of that third, 17 %, 50 % or 84 %, which the plugin rounds to the nearest speed as it does any percentage: Low is speed 2, Medium speed 5 and High speed 8.
135
177
 
136
178
  ### Auto mode
137
179
 
@@ -144,14 +186,16 @@ In its auto mode the machine picks its fan speed from the air it measures. On a
144
186
  | The first step | Below speed 1: step 1, or the bottom of the slider |
145
187
  | The last step | Above speed 10: the top step, or 100 % |
146
188
 
147
- A step takes the place of the Auto fan mode, because in that mode Matter holds no percent: the fan then has eleven steps. The fan modes then round to the nearest of those: with auto first, Low is speed 1, Medium speed 5 and High speed 8, and with auto last, Low is speed 2, Medium speed 6 and High speed 9. Turning the auto mode off on a machine that is off leaves it off.
189
+ A step takes the place of the Auto fan mode, because in that mode Matter holds no percent: the fan then has eleven steps. A fan mode picked outside its third then rounds to the nearest of those: with auto first, Low is speed 1, Medium speed 5 and High speed 8, and with auto last, Low is speed 2, Medium speed 6 and High speed 9. Turning the auto mode off on a machine that is off turns it on at that speed.
148
190
 
149
191
  ### Oscillation
150
192
 
193
+ A machine that dyson-control reads as not oscillating, such as the type 965, gets no oscillation in Matter and no choice in the setup.
194
+
151
195
  | Option | In Matter |
152
196
  | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
153
197
  | Native rocking | The left and right rocking of the fan control, as Matter has it. Not every app shows it |
154
- | A switch | A switch named `<name> Oscillation`, in place of the rocking. On sweeps the angle set in the Dyson app |
198
+ | A switch | A switch named `<name> Oscillation`, in place of the rocking. On sweeps the angle set in the MyDyson app |
155
199
  | A mode select | A mode select named `<name> Oscillation`, in place of the rocking, with Off and the angles the machine sweeps: see below. Few Matter apps show it: see [Mode selects](#mode-selects) |
156
200
 
157
201
  The mode select offers what the machine takes:
@@ -162,7 +206,7 @@ The mode select offers what the machine takes:
162
206
  | One with preset angles | Its presets: 45°, 90°, 180° and 350°, or 15°, 40° and 70° on some models |
163
207
  | A humidifier whose barrel turns | 45°, 90° and Breeze |
164
208
 
165
- A machine that oscillates only on and off gets no mode select, and nor does one whose firmware takes its two angles only as one direction, as on the types 635 and 739: the oscillation is a switch on them.
209
+ A sweep the select does not list, such as one set in the MyDyson app, leaves the select at what it showed before. A machine that oscillates only on and off gets no mode select, and nor does one whose firmware takes its two angles only as one direction, as on the types 635 and 739: the oscillation is a switch on them.
166
210
 
167
211
  A machine that pauses its oscillation while it stands by takes it on and off in modes of their own, which the plugin sends in place of on and off while the machine stands by, as dyson-control asks.
168
212
 
@@ -176,7 +220,7 @@ The Big+Quiet tilts in place of oscillating: to 0°, 25° or 50°, or back and f
176
220
  | A switch | A switch named `<name> Oscillation`, in place of the rocking, which breezes the same way |
177
221
  | A mode select | A mode select named `<name> Tilt`, in place of the rocking, with 0°, 25°, 50° and Breeze |
178
222
 
179
- A tilt turns the machine on when the Dyson app sets it. From Matter it leaves a machine that is off as it is: see [Power](#power).
223
+ A tilt turns a machine that is off on, as in the MyDyson app: see [Power](#power).
180
224
 
181
225
  ### Night mode and airflow direction
182
226
 
@@ -195,7 +239,7 @@ A machine that follows people, such as the Purifier Cool of variant N, finds the
195
239
  | ------------- | ------------------------------------------------------------------------------------------------------------------------- |
196
240
  | A switch | A switch named `<name> Find and Follow`. On follows the people the machine finds, and it shows on while it looks for them |
197
241
  | A mode select | A mode select named `<name> Find and Follow`, with Off, Follow and Scan, which looks for people |
198
- | Not shown | Find and follow stays as the Dyson app sets it |
242
+ | Not shown | Find and follow stays as the MyDyson app sets it |
199
243
 
200
244
  ### Heating
201
245
 
@@ -204,10 +248,10 @@ On a heater, the heating appears in one of these places. It runs only while the
204
248
  | Option | In Matter |
205
249
  | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
206
250
  | A thermostat | A thermostat that heats, with a setpoint from 1 to 37 °C in whole degrees, named `<name> Heater` as a device of its own. Off turns the heating off and leaves the fan running |
207
- | A switch | A switch named `<name> Heat`. It heats to the setpoint set in the Dyson app |
208
- | Not shown | The heating stays as the Dyson app sets it |
251
+ | A switch | A switch named `<name> Heat`. It heats to the setpoint set in the MyDyson app |
252
+ | Not shown | The heating stays as the MyDyson app sets it |
209
253
 
210
- The thermostat shows it heating while the heater runs, as the machine says. A machine that does not say so shows it heating while the room is below the setpoint. A setpoint changed in Matter leaves the heating as it is. On a heater that shows a temperature in °C or °F, the thermostat has that unit as its display mode, which a Matter app can set.
254
+ The thermostat shows it heating while the heater runs, as the machine says. A machine that does not say so shows it heating while the room is below the setpoint. A setpoint changed in Matter turns the heating on, as it does in the MyDyson app. On a heater that shows a temperature in °C or °F, the thermostat has that unit as its display mode, which a Matter app can set.
211
255
 
212
256
  ### Humidifying
213
257
 
@@ -215,9 +259,11 @@ Matter has no humidifier, so on a humidifier the humidifying appears in one of t
215
259
 
216
260
  | Option | In Matter |
217
261
  | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
218
- | Switches | A switch named `<name> Humidify`, which humidifies to the target set in the Dyson app, and one named `<name> Auto Humidify` on a machine that picks its own target |
262
+ | Switches | A switch named `<name> Humidify`, which humidifies to the target set in the MyDyson app, and one named `<name> Auto Humidify` on a machine that picks its own target |
219
263
  | A mode select | A mode select named `<name> Target Humidity`, with Off, Auto on a machine that has it, and 30 %, 40 %, 50 %, 60 % and 70 %. A target the machine holds between two of them shows as the nearer one |
220
- | Not shown | The humidifying stays as the Dyson app sets it |
264
+ | Not shown | The humidifying stays as the MyDyson app sets it |
265
+
266
+ Turning the `<name> Auto Humidify` switch on or off turns the humidifying on as well, to the target the machine picks or to the one set in the MyDyson app, as the MyDyson app does.
221
267
 
222
268
  A humidifier that runs a clean cycle asks for one as often as the hardness of its water says: the harder the water, the sooner. It can get a mode select named `<name> Water Hardness`, with Soft, Medium and Hard. The setup page shows when its next clean cycle is due, and how long one that runs has left.
223
269
 
@@ -240,15 +286,15 @@ A mode select is the Matter device type that picks one value from a list, as a d
240
286
 
241
287
  A machine that has one of these controls can get a switch or a mode select for it, which Matter has no place for beside the fan:
242
288
 
243
- | Control | In Matter | On |
244
- | ------------------ | --------------------------------------------------------------------------------------------- | ---------------------------------------------- |
245
- | Child lock | A switch named `<name> Child Lock`. On locks the buttons of the machine | The types 635, 739, 918, 965, 997 and 1018 |
246
- | UV light | A switch named `<name> UV Light` | The machines dyson-control reads as having one |
247
- | Ioniser | A switch named `<name> Ioniser` | The machines dyson-control reads as having one |
248
- | Jet focus | A switch named `<name> Jet Focus`. On focuses the air into one stream, and off diffuses it | The type 455 |
249
- | Indirect airflow | A switch named `<name> Indirect Airflow`. On tilts the nozzle to 45°, and off points it at 0° | The type 831 |
250
- | Air quality target | A mode select named `<name> Air Quality Target`: the air quality the auto mode aims for | Machines of the first generation |
251
- | Wick drying | A switch named `<name> Wick Drying`, and a mode select for its speed: slow, normal or fast | The type 965 |
289
+ | Control | In Matter | On |
290
+ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
291
+ | Child lock | A switch named `<name> Child Lock`. On locks the buttons of the machine | The types 635, 739, 918, 965, 997 and 1018 |
292
+ | UV light | A switch named `<name> UV Light` | The machines dyson-control reads as having one |
293
+ | Ioniser | A switch named `<name> Ioniser` | The machines dyson-control reads as having one |
294
+ | Jet focus | A switch named `<name> Jet Focus`. On focuses the air into one stream, and off diffuses it | The type 455 |
295
+ | Indirect airflow | A switch named `<name> Indirect Airflow`. On tilts the nozzle to 45°, and off points it at 0° | The type 831 |
296
+ | Air quality target | A mode select named `<name> Air Quality Target`: the air quality the auto mode aims for, Good, Sensitive or Very Sensitive | Machines of the first generation |
297
+ | Wick drying | A switch named `<name> Wick Drying`, which dries the wick, and a mode select named `<name> Wick Drying Speed`: Slow, Normal or Fast, in 60, 45 or 30 minutes. Each is a choice of its own | The type 965 |
252
298
 
253
299
  See dyson-control's [capabilities](https://github.com/cheziyi/dyson-control#capabilities) for which models have a UV light and an ioniser. The setup page offers each only on a machine that has it.
254
300
 
@@ -277,7 +323,7 @@ Dyson rates the air from good to severe on one index for every pollutant, and Ma
277
323
  | 11 to 13 | Extremely poor | Very poor | Critical |
278
324
  | 13 and over | Severe | Extremely poor | Critical |
279
325
 
280
- - **No machine says which readings it has**, beyond whether it measures the air, so the plugin goes by what the machine reads. The setup page offers a temperature or a humidity sensor only once the machine has given that reading, so a machine without them, such as the HushJet Purifier Compact, is offered neither. A sensor gets its place in Matter the first time the machine gives its reading: at once for one it gave during setup, and otherwise the machine is built again in Matter when the reading first comes.
326
+ - **No machine says which readings it has**, beyond whether it measures the air, so the plugin goes by what the machine reads. The setup page offers a temperature or a humidity sensor only once the machine has given that reading, so a machine without them, such as the HushJet Purifier Compact, is offered neither. A sensor gets its place in Matter the first time the machine gives its reading: at once for one it gave during setup, and otherwise the machine is built again in Matter at the first read after the reading comes.
281
327
  - **A reading keeps its place from then on**, so a sensor does not come and go in your Matter app.
282
328
  - **A reading the machine does not give right now shows no value**, instead of the last one it gave.
283
329
  - **Continuous monitoring.** A machine that can keep measuring the air while it is off can get a switch named `<name> Continuous Monitoring`. On keeps its readings fresh while it is off.
@@ -311,37 +357,70 @@ Matter names a device, not its parts, so what a part is called is up to the Matt
311
357
 
312
358
  Changing the choice builds the machine again in Matter, so a Matter app takes its parts for new devices: they lose the rooms, the names and the automations they had there.
313
359
 
360
+ ## Compared with other Dyson plugins
361
+
362
+ One other Matterbridge plugin controls Dyson purifiers, fans and heaters: [matterbridge-dyson-robot](https://github.com/thoukydides/matterbridge-dyson-robot), which despite its name covers these machines as well as the robot vacuums.
363
+
364
+ This plugin is the one for a humidifier, and the one that reaches the oscillation angle, the jet focus, the child lock, the UV light, the ioniser and the other controls Matter has no place for, as switches or mode selects. It also signs in and adds machines without a restart, and fits each control to the Matter app you use. matterbridge-dyson-robot has strengths of its own: it controls the robot vacuums, it can reach a machine over the local network instead of the cloud, and it has been released for longer.
365
+
366
+ | | matterbridge-dyson-care (this plugin) | [matterbridge-dyson-robot](https://github.com/thoukydides/matterbridge-dyson-robot) |
367
+ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
368
+ | Connection | The Dyson cloud, with a MyDyson account | The Dyson cloud with a MyDyson account, the default. Or the local network, with the address of each machine and its credentials from the account, from its label or from [opendyson](https://github.com/libdyson-wg/opendyson), but not for recent products |
369
+ | Machines | The purifiers, fans, heaters and humidifiers dyson-control knows: see its [machines](https://github.com/cheziyi/dyson-control#machines). Not robot vacuums | Robot vacuums, and the Pure Cool Link, Pure Cool, Purifier Cool, Hot+Cool, Humidify+Cool, Big+Quiet, Cool and Hot+Cool fans and HushJet purifiers. Many of these are checked against logs of the machine only |
370
+ | Built on | [dyson-control](https://github.com/cheziyi/dyson-control), a library by the same author that works on its own | Its own cloud and MQTT code |
371
+ | Adding a machine | Sign in and pick the machines in a guided setup page. No restart | Sign in from the plugin settings, then a restart. Every machine of the account, with a white list and a black list |
372
+ | A machine that stops answering | Shown as unreachable after two failed reads, or when its connection to the cloud does not open again | Shown as unreachable when its connection closes, or when the machine says it is leaving |
373
+ | Device types | An air purifier or a fan, as you choose, with a thermostat, the switches, the mode selects and the sensors as parts of it or as devices of their own | An air purifier for every machine, the fans included, with an air quality sensor and a thermostat as devices of their own. Temperature and humidity sensors, and one composed device, are optional |
374
+ | Fan speed and auto | Steps or a percentage, and the auto mode as a fan mode, a switch or a step | Speeds 1 to 10, and the Auto fan mode |
375
+ | Oscillation | The rocking of the fan control, a switch, or a mode select with the angles the machine sweeps. The tilt of the Big+Quiet the same way | The rocking of the fan control, on and off. The tilt of the Big+Quiet as up and down rocking. No angles |
376
+ | Night mode | The sleep wind of the fan control, and an optional switch | The sleep wind of the fan control |
377
+ | Heating | A thermostat or a switch | A thermostat |
378
+ | Humidifying | Switches or a mode select for the target humidity, and the water hardness | No. The breeze of the Humidify+Cool as its natural wind |
379
+ | Air quality | PM2.5, PM10, VOC, NO₂, formaldehyde and CO₂, rated on Dyson's own index | PM2.5, PM10, VOC, NO₂, formaldehyde and CO₂, rated on US EPA and WHO bands |
380
+ | Filters | The HEPA and the activated carbon filter, on a machine that reports them | The HEPA filter, and the activated carbon filter on the Big+Quiet |
381
+ | Other controls | The airflow direction, find and follow, and optional switches and mode selects for the child lock, the UV light, the ioniser, the jet focus, the indirect airflow, the air quality target, the wick drying and the continuous monitoring | The airflow direction. The robot vacuums with their cleaning modes, their areas and their maps |
382
+ | How often it is read | The machine sends its changes, and is read every 30 seconds, or what you set from 10 to 3600 | The machine sends its changes, and is read when it connects |
383
+ | Tested with | Not yet tested in each Matter app: see the notes in [How a machine appears in Matter](#how-a-machine-appears-in-matter) | Apple Home alone |
384
+ | Node.js | 22.13 or later, 24 and 26 | 22.23.2 or later, 24.21 or later and 26.10 or later, with Matterbridge 3.10.13 or later |
385
+ | License | Apache-2.0 | ISC |
386
+
387
+ The table is read from the README, the settings and the source of matterbridge-dyson-robot 1.12.5, in October 2026. It was not run for it. The npm package matterbridge-dyson is a placeholder with no Dyson code, so it is not in the table.
388
+
389
+ Outside Matterbridge, [homebridge-dyson-pure-cool](https://github.com/lukasroegner/homebridge-dyson-pure-cool) brings these machines to Apple Home over HomeKit, and Home Assistant reaches them with [ha-dyson](https://github.com/libdyson-wg/ha-dyson), which [Home Assistant Matter Hub](https://github.com/RiDDiX/home-assistant-matter-hub) can pass on to Matter.
390
+
314
391
  ## How devices are stored
315
392
 
316
- The plugin knows each machine by its **serial number**, which is also the serial number it has in Matter. A switch, a mode select or a sensor that is a device of its own has that serial number with a dash and a letter after it, such as `NK6-EU-MHA0000A-N` for the night mode switch:
393
+ The plugin knows each machine by its **serial number**, which is also the serial number it has in Matter. A thermostat, a switch, a mode select or a sensor that is a device of its own has that serial number with a dash and a letter after it, such as `NK6-EU-MHA0000A-N` for the night mode switch and `NK6-EU-MHA0000A-T` for the thermostat:
317
394
 
318
- - **The firmware is kept up to date.** The plugin reads the machine list of your account when it starts, every 15 minutes and when you open the setup page, and takes the firmware each machine runs now.
319
- - **Each device has the name you give it in the setup page**, which starts as the room name of the Dyson app, followed by a number when another device has that name already, such as `Bedroom 2`. A new room name in the Dyson app does not change it: the options of the device show the new one beside its type and serial number, as soon as you open the setup page again. No two devices share a name, because the name is what Matter shows and what its switches and sensors are named after.
395
+ - **The firmware is kept up to date.** The plugin reads the machine list of your account when it starts, when you sign in, every 15 minutes and when you open the setup page. It takes the firmware, the variant, the model, the product name and the room name each machine has now, and starts again a machine that could not start. A machine the cloud now reports with another type, or on a Dyson cloud service dyson-control cannot connect to, keeps what was stored, and a warning is logged.
396
+ - **Each device has the name you give it in the setup page**, of up to 32 characters, which starts as the room name of the MyDyson app, followed by a number when another device has that name already, such as `Bedroom 2`. A machine without a room name starts with none, for you to type. A new room name in the MyDyson app does not change it: the options of the device show the new one beside its product name and serial number, as soon as you open the setup page again. No two devices share a name, because the name is what Matter shows and what its switches and sensors are named after, shortened where the whole would pass 32 characters.
320
397
  - **A new name builds the device again in Matter**, with the same serial number. A Matter app may take it for a new device, and ask you again for its room and its automations.
321
- - **What each machine can do** is read from its type, its variant and its firmware capabilities, as the cloud reports them. When a firmware update gives a machine other controls, it is built again in Matter and a setting it no longer takes is reset.
322
- - **The readings each machine has given** are kept in the plugin's storage, so that its sensors are there from the start after a restart.
398
+ - **What each machine can do** is read from its type, its model, its variant and its firmware capabilities, as the cloud reports them. When a firmware update gives a machine other controls, it is built again in Matter and a setting it no longer takes is reset.
399
+ - **The readings each machine has given** are kept in the plugin's storage, so that its sensors are there from the start after a restart. Removing a machine in the setup page removes them too.
323
400
 
324
401
  The account and the devices are stored in the plugin configuration, which Matterbridge keeps in `matterbridge-dyson-care.config.json`. The account is stored as the sign-in token Dyson gives the plugin, with its email address and country, and never the password. The devices are added, changed and removed in the setup page only: the Matterbridge config editor does not list them.
325
402
 
326
- A stored device that this version of the plugin cannot read, for example one stored by a later version, is ignored and logged. It stays in the configuration as it is, until a device with its name or its serial number is added in the setup page. A setting whose stored value is not valid falls back to its default, which is logged as well.
403
+ A stored device without a valid name, serial number or type is ignored and logged. It stays in the configuration as it is, until a device with its name or its serial number is added in the setup page. A stored device with the name or the serial number of one before it is ignored and logged too, and left out of the configuration at its next save. A setting whose stored value is not valid falls back to its default, which is logged as well, and a field this version does not know, such as one of a later version, is left out at the next save.
327
404
 
328
405
  ## Configuration
329
406
 
330
- | Setting | Meaning |
331
- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
332
- | `pollIntervalInSeconds` | How often the state and the readings of each machine are read, 10 to 3600. Defaults to 30. A machine sends a change of its state by itself, so this mostly sets how fresh the readings are, and how soon a machine that is unplugged shows as unreachable |
407
+ | Setting | Meaning |
408
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
409
+ | `pollIntervalInSeconds` | How often the state and the readings of each machine are read, 10 to 3600. Defaults to 30. A machine sends a change of its state by itself, so this mostly sets how fresh the readings are, and how soon a machine that is unplugged shows as unreachable. A value outside the range is brought into it, and a new value takes effect without a restart |
410
+
411
+ The settings also have Matterbridge's own `debug` and `unregisterOnShutdown`, for debugging only. Your account and your machines are not settings: they are set up in the setup page.
333
412
 
334
413
  ## Good to know
335
414
 
336
415
  - **It needs the Dyson cloud.** Each machine is reached through the Dyson cloud, which needs a route to the internet: without one, the machines show as unreachable. See dyson-control's [connectivity](https://github.com/cheziyi/dyson-control/blob/main/DESIGN.md#connectivity) for why it does not talk to a machine over the local network.
337
416
  - **The sign-in can expire.** How long the cloud accepts a sign-in is not known. When it stops accepting it, the plugin logs a warning and the setup page asks you to sign in again. Signing out leaves the machines in Matter, unreachable, with their rooms and automations, until you sign in again.
338
- - **A change on the machine shows up at once.** A machine sends its state to the cloud when it changes, from its remote or the Dyson app, and the plugin writes it to Matter as it comes.
339
- - <a id="power"></a>**Only some controls turn a machine on.** The power, a fan speed or the auto mode, the heating, the humidifying and find and follow turn a machine that is off on. Every other control, such as the night mode, the oscillation or a switch of [More controls](#more-controls), sets the machine and leaves it off, though the Dyson app turns the machine on for them.
340
- - **Commands are grouped.** A Matter app often changes several things at once. The plugin collects the changes of 300 milliseconds and sends them to the machine as one command.
341
- - **A device is reported as unreachable** after two reads in a row fail, or when its connection to the cloud closes and does not open again. It is reachable again on the first read that works.
417
+ - **A change on the machine shows up at once.** A machine sends its state to the cloud when it changes, from its remote or the MyDyson app, and the plugin writes it to Matter as it comes.
418
+ - <a id="power"></a>**Controls turn a machine on, as in the MyDyson app.** dyson-control sends the power on with nearly every control, as the MyDyson app does, so changing almost anything on a machine that is off turns it on. The continuous monitoring, the water hardness, the temperature unit, the air quality target and the wick drying leave it off, and so does turning off find and follow or an oscillation that sweeps angles. On a machine of the first generation, only the power, a fan speed and the auto mode turn it on. Turning the heating or the humidifying off on a machine that is off turns it on too, with the fan alone.
419
+ - **Commands are grouped.** A Matter app often changes several things at once. The plugin waits until no change has come for 300 milliseconds and sends the changes to the machine as one command.
420
+ - **A device is reported as unreachable** after two reads in a row fail, or when its connection to the cloud closes and does not open again. It is reachable again on the first read that works, or the first state the machine sends.
342
421
  - **The setup page is as open as Matterbridge itself.** Anyone who can reach the Matterbridge frontend can use it, and so control the machines of the signed-in account. It never returns the stored sign-in token.
343
- - **Faults are logged.** The plugin asks a machine for its faults when it first reads it and every 15 minutes after, and takes those it sends as they change. It logs each change, and the setup page shows them.
344
- - **Not in Matter:** the sleep timer, the clean cycle, the drying of a wick and the faults, which the setup page shows instead, and the temperature unit of a machine without a thermostat. A machine on the RabbitMQ broker of the Dyson cloud, and an account that signs in with a mobile number, are not supported by dyson-control.
422
+ - **Faults are logged.** The plugin asks a machine for its faults when it first reads it and at the first read after each 15 minutes, and takes those it sends as they change. It logs each change, and the setup page shows them.
423
+ - **Not in Matter:** the clean cycle, how long the drying of a wick has left and the faults, which the setup page shows instead, the sleep timer, and the temperature unit of a machine without a thermostat. A machine on the RabbitMQ broker of the Dyson cloud, and an account that signs in with a mobile number, are not supported by dyson-control.
345
424
 
346
425
  ## Development
347
426
 
@@ -358,21 +437,24 @@ npm run lint
358
437
 
359
438
  The plugin's source is in [src](./src), and its tests follow the same layout under [vitest](./vitest):
360
439
 
361
- | Path | What it holds |
362
- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
363
- | [module.ts](./src/module.ts) | The platform: the Matterbridge entry point, the account, the stored device list and the devices that run from it. |
364
- | [config.ts](./src/config.ts) | The stored configuration: its model, its validation and its comparisons. |
365
- | [controls.ts](./src/controls.ts) | What the capabilities of a machine let its device have in Matter, and the readings it has given. |
366
- | [mapping.ts](./src/mapping.ts) | The conversions between the Dyson model and the Matter clusters. |
367
- | [errors.ts](./src/errors.ts) | The helpers that describe errors. |
368
- | [accessory/](./src/accessory) | One machine in Matter: its endpoints, what the controllers ask of it and what the machine answers. |
369
- | [platform/](./src/platform) | What the platform keeps between restarts and machine lists: the readings of each machine, its own saves, the names and the firmware. |
370
- | [setup/](./src/setup) | The guided setup: the checks of a machine and the REST API of the setup page. |
440
+ | Path | What it holds |
441
+ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
442
+ | [module.ts](./src/module.ts) | The platform: the Matterbridge entry point, the account, the stored device list and the devices that run from it. |
443
+ | [config.ts](./src/config.ts) | The stored configuration: its model, its validation and its comparisons. |
444
+ | [controls.ts](./src/controls.ts) | What the capabilities of a machine let its device have in Matter, and the readings it has given. |
445
+ | [settingControls.ts](./src/settingControls.ts) | The switches and the mode selects of [More controls](#more-controls) and the water hardness: their labels and which machines get them. |
446
+ | [mapping.ts](./src/mapping.ts) | The conversions between the Dyson model and the Matter clusters. |
447
+ | [errors.ts](./src/errors.ts) | The helpers that describe errors. |
448
+ | [accessory/](./src/accessory) | One machine in Matter: its endpoints, what the controllers ask of it and what the machine answers. |
449
+ | [platform/](./src/platform) | What the platform keeps between restarts and machine lists: the readings of each machine, its own saves, the names and the firmware. |
450
+ | [setup/](./src/setup) | The guided setup: the checks of a machine and the REST API of the setup page. |
371
451
 
372
452
  The setup page is a small TypeScript page without a framework, in [apps/frontend](./apps/frontend), which esbuild bundles into one `app.js`. Matterbridge serves `apps/frontend/build` at `/plugins/matterbridge-dyson-care/`, and the page calls the plugin through `onFetch`: see [src/setup/setupApi.ts](./src/setup/setupApi.ts). The page takes the types of what the plugin sends from the plugin itself, through a TypeScript project reference to the plugin's build, which is why the plugin is built first. What a machine leaves to choose is worked out by the plugin and sent to the page: see `getAvailableControls` in [src/controls.ts](./src/controls.ts).
373
453
 
374
454
  The tests run the plugin against fake machines, whose capabilities dyson-control decodes from real machine types: see [vitest/fakeDyson.ts](./vitest/fakeDyson.ts).
375
455
 
456
+ To see the setup page without a Dyson account, `npm run screenshots` serves it as Matterbridge does, answers its API with the plugin's own handler in front of a fake account of simulated machines, and takes the [screenshots](./screenshots) of the guided setup in Chromium: see [scripts/screenshots.mjs](./scripts/screenshots.mjs). Build the plugin and the setup page first. It uses the Chromium of Playwright when it is installed, with `npx playwright install chromium`, and Google Chrome otherwise.
457
+
376
458
  ## Legal disclaimer
377
459
 
378
460
  An independent, community project for interoperability and home automation. It is not affiliated with, authorized, or endorsed by Dyson. All product names and trademarks are the property of their respective owners.