@kb1rma/libcomm14cux-ts 0.0.0

package/src/constants.ts

@@ -0,0 +1,175 @@
+// 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.
+
+/** Baud rate of the 14CUX serial port. */
+export const BAUD = 7812;
+
+/** Baud rate used by ECUs running modified double-speed firmware. */
+export const BAUD_DOUBLE_SPEED = 15625;
+
+/** Number of engine speed ranges in the fuel maps. */
+export const FUEL_MAP_COLUMNS = 16;
+
+/** Number of engine load ranges in the fuel maps. */
+export const FUEL_MAP_ROWS = 8;
+
+/** Byte quantities that may be requested in a single read (`c14cux_readcount`). */
+export const ReadCount = {
+  Count0: 0x0010,
+  Count1: 0x0050,
+  Count2: 0x0064,
+  Count3: 0x0190,
+  Count4: 0x0200,
+} as const;
+
+/** Length codes sent to the ECU for the fixed read quantities. */
+export const ReadCountValue = {
+  Count1: 0x10,
+  Count2: 0x11,
+  Count3: 0x12,
+  Count4: 0x13,
+} as const;
+
+/** Sizes in bytes of fixed-size structures within the ROM. */
+export const DataSize = {
+  ROM: 0x4000,
+  FuelMap: 0x80,
+} as const;
+
+/** Important memory offsets in the ECU's address space (`c14cux_memory_offset`). */
+export const MemoryOffset = {
+  ROMAddress: 0xc000,
+  RPMTable: 0xc800,
+  Port1: 0x0002,
+  LongTermLambdaFuelingTrimOdd: 0x0042,
+  LongTermLambdaFuelingTrimEven: 0x0046,
+  ShortTermLambdaFuelingTrimOdd: 0x0065,
+  ShortTermLambdaFuelingTrimEven: 0x0067,
+  FaultCodes: 0x0049,
+  ThrottleMinimumPosition: 0x0051,
+  MainVoltage: 0x0055,
+  MassAirflowDirect: 0x0057,
+  ThrottlePosition: 0x005f,
+  CoolantTemp: 0x006a,
+  IdleBypassPosition: 0x006d,
+  EngineSpeedInstantaneous: 0x007a,
+  EngineSpeedFiltered: 0x007c,
+  InjectorPulseWidth: 0x0082,
+  Bits008A: 0x008a,
+  PurgeValveState: 0x0096,
+  Bits00DD: 0x00dd,
+  TransmissionGear: 0x2000,
+  RoadSpeed: 0x2003,
+  FuelTemp: 0x2006,
+  RowScaler: 0x200a,
+  RPMLimit: 0x200c,
+  IdleMode: 0x2047,
+  MassAirflowLinear: 0x204d,
+  TargetIdleSpeed: 0x2051,
+  RevBMainVoltageFactorA: 0xc79b,
+  RevBMainVoltageFactorB: 0xc79c,
+  RevBMainVoltageFactorC: 0xc79d,
+  RevCMainVoltageFactorA: 0xc7c3,
+  RevCMainVoltageFactorB: 0xc7c4,
+  RevCMainVoltageFactorC: 0xc7c5,
+  MAFRowScaler: 0xc1c7,
+  Map0RowScalerInitValue: 0xc1c9,
+  FuelMap0: 0xc000,
+  NewFuelMap1: 0xc267,
+  NewFuelMap2: 0xc379,
+  NewFuelMap3: 0xc48b,
+  NewFuelMap4: 0xc59d,
+  NewFuelMap5: 0xc6af,
+  OldFuelMap1: 0xc23f,
+  OldFuelMap2: 0xc351,
+  OldFuelMap3: 0xc463,
+  OldFuelMap4: 0xc575,
+  OldFuelMap5: 0xc687,
+  TuneRevision: 0xffe9,
+  ChecksumFixer: 0xffeb,
+  TuneIdent: 0xffec,
+  CurrentFuelMapId: 0x202c,
+  FuelMapRowIndex: 0x005b,
+  FuelMapColumnIndex: 0x005c,
+  IdleAirControlStepCount: 0x0075,
+  FuelPumpTimer: 0x00af,
+} as const;
+
+/** Offset from the start of a fuel map to its row scaler. */
+export const FUEL_MAP_ROW_SCALER_OFFSET = 0x10a;
+
+/** Fixed main-voltage coefficients for very old ECUs (1990 and earlier). */
+export const RevAMainVoltageFactor = {
+  A: 0x64,
+  B: 0xbd,
+  C: 0x6180,
+} as const;
+
+/** Transmission gear selections. */
+export const Gear = {
+  NoReading: 0,
+  ParkOrNeutral: 1,
+  DriveOrReverse: 2,
+  ManualGearbox: 3,
+} as const;
+/**
+ * Union of the {@link Gear} values.
+ */
+export type Gear = (typeof Gear)[keyof typeof Gear];
+
+/** The two engine banks. */
+export const Bank = { Odd: 0, Even: 1 } as const;
+/**
+ * Union of the {@link Bank} values.
+ */
+export type Bank = (typeof Bank)[keyof typeof Bank];
+
+/** Types of lambda trim for fueling. */
+export const LambdaTrimType = { ShortTerm: 0, LongTerm: 1 } as const;
+/**
+ * Union of the {@link LambdaTrimType} values.
+ */
+export type LambdaTrimType =
+  (typeof LambdaTrimType)[keyof typeof LambdaTrimType];
+
+/** Fueling feedback modes. */
+export const FeedbackMode = { ClosedLoop: 0, OpenLoop: 1 } as const;
+/**
+ * Union of the {@link FeedbackMode} values.
+ */
+export type FeedbackMode = (typeof FeedbackMode)[keyof typeof FeedbackMode];
+
+/** The two means of reading a value from the MAF. */
+export const AirflowType = { Direct: 0, Linearized: 1 } as const;
+/**
+ * Union of the {@link AirflowType} values.
+ */
+export type AirflowType = (typeof AirflowType)[keyof typeof AirflowType];
+
+/** The two methods of interpreting a throttle position. */
+export const ThrottlePosType = { Absolute: 0, Corrected: 1 } as const;
+/**
+ * Union of the {@link ThrottlePosType} values.
+ */
+export type ThrottlePosType =
+  (typeof ThrottlePosType)[keyof typeof ThrottlePosType];
+
+/** Revisions of the ROM data layout (`c14cux_data_offset_rev`). */
+export const DataOffsetRev = { Unset: 0, RevA: 1, RevB: 2, RevC: 3 } as const;
+/**
+ * Union of the {@link DataOffsetRev} values.
+ */
+export type DataOffsetRev = (typeof DataOffsetRev)[keyof typeof DataOffsetRev];
+
+/** States of the carbon canister purge valve. */
+export const PurgeValveState = { Closed: 0, Toggling: 1, Open: 2 } as const;
+/**
+ * Union of the {@link PurgeValveState} values.
+ */
+export type PurgeValveState =
+  (typeof PurgeValveState)[keyof typeof PurgeValveState];
+
+/** Default per-read silence timeout, matching libcomm14cux (100 ms). */
+export const DEFAULT_READ_TIMEOUT_MS = 100;

