daikin-local-control 0.1.1

package/src/discovery.ts

@@ -0,0 +1,85 @@
+import { createSocket } from "node:dgram";
+import {
+  isClassicOk,
+  parseClassicKeyValue,
+} from "./codecs/classic/keyValue.js";
+import { parseDevice } from "./codecs/device.js";
+import type { DaikinDevice } from "./models/device.js";
+
+// The UDP discovery probe: broadcast this to :30050, listen for `basic_info`
+// replies.
+const DISCOVERY_PROBE = "DAIKIN_UDP/common/basic_info";
+const DISCOVERY_SEND_PORT = 30000;
+const DISCOVERY_LISTEN_PORT = 30050;
+
+const DEFAULT_DISCOVERY_TIMEOUT_IN_MS = 3_000;
+const BROADCAST_ADDRESS = "255.255.255.255";
+// UDP drops packets, so the probe goes out 10 times, 200 ms apart.
+const PROBE_COUNT = 10;
+const PROBE_INTERVAL_IN_MS = 200;
+
+export interface DiscoverDevicesOptions {
+  /** How long to listen for replies, in milliseconds. Defaults to 3000. */
+  timeoutInMs?: number;
+}
+
+/** Finds the adapters on the LAN: broadcasts `DAIKIN_UDP/common/basic_info` to
+ * UDP port 30050 and collects the `basic_info` replies, which carry the same
+ * `key=value` payload as the HTTP `/common/basic_info`. Classic and DSIOT
+ * adapters both answer, and `parseDevice` picks the protocol from the reply.
+ * Anything on the LAN can send to the port it listens on, so it ignores a
+ * datagram whose `ret` is not `OK`.
+ *
+ * It resolves once `timeoutInMs` has passed, never earlier, with one device
+ * per replying address. It binds UDP port 30000, and rejects with the socket's
+ * error when the socket fails. */
+export async function discoverDevices(
+  options: DiscoverDevicesOptions = {},
+): Promise<DaikinDevice[]> {
+  const socket = createSocket({ type: "udp4", reuseAddr: true });
+  const devices = new Map<string, DaikinDevice>();
+
+  return new Promise((resolve, reject) => {
+    let probesSent = 0;
+    let probeTimer: NodeJS.Timeout | undefined;
+
+    const listenTimer = setTimeout(() => {
+      clearInterval(probeTimer);
+      socket.close();
+      resolve([...devices.values()]);
+    }, options.timeoutInMs ?? DEFAULT_DISCOVERY_TIMEOUT_IN_MS);
+
+    socket.on("error", (error) => {
+      clearInterval(probeTimer);
+      // A socket throws when it is closed twice, so the timer must not fire.
+      clearTimeout(listenTimer);
+      socket.close();
+      reject(error);
+    });
+
+    socket.on("message", (message, remote) => {
+      if (devices.has(remote.address)) {
+        return;
+      }
+      const fields = parseClassicKeyValue(message.toString("utf8"));
+      if (!isClassicOk(fields)) {
+        return;
+      }
+      devices.set(remote.address, parseDevice(remote.address, fields));
+    });
+
+    socket.bind(DISCOVERY_SEND_PORT, () => {
+      socket.setBroadcast(true);
+      const probe = Buffer.from(DISCOVERY_PROBE, "utf8");
+      const sendProbe = () => {
+        socket.send(probe, DISCOVERY_LISTEN_PORT, BROADCAST_ADDRESS);
+        probesSent += 1;
+        if (probesSent >= PROBE_COUNT) {
+          clearInterval(probeTimer);
+        }
+      };
+      sendProbe();
+      probeTimer = setInterval(sendProbe, PROBE_INTERVAL_IN_MS);
+    });
+  });
+}

package/src/error.ts

