daikin-local-control 0.1.1

package/src/codecs/classic/capabilities.ts

@@ -0,0 +1,272 @@
+import type {
+  DaikinCapabilities,
+  TemperatureRange,
+} from "../../models/capabilities.js";
+import {
+  type FanSpeed,
+  FIXED_LOUVER_POSITIONS,
+  type HorizontalPosition,
+  HUMIDITY_SETTINGS,
+  OPERATING_MODES,
+  type OperatingMode,
+  SWING_MODES,
+  type SwingMode,
+  type TargetHumidity,
+  type VerticalPosition,
+} from "../../models/state.js";
+
+const CAPABILITY_VERSIONS = ["0", "1", "2", "3"];
+const COOLING_ONLY_MODES: readonly OperatingMode[] = [
+  "cool",
+  "dehumidify",
+  "fan",
+];
+const VERTICAL_SWING_MODES: SwingMode[] = ["off", "vertical"];
+const ALL_FAN_LEVELS: FanSpeed[] = [
+  "level1",
+  "level2",
+  "level3",
+  "level4",
+  "level5",
+];
+const FAN_LEVELS_BY_STEPS: Record<string, FanSpeed[]> = {
+  "2": ["level1", "level5"],
+  "3": ["level1", "level3", "level5"],
+  "5": ALL_FAN_LEVELS,
+};
+// `s_humd` is a decimal mask with one bit for each mode that takes a humidity
+// setting.
+const HUMIDITY_MODE_BITS = {
+  auto: 0x01,
+  cool: 0x02,
+  heat: 0x04,
+  dehumidify: 0x10,
+} as const;
+// Dehumidify takes no off.
+const DEHUMIDIFY_HUMIDITY_SETTINGS = HUMIDITY_SETTINGS.filter(
+  (setting) => setting !== "off",
+);
+
+/** Merges the `basic_info` and `get_model_info` replies into the one field map
+ * `parseClassicCapabilities` and `applyClassicControl` read. Both replies
+ * carry a `type` (the adapter's and the unit's), so they are renamed
+ * to `basic_type` and `model_type` before merging; cooling-only detection
+ * reads `model_type`. */
+export function mergeClassicCapabilityFields(
+  basicInfo: Record<string, string>,
+  modelInfo: Record<string, string>,
+): Record<string, string> {
+  const { type: basicType, ...basic } = basicInfo;
+  const { type: modelType, ...model } = modelInfo;
+  return {
+    ...basic,
+    ...model,
+    ...(basicType === undefined ? {} : { basic_type: basicType }),
+    ...(modelType === undefined ? {} : { model_type: modelType }),
+  };
+}
+
+/** Turns the field map from `mergeClassicCapabilityFields` into
+ * `DaikinCapabilities`. `cpv` (capability-protocol version) is the master
+ * branch. Units for Japan (`reg=jp`) follow other rules, which this package
+ * does not model. */
+export function parseClassicCapabilities(
+  fields: Record<string, string>,
+): DaikinCapabilities {
+  const cpv = fields.cpv ?? "";
+  const modern = cpv === "2" || cpv === "3";
+  const threeD = fields.en_fdir2 === "1";
+  const offeredModes = modes(fields, cpv);
+  const offered = (mode: OperatingMode, range: TemperatureRange) =>
+    offeredModes.includes(mode) ? range : null;
+
+  return {
+    modes: offeredModes,
+    fanSpeeds: fanSpeeds(fields, modern),
+    swingModes: swingModes(fields),
+    verticalPositions: threeD ? verticalPositions(fields) : [],
+    horizontalPositions: threeD ? horizontalPositions(fields) : [],
+    targetTemperatureInC: {
+      // Only `subtype=qa` units report an auto range; the rest are fixed.
+      auto: offered(
+        "auto",
+        fields.subtype === "qa"
+          ? range(fields.hmlmt_l, 18, fields.cmlmt_h, 30)
+          : range(undefined, 18, undefined, 30),
+      ),
+      cool: offered("cool", range(fields.cmlmt_l, 18, fields.cmlmt_h, 32)),
+      heat: offered("heat", range(fields.hmlmt_l, 10, fields.hmlmt_h, 30)),
+      dehumidify: null,
+      fan: null,
+    },
+    targetHumidity: targetHumidity(fields, modern, offeredModes),
+    specialOutlet: cpv === "3" && fields.airoutlet_pv === "0",
+    energyMonitoring: fields.elec === "1",
+    demandControl: fields.adp_kind === "4" && fields.dmnd === "1",
+    scheduleTimer: ["1", "2"].includes(fields.en_scdltmr ?? ""),
+    model: fields.model,
+  };
+}
+
+function present(fields: Record<string, string>, key: string): boolean {
+  return (fields[key] ?? "") !== "";
+}
+
+function modes(fields: Record<string, string>, cpv: string): OperatingMode[] {
+  if (!CAPABILITY_VERSIONS.includes(cpv)) {
+    return [];
+  }
+  return fields.model_type === "C"
+    ? OPERATING_MODES.filter((mode) => COOLING_ONLY_MODES.includes(mode))
+    : [...OPERATING_MODES];
+}
+
+function fanSpeeds(
+  fields: Record<string, string>,
+  modern: boolean,
+): FanSpeed[] {
+  if (!present(fields, "reg") || fields.reg === "jp") {
+    return [];
+  }
+  // A `reg=th`, `subtype=qa` unit is controllable by the speeds it lists, not
+  // by `en_frate`.
+  const listsItsSpeeds = fields.reg === "th" && fields.subtype === "qa";
+  if (!listsItsSpeeds && fields.en_frate !== "1") {
+    return [];
+  }
+  const speeds: FanSpeed[] = [];
+  if (!("en_frate_auto" in fields) || fields.en_frate_auto === "1") {
+    speeds.push("auto");
+  }
+  if (
+    modern &&
+    (!present(fields, "en_frate_silent") || fields.en_frate_silent === "1")
+  ) {
+    speeds.push("silent");
+  }
+  const levels =
+    "frate_steps" in fields
+      ? (FAN_LEVELS_BY_STEPS[fields.frate_steps ?? ""] ?? [])
+      : ALL_FAN_LEVELS;
+  return [...speeds, ...levels];
+}
+
+/** Whether a unit's `set_control_info` takes `shum`, read from the field map
+ * of `mergeClassicCapabilityFields`. A `subtype=qa` unit takes none. */
+export function takesClassicHumidity(fields: Record<string, string>): boolean {
+  return fields.subtype !== "qa";
+}
+
+function targetHumidity(
+  fields: Record<string, string>,
+  modern: boolean,
+  offeredModes: OperatingMode[],
+): Record<OperatingMode, TargetHumidity[]> {
+  const mask =
+    modern && takesClassicHumidity(fields)
+      ? Number.parseInt(fields.s_humd ?? "", 10)
+      : 0;
+  const settings = (
+    mode: keyof typeof HUMIDITY_MODE_BITS,
+    values: TargetHumidity[],
+  ) =>
+    offeredModes.includes(mode) && mask & HUMIDITY_MODE_BITS[mode]
+      ? values
+      : [];
+  return {
+    auto: settings("auto", [...HUMIDITY_SETTINGS]),
+    dehumidify: settings("dehumidify", DEHUMIDIFY_HUMIDITY_SETTINGS),
+    cool: settings("cool", [...HUMIDITY_SETTINGS]),
+    heat: settings("heat", [...HUMIDITY_SETTINGS]),
+    fan: [],
+  };
+}
+
+// A unit that takes `f_dir` swings vertically only when `s_fdir=1`; a 3D unit
+// without `f_dir` swings through `f_dir_ud`/`f_dir_lr` on both axes.
+function swingModes(fields: Record<string, string>): SwingMode[] {
+  if (takesClassicDirection(fields)) {
+    return fields.s_fdir === "1" ? VERTICAL_SWING_MODES : [...SWING_MODES];
+  }
+  return fields.en_fdir2 === "1" ? [...SWING_MODES] : [];
+}
+
+/** Whether a unit's `set_control_info` takes `f_dir`, read from the field map
+ * of `mergeClassicCapabilityFields`. */
+export function takesClassicDirection(fields: Record<string, string>): boolean {
+  if (!present(fields, "reg")) {
+    return false;
+  }
+  if (fields.subtype === "qa") {
+    return fields.s_fdir === "1";
+  }
+  const cpv = fields.cpv;
+  if (cpv === "0" || cpv === "1") {
+    return fields.s_fdir === "1" || fields.s_fdir === "3";
+  }
+  return (cpv === "2" || cpv === "3") && fields.en_fdir === "1";
+}
+
+// `s_fdir_ud` is a hex mask: 0x01 swing, 0x10 floor warming, 0x80 the five
+// fixed positions (only when `s_fdir_ud_step=5`). Stop is offered unless a
+// fixed position is.
+function verticalPositions(fields: Record<string, string>): VerticalPosition[] {
+  const stopOrSwing: VerticalPosition[] = ["swing", "stop"];
+  if (!present(fields, "s_fdir_ud")) {
+    return stopOrSwing;
+  }
+  const mask = Number.parseInt(fields.s_fdir_ud ?? "", 16);
+  if (!Number.isFinite(mask)) {
+    return stopOrSwing;
+  }
+  const positions: VerticalPosition[] = [];
+  if (mask & 0x01) {
+    positions.push("swing");
+  }
+  if (mask & 0x10) {
+    positions.push("floorWarming");
+  }
+  if (mask & 0x80) {
+    const steps = Number.parseInt(fields.s_fdir_ud_step ?? "", 10);
+    if (!(steps >= 0 && steps <= 5)) {
+      return stopOrSwing;
+    }
+    if (steps === 5) {
+      positions.push(...FIXED_LOUVER_POSITIONS);
+    }
+  }
+  if (
+    positions.length === 0 ||
+    (positions.length === 1 && positions[0] === "swing")
+  ) {
+    positions.push("stop");
+  }
+  return positions;
+}
+
+// `s_fdir_lr` bit 0x01 is swing; stop is always offered.
+function horizontalPositions(
+  fields: Record<string, string>,
+): HorizontalPosition[] {
+  const mask = Number.parseInt(fields.s_fdir_lr ?? "", 16);
+  return Number.isFinite(mask) && mask & 0x01 ? ["stop", "swing"] : ["stop"];
+}
+
+// Setpoint limits are whole °C on the wire; any fraction is dropped.
+function range(
+  low: string | undefined,
+  fallbackMin: number,
+  high: string | undefined,
+  fallbackMax: number,
+): TemperatureRange {
+  return {
+    min: wholeCelsius(low, fallbackMin),
+    max: wholeCelsius(high, fallbackMax),
+    step: 1,
+  };
+}
+
+function wholeCelsius(value: string | undefined, fallback: number): number {
+  const parsed = Number.parseFloat(value ?? "");
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : fallback;
+}

