@senxor/serial-core 1.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @senxor/serial-core
+
+Shared serial transport layer for Senxor.js. Official packages `@senxor/web-serial` and `@senxor/capacitor-serial` build on this module so the same framing, parsing, and register commands work everywhere.
+
+Most applications should depend on a concrete transport (Web Serial or Capacitor) instead of this package. Use `@senxor/serial-core` when you need to plug Senxor into a new runtime by implementing a thin adapter around your serial API.
+
+## What you get
+
+- **`SerialTransportBase`** – Wraps any port that implements **`ISerialPort`** and exposes `@senxor/core`'s transport contract (`open` / `close`, register read/write, streaming callbacks). Pass the result into `new Senxor(transport)` from `@senxor/core`.
+- **`ISerialPort`**, **`SerialDeviceInfo`**, **`SerialOptions`** – The minimal port surface your adapter must provide (open/close, `write`, event-style `on` for `data`, `error`, `open`, `close`, `disconnect`).
+- **`senxorPortOptions`** – Default serial settings (115200 8N1) used when opening a port for Senxor.
+- **`isSenxorDevice`** – Returns whether USB vendor/product IDs match a known Senxor product (same check the official transports use when listing devices).
+- **`CommandSender`** – Lower-level helper for sending framed commands and matching ACKs; mainly useful if you extend or debug serial behavior rather than typical app code.
+- **`utils`** – Small helpers such as **`toHexString`**, **`decodeUint8Array`**, shared with protocol tooling.
+
+## Installation
+
+```bash
+pnpm add @senxor/core @senxor/serial-core
+```
+
+You still need a real serial backend (browser Web Serial, Capacitor plugin, Node serial library, etc.) that you wrap with `ISerialPort`.
+
+## Development (this repository)
+
+From the monorepo root:
+
+```bash
+pnpm install
+pnpm test --filter @senxor/serial-core
+pnpm build --filter @senxor/serial-core
+```
+
+For how `Senxor` consumes a transport after you wire one up, see `packages/core/README.md` and an official transport package for a full example.

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+//#region src/types.d.ts
+interface SerialDeviceInfo {
+  vendorId: number;
+  productId: number;
+  [key: string]: any;
+}
+interface SerialOptions {
+  baudRate: number;
+  dataBits?: number;
+  stopBits?: number;
+  [key: string]: any;
+}
+interface ISerialPort<TDeviceInfo extends SerialDeviceInfo = SerialDeviceInfo, TOptions extends SerialOptions = SerialOptions> {
+  deviceInfo: TDeviceInfo;
+  isOpen: boolean;
+  open(options?: TOptions): Promise<void>;
+  close(): Promise<void>;
+  write(data: Uint8Array): Promise<void>;
+  on(event: "data", listener: (data: Uint8Array) => void): () => void;
+  on(event: "error", listener: (error: Error) => void): () => void;
+  on(event: "open", listener: () => void): () => void;
+  on(event: "close", listener: () => void): () => void;
+  on(event: "disconnect", listener: () => void): () => void;
+}
+type SenxorCommand = {
+  RREG: {
+    regAddr: number;
+  };
+  WREG: {
+    regAddr: number;
+    regValue: number;
+  };
+  RRSE: {
+    regs: Record<number, number>;
+  };
+};
+type SenxorAck = {
+  RREG: number;
+  WREG: void;
+  RRSE: Record<number, number>;
+  GFRA: {
+    header?: Uint8Array;
+    frame: Uint8Array;
+  };
+  SERR: void;
+};
+//#endregion
+//#region src/command-sender.d.ts
+declare class CommandSender<TPort extends ISerialPort> {
+  private port;
+  private commandMutex;
+  private encoder;
+  private pendingCommand?;
+  private errorListener?;
+  constructor(port: TPort);
+  onError(listener: (error: SenxorTransportError$1) => void): void;
+  sendCommand<K extends keyof SenxorCommand>(type: K, command: string, timeout?: number, attempts?: number): Promise<SenxorAck[K]>;
+  resolveAck<K extends keyof SenxorCommand>(type: K, data: SenxorAck[K]): void;
+  private sendCommandWithRetry;
+  private sendCommandOnce;
+}
+//#endregion
+//#region src/transports.d.ts
+declare const senxorPortOptions: SerialOptions;
+declare class SerialTransportBase<TPort extends ISerialPort> implements ISenxorTransport {
+  private port;
+  private parser;
+  private commandSender;
+  private dataListener?;
+  private errorListener?;
+  private openListener?;
+  private closeListener?;
+  private disconnectListener?;
+  constructor(port: TPort);
+  get isOpen(): boolean;
+  get deviceInfo(): SerialDeviceInfo;
+  open(): Promise<void>;
+  close(): Promise<void>;
+  readReg(address: number): Promise<number>;
+  readRegs(addresses: number[]): Promise<Record<number, number>>;
+  writeReg(address: number, value: number): Promise<void>;
+  onData(listener: (data: SenxorRawData) => void): void;
+  onError(listener: (error: SenxorTransportError) => void): void;
+  onOpen(listener: () => void): void;
+  onClose(listener: () => void): void;
+  onDisconnect(listener: () => void): void;
+  private setupPortEventListeners;
+  private handleMessage;
+  private handlePortDisconnect;
+  private handlePortClose;
+  private handlePortOpen;
+  private handleGfraAck;
+  private handleParserError;
+  private handlePortError;
+  private handleSerrAck;
+  private handleUnknownAck;
+}
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Convert a number to a fixed-length uppercase hexadecimal string
+ * @param value - The number to convert (must be non-negative)
+ * @param length - The desired length of the hex string
+ * @returns The uppercase hex string padded to the specified length
+ * @throws Error if value is negative or produces more digits than length
+ */
+declare const toHexString: (value: number, length: number) => string;
+/**
+ * Decode a Uint8Array to ASCII string
+ * @param buffer - The Uint8Array to decode
+ * @returns The decoded string
+ */
+declare const decodeUint8Array: (buffer: Uint8Array) => string;
+declare const isSenxorDevice: (device: SerialDeviceInfo) => boolean;
+//#endregion
+export { CommandSender, ISerialPort, SenxorAck, SenxorCommand, SerialDeviceInfo, SerialOptions, SerialTransportBase, decodeUint8Array, isSenxorDevice, senxorPortOptions, toHexString };