@@ -0,0 +1,20 @@
+export class DaikinError extends Error {
+  constructor(
+    message: string,
+    /** The adapter's own HTTP status, or the status this package gives a
+     * failure that has none: the README's "Errors and retries" lists them. */
+    readonly httpStatusCode: number,
+  ) {
+    super(message);
+    this.name = "DaikinError";
+  }
+}
+
+/** The adapter refused or dropped the connection before answering. The only
+ * failure `withRetry` repeats: see DESIGN.md#retries. */
+export class DaikinConnectionError extends DaikinError {
+  constructor(message: string) {
+    super(message, 503);
+    this.name = "DaikinConnectionError";
+  }
+}

package/src/factory.ts

@@ -0,0 +1,66 @@
+import {
+  ClassicLocalPasswordAuthentication,
+  type DaikinAuthentication,
+  DsiotLocalPasswordAuthentication,
+} from "./authentication.js";
+import { ClassicDaikinClient } from "./clients/classic.js";
+import type { DaikinClient } from "./clients/client.js";
+import { DsiotDaikinClient } from "./clients/dsiot.js";
+import type { DaikinDevice } from "./models/device.js";
+import {
+  type DaikinRetryOptions,
+  type DaikinTlsOptions,
+  DaikinTransport,
+} from "./transport.js";
+
+export interface CreateDaikinClientOptions {
+  /** The terminal uuid, sent as `X-Daikin-uuid`. Generate one and reuse it:
+   * an adapter that requires registration remembers it. */
+  terminalUuid: string;
+  /** The child lock code, for a device whose `requiresLocalPassword` is true. */
+  localPassword?: string;
+  /** How long, in milliseconds, a request waits for the adapter. Defaults to
+   * 10000: see `DaikinTransportOptions.timeoutInMs`. */
+  timeoutInMs?: number;
+  /** The waits between retries of a refused or dropped connection. Defaults to
+   * waits of 0, 50, 100, 200 and 400 milliseconds: see
+   * `DaikinRetryOptions.delaysInMs`. */
+  retry?: DaikinRetryOptions;
+  /** HTTPS adapters only. Without a CA the adapter's certificate isn't verified. */
+  tls?: DaikinTlsOptions;
+}
+
+/** Builds the client for a device: a `DsiotDaikinClient` when
+ * `device.protocol` is `dsiot`, a `ClassicDaikinClient` otherwise. The client
+ * sends over HTTPS when `device.usesHttps` is set, and sends the local
+ * password when `options.localPassword` is given. Call `close` on the client
+ * when done with the unit. */
+export function createDaikinClient(
+  device: DaikinDevice,
+  options: CreateDaikinClientOptions,
+): DaikinClient {
+  const transport = new DaikinTransport({
+    host: device.host,
+    usesHttps: device.usesHttps,
+    terminalUuid: options.terminalUuid,
+    authentication: localPasswordAuthentication(device, options.localPassword),
+    timeoutInMs: options.timeoutInMs,
+    tls: options.tls,
+  });
+
+  return device.protocol === "dsiot"
+    ? new DsiotDaikinClient(transport, options.retry)
+    : new ClassicDaikinClient(transport, options.retry);
+}
+
+function localPasswordAuthentication(
+  device: DaikinDevice,
+  localPassword: string | undefined,
+): DaikinAuthentication | undefined {
+  if (localPassword === undefined) {
+    return undefined;
+  }
+  return device.protocol === "dsiot"
+    ? new DsiotLocalPasswordAuthentication(localPassword)
+    : new ClassicLocalPasswordAuthentication(localPassword);
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export type { DaikinAuthentication } from "./authentication.js";
+export * from "./clients/classic.js";
+export * from "./clients/client.js";
+export * from "./clients/dsiot.js";
+export * from "./codecs/classic/capabilities.js";
+export * from "./codecs/classic/extendedControl.js";
+export * from "./codecs/classic/keyValue.js";
+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/multireq.js";
+export * from "./codecs/dsiot/state.js";
+export * from "./discovery.js";
+export * from "./error.js";
+export * from "./factory.js";
+export * from "./models/capabilities.js";
+export * from "./models/device.js";
+export * from "./models/extendedControl.js";
+export * from "./models/state.js";
+export * from "./transport.js";

package/src/models/capabilities.ts

@@ -0,0 +1,52 @@
+import type {
+  FanSpeed,
+  HorizontalPosition,
+  OperatingMode,
+  SwingMode,
+  TargetHumidity,
+  VerticalPosition,
+} from "./state.js";
+
+/** In °C. */
+export interface TemperatureRange {
+  min: number;
+  max: number;
+  step: number;
+}
+
+/** What a specific unit accepts. Each control field is named for the
+ * `DaikinState` field it limits and lists values in that field's own
+ * vocabulary, so a caller can offer `capabilities.fanSpeeds` and send any of
+ * them back as `fanSpeed`. */
+export interface DaikinCapabilities {
+  /** Operating modes the unit offers. */
+  modes: readonly OperatingMode[];
+  /** Fan speeds the unit accepts; empty when the fan is not controllable.
+   * Dehumidify runs the fan on `auto` only, and so does cool on a DSIOT
+   * adapter while a humidity setting is on. */
+  fanSpeeds: readonly FanSpeed[];
+  /** Swing settings the unit accepts; empty when airflow is not controllable. */
+  swingModes: readonly SwingMode[];
+  /** Vertical louver positions the unit accepts; empty unless it is a 3D
+   * unit. */
+  verticalPositions: readonly VerticalPosition[];
+  /** Horizontal louver positions the unit accepts; empty unless it is a 3D
+   * unit. */
+  horizontalPositions: readonly HorizontalPosition[];
+  /** Setpoint range per mode; `null` where the mode has no setpoint or the unit
+   * does not offer the mode. */
+  targetTemperatureInC: Readonly<
+    Record<OperatingMode, TemperatureRange | null>
+  >;
+  /** 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. */
+  targetHumidity: Readonly<Record<OperatingMode, readonly TargetHumidity[]>>;
+  /** Whether the unit has the special air outlet, which heat can swing
+   * through. That swing is not modelled: see UNSUPPORTED.md. */
+  specialOutlet: boolean;
+  energyMonitoring: boolean;
+  demandControl: boolean;
+  scheduleTimer: boolean;
+  /** The adapter's own code for the unit's model: see UNSUPPORTED.md. */
+  model?: string;
+}

package/src/models/device.ts

@@ -0,0 +1,25 @@
+export const DAIKIN_PROTOCOLS = ["classic", "dsiot"] as const;
+
+/** The wire protocol an adapter speaks, and the only difference between
+ * adapters that takes a separate `DaikinClient` implementation: `classic` for
+ * a CGI adapter such as the BRP069 or BRP072, `dsiot` for a BRP084. */
+export type DaikinProtocol = (typeof DAIKIN_PROTOCOLS)[number];
+
+/** 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 {
+  /** Address, with `:port` when the adapter announces one. */
+  host: string;
+  protocol: DaikinProtocol;
+  name?: string;
+  /** The adapter answers a terminal uuid only once it is registered with the
+   * KEY on the adapter's label (`registerTerminal`). Classic only. */
+  requiresRegistration?: boolean;
+  /** The adapter speaks HTTPS. An adapter can require registration and still
+   * speak plain HTTP. */
+  usesHttps?: boolean;
+  /** The adapter requires the local password: the child lock code. */
+  requiresLocalPassword?: boolean;
+}

