daikin-local-control 0.1.1

package/src/authentication.ts

@@ -0,0 +1,53 @@
+import {
+  encodeClassicLocalPassword,
+  encodeDsiotLocalPassword,
+} from "./codecs/credentials.js";
+
+// Authentication is orthogonal to the wire protocol, so it is injected rather
+// than subclassed. A strategy contributes both headers and query, because the
+// classic protocol carries its local password as a query parameter while
+// DSIOT carries it as a Basic header.
+//
+// An adapter without a local password (basic_info `lpw_flag=0`) takes no
+// strategy: the uuid header alone is accepted. `en_secure` is not
+// authentication here: it means the terminal uuid must be registered
+// (`registerTerminal`), plus HTTPS on a Marvell adapter, which is the
+// transport's scheme.
+
+/** `DaikinTransport.send` calls both methods on every request and adds what
+ * they return. */
+export interface DaikinAuthentication {
+  headers(): Record<string, string> | Promise<Record<string, string>>;
+  /** Replaces a request parameter of the same name. */
+  query(): Record<string, string> | Promise<Record<string, string>>;
+}
+
+/** Classic adapter that requires the local password: sent as
+ * `?lpw=<value>`. */
+export class ClassicLocalPasswordAuthentication
+  implements DaikinAuthentication
+{
+  constructor(private readonly localPassword: string) {}
+
+  headers(): Record<string, string> {
+    return {};
+  }
+
+  query(): Record<string, string> {
+    return encodeClassicLocalPassword(this.localPassword);
+  }
+}
+
+/** DSIOT adapter that requires the local password: sent as
+ * `Authorization: Basic <lpw>`. */
+export class DsiotLocalPasswordAuthentication implements DaikinAuthentication {
+  constructor(private readonly localPassword: string) {}
+
+  headers(): Record<string, string> {
+    return encodeDsiotLocalPassword(this.localPassword);
+  }
+
+  query(): Record<string, string> {
+    return {};
+  }
+}

package/src/clients/classic.ts