package/src/decoders/airflow.ts

@@ -0,0 +1,41 @@
+// 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 { InvalidReadingError } from '../errors.js';
+
+const DIRECT_MAX = 1023;
+const LINEAR_MAX = 17290;
+
+/**
+ * Decodes the "direct" mass airflow reading, which changes linearly with
+ * sensor voltage but logarithmically with airflow.
+ *
+ * @param raw - The 10-bit reading, 0 to 1023.
+ * @returns Airflow as a fraction from 0 to 1 of the highest measurement.
+ * @throws {@link InvalidReadingError} if `raw` is above 1023.
+ */
+export function decodeMafDirect(raw: number): number {
+  if (raw > DIRECT_MAX) {
+    throw new InvalidReadingError(`MAF direct reading out of range: ${raw}`);
+  }
+
+  return raw / DIRECT_MAX;
+}
+
+/**
+ * Decodes the "linearized" mass airflow reading, which changes linearly with
+ * airflow.
+ *
+ * @param raw - The reading, 0 to 17290.
+ * @returns Airflow as a fraction from 0 to 1 of the highest measurement.
+ * @throws {@link InvalidReadingError} if `raw` is above 17290.
+ */
+export function decodeMafLinear(raw: number): number {
+  if (raw > LINEAR_MAX) {
+    throw new InvalidReadingError(`MAF linear reading out of range: ${raw}`);
+  }
+
+  return raw / LINEAR_MAX;
+}

