sharp-echonet 0.2.0

package/dist/decode.js

@@ -0,0 +1,87 @@
+import { fieldsOf, hexEpc, table } from "./table.js";
+const RANK = {
+    confirmed: 3,
+    "offset-confirmed": 2,
+    probable: 1,
+};
+function readUint(edt, offset, size) {
+    let n = 0;
+    for (let i = 0; i < size; i++)
+        n = n * 256 + edt[offset + i];
+    return n;
+}
+function decodeField(edt, f) {
+    // A short response means a different firmware laid the property out
+    // differently. Returning nothing beats returning a number from the wrong place.
+    if (offsetOutOfRange(edt, f))
+        return undefined;
+    switch (f.type) {
+        case "flag":
+            return edt[f.offset] === Number(f.trueValue ?? "0xff");
+        case "bits":
+            return edt[f.offset] >> 4;
+        default:
+            return readUint(edt, f.offset, f.size);
+    }
+}
+function offsetOutOfRange(edt, f) {
+    return f.offset + f.size > edt.length;
+}
+/** Decode one vendor property (0xF1, 0xF2, 0xF3) into named fields. */
+export function decodeProperty(epc, edt, options = {}) {
+    const floor = RANK[options.minConfidence ?? "confirmed"];
+    const out = [];
+    for (const f of fieldsOf(epc)) {
+        if (RANK[f.confidence] < floor)
+            continue;
+        const usable = f.usable !== false;
+        if (!usable && !options.includeUnusable)
+            continue;
+        const value = decodeField(edt, f);
+        if (value === undefined)
+            continue;
+        out.push({
+            name: f.name,
+            value,
+            ...(f.unit ? { unit: f.unit } : {}),
+            confidence: f.confidence,
+            usable,
+            ...(f.vendorSlot ? { vendorSlot: f.vendorSlot } : {}),
+            ...(f.note ? { note: f.note } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Decode a whole read into one flat object keyed by field name.
+ *
+ * Properties the table does not describe are skipped rather than guessed at.
+ */
+export function decodeAll(props, options = {}) {
+    const out = {};
+    for (const [epc, edt] of props) {
+        if (!table.properties[hexEpc(epc)])
+            continue;
+        for (const field of decodeProperty(epc, edt, options))
+            out[field.name] = field;
+    }
+    return out;
+}
+/**
+ * Whether the tank needs a refill.
+ *
+ * Returns undefined when the byte is missing, never false. "I could not read it"
+ * and "there is water" are different answers, and collapsing them means a dry
+ * machine reports as full.
+ *
+ * Anything other than the water-present value counts as empty. Only two values
+ * have ever been observed, so an unrecognised third one is more safely treated
+ * as a refill than as a full tank.
+ */
+export function waterTankEmpty(props) {
+    const edt = props.get(0xf2);
+    const field = fieldsOf(0xf2).find((f) => f.name === "waterPresent");
+    if (!edt || !field || edt.length <= field.offset)
+        return undefined;
+    return edt[field.offset] !== Number(field.trueValue ?? "0xff");
+}

package/dist/echonet.d.ts

@@ -0,0 +1,51 @@
+export declare const EL_PORT = 3610;
+export declare const EL_MULTICAST = "224.0.23.0";
+/** Air cleaner, class group 0x01, class 0x35, instance 1. */
+export declare const EOJ_AIR_CLEANER: Uint8Array<ArrayBuffer>;
+/** Node profile. The target for discovery. */
+export declare const EOJ_NODE_PROFILE: Uint8Array<ArrayBuffer>;
+export interface Frame {
+    tid: number;
+    seoj: Uint8Array;
+    deoj: Uint8Array;
+    esv: number;
+    props: Map<number, Uint8Array>;
+}
+export declare function buildFrame(tid: number, deoj: Uint8Array, esv: number, epcs: number[]): Buffer;
+export declare function parseFrame(b: Uint8Array): Frame | null;
+/** Instance list from EPC 0xD6: one count byte, then three bytes per object. */
+export declare function parseInstanceList(edt: Uint8Array): Uint8Array[];
+export interface ClientOptions {
+    /** Milliseconds to wait for one reply. */
+    timeoutMs?: number;
+}
+/**
+ * A minimal ECHONET Lite client.
+ *
+ * Two things about this protocol cost real time to discover, so they are worth
+ * stating plainly:
+ *
+ * - Replies come back to port 3610, not to the port the request went out from.
+ *   Waiting on an ephemeral port times out every time.
+ * - Joining the multicast group is unnecessary. Discovery goes out as multicast
+ *   and devices answer by unicast.
+ *
+ * Because 3610 is a shared port, hold one client for the life of the process and
+ * demultiplex replies by transaction id rather than opening a socket per request.
+ */
+export declare class EchonetClient {
+    private socket;
+    private tid;
+    private pending;
+    private timeoutMs;
+    private ready;
+    constructor(options?: ClientOptions);
+    private nextTid;
+    /** Read properties from one device. Unreadable EPCs come back with empty data. */
+    get(ip: string, epcs: number[], deoj?: Uint8Array): Promise<Map<number, Uint8Array>>;
+    /** Ask a node which objects it hosts. */
+    instances(ip: string): Promise<Uint8Array[]>;
+    /** Multicast for air cleaners and collect the addresses that answer. */
+    discover(windowMs?: number): Promise<string[]>;
+    close(): void;
+}

package/dist/echonet.js

@@ -0,0 +1,154 @@
+import { createSocket } from "node:dgram";
+export const EL_PORT = 3610;
+export const EL_MULTICAST = "224.0.23.0";
+const EHD1 = 0x10;
+const EHD2 = 0x81;
+const ESV_GET = 0x62;
+const ESV_GET_RES = 0x72;
+const ESV_GET_SNA = 0x52;
+/** Air cleaner, class group 0x01, class 0x35, instance 1. */
+export const EOJ_AIR_CLEANER = Uint8Array.from([0x01, 0x35, 0x01]);
+/** Node profile. The target for discovery. */
+export const EOJ_NODE_PROFILE = Uint8Array.from([0x0e, 0xf0, 0x01]);
+/** Controller. What this library calls itself. */
+const EOJ_CONTROLLER = Uint8Array.from([0x05, 0xff, 0x01]);
+const EPC_INSTANCE_LIST = 0xd6;
+export function buildFrame(tid, deoj, esv, epcs) {
+    const head = [EHD1, EHD2, tid >> 8, tid & 0xff, ...EOJ_CONTROLLER, ...deoj, esv, epcs.length];
+    const body = [];
+    for (const epc of epcs)
+        body.push(epc, 0);
+    return Buffer.from([...head, ...body]);
+}
+export function parseFrame(b) {
+    if (b.length < 12 || b[0] !== EHD1 || b[1] !== EHD2)
+        return null;
+    const props = new Map();
+    const opc = b[11];
+    let i = 12;
+    for (let n = 0; n < opc; n++) {
+        if (i + 2 > b.length)
+            return null;
+        const epc = b[i];
+        const pdc = b[i + 1];
+        i += 2;
+        if (i + pdc > b.length)
+            return null;
+        props.set(epc, b.slice(i, i + pdc));
+        i += pdc;
+    }
+    return {
+        tid: (b[2] << 8) | b[3],
+        seoj: b.slice(4, 7),
+        deoj: b.slice(7, 10),
+        esv: b[10],
+        props,
+    };
+}
+/** Instance list from EPC 0xD6: one count byte, then three bytes per object. */
+export function parseInstanceList(edt) {
+    if (edt.length < 1)
+        return [];
+    const out = [];
+    for (let i = 0; i < edt[0]; i++) {
+        const off = 1 + i * 3;
+        if (off + 3 > edt.length)
+            break;
+        out.push(edt.slice(off, off + 3));
+    }
+    return out;
+}
+/**
+ * A minimal ECHONET Lite client.
+ *
+ * Two things about this protocol cost real time to discover, so they are worth
+ * stating plainly:
+ *
+ * - Replies come back to port 3610, not to the port the request went out from.
+ *   Waiting on an ephemeral port times out every time.
+ * - Joining the multicast group is unnecessary. Discovery goes out as multicast
+ *   and devices answer by unicast.
+ *
+ * Because 3610 is a shared port, hold one client for the life of the process and
+ * demultiplex replies by transaction id rather than opening a socket per request.
+ */
+export class EchonetClient {
+    socket;
+    tid = 0;
+    pending = new Map();
+    timeoutMs;
+    ready;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? 3000;
+        this.socket = createSocket({ type: "udp4", reuseAddr: true });
+        this.socket.on("message", (msg, rinfo) => {
+            const frame = parseFrame(msg);
+            if (!frame)
+                return;
+            this.pending.get(frame.tid)?.({ from: rinfo.address, frame });
+        });
+        this.ready = new Promise((resolve, reject) => {
+            this.socket.once("error", reject);
+            this.socket.bind(EL_PORT, () => resolve());
+        });
+    }
+    nextTid() {
+        this.tid = (this.tid + 1) & 0xffff || 1;
+        return this.tid;
+    }
+    /** Read properties from one device. Unreadable EPCs come back with empty data. */
+    async get(ip, epcs, deoj = EOJ_AIR_CLEANER) {
+        await this.ready;
+        const tid = this.nextTid();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(tid);
+                reject(new Error(`${ip} did not answer`));
+            }, this.timeoutMs);
+            this.pending.set(tid, ({ from, frame }) => {
+                if (from !== ip)
+                    return;
+                clearTimeout(timer);
+                this.pending.delete(tid);
+                if (frame.esv !== ESV_GET_RES && frame.esv !== ESV_GET_SNA) {
+                    reject(new Error(`unexpected ESV 0x${frame.esv.toString(16)}`));
+                    return;
+                }
+                resolve(frame.props);
+            });
+            this.socket.send(buildFrame(tid, deoj, ESV_GET, epcs), EL_PORT, ip);
+        });
+    }
+    /** Ask a node which objects it hosts. */
+    async instances(ip) {
+        const props = await this.get(ip, [EPC_INSTANCE_LIST], EOJ_NODE_PROFILE);
+        const edt = props.get(EPC_INSTANCE_LIST);
+        return edt ? parseInstanceList(edt) : [];
+    }
+    /** Multicast for air cleaners and collect the addresses that answer. */
+    async discover(windowMs = 2000) {
+        await this.ready;
+        const tid = this.nextTid();
+        const found = new Set();
+        this.pending.set(tid, ({ from, frame }) => {
+            const edt = frame.props.get(EPC_INSTANCE_LIST);
+            if (!edt)
+                return;
+            const hit = parseInstanceList(edt).some((eoj) => eoj[0] === 0x01 && eoj[1] === 0x35);
+            if (hit)
+                found.add(from);
+        });
+        const pkt = buildFrame(tid, EOJ_NODE_PROFILE, ESV_GET, [EPC_INSTANCE_LIST]);
+        // UDP drops happen, so ask more than once.
+        for (let i = 0; i < 3; i++) {
+            this.socket.send(pkt, EL_PORT, EL_MULTICAST);
+            await new Promise((r) => setTimeout(r, 150));
+        }
+        await new Promise((r) => setTimeout(r, windowMs));
+        this.pending.delete(tid);
+        return [...found];
+    }
+    close() {
+        this.socket.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { table, fieldsOf, matchesProductCode, hexEpc } from "./table.ts";
+export type { Table, FieldSpec, PropertySpec, Confidence } from "./table.ts";
+export { decodeProperty, decodeAll, waterTankEmpty } from "./decode.ts";
+export type { DecodedField, DecodeOptions } from "./decode.ts";
+export { EchonetClient, EOJ_AIR_CLEANER, EOJ_NODE_PROFILE, EL_PORT, EL_MULTICAST, buildFrame, parseFrame, parseInstanceList, } from "./echonet.ts";
+export type { Frame, ClientOptions } from "./echonet.ts";
+export { read } from "./read.ts";
+export type { Reading } from "./read.ts";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { table, fieldsOf, matchesProductCode, hexEpc } from "./table.js";
+export { decodeProperty, decodeAll, waterTankEmpty } from "./decode.js";
+export { EchonetClient, EOJ_AIR_CLEANER, EOJ_NODE_PROFILE, EL_PORT, EL_MULTICAST, buildFrame, parseFrame, parseInstanceList, } from "./echonet.js";
+export { read } from "./read.js";

package/dist/read.d.ts

@@ -0,0 +1,28 @@
+import { type DecodedField, type DecodeOptions } from "./decode.ts";
+import { EchonetClient } from "./echonet.ts";
+export interface Reading {
+    power: "on" | "off" | undefined;
+    watts: number | undefined;
+    fault: boolean | undefined;
+    airPollutionDetected: boolean | undefined;
+    /** Undefined when the byte could not be read, which is not the same as full. */
+    waterTankEmpty: boolean | undefined;
+    fields: Record<string, DecodedField>;
+    raw: Map<number, Uint8Array>;
+}
+export interface ReadOptions extends DecodeOptions {
+    client?: EchonetClient;
+    /**
+     * Read EPC 0x8C first and refuse to decode hardware the table does not cover.
+     * Leave this on unless you are deliberately probing another model.
+     */
+    checkModel?: boolean;
+}
+/**
+ * Read one air purifier and decode what the table knows.
+ *
+ * The model check is on by default because these offsets were established on one
+ * model and one firmware. Applying them to different hardware would produce
+ * numbers that look plausible and are wrong, which is worse than no reading.
+ */
+export declare function read(ip: string, options?: ReadOptions): Promise<Reading>;

package/dist/read.js

@@ -0,0 +1,63 @@
+import { decodeAll, waterTankEmpty } from "./decode.js";
+import { EchonetClient } from "./echonet.js";
+import { matchesProductCode } from "./table.js";
+const EPC_OPERATION_STATUS = 0x80;
+const EPC_INSTANT_POWER = 0x84;
+const EPC_FAULT = 0x88;
+const EPC_PRODUCT_CODE = 0x8c;
+const EPC_AIR_POLLUTION = 0xc0;
+const VENDOR_EPCS = [0xf1, 0xf2, 0xf3];
+/**
+ * Read one air purifier and decode what the table knows.
+ *
+ * The model check is on by default because these offsets were established on one
+ * model and one firmware. Applying them to different hardware would produce
+ * numbers that look plausible and are wrong, which is worse than no reading.
+ */
+export async function read(ip, options = {}) {
+    const client = options.client ?? new EchonetClient();
+    const owned = !options.client;
+    try {
+        const epcs = [
+            EPC_OPERATION_STATUS,
+            EPC_INSTANT_POWER,
+            EPC_FAULT,
+            EPC_AIR_POLLUTION,
+            ...VENDOR_EPCS,
+        ];
+        if (options.checkModel !== false)
+            epcs.push(EPC_PRODUCT_CODE);
+        const props = await client.get(ip, epcs);
+        if (options.checkModel !== false) {
+            const code = props.get(EPC_PRODUCT_CODE);
+            if (!code || !matchesProductCode(code)) {
+                throw new Error(`${ip} reports a product code this table does not cover. Pass checkModel: false to decode anyway.`);
+            }
+        }
+        const status = props.get(EPC_OPERATION_STATUS);
+        const power = status?.length === 1 ? (status[0] === 0x30 ? "on" : "off") : undefined;
+        const watts = byteLen(props.get(EPC_INSTANT_POWER), 2)
+            ? (props.get(EPC_INSTANT_POWER)[0] << 8) | props.get(EPC_INSTANT_POWER)[1]
+            : undefined;
+        return {
+            power,
+            watts,
+            fault: flag(props.get(EPC_FAULT)),
+            airPollutionDetected: flag(props.get(EPC_AIR_POLLUTION)),
+            waterTankEmpty: waterTankEmpty(props),
+            fields: decodeAll(props, options),
+            raw: props,
+        };
+    }
+    finally {
+        if (owned)
+            client.close();
+    }
+}
+function byteLen(v, n) {
+    return v?.length === n;
+}
+/** ECHONET spells these as 0x41 for yes and 0x42 for no. */
+function flag(v) {
+    return v?.length === 1 ? v[0] === 0x41 : undefined;
+}

package/dist/table.d.ts

@@ -0,0 +1,78 @@
+/**
+ * How much weight a field carries.
+ *
+ * The distinction matters more than it looks. Two of the byte positions in this
+ * table were nearly published as flags before a second experiment showed they
+ * were constants that differ per unit. Anything short of `confirmed` should be
+ * treated as a lead, not a reading.
+ */
+export type Confidence = 
+/** Matched on two units at aligned timestamps, or moved with a deliberate change. */
+"confirmed"
+/** The byte position is certain, but the value is not trustworthy on this model. */
+ | "offset-confirmed"
+/** Placed by the ordering of neighbouring fields, never seen to move. */
+ | "probable";
+export interface FieldSpec {
+    offset: number;
+    size: number;
+    name: string;
+    type: "uint" | "flag" | "bits";
+    unit?: string;
+    /** Value that makes a `flag` field true, as a hex string such as `0xff`. */
+    trueValue?: string;
+    bits?: string;
+    vendorSlot?: string;
+    confidence: Confidence;
+    /** False when the field exists but this model cannot produce a meaningful value. */
+    usable?: boolean;
+    note?: string;
+}
+export interface PropertySpec {
+    length?: number;
+    fields?: FieldSpec[];
+    unresolved?: {
+        vendorSlot?: string;
+        name?: string;
+        note: string;
+    }[];
+    note?: string;
+}
+export interface Table {
+    model: string;
+    /** EPC 0x8C (product code) as lowercase hex, used to refuse unknown hardware. */
+    productCode: string;
+    firmware: string[];
+    eoj: string;
+    standardVersion: string;
+    note: string;
+    spec: Record<string, boolean | number>;
+    standardProperties: Record<string, {
+        name: string;
+        unit?: string;
+        size?: number;
+        note?: string;
+    }>;
+    properties: Record<string, PropertySpec>;
+    traps: {
+        where: string;
+        claim?: string;
+        reality: string;
+    }[];
+}
+/**
+ * data/ki-ux75.json is the source of truth. This reads the TypeScript generated
+ * from it rather than the file itself, so that decoding works where there is no
+ * filesystem.
+ */
+export declare const table: Table;
+/** Every field of one property, in byte order. */
+export declare function fieldsOf(epc: number): FieldSpec[];
+export declare function hexEpc(epc: number): string;
+/**
+ * Whether a product code belongs to the hardware this table describes.
+ *
+ * EPC 0x8C carries the product code as ASCII padded with zero bytes, so
+ * `KIUX75` arrives as `4b4955583735000000000000`. Compare only the prefix.
+ */
+export declare function matchesProductCode(productCode: Uint8Array | string): boolean;

package/dist/table.data.d.ts

@@ -0,0 +1,2 @@
+import type { Table } from "./table.ts";
+export declare const tableData: Table;