@khalido/home 0.1.3 → 0.2.1

package/src/cli/probe.ts

@@ -6,6 +6,7 @@ import {
   printerList,
 } from "../connectors/printers/index.ts";
 import { gatewayHost } from "../connectors/enphase/client.ts";
+import { fetchTimeout } from "../connector.ts";
 import { bunPinnedFetch } from "../connectors/hue/index.ts";
 import { type WeatherSource } from "../connectors/weather/index.ts";
 import {
@@ -39,7 +40,7 @@ function envFromConfig(path: string): Record<string, string> {
       Object.assign(out, {
         HUE_BRIDGE_HOST: d.host,
         HUE_BRIDGE_ID: d.bridgeId,
-        HUE_CA_FILE: fromConfig(path, d.ca),
+        HUE_CA_FILE: d.ca && fromConfig(path, d.ca),
         HUE_APPLICATION_KEY: env[d.key],
       });
     if (d.connector === "daikin") out.DAIKIN_HOST = d.host;
@@ -111,25 +112,28 @@ const jsonOr = (body: string) => {
 
 export async function probe(o: Options): Promise<void> {
   const configPath = configPathOf(o);
-  if (configPath) Object.assign(env, envFromConfig(configPath)); // the config's addresses, for this one command
+  if (configPath) {
+    delete env.HUE_CA_FILE; // the config's `ca` or the package's roots, never the shell's file
+    Object.assign(env, envFromConfig(configPath)); // the config's addresses, for this one command
+  }
   const out: Record<string, unknown> = {};
   try {
     const b = await bridge();
-    const fetchPinned = env.HUE_CA_FILE
-      ? bunPinnedFetch(b.id, ca())
-      : undefined;
-    const r = fetchPinned
-      ? await fetchPinned(`https://${b.host}/api/0/config`).then((x) =>
-          x.json(),
-        )
-      : "needs HUE_CA_FILE";
-    out.hue =
-      typeof r === "string"
-        ? { status: r }
-        : {
-            status: "answers",
-            ...pick(r, ["name", "modelid", "apiversion", "swversion"]),
-          };
+    const r = await fetchTimeout(
+      bunPinnedFetch(b.id, ca()),
+      `https://${b.host}/api/0/config`,
+      {},
+      { timeoutMs: 5000 },
+    ).then((x) => x.json());
+    out.hue = {
+      status: "answers",
+      ...pick(r as Record<string, unknown>, [
+        "name",
+        "modelid",
+        "apiversion",
+        "swversion",
+      ]),
+    };
   } catch (error) {
     out.hue = { status: "unavailable", detail: (error as Error).message };
   }

package/src/cli/status.ts

@@ -12,13 +12,15 @@ import {
   type WeatherSource,
 } from "../connectors/weather/index.ts";
 import { ftpFetch } from "../connectors/weather/ftp.ts";
-import { loadHome } from "../config.ts";
+import { HomeConfig, loadHome } from "../config.ts";
+import { DEVICES, type HomeDevice, homeDevices } from "../devices.ts";
 import { energyNow, gridText } from "../energy.ts";
 import { FINDERS } from "../finders.ts";
 import { type Integration, type Part, type Status, settle } from "../home.ts";
 import { kw, type Manifest } from "../manifest.ts";
 import { MANIFESTS, manifestOf } from "../manifests.ts";
 import { castNow } from "./cast.ts";
+import { daikinHost } from "./daikin.ts";
 import { printersNow } from "./printers.ts";
 import { spotifyFromEnv } from "./spotify.ts";
 import {
@@ -62,17 +64,25 @@ export const weatherSources = (): WeatherSource[] => [
 
 /**
  * Each connector from the shell's env names, once the manifest's non-optional names are set. `needs` adds a step that
- * is not an env name (Enphase's token file). Addresses come from the env only; `home probe` and `home discover` search.
+ * is not an env name (Enphase's token file). Addresses come from the env, except the Daikin's and the Hue bridge's, which
+ * are searched for when unset; `home probe` and `home discover` search for the rest.
  */
 const FROM_ENV: Record<
   string,
   {
-    needs?: () => string[];
+    needs?: () => string[] | Promise<string[]>;
     build: () => Integration<any> | Promise<Integration<any>>;
   }
 > = {
   hue: { build: hueFromEnv },
-  daikin: { build: () => daikin({ host: env.DAIKIN_HOST!, fetch }) },
+  daikin: {
+    // No address set: ask the network. A home with no unit reads "not set up", not as a failure.
+    needs: async () =>
+      (await daikinHost())
+        ? []
+        : ["DAIKIN_HOST (no unit answered the UDP broadcast)"],
+    build: async () => daikin({ host: (await daikinHost())!, fetch }),
+  },
   enphase: {
     needs: () => (existsSync(TOKEN_FILE) ? [] : ["`home enphase login`"]),
     build: enphaseFromEnv,
@@ -106,7 +116,7 @@ async function statusFromEnv(
       const from = FROM_ENV[m.name]!;
       const needs = [
         ...m.env.filter((e) => !e.optional && !env[e.name]).map((e) => e.name),
-        ...(from.needs?.() ?? []),
+        ...((await from.needs?.()) ?? []),
       ];
       rows[m.name] = {
         status: needs.length ? "not set up" : "connecting",
@@ -216,13 +226,54 @@ function rowLines(name: string, r: Row): string[] {
   ];
 }
 
+/** Every connector's row (or the one named), from the config at `path`, else from the shell's env names. */
+const rowsOf = (path: string | undefined, only?: string) =>
+  path
+    ? statusFromConfig(path, only)
+    : statusFromEnv(only === undefined ? MANIFESTS : [manifestOf(only)!]);
+
+/**
+ * `home devices`: every device the connectors read, one line each from `homeDevices`, with its room and name from the
+ * config when there is one. A connector that isn't connected is named on stderr.
+ */
+export async function devices(o: Options): Promise<void> {
+  const path = configPathOf(o);
+  const rows = await rowsOf(path);
+  const parts: Record<string, Part> = {};
+  for (const [name, r] of Object.entries(rows))
+    if (r.status !== "not set up") parts[name] = r as Part;
+  // loadHome has already accepted the config, so a parse that fails here is not expected: list without rooms.
+  const config = path ? HomeConfig.safeParse(readConfig(path)).data : undefined;
+  const list = homeDevices(parts, config);
+  // A connector that isn't connected may have no device to list: say so, off stdout.
+  for (const [name, r] of Object.entries(rows))
+    if (name in DEVICES && r.status !== "connected")
+      console.error(
+        [
+          `${name}: ${r.status}`,
+          r.needs.length ? `needs ${r.needs.join(", ")}` : "",
+          r.detail ?? "",
+        ]
+          .filter(Boolean)
+          .join(" · "),
+      );
+  if (o.json) return printJson(list);
+  for (const d of list) console.log(deviceLine(d));
+}
+
+/** A device's line: "connector  text · in room · not available: reason". */
+export const deviceLine = (d: HomeDevice): string =>
+  [
+    `${d.connector.padEnd(9)}${d.text}`,
+    d.room ? `in ${d.room}` : "",
+    d.available === false ? `not available: ${d.reason}` : "",
+  ]
+    .filter(Boolean)
+    .join(" · ");
+
 /** `home status`: every connector, with the energy now on top. With `only` (`home <connector>`), that connector alone. */
 export async function status(o: Options, only?: string): Promise<void> {
-  const path = configPathOf(o);
-  const manifests = only === undefined ? MANIFESTS : [manifestOf(only)!];
-  const rows = path
-    ? await statusFromConfig(path, only)
-    : await statusFromEnv(manifests);
+  const rows = await rowsOf(configPathOf(o), only);
   if (only !== undefined) {
     const row = rows[only]!;
     if (row.status !== "connected") process.exitCode = 1; // `home <connector>` is a check a script can test; `home` alone lists every one and exits 0

package/src/config.ts

@@ -70,6 +70,12 @@ export const Room = z.looseObject({
     .describe(
       "the Hue room, zone or grouped_light id whose lights this room's marker shows",
     ),
+  photos: z
+    .array(filePath)
+    .optional()
+    .describe(
+      "photos of the room, as paths relative to the config or from ~/; the library never reads them, a drawing agent or an app does",
+    ),
 });
 
 /** JSONC (comments and trailing commas) through jsonc-parser, which runs on Node too; a syntax error throws rather than parsing to part of the file. */
@@ -323,7 +329,7 @@ export type LoadOptions = {
   fetch?: typeof fetch;
   /** Hue's pinned fetch and Enphase's unverified one: Bun's by default, `NODE_TLS` from `@khalido/home/node` under Node. */
   tls?: {
-    hue(bridgeId: string, ca: string): typeof fetch;
+    hue(bridgeId: string, ca?: string): typeof fetch;
     enphase(): typeof fetch;
   };
   /** BOM's transport: `ftpFetch()` from `@khalido/home/weather/ftp`. Without it a listed `bom` source stops and says why. */
@@ -445,7 +451,7 @@ export function loadHome(
   ): HomeIntegration {
     switch (d.connector) {
       case "hue": {
-        const ca = file(d.ca);
+        const ca = d.ca === undefined ? undefined : file(d.ca);
         return hue({
           ...start("hue", d.bridgeId, d.host),
           bridgeId: d.bridgeId,

package/src/connector.ts

@@ -51,6 +51,11 @@ export class ConnectorError extends Error {
   }
 }
 
+/** A 401 or 403 from a device or service: the key or token is wrong or revoked. Every connector reads it as `reason: "auth"`. */
+export const isRejectedKey = (error: unknown) =>
+  error instanceof ConnectorError &&
+  (error.status === 401 || error.status === 403);
+
 /** `fetch` that gives up after `timeoutMs`, or as soon as `signal` (a run's) aborts. Returns the response whatever its status. */
 export function fetchTimeout(
   fetcher: typeof fetch,

package/src/connectors/amber/README.md

@@ -9,7 +9,7 @@ Amber Electric's live wholesale-linked prices, read through Amber's public API.
 - `forecast`: the current interval, then each forecast one, both channels on one row (`PriceInterval`). `next=96` asks for more than Amber has, so the reply runs as far as Amber forecasts: on 2026-10-28 at 3 pm, 12 five-minute intervals then 14 half-hours, to 11 pm. Amber's `startTime` is a second past the interval's start, so `start` is taken to the minute.
 - `estimate: true` means the current interval's price can still move; it is shown as "(estimate)", never as an anomaly.
 - The Amber line in `home status` shows the descriptor, "(estimate)", a spike other than `none`, and a negative price. `energyNow` combines the prices with Enphase; see Energy below.
-- A 401 marks Amber unavailable and stops polling.
+- A 401 or 403 marks Amber unavailable and stops polling.
 
 ## Energy
 

package/src/connectors/amber/client.ts

@@ -4,7 +4,7 @@ import { ConnectorError, getJson } from "../../connector.ts";
 // Amber Electric's public API v1 (https://app.amber.com.au/developers; the published spec is 1.0, there is no v2). Shapes checked against live replies,
 // 2026-10-13; every field optional so a change degrades a reading rather than throwing.
 
-/** A failed Amber call. `status` 401 means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
+/** A failed Amber call. `status` 401 or 403 (`isRejectedKey`) means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
 export class AmberError extends ConnectorError {}
 
 /** One 5-minute price interval on one channel. Prices are c/kWh including GST, as a cost: negative feed-in means you are paid. */

package/src/connectors/amber/index.ts

@@ -1,5 +1,5 @@
 import { asOf, type Clock, realClock } from "../../clock.ts";
-import { errorText } from "../../connector.ts";
+import { errorText, isRejectedKey } from "../../connector.ts";
 import { z } from "zod";
 import { envName, type Integration } from "../../home.ts";
 import { energyNow } from "../../energy.ts";
@@ -62,7 +62,7 @@ export function amber(
           update({ status: "connected", anomaly: last.anomaly, state: last });
         } catch (error) {
           if (signal.aborted) return; // stopped mid-read: not a failure
-          if (error instanceof AmberError && error.status === 401)
+          if (isRejectedKey(error))
             return update({
               status: "unavailable",
               reason: "auth",

package/src/connectors/cast/README.md

@@ -10,9 +10,10 @@ Nest speakers, Nest Hubs, Chromecasts, Google TV and speaker groups, read over C
 - The part is `connecting` until every device has answered or failed, then `connected` while any is up; `detail` names the ones down. A payload of a known type the schema rejects is an `anomaly`, never thrown.
 - State (`CastSnapshot`, by mDNS id): `form` (`speaker`, `display` or `tv`, from `castForm(model)`; none for a model it doesn't know; the address cache keeps the model), app, `idle` (no app, or Backdrop's `isIdleScreen`), `standby`, volume (unrounded), muted, `volumeControl`, player state, title, artist; groups carry `members` and `leader`; devices carry `groups`, and `playingVia` when they show a playing group's media because their own is empty (Home Assistant's model, not yet seen live).
 - Names: a device's `name` in the snapshot is its own, from discovery's `fn` or its own multizone status (the same text on all six live devices, 2026-10-13), so a rename in the Google Home app shows once the device answers, even when every address came from the cache and discovery never ran; the config's name is only the placeholder until then. A group's multizone status lists its members, not itself, so a group's new name shows at the next discovery.
-- `castStatus(snapshot)`: what each device and group is doing, for a caller choosing where to play something. `state` is `idle`, `restorable` (the Default Media Receiver, which `announce` puts back), `busy` (another app, playing or paused: an announce ends it) or `offline` (not connected, or not heard from yet); with the app, title, artist, volume, `via` (the group whose media a member is playing), `standby`, and a group's `members`. A group is as free as its least free connected member.
-- `castFree(snapshot, targets)`: the targets an announcement would not disturb, as names for `announceAll`, and `skipped` with why (`busy`, `offline`, `standby`, `unknown`). A TV in standby is skipped, since a clip may wake it. A group stays a group while every connected member is free; one playing another app is skipped whole; otherwise a group with a busy member becomes its free members one by one (they then play out of step). A device is never named beside a free group that holds it. Both functions are pure, over the snapshot, and tested on built snapshots only: what a group's members report while it plays Spotify hasn't been checked live.
+- `castStatus(state)`: what each device and group is doing, for a caller choosing where to play something. `state` is `idle`, `restorable` (the Default Media Receiver, which `announce` puts back), `busy` (another app, playing or paused: an announce ends it) or `offline` (not connected, or not heard from yet); with the app, title, artist, volume, `via` (the group whose media a member is playing), `standby`, and a group's `members`. A group is as free as its least free connected member.
+- `castFree(state, targets)`: the targets an announcement would not disturb, as names for `announceAll`, and `skipped` with why (`busy`, `offline`, `standby`, `unknown`, `form`). With `{ forms: ["speaker", "display"] }` a TV, or a model whose form isn't known, is skipped as `form`, and a group holding one becomes its other free members. A TV in standby is skipped, since a clip may wake it. A group stays a group while every connected member is free; one playing another app is skipped whole; otherwise a group with a busy member becomes its free members one by one (they then play out of step). A device is never named beside a free group that holds it. Both functions are pure, over the snapshot, and tested on built snapshots only: what a group's members report while it plays Spotify hasn't been checked live.
 - Writes, on the object `cast()` returns (`CastActions`), over the sockets it already holds, never a second connection. A target is a name (any case) or a castId; volume is 0 to 1, as the snapshot's. `setVolume`, `setMuted` (receiver `SET_VOLUME`; a group's goes to the group's socket; per device, levels and mutes each at most 30 a minute, the newest waiting one winning; one device's lane never waits on another's) and `stop` (receiver `STOP` of the running app; nothing when idle). Each request waits 10 s for its reply and a refusal (`LAUNCH_ERROR`, `LOAD_FAILED`, …) rejects, naming it.
+- `castFreeSpeakers(state)`: the one call for "where can I announce now": `castFree` over every device and group, with `forms: ["speaker", "display"]`. Read live 2026-11-11 (Bun 1.4.4, reads only): 8 devices and groups gave one free group of four, with two TVs and a device whose model was not known skipped as `form`.
 - `announce(target, clip, { volume?, timeoutMs? })`: `clip` is `{ url, type? }` or `{ bytes, type }`, bytes served through `serve` (`serveClip` from `@khalido/home/cast/serve`, passed to `cast()`). It reads the receiver status (and a Default Media Receiver's media status), for a group re-runs discovery first and reconnects if the leader moved, sets the volume if given and unmutes a muted target (as two requests: a `SET_VOLUME` takes a level or a mute, not both), launches the Default Media Receiver (`CC1AD845`), `LOAD`s the clip and waits for its media session to go `IDLE` with `FINISHED` (60 s plus the clip's length when the device reports it, or `timeoutMs`). Then, always: what the Default Media Receiver was playing is loaded again at its `currentTime`, an idle device gets `STOP`, then the volume and mute (a group's its own level first, then member by member, through each member's own socket, from the group's multizone status). Another app (Spotify, YouTube) is interrupted, as Google's own announcements do, and the result names it in `notRestored`. It returns `{ played, why?, restored, notRestored }` and throws only before anything changed (an unknown target, a socket down). A clip gets 15 s to reach `PLAYING`, then the name of its type goes in the failure, since a device that can't play it took 35-44 s to say so; a receiver error sooner carries its reason and code. `timeoutMs` replaces both waits. `announceAll(targets, clip, options)` does several at once, one result per device, an unreachable target its own `played: false`; a group and one of its members would clash, untried.
 - `serveClip(bytes, type, { host?, signal? })` (`node:http`, Node-only like `tls.ts`): an address of this machine on the target's network (else the first non-internal IPv4), a random port and an unguessable path, `Content-Type` and `Content-Length`; the whole body to every GET and HEAD (a `Range` probe gets a full 200, which HTTP allows), so a player that probes before it fetches still gets the clip. It closes on `close()`, which `announce` calls once the clip has played, when `signal` aborts, or after 60 s. Not yet seen live: how the Default Media Receiver fetches, and the macOS local-network prompt the first serve may raise.
 - CLI: `home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100]`, `home cast volume <name> <0-100>`, `home cast mute <name> on|off`, `home cast stop <name>`. `--say` runs `say -o <tmp>.m4a --file-format=m4af --data-format=aac` (without the data format, m4af holds uncompressed PCM), serves it as `audio/mp4` and deletes the file. The library never runs `say`.
@@ -31,7 +32,9 @@ CastV2 is TLS to port 8009 (a group: its own port), carrying length-prefixed pro
 - Media status first seen live 2026-11-09 (Bun 1.4.4): a paused title and artist on a TV.
 - **First announcements, 2026-11-09, from a Pi on 0.1.1.** MP3 played on two audio-only speakers and two displays, 7-8 s each, the clip fetched from the Pi's LAN address, idle and volume restored. A 24 kHz mono WAV played on the displays and failed on both audio-only speakers, "the clip stopped: ERROR" after 35-44 s. One WAV format tried: use MP3 or AAC.
 - **On 0.1.2, 2026-11-10, from the Pi (Bun 1.4.4; chota-bot's session, KO listening).** MP3 at volume 30 on one audio-only speaker: played and restored in 2 s. To a group of four: played in 9.5 s, each member back at its own level. `setVolume` and `setMuted` on one speaker read back as set. Over Spotify playing on the speaker: played, the volume restored, Spotify listed in `notRestored`, and KO had to pick the speaker again in the Spotify app.
-- **A group's own level was not restored** (same run; fixed after 0.1.2, untried live): after the group announce at 30 the group read 30 (it had been 53) though every member was back; setting the group to 53 afterwards did not move the members. `restoreVolume` restored members only; since fixed: the group's own level goes back first, then each member's. Untried live.
+- **A group's own level was not restored** (same run; fixed in 0.1.3, confirmed below): after the group announce at 30 the group read 30 (it had been 53) though every member was back; setting the group to 53 afterwards did not move the members. `restoreVolume` restored members only; fixed in 0.1.3: the group's own level goes back first, then each member's.
+- **From a Mac, 2026-11-11 (Bun 1.4.4).** `home cast announce --to <a Nest Hub> --say … --volume 40`: played, idle and volume restored, 6 s in all; KO heard it.
+- **On 0.1.3, 2026-11-11, from the Pi (Bun 1.4.4; chota-bot's session).** A group announce at volume 30: played, and the group and all four members read their earlier levels straight after and 10 s later. With Spotify cast to the group of four: every member read the group's track "via" the group at its own level, `castStatus` gave each member and the group `busy`, and `castFree` over every target left only the idle TV free. So what `castFree` assumes members report is what they report. `castFree` over every target at idle: the group and an idle TV free, a TV with Spotify paused skipped as busy, a device not in discovery skipped as unknown.
 - Not seen yet: `stop`, an announce over a Default Media Receiver stream, `announceAll`, a leader change, member changes, and Node's `tls` (no Node caller yet).
 
 ## TLS: verification off, the name checked

package/src/connectors/cast/index.ts

@@ -37,7 +37,13 @@ import {
 } from "./writes.ts";
 
 export type { CastConnect } from "./codec.ts";
-export { castDevices, castForm, castFree, castStatus } from "./state.ts";
+export {
+  castDevices,
+  castForm,
+  castFree,
+  castFreeSpeakers,
+  castStatus,
+} from "./state.ts";
 export type {
   CastDevice,
   CastForm,

package/src/connectors/cast/state.ts

@@ -325,10 +325,10 @@ export function castStatus(s: CastSnapshot): CastStatus[] {
   return castDevices(s).map(one);
 }
 
-/** A target `castFree` left out: `standby` is a TV that is off, which a clip may wake. */
+/** A target `castFree` left out: `standby` is a TV that is off, which a clip may wake; `form` is one whose form wasn't asked for. */
 export type CastSkipped = {
   name: string;
-  why: "busy" | "offline" | "standby" | "unknown";
+  why: "busy" | "offline" | "standby" | "unknown" | "form";
   app?: string;
 };
 
@@ -340,11 +340,21 @@ export type CastSkipped = {
  *   becomes its free members, named one by one (they then play out of step with each other).
  * - A device is never named beside a free group that holds it, nor two groups that share a member: the second becomes its
  *   members not yet covered.
+ * - With `forms` (`["speaker", "display"]` keeps an announcement off TVs), a device of another form, or of a model this
+ *   library doesn't know, is skipped with `why: "form"`, and a group holding one (or a member the snapshot doesn't have)
+ *   becomes its other free members. An empty list leaves every device out.
  */
 export function castFree(
   s: CastSnapshot,
   targets: string[],
+  options: { forms?: readonly CastForm[] } = {},
 ): { free: string[]; skipped: CastSkipped[] } {
+  /** A device of a form asked for. A group has no form of its own: its members decide. */
+  const wanted = (id: string) => {
+    const d = s.devices[id];
+    if (!options.forms || d?.kind === "group") return true;
+    return d?.form !== undefined && options.forms.includes(d.form);
+  };
   const status = new Map(castStatus(s).map((c) => [c.id, c]));
   const free = new Map<string, CastStatus>();
   const covered = new Set<string>(); // members of the groups in `free`
@@ -354,15 +364,17 @@ export function castFree(
   const skip = (c: CastStatus) =>
     skipped.set(c.id, {
       name: c.name,
-      why:
-        c.state === "offline"
+      why: !wanted(c.id)
+        ? "form"
+        : c.state === "offline"
           ? "offline"
           : c.standby && c.state !== "busy"
             ? "standby"
             : "busy",
       ...(c.app ? { app: c.app } : {}),
     });
-  const device = (c: CastStatus) => (ok(c) ? free.set(c.id, c) : skip(c));
+  const device = (c: CastStatus) =>
+    ok(c) && wanted(c.id) ? free.set(c.id, c) : skip(c);
   for (const target of targets) {
     const d = findCast(s.devices, target);
     const c = d && status.get(d.id);
@@ -376,6 +388,7 @@ export function castFree(
       else if (
         own !== "offline" &&
         up.every(ok) &&
+        (d.members ?? []).every(wanted) &&
         !members.some((m) => covered.has(m.id))
       ) {
         free.set(c.id, c);
@@ -390,3 +403,17 @@ export function castFree(
     skipped: [...skipped.values()],
   };
 }
+
+/**
+ * Where an announcement can play right now, in one call: every speaker and display that is free, a whole group where all
+ * of it is, and never a TV. `castFree` over everything Cast has found, with `forms: ["speaker", "display"]`; `free` goes
+ * straight to `announceAll`.
+ */
+export const castFreeSpeakers = (
+  s: CastSnapshot,
+): { free: string[]; skipped: CastSkipped[] } =>
+  castFree(
+    s,
+    castDevices(s).map((d) => d.id),
+    { forms: ["speaker", "display"] },
+  );

package/src/connectors/daikin/README.md

@@ -2,9 +2,9 @@
 
 Reads one Daikin AC over its local JSON `dsiot` API. `iot_class`: **local_polling**. KO's unit is a Daikin Australia **Alira X** with built-in Wi-Fi (likely; it reports a blank model string).
 
-- `client.ts`: `daikinClient({ host, fetch }).read()` returns `DaikinState` (power, mode, the selected mode's setpoint and fan speed, room °C, humidity, outside °C, `anomaly`). `setPower`, `setMode`, `setTarget`, `setFan` build write requests; `client.write(request)` sends one, through a write lane: 1 s apart and at most 20 a minute (guesses), a waiting write merging the next one field by field (`mergeWrites`). Every request times out at 10 s.
-- `index.ts`: `daikin({ host, fetch, clock })` reads now, then every **120 s** (Home Assistant's `update_interval`). A failed poll is `disconnected` and keeps the last reading with `asOf`; a 404 on `/dsiot/multireq` is a failed read too, saying "not a dsiot Daikin": the address may now be another device's, so discovery looks for the unit. There is no key, so nothing is terminal. Writes go through `daikin().client.write(…)`: one client for the integration's life, at the unit's current address.
-- `home status` reads `DAIKIN_HOST`, or a home config's address, with discovery by `mac` if the unit moves. There is no CLI command that writes.
+- `client.ts`: `daikinClient({ host, fetch }).read()` returns `DaikinState` (power, mode, the selected mode's setpoint and fan speed, room °C, humidity, outside °C, `anomaly`). **`power(on)` and `mode(mode, targetC?)` are the writes most callers want.** `mode` selects the mode, turns the unit on and sets the setpoint in one request: the one given, else the library's default (`DEFAULT_TARGET_C`: cool 25, heat 27), else (auto) the unit's own; dry and fan take none. Both resolve with `{ state, confirmed }`: the unit read once a second until it reports what was asked, at most 5 s (`CONFIRM_MS`); unconfirmed is a result, not an error. A setpoint off the unit's range or a half degree throws before anything is sent. `setPower`, `setMode`, `setTarget`, `setFan` build write requests; `client.write(request)` sends one, through a write lane: 1 s apart and at most 20 a minute (guesses), a waiting write merging the next one field by field (`mergeWrites`). Every request times out at 10 s.
+- `index.ts`: `daikin({ host, fetch, clock })` reads now, then every **120 s** (Home Assistant's `update_interval`). A failed poll is `disconnected` and keeps the last reading with `asOf`; a 404 on `/dsiot/multireq` is a failed read too, saying "not a dsiot Daikin": the address may now be another device's, so discovery looks for the unit. There is no key, so nothing is terminal. Writes go through `daikin().client` (`power`, `mode`, or `write` for a built request): one client for the integration's life, at the unit's current address.
+- `home status` and `home daikin` read `DAIKIN_HOST`, or a home config's address (with discovery by `mac` if the unit moves); with neither, they take the first unit to answer the UDP broadcast, which adds 1.5 s. The broadcast goes out three times in that window: a single one missed KO's unit in 2 runs of 3 while mDNS searches ran beside it (2026-11-11); three found it 6 of 6. `home daikin on | off` and `home daikin cool | heat | auto [°C] | dry | fan` are the CLI writes, at `DAIKIN_HOST` or the first unit to answer the UDP broadcast, printing what the unit then reports.
 
 ## The protocol
 
@@ -39,7 +39,7 @@ One read-only request, saved with the MAC, SSID, `edid` and the unit's ASCII ids
 ## Unconfirmed
 
 - **The write lane's rates** (1 s apart, 20 a minute) are guesses. One client lives as long as the integration and reads the unit's address at each send, so a move keeps the lane's count, and a write still waiting goes to the new address.
-- **Writes other than power.** Only `setPower(true)` has been sent to KO's unit (2026-10-16, Bun 1.4.3, see below); mode, setpoint and fan writes are untried. The encodings come from pydaikin, which reports verified live writes on other BRP084 units. The two sources disagree in three places, plus one choice of our own, settled here as follows:
+- **Writes other than power.** Only `setPower(true)` has been sent to KO's unit (2026-10-16 and 2026-11-11, see below); dry to cool at 25 °C worked (2026-11-11, below); heat, auto, fan mode and fan-speed writes are untried. The encodings come from pydaikin, which reports verified live writes on other BRP084 units. The two sources disagree in three places, plus one choice of our own, settled here as follows:
   - Setpoint width: pydaikin sends one byte, Alira two (`3200`). One byte, because the live field is one byte (`p_02` `mi 24`, `mx 40`).
   - Method: pydaikin POSTs, Alira PUTs. POST, the method reads already use.
   - Field: Alira always writes `p_03` and `p_0A`. Those are pydaikin's heat-mode setpoint and fan, and Alira reads by list position (its `[2]` and `[8]` are `p_03` and `p_0A`), so it appears written on a unit in heat. Per-mode fields here.
@@ -63,10 +63,22 @@ All setpoint and fan fields, read from `e_3001` with `md` (setpoint is one byte,
 
 Unmapped and unread: `p_27` (`0A00`, like auto), `p_34` (one signed byte, `00`, `mi FA`, `mx 00`), and the `p_05`–`p_08`, `p_20`–`p_25` fields (3- and 4-byte values, mostly `0F…`, likely schedules or limits). Meaning unknown.
 
+## Second write (2026-11-11)
+
+`setPower(true)` at KO's request, through `daikinClient().write` and the rewritten write lane (Bun 1.4.4, from a Mac): accepted in 280 ms, and reads at once, 2 s and 5 s later all showed `on` (before: off, dry, room 25 °C). The unit was found by the UDP broadcast. Then `setMode("dry")` at KO's request: accepted in 291 ms and the unit read `on`, dry. It was already in dry, so this shows the write is accepted, not that a mode changes. `home daikin on` on the running unit printed its line and exited 0. `home probe` shows 404 on the three old `/common` and `/aircon` paths and an answer on `dsiot`, as expected for this unit.
+
+## First mode change and setpoint (2026-11-11)
+
+`home daikin cool` at KO's request, the unit on in dry (Bun 1.4.4): one request with power, mode and the default setpoint; the command took 3.3 s in all, 1.5 s of it the UDP search, and printed `on · cool 25 °C`. A read some 15 s later showed the same, fan 3. So `mode` with a setpoint works on this unit, and the unit reports the change within the confirm wait. Still untried: heat, auto, fan mode, a fan-speed write, and `power(false)`.
+
 ## Read from a Pi (2026-11-10)
 
 `home daikin` on 0.1.2 (Bun 1.4.4; chota-bot's session): "connected · off · dry · room 26 °C · outdoor unit 28 °C". `home discover` found the unit by UDP. No write was sent.
 
+## Dry run (2026-11-12)
+
+`power` and `mode` take `{ dryRun: true }`: the checks, one read, and `wouldSend` with what it would set; nothing sent. `home daikin cool --dry-run` and `heat --dry-run` on KO's unit (Bun 1.4.4) read it and printed 25 and 27; the unit stayed off.
+
 ## Sources
 
 Both Daikin protocol sources are GPL-3.0, so they are read for facts only (endpoints, field paths, value maps) and no code is copied; that keeps this package MIT.

package/src/connectors/daikin/client.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { Clock } from "../../clock.ts";
+import { type Clock, realClock } from "../../clock.ts";
 import { ConnectorError, getJson } from "../../connector.ts";
 import { writeLane } from "../../lane.ts";
 
@@ -81,6 +81,37 @@ const TARGET_RANGE: Partial<Record<Mode, [number, number]>> = {
   auto: [18, 30],
 };
 
+/**
+ * The setpoint a mode gets when the caller names none: this library's opinion (KO's: not too cold, properly warm).
+ * Without one, "cool" would mean whatever the remote last left. Auto keeps the unit's own.
+ */
+export const DEFAULT_TARGET_C = {
+  cool: 25,
+  heat: 27,
+} as const satisfies Partial<Record<Mode, number>>;
+
+/**
+ * What a write left: the state once the unit reported the change (`confirmed`), or as it stood when `CONFIRM_MS` ran out
+ * without it. With `{ dryRun: true }` nothing is sent: `wouldSend` is the request and what it sets, `state` the unit as it
+ * reads now, and `confirmed` is false. Check `wouldSend` first.
+ */
+export type DaikinApplied = {
+  state: DaikinState;
+  confirmed: boolean;
+  wouldSend?: DaikinRequest;
+};
+/** One write: `POST /dsiot/multireq` with `body`; `sets` is what it changes, in this library's words. */
+export type DaikinRequest = {
+  method: "POST";
+  path: "/dsiot/multireq";
+  body: WriteRequest;
+  sets: { on?: boolean; mode?: Mode; targetC?: number };
+};
+/** `dryRun`: every check a write makes (the mode, the setpoint's range), one read for the state, and nothing sent. */
+export type DaikinWriteOptions = { dryRun?: boolean };
+/** How long `power` and `mode` wait for the unit to report what was asked, reading once a second. */
+export const CONFIRM_MS = 5000;
+
 /** Little-endian hex to an integer, two's complement when `signed`: "2700" → 39, "EEFF" → -18. */
 export function hexLE(hex: string, signed = false): number | undefined {
   if (!/^(?:[0-9a-f]{2})+$/i.test(hex)) return undefined;
@@ -229,7 +260,7 @@ export function setFan(fan: Fan, mode: Mode): WriteRequest {
   return write([["e_3001", FAN[mode]!, key(FANS, fan)]]);
 }
 
-/** A client for one unit. Reads are op 2; `write` sends a body built by setPower, setMode, setTarget or setFan. */
+/** A client for one unit. Reads are op 2. `power` and `mode` are the writes most callers want; `write` sends any body built by setPower, setMode, setTarget or setFan. */
 export function daikinClient(options: {
   host: string;
   fetch: typeof fetch;
@@ -251,7 +282,8 @@ export function daikinClient(options: {
       schema: Multi,
       error: DaikinError,
     });
-  return {
+  const clock = options.clock ?? realClock;
+  const client = {
     /** The indoor and outdoor status in one request. A failed outdoor read leaves `outsideC` empty. */
     async read(signal?: AbortSignal): Promise<DaikinState> {
       const m = await multireq(
@@ -292,4 +324,73 @@ export function daikinClient(options: {
       );
     },
   };
+  /** Send `request`, then read once a second until the unit reports `asked` or `CONFIRM_MS` passes. Rejects if the write is refused, or if no read after it succeeds. */
+  async function apply(
+    request: WriteRequest,
+    sets: DaikinRequest["sets"],
+    asked: (s: DaikinState) => boolean,
+    options: DaikinWriteOptions | undefined,
+  ): Promise<DaikinApplied> {
+    if (options?.dryRun)
+      return {
+        state: await client.read(),
+        confirmed: false,
+        wouldSend: {
+          method: "POST",
+          path: "/dsiot/multireq",
+          body: request,
+          sets,
+        },
+      };
+    await client.write(request);
+    const until = clock.now() + CONFIRM_MS;
+    let state: DaikinState | undefined;
+    let failed: unknown;
+    // The write was accepted, so one dropped read must not turn it into a failure: keep reading until the time is up.
+    for (;;) {
+      try {
+        state = await client.read();
+        if (asked(state)) break;
+      } catch (error) {
+        failed = error;
+      }
+      if (clock.now() >= until) break;
+      await clock.sleep(1000);
+    }
+    if (!state) throw failed; // sent, but the unit answered no read since: nothing to report
+    return { state, confirmed: asked(state) };
+  }
+  return {
+    ...client,
+    /** Turn the unit on or off, as it was last left. Only when a person asks. Resolves with what the unit then reported. */
+    power: (
+      on: boolean,
+      options?: DaikinWriteOptions,
+    ): Promise<DaikinApplied> =>
+      apply(setPower(on), { on }, (s) => s.on === on, options),
+    /**
+     * Select a mode, turn the unit on and set its setpoint, in one request: `targetC`, else `DEFAULT_TARGET_C` (cool 25,
+     * heat 27), else (auto) the unit's own. Dry and fan take none, and a `targetC` for them throws before anything is
+     * sent, as one off the unit's range does. Only when a person asks. Resolves with what the unit then reported.
+     */
+    async mode(
+      mode: Mode,
+      targetC?: number,
+      options?: DaikinWriteOptions,
+    ): Promise<DaikinApplied> {
+      const c =
+        targetC ?? (DEFAULT_TARGET_C as Partial<Record<Mode, number>>)[mode];
+      return apply(
+        c === undefined
+          ? setMode(mode)
+          : mergeWrites(setMode(mode), setTarget(c, mode)),
+        { on: true, mode, ...(c === undefined ? {} : { targetC: c }) },
+        (s) =>
+          s.on === true &&
+          s.mode === mode &&
+          (c === undefined || s.targetC === c),
+        options,
+      );
+    },
+  };
 }

package/src/connectors/daikin/index.ts

@@ -17,8 +17,13 @@ import {
 } from "./client.ts";
 
 export {
+  CONFIRM_MS,
+  type DaikinApplied,
+  type DaikinRequest,
+  type DaikinWriteOptions,
   DaikinError,
   type DaikinState,
+  DEFAULT_TARGET_C,
   daikinClient,
   type Fan,
   type Mode,
@@ -60,7 +65,7 @@ export type DaikinSnapshot = DaikinState & { asOf: string };
 export type DaikinClient = ReturnType<typeof daikinClient>;
 
 /**
- * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.write(setPower(true))`: one
+ * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.power(on)` and `client.mode(mode, targetC?)`: one
  * client for the integration's life, so the writes share its lane and follow the unit when it moves.
  */
 export function daikin(
@@ -148,7 +153,8 @@ export const manifest: Manifest<DaikinSnapshot> = {
     {
       name: "DAIKIN_HOST",
       example: "192.0.2.20",
-      what: "the unit's address; `home probe` finds it by UDP broadcast",
+      optional: true,
+      what: "the unit's address; found by UDP broadcast when unset (1.5 s a run)",
     },
   ],
   lines: ({ state }) => (state ? [acText(state)] : []),

package/src/connectors/enphase/README.md

@@ -10,9 +10,11 @@ Reads an IQ Gateway (Envoy) on the LAN: production, consumption and grid flow. `
 - `host` may be pasted with a scheme or a trailing slash (`https://…/`); `gatewayHost` reduces it to the bare host for requests, discovery and the address cache.
 - In the home config the device may carry `marker` (the plan's marker where the array is drawn, on the roof outside any room) and `capacityW` (the array's rated watts from the installer's paperwork, never guessed from the gateway). Neither reaches the gateway; they are for drawing.
 - A meter counts only when `/ivp/meters` says `enabled` **and** its reading has `activeCount > 0`; otherwise production comes from the inverters and Wh today is left out, since pyenphase found the inverter daily total unreliable.
-- The token's days left ride in the snapshot; under 30 the status says to run `home enphase login`. A 401 marks Enphase unavailable and stops polling.
+- The token's days left ride in the snapshot; under 30 the status says to run `home enphase login`. A 401 or 403 marks Enphase unavailable and stops polling.
 - `home enphase login` mints the token (below) and writes `~/.config/home/enphase-token.json` (0600, directory 0700), printing only the days left. `home status` shows solar now, consumption and the token's days left.
 
+**Live, 2026-11-12 (Bun 1.4.4).** From late October `home enphase` said ECONNREFUSED. The gateway had not changed: DHCP had given it a new address, mDNS and the address cache had the new one, and an `IQ_GATEWAY_HOST` in the shell still named the old one, which the CLI trusted without a fallback. The CLI now takes the serial from the address cache and runs discovery after one failed read, so the status line reads and says "moved from a to b". The owner token was fine throughout (338 days left).
+
 **Live, KO's gateway, 2026-10-13 (D8.3.5528, owner token).** `/info` answers without a token; everything else answers 401 without one. With the token, one GET each:
 
 - `/ivp/meters`: `production` and `net-consumption` **enabled**, `meteringStatus normal`; `storage`, `backfeed`, `load`, `evse`, `pv3p` disabled. So both CTs are fitted.

package/src/connectors/enphase/client.ts

@@ -8,7 +8,7 @@ import {
   type Measurement,
 } from "./schemas.ts";
 
-/** A failed Enphase call. `status` 401 means the token is wrong or expired. */
+/** A failed Enphase call. `status` 401 or 403 (`isRejectedKey`) means the token is wrong or expired. */
 export class EnphaseError extends ConnectorError {}
 
 /** Solar right now and today. Watts and watt-hours as the gateway reports them, negatives included. */