@@ -0,0 +1,251 @@
+import {
+  mergeClassicCapabilityFields,
+  parseClassicCapabilities,
+} from "../codecs/classic/capabilities.js";
+import {
+  applyClassicOutOfHomeAccess,
+  encodeClassicDemandControl,
+  encodeClassicEnergyPrice,
+  encodeClassicEnergyTarget,
+  encodeClassicGroup,
+  encodeClassicHolidayMode,
+  encodeClassicIcon,
+  encodeClassicLed,
+  encodeClassicName,
+  encodeClassicSpecialMode,
+  encodeClassicTerminalKey,
+  encodeClassicTerminalScope,
+} from "../codecs/classic/extendedControl.js";
+import {
+  assertClassicOk,
+  parseClassicKeyValue,
+} from "../codecs/classic/keyValue.js";
+import {
+  applyClassicControl,
+  parseClassicSensors,
+  parseClassicState,
+} from "../codecs/classic/state.js";
+import type { DaikinCapabilities } from "../models/capabilities.js";
+import type {
+  DemandControl,
+  DeviceMetadata,
+  SpecialMode,
+  TerminalScope,
+} from "../models/extendedControl.js";
+import type {
+  DaikinControl,
+  DaikinSensors,
+  DaikinState,
+} from "../models/state.js";
+import {
+  type DaikinRequestOptions,
+  type DaikinRetryOptions,
+  type DaikinTransport,
+  withRetry,
+} from "../transport.js";
+import type { DaikinClient } from "./client.js";
+
+// Classic CGI endpoints (BRP069-style). Reads and writes are both HTTP GET with
+// query parameters; the reply is `key=value,key=value`.
+const CLASSIC_ROUTES = {
+  basicInfo: "/common/basic_info",
+  getModelInfo: "/aircon/get_model_info",
+  getControlInfo: "/aircon/get_control_info",
+  setControlInfo: "/aircon/set_control_info",
+  getSensorInfo: "/aircon/get_sensor_info",
+  setSpecialMode: "/aircon/set_special_mode",
+  setDemandControl: "/aircon/set_demand_control",
+  setPrice: "/aircon/set_price",
+  setTarget: "/aircon/set_target",
+  setLed: "/common/set_led",
+  setHoliday: "/common/set_holiday",
+  setName: "/common/set_name",
+  setIcon: "/common/set_icon",
+  setGroup: "/common/set_group",
+  getRemoteMethod: "/common/get_remote_method",
+  setRemoteMethod: "/common/set_remote_method",
+  reboot: "/common/reboot",
+  registerTerminal: "/common/register_terminal",
+  unregisterTerminal: "/common/unregister_terminal",
+} as const;
+
+/** Classic CGI adapter (BRP069-style). Reads and writes are HTTP GET with query
+ * parameters; replies are `key=value,key=value`. */
+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;
+
+  /** `close` closes `transport`, so give each client a transport of its own. */
+  constructor(
+    private readonly transport: DaikinTransport,
+    private readonly retryOptions?: DaikinRetryOptions,
+  ) {}
+
+  close(): Promise<void> {
+    return this.transport.close();
+  }
+
+  async getCapabilities(): Promise<DaikinCapabilities> {
+    return parseClassicCapabilities(await this.readCapabilityFields());
+  }
+
+  async getState(): Promise<DaikinState> {
+    return parseClassicState(await this.command(CLASSIC_ROUTES.getControlInfo));
+  }
+
+  async setState(control: DaikinControl): Promise<void> {
+    const capabilityFields = await this.readCapabilityFields();
+    const current = await this.command(CLASSIC_ROUTES.getControlInfo);
+    await this.command(
+      CLASSIC_ROUTES.setControlInfo,
+      applyClassicControl(current, control, capabilityFields),
+    );
+  }
+
+  async getSensors(): Promise<DaikinSensors> {
+    return parseClassicSensors(
+      await this.command(CLASSIC_ROUTES.getSensorInfo),
+    );
+  }
+
+  // --- extended controls ---------------------------------------------------
+  // Each maps to its own endpoint (not control_info).
+
+  /** Adapter status LED on/off (`set_led`). */
+  async setLed(on: boolean): Promise<void> {
+    await this.command(CLASSIC_ROUTES.setLed, encodeClassicLed(on));
+  }
+
+  /** Holiday / away mode (`set_holiday`). */
+  async setHolidayMode(enabled: boolean): Promise<void> {
+    await this.command(
+      CLASSIC_ROUTES.setHoliday,
+      encodeClassicHolidayMode(enabled),
+    );
+  }
+
+  /** Demand control — cap the unit's power draw (`set_demand_control`). */
+  async setDemandControl(demand: DemandControl): Promise<void> {
+    await this.command(
+      CLASSIC_ROUTES.setDemandControl,
+      encodeClassicDemandControl(demand),
+    );
+  }
+
+  /** Powerful, econo or streamer (`set_special_mode`). */
+  async setSpecialMode(mode: SpecialMode, enabled: boolean): Promise<void> {
+    await this.command(
+      CLASSIC_ROUTES.setSpecialMode,
+      encodeClassicSpecialMode(mode, enabled),
+    );
+  }
+
+  /** Whether the unit can be operated from outside the home network
+   * (`set_remote_method`). */
+  async setOutOfHomeAccess(enabled: boolean): Promise<void> {
+    const current = await this.command(CLASSIC_ROUTES.getRemoteMethod);
+    await this.command(
+      CLASSIC_ROUTES.setRemoteMethod,
+      applyClassicOutOfHomeAccess(current, enabled),
+    );
+  }
+
+  /** Electricity price per kWh for the consumption estimates (`set_price`),
+   * to two decimal places. */
+  async setEnergyPrice(price: number): Promise<void> {
+    await this.command(
+      CLASSIC_ROUTES.setPrice,
+      encodeClassicEnergyPrice(price),
+    );
+  }
+
+  /** Energy target for the "target" feature (`set_target`). */
+  async setEnergyTarget(target: number): Promise<void> {
+    await this.command(
+      CLASSIC_ROUTES.setTarget,
+      encodeClassicEnergyTarget(target),
+    );
+  }
+
+  /** Name / icon / group metadata (`set_name` etc.). */
+  async setMetadata(metadata: DeviceMetadata): Promise<void> {
+    if (metadata.name !== undefined) {
+      await this.command(
+        CLASSIC_ROUTES.setName,
+        encodeClassicName(metadata.name),
+      );
+    }
+    if (metadata.icon !== undefined) {
+      await this.command(
+        CLASSIC_ROUTES.setIcon,
+        encodeClassicIcon(metadata.icon),
+      );
+    }
+    if (metadata.group !== undefined) {
+      await this.command(
+        CLASSIC_ROUTES.setGroup,
+        encodeClassicGroup(metadata.group),
+      );
+    }
+  }
+
+  /** Register this client's uuid with an adapter whose
+   * `requiresRegistration` is true, using the KEY printed on the adapter's
+   * label (`register_terminal`). Once per uuid; the adapter remembers it. */
+  async registerTerminal(key: string): Promise<void> {
+    await this.command(
+      CLASSIC_ROUTES.registerTerminal,
+      encodeClassicTerminalKey(key),
+    );
+  }
+
+  /** Unregister terminals (`unregister_terminal`): this uuid, every other
+   * uuid, or all of them. */
+  async unregisterTerminal(scope: TerminalScope = "self"): Promise<void> {
+    await this.command(
+      CLASSIC_ROUTES.unregisterTerminal,
+      encodeClassicTerminalScope(scope),
+    );
+  }
+
+  /** Reboot the adapter (`reboot`). */
+  async reboot(): Promise<void> {
+    await this.command(CLASSIC_ROUTES.reboot, undefined, { retry: false });
+  }
+
+  /** Calls any classic CGI endpoint with query parameters and returns the reply's
+   * `key=value` fields. It reaches the controls without a typed method:
+   * timers, schedules, programs, network, credentials and firmware. It throws
+   * a `DaikinError` when the reply's `ret` is not `OK`. */
+  async command(
+    path: string,
+    parameters?: Record<string, string>,
+    { retry = true }: DaikinRequestOptions = {},
+  ): Promise<Record<string, string>> {
+    const send = () =>
+      this.transport.send({
+        method: "GET",
+        path,
+        ...(parameters ? { query: parameters } : {}),
+      });
+    const fields = parseClassicKeyValue(
+      await (retry ? withRetry(send, this.retryOptions) : send()),
+    );
+    assertClassicOk(fields);
+    return fields;
+  }
+
+  private readCapabilityFields(): Promise<Record<string, string>> {
+    this.capabilityFields ??= (async () =>
+      mergeClassicCapabilityFields(
+        await this.command(CLASSIC_ROUTES.basicInfo),
+        await this.command(CLASSIC_ROUTES.getModelInfo),
+      ))();
+    // A failed read is not cached, so the next call tries again.
+    this.capabilityFields.catch(() => {
+      this.capabilityFields = undefined;
+    });
+    return this.capabilityFields;
+  }
+}