package/dist/index.js

@@ -0,0 +1,932 @@
+import { Mutex } from "async-mutex";
+import { PrefixLengthParser } from "serial-packet-parser";
+const SENXOR_PRODUCT_ID = {
+	45058: "EVK",
+	45088: "XPRO",
+	37779: "XCAM"
+};
+//#endregion
+//#region ../core/src/error.ts
+var SenxorTransportError = class extends Error {
+	cause;
+	constructor(message, cause) {
+		super(message);
+		this.name = "SenxorTransportError";
+		this.cause = cause;
+	}
+};
+//#endregion
+//#region ../core/src/fields.ts
+const FIELDS = {
+	SW_RESET: {
+		name: "SW_RESET",
+		readable: false,
+		writable: true,
+		addr: 0,
+		startBit: 0,
+		endBit: 1,
+		selfReset: true
+	},
+	DMA_TIMEOUT_ENABLE: {
+		name: "DMA_TIMEOUT_ENABLE",
+		readable: true,
+		writable: true,
+		addr: 1,
+		startBit: 0,
+		endBit: 1,
+		selfReset: false
+	},
+	TIMEOUT_PERIOD: {
+		name: "TIMEOUT_PERIOD",
+		readable: true,
+		writable: true,
+		addr: 1,
+		startBit: 1,
+		endBit: 3,
+		selfReset: false
+	},
+	STOP_HOST_XFER: {
+		name: "STOP_HOST_XFER",
+		readable: true,
+		writable: true,
+		addr: 1,
+		startBit: 3,
+		endBit: 4,
+		selfReset: true
+	},
+	REQ_RETRANSMIT: {
+		name: "REQ_RETRANSMIT",
+		readable: true,
+		writable: true,
+		addr: 25,
+		startBit: 0,
+		endBit: 1,
+		selfReset: true
+	},
+	AUTO_RETRANSMIT: {
+		name: "AUTO_RETRANSMIT",
+		readable: true,
+		writable: true,
+		addr: 25,
+		startBit: 1,
+		endBit: 2,
+		selfReset: false
+	},
+	GET_SINGLE_FRAME: {
+		name: "GET_SINGLE_FRAME",
+		readable: true,
+		writable: true,
+		addr: 177,
+		startBit: 0,
+		endBit: 1,
+		selfReset: true
+	},
+	CONTINUOUS_STREAM: {
+		name: "CONTINUOUS_STREAM",
+		readable: true,
+		writable: true,
+		addr: 177,
+		startBit: 1,
+		endBit: 2,
+		selfReset: false
+	},
+	READOUT_MODE: {
+		name: "READOUT_MODE",
+		readable: true,
+		writable: true,
+		addr: 177,
+		startBit: 2,
+		endBit: 5,
+		selfReset: false
+	},
+	NO_HEADER: {
+		name: "NO_HEADER",
+		readable: true,
+		writable: true,
+		addr: 177,
+		startBit: 5,
+		endBit: 6,
+		selfReset: false
+	},
+	ADC_ENABLE: {
+		name: "ADC_ENABLE",
+		readable: true,
+		writable: true,
+		addr: 177,
+		startBit: 7,
+		endBit: 8,
+		selfReset: false
+	},
+	FW_VERSION_MAJOR: {
+		name: "FW_VERSION_MAJOR",
+		readable: true,
+		writable: false,
+		addr: 178,
+		startBit: 4,
+		endBit: 8,
+		selfReset: false
+	},
+	FW_VERSION_MINOR: {
+		name: "FW_VERSION_MINOR",
+		readable: true,
+		writable: false,
+		addr: 178,
+		startBit: 0,
+		endBit: 4,
+		selfReset: false
+	},
+	FW_VERSION_BUILD: {
+		name: "FW_VERSION_BUILD",
+		readable: true,
+		writable: false,
+		addr: 179,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	FRAME_RATE_DIVIDER: {
+		name: "FRAME_RATE_DIVIDER",
+		readable: true,
+		writable: true,
+		addr: 180,
+		startBit: 0,
+		endBit: 7,
+		selfReset: false
+	},
+	SLEEP_PERIOD: {
+		name: "SLEEP_PERIOD",
+		readable: true,
+		writable: true,
+		addr: 181,
+		startBit: 0,
+		endBit: 6,
+		selfReset: false
+	},
+	PERIOD_X100: {
+		name: "PERIOD_X100",
+		readable: true,
+		writable: true,
+		addr: 181,
+		startBit: 6,
+		endBit: 7,
+		selfReset: false
+	},
+	SLEEP: {
+		name: "SLEEP",
+		readable: true,
+		writable: true,
+		addr: 181,
+		startBit: 7,
+		endBit: 8,
+		selfReset: true
+	},
+	READOUT_TOO_SLOW: {
+		name: "READOUT_TOO_SLOW",
+		readable: true,
+		writable: false,
+		addr: 182,
+		startBit: 1,
+		endBit: 2,
+		selfReset: true
+	},
+	SENXOR_IF_ERROR: {
+		name: "SENXOR_IF_ERROR",
+		readable: true,
+		writable: false,
+		addr: 182,
+		startBit: 2,
+		endBit: 3,
+		selfReset: false
+	},
+	CAPTURE_ERROR: {
+		name: "CAPTURE_ERROR",
+		readable: true,
+		writable: false,
+		addr: 182,
+		startBit: 3,
+		endBit: 4,
+		selfReset: false
+	},
+	DATA_READY: {
+		name: "DATA_READY",
+		readable: true,
+		writable: false,
+		addr: 182,
+		startBit: 4,
+		endBit: 5,
+		selfReset: false
+	},
+	BOOTING_UP: {
+		name: "BOOTING_UP",
+		readable: true,
+		writable: false,
+		addr: 182,
+		startBit: 5,
+		endBit: 6,
+		selfReset: false
+	},
+	CLK_SLOW_DOWN: {
+		name: "CLK_SLOW_DOWN",
+		readable: true,
+		writable: true,
+		addr: 183,
+		startBit: 0,
+		endBit: 1,
+		selfReset: false
+	},
+	MODULE_GAIN: {
+		name: "MODULE_GAIN",
+		readable: true,
+		writable: true,
+		addr: 185,
+		startBit: 0,
+		endBit: 4,
+		selfReset: false
+	},
+	SENXOR_TYPE: {
+		name: "SENXOR_TYPE",
+		readable: true,
+		writable: false,
+		addr: 186,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	MODULE_TYPE: {
+		name: "MODULE_TYPE",
+		readable: true,
+		writable: false,
+		addr: 187,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	MCU_TYPE: {
+		name: "MCU_TYPE",
+		readable: true,
+		writable: false,
+		addr: 51,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	LUT_SOURCE: {
+		name: "LUT_SOURCE",
+		readable: true,
+		writable: true,
+		addr: 188,
+		startBit: 0,
+		endBit: 1,
+		selfReset: false
+	},
+	LUT_SELECTOR: {
+		name: "LUT_SELECTOR",
+		readable: true,
+		writable: true,
+		addr: 188,
+		startBit: 1,
+		endBit: 3,
+		selfReset: false
+	},
+	LUT_VERSION: {
+		name: "LUT_VERSION",
+		readable: true,
+		writable: false,
+		addr: 188,
+		startBit: 4,
+		endBit: 8,
+		selfReset: false
+	},
+	CORR_FACTOR: {
+		name: "CORR_FACTOR",
+		readable: true,
+		writable: true,
+		addr: 194,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	START_COLOFFS_CALIB: {
+		name: "START_COLOFFS_CALIB",
+		readable: true,
+		writable: true,
+		addr: 197,
+		startBit: 1,
+		endBit: 2,
+		selfReset: true
+	},
+	COLOFFS_CALIB_ON: {
+		name: "COLOFFS_CALIB_ON",
+		readable: true,
+		writable: false,
+		addr: 197,
+		startBit: 2,
+		endBit: 3,
+		selfReset: false
+	},
+	USE_SELF_CALIB: {
+		name: "USE_SELF_CALIB",
+		readable: true,
+		writable: true,
+		addr: 197,
+		startBit: 4,
+		endBit: 5,
+		selfReset: true
+	},
+	CALIB_SAMPLE_SIZE: {
+		name: "CALIB_SAMPLE_SIZE",
+		readable: true,
+		writable: true,
+		addr: 197,
+		startBit: 5,
+		endBit: 8,
+		selfReset: false
+	},
+	EMISSIVITY: {
+		name: "EMISSIVITY",
+		readable: true,
+		writable: true,
+		addr: 202,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	OFFSET: {
+		name: "OFFSET",
+		readable: true,
+		writable: true,
+		addr: 203,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	OTF: {
+		name: "OTF",
+		readable: true,
+		writable: true,
+		addr: 205,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	PRODUCTION_YEAR: {
+		name: "PRODUCTION_YEAR",
+		readable: true,
+		writable: false,
+		addr: 224,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	PRODUCTION_WEEK: {
+		name: "PRODUCTION_WEEK",
+		readable: true,
+		writable: false,
+		addr: 225,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	MANUF_LOCATION: {
+		name: "MANUF_LOCATION",
+		readable: true,
+		writable: false,
+		addr: 226,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	SERIAL_NUMBER_0: {
+		name: "SERIAL_NUMBER_0",
+		readable: true,
+		writable: false,
+		addr: 227,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	SERIAL_NUMBER_1: {
+		name: "SERIAL_NUMBER_1",
+		readable: true,
+		writable: false,
+		addr: 228,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	SERIAL_NUMBER_2: {
+		name: "SERIAL_NUMBER_2",
+		readable: true,
+		writable: false,
+		addr: 229,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	USER_FLASH_ENABLE: {
+		name: "USER_FLASH_ENABLE",
+		readable: true,
+		writable: true,
+		addr: 216,
+		startBit: 0,
+		endBit: 1,
+		selfReset: false
+	},
+	TEMP_UNITS: {
+		name: "TEMP_UNITS",
+		readable: true,
+		writable: true,
+		addr: 49,
+		startBit: 0,
+		endBit: 3,
+		selfReset: false
+	},
+	STARK_ENABLE: {
+		name: "STARK_ENABLE",
+		readable: true,
+		writable: true,
+		addr: 32,
+		startBit: 0,
+		endBit: 1,
+		selfReset: false
+	},
+	STARK_TYPE: {
+		name: "STARK_TYPE",
+		readable: true,
+		writable: true,
+		addr: 32,
+		startBit: 1,
+		endBit: 4,
+		selfReset: false
+	},
+	SPATIAL_KERNEL: {
+		name: "SPATIAL_KERNEL",
+		readable: true,
+		writable: true,
+		addr: 32,
+		startBit: 4,
+		endBit: 5,
+		selfReset: false
+	},
+	STARK_CUTOFF: {
+		name: "STARK_CUTOFF",
+		readable: true,
+		writable: true,
+		addr: 33,
+		startBit: 0,
+		endBit: 7,
+		selfReset: false
+	},
+	STARK_GRADIENT: {
+		name: "STARK_GRADIENT",
+		readable: true,
+		writable: true,
+		addr: 34,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	STARK_SCALE: {
+		name: "STARK_SCALE",
+		readable: true,
+		writable: true,
+		addr: 35,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	MMS_KXMS: {
+		name: "MMS_KXMS",
+		readable: true,
+		writable: true,
+		addr: 37,
+		startBit: 0,
+		endBit: 1,
+		selfReset: false
+	},
+	MMS_RA: {
+		name: "MMS_RA",
+		readable: true,
+		writable: true,
+		addr: 37,
+		startBit: 1,
+		endBit: 2,
+		selfReset: false
+	},
+	MEDIAN_ENABLE: {
+		name: "MEDIAN_ENABLE",
+		readable: true,
+		writable: true,
+		addr: 48,
+		startBit: 0,
+		endBit: 1,
+		selfReset: false
+	},
+	MEDIAN_KERNEL_SIZE: {
+		name: "MEDIAN_KERNEL_SIZE",
+		readable: true,
+		writable: true,
+		addr: 48,
+		startBit: 1,
+		endBit: 2,
+		selfReset: false
+	},
+	TEMPORAL_ENABLE: {
+		name: "TEMPORAL_ENABLE",
+		readable: true,
+		writable: true,
+		addr: 208,
+		startBit: 0,
+		endBit: 1,
+		selfReset: false
+	},
+	TEMPORAL_INIT: {
+		name: "TEMPORAL_INIT",
+		readable: true,
+		writable: true,
+		addr: 208,
+		startBit: 1,
+		endBit: 2,
+		selfReset: true
+	},
+	TEMPORAL_LSB: {
+		name: "TEMPORAL_LSB",
+		readable: true,
+		writable: true,
+		addr: 209,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	},
+	TEMPORAL_MSB: {
+		name: "TEMPORAL_MSB",
+		readable: true,
+		writable: true,
+		addr: 210,
+		startBit: 0,
+		endBit: 8,
+		selfReset: false
+	}
+};
+(() => {
+	const result = {};
+	Object.keys(FIELDS).forEach((fieldName) => {
+		const addr = FIELDS[fieldName].addr;
+		if (!result[addr]) result[addr] = [];
+		result[addr].push(fieldName);
+	});
+	return result;
+})();
+//#endregion
+//#region src/command-sender.ts
+var CommandSender = class {
+	port;
+	commandMutex;
+	encoder = new TextEncoder();
+	pendingCommand;
+	errorListener;
+	constructor(port) {
+		this.port = port;
+		this.commandMutex = new Mutex();
+	}
+	onError(listener) {
+		this.errorListener = listener;
+	}
+	async sendCommand(type, command, timeout = 2e3, attempts = 3) {
+		return this.commandMutex.runExclusive(async () => {
+			return this.sendCommandWithRetry(type, command, timeout, attempts);
+		});
+	}
+	resolveAck(type, data) {
+		if (!this.pendingCommand) {
+			const err = new SenxorTransportError(`Bare ACK received: ${type} without a corresponding command`);
+			this.errorListener?.(err);
+			return;
+		}
+		if (this.pendingCommand.type !== type) {
+			const err = new SenxorTransportError(`ACK type mismatch: expected ${this.pendingCommand.type}, received ${type}`);
+			this.pendingCommand.reject(err);
+			this.pendingCommand = void 0;
+			return;
+		}
+		this.pendingCommand.resolve(data);
+		this.pendingCommand = void 0;
+	}
+	async sendCommandWithRetry(type, command, timeout, attempts) {
+		let lastError;
+		for (let i = 0; i < attempts; i++) try {
+			return await this.sendCommandOnce(type, command, timeout);
+		} catch (error) {
+			lastError = error;
+		}
+		throw lastError;
+	}
+	async sendCommandOnce(type, command, timeout) {
+		return new Promise((resolve, reject) => {
+			this.pendingCommand = {
+				type,
+				resolve,
+				reject
+			};
+			const timeoutId = setTimeout(() => {
+				this.pendingCommand = void 0;
+				reject(new SenxorTransportError(`Command timeout: no ACK received for ${type}`));
+			}, timeout);
+			this.port.write(this.encoder.encode(command)).catch((err) => {
+				clearTimeout(timeoutId);
+				this.pendingCommand = void 0;
+				reject(new SenxorTransportError(`Failed to write command: ${type}`, err));
+			});
+		});
+	}
+};
+//#endregion
+//#region src/utils.ts
+const decoder = new TextDecoder("ascii");
+/**
+* Convert a number to a fixed-length uppercase hexadecimal string
+* @param value - The number to convert (must be non-negative)
+* @param length - The desired length of the hex string
+* @returns The uppercase hex string padded to the specified length
+* @throws Error if value is negative or produces more digits than length
+*/
+const toHexString = (value, length) => {
+	if (value < 0) throw new Error(`Cannot convert negative value ${value} to hex string`);
+	const hex = value.toString(16).toUpperCase();
+	if (hex.length > length) throw new Error(`Value ${value} (0x${hex}) exceeds ${length} hex digits`);
+	return hex.padStart(length, "0");
+};
+/**
+* Decode a Uint8Array to ASCII string
+* @param buffer - The Uint8Array to decode
+* @returns The decoded string
+*/
+const decodeUint8Array = (buffer) => {
+	return decoder.decode(buffer);
+};
+const isSenxorDevice = (device) => {
+	return device.vendorId === 1046 && device.productId in SENXOR_PRODUCT_ID;
+};
+//#endregion
+//#region src/parser.ts
+const msgPrefix = new TextEncoder().encode("   #");
+const msgLenFieldSize = 4;
+const msgLenFieldStart = 4;
+const msgCmdStart = msgLenFieldStart + msgLenFieldSize;
+const cmdLen = 4;
+const checksumIndex = -4;
+const msgDataStart = msgCmdStart + cmdLen;
+const parseMessageLength = (buf, start, size) => {
+	const hexString = decodeUint8Array(buf.slice(start, start + size));
+	return Number.parseInt(hexString, 16);
+};
+const verifyChecksum = (message, _payloadStart, _payloadLen) => {
+	return decodeUint8Array(message.slice(checksumIndex)) === toHexString(message.slice(msgLenFieldStart, checksumIndex).reduce((acc, val) => acc + val, 0) & 65535, 4);
+};
+const parseMessageBody = (message) => {
+	return {
+		cmd: decodeUint8Array(message.slice(msgCmdStart, msgCmdStart + cmdLen)),
+		data: message.slice(msgDataStart, checksumIndex)
+	};
+};
+const messageParserOptions = {
+	prefix: msgPrefix,
+	lengthFieldSize: msgLenFieldSize,
+	parseLength: parseMessageLength,
+	minPayloadLen: 4,
+	maxPayloadLen: 64 * 1024,
+	maxBufferSize: 64 * 1024,
+	verifyMessage: verifyChecksum,
+	onMessage: void 0,
+	onError: void 0,
+	onResync: void 0
+};
+const gfraDataFormat = {
+	10080: {
+		header: void 0,
+		frame: {
+			start: 160,
+			end: 10080
+		}
+	},
+	10240: {
+		header: {
+			start: 160,
+			end: 320
+		},
+		frame: {
+			start: 320,
+			end: 10240
+		}
+	},
+	39360: {
+		header: void 0,
+		frame: {
+			start: 960,
+			end: 39360
+		}
+	},
+	39680: {
+		header: {
+			start: 960,
+			end: 1280
+		},
+		frame: {
+			start: 1280,
+			end: 39680
+		}
+	},
+	5200: {
+		header: {
+			start: 100,
+			end: 200
+		},
+		frame: {
+			start: 200,
+			end: 5200
+		}
+	}
+};
+const senxorAckDecoder = {
+	RREG(data) {
+		const hexString = decodeUint8Array(data);
+		return Number.parseInt(hexString, 16);
+	},
+	WREG(data) {},
+	RRSE(data) {
+		const regs = {};
+		for (let i = 0; i < data.length; i += 4) {
+			const regAddr = Number.parseInt(decodeUint8Array(data.slice(i, i + 2)), 16);
+			regs[regAddr] = Number.parseInt(decodeUint8Array(data.slice(i + 2, i + 4)), 16);
+		}
+		return regs;
+	},
+	GFRA(data) {
+		const length = data.length;
+		if (length in gfraDataFormat) {
+			const { header: headerSlice, frame: frameSlice } = gfraDataFormat[length];
+			return {
+				header: headerSlice ? data.slice(headerSlice.start, headerSlice.end) : void 0,
+				frame: data.slice(frameSlice.start, frameSlice.end)
+			};
+		}
+		throw new Error(`Invalid GFRA data length: ${length}`);
+	},
+	SERR(data) {}
+};
+const senxorAckEncoder = {
+	RREG(regAddr) {
+		return `   #000ARREG${toHexString(regAddr, 2)}XXXX`;
+	},
+	WREG(regAddr, regValue) {
+		return `   #000CWREG${toHexString(regAddr, 2)}${toHexString(regValue, 2)}XXXX`;
+	},
+	RRSE(addrs) {
+		const payload = `RRSE${addrs.map((addr) => toHexString(addr, 2)).join("")}FFXXXX`;
+		return `   #${toHexString(payload.length, 4)}${payload}`;
+	}
+};
+//#endregion
+//#region src/transports.ts
+const senxorPortOptions = {
+	baudRate: 115200,
+	bytesize: 8,
+	stopbits: 1
+};
+var SerialTransportBase = class {
+	port;
+	parser;
+	commandSender;
+	dataListener;
+	errorListener;
+	openListener;
+	closeListener;
+	disconnectListener;
+	constructor(port) {
+		this.port = port;
+		this.commandSender = new CommandSender(this.port);
+		this.parser = new PrefixLengthParser({
+			...messageParserOptions,
+			onMessage: this.handleMessage.bind(this),
+			onError: this.handleParserError.bind(this)
+		});
+		this.setupPortEventListeners();
+	}
+	get isOpen() {
+		return this.port.isOpen;
+	}
+	get deviceInfo() {
+		return this.port.deviceInfo;
+	}
+	async open() {
+		await this.port.open(senxorPortOptions);
+	}
+	async close() {
+		await this.port.close();
+	}
+	async readReg(address) {
+		if (!this.port.isOpen) throw new SenxorTransportError("Cannot read register: port is closed");
+		const command = senxorAckEncoder.RREG(address);
+		return this.commandSender.sendCommand("RREG", command, 1e3, 2);
+	}
+	async readRegs(addresses) {
+		if (!this.port.isOpen) throw new SenxorTransportError("Cannot read registers: port is closed");
+		const commands = senxorAckEncoder.RRSE(addresses);
+		return this.commandSender.sendCommand("RRSE", commands, 1e3, 2);
+	}
+	async writeReg(address, value) {
+		if (!this.port.isOpen) throw new SenxorTransportError("Cannot write register: port is closed");
+		const command = senxorAckEncoder.WREG(address, value);
+		return this.commandSender.sendCommand("WREG", command, 1e3, 2);
+	}
+	onData(listener) {
+		this.dataListener = listener;
+	}
+	onError(listener) {
+		this.errorListener = listener;
+		this.commandSender.onError(listener);
+	}
+	onOpen(listener) {
+		this.openListener = listener;
+	}
+	onClose(listener) {
+		this.closeListener = listener;
+	}
+	onDisconnect(listener) {
+		this.disconnectListener = listener;
+	}
+	setupPortEventListeners() {
+		this.port.on("data", (data) => this.parser.push(data));
+		this.port.on("error", (error) => this.handlePortError(error));
+		this.port.on("open", () => this.handlePortOpen());
+		this.port.on("close", () => this.handlePortClose());
+		this.port.on("disconnect", () => this.handlePortDisconnect());
+	}
+	handleMessage(message, _totalLength) {
+		const { cmd: cmdStr, data } = parseMessageBody(message);
+		switch (cmdStr) {
+			case "RREG": {
+				const regValue = senxorAckDecoder.RREG(data);
+				this.commandSender.resolveAck("RREG", regValue);
+				break;
+			}
+			case "WREG": {
+				const wregResult = senxorAckDecoder.WREG(data);
+				this.commandSender.resolveAck("WREG", wregResult);
+				break;
+			}
+			case "RRSE": {
+				const rrseResult = senxorAckDecoder.RRSE(data);
+				this.commandSender.resolveAck("RRSE", rrseResult);
+				break;
+			}
+			case "GFRA": {
+				const gfraData = senxorAckDecoder.GFRA(data);
+				this.handleGfraAck(gfraData);
+				break;
+			}
+			case "SERR":
+				this.handleSerrAck();
+				break;
+			default:
+				this.handleUnknownAck(cmdStr);
+				break;
+		}
+	}
+	handlePortDisconnect() {
+		this.disconnectListener?.();
+	}
+	handlePortClose() {
+		this.closeListener?.();
+	}
+	handlePortOpen() {
+		this.openListener?.();
+	}
+	handleGfraAck(gfraData) {
+		const timestamp = Date.now();
+		const senxorRawData = {
+			header: gfraData.header,
+			frame: gfraData.frame,
+			timestamp
+		};
+		this.dataListener?.(senxorRawData);
+	}
+	handleParserError(error) {
+		const err = new SenxorTransportError("Parser error", error);
+		this.errorListener?.(err);
+	}
+	handlePortError(error) {
+		const err = new SenxorTransportError("Port I/O error", error);
+		this.errorListener?.(err);
+	}
+	handleSerrAck() {
+		const err = new SenxorTransportError("SERR Error: The device does not have a lens module installed");
+		this.errorListener?.(err);
+	}
+	handleUnknownAck(cmd) {
+		const err = new SenxorTransportError(`Unknown ACK: ${cmd}`);
+		this.errorListener?.(err);
+	}
+};
+//#endregion
+export { CommandSender, SerialTransportBase, decodeUint8Array, isSenxorDevice, senxorPortOptions, toHexString };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@senxor/serial-core",
+  "type": "module",
+  "version": "1.1.0",
+  "description": "Shared serial transport core for Senxor JavaScript SDK.",
+  "author": "Shui <zelongshui@meridianinno.com>",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/MeridianInnovation/senxor-js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MeridianInnovation/senxor-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MeridianInnovation/senxor-js/issues"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "@typescript/native-preview": "7.0.0-dev.20260309.1",
+    "bumpp": "^10.4.1",
+    "tsdown": "^0.21.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "async-mutex": "^0.5.0",
+    "serial-packet-parser": "latest"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}