daikin-local-control 0.1.1

package/src/codecs/classic/state.ts

@@ -0,0 +1,302 @@
+import type {
+  DaikinControl,
+  DaikinSensors,
+  DaikinState,
+  FanSpeed,
+  HorizontalPosition,
+  HumiditySetting,
+  OperatingMode,
+  SwingMode,
+  TargetHumidity,
+  VerticalPosition,
+} from "../../models/state.js";
+import { takesClassicDirection, takesClassicHumidity } from "./capabilities.js";
+
+// Maps between `DaikinState` and the classic `control_info` wire fields, and reads
+// `DaikinSensors` from `get_sensor_info`.
+
+const OPERATING_MODE_CODES: Record<OperatingMode, string> = {
+  auto: "1",
+  dehumidify: "2",
+  cool: "3",
+  heat: "4",
+  fan: "6",
+};
+
+const OPERATING_MODES_BY_CODE: Record<string, OperatingMode> = {
+  "0": "auto",
+  "1": "auto",
+  "7": "auto",
+  "2": "dehumidify",
+  "3": "cool",
+  "4": "heat",
+  "6": "fan",
+};
+
+const FAN_SPEED_CODES: Record<FanSpeed, string> = {
+  auto: "A",
+  silent: "B",
+  level1: "3",
+  level2: "4",
+  level3: "5",
+  level4: "6",
+  level5: "7",
+};
+
+const FAN_SPEEDS_BY_CODE: Record<string, FanSpeed> = Object.fromEntries(
+  Object.entries(FAN_SPEED_CODES).map(([speed, code]) => [
+    code,
+    speed as FanSpeed,
+  ]),
+);
+
+const SWING_MODE_CODES: Record<SwingMode, string> = {
+  off: "0",
+  vertical: "1",
+  horizontal: "2",
+  both: "3",
+};
+
+const SWING_MODES_BY_CODE: Record<string, SwingMode> = Object.fromEntries(
+  Object.entries(SWING_MODE_CODES).map(([swing, code]) => [
+    code,
+    swing as SwingMode,
+  ]),
+);
+
+// `f_dir_ud` and `f_dir_lr` carry a digit for stop and each fixed position, and
+// a letter for the rest.
+const LOUVER_STOP = "0";
+const LOUVER_SWING = "S";
+const VERTICAL_POSITION_CODES: Record<VerticalPosition, string> = {
+  stop: LOUVER_STOP,
+  position1: "1",
+  position2: "2",
+  position3: "3",
+  position4: "4",
+  position5: "5",
+  swing: LOUVER_SWING,
+  naturalWind: "N",
+  auto: "A",
+  floorWarming: "F",
+};
+const HORIZONTAL_POSITION_CODES: Record<HorizontalPosition, string> = {
+  stop: LOUVER_STOP,
+  position1: "1",
+  position2: "2",
+  position3: "3",
+  position4: "4",
+  position5: "5",
+  swing: LOUVER_SWING,
+  auto: "A",
+};
+
+const VERTICAL_POSITIONS_BY_CODE: Record<string, VerticalPosition> =
+  Object.fromEntries(
+    Object.entries(VERTICAL_POSITION_CODES).map(([position, code]) => [
+      code,
+      position as VerticalPosition,
+    ]),
+  );
+
+const HORIZONTAL_POSITIONS_BY_CODE: Record<string, HorizontalPosition> =
+  Object.fromEntries(
+    Object.entries(HORIZONTAL_POSITION_CODES).map(([position, code]) => [
+      code,
+      position as HorizontalPosition,
+    ]),
+  );
+
+const HUMIDITY_SETTING_CODES: Record<HumiditySetting, string> = {
+  off: "0",
+  autoLow: "AUTO_L",
+  auto: "AUTO",
+  autoHigh: "AUTO_H",
+  continuous: "CONTINUE",
+};
+
+const HUMIDITY_SETTINGS_BY_CODE: Record<string, HumiditySetting> =
+  Object.fromEntries(
+    Object.entries(HUMIDITY_SETTING_CODES).map(([setting, code]) => [
+      code,
+      setting as HumiditySetting,
+    ]),
+  );
+
+// Fan mode keeps no setpoint memory, and dehumidify runs the fan on auto only.
+const NO_SETPOINT = "--";
+const DEHUMIDIFY_FAN_SPEED = "A";
+// In `ndfd<mode>`, a louver the unit lacks.
+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`. */
+export function parseClassicState(fields: Record<string, string>): DaikinState {
+  return {
+    power: fields.pow === "1",
+    mode: OPERATING_MODES_BY_CODE[fields.mode ?? ""] ?? "auto",
+    targetTemperatureInC: parseNumeric(fields.stemp),
+    targetHumidity: parseTargetHumidity(fields.shum),
+    fanSpeed: FAN_SPEEDS_BY_CODE[fields.f_rate ?? ""] ?? "auto",
+    swingMode: SWING_MODES_BY_CODE[fields.f_dir ?? ""] ?? "off",
+    verticalPosition: VERTICAL_POSITIONS_BY_CODE[fields.f_dir_ud ?? ""] ?? null,
+    horizontalPosition:
+      HORIZONTAL_POSITIONS_BY_CODE[fields.f_dir_lr ?? ""] ?? null,
+  };
+}
+
+export function parseClassicSensors(
+  fields: Record<string, string>,
+): DaikinSensors {
+  return {
+    indoorTemperatureInC: parseNumeric(fields.htemp),
+    outdoorTemperatureInC: parseNumeric(fields.otemp),
+    indoorHumidityInPercent: parseNumeric(fields.hhum),
+  };
+}
+
+/** Turns `current`, the `get_control_info` reply, and a control into the
+ * `set_control_info` query: power and mode, the setpoint, humidity and fan
+ * speed for the target mode, and the airflow fields the unit takes. When the
+ * mode changes, each comes from the target mode's memory: `dt`, `dh`, `dfr`,
+ * `dfd` and, for the louvers, `ndfd`. `capabilityFields`, the field map of
+ * `mergeClassicCapabilityFields`, says which fields the unit takes: `shum`
+ * unless it is `subtype=qa`, `f_dir_ud` and `f_dir_lr` on a 3D unit
+ * (`en_fdir2`), and `f_dir` on a unit that takes a direction. It drops a
+ * `targetTemperatureInC` in dehumidify, writes `mode=0` and `mode=7` as
+ * `mode=1`, and never echoes `ret`, `adv` or the other modes' memory. */
+export function applyClassicControl(
+  current: Record<string, string>,
+  control: DaikinControl,
+  capabilityFields: Record<string, string>,
+): Record<string, string> {
+  const takesDirection = takesClassicDirection(capabilityFields);
+  const heldMode = OPERATING_MODES_BY_CODE[current.mode ?? ""];
+  // A mode outside the model is sent back as it came.
+  const currentMode =
+    heldMode === undefined
+      ? (current.mode ?? "")
+      : OPERATING_MODE_CODES[heldMode];
+  const mode =
+    control.mode === undefined
+      ? currentMode
+      : OPERATING_MODE_CODES[control.mode];
+  const modeChanged = mode !== currentMode;
+  const remembered = (field: string, memoryPrefix: string) =>
+    (modeChanged ? current[`${memoryPrefix}${mode}`] : undefined) ??
+    current[field] ??
+    "";
+
+  const power = control.power ?? current.pow === "1";
+  const next: Record<string, string> = { pow: power ? "1" : "0", mode };
+
+  const setpointFrozen = mode === OPERATING_MODE_CODES.fan;
+  // Only a mode in the model has a `dt` and a `dh` memory.
+  const hasMemory =
+    !setpointFrozen && (control.mode !== undefined || heldMode !== undefined);
+  next.stemp = setpointFrozen
+    ? NO_SETPOINT
+    : control.targetTemperatureInC != null &&
+        mode !== OPERATING_MODE_CODES.dehumidify
+      ? control.targetTemperatureInC.toFixed(1)
+      : remembered("stemp", "dt");
+  if (hasMemory) {
+    next[`dt${mode}`] = next.stemp;
+  }
+  if (takesClassicHumidity(capabilityFields)) {
+    next.shum = setpointFrozen
+      ? NO_SETPOINT
+      : control.targetHumidity != null
+        ? encodeTargetHumidity(control.targetHumidity)
+        : remembered("shum", "dh");
+    if (hasMemory) {
+      next[`dh${mode}`] = next.shum;
+    }
+  }
+
+  next.f_rate =
+    mode === OPERATING_MODE_CODES.dehumidify
+      ? DEHUMIDIFY_FAN_SPEED
+      : control.fanSpeed === undefined
+        ? remembered("f_rate", "dfr")
+        : FAN_SPEED_CODES[control.fanSpeed];
+
+  if (capabilityFields.en_fdir2 === "1") {
+    // `ndfd<mode>` holds the mode's `f_dir_ud` value, then its `f_dir_lr`
+    // value. A value outside the model is sent back as it came.
+    const louverMemory = modeChanged ? current[`ndfd${mode}`] : undefined;
+    let vertical =
+      rememberedLouver(louverMemory, 0) || current.f_dir_ud || LOUVER_STOP;
+    let horizontal =
+      rememberedLouver(louverMemory, 1) || current.f_dir_lr || LOUVER_STOP;
+    if (control.swingMode !== undefined) {
+      const swingsVertically =
+        control.swingMode === "vertical" || control.swingMode === "both";
+      const swingsHorizontally =
+        control.swingMode === "horizontal" || control.swingMode === "both";
+      vertical = swingsVertically
+        ? LOUVER_SWING
+        : vertical === LOUVER_SWING
+          ? LOUVER_STOP
+          : vertical;
+      horizontal = swingsHorizontally
+        ? LOUVER_SWING
+        : horizontal === LOUVER_SWING
+          ? LOUVER_STOP
+          : horizontal;
+    }
+    if (control.verticalPosition != null) {
+      vertical = VERTICAL_POSITION_CODES[control.verticalPosition];
+    }
+    if (control.horizontalPosition != null) {
+      horizontal = HORIZONTAL_POSITION_CODES[control.horizontalPosition];
+    }
+    next.f_dir_ud = vertical;
+    next.f_dir_lr = horizontal;
+    if (takesDirection) {
+      next.f_dir = String(
+        (vertical === LOUVER_SWING ? 1 : 0) |
+          (horizontal === LOUVER_SWING ? 2 : 0),
+      );
+    }
+  } else if (takesDirection) {
+    next.f_dir =
+      control.swingMode === undefined
+        ? remembered("f_dir", "dfd")
+        : SWING_MODE_CODES[control.swingMode];
+  }
+  return next;
+}
+
+function parseTargetHumidity(shum: string | undefined): TargetHumidity | null {
+  const setting = HUMIDITY_SETTINGS_BY_CODE[shum ?? ""];
+  if (setting !== undefined) {
+    return setting;
+  }
+  const percent = parseNumeric(shum);
+  return percent === null ? null : { percent };
+}
+
+function encodeTargetHumidity(targetHumidity: TargetHumidity): string {
+  return typeof targetHumidity === "string"
+    ? HUMIDITY_SETTING_CODES[targetHumidity]
+    : String(targetHumidity.percent);
+}
+
+function rememberedLouver(
+  louverMemory: string | undefined,
+  index: number,
+): string | undefined {
+  const value = louverMemory?.[index];
+  return value === NO_LOUVER ? undefined : value;
+}
+
+function parseNumeric(value: string | undefined): number | null {
+  if (value === undefined || value === "") {
+    return null;
+  }
+  const parsed = Number(value);
+  // Modes without a setpoint answer "M", "--" or "-", which are not numbers.
+  return Number.isFinite(parsed) ? parsed : null;
+}

package/src/codecs/credentials.ts

@@ -0,0 +1,19 @@
+/** The header that carries the terminal uuid on every call. The adapter takes
+ * the uuid without its dashes. */
+export function encodeTerminalUuid(uuid: string): Record<string, string> {
+  return { "X-Daikin-uuid": uuid.replaceAll("-", "") };
+}
+
+/** The query parameter a classic adapter takes the local password as. */
+export function encodeClassicLocalPassword(
+  localPassword: string,
+): Record<string, string> {
+  return { lpw: localPassword };
+}
+
+/** The header a DSIOT adapter takes the local password as. */
+export function encodeDsiotLocalPassword(
+  localPassword: string,
+): Record<string, string> {
+  return { Authorization: `Basic ${localPassword}` };
+}

package/src/codecs/device.ts

@@ -0,0 +1,41 @@
+import type { DaikinDevice } from "../models/device.js";
+
+const DSIOT_TYPE = "GPF";
+const MARVELL_ADP_KIND = "3";
+
+/** Turns a `basic_info` reply into a `DaikinDevice`: `type=GPF` marks a DSIOT
+ * adapter, and `api_port`, when present, is the HTTP port and is appended to
+ * `host`, the address the reply came from. */
+export function parseDevice(
+  host: string,
+  basicInfo: Record<string, string>,
+): DaikinDevice {
+  const protocol = basicInfo.type === DSIOT_TYPE ? "dsiot" : "classic";
+  const secure = basicInfo.en_secure === "1";
+  return {
+    host: basicInfo.api_port ? `${host}:${basicInfo.api_port}` : host,
+    protocol,
+    name: decodeName(basicInfo.name),
+    // Only classic adapters register terminals.
+    requiresRegistration: secure && protocol === "classic",
+    // Only a Marvell adapter (adp_kind=3) in secure mode speaks HTTPS; every
+    // other adapter, DSIOT included, stays on HTTP on the LAN.
+    usesHttps:
+      secure &&
+      protocol === "classic" &&
+      basicInfo.adp_kind === MARVELL_ADP_KIND,
+    requiresLocalPassword: basicInfo.lpw_flag === "1",
+  };
+}
+
+// The name is form-encoded: `+` is a space.
+function decodeName(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  try {
+    return decodeURIComponent(value.replaceAll("+", " "));
+  } catch {
+    return value;
+  }
+}

package/src/codecs/dsiot/capabilities.ts

@@ -0,0 +1,209 @@
+import type {
+  DaikinCapabilities,
+  TemperatureRange,
+} from "../../models/capabilities.js";
+import {
+  FAN_SPEEDS,
+  type FanSpeed,
+  FIXED_LOUVER_POSITIONS,
+  HORIZONTAL_POSITIONS,
+  type HorizontalPosition,
+  HUMIDITY_SETTINGS,
+  OPERATING_MODES,
+  type OperatingMode,
+  SWING_MODES,
+  type SwingMode,
+  VERTICAL_POSITIONS,
+  type VerticalPosition,
+} from "../../models/state.js";
+import {
+  DSIOT_HORIZONTAL_POSITION_VALUES,
+  DSIOT_MODE_PATHS,
+  DSIOT_PATHS,
+  DSIOT_VERTICAL_POSITION_VALUES,
+  type DsiotSetpoint,
+  decodeDsiotLittleEndian,
+} from "./state.js";
+
+const MODE_PATHS = Object.values(DSIOT_MODE_PATHS);
+
+const ADAPTER_PATHS = {
+  region: "adp_i.reg",
+  kind: "adp_i.kind",
+  energyMonitoring: "adp_i.func.en_ipower",
+  demandControl: "adp_i.func.en_demand",
+  scheduleTimer: "adp_i.func.en_scdltmr",
+} as const;
+
+const COOLING_ONLY_MODEL_TYPE = "01";
+const COOLING_ONLY_MODES: readonly OperatingMode[] = [
+  "dehumidify",
+  "cool",
+  "fan",
+];
+
+// The fixed positions, 1-14, in a louver leaf's `md.mx`.
+const FIXED_LOUVER_MASK = 0x7ffe;
+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. */
+export function parseDsiotCapabilities(
+  values: Record<string, string>,
+): DaikinCapabilities {
+  const modes =
+    values[DSIOT_PATHS.modelType] === COOLING_ONLY_MODEL_TYPE
+      ? [...COOLING_ONLY_MODES]
+      : [...OPERATING_MODES];
+  const offered = (mode: OperatingMode, range: TemperatureRange) =>
+    modes.includes(mode) ? range : null;
+  // A mode takes a humidity setting when the unit reports the mode's flag.
+  const humiditySettings = (mode: OperatingMode) => {
+    const flag = DSIOT_MODE_PATHS[mode].humidity?.flag;
+    return modes.includes(mode) && flag !== undefined && flag in values
+      ? [...HUMIDITY_SETTINGS]
+      : [];
+  };
+  const vertical = hasLouver(values, "vertical");
+  const horizontal = hasLouver(values, "horizontal");
+  const energyMonitoring =
+    values[ADAPTER_PATHS.energyMonitoring] === "1" &&
+    values[DSIOT_PATHS.energyMonitoring] === "01";
+
+  return {
+    modes,
+    fanSpeeds: fanSpeeds(values),
+    swingModes: swingModes(vertical, horizontal),
+    verticalPositions: vertical
+      ? verticalPositions(louverMask(values, "vertical"))
+      : [],
+    horizontalPositions: horizontal
+      ? horizontalPositions(louverMask(values, "horizontal"))
+      : [],
+    targetTemperatureInC: {
+      auto: offered("auto", { min: 18, max: 30, step: 0.5 }),
+      cool: offered(
+        "cool",
+        range(values, DSIOT_MODE_PATHS.cool.setpoint, 18, 32),
+      ),
+      heat: offered(
+        "heat",
+        range(values, DSIOT_MODE_PATHS.heat.setpoint, 10, 30),
+      ),
+      dehumidify: null,
+      fan: null,
+    },
+    targetHumidity: {
+      auto: humiditySettings("auto"),
+      // Dehumidify takes no off.
+      dehumidify: humiditySettings("dehumidify").filter(
+        (setting) => setting !== "off",
+      ),
+      cool: humiditySettings("cool"),
+      heat: humiditySettings("heat"),
+      fan: [],
+    },
+    // Which leaf reports the special air outlet is not known: see
+    // UNSUPPORTED.md.
+    specialOutlet: false,
+    energyMonitoring,
+    demandControl:
+      energyMonitoring &&
+      values[ADAPTER_PATHS.kind] === "4" &&
+      values[ADAPTER_PATHS.demandControl] === "1",
+    scheduleTimer: ["1", "2"].includes(
+      values[ADAPTER_PATHS.scheduleTimer] ?? "",
+    ),
+    model: values[DSIOT_PATHS.model],
+  };
+}
+
+function hasLouver(values: Record<string, string>, axis: LouverAxis): boolean {
+  return MODE_PATHS.some((paths) => paths[axis] in values);
+}
+
+// Every value the unit takes on an axis in any mode, as `md.mx` bits.
+function louverMask(values: Record<string, string>, axis: LouverAxis): number {
+  return MODE_PATHS.reduce(
+    (mask, paths) =>
+      mask | decodeDsiotLittleEndian(values[`${paths[axis]}.md.mx`] ?? ""),
+    0,
+  );
+}
+
+function takes(mask: number, value: number | undefined): boolean {
+  return value !== undefined && (mask & (1 << value)) !== 0;
+}
+
+// Japanese units (`jp`) follow other rules: see UNSUPPORTED.md.
+function fanSpeeds(values: Record<string, string>): FanSpeed[] {
+  const region = values[ADAPTER_PATHS.region];
+  if (!region || region === "jp") {
+    return [];
+  }
+  return MODE_PATHS.some(({ fanSpeed }) => fanSpeed in values)
+    ? [...FAN_SPEEDS]
+    : [];
+}
+
+function swingModes(vertical: boolean, horizontal: boolean): SwingMode[] {
+  if (vertical && horizontal) {
+    return [...SWING_MODES];
+  }
+  if (vertical) {
+    return ["off", "vertical"];
+  }
+  return horizontal ? ["off", "horizontal"] : [];
+}
+
+// A unit that takes n fixed values offers the first n fixed positions, as
+// `parseDsiotState` names them by rank.
+function verticalPositions(mask: number): VerticalPosition[] {
+  // Without `md.mx` the unit does not say what it takes.
+  if (mask === 0) {
+    return ["stop", "swing"];
+  }
+  const fixedCount = bitCount(mask & FIXED_LOUVER_MASK);
+  return VERTICAL_POSITIONS.filter((position) => {
+    const rank = FIXED_POSITIONS.indexOf(position);
+    return rank === -1
+      ? takes(mask, DSIOT_VERTICAL_POSITION_VALUES[position])
+      : rank < fixedCount;
+  });
+}
+
+// `parseDsiotState` reads a fixed position as `stop`, so stop is always
+// offered: see UNSUPPORTED.md.
+function horizontalPositions(mask: number): HorizontalPosition[] {
+  return HORIZONTAL_POSITIONS.filter(
+    (position) =>
+      position === "stop" ||
+      takes(mask, DSIOT_HORIZONTAL_POSITION_VALUES[position]),
+  );
+}
+
+function bitCount(mask: number): number {
+  return mask.toString(2).replaceAll("0", "").length;
+}
+
+// A setpoint's `md.mi` and `md.mx` count half degrees. Without both, the range
+// is `fallbackMin` to `ceiling`, and `ceiling` caps the unit's own maximum.
+function range(
+  values: Record<string, string>,
+  setpoint: DsiotSetpoint | undefined,
+  fallbackMin: number,
+  ceiling: number,
+): TemperatureRange {
+  const min =
+    decodeDsiotLittleEndian(values[`${setpoint?.path}.md.mi`] ?? "") / 2;
+  const max =
+    decodeDsiotLittleEndian(values[`${setpoint?.path}.md.mx`] ?? "") / 2;
+  const reported = Number.isFinite(min) && Number.isFinite(max);
+  return {
+    min: reported ? min : fallbackMin,
+    max: reported ? Math.min(max, ceiling) : ceiling,
+    step: 0.5,
+  };
+}