sharp-echonet 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soh Satoh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# sharp-echonet
+
+Read a Sharp humidifying air purifier over ECHONET Lite on the local network, and
+decode the vendor-specific properties that carry most of what the machine knows.
+
+Worked out on two **KI-UX75** units, firmware `SHARP_B02`.
+
+## Why this exists
+
+The standard side of ECHONET Lite gives almost nothing on this hardware. The air
+cleaner class (`0x0135`) defines six class properties and KI-UX75 implements
+three: power, air flow rate, and a dirty-air flag. Temperature, humidity, particle
+count, filter usage and the water tank all sit in the vendor properties `0xF1` to
+`0xF3`, which are not documented anywhere.
+
+The standard does define a six-step water level for humidifiers, at EPC `0xC5` of
+the humidifier class. KI-UX75 never announces a humidifier object, so that route
+is closed even though the machine humidifies.
+
+## Install
+
+```
+npm install sharp-echonet
+```
+
+Node 18 or newer, no runtime dependencies.
+
+## Use
+
+```ts
+import { read } from "sharp-echonet";
+
+const r = await read("192.168.1.20");
+
+r.power;                          // "on"
+r.waterTankEmpty;                 // false, or undefined when the byte was unreadable
+r.fields.roomTemperature.value;   // 28
+r.fields.numberOfParticles.value; // 1101
+```
+
+```ts
+import { EchonetClient } from "sharp-echonet";
+
+const client = new EchonetClient();
+const ips = await client.discover();
+client.close();
+```
+
+```
+npx sharp-echonet discover
+npx sharp-echonet read 192.168.1.20
+npx sharp-echonet table
+```
+
+`read` checks the product code (EPC `0x8C`) first and refuses hardware the table
+does not cover, because offsets from one model would produce plausible-looking
+wrong numbers on another. Pass `checkModel: false` to probe anyway.
+
+## What it reads
+
+| Field | Property | Notes |
+| --- | --- | --- |
+| `roomTemperature` | `0xF1[3]` | degrees C |
+| `roomHumidity` | `0xF1[4]` | per cent |
+| `brightnessRaw` | `0xF1[2]` | 0 to 255, not lux, non-linear |
+| `lightingLevel` | `0xF1[8]` | three steps, from the top four bits |
+| `totalOperatingTime` | `0xF1[11:15]` | minutes |
+| `cadrUsed` | `0xF1[21:25]` | cumulative volume of air cleaned |
+| `dustFilterUsed` | `0xF1[29:31]` | compare against `dustFilterLimit` of 3000 |
+| `smellFilterUsed` | `0xF1[31:33]` | |
+| `humidFilterUsed` | `0xF1[35:37]` | |
+| `totalHumidificationAmount` | `0xF1[38:40]` | |
+| `numberOfParticles` | `0xF1[40:43]` | particles per litre |
+| `waterPresent` | `0xF2[19]` | `0xff` while the tank has water |
+| `lightSensorFlag` | `0xF2[20]` | `0xff` in a lit room |
+| `humidificationEnabled` | `0xF3[15]` | the setting, not whether it humidifies now |
+
+The full table, unresolved fields included, ships as
+[`data/ki-ux75.json`](data/ki-ux75.json) and is importable on its own:
+
+```ts
+import table from "sharp-echonet/table" with { type: "json" };
+```
+
+Porting it to another language is a short job, which is why it is data rather
+than code.
+
+Where there is no UDP, such as an edge runtime, fetch the bytes elsewhere and
+unpack them through the decode-only entry point, which pulls in no node built-ins:
+
+```ts
+import { decodeAll, waterTankEmpty } from "sharp-echonet/decode";
+```
+
+## Confidence
+
+Fields carry a confidence level, and `read` returns only `confirmed` ones unless
+asked otherwise.
+
+- `confirmed`: matched on two units at aligned timestamps, or moved when
+  something was deliberately changed.
+- `probable`: the position follows from its neighbours and was never seen to move.
+- `offset-confirmed`: the byte position is certain, the value is not trustworthy
+  on this model.
+
+That last case is real. The vendor app names `0xF1[27:29]` as a PM2.5 reading and
+the bytes do move, but the device reports no PM2.5 sensor, so publishing it as a
+measurement would be inventing a number.
+
+```ts
+await read(ip, { minConfidence: "probable", includeUnusable: true });
+```
+
+## Traps
+
+- `0xF3[5]` and `0xF2[39]` read `0x00` on one unit and `0x01` on the other, which
+  makes them look like flags. They are per-unit constants, and neither moved when
+  the tank was refilled or humidification was toggled. Comparing two machines is
+  not enough to call a byte a flag.
+- `0xF1[42]` drifts and never returns, so alone it reads as noise. It is the low
+  byte of the three-byte particle count at offset 40.
+- `0xF1[14]` counts up once a minute, `0xF1[24]` roughly every 43 seconds.
+- Writes to `0xA0` are answered with ESV `0x71` and then ignored, and power draw
+  does not change. Power is the only write this hardware honours.
+
+## The tank
+
+Nothing on the vendor side reports a refill: the machine keeps running, the app
+has no such wording, and `0xF2[19]` is the one slot in its group the app never
+reads. Only the panel indicator shows it.
+
+The byte was pinned by switching humidification off while water remained, which
+separates having water from humidifying. Those states overlap completely
+otherwise, since a dry machine cannot humidify. Pulling the tank out does not
+change it, so the sensor appears to watch the tray and routine cleaning will not
+raise a false refill.
+
+Anything other than `0xff` counts as empty. Only two values have ever been seen,
+and treating an unknown third one as a full tank would fail silently in the one
+direction that matters.
+
+## Protocol notes
+
+- Replies arrive on port 3610, not on 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.
+- Since 3610 is shared, keep one `EchonetClient` per process and let it
+  demultiplex replies by transaction id.
+
+## Scope and disclaimer
+
+This project has no connection with Sharp Corporation and is neither endorsed nor
+supported by it. Product and company names belong to their owners.
+
+The offsets were derived by observing the author's own devices on the author's own
+network. They are not published by the manufacturer, they are not a specification,
+and a firmware update can invalidate any of them. Treat the table as findings that
+held on two units at a point in time. The product code check exists so that a
+mismatch fails loudly instead of returning numbers from the wrong place.
+
+The library reads. Power is the only write the hardware honours and it is not
+wrapped here. No credentials are included and nothing depends on the
+manufacturer's cloud at runtime.
+
+Provided as is, without warranty of any kind, under the MIT licence. Anyone using
+it does so at their own risk.

