irtxrx 0.0.1

package/README.md

@@ -0,0 +1,127 @@
+# irtxrx
+
+TypeScript library for encoding and decoding raw IR remote control frames. Converts between appliance state (temperature, mode, fan speed) and raw timing arrays that IR blaster hardware can transmit.
+
+Zero runtime dependencies. Dual ESM/CJS. Correctness verified against the [IRremoteESP8266](https://github.com/crankyoldgit/IRremoteESP8266) C++ library.
+
+## Install
+
+```
+npm install irtxrx
+```
+
+## Encode (TX)
+
+Build raw IR timing arrays from appliance state:
+
+```typescript
+import { sendDaikin152, DaikinMode, DaikinFan } from "irtxrx";
+
+const timings = sendDaikin152({
+  power: true,
+  temp: 24,
+  mode: DaikinMode.Cool,
+  fan: DaikinFan.Auto,
+  swingVertical: true,
+});
+// → [3492, 1718, 433, 1529, 433, 433, ...] (mark/space durations in µs)
+```
+
+```typescript
+import { sendCoolix, CoolixMode, CoolixFan } from "irtxrx";
+
+const timings = sendCoolix({ temp: 22, mode: CoolixMode.Heat, fan: CoolixFan.Max });
+```
+
+```typescript
+import { sendNEC, encodeNEC } from "irtxrx";
+
+const timings = sendNEC(encodeNEC(0x01, 0x02));
+```
+
+## Decode (RX)
+
+Identify the protocol and extract state from raw timings captured by hardware:
+
+```typescript
+import { decode } from "irtxrx";
+
+// Blind decode — identifies the protocol automatically
+const result = decode(timings);
+// → { protocol: "daikin152", brand: "daikin", type: "ac",
+//    state: { power: true, temp: 24, mode: 3, fan: 10, ... },
+//    confidence: "checksum_valid" }
+
+// With protocol hint — faster, tolerates missing headers
+const result = decode(timings, { protocol: "coolix" });
+
+// Filter by brand or type
+const result = decode(timings, { brand: "daikin" });
+const result = decode(timings, { type: "ac" });
+```
+
+The decoded `state` is the same type accepted by the encoder, so roundtrips are lossless:
+
+```typescript
+const state = decode(timings, { protocol: "daikin152" })!.state;
+const timings2 = sendDaikin152(state);
+// timings2 produces identical raw bytes
+```
+
+### Handling hardware captures
+
+Real IR captures from photodiode hardware often arrive with the first frame's header missing (the sensor wakes from sleep on the initial pulse). The decoder handles this automatically:
+
+- **Blind decode** uses a 3-tier strategy: header match, repeat frame scan, then headerless brute force with checksum validation
+- **Protocol-hinted decode** skips straight to headerless decoding since the checksum/parity check is sufficient
+
+### Command-based protocols
+
+Some protocols (Coolix) use fixed codes for toggle features like swing, turbo, and power off. These decode as `state: null` with a `raw` code:
+
+```typescript
+import { decode, CoolixCommand } from "irtxrx";
+
+const result = decode(timings, { protocol: "coolix" });
+if (result?.state === null) {
+  // It's a command frame
+  if (result.raw === CoolixCommand.Off) { /* power off */ }
+  if (result.raw === CoolixCommand.Swing) { /* toggle swing */ }
+}
+```
+
+## Supported protocols
+
+| Protocol | Bits | Brand | Type | Features |
+|----------|------|-------|------|----------|
+| NEC | 32 | NEC | Simple | Address + command, repeat detection |
+| Coolix | 24 | Coolix | AC | Temp, mode, fan, zone follow, toggle commands |
+| Daikin64 | 64 | Daikin | AC | Temp, mode, fan, swing, sleep, timers |
+| Daikin128 | 128 | Daikin | AC | BCD temps, nibble checksums, timers |
+| Daikin152 | 152 | Daikin | AC | Quiet, powerful, econo, comfort, sensor |
+| Daikin160 | 160 | Daikin | AC | 5 discrete swing positions |
+| Daikin176 | 176 | Daikin | AC | Unique mode values, horizontal swing |
+| Daikin216 | 216 | Daikin | AC | Vertical + horizontal swing, powerful |
+| DaikinESP | 280 | Daikin | AC | Most features: 0.5°C, timers, mold, comfort |
+| Daikin2 | 312 | Daikin | AC | Eye, purify, fresh air, light, beep |
+| Daikin312 | 312 | Daikin | AC | 0.5°C, eye auto, purify |
+
+## Development
+
+Requires [Bun](https://bun.sh) and a C++ compiler (for cross-validation tests).
+
+```bash
+bun install
+bun test        # Run tests (compiles C++ runner on first run)
+bun run build   # Build ESM + CJS to dist/
+```
+
+The vendored IRremoteESP8266 submodule is used only for testing:
+
+```bash
+git submodule update --init
+```
+
+## License
+
+MIT

package/dist/cjs/decode.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Core IR decoding engine.
+ *
+ * Mirrors the decoding logic of IRremoteESP8266's IRrecv, but operates
+ * on plain timing arrays (in microseconds) instead of hardware capture buffers.
+ */
+/** Default percentage tolerance for timing matches (±25%). */
+export declare const kTolerance = 25;
+/**
+ * Default mark excess in microseconds.
+ * Compensates for sensor lag: marks are captured too long, spaces too short.
+ * Set to 0 for ideal timings (encoder output); increase for real hardware.
+ */
+export declare const kMarkExcess = 0;
+/** Check if a measured timing is within tolerance of a desired value. */
+export declare function matchTiming(measured: number, desired: number, tolerance?: number, delta?: number): boolean;
+/**
+ * Match a mark (IR ON) timing.
+ * Adds excess to desired to compensate for marks being captured too long.
+ */
+export declare function matchMark(measured: number, desired: number, tolerance?: number, excess?: number): boolean;
+/**
+ * Match a space (IR OFF) timing.
+ * Subtracts excess from desired to compensate for spaces being too short.
+ */
+export declare function matchSpace(measured: number, desired: number, tolerance?: number, excess?: number): boolean;
+/**
+ * Match a timing that should be at least as long as desired.
+ * Used for trailing gaps which can be arbitrarily long.
+ */
+export declare function matchAtLeast(measured: number, desired: number, tolerance?: number, delta?: number): boolean;
+export interface MatchDataResult {
+    success: boolean;
+    data: bigint;
+    used: number;
+}
+/**
+ * Decode `nbits` of data from mark/space pairs in a timing array.
+ *
+ * Inverse of `encodeData`. Matches IRremoteESP8266 `IRrecv::matchData`.
+ */
+export declare function matchData(timings: number[], offset: number, nbits: number, oneMark: number, oneSpace: number, zeroMark: number, zeroSpace: number, tolerance?: number, excess?: number, msbFirst?: boolean, expectLastSpace?: boolean): MatchDataResult;
+export interface MatchGenericResult {
+    data: bigint;
+    used: number;
+}
+/**
+ * Generic IR frame decoder for protocols with ≤ 64 data bits.
+ *
+ * Inverse of `sendGeneric`. Matches IRremoteESP8266 `IRrecv::matchGeneric`.
+ *
+ * @returns Decoded data and entries consumed, or null on mismatch.
+ */
+export declare function matchGeneric(timings: number[], offset: number, remaining: number, nbits: number, headerMark: number, headerSpace: number, oneMark: number, oneSpace: number, zeroMark: number, zeroSpace: number, footerMark: number, footerSpace: number, atLeast?: boolean, tolerance?: number, excess?: number, msbFirst?: boolean, headerOptional?: boolean): MatchGenericResult | null;
+export interface MatchGenericBytesResult {
+    data: Uint8Array;
+    used: number;
+}
+/**
+ * Generic IR frame decoder for byte-array protocols (AC protocols).
+ *
+ * Inverse of `sendGenericBytes`. Decodes each byte individually (8 bits).
+ *
+ * @returns Decoded byte array and entries consumed, or null on mismatch.
+ */
+export declare function matchGenericBytes(timings: number[], offset: number, remaining: number, nbytes: number, headerMark: number, headerSpace: number, oneMark: number, oneSpace: number, zeroMark: number, zeroSpace: number, footerMark: number, footerSpace: number, atLeast?: boolean, tolerance?: number, excess?: number, msbFirst?: boolean, headerOptional?: boolean): MatchGenericBytesResult | null;
+import type { NECDecodeResult } from "./protocols/nec.js";
+import type { Daikin64State } from "./protocols/daikin64.js";
+import type { Daikin128State } from "./protocols/daikin128.js";
+import type { Daikin152State } from "./protocols/daikin152.js";
+import type { Daikin160State } from "./protocols/daikin160.js";
+import type { Daikin176State } from "./protocols/daikin176.js";
+import type { Daikin216State } from "./protocols/daikin216.js";
+import type { DaikinESPState } from "./protocols/daikin.js";
+import type { Daikin2State } from "./protocols/daikin2.js";
+import type { Daikin312State } from "./protocols/daikin312.js";
+import type { CoolixState } from "./protocols/coolix.js";
+/** All supported protocol names. */
+export type ProtocolName = "nec" | "daikin64" | "daikin128" | "daikin152" | "daikin160" | "daikin176" | "daikin216" | "daikin" | "daikin2" | "daikin312" | "coolix";
+/** Brand groupings for hint-based filtering. */
+export type BrandName = "nec" | "daikin" | "coolix";
+/** Protocol type groupings. */
+export type ProtocolType = "ac" | "simple";
+/** Discriminated union of all possible decode results. */
+export type DecodeResult = {
+    protocol: "nec";
+    brand: "nec";
+    type: "simple";
+    state: NECDecodeResult;
+    confidence: "timing_match";
+} | {
+    protocol: "daikin64";
+    brand: "daikin";
+    type: "ac";
+    state: Daikin64State;
+    confidence: "checksum_valid";
+} | {
+    protocol: "daikin128";
+    brand: "daikin";
+    type: "ac";
+    state: Daikin128State;
+    confidence: "checksum_valid";
+} | {
+    protocol: "daikin152";
+    brand: "daikin";
+    type: "ac";
+    state: Daikin152State;
+    confidence: "checksum_valid";
+} | {
+    protocol: "daikin160";
+    brand: "daikin";
+    type: "ac";
+    state: Daikin160State;
+    confidence: "checksum_valid";
+} | {
+    protocol: "daikin176";
+    brand: "daikin";
+    type: "ac";
+    state: Daikin176State;
+    confidence: "checksum_valid";
+} | {
+    protocol: "daikin216";
+    brand: "daikin";
+    type: "ac";
+    state: Daikin216State;
+    confidence: "checksum_valid";
+} | {
+    protocol: "daikin";
+    brand: "daikin";
+    type: "ac";
+    state: DaikinESPState;
+    confidence: "checksum_valid";
+} | {
+    protocol: "daikin2";
+    brand: "daikin";
+    type: "ac";
+    state: Daikin2State;
+    confidence: "checksum_valid";
+} | {
+    protocol: "daikin312";
+    brand: "daikin";
+    type: "ac";
+    state: Daikin312State;
+    confidence: "checksum_valid";
+} | {
+    protocol: "coolix";
+    brand: "coolix";
+    type: "ac";
+    state: CoolixState;
+    confidence: "checksum_valid";
+} | {
+    protocol: "coolix";
+    brand: "coolix";
+    type: "ac";
+    state: null;
+    raw: number;
+    confidence: "checksum_valid";
+};
+export interface DecodeOptions {
+    /** Try only this specific protocol. */
+    protocol?: ProtocolName;
+    /** Try only protocols from this brand. */
+    brand?: BrandName;
+    /** Try only protocols of this type. */
+    type?: ProtocolType;
+}
+/**
+ * Unified IR decode dispatcher.
+ *
+ * Uses a 3-tier strategy to handle real-world hardware captures where
+ * headers may be missing:
+ *
+ * 1. **Header match at offset 0** — fastest path, handles intact captures.
+ * 2. **Find repeat frame** — scan for inter-frame gaps, try after each gap
+ *    with header required. Handles missing first-frame headers.
+ * 3. **Brute force, header optional** — try at offset 0 relying solely on
+ *    checksum/parity validation. Handles single-frame headerless captures.
+ *
+ * @param timings Raw mark/space timing array in microseconds.
+ * @param options Optional hints to narrow the search.
+ * @returns The first matching protocol's decode result, or null.
+ */
+export declare function decode(timings: number[], options?: DecodeOptions): DecodeResult | null;
+//# sourceMappingURL=decode.d.ts.map

package/dist/cjs/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/decode.ts"],"names":[],"mappings":"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"}