package/src/codecs/classic/extendedControl.ts

@@ -0,0 +1,132 @@
+import type {
+  DemandControl,
+  DemandMode,
+  DeviceGroup,
+  SpecialMode,
+  TerminalScope,
+} from "../../models/extendedControl.js";
+
+// Encodes each control outside `control_info` as the query its classic `set_*`
+// endpoint takes.
+
+const TERMINAL_SCOPE_CODES: Record<TerminalScope, string> = {
+  self: "0",
+  others: "1",
+  all: "2",
+};
+
+const DEMAND_MODE_CODES: Record<DemandMode, string> = {
+  manual: "0",
+  auto: "2",
+};
+
+// `spmode_kind` on the wire; control_info's `adv` reports powerful as 2 and
+// econo as 12.
+const SPECIAL_MODE_KIND_CODES: Record<
+  Exclude<SpecialMode, "streamer">,
+  string
+> = {
+  powerful: "1",
+  econo: "2",
+};
+
+// `method`: the adapter is reached from outside the home network while it
+// polls, and from inside only otherwise.
+const REMOTE_METHOD_POLLING = "polling";
+const REMOTE_METHOD_HOME_ONLY = "home only";
+
+const REMOTE_METHOD_INTERVALS = ["notice_ip_int", "notice_sync_int"];
+
+export function encodeClassicLed(on: boolean): Record<string, string> {
+  return { led: flag(on) };
+}
+
+export function encodeClassicHolidayMode(
+  enabled: boolean,
+): Record<string, string> {
+  return { en_hol: flag(enabled) };
+}
+
+export function encodeClassicDemandControl(
+  demand: DemandControl,
+): Record<string, string> {
+  return {
+    demand_type: "1",
+    en_demand: flag(demand.enabled),
+    mode: DEMAND_MODE_CODES[demand.mode],
+    max_pow: String(demand.maxPowerInPercent),
+  };
+}
+
+export function encodeClassicSpecialMode(
+  mode: SpecialMode,
+  enabled: boolean,
+): Record<string, string> {
+  return mode === "streamer"
+    ? { en_streamer: flag(enabled) }
+    : { set_spmode: flag(enabled), spmode_kind: SPECIAL_MODE_KIND_CODES[mode] };
+}
+
+/** 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. */
+export function applyClassicOutOfHomeAccess(
+  current: Record<string, string>,
+  enabled: boolean,
+): Record<string, string> {
+  const query: Record<string, string> = {
+    method: enabled ? REMOTE_METHOD_POLLING : REMOTE_METHOD_HOME_ONLY,
+  };
+  for (const key of REMOTE_METHOD_INTERVALS) {
+    const value = current[key];
+    if (value !== undefined) {
+      query[key] = value;
+    }
+  }
+  return query;
+}
+
+/** Encodes the price as the `set_price` query takes it: whole units
+ * (`price_int`) and hundredths (`price_dec`). The price is rounded to two
+ * decimal places. */
+export function encodeClassicEnergyPrice(
+  price: number,
+): Record<string, string> {
+  const hundredths = Math.round(price * 100);
+  return {
+    price_int: String(Math.trunc(hundredths / 100)),
+    price_dec: String(hundredths % 100),
+  };
+}
+
+export function encodeClassicEnergyTarget(
+  target: number,
+): Record<string, string> {
+  return { target: String(target) };
+}
+
+export function encodeClassicName(name: string): Record<string, string> {
+  return { name };
+}
+
+export function encodeClassicIcon(icon: string): Record<string, string> {
+  return { icon };
+}
+
+export function encodeClassicGroup(group: DeviceGroup): Record<string, string> {
+  return { grp_name: group.name, en_grp: flag(group.enabled) };
+}
+
+export function encodeClassicTerminalKey(key: string): Record<string, string> {
+  return { key };
+}
+
+export function encodeClassicTerminalScope(
+  scope: TerminalScope,
+): Record<string, string> {
+  return { type: TERMINAL_SCOPE_CODES[scope] };
+}
+
+function flag(on: boolean): string {
+  return on ? "1" : "0";
+}

