/**
|
* @file dxChannel.js
|
* @module dxChannel
|
* @description
|
* Data communication channel module based on the native dxChannel C library.
|
* This module provides a direct, handle-based interface for various communication channels,
|
* including Serial Port (UART), USB (HID, Keyboard Wedge), and Wiegand.
|
*
|
* It is designed for high-performance, multi-threaded environments, allowing different
|
* channels to be operated in parallel safely.
|
*
|
* @usage
|
* // 1. Import the module
|
* import channel from 'dxChannel.js';
|
*
|
* // 2. Open a channel (e.g., a serial port) and get its handle
|
* let uart_handle = null;
|
* try {
|
* uart_handle = channel.open(channel.TYPE.UART, "/dev/ttyS2");
|
* } catch (e) {
|
* console.error("Failed to open UART:", e);
|
* }
|
*
|
* if (uart_handle !== null) {
|
* try {
|
* // 3. Configure the channel
|
* channel.setUartParam(uart_handle, 9600, 8, 'N', 1);
|
*
|
* // 4. Send data
|
* const dataToSend = new Uint8Array([0x01, 0x02, 0x03, 0x04]).buffer;
|
* const success = channel.send(uart_handle, dataToSend);
|
* dxLogger.info("Send successful:", success);
|
*
|
* // 5. Receive data (this is a blocking call)
|
* const receivedData = channel.receive(uart_handle, 4, 1000); // Wait for 4 bytes for up to 1000ms
|
* if (receivedData) {
|
* dxLogger.info("Received data:", receivedData);
|
* }
|
* } catch (e) {
|
* console.error("Channel operation failed:", e);
|
* } finally {
|
* // 6. Close the handle when done
|
* channel.close(uart_handle);
|
* }
|
* }
|
*/
|
import { channel as nativeChannel } from './libvbar-m-dxchannel.so'
|
|
const channel = {}
|
|
/**
|
* @readonly
|
* @enum {number}
|
* Channel type enumeration.
|
*/
|
channel.TYPE = Object.freeze({
|
USBKBW: 1, // USB Keyboard Wedge
|
USBHID: 2, // USB Human Interface Device
|
UART: 3, // Serial Port (UART)
|
WIEGAND: 4 // Wiegand interface
|
});
|
|
/**
|
* @readonly
|
* @enum {number}
|
* IO Control command enumeration for `channel.ioctl`.
|
*/
|
channel.IOC_SET_CMD = Object.freeze({
|
/** Set KBW channel configuration parameters */
|
CHANNEL_IOC_SET_KBW_CONFIG: 1,
|
/** Set KBW channel upper computer parameters */
|
CHANNEL_IOC_SET_KBW_UPPER: 2,
|
/** Set KBW online time */
|
CHANNEL_IOC_SET_KBW_UPTIME: 3,
|
/** Set KBW offline time */
|
CHANNEL_IOC_SET_KBW_DOWNTIME: 4,
|
/** Set HID channel report length */
|
CHANNEL_IOC_SET_HID_REPORT_LEN: 5,
|
/** Set UART channel parameters */
|
CHANNEL_IOC_SET_UART_PARAM: 6,
|
/** Set Wiegand channel working mode */
|
CHANNEL_IOC_SET_WIEGAND_MODE: 7,
|
/** Set Wiegand channel GPIO configuration */
|
CHANNEL_IOC_SET_WIEGAND_GPIO: 8,
|
/** Set Wiegand channel delay time */
|
CHANNEL_IOC_SET_WIEGAND_DELAY: 9,
|
/** Set Wiegand channel logging function */
|
CHANNEL_IOC_SET_WIEGAND_LOG: 10
|
});
|
|
/**
|
* @readonly
|
* @enum {number}
|
* Wiegand channel working modes.
|
*/
|
channel.WIEGAND_MODE = Object.freeze({
|
/** Initial value for Wiegand mode */
|
WIEGAND_MODE_INIT: 0,
|
/** Wiegand 26-bit mode */
|
WIEGAND_MODE_26: 1,
|
/** Wiegand 34-bit mode */
|
WIEGAND_MODE_34: 2,
|
/** Wiegand 128-bit mode */
|
WIEGAND_MODE_128: 3,
|
/** Wiegand 256-bit mode */
|
WIEGAND_MODE_256: 4,
|
/** Wiegand 2048-bit mode */
|
WIEGAND_MODE_2048: 5,
|
/** Custom Wiegand mode, max 6400 bits */
|
WIEGAND_MODE_CUSTOM: 6
|
});
|
|
/**
|
* Opens a communication channel and returns its handle.
|
* @param {number} type - The channel type, from `channel.TYPE` enum.
|
* @param {string} path - The channel device path, e.g., "/dev/ttyS2". Note: The path may vary on different hardware. Please refer to `dxDriver.js` for device-specific constants.
|
* @returns {number} The numeric handle for the opened channel, used in all subsequent operations.
|
* @throws {Error} If the channel fails to open or if parameters are invalid.
|
*/
|
channel.open = function (type, path) {
|
if (type === undefined || type === null) {
|
throw new Error("channel.open: 'type' parameter is required.")
|
}
|
// Validate that the provided type is a valid value from the enum
|
if (!Object.values(channel.TYPE).includes(type)) {
|
throw new Error(`channel.open: invalid 'type' parameter. Please use a value from channel.TYPE.`);
|
}
|
if (path === undefined || path === null) {
|
throw new Error("channel.open: 'path' parameter is required.")
|
}
|
|
try {
|
const handle_id = nativeChannel.open(type, path);
|
return handle_id;
|
} catch (e) {
|
// The C layer throws an exception on failure. We catch it and re-throw a more user-friendly JS error.
|
throw new Error(`channel.open: failed to open channel with type ${type} and path '${path}'. Reason: ${e.message}`);
|
}
|
}
|
|
/**
|
* Sends data to a specified channel.
|
* @param {number} handle_id - The channel handle returned by `open()`.
|
* @param {ArrayBuffer} buffer - The binary data to send.
|
* @returns {number} The number of bytes successfully sent, or a negative value on failure.
|
* Note: A successful return only indicates data has been sent from the local buffer,
|
* not that it has been received by the remote end.
|
*/
|
channel.send = function (handle_id, buffer) {
|
if (handle_id === undefined || handle_id === null) {
|
throw new Error("channel.send: 'handle_id' parameter is required.")
|
}
|
if (buffer === undefined || buffer === null) {
|
throw new Error("channel.send: 'buffer' parameter is required.")
|
}
|
return nativeChannel.send(handle_id, buffer);
|
}
|
|
/**
|
* Receives data from a specified channel. This is a blocking call.
|
* @param {number} handle_id - The channel handle returned by `open()`.
|
* @param {number} size - The number of bytes to receive.
|
* @param {number} [timeout=10] - The maximum time to wait in milliseconds. Defaults to 10.
|
* @returns {Uint8Array|null} A `Uint8Array` containing the received data, or `null` if the operation timed out with no data.
|
*/
|
channel.receive = function (handle_id, size, timeout) {
|
if (handle_id === undefined || handle_id === null) {
|
throw new Error("channel.receive: 'handle_id' parameter is required.")
|
}
|
if (size === undefined || size === null) {
|
throw new Error("channel.receive: 'size' parameter is required.")
|
}
|
if (timeout === undefined || timeout === null) {
|
timeout = 10
|
}
|
|
const res = nativeChannel.receive(handle_id, size, timeout)
|
if (res === null) {
|
return null
|
}
|
return new Uint8Array(res)
|
}
|
|
/**
|
* Performs a special I/O control operation on a specified channel.
|
* @param {number} handle_id - The channel handle returned by `open()`.
|
* @param {number} request - The control command code, from `channel.IOC_SET_CMD` enum.
|
* @param {*} arg - The argument for the request, which can be a number, string, or object.
|
* @returns {boolean} True on success, false on failure.
|
*/
|
channel.ioctl = function (handle_id, request, arg) {
|
if (handle_id === undefined || handle_id === null) {
|
throw new Error("channel.ioctl: 'handle_id' parameter is required.")
|
}
|
// Validate that the provided request is a valid value from the enum
|
if (!Object.values(channel.IOC_SET_CMD).includes(request)) {
|
throw new Error(`channel.ioctl: invalid 'request' parameter. Please use a value from channel.IOC_SET_CMD.`);
|
}
|
return nativeChannel.ioctl(handle_id, request, arg)
|
}
|
|
/**
|
* Closes a communication channel.
|
* @param {number} handle_id - The channel handle returned by `open()`.
|
* @returns {boolean} Always returns true on success.
|
* @throws {Error} If the handle_id is invalid.
|
*/
|
channel.close = function (handle_id) {
|
if (handle_id === undefined || handle_id === null) {
|
throw new Error("channel.close: 'handle_id' parameter is required.")
|
}
|
return nativeChannel.close(handle_id)
|
}
|
|
/**
|
* Flushes (clears) the input/output buffers of a specified channel.
|
* @param {number} handle_id - The channel handle returned by `open()`.
|
* @param {number} queue_selector - Which queue to flush. 0: Input, 1: Output, 2: Both.
|
* @returns {boolean} True on success, false on failure.
|
*/
|
channel.flush = function (handle_id, queue_selector) {
|
if (handle_id === undefined || handle_id === null) {
|
throw new Error("channel.flush: 'handle_id' parameter is required.")
|
}
|
if (queue_selector === undefined || queue_selector === null) {
|
throw new Error("channel.flush: 'queue_selector' parameter is required.")
|
}
|
return nativeChannel.flush(handle_id, queue_selector);
|
}
|
|
/**
|
* Sets the communication parameters for a UART (serial) channel.
|
* @param {number} handle_id - The channel handle returned by `open()`.
|
* @param {number} baudrate - The baud rate, e.g., 9600, 115200.
|
* @param {number} [databits=8] - The number of data bits.
|
* @param {string} [parity='N'] - The parity: 'N' (None), 'O' (Odd), 'E' (Even).
|
* @param {number} [stopbits=1] - The number of stop bits.
|
* @returns {boolean} True on success, false on failure.
|
*/
|
channel.setUartParam = function (handle_id, baudrate, databits, parity, stopbits) {
|
if (baudrate === undefined || baudrate === null) {
|
throw new Error("channel.setUartParam: 'baudrate' parameter is required.");
|
}
|
// Set default values for optional parameters
|
const final_databits = (databits === undefined || databits === null) ? 8 : databits;
|
const final_parity = (parity === undefined || parity === null) ? 'N' : parity;
|
const final_stopbits = (stopbits === undefined || stopbits === null) ? 1 : stopbits;
|
|
const param_string = `${baudrate}-${final_databits}-${final_parity}-${final_stopbits}`;
|
|
return channel.ioctl(handle_id, channel.IOC_SET_CMD.CHANNEL_IOC_SET_UART_PARAM, param_string);
|
}
|
|
/**
|
* @typedef {object} WiegandGpioConfig
|
* @property {number} [busy_time] - Busy time (in microseconds). Defaults to 50 in the C layer.
|
* @property {number} [free_time] - Free time (in microseconds). Defaults to 100 in the C layer.
|
* @property {number} [mode] - Working mode, see `channel.WIEGAND_MODE`. Defaults to 2 (34-bit) in the C layer.
|
* @property {number} [log_level] - Log level. Defaults to 1 in the C layer.
|
* @property {number} [wiegand_d0] - GPIO pin number for D0 data line. Defaults to 4 in the C layer.
|
* @property {number} [wiegand_d1] - GPIO pin number for D1 data line. Defaults to 5 in the C layer.
|
*/
|
|
/**
|
* Sets the GPIO pins and working parameters for a Wiegand channel.
|
* @param {number} handle_id - The channel handle returned by `open()`.
|
* @param {WiegandGpioConfig} config - Wiegand configuration object.
|
* @returns {boolean} True on success, false on failure.
|
*/
|
channel.setWiegandGpio = function (handle_id, config) {
|
if (config === undefined || config === null) {
|
throw new Error("channel.setWiegandGpio: 'config' object is required.");
|
}
|
// The C layer provides default values, so passing a partial or empty object is safe.
|
return channel.ioctl(handle_id, channel.IOC_SET_CMD.CHANNEL_IOC_SET_WIEGAND_GPIO, config);
|
}
|
export default channel;
|