package/src/decoders/engineSpeed.ts

@@ -0,0 +1,36 @@
+// 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 { InvalidReadingError } from '../errors.js';
+
+/**
+ * Converts a crank pulse width to engine speed (`7500000 / pulseWidth`,
+ * truncated).
+ *
+ * @param pulseWidth - Pulse width in ECU timer ticks. Must not be 0.
+ * @returns Engine speed in revolutions per minute.
+ * @throws {@link InvalidReadingError} if `pulseWidth` is 0. libcomm14cux
+ * divides by zero here, which is undefined behaviour in C.
+ */
+export function pulseWidthToRpm(pulseWidth: number): number {
+  if (pulseWidth === 0) {
+    // libcomm14cux divides by zero here (undefined behaviour in C).
+    throw new InvalidReadingError('Pulse width of zero');
+  }
+
+  return Math.trunc(7500000 / pulseWidth);
+}
+
+/**
+ * Decodes the engine speed from the filtered pulse width. 0xFFFF is the ECU's
+ * initial value with the ignition on and the engine stopped, and means 0 RPM.
+ *
+ * @param pulseWidth - The filtered pulse width, 0 to 0xFFFF.
+ * @returns Engine speed in revolutions per minute.
+ * @throws {@link InvalidReadingError} if `pulseWidth` is 0.
+ */
+export function decodeEngineRpm(pulseWidth: number): number {
+  return pulseWidth === 0xffff ? 0 : pulseWidthToRpm(pulseWidth);
+}

package/src/decoders/faultCodes.ts

@@ -0,0 +1,61 @@
+// 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.
+
+// [byte offset from 0x0049, bit (0 = LSB), name]. Spare bits are omitted.
+// Names follow the field names of `c14cux_faultcodes`.
+const FAULT_BITS = [
+  [0, 0, 'romChecksumFailure'],
+  [0, 1, 'lambdaSensorOdd'],
+  [0, 2, 'lambdaSensorEven'],
+  [0, 4, 'misfireOddBank'],
+  [0, 5, 'misfireEvenBank'],
+  [0, 6, 'airflowMeter'],
+  [0, 7, 'tuneResistorOutOfRange'],
+  [1, 0, 'injectorOddBank'],
+  [1, 2, 'injectorEvenBank'],
+  [1, 3, 'coolantTempSensor'],
+  [1, 4, 'throttlePot'],
+  [1, 5, 'throttlePotHiMafLo'],
+  [1, 6, 'throttlePotLoMafHi'],
+  [1, 7, 'purgeValveLeak'],
+  [2, 1, 'mixtureTooLean'],
+  [2, 3, 'intakeAirLeak'],
+  [3, 0, 'lowFuelPressure'],
+  [3, 4, 'idleValveStepperMotor'],
+  [3, 6, 'roadSpeedSensor'],
+  [3, 7, 'neutralSwitch'],
+  [4, 4, 'lowFuelPressureOrAirLeak'],
+  [4, 5, 'fuelTempSensor'],
+  [5, 6, 'batteryDisconnected'],
+  [5, 7, 'ramChecksumFailure'],
+] as const;
+
+/**
+ * Name of a fault flag in {@link FaultCodes}, taken from the field names of
+ * the C `c14cux_faultcodes` struct.
+ */
+export type FaultCodeName = (typeof FAULT_BITS)[number][2];
+
+/** Fault code flags (`c14cux_faultcodes`); `true` means the fault is set. */
+export type FaultCodes = Record<FaultCodeName, boolean>;
+
+/** Number of bytes in the fault code block at 0x0049. */
+export const FAULT_CODE_BLOCK_SIZE = 6;
+
+/**
+ * Decodes the fault code block into named flags. Spare bits are ignored.
+ *
+ * @param bytes - The six bytes read from 0x0049.
+ * @returns A flag for each fault; `true` means the fault is set.
+ */
+export function decodeFaultCodes(bytes: Uint8Array): FaultCodes {
+  const codes = {} as FaultCodes;
+
+  for (const [byteIndex, bit, name] of FAULT_BITS) {
+    codes[name] = (((bytes[byteIndex] ?? 0) >> bit) & 1) === 1;
+  }
+
+  return codes;
+}

