homebridge-tsvesync 1.5.0 → 1.5.2

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.
@@ -39,7 +39,25 @@ interface ExtendedVeSyncAirPurifier extends VeSyncAirPurifier {
39
39
  };
40
40
  }
41
41
 
42
+ /**
43
+ * The subset of a HomeKit write batch this accessory has to reconcile.
44
+ * Each field is present only if that characteristic was written.
45
+ */
46
+ interface PendingWrite {
47
+ active?: number;
48
+ targetState?: number;
49
+ rotationSpeed?: number;
50
+ }
51
+
42
52
  export class AirPurifierAccessory extends BaseAccessory {
53
+ /**
54
+ * How long to buffer characteristic writes before applying them. HAP-NodeJS
55
+ * dispatches every characteristic in one request within the same tick, so a
56
+ * short window is enough to see the whole batch; it stays far below HAP's
57
+ * 3s slow-write warning threshold.
58
+ */
59
+ private static readonly WRITE_COALESCE_MS = 50;
60
+
43
61
  private readonly capabilities: DeviceCapabilities;
44
62
  protected readonly device: VeSyncAirPurifier;
45
63
  private isAirBypassDevice: boolean;
@@ -49,6 +67,31 @@ export class AirPurifierAccessory extends BaseAccessory {
49
67
  private lastSetPercentage: number = 0; // Track the last percentage we set
50
68
  private skipNextUpdate: boolean = false; // Flag to skip the next update
51
69
 
70
+ // Coalesced write state. HomeKit scenes and automations send Active,
71
+ // TargetAirPurifierState and RotationSpeed in a single HAP request, and
72
+ // HAP-NodeJS dispatches those writes concurrently. Applying them
73
+ // independently makes them race and clobber each other, so they are
74
+ // buffered here and resolved into one intent. See resolveWrite().
75
+ private pendingWrite: PendingWrite | null = null;
76
+ private pendingWriteTimer: NodeJS.Timeout | null = null;
77
+ private pendingWritePromise: Promise<void> | null = null;
78
+ // Batches are applied one at a time. Dragging the slider produces a burst of
79
+ // writes spaced further apart than the coalesce window, so several batches
80
+ // can be in flight at once; without this their API calls interleave and the
81
+ // device can settle on whichever happens to land last rather than the last
82
+ // value the user chose.
83
+ private writeChain: Promise<void> = Promise.resolve();
84
+
85
+ // Tracks the last mode we commanded, to protect against stale API responses.
86
+ // VeSync is eventually consistent: for a few seconds after a mode change
87
+ // getDetails() still reports the *previous* mode, which would otherwise flip
88
+ // the HomeKit tile straight back (auto->manual, or manual->auto). Mirrors the
89
+ // guard the humidifier accessory already uses. Expires so an out-of-band
90
+ // change made in the VeSync app is not masked indefinitely.
91
+ private static readonly COMMANDED_MODE_TTL_MS = 30000;
92
+ private _lastCommandedMode: string | null = null;
93
+ private _lastCommandedModeTime = 0;
94
+
52
95
  constructor(
53
96
  platform: TSVESyncPlatform,
54
97
  accessory: PlatformAccessory,
@@ -299,19 +342,34 @@ export class AirPurifierAccessory extends BaseAccessory {
299
342
  return (this.device.deviceType || '').toUpperCase().includes('CORE200S');
300
343
  }
301
344
 
345
+ private isCore300S(): boolean {
346
+ return (this.device.deviceType || '').toUpperCase().includes('CORE300S');
347
+ }
348
+
349
+ /**
350
+ * The real number of manual fan speeds, which is not always what the library
351
+ * advertises. tsvesync declares `levels: [1,2,3,4]` for the Core 200S and
352
+ * Core 300S, but both hardware families only have three manual speeds -
353
+ * verified against a Core300S, where changeFanSpeed(4) reports success and
354
+ * the device settles at 3. Trusting the declared 4 produces a dead top notch
355
+ * where 80% and 100% both mean speed 3.
356
+ */
357
+ private getEffectiveMaxFanSpeed(): number {
358
+ if (this.isCore200S() || this.isCore300S()) {
359
+ return 3;
360
+ }
361
+ return this.getMaxFanSpeed();
362
+ }
363
+
302
364
  /**
303
365
  * Calculate the appropriate step size for discrete speed levels
304
366
  */
305
367
  private calculateRotationSpeedStep(): number {
306
- // Expose Sleep as the first notch when supported.
307
- // Core 200S uses 3 manual speeds (25% step). 4-speed models use 20% step.
368
+ // Expose Sleep as the first notch when supported. The step is simply the
369
+ // width of one notch, derived from the notch count so the slider grid and
370
+ // the percentage->notch mapping can never disagree.
308
371
  if (this.hasFeature('sleep_mode')) {
309
- if (this.hasFeature('turbo_mode')) {
310
- return 20;
311
- }
312
- if (this.isCore200S()) return 25;
313
- const max = this.getMaxFanSpeed();
314
- return max >= 4 ? 20 : 25;
372
+ return 100 / this.getTotalNotches();
315
373
  }
316
374
  const maxSpeed = this.getMaxFanSpeed();
317
375
  if (maxSpeed === 3) return 33.33;
@@ -319,6 +377,34 @@ export class AirPurifierAccessory extends BaseAccessory {
319
377
  return 1;
320
378
  }
321
379
 
380
+ /**
381
+ * Total slider notches: sleep, each manual speed, and turbo when supported.
382
+ */
383
+ private getTotalNotches(): number {
384
+ const max = this.getEffectiveMaxFanSpeed();
385
+ return max + (this.hasFeature('turbo_mode') ? 2 : 1);
386
+ }
387
+
388
+ /**
389
+ * Map a percentage to a slider notch by which equal-width range it falls in,
390
+ * rather than by rounding against our own step.
391
+ *
392
+ * This has to stay correct even when the controller disagrees with us about
393
+ * the step. HomeKit caches characteristic metadata on the home hub, so after
394
+ * an upgrade that changes minStep a controller can keep sending values on the
395
+ * *old* grid for an unknown period. Rounding against our step maps those to
396
+ * the wrong speed (a 60% on an old 20% grid became Low instead of Medium);
397
+ * range mapping gets it right on either grid.
398
+ */
399
+ private percentageToNotch(percentage: number): number {
400
+ if (typeof percentage !== 'number' || isNaN(percentage) || percentage <= 0) {
401
+ return 0;
402
+ }
403
+ const totalNotches = this.getTotalNotches();
404
+ const sliceWidth = 100 / totalNotches;
405
+ return Math.max(1, Math.min(totalNotches, Math.ceil(percentage / sliceWidth)));
406
+ }
407
+
322
408
  /**
323
409
  * Convert device speed to percentage
324
410
  */
@@ -331,7 +417,7 @@ export class AirPurifierAccessory extends BaseAccessory {
331
417
  }
332
418
  if (typeof speed !== 'number' || speed <= 0) return 0;
333
419
  const step = this.calculateRotationSpeedStep();
334
- const max = this.isCore200S() ? 3 : this.getMaxFanSpeed();
420
+ const max = this.getEffectiveMaxFanSpeed();
335
421
  // Manual speeds occupy notches 2..(max+1)
336
422
  const notch = Math.max(2, Math.min(max + 1, speed + 1));
337
423
  return Math.min(100, notch * step);
@@ -401,11 +487,10 @@ export class AirPurifierAccessory extends BaseAccessory {
401
487
  if (this.hasFeature('sleep_mode')) {
402
488
  if (typeof percentage !== 'number') return 1;
403
489
  percentage = Math.min(100, Math.max(0, percentage));
404
- const step = this.calculateRotationSpeedStep();
405
- const max = this.isCore200S() ? 3 : this.getMaxFanSpeed();
490
+ const max = this.getEffectiveMaxFanSpeed();
406
491
  const supportsTurbo = this.hasFeature('turbo_mode');
407
- const totalNotches = max + (supportsTurbo ? 2 : 1); // sleep + manual + optional turbo
408
- const notch = Math.max(0, Math.min(totalNotches, Math.round(percentage / step)));
492
+ const totalNotches = this.getTotalNotches(); // sleep + manual + optional turbo
493
+ const notch = this.percentageToNotch(percentage);
409
494
  if (supportsTurbo && notch === totalNotches) {
410
495
  return max;
411
496
  }
@@ -601,7 +686,7 @@ export class AirPurifierAccessory extends BaseAccessory {
601
686
  */
602
687
  private async getPetMode(): Promise<CharacteristicValue> {
603
688
  const extendedDevice = this.device as ExtendedVeSyncAirPurifier;
604
- return (extendedDevice.mode || '').toLowerCase() === 'pet';
689
+ return this.resolveEffectiveMode(extendedDevice.mode) === 'pet';
605
690
  }
606
691
 
607
692
  /**
@@ -641,6 +726,11 @@ export class AirPurifierAccessory extends BaseAccessory {
641
726
  throw new Error(`Failed to ${value ? 'enable' : 'disable'} pet mode`);
642
727
  }
643
728
 
729
+ // Hold the commanded mode against stale API reads
730
+ this.rememberCommandedMode(
731
+ value ? 'pet' : (this.hasFeature('auto_mode') ? 'auto' : 'manual')
732
+ );
733
+
644
734
  // Refresh characteristics so the main service and switch stay consistent
645
735
  await this.updateDeviceSpecificStates(this.device);
646
736
  } catch (error) {
@@ -728,9 +818,11 @@ export class AirPurifierAccessory extends BaseAccessory {
728
818
  * Update device states based on the latest details
729
819
  */
730
820
  protected async updateDeviceSpecificStates(details: any): Promise<void> {
731
- // Update power state (treat sleep as on for some VeSync models)
821
+ // Update power state (treat sleep as on for some VeSync models).
822
+ // Prefer the mode we last commanded - a poll that lands while VeSync is
823
+ // still reporting the previous mode must not flip the tile back.
732
824
  const extended = this.device as ExtendedVeSyncAirPurifier;
733
- const mode = (extended.mode || details.mode || '').toLowerCase();
825
+ const mode = this.resolveEffectiveMode(extended.mode || details.mode || '');
734
826
  const isSleep = mode === 'sleep';
735
827
  const isTurbo = this.hasFeature('turbo_mode') && mode === 'turbo';
736
828
  const isOn = isSleep || details.enabled || details.deviceStatus === 'on';
@@ -742,21 +834,17 @@ export class AirPurifierAccessory extends BaseAccessory {
742
834
  isOn ? 2 : 0
743
835
  );
744
836
 
745
- // Get the extended device to access mode information
746
- const extendedDevice = this.device as ExtendedVeSyncAirPurifier;
747
-
748
837
  // Update target state (MANUAL = 0, AUTO = 1)
749
838
  // Special handling for Core200S
750
839
  let targetState = 0; // Default to MANUAL
751
-
840
+
752
841
  if (this.device.deviceType.includes('Core200S')) {
753
842
  // Core200S always reports MANUAL mode
754
843
  targetState = 0; // MANUAL
755
- } else if (extendedDevice.mode) {
756
- // For other devices, including Core300S, use the reported mode.
757
- // Pet mode is an automatic mode, so surface it as AUTO on the main service.
758
- const reportedMode = (extendedDevice.mode || '').toLowerCase();
759
- targetState = (reportedMode === 'auto' || reportedMode === 'pet') ? 1 : 0;
844
+ } else if (mode) {
845
+ // For other devices, including Core300S, use the effective mode resolved
846
+ // above. Pet mode is an automatic mode, so surface it as AUTO.
847
+ targetState = this.modeToTargetState(mode);
760
848
  }
761
849
 
762
850
  this.service.updateCharacteristic(
@@ -858,6 +946,198 @@ export class AirPurifierAccessory extends BaseAccessory {
858
946
  }
859
947
  }
860
948
 
949
+ /**
950
+ * Buffer a characteristic write and return a promise that settles once the
951
+ * whole batch has been applied. Every characteristic in the batch shares the
952
+ * same promise, so HomeKit gets a success/failure per write as usual.
953
+ */
954
+ private queueWrite(key: keyof PendingWrite, value: number): Promise<void> {
955
+ if (!this.pendingWrite) {
956
+ this.pendingWrite = {};
957
+ }
958
+ this.pendingWrite[key] = value;
959
+
960
+ if (!this.pendingWritePromise) {
961
+ this.pendingWritePromise = new Promise<void>((resolve, reject) => {
962
+ this.pendingWriteTimer = setTimeout(() => {
963
+ const batch = this.pendingWrite ?? {};
964
+ this.pendingWrite = null;
965
+ this.pendingWritePromise = null;
966
+ this.pendingWriteTimer = null;
967
+ // Queue behind any batch still being applied so commands reach the
968
+ // device in the order the user made them.
969
+ this.writeChain = this.writeChain
970
+ .catch(() => undefined)
971
+ .then(() => this.resolveWrite(batch));
972
+ this.writeChain.then(resolve, reject);
973
+ }, AirPurifierAccessory.WRITE_COALESCE_MS);
974
+ // NB: deliberately not unref()'d - an unref'd timer lets the process
975
+ // exit before the buffered write is ever applied.
976
+ });
977
+ }
978
+
979
+ return this.pendingWritePromise;
980
+ }
981
+
982
+ /**
983
+ * Turn one buffered batch of HomeKit writes into a single device intent.
984
+ *
985
+ * The ordering rules that matter (issue #42):
986
+ * - An explicit AUTO write wins over the mode implied by the speed slider.
987
+ * This accessory encodes sleep/manual/turbo into RotationSpeed, so every
988
+ * speed write is implicitly a mode write; without this rule an automation
989
+ * that sets "on + auto + 60%" ends up in manual.
990
+ * - RotationSpeed 0 only means "turn off" when the same batch didn't also
991
+ * ask for the device to be on or set a mode. Otherwise "on + auto + 0%"
992
+ * turns the device on and straight back off.
993
+ */
994
+ private async resolveWrite(batch: PendingWrite): Promise<void> {
995
+ const { active, targetState } = batch;
996
+ let { rotationSpeed } = batch;
997
+
998
+ this.platform.log.debug(
999
+ `${this.device.deviceName}: HomeKit write batch ${JSON.stringify(batch)} ` +
1000
+ `(device reports mode=${(this.device as ExtendedVeSyncAirPurifier).mode}, ` +
1001
+ `status=${this.device.deviceStatus}, speed=${this.device.speed})`
1002
+ );
1003
+
1004
+ // An explicit power-off wins outright - nothing else in the batch matters.
1005
+ if (active === 0) {
1006
+ await this.applyActive(0);
1007
+ return;
1008
+ }
1009
+
1010
+ if (rotationSpeed === 0) {
1011
+ if (active !== 1 && targetState === undefined) {
1012
+ // Slider dragged to zero on its own - the long-standing "0% means off".
1013
+ await this.applyActive(0);
1014
+ return;
1015
+ }
1016
+ // Something else in the batch asked for the device to be on or set a
1017
+ // mode, so the 0% slider is stale state rather than an off request.
1018
+ this.platform.log.debug(
1019
+ `${this.device.deviceName}: Ignoring 0% speed - batch also requested on/mode`
1020
+ );
1021
+ rotationSpeed = undefined;
1022
+ }
1023
+
1024
+ // Power on first so the mode and speed commands land on a running device.
1025
+ if (active === 1) {
1026
+ await this.applyActive(1);
1027
+ }
1028
+
1029
+ // Explicit AUTO beats the slider. In auto the device picks its own speed,
1030
+ // so the requested percentage is advisory and deliberately not applied.
1031
+ if (targetState === 1) {
1032
+ await this.applyTargetState(1);
1033
+ return;
1034
+ }
1035
+
1036
+ // Otherwise the slider carries the mode (sleep / manual / turbo).
1037
+ if (rotationSpeed !== undefined) {
1038
+ await this.applyRotationSpeed(rotationSpeed);
1039
+ return;
1040
+ }
1041
+
1042
+ if (targetState === 0) {
1043
+ await this.applyTargetState(0);
1044
+ }
1045
+ }
1046
+
1047
+ /**
1048
+ * Write a commanded speed/mode back into the device's cached details.
1049
+ *
1050
+ * The bypass purifiers (Core series) don't update their own cache after a
1051
+ * successful changeFanSpeed - unlike the bypassV2 models, which do - so
1052
+ * device.speed stays stale until the next poll, and the poll interval has a
1053
+ * two minute floor. That stale value makes getRotationSpeed() disagree with
1054
+ * what we just set and snaps the slider back to the wrong notch.
1055
+ */
1056
+ private cacheCommandedSpeed(speed: number, mode?: string): void {
1057
+ const device = this.device as ExtendedVeSyncAirPurifier & {
1058
+ details?: Record<string, unknown>;
1059
+ };
1060
+
1061
+ // NB: `speed` and `mode` are getter-only on VeSyncFan and read straight
1062
+ // through to `details`. Assigning to them is a no-op in sloppy mode and a
1063
+ // TypeError under the strict-mode build, so write to `details` instead.
1064
+ if (device.details) {
1065
+ device.details.speed = speed;
1066
+ if (mode) {
1067
+ device.details.mode = mode;
1068
+ }
1069
+ }
1070
+ if (mode) {
1071
+ this.rememberCommandedMode(mode);
1072
+ }
1073
+ }
1074
+
1075
+ /**
1076
+ * Record a mode we just commanded so a stale API read can't undo it.
1077
+ */
1078
+ private rememberCommandedMode(mode: string): void {
1079
+ this._lastCommandedMode = (mode || '').toLowerCase();
1080
+ this._lastCommandedModeTime = Date.now();
1081
+ }
1082
+
1083
+ /**
1084
+ * Resolve the mode to report to HomeKit, preferring what we last commanded
1085
+ * over what the device currently reports. The override is dropped as soon as
1086
+ * the device catches up, or once it expires - so a mode changed in the VeSync
1087
+ * app still comes through.
1088
+ */
1089
+ private resolveEffectiveMode(reportedMode: string): string {
1090
+ const reported = (reportedMode || '').toLowerCase();
1091
+
1092
+ if (this._lastCommandedMode === null) {
1093
+ return reported;
1094
+ }
1095
+
1096
+ const elapsed = Date.now() - this._lastCommandedModeTime;
1097
+ if (reported === this._lastCommandedMode ||
1098
+ elapsed > AirPurifierAccessory.COMMANDED_MODE_TTL_MS) {
1099
+ // Device caught up, or we've waited long enough - stop overriding.
1100
+ this._lastCommandedMode = null;
1101
+ return reported;
1102
+ }
1103
+
1104
+ this.platform.log.debug(
1105
+ `${this.device.deviceName}: Using commanded mode '${this._lastCommandedMode}' ` +
1106
+ `instead of device-reported '${reported}'`
1107
+ );
1108
+ return this._lastCommandedMode;
1109
+ }
1110
+
1111
+ /**
1112
+ * Map a VeSync mode to the HomeKit TargetAirPurifierState value.
1113
+ * Pet is an automatic mode, so it surfaces as AUTO like auto itself.
1114
+ */
1115
+ private modeToTargetState(mode: string): number {
1116
+ const normalised = (mode || '').toLowerCase();
1117
+ return (normalised === 'auto' || normalised === 'pet') ? 1 : 0;
1118
+ }
1119
+
1120
+ /**
1121
+ * Push the mode back to HomeKit immediately after we change it.
1122
+ *
1123
+ * The RotationSpeed slider implicitly carries a mode (sleep/manual/turbo),
1124
+ * so dragging it can move the device out of auto. Without this the tile
1125
+ * keeps showing the old mode until the next poll - and the poll interval has
1126
+ * a two minute floor, so "Auto" would linger long after the device had
1127
+ * actually switched to Manual.
1128
+ */
1129
+ private syncTargetStateToHomeKit(mode: string): void {
1130
+ this.rememberCommandedMode(mode);
1131
+ const targetState = this.modeToTargetState(mode);
1132
+ this.service.updateCharacteristic(
1133
+ this.platform.Characteristic.TargetAirPurifierState,
1134
+ targetState
1135
+ );
1136
+ this.platform.log.debug(
1137
+ `${this.device.deviceName}: Synced TargetAirPurifierState to ${targetState} for mode '${mode}'`
1138
+ );
1139
+ }
1140
+
861
1141
  /**
862
1142
  * Get target state (MANUAL = 0, AUTO = 1)
863
1143
  */
@@ -869,16 +1149,21 @@ export class AirPurifierAccessory extends BaseAccessory {
869
1149
 
870
1150
  const extendedDevice = this.device as ExtendedVeSyncAirPurifier;
871
1151
  // Pet mode is an automatic mode, so report it as AUTO on the main service.
872
- const reportedMode = (extendedDevice.mode || '').toLowerCase();
873
- const targetState = (reportedMode === 'auto' || reportedMode === 'pet') ? 1 : 0;
1152
+ // Prefer the mode we last commanded so a stale API read can't flip the tile.
1153
+ const effectiveMode = this.resolveEffectiveMode(extendedDevice.mode);
874
1154
 
875
- return targetState;
1155
+ return this.modeToTargetState(effectiveMode);
876
1156
  }
877
1157
 
878
1158
  /**
879
- * Set target state (AUTO = 0, MANUAL = 1)
1159
+ * Set target state (MANUAL = 0, AUTO = 1). Buffered so it can be reconciled
1160
+ * with any Active/RotationSpeed writes sent in the same HomeKit request.
880
1161
  */
881
1162
  private async setTargetState(value: CharacteristicValue): Promise<void> {
1163
+ return this.queueWrite('targetState', value as number);
1164
+ }
1165
+
1166
+ private async applyTargetState(value: CharacteristicValue): Promise<void> {
882
1167
  try {
883
1168
  const targetState = value as number;
884
1169
  const extendedDevice = this.device as ExtendedVeSyncAirPurifier;
@@ -913,7 +1198,11 @@ export class AirPurifierAccessory extends BaseAccessory {
913
1198
  if (!success) {
914
1199
  throw new Error(`Failed to set mode to ${mode}`);
915
1200
  }
916
-
1201
+
1202
+ // Remember what we commanded so the stale-read guard holds the tile on
1203
+ // the new mode until VeSync catches up.
1204
+ this.rememberCommandedMode(mode);
1205
+
917
1206
  // Update device state and characteristics
918
1207
  await this.updateDeviceSpecificStates(this.device);
919
1208
  } catch (error) {
@@ -926,17 +1215,28 @@ export class AirPurifierAccessory extends BaseAccessory {
926
1215
  */
927
1216
  private async getRotationSpeed(): Promise<CharacteristicValue> {
928
1217
  const extended = this.device as ExtendedVeSyncAirPurifier;
929
- if (this.hasFeature('turbo_mode') && (extended.mode || '').toLowerCase() === 'turbo') {
1218
+ const effectiveMode = this.resolveEffectiveMode(extended.mode);
1219
+ if (this.hasFeature('turbo_mode') && effectiveMode === 'turbo') {
930
1220
  return 100;
931
1221
  }
1222
+ // Sleep occupies the first notch. This has to be checked before the
1223
+ // on/off gate below: while the device is ON the gate falls through to the
1224
+ // speed conversion, which would report the last manual speed instead of
1225
+ // the sleep notch.
1226
+ if (this.hasFeature('sleep_mode') && effectiveMode === 'sleep') {
1227
+ if (this.device.deviceStatus !== 'on') {
1228
+ return 0;
1229
+ }
1230
+ // Prefer the value the controller sent, so a controller on a stale grid
1231
+ // isn't dragged to our canonical notch position.
1232
+ return this.lastSetPercentage > 0
1233
+ ? this.lastSetPercentage
1234
+ : this.calculateRotationSpeedStep();
1235
+ }
932
1236
  // If device is off or speed is not defined, return 0
933
- if (this.device.deviceStatus !== 'on' ||
934
- this.device.speed === undefined ||
1237
+ if (this.device.deviceStatus !== 'on' ||
1238
+ this.device.speed === undefined ||
935
1239
  this.device.speed === null) {
936
- // If in sleep mode, surface the first notch
937
- if (this.hasFeature('sleep_mode') && (extended.mode || '').toLowerCase() === 'sleep') {
938
- return this.calculateRotationSpeedStep();
939
- }
940
1240
  return 0;
941
1241
  }
942
1242
 
@@ -954,35 +1254,28 @@ export class AirPurifierAccessory extends BaseAccessory {
954
1254
  }
955
1255
 
956
1256
  /**
957
- * Set rotation speed
1257
+ * Set rotation speed. Buffered so it can be reconciled with any
1258
+ * Active/TargetAirPurifierState writes sent in the same HomeKit request -
1259
+ * the slider implicitly carries a mode, so it must not clobber an explicit
1260
+ * AUTO written alongside it.
958
1261
  */
959
1262
  private async setRotationSpeed(value: CharacteristicValue): Promise<void> {
1263
+ let percentage = value as number;
1264
+ if (typeof percentage !== 'number' || isNaN(percentage)) {
1265
+ this.platform.log.warn(`Invalid rotation speed value: ${value} for device: ${this.device.deviceName}`);
1266
+ return;
1267
+ }
1268
+ percentage = Math.min(100, Math.max(0, percentage));
1269
+ return this.queueWrite('rotationSpeed', percentage);
1270
+ }
1271
+
1272
+ private async applyRotationSpeed(value: CharacteristicValue): Promise<void> {
960
1273
  try {
961
- // Ensure value is a valid number
962
- let percentage = value as number;
963
- if (isNaN(percentage) || percentage === null || percentage === undefined) {
964
- this.platform.log.warn(`Invalid rotation speed value: ${value} for device: ${this.device.deviceName}`);
965
- return;
966
- }
967
-
968
- // Ensure percentage is between 0 and 100
969
- percentage = Math.min(100, Math.max(0, percentage));
970
-
1274
+ // Value is already validated and clamped by setRotationSpeed()
1275
+ const percentage = value as number;
1276
+
971
1277
  this.platform.log.debug(`Setting rotation speed to ${percentage}% for device: ${this.device.deviceName}`);
972
-
973
- if (percentage === 0) {
974
- // Turn off the device instead of setting speed to 0
975
- this.platform.log.debug(`Turning off device ${this.device.deviceName} due to 0% rotation speed`);
976
- const success = await this.device.turnOff();
977
- if (!success) {
978
- throw new Error('Failed to turn off device');
979
- }
980
- // Reset tracking variables when turning off
981
- this.lastSetSpeed = 0;
982
- this.lastSetPercentage = 0;
983
- return;
984
- }
985
-
1278
+
986
1279
  const extendedDevice = this.device as ExtendedVeSyncAirPurifier;
987
1280
 
988
1281
  // Check if device is off and turn it on first
@@ -1006,11 +1299,14 @@ export class AirPurifierAccessory extends BaseAccessory {
1006
1299
 
1007
1300
  // When using sleep-as-first-notch, map slider notches robustly by rounding
1008
1301
  if (this.hasFeature('sleep_mode')) {
1009
- const max = this.isCore200S() ? 3 : this.getMaxFanSpeed();
1010
- const step = this.calculateRotationSpeedStep();
1302
+ const max = this.getEffectiveMaxFanSpeed();
1011
1303
  const supportsTurbo = this.hasFeature('turbo_mode');
1012
- const totalNotches = max + (supportsTurbo ? 2 : 1); // sleep + manual + optional turbo
1013
- const notch = Math.max(0, Math.min(totalNotches, Math.round(percentage / step)));
1304
+ const totalNotches = this.getTotalNotches(); // sleep + manual + optional turbo
1305
+ const notch = this.percentageToNotch(percentage);
1306
+ // Echo back the value the controller actually sent rather than our own
1307
+ // canonical notch position. If its cached step differs from ours the
1308
+ // two are not equal, and echoing ours makes the slider visibly jump.
1309
+ const echoPct = percentage;
1014
1310
  if (notch <= 1) {
1015
1311
  // Sleep
1016
1312
  this.platform.log.info(`Changing mode to sleep for device: ${this.device.deviceName}`);
@@ -1024,11 +1320,12 @@ export class AirPurifierAccessory extends BaseAccessory {
1024
1320
  throw new Error('Failed to set sleep mode');
1025
1321
  }
1026
1322
  // Immediate UI feedback
1027
- this.service.updateCharacteristic(this.platform.Characteristic.RotationSpeed, step);
1323
+ this.service.updateCharacteristic(this.platform.Characteristic.RotationSpeed, echoPct);
1028
1324
  this.service.updateCharacteristic(this.platform.Characteristic.Active, 1);
1029
1325
  this.service.updateCharacteristic(this.platform.Characteristic.CurrentAirPurifierState, 2);
1326
+ this.syncTargetStateToHomeKit('sleep');
1030
1327
  this.lastSetSpeed = 0;
1031
- this.lastSetPercentage = step;
1328
+ this.lastSetPercentage = echoPct;
1032
1329
  this.skipNextUpdate = true;
1033
1330
  return;
1034
1331
  }
@@ -1046,6 +1343,7 @@ export class AirPurifierAccessory extends BaseAccessory {
1046
1343
  this.service.updateCharacteristic(this.platform.Characteristic.RotationSpeed, 100);
1047
1344
  this.service.updateCharacteristic(this.platform.Characteristic.Active, 1);
1048
1345
  this.service.updateCharacteristic(this.platform.Characteristic.CurrentAirPurifierState, 2);
1346
+ this.syncTargetStateToHomeKit('turbo');
1049
1347
  this.lastSetSpeed = max;
1050
1348
  this.lastSetPercentage = 100;
1051
1349
  this.skipNextUpdate = true;
@@ -1060,17 +1358,22 @@ export class AirPurifierAccessory extends BaseAccessory {
1060
1358
  const modeNow = (extendedDevice.mode || '').toLowerCase();
1061
1359
  if (modeNow === 'auto' || modeNow === 'sleep' || (supportsTurbo && modeNow === 'turbo')) {
1062
1360
  this.platform.log.info(`Changing mode to manual for device: ${this.device.deviceName}`);
1361
+ let modeOk = false;
1063
1362
  if (typeof extendedDevice.manualMode === 'function') {
1064
- await extendedDevice.manualMode();
1363
+ modeOk = await extendedDevice.manualMode();
1065
1364
  } else if (typeof extendedDevice.setMode === 'function') {
1066
- await extendedDevice.setMode('manual');
1365
+ modeOk = await extendedDevice.setMode('manual');
1366
+ }
1367
+ if (!modeOk) {
1368
+ // Don't silently push a speed at a device still sitting in auto
1369
+ throw new Error('Failed to set manual mode');
1067
1370
  }
1068
1371
  }
1069
- // Update UI early
1070
- const uiPct = Math.min(100, manualNotch * step);
1071
- this.service.updateCharacteristic(this.platform.Characteristic.RotationSpeed, uiPct);
1372
+ // Update UI early, echoing the controller's own value
1373
+ this.service.updateCharacteristic(this.platform.Characteristic.RotationSpeed, echoPct);
1374
+ this.syncTargetStateToHomeKit('manual');
1072
1375
  this.lastSetSpeed = desiredSpeed;
1073
- this.lastSetPercentage = uiPct;
1376
+ this.lastSetPercentage = echoPct;
1074
1377
  this.skipNextUpdate = true;
1075
1378
  const ok = await this.device.changeFanSpeed(desiredSpeed);
1076
1379
  if (!ok) {
@@ -1078,6 +1381,9 @@ export class AirPurifierAccessory extends BaseAccessory {
1078
1381
  this.lastSetPercentage = 0;
1079
1382
  throw new Error(`Failed to set speed to ${desiredSpeed}`);
1080
1383
  }
1384
+ // The library leaves its cache stale for these models - fix it up so
1385
+ // the slider doesn't snap back to the previously reported speed.
1386
+ this.cacheCommandedSpeed(desiredSpeed, 'manual');
1081
1387
  return;
1082
1388
  }
1083
1389
 
@@ -1107,11 +1413,17 @@ export class AirPurifierAccessory extends BaseAccessory {
1107
1413
  // For devices without sleep notch, ensure manual mode if required
1108
1414
  const modeNow = (extendedDevice.mode || '').toLowerCase();
1109
1415
  if (modeNow === 'auto') {
1416
+ let modeOk = false;
1110
1417
  if (typeof extendedDevice.manualMode === 'function') {
1111
- await extendedDevice.manualMode();
1418
+ modeOk = await extendedDevice.manualMode();
1112
1419
  } else if (typeof extendedDevice.setMode === 'function') {
1113
- await extendedDevice.setMode('manual');
1420
+ modeOk = await extendedDevice.setMode('manual');
1114
1421
  }
1422
+ if (!modeOk) {
1423
+ throw new Error('Failed to set manual mode');
1424
+ }
1425
+ // Reflect the mode change in HomeKit right away
1426
+ this.syncTargetStateToHomeKit('manual');
1115
1427
  }
1116
1428
 
1117
1429
  // Convert percentage to device speed using our consistent conversion method
@@ -1140,13 +1452,15 @@ export class AirPurifierAccessory extends BaseAccessory {
1140
1452
  );
1141
1453
 
1142
1454
  const success = await this.device.changeFanSpeed(speed);
1143
-
1455
+
1144
1456
  if (!success) {
1145
1457
  // If the API call failed, reset our tracking variables
1146
1458
  this.lastSetSpeed = 0;
1147
1459
  this.lastSetPercentage = 0;
1148
1460
  throw new Error(`Failed to set speed to ${speed}`);
1149
1461
  }
1462
+
1463
+ this.cacheCommandedSpeed(speed, 'manual');
1150
1464
 
1151
1465
  this.platform.log.debug(`Successfully set fan speed to ${speed} (${percentage}%) for device: ${this.device.deviceName}`);
1152
1466
 
@@ -1162,7 +1476,16 @@ export class AirPurifierAccessory extends BaseAccessory {
1162
1476
  return this.device.deviceStatus === 'on' ? 1 : 0;
1163
1477
  }
1164
1478
 
1479
+ /**
1480
+ * Set active state. Buffered so it can be reconciled with any
1481
+ * RotationSpeed/TargetAirPurifierState writes sent in the same HomeKit
1482
+ * request - notably so a 0% slider can't turn the device straight back off.
1483
+ */
1165
1484
  private async setActive(value: CharacteristicValue): Promise<void> {
1485
+ return this.queueWrite('active', value as number === 1 ? 1 : 0);
1486
+ }
1487
+
1488
+ private async applyActive(value: CharacteristicValue): Promise<void> {
1166
1489
  try {
1167
1490
  const isOn = value as number === 1;
1168
1491
  this.platform.log.debug(`Setting device ${this.device.deviceName} to ${isOn ? 'on' : 'off'}`);