@kb1rma/libcomm14cux-ts 0.0.0

package/src/errors.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 comm14cux-ts contributors
+
+/** Base class for every error thrown by this library. */
+export class Comm14cuxError extends Error {
+  /** The name of this error class. */
+  override name = 'Comm14cuxError';
+}
+
+/** The ECU (or serial port) did not deliver the expected bytes in time. */
+export class TimeoutError extends Comm14cuxError {
+  /** The name of this error class. */
+  override name = 'TimeoutError';
+}
+
+/** The ECU's reply did not match the protocol (for example a wrong echo). */
+export class ProtocolError extends Comm14cuxError {
+  /** The name of this error class. */
+  override name = 'ProtocolError';
+}
+
+/** An operation was attempted while the transport was not open. */
+export class NotConnectedError extends Comm14cuxError {
+  /** The name of this error class. */
+  override name = 'NotConnectedError';
+}
+
+/** A multi-chunk read was stopped by `cancelRead()`. */
+export class ReadCancelledError extends Comm14cuxError {
+  /** The name of this error class. */
+  override name = 'ReadCancelledError';
+}
+
+/** The ECU returned data that is outside the range the firmware can produce. */
+export class InvalidReadingError extends Comm14cuxError {
+  /** The name of this error class. */
+  override name = 'InvalidReadingError';
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 comm14cux-ts contributors
+
+export { Ecu, type EcuOptions, type FuelMap } from './ecu.js';
+export * from './constants.js';
+export * from './errors.js';
+export type { Transport } from './transport/types.js';
+export { SimulatedTransport } from './transport/simulated.js';
+export {
+  WebSerialTransport,
+  type WebSerialTransportOptions,
+} from './transport/webSerial.js';
+export type { FaultCodes, FaultCodeName } from './decoders/faultCodes.js';
+export type { FuelMapIndex } from './decoders/fuelMap.js';
+export type { TuneRevision } from './decoders/tuneRevision.js';
+export type { Version } from './version.js';

package/src/protocol/protocol.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Derived from libcomm14cux (https://github.com/colinbourassa/libcomm14cux)
+// Copyright (C) Colin Bourassa. Licensed under the GNU GPL v3.
+// Ported to TypeScript and modified for comm14cux-ts, 2026.
+import { DEFAULT_READ_TIMEOUT_MS } from '../constants.js';
+import { ProtocolError, ReadCancelledError } from '../errors.js';
+import type { Transport } from '../transport/types.js';
+import { nextRead } from './readCount.js';
+
+const ADDRESS_SPACE = 0x10000;
+const COARSE_WINDOW = 64;
+// Writes use the coarse-address command with a length code of 0.
+const WRITE_LENGTH_CODE = 0;
+
+/**
+ * Memory read and write commands over a `Transport`
+ * (`protocol.c`: `c14cux_readMem`, `c14cux_writeMem`).
+ *
+ * This class is not re-entrant: callers must serialise operations (the
+ * `Ecu` class does so with a `CommandQueue`). Cancellation is decided by the
+ * caller, through the `isCancelled` callback given to `readMem`.
+ */
+export class Protocol {
+  readonly #transport: Transport;
+  readonly #timeoutMs: number;
+  #lastReadCoarseAddress = 0;
+  #lastReadQuantity = 0;
+
+  /**
+   * Creates a protocol handler.
+   *
+   * @param transport - The link to the ECU.
+   * @param timeoutMs - Silence timeout for each read, in milliseconds.
+   */
+  constructor(transport: Transport, timeoutMs = DEFAULT_READ_TIMEOUT_MS) {
+    this.#transport = transport;
+    this.#timeoutMs = timeoutMs;
+  }
+
+  /** Forgets the last coarse address, forcing the next read to set it. */
+  resetCache(): void {
+    this.#lastReadCoarseAddress = 0;
+    this.#lastReadQuantity = 0;
+  }
+
+  /**
+   * Reads `length` bytes starting at `addr`, splitting long reads into chunks
+   * (`c14cux_readMem`).
+   *
+   * @param addr - First address to read, 0 to 0xFFFF.
+   * @param length - Number of bytes to read. `addr + length` must not exceed 0x10000.
+   * @param isCancelled - Checked before each chunk of a multi-chunk read; a
+   * read that fits in one chunk is never cancelled.
+   * @returns The bytes read.
+   * @throws {@link RangeError} if the address or length is out of range.
+   * @throws {@link ReadCancelledError} if `isCancelled` returns `true`.
+   * @throws {@link ProtocolError} if an echo is wrong.
+   * @throws {@link TimeoutError} if the ECU stops responding.
+   */
+  async readMem(
+    addr: number,
+    length: number,
+    isCancelled: () => boolean,
+  ): Promise<Uint8Array> {
+    assertUint16(addr, 'address');
+    assertUint16(length, 'length');
+
+    if (addr + length > ADDRESS_SPACE) {
+      throw new RangeError('Read extends past the end of the address space');
+    }
+
+    const result = new Uint8Array(length);
+    const multiChunk = nextRead(length, 0).count < length;
+    let totalRead = 0;
+
+    try {
+      while (totalRead < length) {
+        if (multiChunk && isCancelled()) {
+          throw new ReadCancelledError('Read cancelled');
+        }
+
+        const { count: quantity, code } = nextRead(length, totalRead);
+        const chunkAddr = addr + totalRead;
+
+        // The ECU latches only the 64-byte-aligned block (addr >> 6), so the
+        // final command byte alone is enough only within that same block.
+        const lastByteOnly =
+          quantity === this.#lastReadQuantity &&
+          Math.trunc(chunkAddr / COARSE_WINDOW) ===
+            Math.trunc(this.#lastReadCoarseAddress / COARSE_WINDOW);
+
+        if (!lastByteOnly) {
+          await this.setCoarseAddr(chunkAddr, code);
+          this.#lastReadCoarseAddress = chunkAddr;
+        }
+
+        // The ECU does not echo the read command; it starts sending data.
+        await this.#transport.write(Uint8Array.of(0xc0 | (chunkAddr & 0x3f)));
+        result.set(
+          await this.#transport.read(quantity, this.#timeoutMs),
+          totalRead,
+        );
+        totalRead += quantity;
+        this.#lastReadQuantity = quantity;
+      }
+    } catch (error) {
+      this.resetCache();
+      throw error;
+    }
+
+    return result;
+  }
+
+  /**
+   * Writes one byte to ECU memory (`c14cux_writeMem`).
+   *
+   * @param addr - Address to write, 0 to 0xFFFF.
+   * @param value - Byte to write, 0 to 255.
+   * @throws {@link RangeError} if the address or value is out of range.
+   * @throws {@link ProtocolError} if an echo is wrong.
+   * @throws {@link TimeoutError} if the ECU stops responding.
+   */
+  async writeMem(addr: number, value: number): Promise<void> {
+    assertUint16(addr, 'address');
+
+    if (!Number.isInteger(value) || value < 0 || value > 0xff) {
+      throw new RangeError(`Invalid value: ${value}`);
+    }
+
+    this.resetCache();
+    await this.setCoarseAddr(addr, WRITE_LENGTH_CODE);
+    await this.#sendEchoed(0x80 | (addr & 0x3f));
+    await this.#sendEchoed(value);
+  }
+
+  /**
+   * Sets the coarse address and length code for the next command
+   * (`c14cux_setCoarseAddr`).
+   *
+   * @param addr - Address of the read or write, 0 to 0xFFFF.
+   * @param code - Length code of the following read, or 0 for a write.
+   * @throws {@link ProtocolError} if an echo is wrong.
+   * @throws {@link TimeoutError} if the ECU stops responding.
+   */
+  async setCoarseAddr(addr: number, code: number): Promise<void> {
+    await this.#sendEchoed(((code << 2) | (addr >> 14)) & 0xff);
+    await this.#sendEchoed((addr >> 6) & 0xff);
+  }
+
+  async #sendEchoed(byte: number): Promise<void> {
+    await this.#transport.write(Uint8Array.of(byte));
+
+    const [echo] = await this.#transport.read(1, this.#timeoutMs);
+
+    if (echo !== byte) {
+      throw new ProtocolError(
+        `Echo mismatch: sent 0x${byte.toString(16)}, received 0x${(echo ?? 0).toString(16)}`,
+      );
+    }
+  }
+}
+
+function assertUint16(value: number, name: string): void {
+  if (!Number.isInteger(value) || value < 0 || value >= ADDRESS_SPACE) {
+    throw new RangeError(`Invalid ${name}: ${value}`);
+  }
+}

package/src/protocol/readCount.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Derived from libcomm14cux (https://github.com/colinbourassa/libcomm14cux)
+// Copyright (C) Colin Bourassa. Licensed under the GNU GPL v3.
+// Ported to TypeScript and modified for comm14cux-ts, 2026.
+import { ReadCount, ReadCountValue } from '../constants.js';
+
+/**
+ * A single read request: how many bytes, and the length code that asks the
+ * ECU for them.
+ */
+export interface ReadChunk {
+  /** Number of bytes the ECU will return. */
+  count: number;
+  /** 5-bit length code for the coarse-address command. */
+  code: number;
+}
+
+const PRESETS: readonly ReadChunk[] = [
+  { count: ReadCount.Count4, code: ReadCountValue.Count4 },
+  { count: ReadCount.Count3, code: ReadCountValue.Count3 },
+  { count: ReadCount.Count2, code: ReadCountValue.Count2 },
+  { count: ReadCount.Count1, code: ReadCountValue.Count1 },
+];
+
+/**
+ * Chooses the next single read (`c14cux_getByteCountForNextRead`). The ECU
+ * can return 1 to 16, 80, 100, 400 or 512 bytes; 1 to 16 bytes use the code
+ * `count - 1`.
+ *
+ * @param total - Total bytes being read over all requests.
+ * @param alreadyRead - Bytes read so far; less than `total`.
+ * @returns 512, 400, 100 or 80 bytes if that many remain, otherwise up to 16.
+ */
+export function nextRead(total: number, alreadyRead: number): ReadChunk {
+  const bytesLeft = total - alreadyRead;
+  const preset = PRESETS.find(({ count }) => bytesLeft >= count);
+
+  if (preset) {
+    return preset;
+  }
+
+  const count = Math.min(bytesLeft, ReadCount.Count0);
+
+  return { count, code: count - 1 };
+}

package/src/queue.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 comm14cux-ts contributors
+
+/**
+ * Runs asynchronous tasks one at a time, in submission order. Replaces the
+ * per-connection mutex that libcomm14cux holds around each operation.
+ */
+export class CommandQueue {
+  #tail: Promise<unknown> = Promise.resolve();
+
+  /**
+   * Queues a task and runs it once all earlier tasks have settled.
+   *
+   * @param task - Function that performs the work.
+   * @returns The task's result. If the task rejects, only this call rejects.
+   */
+  run<T>(task: () => Promise<T>): Promise<T> {
+    const result = this.#tail.then(task);
+
+    this.#tail = result.catch(() => undefined);
+
+    return result;
+  }
+}

package/src/test-support/ecu.ts

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Derived from libcomm14cux (https://github.com/colinbourassa/libcomm14cux)
+// Copyright (C) Colin Bourassa. Licensed under the GNU GPL v3.
+// Ported to TypeScript and modified for comm14cux-ts, 2026.
+
+// Helpers shared by the test files. Everything here goes through the
+// package entry point, as a user of the library would.
+import { DataOffsetRev, Ecu, SimulatedTransport } from '../index.js';
+
+/**
+ * Creates an `Ecu` over a fresh `SimulatedTransport` and connects it.
+ *
+ * @returns The connected `Ecu` and the simulated ECU behind it.
+ */
+export async function connected(): Promise<{
+  transport: SimulatedTransport;
+  ecu: Ecu;
+}> {
+  const transport = new SimulatedTransport();
+  const ecu = new Ecu(transport, { readTimeoutMs: 5 });
+
+  await ecu.connect();
+
+  return { transport, ecu };
+}
+
+/**
+ * Fills the simulated memory with a non-repeating pattern, so a read from
+ * the wrong address cannot pass by accident.
+ *
+ * @param transport - The simulated ECU.
+ */
+export function fillPattern(transport: SimulatedTransport): void {
+  transport.memory.forEach((_, i) => {
+    transport.memory[i] = (i * 7 + (i >> 8)) & 0xff;
+  });
+}
+
+/**
+ * Sets memory so that the ROM looks like the given data layout.
+ *
+ * @param transport - The simulated ECU.
+ * @param rev - The layout to imitate.
+ */
+export function setRevision(
+  transport: SimulatedTransport,
+  rev: DataOffsetRev,
+): void {
+  if (rev === DataOffsetRev.RevC) {
+    transport.memory[0xc23f] = 0x40;
+  } else {
+    transport.memory.fill(0x10, 0xc23f, 0xc23f + 16);
+    transport.memory[0xc79b] = rev === DataOffsetRev.RevA ? 0xff : 0x64;
+  }
+}
+
+/** One command sent to the ECU, decoded from the transport's write log. */
+export type WireCommand =
+  | { kind: 'coarse'; lengthCode: number; address: number }
+  | { kind: 'read'; low: number }
+  | { kind: 'write'; low: number; value: number };
+
+/**
+ * Splits the bytes written to the ECU back into commands.
+ *
+ * @param written - `SimulatedTransport.written`.
+ * @returns The commands, in order.
+ */
+export function parseWire(written: readonly number[]): WireCommand[] {
+  const commands: WireCommand[] = [];
+
+  for (let i = 0; i < written.length; i++) {
+    const byte = written[i] ?? 0;
+
+    if (byte < 0x80) {
+      const second = written[++i] ?? 0;
+
+      commands.push({
+        kind: 'coarse',
+        lengthCode: byte >> 2,
+        address: ((byte & 0x03) << 14) | (second << 6),
+      });
+    } else if (byte >= 0xc0) {
+      commands.push({ kind: 'read', low: byte & 0x3f });
+    } else {
+      commands.push({
+        kind: 'write',
+        low: byte & 0x3f,
+        value: written[++i] ?? 0,
+      });
+    }
+  }
+
+  return commands;
+}
+
+const PRESET_LENGTHS: Record<number, number> = {
+  0x10: 80,
+  0x11: 100,
+  0x12: 400,
+  0x13: 512,
+};
+
+/**
+ * Gives the size of each read chunk the ECU was asked for.
+ *
+ * @param written - `SimulatedTransport.written`.
+ * @returns One length per read command, in order.
+ */
+export function readChunkLengths(written: readonly number[]): number[] {
+  const lengths: number[] = [];
+  let current = 0;
+
+  for (const command of parseWire(written)) {
+    if (command.kind === 'coarse') {
+      current =
+        command.lengthCode <= 0x0f
+          ? command.lengthCode + 1
+          : (PRESET_LENGTHS[command.lengthCode] ?? -1);
+    } else if (command.kind === 'read') {
+      lengths.push(current);
+    }
+  }
+
+  return lengths;
+}

package/src/transport/simulated.ts

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Derived from libcomm14cux (https://github.com/colinbourassa/libcomm14cux)
+// Copyright (C) Colin Bourassa. Licensed under the GNU GPL v3.
+// Ported to TypeScript and modified for comm14cux-ts, 2026.
+import { NotConnectedError, TimeoutError } from '../errors.js';
+import { DataSize, MemoryOffset, ReadCountValue } from '../constants.js';
+import type { Transport } from './types.js';
+
+const MEMORY_SIZE = 0x10000;
+
+type State = 'idle' | 'coarse2' | 'writeValue';
+
+function lengthFromCode(code: number): number | undefined {
+  if (code <= 0x0f) {
+    return code + 1;
+  }
+
+  switch (code) {
+    case ReadCountValue.Count1:
+      return 0x50;
+    case ReadCountValue.Count2:
+      return 0x64;
+    case ReadCountValue.Count3:
+      return 0x190;
+    case ReadCountValue.Count4:
+      return 0x200;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Emulates the ECU's side of the serial protocol over an in-memory 64 KiB
+ * address space. Used for tests and for developing a UI without a car.
+ */
+export class SimulatedTransport implements Transport {
+  /** The ECU's address space. Tests may read and modify it directly. */
+  readonly memory = new Uint8Array(MEMORY_SIZE);
+  /** Every byte written to the ECU, in order. */
+  readonly written: number[] = [];
+
+  /** Fault injection: invert the next echoed byte. */
+  corruptNextEcho = false;
+  /** Fault injection: never reply. */
+  silent = false;
+  /** Fault injection: reject every write. */
+  failWrites = false;
+  /** Fault injection: stream at most this many bytes per read command. */
+  streamLimit: number | undefined = undefined;
+
+  #open = false;
+  #state: State = 'idle';
+  #output: number[] = [];
+  #firstCoarse = 0;
+  #coarse = 0;
+  #latched = false;
+  #lengthCode = 0;
+  #writeAddr = 0;
+
+  /**
+   * Whether the transport is open.
+   *
+   * @returns `true` between {@link SimulatedTransport.open} and {@link SimulatedTransport.close}.
+   */
+  get isOpen(): boolean {
+    return this.#open;
+  }
+
+  /**
+   * Places a 16 KiB firmware image at 0xC000 to 0xFFFF.
+   *
+   * @param image - The ROM image, exactly 0x4000 bytes.
+   * @throws {@link RangeError} if the image is the wrong size.
+   */
+  loadRom(image: Uint8Array): void {
+    if (image.length !== DataSize.ROM) {
+      throw new RangeError(`ROM image must be ${DataSize.ROM} bytes`);
+    }
+
+    this.memory.set(image, MemoryOffset.ROMAddress);
+  }
+
+  /**
+   * Opens the simulated link.
+   *
+   * @returns A promise that resolves immediately.
+   */
+  open(): Promise<void> {
+    this.#open = true;
+
+    return Promise.resolve();
+  }
+
+  /**
+   * Closes the simulated link and discards any pending ECU output.
+   *
+   * @returns A promise that resolves immediately.
+   */
+  close(): Promise<void> {
+    this.#open = false;
+    this.#state = 'idle';
+    this.#latched = false;
+    this.#output = [];
+
+    return Promise.resolve();
+  }
+
+  /**
+   * Delivers bytes to the simulated ECU, which may queue a reply.
+   *
+   * @param data - Bytes to send.
+   * @returns A promise that resolves once the bytes are delivered.
+   * @throws {@link NotConnectedError} if the transport is closed.
+   * @throws Error if {@link SimulatedTransport.failWrites} is set.
+   */
+  write(data: Uint8Array): Promise<void> {
+    if (!this.#open) {
+      return Promise.reject(new NotConnectedError('Transport is not open'));
+    }
+
+    if (this.failWrites) {
+      return Promise.reject(new Error('Simulated write failure'));
+    }
+
+    for (const byte of data) {
+      this.written.push(byte);
+      this.#receive(byte);
+    }
+
+    return Promise.resolve();
+  }
+
+  /**
+   * Takes bytes from the simulated ECU's reply.
+   *
+   * @param length - Number of bytes wanted.
+   * @param _timeoutMs - Ignored; the simulation answers immediately.
+   * @returns Exactly `length` bytes.
+   * @throws {@link TimeoutError} if the ECU has not produced that many bytes.
+   * @throws {@link NotConnectedError} if the transport is closed.
+   */
+  read(length: number, _timeoutMs: number): Promise<Uint8Array> {
+    if (!this.#open) {
+      return Promise.reject(new NotConnectedError('Transport is not open'));
+    }
+
+    if (this.#output.length < length) {
+      this.#output = [];
+
+      return Promise.reject(new TimeoutError('Simulated ECU is silent'));
+    }
+
+    return Promise.resolve(Uint8Array.from(this.#output.splice(0, length)));
+  }
+
+  #echo(byte: number): void {
+    if (this.silent) {
+      return;
+    }
+
+    if (this.corruptNextEcho) {
+      this.corruptNextEcho = false;
+      this.#output.push(byte ^ 0xff);
+    } else {
+      this.#output.push(byte);
+    }
+  }
+
+  #receive(byte: number): void {
+    if (this.#state === 'writeValue') {
+      this.memory[this.#writeAddr] = byte;
+      this.#echo(byte);
+      this.#state = 'idle';
+      this.#latched = false;
+
+      return;
+    }
+
+    if (this.#state === 'coarse2') {
+      this.#coarse = ((this.#firstCoarse & 0x03) << 14) | (byte << 6);
+      this.#lengthCode = (this.#firstCoarse >> 2) & 0x1f;
+      this.#echo(byte);
+      this.#state = 'idle';
+      this.#latched = true;
+
+      return;
+    }
+
+    if (byte < 0x80) {
+      this.#firstCoarse = byte;
+      this.#echo(byte);
+      this.#state = 'coarse2';
+      this.#latched = false;
+    } else if (!this.#latched) {
+      // A command byte without a preceding coarse address is ignored.
+    } else if ((byte & 0xc0) === 0xc0) {
+      this.#streamRead(this.#coarse | (byte & 0x3f));
+    } else {
+      this.#writeAddr = this.#coarse | (byte & 0x3f);
+      this.#echo(byte);
+      this.#state = 'writeValue';
+    }
+  }
+
+  #streamRead(address: number): void {
+    if (this.silent) {
+      return;
+    }
+
+    let length = lengthFromCode(this.#lengthCode) ?? 0;
+
+    if (this.streamLimit !== undefined) {
+      length = Math.min(length, this.streamLimit);
+    }
+
+    for (let i = 0; i < length; i++) {
+      this.#output.push(this.memory[(address + i) % MEMORY_SIZE] ?? 0);
+    }
+  }
+}

package/src/transport/types.ts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 comm14cux-ts contributors
+
+/** Byte-level link to the ECU. The protocol layer uses nothing else. */
+export interface Transport {
+  open(): Promise<void>;
+  close(): Promise<void>;
+  write(data: Uint8Array): Promise<void>;
+  /** Resolves with exactly `length` bytes, or rejects with a TimeoutError. */
+  read(length: number, timeoutMs: number): Promise<Uint8Array>;
+}