package/src/clients/client.ts

@@ -0,0 +1,29 @@
+import type { DaikinCapabilities } from "../models/capabilities.js";
+import type {
+  DaikinControl,
+  DaikinSensors,
+  DaikinState,
+} from "../models/state.js";
+
+/** The controls every adapter offers, whatever its wire protocol or
+ * authentication. `createDaikinClient` picks the implementation, so a caller
+ * needs the concrete class only for what one protocol adds, such as
+ * `ClassicDaikinClient.registerTerminal`. Every method rejects with a
+ * `DaikinError` when its request fails. */
+export interface DaikinClient {
+  /** The unit's supported features. */
+  getCapabilities(): Promise<DaikinCapabilities>;
+
+  /** Current controllable state. */
+  getState(): Promise<DaikinState>;
+
+  /** Change part of the state. The client reads the current state, overlays the
+   * control, and writes the whole thing back. */
+  setState(control: DaikinControl): Promise<void>;
+
+  /** Read-only temperature / humidity readings. */
+  getSensors(): Promise<DaikinSensors>;
+
+  /** Close the connection to the adapter. */
+  close(): Promise<void>;
+}

package/src/clients/dsiot.ts

@@ -0,0 +1,116 @@
+import { parseDsiotCapabilities } from "../codecs/dsiot/capabilities.js";
+import {
+  buildDsiotMultireqGet,
+  buildDsiotMultireqUpdate,
+  DSIOT_TARGETS,
+  type DsiotUpdate,
+  parseDsiotMultireqReply,
+} from "../codecs/dsiot/multireq.js";
+import {
+  applyDsiotControl,
+  parseDsiotSensors,
+  parseDsiotState,
+} from "../codecs/dsiot/state.js";
+import type { DaikinCapabilities } from "../models/capabilities.js";
+import type {
+  DaikinControl,
+  DaikinSensors,
+  DaikinState,
+} from "../models/state.js";
+import {
+  type DaikinRequestOptions,
+  type DaikinRetryOptions,
+  type DaikinTransport,
+  withRetry,
+} from "../transport.js";
+import type { DaikinClient } from "./client.js";
+
+// DSIOT endpoints (BRP084-style). Climate state is a POST (read) or PUT (write)
+// of a JSON property tree to `multireq`.
+const DSIOT_ROUTES = {
+  multireq: "/dsiot/multireq",
+  reboot: "/config/system/reboot",
+} as const;
+
+/** 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. */
+  constructor(
+    private readonly transport: DaikinTransport,
+    private readonly retryOptions?: DaikinRetryOptions,
+  ) {}
+
+  close(): Promise<void> {
+    return this.transport.close();
+  }
+
+  async getCapabilities(): Promise<DaikinCapabilities> {
+    return parseDsiotCapabilities(
+      await this.multireqGet([
+        DSIOT_TARGETS.adapterInfo,
+        DSIOT_TARGETS.indoorStatus,
+      ]),
+    );
+  }
+
+  async getState(): Promise<DaikinState> {
+    return parseDsiotState(
+      await this.multireqGet([DSIOT_TARGETS.indoorStatus]),
+    );
+  }
+
+  async setState(control: DaikinControl): Promise<void> {
+    const values = await this.multireqGet([DSIOT_TARGETS.indoorStatus]);
+    await this.multireqUpdate(applyDsiotControl(values, control));
+  }
+
+  async getSensors(): Promise<DaikinSensors> {
+    return parseDsiotSensors(
+      await this.multireqGet([
+        DSIOT_TARGETS.indoorStatus,
+        DSIOT_TARGETS.outdoorStatus,
+      ]),
+    );
+  }
+
+  // --- extended controls ---------------------------------------------------
+
+  /** Reboot the adapter (`/config/system/reboot`). */
+  async reboot(): Promise<void> {
+    await this.transport.send({
+      method: "POST",
+      path: DSIOT_ROUTES.reboot,
+    });
+  }
+
+  /** Raw multireq read of whole resources (`DSIOT_TARGETS` values or any `to`),
+   * flattened to dotted path -> value. */
+  async multireqGet(
+    targets: string[],
+    options?: DaikinRequestOptions,
+  ): Promise<Record<string, string>> {
+    return this.multireq("POST", buildDsiotMultireqGet(targets), options);
+  }
+
+  /** Raw multireq write: update any leaves by dotted path, merged into one tree
+   * on the indoor edge. Returns the reply, flattened as `multireqGet` does. */
+  async multireqUpdate(
+    updates: DsiotUpdate[],
+    options?: DaikinRequestOptions,
+  ): Promise<Record<string, string>> {
+    return this.multireq("PUT", buildDsiotMultireqUpdate(updates), options);
+  }
+
+  private async multireq(
+    method: "POST" | "PUT",
+    jsonBody: unknown,
+    { retry = true }: DaikinRequestOptions = {},
+  ): Promise<Record<string, string>> {
+    const send = () =>
+      this.transport.send({ method, path: DSIOT_ROUTES.multireq, jsonBody });
+    return parseDsiotMultireqReply(
+      await (retry ? withRetry(send, this.retryOptions) : send()),
+    );
+  }
+}