package/src/decoders/flags.ts

@@ -0,0 +1,64 @@
+// 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 { PurgeValveState } from '../constants.js';
+
+/**
+ * Decodes the fuel pump relay line. The relay is closed when bit 6 of port 1 is clear.
+ *
+ * @param port1 - The port 1 byte read from 0x0002.
+ * @returns `true` when the relay is closed (pump running).
+ */
+export const decodeFuelPumpRelay = (port1: number): boolean =>
+  (port1 & 0x40) === 0;
+
+/**
+ * Decodes the malfunction indicator lamp. It is lit when bit 0 of port 1 is clear.
+ *
+ * @param port1 - The port 1 byte read from 0x0002.
+ * @returns `true` when the MIL is lit.
+ */
+export const decodeMilOn = (port1: number): boolean => (port1 & 0x01) === 0;
+
+/**
+ * Decodes idle mode, which is active when bit 0 of 0x2047 is set.
+ *
+ * @param byte - The byte read from 0x2047.
+ * @returns `true` when the ECU is driving an idle speed.
+ */
+export const decodeIdleMode = (byte: number): boolean => (byte & 0x01) === 0x01;
+
+/**
+ * Decodes the heated screen state. It is on when bit 2 of 0x00DD is clear.
+ *
+ * @param bits - The flag byte read from its address.
+ * @returns `true` when the screen heater is on.
+ */
+export const decodeScreenHeater = (bits: number): boolean =>
+  (bits & 0x04) === 0;
+
+/**
+ * Decodes the A/C compressor input. It is on when bit 3 of 0x008A is clear.
+ *
+ * @param bits - The flag byte read from its address.
+ * @returns `true` when the compressor is on.
+ */
+export const decodeAcCompressor = (bits: number): boolean =>
+  (bits & 0x08) === 0;
+
+/**
+ * Decodes the purge valve state from the ECU's 16-bit purge timer, using the
+ * thresholds the ECU itself uses.
+ *
+ * @param timer - The value read from 0x0096.
+ * @returns Closed below 4000, toggling below 29000, otherwise open.
+ */
+export function decodePurgeValveState(timer: number): PurgeValveState {
+  if (timer < 4000) {
+    return PurgeValveState.Closed;
+  }
+
+  return timer < 29000 ? PurgeValveState.Toggling : PurgeValveState.Open;
+}