package/src/codecs/classic/keyValue.ts

@@ -0,0 +1,39 @@
+import { DaikinError } from "../../error.js";
+
+// The classic CGI protocol answers a flat, comma-separated `key=value` string,
+// e.g. `ret=OK,pow=1,mode=3,stemp=24,...`, and takes its writes as query parameters.
+
+/** Splits a classic reply into its fields. A pair without `=` is dropped, and
+ * a value is kept as the adapter sent it, undecoded. */
+export function parseClassicKeyValue(body: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const pair of body.split(",")) {
+    const index = pair.indexOf("=");
+    if (index === -1) {
+      continue;
+    }
+    result[pair.slice(0, index)] = pair.slice(index + 1);
+  }
+  return result;
+}
+
+export function isClassicOk(fields: Record<string, string>): boolean {
+  return fields.ret === "OK";
+}
+
+/** Throws a `DaikinError` unless the reply's `ret` is `OK`: status 401 for
+ * `AUTH NG` or `LPW NG`, 502 for anything else. Every reply carries a `ret`,
+ * and the adapter rejects a call with HTTP 200, so the rejection has to be
+ * read here rather than from the status code. */
+export function assertClassicOk(fields: Record<string, string>): void {
+  if (isClassicOk(fields)) {
+    return;
+  }
+  const ret = fields.ret;
+  // AUTH NG: the terminal is not registered. LPW NG: the child lock code is
+  // wrong.
+  if (ret === "AUTH NG" || ret === "LPW NG") {
+    throw new DaikinError(`Daikin rejected the credentials (ret=${ret})`, 401);
+  }
+  throw new DaikinError(`Daikin command failed (ret=${ret ?? "missing"})`, 502);
+}