package/src/models/extendedControl.ts

@@ -0,0 +1,41 @@
+// Inputs to the controls outside `DaikinState`, which only a classic adapter
+// takes.
+
+export const TERMINAL_SCOPES = ["self", "others", "all"] as const;
+
+/** Which registered terminals to unregister: this uuid, every other uuid, or
+ * all of them. */
+export type TerminalScope = (typeof TERMINAL_SCOPES)[number];
+
+/** The adapter's third mode, schedule, is not offered: see UNSUPPORTED.md. */
+export const DEMAND_MODES = ["manual", "auto"] as const;
+
+/** Who picks the cap: `manual` holds the unit to `maxPowerInPercent`, and `auto`
+ * lets the unit choose, which it does in cool and heat only. */
+export type DemandMode = (typeof DEMAND_MODES)[number];
+
+export interface DemandControl {
+  enabled: boolean;
+  /** The unit caps its power draw at this percent. A unit accepts 40, 50 and
+   * 70 in `manual` and 85 in `auto`; what else it accepts is not known. */
+  maxPowerInPercent: number;
+  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. */
+export interface DeviceMetadata {
+  name?: string;
+  /** The adapter's own code for the icon: see UNSUPPORTED.md. */
+  icon?: string;
+  group?: DeviceGroup;
+}

package/src/models/state.ts

@@ -0,0 +1,110 @@
+// The unit's controllable state, in the package's own terms. The
+// codecs map it to and from each protocol's wire encoding.
+
+export const OPERATING_MODES = [
+  "auto",
+  "dehumidify",
+  "cool",
+  "heat",
+  "fan",
+] as const;
+
+export type OperatingMode = (typeof OPERATING_MODES)[number];
+
+export const FAN_SPEEDS = [
+  "auto",
+  "silent",
+  "level1",
+  "level2",
+  "level3",
+  "level4",
+  "level5",
+] as const;
+
+export type FanSpeed = (typeof FAN_SPEEDS)[number];
+
+export const SWING_MODES = ["off", "vertical", "horizontal", "both"] as const;
+
+/** The axes the louvers swing on: `vertical` moves the air up and down, and
+ * `horizontal` moves it left and right. A 3D unit, one with 3D airflow, also
+ * reports each axis on its own, as `DaikinState.verticalPosition` and
+ * `DaikinState.horizontalPosition`. */
+export type SwingMode = (typeof SWING_MODES)[number];
+
+/** The positions a louver holds still at, on either axis. */
+export const FIXED_LOUVER_POSITIONS = [
+  "position1",
+  "position2",
+  "position3",
+  "position4",
+  "position5",
+] as const;
+
+export const VERTICAL_POSITIONS = [
+  "stop",
+  ...FIXED_LOUVER_POSITIONS,
+  "swing",
+  "naturalWind",
+  "auto",
+  "floorWarming",
+] as const;
+
+/** On a DSIOT adapter, `position1` to `position5` are the first five fixed
+ * positions the unit takes, in the adapter's order. */
+export type VerticalPosition = (typeof VERTICAL_POSITIONS)[number];
+
+export const HORIZONTAL_POSITIONS = [
+  "stop",
+  ...FIXED_LOUVER_POSITIONS,
+  "swing",
+  "auto",
+] as const;
+
+/** A DSIOT adapter reports a fixed position as `stop`: see UNSUPPORTED.md. */
+export type HorizontalPosition = (typeof HORIZONTAL_POSITIONS)[number];
+
+export const HUMIDITY_SETTINGS = [
+  "off",
+  "autoLow",
+  "auto",
+  "autoHigh",
+  "continuous",
+] as const;
+
+/** The humidity settings that name no percentage. */
+export type HumiditySetting = (typeof HUMIDITY_SETTINGS)[number];
+
+/** A `HumiditySetting` or a percentage.
+ * `DaikinCapabilities.targetHumidity` lists which of them a unit takes. */
+export type TargetHumidity = HumiditySetting | { percent: number };
+
+export interface DaikinState {
+  power: boolean;
+  mode: OperatingMode;
+  /** `null` in modes without a setpoint (fan, sometimes dehumidify). */
+  targetTemperatureInC: number | null;
+  /** `null` when the unit has no humidity setting. */
+  targetHumidity: TargetHumidity | null;
+  fanSpeed: FanSpeed;
+  swingMode: SwingMode;
+  /** On a 3D unit. `null` where the unit reports none, or one outside
+   * `VerticalPosition`. */
+  verticalPosition: VerticalPosition | null;
+  /** On a 3D unit. `null` where the unit reports none, or one outside
+   * `HorizontalPosition`. */
+  horizontalPosition: HorizontalPosition | null;
+}
+
+/** 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
+ * the target mode, such as a louver position outside
+ * `DaikinCapabilities.verticalPositions`. */
+export type DaikinControl = Partial<DaikinState>;
+
+/** A reading is `null` when the unit does not report it. */
+export interface DaikinSensors {
+  indoorTemperatureInC: number | null;
+  outdoorTemperatureInC: number | null;
+  indoorHumidityInPercent: number | null;
+}

package/src/transport.ts

@@ -0,0 +1,191 @@
+import { Client } from "undici";
+import type { DaikinAuthentication } from "./authentication.js";
+import { encodeTerminalUuid } from "./codecs/credentials.js";
+import { DaikinConnectionError, DaikinError } from "./error.js";
+
+export interface DaikinRequestOptions {
+  /** Retry a refused or dropped connection. Defaults to true. Pass false for a
+   * request that is not safe to repeat. */
+  retry?: boolean;
+}
+
+export interface DaikinRetryOptions {
+  /** How long, in milliseconds, to wait before each retry, so its length is
+   * how many times a request is retried. Defaults to 0, 50, 100, 200 and 400:
+   * see DESIGN.md#retries. Pass an empty array to never retry. */
+  delaysInMs?: number[];
+}
+
+const DEFAULT_RETRY_DELAYS_IN_MS = [0, 50, 100, 200, 400];
+
+/** Runs `operation` again each time it throws a `DaikinConnectionError`, once
+ * for each of `delaysInMs`, and throws any other error at once: see
+ * DESIGN.md#retries. */
+export async function withRetry<ResultT>(
+  operation: () => Promise<ResultT>,
+  { delaysInMs = DEFAULT_RETRY_DELAYS_IN_MS }: DaikinRetryOptions = {},
+): Promise<ResultT> {
+  for (const delayInMs of delaysInMs) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (!(error instanceof DaikinConnectionError)) {
+        throw error;
+      }
+    }
+    await sleep(delayInMs);
+  }
+  return operation();
+}
+
+function sleep(delayInMs: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, delayInMs));
+}
+
+const JSON_CONTENT_HEADERS = {
+  "Content-Type": "application/json",
+};
+
+const DEFAULT_TIMEOUT_IN_MS = 10_000;
+
+// The codes for a refused, reset or closed connection. Every other failure,
+// such as a timeout or a TLS error, is not one.
+const CONNECTION_FAILURE_CODES = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "UND_ERR_SOCKET",
+]);
+
+export interface DaikinRequest {
+  method: "GET" | "POST" | "PUT";
+  /** From the leading `/`, without a query string. */
+  path: string;
+  /** Unencoded: `send` percent-encodes each key and value. */
+  query?: Record<string, string>;
+  /** JSON body for DSIOT writes. Classic uses `query` only. */
+  jsonBody?: unknown;
+}
+
+export interface DaikinTransportOptions {
+  /** With `:port` when the adapter announces one. */
+  host: string;
+  /** HTTPS (a Marvell adapter in secure mode). */
+  usesHttps?: boolean;
+  /** The terminal uuid, sent as `X-Daikin-uuid` on every call. */
+  terminalUuid: string;
+  authentication?: DaikinAuthentication;
+  /** How long, in milliseconds, to wait for each of the connection, the
+   * reply's headers and the reply's body before `send` throws a
+   * `DaikinError` with status 504. Defaults to 10000. */
+  timeoutInMs?: number;
+  /** HTTPS adapters only. */
+  tls?: DaikinTlsOptions;
+}
+
+/** An HTTPS adapter presents a certificate chaining to Daikin's own CA, which
+ * this package cannot ship. So by default the certificate is not verified at
+ * all; supplying the CA turns chain verification on. */
+export interface DaikinTlsOptions {
+  /** Daikin's CA certificate (PEM). The chain is then verified against it, but
+   * not the hostname: the adapter's certificate doesn't name its LAN address. */
+  ca?: string | Buffer;
+}
+
+/** The HTTP connection to one adapter. It builds each URL from `host` and
+ * `usesHttps`, attaches the uuid header and whatever the
+ * `DaikinAuthentication` contributes, and returns the reply's body as text for
+ * a codec to parse.
+ *
+ * It holds one undici connection per adapter, so requests queue rather than
+ * run in parallel: these small embedded servers are best talked to one request
+ * at a time. */
+export class DaikinTransport {
+  private readonly origin: string;
+  private readonly client: Client;
+
+  /** Call `close` when done with the adapter. */
+  constructor(private readonly options: DaikinTransportOptions) {
+    const scheme = options.usesHttps ? "https" : "http";
+    this.origin = `${scheme}://${options.host.replace(/\/+$/, "")}`;
+
+    const timeoutInMs = options.timeoutInMs ?? DEFAULT_TIMEOUT_IN_MS;
+    this.client = new Client(this.origin, {
+      connect: { timeout: timeoutInMs, ...tlsConnectOptions(options.tls) },
+      headersTimeout: timeoutInMs,
+      bodyTimeout: timeoutInMs,
+    });
+  }
+
+  /** Sends one request and returns the reply's body as text. It never retries:
+   * wrap the call in `withRetry` for that.
+   *
+   * It throws a `DaikinConnectionError` when the adapter refuses, resets or
+   * closes the connection, and a `DaikinError` with status 504 when the
+   * request fails to complete any other way, such as a timeout or a TLS
+   * error. A reply whose status is not 2xx makes it throw a `DaikinError`
+   * with that status. */
+  async send(request: DaikinRequest): Promise<string> {
+    const authenticationQuery =
+      (await this.options.authentication?.query()) ?? {};
+    // Not URLSearchParams: it writes a space as `+`, and the adapter expects
+    // `%20` (e.g. `method=home%20only`).
+    const query = Object.entries({ ...request.query, ...authenticationQuery })
+      .map(
+        ([key, value]) =>
+          `${encodeURIComponent(key)}=${encodeURIComponent(value)}`,
+      )
+      .join("&");
+
+    const headers: Record<string, string> = {
+      ...encodeTerminalUuid(this.options.terminalUuid),
+      ...((await this.options.authentication?.headers()) ?? {}),
+      ...(request.jsonBody !== undefined ? JSON_CONTENT_HEADERS : {}),
+    };
+
+    let statusCode: number;
+    let text: string;
+    try {
+      const response = await this.client.request({
+        method: request.method,
+        path: query ? `${request.path}?${query}` : request.path,
+        headers,
+        ...(request.jsonBody !== undefined
+          ? { body: JSON.stringify(request.jsonBody) }
+          : {}),
+      });
+      statusCode = response.statusCode;
+      text = await response.body.text();
+    } catch (error) {
+      const message = `Daikin request to ${request.path} did not complete: ${String(error)}`;
+      if (
+        CONNECTION_FAILURE_CODES.has(
+          (error as NodeJS.ErrnoException).code ?? "",
+        )
+      ) {
+        throw new DaikinConnectionError(message);
+      }
+      throw new DaikinError(message, 504);
+    }
+
+    if (statusCode < 200 || statusCode >= 300) {
+      // The classic protocol signals logical failures in the body with HTTP 200,
+      // so an HTTP error here is a transport-level one.
+      throw new DaikinError(
+        `Daikin request to ${request.path} failed`,
+        statusCode,
+      );
+    }
+    return text;
+  }
+
+  /** Close the connection to the adapter. */
+  async close(): Promise<void> {
+    await this.client.close();
+  }
+}
+
+function tlsConnectOptions(tls: DaikinTlsOptions | undefined) {
+  return tls?.ca === undefined
+    ? { rejectUnauthorized: false }
+    : { ca: tls.ca, checkServerIdentity: () => undefined };
+}