package/src/decoders/fuelMap.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 {
+  DataOffsetRev,
+  FUEL_MAP_COLUMNS,
+  FUEL_MAP_ROWS,
+  FUEL_MAP_ROW_SCALER_OFFSET,
+  MemoryOffset,
+} from '../constants.js';
+import { InvalidReadingError } from '../errors.js';
+import { pulseWidthToRpm } from './engineSpeed.js';
+
+/**
+ * Where a fuel map lives in ECU memory.
+ */
+export interface FuelMapLocation {
+  /** Address of the 128-byte map; the 2-byte adjustment factor follows it. */
+  offset: number;
+  /** Address of the row scaler byte. */
+  scalerOffset: number;
+}
+
+const OLD_MAPS = [
+  MemoryOffset.OldFuelMap1,
+  MemoryOffset.OldFuelMap2,
+  MemoryOffset.OldFuelMap3,
+  MemoryOffset.OldFuelMap4,
+  MemoryOffset.OldFuelMap5,
+];
+
+const NEW_MAPS = [
+  MemoryOffset.NewFuelMap1,
+  MemoryOffset.NewFuelMap2,
+  MemoryOffset.NewFuelMap3,
+  MemoryOffset.NewFuelMap4,
+  MemoryOffset.NewFuelMap5,
+];
+
+/**
+ * A {@link DataOffsetRev} that has been determined (not `Unset`).
+ */
+export type KnownDataOffsetRev = Exclude<DataOffsetRev, 0>;
+
+/**
+ * Rejects a fuel map id outside 0 to 5.
+ *
+ * @param id - The fuel map id to check.
+ * @throws {@link RangeError} if `id` is not an integer from 0 to 5.
+ */
+export function assertFuelMapId(id: number): void {
+  if (!Number.isInteger(id) || id < 0 || id > 5) {
+    throw new RangeError(`Invalid fuel map id: ${id}`);
+  }
+}
+
+/**
+ * Finds where a fuel map lives for the given ROM data layout.
+ *
+ * @param id - Map id, 0 to 5 (checked by {@link assertFuelMapId}).
+ * @param revision - The ROM's data layout.
+ * @returns The map's address and its row scaler's address.
+ */
+export function fuelMapLocation(
+  id: number,
+  revision: KnownDataOffsetRev,
+): FuelMapLocation {
+  // Map 0 is at the same place in both layouts.
+  if (id === 0) {
+    return {
+      offset: MemoryOffset.FuelMap0,
+      scalerOffset: MemoryOffset.Map0RowScalerInitValue,
+    };
+  }
+
+  const maps = revision === DataOffsetRev.RevC ? NEW_MAPS : OLD_MAPS;
+  const offset = maps[id - 1] ?? 0;
+
+  return { offset, scalerOffset: offset + FUEL_MAP_ROW_SCALER_OFFSET };
+}
+
+/**
+ * Validates the current fuel map id.
+ *
+ * @param id - The byte read from 0x202C.
+ * @returns The map id, 0 to 5.
+ * @throws {@link InvalidReadingError} if `id` is above 5.
+ */
+export function decodeCurrentFuelMap(id: number): number {
+  if (id > 5) {
+    throw new InvalidReadingError(`Invalid fuel map id: ${id}`);
+  }
+
+  return id;
+}
+
+/**
+ * A position within the fuel map and its interpolation weighting.
+ */
+export interface FuelMapIndex {
+  /**
+   * The row or column index.
+   */
+  index: number;
+  /**
+   * The weighting (0 to 15) used to interpolate toward the next row or column.
+   */
+  weighting: number;
+}
+
+function decodeIndex(byte: number, limit: number, what: string): FuelMapIndex {
+  const index = byte >> 4;
+
+  if (index >= limit) {
+    throw new InvalidReadingError(`Invalid fuel map ${what} index: ${index}`);
+  }
+
+  return { index, weighting: byte & 0x0f };
+}
+
+/**
+ * Decodes the row index byte: the high nibble is the row, the low nibble the
+ * weighting.
+ *
+ * @param byte - The byte read from 0x005B.
+ * @returns The row index (0 to 7) and weighting.
+ * @throws {@link InvalidReadingError} if the row index is 8 or more.
+ */
+export const decodeFuelMapRowIndex = (byte: number): FuelMapIndex =>
+  decodeIndex(byte, FUEL_MAP_ROWS, 'row');
+
+/**
+ * Decodes the column index byte: the high nibble is the column, the low nibble
+ * the weighting.
+ *
+ * @param byte - The byte read from 0x005C.
+ * @returns The column index (0 to 15) and weighting.
+ * @throws {@link InvalidReadingError} if the column index is 16 or more.
+ */
+export const decodeFuelMapColumnIndex = (byte: number): FuelMapIndex =>
+  decodeIndex(byte, FUEL_MAP_COLUMNS, 'column');
+
+/**
+ * Gives the address of one entry in the RPM table.
+ *
+ * @param column - Fuel map column, 0 to 15.
+ * @returns The address of the column's two-byte pulse width.
+ */
+export const rpmTableEntryAddress = (column: number): number =>
+  MemoryOffset.RPMTable + column * 4;
+
+/**
+ * Gives the slot in the result array for an RPM table column. The C library
+ * stores column 0 last.
+ *
+ * @param column - Fuel map column, 0 to 15.
+ * @returns The index in the result array.
+ */
+export const rpmTableSlot = (column: number): number =>
+  FUEL_MAP_COLUMNS - column - 1;
+
+/**
+ * Converts one RPM table pulse width to RPM; see {@link pulseWidthToRpm}.
+ */
+export const decodeRpmTableEntry = pulseWidthToRpm;