package/data/ki-ux75.json

@@ -0,0 +1,354 @@
+{
+  "model": "KIUX75",
+  "productCode": "4b4955583735",
+  "firmware": [
+    "SHARP_B02"
+  ],
+  "eoj": "0x013501",
+  "standardVersion": "I",
+  "note": "Field offsets for the vendor-specific properties of the Sharp KI-UX75 humidifying air purifier. Confirmed against two units. Offsets are byte positions inside the EDT of the given EPC.",
+  "spec": {
+    "hasDustSensor": true,
+    "hasPM25Sensor": false,
+    "hasCO2Sensor": false,
+    "hasLightSensor": true,
+    "hasHumidFunc": true,
+    "dustFilterLimit": 3000
+  },
+  "standardProperties": {
+    "0x80": {
+      "name": "operationStatus",
+      "note": "0x30 on, 0x31 off. Readable and writable."
+    },
+    "0x84": {
+      "name": "instantaneousPower",
+      "unit": "W",
+      "size": 2
+    },
+    "0x88": {
+      "name": "faultStatus",
+      "note": "0x41 fault, 0x42 normal"
+    },
+    "0xA0": {
+      "name": "airFlowRate",
+      "note": "Writes are acknowledged with ESV 0x71 and then ignored. Power draw does not change."
+    },
+    "0xC0": {
+      "name": "airPollutionDetected",
+      "note": "0x41 detected, 0x42 not detected"
+    }
+  },
+  "properties": {
+    "0xF1": {
+      "length": 43,
+      "fields": [
+        {
+          "offset": 2,
+          "size": 1,
+          "name": "brightnessRaw",
+          "type": "uint",
+          "confidence": "confirmed",
+          "note": "Not lux. A non-linear 0-255 scale: 199-202 fully lit, 145 at dusk with no lights, 0 in the dark. The vendor app does not read this byte; it uses the three-level flag at offset 8 instead."
+        },
+        {
+          "offset": 3,
+          "size": 1,
+          "name": "roomTemperature",
+          "type": "uint",
+          "unit": "degC",
+          "vendorSlot": "k1.s1",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 4,
+          "size": 1,
+          "name": "roomHumidity",
+          "type": "uint",
+          "unit": "%",
+          "vendorSlot": "k1.s2",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 8,
+          "size": 1,
+          "name": "lightingLevel",
+          "type": "bits",
+          "bits": "high 4",
+          "vendorSlot": "k1.s15",
+          "confidence": "confirmed",
+          "note": "The vendor app reads the top four bits and maps them to off / dark / bright."
+        },
+        {
+          "offset": 11,
+          "size": 4,
+          "name": "totalOperatingTime",
+          "type": "uint",
+          "unit": "minutes",
+          "vendorSlot": "k1.s3",
+          "confidence": "confirmed",
+          "note": "Advanced by exactly 30 across a 30 minute gap."
+        },
+        {
+          "offset": 15,
+          "size": 2,
+          "name": "pciUnit1Used",
+          "type": "uint",
+          "vendorSlot": "k1.s4",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 17,
+          "size": 2,
+          "name": "pciUnit2Used",
+          "type": "uint",
+          "vendorSlot": "k1.s5",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 21,
+          "size": 4,
+          "name": "cadrUsed",
+          "type": "uint",
+          "vendorSlot": "k1.s6",
+          "confidence": "confirmed",
+          "note": "Cumulative volume of air cleaned. Rises monotonically."
+        },
+        {
+          "offset": 27,
+          "size": 2,
+          "name": "pm25Value",
+          "type": "uint",
+          "vendorSlot": "k1.s7",
+          "confidence": "offset-confirmed",
+          "usable": false,
+          "note": "The vendor app calls this pm25Value but gates it on hasPM25Sensor, which is false for this model. The bytes move, but do not publish them as a PM2.5 reading."
+        },
+        {
+          "offset": 29,
+          "size": 2,
+          "name": "dustFilterUsed",
+          "type": "uint",
+          "vendorSlot": "k1.s8",
+          "confidence": "confirmed",
+          "note": "Compare against spec.dustFilterLimit for remaining life."
+        },
+        {
+          "offset": 31,
+          "size": 2,
+          "name": "smellFilterUsed",
+          "type": "uint",
+          "vendorSlot": "k1.s9",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 35,
+          "size": 2,
+          "name": "humidFilterUsed",
+          "type": "uint",
+          "vendorSlot": "k1.s10",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 37,
+          "size": 1,
+          "name": "agIonFilterUsed",
+          "type": "uint",
+          "vendorSlot": "k1.s11",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 38,
+          "size": 2,
+          "name": "totalHumidificationAmount",
+          "type": "uint",
+          "vendorSlot": "k1.s12",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 40,
+          "size": 3,
+          "name": "numberOfParticles",
+          "type": "uint",
+          "unit": "particles/L",
+          "vendorSlot": "k1.s14",
+          "confidence": "confirmed",
+          "note": "Matched the vendor's own figure at an aligned timestamp, then again on the second unit."
+        }
+      ],
+      "unresolved": [
+        {
+          "vendorSlot": "k1.s13",
+          "name": "co2Concentration",
+          "note": "This model has no CO2 sensor, so the field is always zero and its offset cannot be pinned."
+        }
+      ]
+    },
+    "0xF2": {
+      "length": 41,
+      "fields": [
+        {
+          "offset": 16,
+          "size": 1,
+          "name": "pm25Level",
+          "type": "uint",
+          "vendorSlot": "k2.s3",
+          "confidence": "confirmed",
+          "usable": false,
+          "note": "Tracked the vendor value across four timestamps. Still gated on hasPM25Sensor for this model."
+        },
+        {
+          "offset": 17,
+          "size": 1,
+          "name": "airSummaryLevel",
+          "type": "uint",
+          "vendorSlot": "k2.s4",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 18,
+          "size": 1,
+          "name": "humidIconStatus",
+          "type": "uint",
+          "vendorSlot": "k2.s5",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 19,
+          "size": 1,
+          "name": "waterPresent",
+          "type": "flag",
+          "trueValue": "0xff",
+          "vendorSlot": "k2.s6",
+          "confidence": "confirmed",
+          "note": "0xff while the machine has water, 0x00 once it wants a refill. This is the only slot in the group that the vendor app never reads, and no vendor screen shows a refill state. Treat anything other than 0xff as empty so that an unseen third value does not fail silent."
+        },
+        {
+          "offset": 20,
+          "size": 1,
+          "name": "lightSensorFlag",
+          "type": "flag",
+          "trueValue": "0xff",
+          "vendorSlot": "k2.s7",
+          "confidence": "confirmed",
+          "note": "0xff in a lit room, 0x00 in the dark."
+        },
+        {
+          "offset": 24,
+          "size": 1,
+          "name": "humidButtonStatus",
+          "type": "uint",
+          "vendorSlot": "k2.s11",
+          "confidence": "confirmed",
+          "note": "Changed from 0x00 to 0x81 at the moment humidification was switched back on."
+        },
+        {
+          "offset": 25,
+          "size": 1,
+          "name": "pciVisible",
+          "type": "uint",
+          "vendorSlot": "k2.s12",
+          "confidence": "confirmed"
+        },
+        {
+          "offset": 14,
+          "size": 1,
+          "name": "smellLevel",
+          "type": "uint",
+          "vendorSlot": "k2.s1",
+          "confidence": "probable",
+          "note": "Placed by the ordering that holds for slots 3 through 12. Not observed changing."
+        },
+        {
+          "offset": 15,
+          "size": 1,
+          "name": "dustLevel",
+          "type": "uint",
+          "vendorSlot": "k2.s2",
+          "confidence": "probable",
+          "note": "Same reasoning as smellLevel."
+        }
+      ],
+      "unresolved": [
+        {
+          "vendorSlot": "k2.s13 - k2.s17",
+          "note": "Slots 1 through 12 sit at offsets 14 through 25 in order, but slot 16 (volumeSetting) does not land where that run predicts, so the tail is laid out differently. Left unresolved rather than guessed."
+        }
+      ]
+    },
+    "0xF3": {
+      "length": 27,
+      "fields": [
+        {
+          "offset": 15,
+          "size": 1,
+          "name": "humidificationEnabled",
+          "type": "flag",
+          "trueValue": "0xff",
+          "confidence": "confirmed",
+          "note": "The setting, not whether the machine is humidifying right now. A unit with an empty tank still reports 0xff while the setting is on. Writes are not reflected."
+        },
+        {
+          "offset": 4,
+          "size": 1,
+          "name": "driveState",
+          "type": "uint",
+          "vendorSlot": "k3.s1",
+          "confidence": "probable",
+          "note": "The vendor app reads this slot for drive mode, running state and dust filter life."
+        }
+      ],
+      "unresolved": [
+        {
+          "vendorSlot": "k3.s2",
+          "offset": 8,
+          "note": "The vendor app reads this slot, but what it means is not established."
+        },
+        {
+          "vendorSlot": "k3.s6",
+          "offset": 13,
+          "note": "Position matched on a single snapshot. Meaning unknown."
+        },
+        {
+          "vendorSlot": "rest of 0xF3",
+          "note": "Matched from a single snapshot where most bytes were zero."
+        }
+      ]
+    },
+    "0xF4": {
+      "note": "Every byte was zero on both units across every reading."
+    }
+  },
+  "traps": [
+    {
+      "where": "0xF3[5]",
+      "claim": "Looks like a water or mode flag: 0x00 on one unit and 0x01 on the other.",
+      "reality": "A per-unit constant. It did not move when the tank was refilled or when humidification was switched on and off."
+    },
+    {
+      "where": "0xF2[39]",
+      "claim": "Same shape, 0x00 against 0x01 between units.",
+      "reality": "Also a per-unit constant."
+    },
+    {
+      "where": "0xF1[42]",
+      "claim": "Drifts constantly and never returns, so it reads as noise.",
+      "reality": "The low byte of the three byte particle count at offset 40. Read the whole field."
+    },
+    {
+      "where": "0xF1[14]",
+      "reality": "Increments once a minute."
+    },
+    {
+      "where": "0xF1[24]",
+      "reality": "Increments roughly every 43 seconds."
+    },
+    {
+      "where": "0xA0",
+      "reality": "The device answers a write with ESV 0x71 and then ignores it. Instantaneous power does not budge."
+    },
+    {
+      "where": "humidifier class 0x0139",
+      "reality": "The standard defines a six step water level at EPC 0xC5, but this unit lists only 0x013501 in its instance list and does not answer that object at all."
+    }
+  ]
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { EchonetClient } from "./echonet.js";
+import { read } from "./read.js";
+import { table } from "./table.js";
+function usage() {
+    console.error(`sharp-echonet <command>
+
+  discover              find air purifiers on the local network
+  read <ip> [--all]     read one purifier; --all includes unconfirmed fields
+  table                 print what this build knows about ${table.model}
+`);
+    process.exit(1);
+}
+const [command, ...rest] = process.argv.slice(2);
+if (command === "discover") {
+    const client = new EchonetClient();
+    const found = await client.discover();
+    client.close();
+    if (found.length === 0) {
+        console.error("nothing answered. Some networks block multicast between clients.");
+        process.exit(1);
+    }
+    for (const ip of found)
+        console.log(ip);
+}
+else if (command === "read") {
+    const ip = rest[0];
+    if (!ip)
+        usage();
+    const all = rest.includes("--all");
+    const reading = await read(ip, {
+        ...(all ? { minConfidence: "probable", includeUnusable: true } : {}),
+    });
+    const { raw, ...rest2 } = reading;
+    console.log(JSON.stringify({ ...rest2, fields: Object.fromEntries(Object.entries(reading.fields)) }, null, 2));
+}
+else if (command === "table") {
+    console.log(JSON.stringify(table, null, 2));
+}
+else {
+    usage();
+}

package/dist/decode-only.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Decoding on its own, pulling in no node built-ins.
+ *
+ * The root entry point carries the UDP client and therefore `node:dgram`. Where
+ * there is no UDP, such as an edge runtime, the bytes have to be fetched
+ * elsewhere and unpacked here, so that path is kept separate.
+ */
+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";

package/dist/decode-only.js

@@ -0,0 +1,9 @@
+/**
+ * Decoding on its own, pulling in no node built-ins.
+ *
+ * The root entry point carries the UDP client and therefore `node:dgram`. Where
+ * there is no UDP, such as an edge runtime, the bytes have to be fetched
+ * elsewhere and unpacked here, so that path is kept separate.
+ */
+export { table, fieldsOf, matchesProductCode, hexEpc } from "./table.js";
+export { decodeProperty, decodeAll, waterTankEmpty } from "./decode.js";

package/dist/decode.d.ts

@@ -0,0 +1,40 @@
+import { type Confidence } from "./table.ts";
+export interface DecodedField {
+    name: string;
+    value: number | boolean;
+    unit?: string;
+    confidence: Confidence;
+    /** False when the field exists but this model cannot produce a meaningful value. */
+    usable: boolean;
+    vendorSlot?: string;
+    note?: string;
+}
+export interface DecodeOptions {
+    /**
+     * Lowest confidence to return. Defaults to `confirmed`, so callers get only
+     * fields that survived a second experiment unless they ask for more.
+     */
+    minConfidence?: Confidence;
+    /** Include fields whose value this model cannot produce. Off by default. */
+    includeUnusable?: boolean;
+}
+/** Decode one vendor property (0xF1, 0xF2, 0xF3) into named fields. */
+export declare function decodeProperty(epc: number, edt: Uint8Array, options?: DecodeOptions): DecodedField[];
+/**
+ * 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 declare function decodeAll(props: Map<number, Uint8Array>, options?: DecodeOptions): Record<string, DecodedField>;
+/**
+ * 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 declare function waterTankEmpty(props: Map<number, Uint8Array>): boolean | undefined;