daikin-local-control 0.2.0 → 0.3.0

package/src/codecs/device.ts

@@ -1,4 +1,5 @@
-import type { DaikinDevice } from "../models/device.js";
+import type { DaikinDevice, DaikinDeviceInfo } from "../models/device.js";
+import { decodeClassicText } from "./classic/keyValue.js";
 
 const DSIOT_TYPE = "GPF";
 const MARVELL_ADP_KIND = "3";
@@ -15,7 +16,10 @@ export function parseDevice(
   return {
     host: basicInfo.api_port ? `${host}:${basicInfo.api_port}` : host,
     protocol,
-    name: decodeName(basicInfo.name),
+    name:
+      basicInfo.name === undefined
+        ? undefined
+        : decodeClassicText(basicInfo.name),
     // Only classic adapters register terminals.
     requiresRegistration: secure && protocol === "classic",
     // Only a Marvell adapter (adp_kind=3) in secure mode speaks HTTPS; every
@@ -25,17 +29,38 @@ export function parseDevice(
       protocol === "classic" &&
       basicInfo.adp_kind === MARVELL_ADP_KIND,
     requiresLocalPassword: basicInfo.lpw_flag === "1",
+    ...parseDeviceInfo(basicInfo),
   };
 }
 
-// The name is form-encoded: `+` is a space.
-function decodeName(value: string | undefined): string | undefined {
-  if (value === undefined) {
+/** Reads what a `basic_info` reply says to identify the adapter. */
+export function parseDeviceInfo(
+  basicInfo: Record<string, string>,
+): DaikinDeviceInfo {
+  return {
+    macAddress: decodeMacAddress(basicInfo.mac),
+    firmwareVersion: decodeFirmwareVersion(basicInfo.ver),
+  };
+}
+
+/** The adapter sends a MAC address without separators. It keeps the adapter's
+ * letter case. */
+export function decodeMacAddress(
+  value: string | undefined,
+): string | undefined {
+  return value ? value.replace(/..(?=..)/g, "$&:") : undefined;
+}
+
+/** The adapter sends a version as three numbers joined by underscores, with a
+ * fourth part, `pre`, on a pre-release. This drops any other fourth part, and
+ * decodes a value that is not three numbers to `undefined`. */
+export function decodeFirmwareVersion(
+  value: string | undefined,
+): string | undefined {
+  const parts = /^(\d+)_(\d+)_(\d+)(?:_([^_]*))?$/.exec(value ?? "");
+  if (parts === null) {
     return undefined;
   }
-  try {
-    return decodeURIComponent(value.replaceAll("+", " "));
-  } catch {
-    return value;
-  }
+  const version = parts.slice(1, 4).map(Number).join(".");
+  return parts[4] === "pre" ? `${version}.pre` : version;
 }

package/src/codecs/dsiot/capabilities.ts

@@ -11,6 +11,7 @@ import {
   HUMIDITY_SETTINGS,
   OPERATING_MODES,
   type OperatingMode,
+  SPECIAL_MODES,
   SWING_MODES,
   type SwingMode,
   VERTICAL_POSITIONS,
@@ -20,6 +21,7 @@ import {
   DSIOT_HORIZONTAL_POSITION_VALUES,
   DSIOT_MODE_PATHS,
   DSIOT_PATHS,
+  DSIOT_SPECIAL_MODE_PATHS,
   DSIOT_VERTICAL_POSITION_VALUES,
   type DsiotSetpoint,
   decodeDsiotLittleEndian,
@@ -35,6 +37,9 @@ const ADAPTER_PATHS = {
   scheduleTimer: "adp_i.func.en_scdltmr",
 } as const;
 
+// The `pt` of a special mode's leaf on a unit that takes the mode.
+const SPECIAL_MODE_OFFERED_TYPE = "2";
+
 const COOLING_ONLY_MODEL_TYPE = "01";
 const COOLING_ONLY_MODES: readonly OperatingMode[] = [
   "dehumidify",
@@ -48,8 +53,10 @@ const FIXED_POSITIONS: readonly string[] = FIXED_LOUVER_POSITIONS;
 
 type LouverAxis = "vertical" | "horizontal";
 
-/** Turns the flattened `adp_i` and indoor `dgc_status` trees (with `md`) into
- * `DaikinCapabilities`. Setpoints count half degrees. */
+/** Turns the flattened `adp_i` tree and the indoor and outdoor `dgc_status`
+ * trees (with `pt` and `md`) into `DaikinCapabilities`. Setpoints count half
+ * degrees. Without the outdoor tree, `specialModes` lists no `powerful`. It
+ * lists econo in every mode but fan: see UNSUPPORTED.md. */
 export function parseDsiotCapabilities(
   values: Record<string, string>,
 ): DaikinCapabilities {
@@ -66,6 +73,17 @@ export function parseDsiotCapabilities(
       ? [...HUMIDITY_SETTINGS]
       : [];
   };
+  const takenSpecialModes = SPECIAL_MODES.filter(
+    (specialMode) =>
+      values[`${DSIOT_SPECIAL_MODE_PATHS[specialMode]}.pt`] ===
+      SPECIAL_MODE_OFFERED_TYPE,
+  );
+  const specialModes = (mode: OperatingMode) =>
+    modes.includes(mode)
+      ? takenSpecialModes.filter(
+          (specialMode) => mode !== "fan" || specialMode !== "econo",
+        )
+      : [];
   const vertical = hasLouver(values, "vertical");
   const horizontal = hasLouver(values, "horizontal");
   const energyMonitoring =
@@ -105,6 +123,13 @@ export function parseDsiotCapabilities(
       heat: humiditySettings("heat"),
       fan: [],
     },
+    specialModes: {
+      auto: specialModes("auto"),
+      dehumidify: specialModes("dehumidify"),
+      cool: specialModes("cool"),
+      heat: specialModes("heat"),
+      fan: specialModes("fan"),
+    },
     // Which leaf reports the special air outlet is not known: see
     // UNSUPPORTED.md.
     specialOutlet: false,

package/src/codecs/dsiot/device.ts

@@ -0,0 +1,20 @@
+import type { DaikinDeviceInfo } from "../../models/device.js";
+import { decodeFirmwareVersion, decodeMacAddress } from "../device.js";
+
+const ADAPTER_PATHS = {
+  macAddress: "adp_i.mac",
+  firmwareVersion: "adp_i.ver",
+} as const;
+
+/** Reads what the flattened `adp_i` tree says to identify the adapter. Both
+ * leaves hold the value a classic adapter sends in `basic_info`. */
+export function parseDsiotDeviceInfo(
+  values: Record<string, string>,
+): DaikinDeviceInfo {
+  return {
+    macAddress: decodeMacAddress(values[ADAPTER_PATHS.macAddress]),
+    firmwareVersion: decodeFirmwareVersion(
+      values[ADAPTER_PATHS.firmwareVersion],
+    ),
+  };
+}

package/src/codecs/dsiot/multireq.ts

@@ -20,11 +20,12 @@ export const DSIOT_EDGES = {
 const EDGE_ROOT = "/dsiot/edge";
 
 /** What a read fetches, as the `to` of a request: whole trees, never single
- * leaves. */
+ * leaves. The status trees come with `pt`, which `parseDsiotCapabilities`
+ * reads. */
 export const DSIOT_TARGETS = {
   adapterInfo: `${EDGE_ROOT}.adp_i?filter=pv`,
-  indoorStatus: `${EDGE_ROOT}/${DSIOT_EDGES.indoor}.dgc_status?filter=pv,md`,
-  outdoorStatus: `${EDGE_ROOT}/${DSIOT_EDGES.outdoor}.dgc_status?filter=pv,md`,
+  indoorStatus: `${EDGE_ROOT}/${DSIOT_EDGES.indoor}.dgc_status?filter=pv,pt,md`,
+  outdoorStatus: `${EDGE_ROOT}/${DSIOT_EDGES.outdoor}.dgc_status?filter=pv,pt,md`,
 } as const;
 
 interface PropertyNode {
@@ -92,7 +93,8 @@ function childNamed(siblings: PropertyNode[], name: string): PropertyNode {
 }
 
 /** Flattens a `/dsiot/multireq` reply into dotted paths -> `pv`, plus
- * `<path>.md.mi` / `.md.mx` / `.md.st` where metadata came back.
+ * `<path>.pt` where a leaf's type came back and `<path>.md.mi` / `.md.mx` /
+ * `.md.st` where metadata did.
  *
  * Each of its `responses` carries its own `rsc`; any not starting with 200 is
  * the adapter refusing, and throws a `DaikinError`: status 401 for `rsc` 401
@@ -149,6 +151,9 @@ function flatten(
   if (node.pv !== undefined) {
     values[path] = stringify(node.pv);
   }
+  if (node.pt !== undefined) {
+    values[`${path}.pt`] = stringify(node.pt);
+  }
   for (const key of ["mi", "mx", "st"] as const) {
     const metadata = node.md?.[key];
     if (metadata !== undefined && metadata !== null) {

package/src/codecs/dsiot/state.ts

@@ -8,6 +8,8 @@ import {
   type HorizontalPosition,
   type HumiditySetting,
   type OperatingMode,
+  SPECIAL_MODES,
+  type SpecialMode,
   type SwingMode,
   type TargetHumidity,
   VERTICAL_POSITIONS,
@@ -30,6 +32,15 @@ export const DSIOT_PATHS = {
   energyMonitoring: "dgc_status.e_1002.e_A011.p_01",
 } as const;
 
+/** Each leaf holds `01` while its mode is on. Powerful is on the outdoor
+ * edge. */
+export const DSIOT_SPECIAL_MODE_PATHS: Record<SpecialMode, string> = {
+  powerful: "dgc_status.e_1003.e_3002.p_44",
+  econo: "dgc_status.e_1002.e_3003.p_24",
+  streamer: "dgc_status.e_1002.e_3003.p_20",
+};
+const SPECIAL_MODE_ON = "01";
+
 export interface DsiotSetpoint {
   path: string;
   /** Auto and dehumidify are a signed byte; cool and heat are little-endian. */
@@ -476,7 +487,8 @@ const POWER_TRANSITIONS = {
 /** Turns the flattened indoor `dgc_status` tree, read with `md`, into a
  * `DaikinState`. Every value is per mode: the setpoint, humidity, fan speed and
  * louvers each have a leaf for each mode, and the state reads the current
- * mode's. */
+ * mode's. Powerful is read from the outdoor tree, and reads as off without
+ * it. */
 export function parseDsiotState(values: Record<string, string>): DaikinState {
   const mode = decodeDsiotMode(values[DSIOT_PATHS.mode]) ?? "auto";
   const paths = DSIOT_MODE_PATHS[mode];
@@ -491,6 +503,9 @@ export function parseDsiotState(values: Record<string, string>): DaikinState {
     swingMode: decodeSwing(values[paths.vertical], values[paths.horizontal]),
     verticalPosition: parseVerticalPosition(values, paths.vertical),
     horizontalPosition: parseHorizontalPosition(values[paths.horizontal]),
+    specialModes: SPECIAL_MODES.filter(
+      (mode) => values[DSIOT_SPECIAL_MODE_PATHS[mode]] === SPECIAL_MODE_ON,
+    ),
   };
 }
 

package/src/factory.ts

@@ -26,6 +26,13 @@ export interface CreateDaikinClientOptions {
    * waits of 0, 50, 100, 200 and 400 milliseconds: see
    * `DaikinRetryOptions.delaysInMs`. */
   retry?: DaikinRetryOptions;
+  /** How old, in milliseconds, a reply to `getState` or `getStateAndSensors`
+   * may be for `setState` to build its write from it instead of reading the
+   * unit first. Defaults to 0: `setState` always reads first. It changes no
+   * read: `getState` asks the unit every time. The write undoes a change made
+   * on the remote control since that reply: see
+   * DESIGN.md#the-read-before-a-write. */
+  maxStateAgeForSetStateInMs?: number;
   /** HTTPS adapters only. Without a CA the adapter's certificate isn't verified. */
   tls?: DaikinTlsOptions;
 }
@@ -49,8 +56,16 @@ export function createDaikinClient(
   });
 
   return device.protocol === "dsiot"
-    ? new DsiotDaikinClient(transport, options.retry)
-    : new ClassicDaikinClient(transport, options.retry);
+    ? new DsiotDaikinClient(
+        transport,
+        options.retry,
+        options.maxStateAgeForSetStateInMs,
+      )
+    : new ClassicDaikinClient(
+        transport,
+        options.retry,
+        options.maxStateAgeForSetStateInMs,
+      );
 }
 
 function localPasswordAuthentication(

package/src/index.ts

@@ -9,6 +9,7 @@ export * from "./codecs/classic/state.js";
 export * from "./codecs/credentials.js";
 export * from "./codecs/device.js";
 export * from "./codecs/dsiot/capabilities.js";
+export * from "./codecs/dsiot/device.js";
 export * from "./codecs/dsiot/multireq.js";
 export * from "./codecs/dsiot/state.js";
 export * from "./discovery.js";

package/src/models/capabilities.ts

@@ -2,6 +2,7 @@ import type {
   FanSpeed,
   HorizontalPosition,
   OperatingMode,
+  SpecialMode,
   SwingMode,
   TargetHumidity,
   VerticalPosition,
@@ -41,6 +42,10 @@ export interface DaikinCapabilities {
   /** Humidity settings per mode; empty where the mode has none or the unit does
    * not offer it. A percentage is listed for no unit: see UNSUPPORTED.md. */
   targetHumidities: Readonly<Record<OperatingMode, readonly TargetHumidity[]>>;
+  /** Special modes per mode; empty where the unit takes none or does not offer
+   * the mode. `getCapabilities` lists econo in every mode but fan: see
+   * UNSUPPORTED.md. */
+  specialModes: Readonly<Record<OperatingMode, readonly SpecialMode[]>>;
   /** Whether the unit has the special air outlet, which heat can swing
    * through. That swing is not modelled: see UNSUPPORTED.md. */
   specialOutlet: boolean;

package/src/models/device.ts

@@ -5,11 +5,23 @@ export const DAIKIN_PROTOCOLS = ["classic", "dsiot"] as const;
  * a CGI adapter such as the BRP069 or BRP072, `dsiot` for a BRP084. */
 export type DaikinProtocol = (typeof DAIKIN_PROTOCOLS)[number];
 
+/** What an adapter reports to identify itself. `discoverDevices` fills it into
+ * each `DaikinDevice`, and `DaikinClient.getDeviceInfo` reads it for a device
+ * written by hand. */
+export interface DaikinDeviceInfo {
+  /** In pairs joined by colons, in the letter case the adapter sends, such as
+   * `A4:08:EA:CC:91:D4`. Left out when the adapter reports none. */
+  macAddress?: string;
+  /** The adapter's firmware, such as `1.2.51`, or `1.2.51.pre` for a
+   * pre-release. Left out when the adapter reports none. */
+  firmwareVersion?: string;
+}
+
 /** An adapter on the LAN, as `discoverDevices` finds it or as a caller writes
  * it by hand, carrying what `createDaikinClient` needs to reach it. A flag left
  * out means `false`, so a device written by hand needs only `host` and
  * `protocol`. */
-export interface DaikinDevice {
+export interface DaikinDevice extends DaikinDeviceInfo {
   /** Address, with `:port` when the adapter announces one. */
   host: string;
   protocol: DaikinProtocol;

package/src/models/extendedControl.ts

@@ -22,17 +22,14 @@ export interface DemandControl {
   mode: DemandMode;
 }
 
-export const SPECIAL_MODES = ["powerful", "econo", "streamer"] as const;
-
-export type SpecialMode = (typeof SPECIAL_MODES)[number];
-
 export interface DeviceGroup {
   name: string;
   /** Whether the unit is in the group. */
   enabled: boolean;
 }
 
-/** A field left out is not written. */
+/** `setMetadata` writes no field that is left out, and `getMetadata` leaves
+ * out a field the adapter does not report. */
 export interface DeviceMetadata {
   name?: string;
   /** The adapter's own code for the icon: see UNSUPPORTED.md. */

package/src/models/state.ts

@@ -78,6 +78,10 @@ export type HumiditySetting = (typeof HUMIDITY_SETTINGS)[number];
  * `DaikinCapabilities.targetHumidities` lists which of them a unit takes. */
 export type TargetHumidity = HumiditySetting | { percent: number };
 
+export const SPECIAL_MODES = ["powerful", "econo", "streamer"] as const;
+
+export type SpecialMode = (typeof SPECIAL_MODES)[number];
+
 export interface DaikinState {
   power: boolean;
   mode: OperatingMode;
@@ -93,14 +97,19 @@ export interface DaikinState {
   /** On a 3D unit. `null` where the unit reports none, or one outside
    * `HorizontalPosition`. */
   horizontalPosition: HorizontalPosition | null;
+  /** The special modes that are on, in the order of `SPECIAL_MODES`; empty
+   * when none is. `setState` does not take it: see `DaikinControl`. */
+  specialModes: SpecialMode[];
 }
 
 /** A partial `DaikinState`, as `DaikinClient.setState` takes it: set only the
- * fields to change. The client reads the current state, overlays the control,
- * and writes the whole state back. It drops a field the unit does not take in
+ * fields to change. The client overlays the control on the state the unit
+ * holds, and writes the whole state back. It drops a field the unit does not take in
  * the target mode, such as a louver position outside
- * `DaikinCapabilities.verticalPositions`. */
-export type DaikinControl = Partial<DaikinState>;
+ * `DaikinCapabilities.verticalPositions`. It takes no `specialModes`: a
+ * classic adapter is set one with `ClassicDaikinClient.setSpecialMode`, and
+ * UNSUPPORTED.md says what is not known about the rest. */
+export type DaikinControl = Partial<Omit<DaikinState, "specialModes">>;
 
 /** A reading is `null` when the unit does not report it. */
 export interface DaikinSensors {
@@ -108,3 +117,8 @@ export interface DaikinSensors {
   outdoorTemperatureInC: number | null;
   indoorHumidityInPercent: number | null;
 }
+
+export interface DaikinStateAndSensors {
+  state: DaikinState;
+  sensors: DaikinSensors;
+}