@khalido/home 0.0.0-stage → 0.1.0

package/src/connectors/daikin/client.ts

@@ -0,0 +1,295 @@
+import { z } from "zod";
+import type { Clock } from "../../clock.ts";
+import { ConnectorError, getJson } from "../../connector.ts";
+import { writeLane } from "../../lane.ts";
+
+// Daikin's JSON dsiot API (the BRP084 family): POST /dsiot/multireq, plain HTTP, no key. Field paths and value
+// maps are protocol facts from pydaikin (GPL-3.0, read only; see README.md), checked against KO's unit 2026-10-13.
+
+/** A failed Daikin call. `status` is the HTTP status, or the dsiot `rsc` when HTTP succeeded. */
+export class DaikinError extends ConnectorError {}
+
+export type Mode = "auto" | "cool" | "heat" | "fan" | "dry";
+export type Fan = "1" | "2" | "3" | "4" | "5" | "auto" | "quiet";
+
+/** The AC now. Temperatures in °C as the unit reports them. */
+export type DaikinState = {
+  on?: boolean;
+  mode?: Mode; // the selected mode, kept while the unit is off
+  targetC?: number; // the setpoint of the selected mode; none in fan or dry
+  roomC?: number;
+  humidity?: number; // percent
+  fan?: Fan; // the fan speed of the selected mode; none in dry
+  outsideC?: number;
+  anomaly?: string; // a code or value the maps here do not know, kept visible rather than guessed
+};
+
+type Node = { pn?: string; pv?: unknown; pch?: Node[] };
+const Node: z.ZodType<Node> = z.looseObject({
+  pn: z.string().optional(),
+  pv: z.unknown().optional(),
+  get pch() {
+    return z.array(Node).optional();
+  },
+});
+const Multi = z.looseObject({
+  responses: z.array(
+    z.looseObject({
+      fr: z.string().optional(),
+      rsc: z.number().optional(),
+      pc: Node.optional(),
+    }),
+  ),
+});
+type Multi = z.infer<typeof Multi>;
+
+const INDOOR = "/dsiot/edge/adr_0100.dgc_status";
+const OUTDOOR = "/dsiot/edge/adr_0200.dgc_status";
+
+const MODES: Record<string, Mode> = {
+  "0000": "fan",
+  "0100": "heat",
+  "0200": "cool",
+  "0300": "auto",
+  "0500": "dry",
+};
+const FANS: Record<string, Fan> = {
+  "0300": "1",
+  "0400": "2",
+  "0500": "3",
+  "0600": "4",
+  "0700": "5",
+  "0A00": "auto",
+  "0B00": "quiet",
+};
+/** Each mode keeps its own setpoint and fan speed under `e_3001`. */
+const TARGET: Partial<Record<Mode, string>> = {
+  cool: "p_02",
+  heat: "p_03",
+  auto: "p_1D",
+};
+const FAN: Partial<Record<Mode, string>> = {
+  cool: "p_09",
+  heat: "p_0A",
+  auto: "p_26",
+  fan: "p_28",
+};
+/** The setpoint range per mode, from the unit's own `md.mi`/`md.mx` (KO's unit, 2026-10-13). */
+const TARGET_RANGE: Partial<Record<Mode, [number, number]>> = {
+  cool: [18, 32],
+  heat: [10, 30],
+  auto: [18, 30],
+};
+
+/** 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;
+  const bytes = hex.match(/../g)!.reverse().join("");
+  const n = Number.parseInt(bytes, 16);
+  return signed && n >= 2 ** (hex.length * 4 - 1)
+    ? n - 2 ** (hex.length * 4)
+    : n;
+}
+
+/** The `pv` at a path of `pn` names under one response's tree, by name (never by position). */
+function value(m: Multi, fr: string, path: string[]): string | undefined {
+  let node = m.responses.find((r) => r.fr === fr)?.pc;
+  for (const pn of path) node = node?.pch?.find((c) => c.pn === pn);
+  return typeof node?.pv === "string" ? node.pv : undefined;
+}
+
+/** Map the indoor and outdoor `dgc_status` trees to a state. Unknown codes go to `anomaly`, never to a guess. */
+export function toState(response: unknown): DaikinState {
+  const m = Multi.parse(response);
+  const odd: string[] = [];
+  const indoor = (...path: string[]) => value(m, INDOOR, ["e_1002", ...path]);
+  const code = <T>(
+    map: Record<string, T>,
+    hex: string | undefined,
+    what: string,
+  ) => {
+    if (hex !== undefined && !(hex in map))
+      odd.push(`unknown ${what} code ${hex}`);
+    return hex === undefined ? undefined : map[hex];
+  };
+  const temp = (hex: string | undefined, divisor: number, what: string) => {
+    if (hex === undefined) return undefined;
+    const n = hexLE(hex, true);
+    if (n === undefined) odd.push(`${what} is not hex: ${hex}`);
+    return n === undefined ? undefined : n / divisor;
+  };
+  const power = indoor("e_A002", "p_01");
+  if (power !== undefined && power !== "00" && power !== "01")
+    odd.push(`unknown power code ${power}`);
+  const mode = code(MODES, indoor("e_3001", "p_01"), "mode");
+  const target = mode && TARGET[mode];
+  const fan = mode && FAN[mode];
+  const humidityHex = indoor("e_A00B", "p_02");
+  const humidity = humidityHex === undefined ? undefined : hexLE(humidityHex);
+  if (humidityHex !== undefined && humidity === undefined)
+    odd.push(`humidity is not hex: ${humidityHex}`);
+  return {
+    on: power === "01" ? true : power === "00" ? false : undefined,
+    mode,
+    targetC: target ? temp(indoor("e_3001", target), 2, "target") : undefined,
+    roomC: temp(indoor("e_A00B", "p_01"), 1, "room temperature"),
+    humidity,
+    fan: fan ? code(FANS, indoor("e_3001", fan), "fan") : undefined,
+    outsideC: temp(
+      value(m, OUTDOOR, ["e_1003", "e_A00D", "p_01"]),
+      2,
+      "outside temperature",
+    ),
+    anomaly: odd.length ? odd.join("; ") : undefined,
+  };
+}
+
+/** A multireq body that writes one or more `e_1002` fields of the indoor unit (op 3), merged into one tree. */
+export type WriteRequest = { requests: { op: 3; to: string; pc: Node }[] };
+const write = (
+  fields: [entity: string, pn: string, pv: string][],
+): WriteRequest => ({
+  requests: [
+    {
+      op: 3,
+      to: INDOOR,
+      pc: {
+        pn: "dgc_status",
+        pch: [
+          {
+            pn: "e_1002",
+            pch: fields.map(([e, pn, pv]) => ({ pn: e, pch: [{ pn, pv }] })),
+          },
+        ],
+      },
+    },
+  ],
+});
+const fields = (r: WriteRequest): [string, string, string][] =>
+  r.requests.flatMap((q) =>
+    (q.pc.pch ?? []).flatMap((e1002) =>
+      (e1002.pch ?? []).flatMap((e) =>
+        (e.pch ?? []).map((f): [string, string, string] => [
+          e.pn!,
+          f.pn!,
+          String(f.pv),
+        ]),
+      ),
+    ),
+  );
+
+/** Two writes as one, field by field, the newer value winning: `setMode("cool")` then `setPower(false)` sends mode cool, power off. */
+export function mergeWrites(
+  older: WriteRequest,
+  newer: WriteRequest,
+): WriteRequest {
+  const merged = new Map(fields(older).map((f) => [`${f[0]}/${f[1]}`, f]));
+  for (const f of fields(newer)) merged.set(`${f[0]}/${f[1]}`, f);
+  return write([...merged.values()]);
+}
+
+/** Writes to the unit at most this often, and at most `WRITE_PER_MINUTE` a minute; a guess, the BRP084's limits are unpublished. */
+export const WRITE_GAP_MS = 1000;
+export const WRITE_PER_MINUTE = 20;
+
+const key = <T>(map: Record<string, T>, v: T) =>
+  Object.keys(map).find((k) => map[k] === v)!;
+
+/** Turn the unit on or off. */
+export const setPower = (on: boolean) =>
+  write([["e_A002", "p_01", on ? "01" : "00"]]);
+
+/** Select a mode and turn the unit on, as pydaikin and the Alira integration both do. */
+export const setMode = (mode: Mode) =>
+  write([
+    ["e_A002", "p_01", "01"],
+    ["e_3001", "p_01", key(MODES, mode)],
+  ]);
+
+/** Set the setpoint of `mode` (usually the current one), one byte of °C × 2. Throws off the unit's range or 0.5 steps; never rounds. */
+export function setTarget(c: number, mode: Mode): WriteRequest {
+  const range = TARGET_RANGE[mode];
+  if (!range) throw new DaikinError(`${mode} mode has no setpoint`);
+  if (!Number.isInteger(c * 2) || c < range[0] || c > range[1])
+    throw new DaikinError(
+      `${c} °C is not a ${mode} setpoint (${range[0]}–${range[1]} in 0.5 steps)`,
+    );
+  return write([
+    [
+      "e_3001",
+      TARGET[mode]!,
+      (c * 2).toString(16).toUpperCase().padStart(2, "0"),
+    ],
+  ]);
+}
+
+/** Set the fan speed of `mode` (usually the current one). */
+export function setFan(fan: Fan, mode: Mode): WriteRequest {
+  if (!FAN[mode]) throw new DaikinError(`${mode} mode has no fan speed`);
+  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. */
+export function daikinClient(options: {
+  host: string;
+  fetch: typeof fetch;
+  clock?: Clock;
+}) {
+  const lane = writeLane({
+    gapMs: WRITE_GAP_MS,
+    perMinute: WRITE_PER_MINUTE,
+    clock: options.clock,
+  });
+  const multireq = (body: unknown, signal?: AbortSignal): Promise<Multi> =>
+    getJson(options.fetch, `http://${options.host}/dsiot/multireq`, {
+      init: {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      },
+      signal,
+      schema: Multi,
+      error: DaikinError,
+    });
+  return {
+    /** 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(
+        {
+          requests: [INDOOR, OUTDOOR].map((to) => ({
+            op: 2,
+            to: `${to}?filter=pv,pt,md`,
+          })),
+        },
+        signal,
+      );
+      const indoor = m.responses.find((r) => r.fr === INDOOR);
+      if (indoor?.rsc !== 2000)
+        throw new DaikinError(`no indoor status (rsc ${indoor?.rsc})`, {
+          status: indoor?.rsc,
+        });
+      return toState(m);
+    },
+    /**
+     * Send a write. Only when KO asks: this changes the AC. Needs an answer for the indoor unit below 4000 (success codes
+     * unconfirmed; re-read to be sure). Writes waiting their turn merge (`mergeWrites`) and resolve with the send that carried them.
+     */
+    write(request: WriteRequest): Promise<void> {
+      return lane.send(
+        "unit",
+        request,
+        async (r) => {
+          const answer = (await multireq(r)).responses.find(
+            (x) => x.fr === INDOOR,
+          );
+          if (!answer || answer.rsc === undefined || answer.rsc >= 4000)
+            throw new DaikinError(
+              `no accepted answer from the indoor unit (rsc ${answer?.rsc})`,
+              { status: answer?.rsc },
+            );
+        },
+        mergeWrites,
+      );
+    },
+  };
+}

package/src/connectors/daikin/index.ts

@@ -0,0 +1,145 @@
+import { asOf, type Clock, realClock } from "../../clock.ts";
+import { z } from "zod";
+import type { Integration } from "../../home.ts";
+import { type Finder, lostDetail, relocator } from "../../discover.ts";
+import type { Manifest } from "../../manifest.ts";
+import { poller } from "../../poll.ts";
+import { daikinClient, DaikinError, type DaikinState } from "./client.ts";
+
+export {
+  DaikinError,
+  type DaikinState,
+  daikinClient,
+  type Fan,
+  type Mode,
+  setFan,
+  setMode,
+  setPower,
+  setTarget,
+  type WriteRequest,
+} from "./client.ts";
+
+/** Poll every 120 s, as Home Assistant's daikin integration does (its coordinator's update_interval). */
+export const POLL_MS = 120_000;
+
+/** A Daikin AC in a home config: its last known address, and the MAC its UDP discovery reports, which is how it is recognised. */
+export const configSchema = z.looseObject({
+  connector: z.literal("daikin"),
+  host: z.string().describe("the unit's last known address"),
+  mac: z
+    .string()
+    .optional()
+    .describe("the unit's MAC as its UDP discovery reports it: its identity"),
+});
+
+/** Daikin settings: its last known address, its MAC and a UDP discovery to find it again if it moves (both optional), and a `fetch`. */
+export type DaikinConfig = {
+  host: string;
+  mac?: string;
+  find?: Finder;
+  fetch: typeof fetch;
+  clock?: Clock;
+  seen?: (host: string) => void;
+  hostCached?: boolean;
+}; // seen: after each good read, for an address cache; hostCached: `host` came from it
+
+/** What the snapshot holds: the latest reading and when it was taken. */
+export type DaikinSnapshot = DaikinState & { asOf: string };
+
+/** What `daikin().client` is: the reads and writes of the unit, at wherever it is now. */
+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
+ * client for the integration's life, so the writes share its lane and follow the unit when it moves.
+ */
+export function daikin(
+  config: DaikinConfig,
+): Integration<DaikinSnapshot, "daikin"> & { readonly client: DaikinClient } {
+  const clock = config.clock ?? realClock;
+  const where = relocator({
+    host: config.host,
+    id: config.mac,
+    find: config.find,
+    clock,
+    cached: config.hostCached,
+  });
+  const client = daikinClient({
+    ...config,
+    get host() {
+      return where.host();
+    },
+  });
+  const poll = poller(clock);
+  return {
+    name: "daikin",
+    client,
+    refresh: () => (where.reset(), poll.nudge()),
+    async run(signal, update) {
+      let last: DaikinSnapshot | undefined;
+      let moved: string | undefined; // kept in `detail` so a consumer can persist the new address
+      while (!signal.aborted) {
+        try {
+          last = { ...(await client.read(signal)), asOf: asOf(clock) };
+          where.ok();
+          config.seen?.(where.host());
+          update({
+            status: "connected",
+            detail: moved,
+            anomaly: last.anomaly,
+            state: last,
+          });
+        } catch (error) {
+          if (signal.aborted) return; // stopped mid-read: not a failure
+          // A 404 is a failed read like any other: the address may now be another device's, so discovery looks for the unit.
+          const why =
+            error instanceof DaikinError && error.status === 404
+              ? "no /dsiot/multireq at this address: not a dsiot Daikin"
+              : error;
+          const r = await where.failed(signal);
+          if (r.moved) {
+            moved = r.moved;
+            continue; // read at the new address now; that read reports, with the move in `detail`
+          }
+          update({
+            status: "disconnected",
+            detail: lostDetail(r, why),
+            state: last,
+          });
+        }
+        await poll.wait(POLL_MS, signal);
+      }
+    },
+  };
+}
+
+/** The AC in a few words: "off · cool 25 °C · room 24 °C · outdoor unit 19.5 °C". */
+export function acText(s: DaikinState): string {
+  const setting = [s.mode, s.targetC === undefined ? "" : `${s.targetC} °C`]
+    .filter(Boolean)
+    .join(" ");
+  return [
+    s.on === undefined ? "" : s.on ? "on" : "off",
+    setting,
+    s.roomC === undefined ? "" : `room ${s.roomC} °C`,
+    s.outsideC === undefined ? "" : `outdoor unit ${s.outsideC} °C`,
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+export const manifest: Manifest<DaikinSnapshot> = {
+  name: "daikin",
+  title: "Daikin",
+  iotClass: "local_polling",
+  pollSeconds: POLL_MS / 1000,
+  access: "local HTTP JSON (dsiot), no key",
+  env: [
+    {
+      name: "DAIKIN_HOST",
+      example: "192.0.2.20",
+      what: "the unit's address; `home probe` finds it by UDP broadcast",
+    },
+  ],
+  lines: ({ state }) => (state ? [acText(state)] : []),
+};

package/src/connectors/enphase/README.md

@@ -0,0 +1,64 @@
+# Enphase
+
+Reads an IQ Gateway (Envoy) on the LAN: production, consumption and grid flow. `iot_class`: **local_polling**, every 60 s. Tried on one metered gateway with microinverters, **software D8.3.5528**, `web-tokens: true` (read 2026-10-13).
+
+## Built
+
+- `enphase({ host, token, fetch: bunGatewayFetch() })` polls every 60 s (the caller chooses the TLS trade-off; see below). With a production meter on, it reads `GET /ivp/meters` and `GET /ivp/meters/readings`, joined by `eid` (`fromReadings`): about 100 ms on KO's gateway, where `/production.json?details=1` takes 1–10 s (measured, Bun 1.4.2) against a 10 s timeout. Production is the production meter's `activePower`; on a net-consumption meter, consumption is production plus net import, and lifetime consumption is production + imported − exported. Both matched `/production.json` live to within a few watts and to the Wh. Without a production meter it falls back to `/production.json` (`toState`).
+- Today is counted by the integration from the lifetime counters, from its first reading of the day (`todaySince`). The day starts at midnight in `timeZone` (the home config's `location.timezone`, an IANA name), the runtime's zone when unset, so a consumer on a UTC server does not reset at 10 am Sydney.
+- Today's peak (`productionWPeakToday`, since `peakSince`) is the highest production the integration has read today, one read a minute, so a short burst between reads is missed. It starts again at the home's midnight, or when the integration starts. A drawing scales the roof's panels by it when the config gives no `capacityW` (`solarLevel` in `src/energy.ts`).
+- `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.
+- `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, 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.
+- `/production.json?details=1`: `production` holds `inverters` (`activeCount`, `wNow`, `whLifetime`, no daily fields) and `eim production` (20 fields); `consumption` holds `eim total-consumption` and `eim net-consumption`; `storage` holds an inactive `acb`. At dusk production was near zero and net consumption matched consumption less production.
+- **Anomaly**: on every `eim` reading, `whToday`, `whLastSevenDays` and `whLifetime` are the same number. The daily counters are broken on this firmware. `toState` drops them and sets `anomaly`; `enphase()` counts today from the lifetime counter from its first reading of the day and marks where that count starts (`todaySince`).
+- `/api/v1/production`: all zeros except `wattHoursLifetime`. Not used.
+- `/ivp/meters/readings`: 8 entries with `eid`, `timestamp`, `actEnergyDlvd`, `actEnergyRcvd`, `instantaneousDemand` and more. Not used yet.
+- The lifetime totals disagree across the production meter, the inverters (far lower) and `/api/v1`. The meter is used; why the inverter total is lower is unconfirmed (a reset or replacement is a guess).
+
+## TLS: why the Bun path skips verification
+
+The gateway's certificate is **not self-signed** on software 8: it serves `CN=<serial>.<part>._mDevice.enphaseenergy.com`, issued by `Cloud.HSM.TA`, then `Factories.MFR.CA` (valid to 2070), which chains to `root-a.PKI.CA`. The gateway does not send that root and Enphase does not publish it (searched 2026-10-13).
+
+- **Bun 1.4.2** (measured): trusting `Factories.MFR.CA` fails with "unable to get issuer certificate" (no partial-chain trust), and with verification off Bun does not run `checkServerIdentity`, so the CN cannot be checked either. `bunGatewayFetch()` therefore skips verification for the gateway's requests only. The token goes to whatever answers at that address, so reserve the address in the router.
+- **Node**: `nodeGatewayFetch()` from `@khalido/home/node` skips verification the same way (checked against a local self-signed server, 2026-10-28; the gateway did not answer that day). Untested: undici's `Agent({ connect: { ca: factoriesMfrCa, allowPartialTrustChain: true, checkServerIdentity } })`, checking the CN starts with the serial, would pin it properly (Node 22.9 and later).
+
+## The plan: local IQ Gateway with an owner token
+
+Source for every step: Enphase's technical brief [Accessing IQ Gateway local APIs and local UI using token](https://enphase.com/download/iq-gateway-local-apis-or-ui-access-using-token) (TEB-00060-2.0, June 2025). It lists ENV-S-WM-230 among the gateways it covers.
+
+1. **Mint a token once** (`home enphase login`, KO runs it). Gateway software 7.0 and later needs a token for local APIs. The brief's script does two calls:
+   - `POST https://enlighten.enphaseenergy.com/login/login.json` with form fields `user[email]` and `user[password]`, returning a `session_id`. (The brief writes `http://`; use HTTPS.)
+   - `POST https://entrez.enphaseenergy.com/tokens` with JSON `{ session_id, serial_num, username }`, returning the token.
+
+   A system owner's token is valid for **one year**; an installer's, or a self-installer's, for 12 hours. Unconfirmed which KO's account is; the token's expiry will say.
+
+2. **Cache it** in `~/.config/home/enphase-token.json`, owner-only (0600), written by the CLI only. The library never stores it; callers pass it in. The password is read from `ENPHASE_PASSWORD` for those two calls and never written.
+3. **Read locally**: HTTPS to the gateway with `Authorization: Bearer <token>` and `Accept: application/json`. The brief uses `curl -k`; see TLS above.
+
+Endpoints from the brief: `/info` (serial, part number, software; **no token needed**), `/api/v1/production` (watts now, watt-hours today, seven days, lifetime), `/api/v1/production/inverters`, `/ivp/meters`, `/ivp/meters/readings`, `/ivp/pdm/energy`, `/ivp/livedata/status`, `/ivp/meters/reports/consumption`, `/ivp/meters/gridReading`.
+
+```sh
+home enphase login   # mints the token from IQ_GATEWAY_SERIAL_NUMBER, ENPHASE_USERNAME, ENPHASE_PASSWORD; prints its expiry
+```
+
+## From Home Assistant's `enphase_envoy`
+
+Its coordinator polls the gateway every 60 s, rechecks the firmware every 4 h, checks the token once a day, and refreshes it when fewer than 30 days remain, raising a repair notice if that fails. The plan copies the policy: `home status` shows the token's days left, and a client warns under 30.
+
+## Sources
+
+| Source                                                                                                                               | Licence                     | Used for                                                                                                                      |
+| ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Enphase [Envoy-S manual](https://portal.segen.co.uk/reseller/docs/Envoy-S-MAN-EN-INTL.pdf) (141-00035 Rev 02, a reseller's copy)     | Enphase document            | LEDs, AP mode, Wi-Fi change                                                                                                   |
+| Enphase [TEB-00060-2.0](https://enphase.com/download/iq-gateway-local-apis-or-ui-access-using-token)                                 | Enphase document, © Enphase | token flow, local endpoints                                                                                                   |
+| [Enphase developer v4](https://developer-v4.enphase.com/)                                                                            | Enphase API terms           | the cloud alternative                                                                                                         |
+| [Home Assistant `enphase_envoy` integration](https://github.com/home-assistant/core/tree/dev/homeassistant/components/enphase_envoy) | Apache-2.0                  | how HA reads a local gateway                                                                                                  |
+| [pyenphase/pyenphase](https://github.com/pyenphase/pyenphase)                                                                        | MIT                         | endpoints for software 8, the meter rules, and the test fixtures (copied with attribution)                                    |
+| The author's earlier Python dashboard (not public)                                                                                   | the author's                | ran against this gateway: the env names, `/production.json` with `/ivp/meters`, trusting a meter only when enabled and active |