daikin-local-control 0.2.1 → 0.3.0

package/src/clients/classic.ts

@@ -15,6 +15,10 @@ import {
   encodeClassicSpecialMode,
   encodeClassicTerminalKey,
   encodeClassicTerminalScope,
+  parseClassicHolidayMode,
+  parseClassicLed,
+  parseClassicMetadata,
+  parseClassicOutOfHomeAccess,
 } from "../codecs/classic/extendedControl.js";
 import {
   assertClassicOk,
@@ -25,17 +29,20 @@ import {
   parseClassicSensors,
   parseClassicState,
 } from "../codecs/classic/state.js";
+import { parseDeviceInfo } from "../codecs/device.js";
 import type { DaikinCapabilities } from "../models/capabilities.js";
+import type { DaikinDeviceInfo } from "../models/device.js";
 import type {
   DemandControl,
   DeviceMetadata,
-  SpecialMode,
   TerminalScope,
 } from "../models/extendedControl.js";
 import type {
   DaikinControl,
   DaikinSensors,
   DaikinState,
+  DaikinStateAndSensors,
+  SpecialMode,
 } from "../models/state.js";
 import {
   type DaikinRequestOptions,
@@ -44,6 +51,7 @@ import {
   withRetry,
 } from "../transport.js";
 import type { DaikinClient } from "./client.js";
+import { SetStateCache } from "./setStateCache.js";
 
 // Classic CGI endpoints (BRP069-style). Reads and writes are both HTTP GET with
 // query parameters; the reply is `key=value,key=value`.
@@ -75,28 +83,40 @@ export class ClassicDaikinClient implements DaikinClient {
   // A unit's capabilities don't change, and `setState` needs them, so they are
   // read once.
   private capabilityFields: Promise<Record<string, string>> | undefined;
+  private readonly setStateCache: SetStateCache;
 
-  /** `close` closes `transport`, so give each client a transport of its own. */
+  /** `close` closes `transport`, so give each client a transport of its own.
+   * `maxStateAgeForSetStateInMs` defaults to 0: see
+   * `CreateDaikinClientOptions.maxStateAgeForSetStateInMs`. */
   constructor(
     private readonly transport: DaikinTransport,
     private readonly retryOptions?: DaikinRetryOptions,
-  ) {}
+    maxStateAgeForSetStateInMs = 0,
+  ) {
+    this.setStateCache = new SetStateCache(maxStateAgeForSetStateInMs);
+  }
 
   close(): Promise<void> {
     return this.transport.close();
   }
 
+  async getDeviceInfo(): Promise<DaikinDeviceInfo> {
+    return parseDeviceInfo(await this.command(CLASSIC_ROUTES.basicInfo));
+  }
+
   async getCapabilities(): Promise<DaikinCapabilities> {
     return parseClassicCapabilities(await this.readCapabilityFields());
   }
 
   async getState(): Promise<DaikinState> {
-    return parseClassicState(await this.command(CLASSIC_ROUTES.getControlInfo));
+    return parseClassicState(await this.readControlInfo());
   }
 
   async setState(control: DaikinControl): Promise<void> {
     const capabilityFields = await this.readCapabilityFields();
-    const current = await this.command(CLASSIC_ROUTES.getControlInfo);
+    const current =
+      this.setStateCache.get() ??
+      (await this.command(CLASSIC_ROUTES.getControlInfo));
     await this.command(
       CLASSIC_ROUTES.setControlInfo,
       applyClassicControl(current, control, capabilityFields),
@@ -109,14 +129,32 @@ export class ClassicDaikinClient implements DaikinClient {
     );
   }
 
+  async getStateAndSensors(): Promise<DaikinStateAndSensors> {
+    return { state: await this.getState(), sensors: await this.getSensors() };
+  }
+
   // --- extended controls ---------------------------------------------------
-  // Each maps to its own endpoint (not control_info).
+  // Each write goes to its own endpoint, not `set_control_info`.
+
+  /** Whether the adapter's status LED is on (`basic_info`): `null` when the
+   * adapter does not report it. */
+  async getLed(): Promise<boolean | null> {
+    return parseClassicLed(await this.command(CLASSIC_ROUTES.basicInfo));
+  }
 
   /** Adapter status LED on/off (`set_led`). */
   async setLed(on: boolean): Promise<void> {
     await this.command(CLASSIC_ROUTES.setLed, encodeClassicLed(on));
   }
 
+  /** Whether holiday mode is on (`basic_info`): `null` when the adapter does
+   * not report it. */
+  async getHolidayMode(): Promise<boolean | null> {
+    return parseClassicHolidayMode(
+      await this.command(CLASSIC_ROUTES.basicInfo),
+    );
+  }
+
   /** Holiday / away mode (`set_holiday`). */
   async setHolidayMode(enabled: boolean): Promise<void> {
     await this.command(
@@ -141,6 +179,14 @@ export class ClassicDaikinClient implements DaikinClient {
     );
   }
 
+  /** Whether the unit can be operated from outside the home network
+   * (`basic_info`): `null` when the adapter does not report it. */
+  async getOutOfHomeAccess(): Promise<boolean | null> {
+    return parseClassicOutOfHomeAccess(
+      await this.command(CLASSIC_ROUTES.basicInfo),
+    );
+  }
+
   /** Whether the unit can be operated from outside the home network
    * (`set_remote_method`). */
   async setOutOfHomeAccess(enabled: boolean): Promise<void> {
@@ -168,6 +214,11 @@ export class ClassicDaikinClient implements DaikinClient {
     );
   }
 
+  /** Name / icon / group metadata (`basic_info`). */
+  async getMetadata(): Promise<DeviceMetadata> {
+    return parseClassicMetadata(await this.command(CLASSIC_ROUTES.basicInfo));
+  }
+
   /** Name / icon / group metadata (`set_name` etc.). */
   async setMetadata(metadata: DeviceMetadata): Promise<void> {
     if (metadata.name !== undefined) {
@@ -229,10 +280,25 @@ export class ClassicDaikinClient implements DaikinClient {
         path,
         ...(parameters ? { query: parameters } : {}),
       });
-    const fields = parseClassicKeyValue(
-      await (retry ? withRetry(send, this.retryOptions) : send()),
-    );
-    assertClassicOk(fields);
+    try {
+      const fields = parseClassicKeyValue(
+        await (retry ? withRetry(send, this.retryOptions) : send()),
+      );
+      assertClassicOk(fields);
+      return fields;
+    } finally {
+      // Every request that changes the unit takes parameters, and any of them
+      // may change what `get_control_info` answers, even one that failed: a
+      // request that timed out may still have reached the unit.
+      if (parameters) {
+        this.setStateCache.clear();
+      }
+    }
+  }
+
+  private async readControlInfo(): Promise<Record<string, string>> {
+    const fields = await this.command(CLASSIC_ROUTES.getControlInfo);
+    this.setStateCache.set(fields);
     return fields;
   }
 

package/src/clients/client.ts

@@ -1,8 +1,10 @@
 import type { DaikinCapabilities } from "../models/capabilities.js";
+import type { DaikinDeviceInfo } from "../models/device.js";
 import type {
   DaikinControl,
   DaikinSensors,
   DaikinState,
+  DaikinStateAndSensors,
 } from "../models/state.js";
 
 /** The controls every adapter offers, whatever its wire protocol or
@@ -11,6 +13,9 @@ import type {
  * `ClassicDaikinClient.registerTerminal`. Every method rejects with a
  * `DaikinError` when its request fails. */
 export interface DaikinClient {
+  /** The adapter's MAC address and firmware version. */
+  getDeviceInfo(): Promise<DaikinDeviceInfo>;
+
   /** The unit's supported features. */
   getCapabilities(): Promise<DaikinCapabilities>;
 
@@ -18,12 +23,19 @@ export interface DaikinClient {
   getState(): Promise<DaikinState>;
 
   /** Change part of the state. The client reads the current state, overlays the
-   * control, and writes the whole thing back. */
+   * control, and writes the whole thing back. It skips the read when it holds
+   * a reply to `getState` or `getStateAndSensors` younger than
+   * `CreateDaikinClientOptions.maxStateAgeForSetStateInMs`. */
   setState(control: DaikinControl): Promise<void>;
 
   /** Read-only temperature / humidity readings. */
   getSensors(): Promise<DaikinSensors>;
 
+  /** What `getState` and `getSensors` resolve with, together. A DSIOT adapter
+   * answers both in one request, where calling the two sends the same request
+   * twice. A classic adapter takes one request for each. */
+  getStateAndSensors(): Promise<DaikinStateAndSensors>;
+
   /** Close the connection to the adapter. */
   close(): Promise<void>;
 }

package/src/clients/dsiot.ts

@@ -1,4 +1,5 @@
 import { parseDsiotCapabilities } from "../codecs/dsiot/capabilities.js";
+import { parseDsiotDeviceInfo } from "../codecs/dsiot/device.js";
 import {
   buildDsiotMultireqGet,
   buildDsiotMultireqUpdate,
@@ -12,10 +13,12 @@ import {
   parseDsiotState,
 } from "../codecs/dsiot/state.js";
 import type { DaikinCapabilities } from "../models/capabilities.js";
+import type { DaikinDeviceInfo } from "../models/device.js";
 import type {
   DaikinControl,
   DaikinSensors,
   DaikinState,
+  DaikinStateAndSensors,
 } from "../models/state.js";
 import {
   type DaikinRequestOptions,
@@ -24,6 +27,7 @@ import {
   withRetry,
 } from "../transport.js";
 import type { DaikinClient } from "./client.js";
+import { SetStateCache } from "./setStateCache.js";
 
 // DSIOT endpoints (BRP084-style). Climate state is a POST (read) or PUT (write)
 // of a JSON property tree to `multireq`.
@@ -35,33 +39,47 @@ const DSIOT_ROUTES = {
 /** DSIOT adapter (BRP084-style). One endpoint, `/dsiot/multireq`: POST to read
  * whole `dgc_status` trees, PUT to write one merged tree. */
 export class DsiotDaikinClient implements DaikinClient {
-  /** `close` closes `transport`, so give each client a transport of its own. */
+  private readonly setStateCache: SetStateCache;
+
+  /** `close` closes `transport`, so give each client a transport of its own.
+   * `maxStateAgeForSetStateInMs` defaults to 0: see
+   * `CreateDaikinClientOptions.maxStateAgeForSetStateInMs`. */
   constructor(
     private readonly transport: DaikinTransport,
     private readonly retryOptions?: DaikinRetryOptions,
-  ) {}
+    maxStateAgeForSetStateInMs = 0,
+  ) {
+    this.setStateCache = new SetStateCache(maxStateAgeForSetStateInMs);
+  }
 
   close(): Promise<void> {
     return this.transport.close();
   }
 
+  async getDeviceInfo(): Promise<DaikinDeviceInfo> {
+    return parseDsiotDeviceInfo(
+      await this.multireqGet([DSIOT_TARGETS.adapterInfo]),
+    );
+  }
+
   async getCapabilities(): Promise<DaikinCapabilities> {
     return parseDsiotCapabilities(
       await this.multireqGet([
         DSIOT_TARGETS.adapterInfo,
         DSIOT_TARGETS.indoorStatus,
+        DSIOT_TARGETS.outdoorStatus,
       ]),
     );
   }
 
   async getState(): Promise<DaikinState> {
-    return parseDsiotState(
-      await this.multireqGet([DSIOT_TARGETS.indoorStatus]),
-    );
+    return parseDsiotState(await this.readStatus());
   }
 
   async setState(control: DaikinControl): Promise<void> {
-    const values = await this.multireqGet([DSIOT_TARGETS.indoorStatus]);
+    const values =
+      this.setStateCache.get() ??
+      (await this.multireqGet([DSIOT_TARGETS.indoorStatus]));
     await this.multireqUpdate(applyDsiotControl(values, control));
   }
 
@@ -74,6 +92,14 @@ export class DsiotDaikinClient implements DaikinClient {
     );
   }
 
+  async getStateAndSensors(): Promise<DaikinStateAndSensors> {
+    const values = await this.readStatus();
+    return {
+      state: parseDsiotState(values),
+      sensors: parseDsiotSensors(values),
+    };
+  }
+
   // --- extended controls ---------------------------------------------------
 
   /** Reboot the adapter (`/config/system/reboot`). */
@@ -109,8 +135,25 @@ export class DsiotDaikinClient implements DaikinClient {
   ): Promise<Record<string, string>> {
     const send = () =>
       this.transport.send({ method, path: DSIOT_ROUTES.multireq, jsonBody });
-    return parseDsiotMultireqReply(
-      await (retry ? withRetry(send, this.retryOptions) : send()),
-    );
+    try {
+      return parseDsiotMultireqReply(
+        await (retry ? withRetry(send, this.retryOptions) : send()),
+      );
+    } finally {
+      // Even a write that failed: one that timed out may still have reached
+      // the unit.
+      if (method === "PUT") {
+        this.setStateCache.clear();
+      }
+    }
+  }
+
+  private async readStatus(): Promise<Record<string, string>> {
+    const values = await this.multireqGet([
+      DSIOT_TARGETS.indoorStatus,
+      DSIOT_TARGETS.outdoorStatus,
+    ]);
+    this.setStateCache.set(values);
+    return values;
   }
 }

package/src/clients/setStateCache.ts

@@ -0,0 +1,28 @@
+/** Caches the reply a client last read a unit's state from, for `setState`
+ * alone. A write carries more than the fields a control changes, so
+ * `setState` builds it from what the unit holds: from this reply while it is
+ * fresh, and from a read of its own otherwise. No read is answered from the
+ * cache: see DESIGN.md#the-read-before-a-write. */
+export class SetStateCache {
+  private kept:
+    | { reply: Record<string, string>; readAtInMs: number }
+    | undefined;
+
+  /** `get` answers a reply younger than `maxAgeInMs`, so 0 answers none. */
+  constructor(private readonly maxAgeInMs: number) {}
+
+  set(reply: Record<string, string>): void {
+    this.kept = { reply, readAtInMs: performance.now() };
+  }
+
+  get(): Record<string, string> | undefined {
+    return this.kept !== undefined &&
+      performance.now() - this.kept.readAtInMs < this.maxAgeInMs
+      ? this.kept.reply
+      : undefined;
+  }
+
+  clear(): void {
+    this.kept = undefined;
+  }
+}

package/src/codecs/classic/capabilities.ts

@@ -9,6 +9,8 @@ import {
   HUMIDITY_SETTINGS,
   OPERATING_MODES,
   type OperatingMode,
+  SPECIAL_MODES,
+  type SpecialMode,
   SWING_MODES,
   type SwingMode,
   type TargetHumidity,
@@ -16,6 +18,14 @@ import {
 } from "../../models/state.js";
 
 const CAPABILITY_VERSIONS = ["0", "1", "2", "3"];
+// `en_spmode` sets one bit for each special mode the unit takes. Bit 8 is a
+// mode outside `SpecialMode`. The powerful and econo bits count only at
+// `cpv=3` with a `cpv_minor` other than `00`: see UNSUPPORTED.md.
+const SPECIAL_MODE_BITS: Record<SpecialMode, number> = {
+  powerful: 1,
+  econo: 2,
+  streamer: 4,
+};
 const COOLING_ONLY_MODES: readonly OperatingMode[] = [
   "cool",
   "dehumidify",
@@ -100,6 +110,7 @@ export function parseClassicCapabilities(
       fan: null,
     },
     targetHumidities: targetHumidities(fields, modern, offeredModes),
+    specialModes: specialModes(fields, cpv, offeredModes),
     specialOutlet: cpv === "3" && fields.airoutlet_pv === "0",
     energyMonitoring: fields.elec === "1",
     demandControl: fields.adp_kind === "4" && fields.dmnd === "1",
@@ -108,6 +119,34 @@ export function parseClassicCapabilities(
   };
 }
 
+// Lists none for a unit that reports no `en_spmode`, and econo in every mode
+// but fan: see UNSUPPORTED.md.
+function specialModes(
+  fields: Record<string, string>,
+  cpv: string,
+  offeredModes: OperatingMode[],
+): Record<OperatingMode, SpecialMode[]> {
+  const bits = Number.parseInt(fields.en_spmode ?? "", 10);
+  const followsPowerfulAndEcono =
+    cpv === "3" && (fields.cpv_minor ?? "00") !== "00";
+  const taken = SPECIAL_MODES.filter(
+    (specialMode) =>
+      (bits & SPECIAL_MODE_BITS[specialMode]) !== 0 &&
+      (specialMode === "streamer" || followsPowerfulAndEcono),
+  );
+  const inMode = (mode: OperatingMode) =>
+    offeredModes.includes(mode)
+      ? taken.filter((specialMode) => mode !== "fan" || specialMode !== "econo")
+      : [];
+  return {
+    auto: inMode("auto"),
+    dehumidify: inMode("dehumidify"),
+    cool: inMode("cool"),
+    heat: inMode("heat"),
+    fan: inMode("fan"),
+  };
+}
+
 function present(fields: Record<string, string>, key: string): boolean {
   return (fields[key] ?? "") !== "";
 }

package/src/codecs/classic/extendedControl.ts

@@ -2,12 +2,14 @@ import type {
   DemandControl,
   DemandMode,
   DeviceGroup,
-  SpecialMode,
+  DeviceMetadata,
   TerminalScope,
 } from "../../models/extendedControl.js";
+import type { SpecialMode } from "../../models/state.js";
+import { decodeClassicText } from "./keyValue.js";
 
-// Encodes each control outside `control_info` as the query its classic `set_*`
-// endpoint takes.
+// Encodes each control outside `DaikinState` as the query its classic `set_*`
+// endpoint takes, and reads each one back from the reply that reports it.
 
 const TERMINAL_SCOPE_CODES: Record<TerminalScope, string> = {
   self: "0",
@@ -20,8 +22,8 @@ const DEMAND_MODE_CODES: Record<DemandMode, string> = {
   auto: "2",
 };
 
-// `spmode_kind` on the wire; control_info's `adv` reports powerful as 2 and
-// econo as 12.
+// `spmode_kind` on the wire, which numbers the modes differently from the
+// `adv` that `parseClassicState` reads.
 const SPECIAL_MODE_KIND_CODES: Record<
   Exclude<SpecialMode, "streamer">,
   string
@@ -41,12 +43,27 @@ export function encodeClassicLed(on: boolean): Record<string, string> {
   return { led: flag(on) };
 }
 
+/** Reads the LED from a `basic_info` reply: `null` when it carries no `led`. */
+export function parseClassicLed(
+  fields: Record<string, string>,
+): boolean | null {
+  return parseFlag(fields.led);
+}
+
 export function encodeClassicHolidayMode(
   enabled: boolean,
 ): Record<string, string> {
   return { en_hol: flag(enabled) };
 }
 
+/** Reads holiday mode from a `basic_info` reply: `null` when it carries no
+ * `en_hol`. */
+export function parseClassicHolidayMode(
+  fields: Record<string, string>,
+): boolean | null {
+  return parseFlag(fields.en_hol);
+}
+
 export function encodeClassicDemandControl(
   demand: DemandControl,
 ): Record<string, string> {
@@ -67,6 +84,16 @@ export function encodeClassicSpecialMode(
     : { set_spmode: flag(enabled), spmode_kind: SPECIAL_MODE_KIND_CODES[mode] };
 }
 
+/** Reads out-of-home access from a `basic_info` reply: `null` when it carries
+ * no `method`. */
+export function parseClassicOutOfHomeAccess(
+  fields: Record<string, string>,
+): boolean | null {
+  return fields.method === undefined
+    ? null
+    : fields.method === REMOTE_METHOD_POLLING;
+}
+
 /** Turns `current`, the `get_remote_method` reply, and `enabled` into the
  * `set_remote_method` query. The endpoint takes the intervals back unchanged,
  * so the reply's `notice_ip_int` and `notice_sync_int` are copied in. */
@@ -117,6 +144,26 @@ export function encodeClassicGroup(group: DeviceGroup): Record<string, string> {
   return { grp_name: group.name, en_grp: flag(group.enabled) };
 }
 
+/** Reads the name, icon and group from a `basic_info` reply, leaving out each
+ * one the reply does not carry. The name and the group's name arrive
+ * form-encoded. */
+export function parseClassicMetadata(
+  fields: Record<string, string>,
+): DeviceMetadata {
+  return {
+    name:
+      fields.name === undefined ? undefined : decodeClassicText(fields.name),
+    icon: fields.icon,
+    group:
+      fields.en_grp === undefined
+        ? undefined
+        : {
+            name: decodeClassicText(fields.grp_name ?? ""),
+            enabled: fields.en_grp === "1",
+          },
+  };
+}
+
 export function encodeClassicTerminalKey(key: string): Record<string, string> {
   return { key };
 }
@@ -130,3 +177,7 @@ export function encodeClassicTerminalScope(
 function flag(on: boolean): string {
   return on ? "1" : "0";
 }
+
+function parseFlag(value: string | undefined): boolean | null {
+  return value === undefined ? null : value === "1";
+}

package/src/codecs/classic/keyValue.ts

@@ -17,6 +17,16 @@ export function parseClassicKeyValue(body: string): Record<string, string> {
   return result;
 }
 
+/** Decodes a form-encoded value, such as a name: `+` is a space. A value that
+ * is not valid percent-encoding is returned as the adapter sent it. */
+export function decodeClassicText(value: string): string {
+  try {
+    return decodeURIComponent(value.replaceAll("+", " "));
+  } catch {
+    return value;
+  }
+}
+
 export function isClassicOk(fields: Record<string, string>): boolean {
   return fields.ret === "OK";
 }

package/src/codecs/classic/state.ts

@@ -1,14 +1,16 @@
-import type {
-  DaikinControl,
-  DaikinSensors,
-  DaikinState,
-  FanSpeed,
-  HorizontalPosition,
-  HumiditySetting,
-  OperatingMode,
-  SwingMode,
-  TargetHumidity,
-  VerticalPosition,
+import {
+  type DaikinControl,
+  type DaikinSensors,
+  type DaikinState,
+  type FanSpeed,
+  type HorizontalPosition,
+  type HumiditySetting,
+  type OperatingMode,
+  SPECIAL_MODES,
+  type SpecialMode,
+  type SwingMode,
+  type TargetHumidity,
+  type VerticalPosition,
 } from "../../models/state.js";
 import { takesClassicDirection, takesClassicHumidity } from "./capabilities.js";
 
@@ -123,6 +125,13 @@ const HUMIDITY_SETTINGS_BY_CODE: Record<string, HumiditySetting> =
     ]),
   );
 
+// `adv` holds one code for each special mode that is on, separated by `/`.
+const SPECIAL_MODE_ADV_CODES: Record<SpecialMode, string> = {
+  powerful: "2",
+  econo: "12",
+  streamer: "13",
+};
+
 // Fan mode keeps no setpoint memory, and dehumidify runs the fan on auto only.
 const NO_SETPOINT = "--";
 const DEHUMIDIFY_FAN_SPEED = "A";
@@ -131,7 +140,8 @@ const NO_LOUVER = "-";
 
 /** Turns a `get_control_info` reply into a `DaikinState`. A `mode` or `f_rate`
  * outside the model reads as `auto`, an `f_dir` outside it as `off`, and an
- * `f_dir_ud` or `f_dir_lr` outside it as `null`. */
+ * `f_dir_ud` or `f_dir_lr` outside it as `null`. A code in `adv` outside
+ * `SpecialMode` is left out. */
 export function parseClassicState(fields: Record<string, string>): DaikinState {
   return {
     power: fields.pow === "1",
@@ -143,6 +153,7 @@ export function parseClassicState(fields: Record<string, string>): DaikinState {
     verticalPosition: VERTICAL_POSITIONS_BY_CODE[fields.f_dir_ud ?? ""] ?? null,
     horizontalPosition:
       HORIZONTAL_POSITIONS_BY_CODE[fields.f_dir_lr ?? ""] ?? null,
+    specialModes: parseSpecialModes(fields.adv),
   };
 }
 
@@ -269,6 +280,13 @@ export function applyClassicControl(
   return next;
 }
 
+function parseSpecialModes(adv: string | undefined): SpecialMode[] {
+  const codes = (adv ?? "").split("/");
+  return SPECIAL_MODES.filter((mode) =>
+    codes.includes(SPECIAL_MODE_ADV_CODES[mode]),
+  );
+}
+
 function parseTargetHumidity(shum: string | undefined): TargetHumidity | null {
   const setting = HUMIDITY_SETTINGS_BY_CODE[shum ?? ""];
   if (setting !== undefined) {