package/src/decoders/gear.ts

@@ -0,0 +1,26 @@
+// 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 { Gear } from '../constants.js';
+
+/**
+ * Decodes the gear selection from the neutral switch ADC byte. The thresholds
+ * are those hardcoded in the ECU firmware.
+ *
+ * @param adc - The byte read from 0x2000.
+ * @returns Park/neutral below 0x4D, drive/reverse above 0xB3, otherwise manual gearbox.
+ */
+export function decodeGear(adc: number): Gear {
+  if (adc < 0x4d) {
+    return Gear.ParkOrNeutral;
+  }
+
+  if (adc > 0xb3) {
+    return Gear.DriveOrReverse;
+  }
+
+  // Manual gearboxes have a resistor fitted to give a midpoint value.
+  return Gear.ManualGearbox;
+}

package/src/decoders/idleBypass.ts

@@ -0,0 +1,16 @@
+// 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.
+
+const FULLY_CLOSED = 180;
+
+/**
+ * Decodes the idle bypass motor position. 180 counts is fully closed.
+ *
+ * @param raw - The byte read from 0x006D.
+ * @returns Position as a fraction from 0 (closed) to 1 (widest opening).
+ */
+export function decodeIdleBypassPosition(raw: number): number {
+  return (FULLY_CLOSED - Math.min(raw, FULLY_CLOSED)) / FULLY_CLOSED;
+}

package/src/decoders/lambdaTrim.ts

@@ -0,0 +1,24 @@
+// 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.
+
+/**
+ * Decodes a lambda fueling trim. A larger number means more fuel.
+ *
+ * @param raw - The 16-bit value read from the trim location.
+ * @returns Trim in counts, from -256 to 255.
+ */
+export function decodeLambdaTrim(raw: number): number {
+  return Math.trunc(raw / 0x80) - 0x100;
+}
+
+/**
+ * Decodes the MAF CO trim voltage from the even-bank long-term trim value.
+ *
+ * @param raw - The 16-bit value read from 0x0046.
+ * @returns Voltage in volts.
+ */
+export function decodeCoTrimVoltage(raw: number): number {
+  return (5.0 * (raw >> 7)) / 1024.0;
+}

package/src/decoders/mainVoltage.ts

@@ -0,0 +1,37 @@
+// 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 { InvalidReadingError } from '../errors.js';
+
+/**
+ * Reverses the quadratic the ECU applies to the battery voltage ADC count,
+ * then maps the count linearly to volts.
+ *
+ * @param stored - The 16-bit value read from 0x0055.
+ * @param a - First coefficient (a byte).
+ * @param b - Second coefficient (a byte).
+ * @param c - Third coefficient (16 bits).
+ * @returns The main relay voltage in volts.
+ * @throws {@link InvalidReadingError} if the coefficients cannot produce a real
+ * result for `stored`.
+ */
+export function decodeMainVoltage(
+  stored: number,
+  a: number,
+  b: number,
+  c: number,
+): number {
+  const discriminant = 4 * a * stored - a * c + 64 * b * b;
+
+  if (discriminant < 0) {
+    throw new InvalidReadingError(
+      'Main voltage coefficients do not fit reading',
+    );
+  }
+
+  const adcCount = Math.trunc((-16 * (Math.sqrt(discriminant) - 8 * b)) / a);
+
+  return 0.07 * adcCount - 0.09;
+}

package/src/decoders/roadSpeed.ts

@@ -0,0 +1,14 @@
+// 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.
+
+/**
+ * Converts the road speed byte to miles per hour.
+ *
+ * @param kph - The byte read from 0x2003, in kilometres per hour.
+ * @returns Speed in whole miles per hour, truncated.
+ */
+export function decodeRoadSpeedMph(kph: number): number {
+  return Math.trunc(kph * 0.621371192);
+}