serial-core 0.1.0 → 0.2.0-dev.1

package/LICENSE.md

@@ -7,11 +7,11 @@ the Free Software Foundation, either version 3 of the License, or
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
-along with this program.  If not, see https://www.gnu.org/licenses/.
+along with this program. If not, see https://www.gnu.org/licenses/.
 
 # GNU GENERAL PUBLIC LICENSE
 
@@ -232,23 +232,23 @@ produce it from the Program, in the form of source code under the
 terms of section 4, provided that you also meet all of these
 conditions:
 
--   a) The work must carry prominent notices stating that you modified
-    it, and giving a relevant date.
--   b) The work must carry prominent notices stating that it is
-    released under this License and any conditions added under
-    section 7. This requirement modifies the requirement in section 4
-    to "keep intact all notices".
--   c) You must license the entire work, as a whole, under this
-    License to anyone who comes into possession of a copy. This
-    License will therefore apply, along with any applicable section 7
-    additional terms, to the whole of the work, and all its parts,
-    regardless of how they are packaged. This License gives no
-    permission to license the work in any other way, but it does not
-    invalidate such permission if you have separately received it.
--   d) If the work has interactive user interfaces, each must display
-    Appropriate Legal Notices; however, if the Program has interactive
-    interfaces that do not display Appropriate Legal Notices, your
-    work need not make them do so.
+- a) The work must carry prominent notices stating that you modified
+  it, and giving a relevant date.
+- b) The work must carry prominent notices stating that it is
+  released under this License and any conditions added under
+  section 7. This requirement modifies the requirement in section 4
+  to "keep intact all notices".
+- c) You must license the entire work, as a whole, under this
+  License to anyone who comes into possession of a copy. This
+  License will therefore apply, along with any applicable section 7
+  additional terms, to the whole of the work, and all its parts,
+  regardless of how they are packaged. This License gives no
+  permission to license the work in any other way, but it does not
+  invalidate such permission if you have separately received it.
+- d) If the work has interactive user interfaces, each must display
+  Appropriate Legal Notices; however, if the Program has interactive
+  interfaces that do not display Appropriate Legal Notices, your
+  work need not make them do so.
 
 A compilation of a covered work with other separate and independent
 works, which are not by their nature extensions of the covered work,
@@ -267,42 +267,42 @@ sections 4 and 5, provided that you also convey the machine-readable
 Corresponding Source under the terms of this License, in one of these
 ways:
 
--   a) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by the
-    Corresponding Source fixed on a durable physical medium
-    customarily used for software interchange.
--   b) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by a
-    written offer, valid for at least three years and valid for as
-    long as you offer spare parts or customer support for that product
-    model, to give anyone who possesses the object code either (1) a
-    copy of the Corresponding Source for all the software in the
-    product that is covered by this License, on a durable physical
-    medium customarily used for software interchange, for a price no
-    more than your reasonable cost of physically performing this
-    conveying of source, or (2) access to copy the Corresponding
-    Source from a network server at no charge.
--   c) Convey individual copies of the object code with a copy of the
-    written offer to provide the Corresponding Source. This
-    alternative is allowed only occasionally and noncommercially, and
-    only if you received the object code with such an offer, in accord
-    with subsection 6b.
--   d) Convey the object code by offering access from a designated
-    place (gratis or for a charge), and offer equivalent access to the
-    Corresponding Source in the same way through the same place at no
-    further charge. You need not require recipients to copy the
-    Corresponding Source along with the object code. If the place to
-    copy the object code is a network server, the Corresponding Source
-    may be on a different server (operated by you or a third party)
-    that supports equivalent copying facilities, provided you maintain
-    clear directions next to the object code saying where to find the
-    Corresponding Source. Regardless of what server hosts the
-    Corresponding Source, you remain obligated to ensure that it is
-    available for as long as needed to satisfy these requirements.
--   e) Convey the object code using peer-to-peer transmission,
-    provided you inform other peers where the object code and
-    Corresponding Source of the work are being offered to the general
-    public at no charge under subsection 6d.
+- a) Convey the object code in, or embodied in, a physical product
+  (including a physical distribution medium), accompanied by the
+  Corresponding Source fixed on a durable physical medium
+  customarily used for software interchange.
+- b) Convey the object code in, or embodied in, a physical product
+  (including a physical distribution medium), accompanied by a
+  written offer, valid for at least three years and valid for as
+  long as you offer spare parts or customer support for that product
+  model, to give anyone who possesses the object code either (1) a
+  copy of the Corresponding Source for all the software in the
+  product that is covered by this License, on a durable physical
+  medium customarily used for software interchange, for a price no
+  more than your reasonable cost of physically performing this
+  conveying of source, or (2) access to copy the Corresponding
+  Source from a network server at no charge.
+- c) Convey individual copies of the object code with a copy of the
+  written offer to provide the Corresponding Source. This
+  alternative is allowed only occasionally and noncommercially, and
+  only if you received the object code with such an offer, in accord
+  with subsection 6b.
+- d) Convey the object code by offering access from a designated
+  place (gratis or for a charge), and offer equivalent access to the
+  Corresponding Source in the same way through the same place at no
+  further charge. You need not require recipients to copy the
+  Corresponding Source along with the object code. If the place to
+  copy the object code is a network server, the Corresponding Source
+  may be on a different server (operated by you or a third party)
+  that supports equivalent copying facilities, provided you maintain
+  clear directions next to the object code saying where to find the
+  Corresponding Source. Regardless of what server hosts the
+  Corresponding Source, you remain obligated to ensure that it is
+  available for as long as needed to satisfy these requirements.
+- e) Convey the object code using peer-to-peer transmission,
+  provided you inform other peers where the object code and
+  Corresponding Source of the work are being offered to the general
+  public at no charge under subsection 6d.
 
 A separable portion of the object code, whose source code is excluded
 from the Corresponding Source as a System Library, need not be
@@ -378,23 +378,23 @@ Notwithstanding any other provision of this License, for material you
 add to a covered work, you may (if authorized by the copyright holders
 of that material) supplement the terms of this License with terms:
 
--   a) Disclaiming warranty or limiting liability differently from the
-    terms of sections 15 and 16 of this License; or
--   b) Requiring preservation of specified reasonable legal notices or
-    author attributions in that material or in the Appropriate Legal
-    Notices displayed by works containing it; or
--   c) Prohibiting misrepresentation of the origin of that material,
-    or requiring that modified versions of such material be marked in
-    reasonable ways as different from the original version; or
--   d) Limiting the use for publicity purposes of names of licensors
-    or authors of the material; or
--   e) Declining to grant rights under trademark law for use of some
-    trade names, trademarks, or service marks; or
--   f) Requiring indemnification of licensors and authors of that
-    material by anyone who conveys the material (or modified versions
-    of it) with contractual assumptions of liability to the recipient,
-    for any liability that these contractual assumptions directly
-    impose on those licensors and authors.
+- a) Disclaiming warranty or limiting liability differently from the
+  terms of sections 15 and 16 of this License; or
+- b) Requiring preservation of specified reasonable legal notices or
+  author attributions in that material or in the Appropriate Legal
+  Notices displayed by works containing it; or
+- c) Prohibiting misrepresentation of the origin of that material,
+  or requiring that modified versions of such material be marked in
+  reasonable ways as different from the original version; or
+- d) Limiting the use for publicity purposes of names of licensors
+  or authors of the material; or
+- e) Declining to grant rights under trademark law for use of some
+  trade names, trademarks, or service marks; or
+- f) Requiring indemnification of licensors and authors of that
+  material by anyone who conveys the material (or modified versions
+  of it) with contractual assumptions of liability to the recipient,
+  for any liability that these contractual assumptions directly
+  impose on those licensors and authors.
 
 All other non-permissive additional terms are considered "further
 restrictions" within the meaning of section 10. If the Program as you
@@ -687,4 +687,4 @@ program into proprietary programs. If your program is a subroutine
 library, you may consider it more useful to permit linking proprietary
 applications with the library. If this is what you want to do, use the
 GNU Lesser General Public License instead of this License. But first,
-please read <https://www.gnu.org/licenses/why-not-lgpl.html>.
+please read <https://www.gnu.org/licenses/why-not-lgpl.html>.

package/README.md

@@ -1,154 +1,126 @@
 # serial-core
 
-A easy way to work with serial ports in Node.js
+> Resilient serial communication service with automatic reconnection and queues.
 
-## Development
 
-- Install dependencies:
+`serial-core` is a robust TypeScript library designed to manage serial port communications in Node.js applications. It provides a resilient architecture with built-in features for automatic reconnection, message queuing, and device scanning.
 
-```bash
-npm install
-```
+> [!WARNING]
+> This library is currently in active development. The API is subject to change at any time before the first stable release (v1.0.0).
 
-- Run the unit tests:
+## Features
 
-```bash
-npm run test
-```
+- **Resilience:** Automatically handles connection drops and attempts to reconnect.
+- **Message Queuing:** Internal queue manager ensures data is sent sequentially and handles backpressure.
+- **Auto-Discovery:** Can scan for devices by Vendor ID (VID) and Product ID (PID) if a specific path is not provided.
+- **Handshake Support:** Built-in mechanism to verify device connection with a handshake command and response pattern.
+- **TypeScript Support:** Written in TypeScript with full type definitions included.
+- **Event-Driven:** Extends `EventEmitter` to provide real-time updates on connection status and incoming data.
 
-- Build the library:
+## Installation
 
 ```bash
-npm run build
+npm install serial-core serialport
 ```
 
-## How to use
-
-### Using the Core Abstract Class
-
-The `Core` class is an abstract base class that provides the foundation for working with serial ports. To use it, you need to create a class that extends `Core` and implement the abstract methods.
-
-#### Basic Setup
-
-1. **Create a class that extends Core:**
-
-```typescript
-import { Core } from './lib/serial/core';
-import { SerialPort } from 'serialport';
-
-class MySerialDevice extends Core {
-  constructor() {
-    super({ port: null });
-  }
-
-  // Implement abstract methods
-  protected initParser(): void {
-    // Initialize your data parser here
-  }
-
-  protected serialMessage(buffer: Buffer): void {
-    // Handle incoming serial data here
-  }
-}
-```
+*Note: `serialport` is a peer dependency.*
 
-#### Configuration
+## Usage
 
-Before connecting, configure your serial port:
+Here is a basic example of how to use `SerialService`:
 
 ```typescript
-const device = new MySerialDevice();
+import { SerialService, SerialStatus } from 'serial-core';
 
-// Set filters to automatically find your device (optional)
-device.setFilters({
-  vendorId: '1234', // Optional: device vendor ID
-  productId: '5678'  // Optional: device product ID
-});
+// Configuration
+const config = {
+  // Option 1: Direct path
+  path: '/dev/ttyUSB0',
+  
+  // Option 2: Auto-discovery (used if path is not set)
+  // vendorId: '1234',
+  // productId: '5678',
 
-// Set port configuration
-device.setConfig({
-  path: '/dev/ttyUSB0',  // Port path (optional if using filters)
   baudRate: 9600,
-  dataBits: 8,
-  stopBits: 1,
-  parity: 'none'
+  autoConnect: true,
+  reconnectInterval: 5000,
+  
+  // Optional: Verify connection
+  // handshake: {
+  //   command: 'PING\n',
+  //   pattern: 'PONG',
+  //   timeout: 2000
+  // }
+};
+
+// Initialize Service
+const serial = new SerialService(config);
+
+// Listen to Status Changes
+serial.on('status', (status: SerialStatus) => {
+  console.log(`Serial Status: ${status}`);
+  // Possible values: DISCONNECTED, SCANNING, CONNECTING, CONNECTED, RECONNECTING
 });
-```
 
-#### Available Methods
-
-**Connection Management:**
-- `connect()`: Opens the serial port and establishes connection
-- `disconnect()`: Closes the serial port and disconnects
-
-**Configuration:**
-- `setConfig(config)`: Set port configuration options
-- `getConfig()`: Get current port configuration
-- `setFilters(filters)`: Set vendor/product ID filters for auto-discovery
-- `getFilters()`: Get current filters
-
-**Data Transmission:**
-- `appendToQueue(bytes, action)`: Add data to the send queue
-- `write()`: Send queued data
-
-**Utility Methods:**
-- `uint8ArrayToHexArray(array)`: Convert Uint8Array to hex array
-- `stringToArrayHex(string)`: Convert string to hex array
-- `asciiToHex(asciiString, joinWith)`: Convert ASCII to hex
-- `fixHexArray(array, size)`: Normalize hex array values
-- `getConnectionCmd()`: Get the connection command bytes
-
-#### Example Usage
+// Listen to Incoming Data
+serial.on('data', (data: any) => {
+  console.log('Received:', data.toString());
+});
 
-```typescript
-class ArduinoDevice extends Core {
-  protected initParser(): void {
-    // Setup your parser for incoming data
-  }
+// Listen to Errors
+serial.on('error', (err: Error) => {
+  console.error('Serial Error:', err.message);
+});
 
-  protected serialMessage(buffer: Buffer): void {
-    console.log('Data received:', buffer);
+// Send Data
+async function sendCommand() {
+  try {
+    // Sends data using the internal queue
+    await serial.send('HELLO_WORLD\n');
+    console.log('Message sent successfully');
+  } catch (error) {
+    console.error('Failed to send:', error);
   }
 }
 
-async function main() {
-  const arduino = new ArduinoDevice();
+// Manual Control
+// serial.connect();
+// serial.disconnect();
+```
 
-  // Set device filters
-  arduino.setFilters({
-    vendorId: 'arduino_vendor_id'
-  });
+## API Reference
 
-  // Connect to device
-  try {
-    await arduino.connect();
-    console.log('Connected!');
-  } catch (error) {
-    console.error('Failed to connect:', error);
-  }
+### `SerialService`
 
-  // Listen to events
-  arduino.on('serial:connected', () => {
-    console.log('Device connected');
-  });
+The main class for managing the serial connection.
 
-  arduino.on('serial:sent', (data) => {
-    console.log('Data sent:', data);
-  });
+#### Configuration (`SerialConfig`)
 
-  arduino.on('serial:timeout', (error) => {
-    console.log('Timeout:', error);
-  });
+| Property | Type | Description |
+|----------|------|-------------|
+| `path?` | `string` | The system path to the serial port (e.g., `/dev/ttyUSB0`). |
+| `vendorId?` | `string` | USB Vendor ID for auto-discovery (if `path` is omitted). |
+| `productId?` | `string` | USB Product ID for auto-discovery. |
+| `baudRate` | `number` | Serial baud rate (default: `9600`). |
+| `autoConnect` | `boolean` | Whether to connect automatically on instantiation. |
+| `reconnectInterval` | `number` | Time in ms to wait before retrying connection. |
+| `handshake?` | `object` | Optional handshake configuration to verify device identity. |
 
-  // Later, disconnect
-  await arduino.disconnect();
-}
-```
+#### Methods
+
+- **`connect(): Promise<void>`**: Initiates the connection process (scanning -> connecting -> handshake -> connected).
+- **`disconnect(): Promise<void>`**: Manually closes the connection and stops reconnection attempts.
+- **`send(data: string | Buffer, options?): Promise<void>`**: Queues data to be sent to the device.
+- **`status`: `SerialStatus`**: Getter for the current connection state.
 
 #### Events
 
-The Core class extends `Dispatcher` and emits the following events:
-- `serial:connected` - Emitted when device connects successfully
-- `serial:disconnected` - Emitted when device disconnects
-- `serial:sent` - Emitted after data is sent
-- `serial:timeout` - Emitted when an operation times out
+- **`status`**: Emitted when the connection status changes.
+- **`connected`**: Emitted when a connection is successfully established (and handshake passes).
+- **`disconnected`**: Emitted when the connection is lost or closed.
+- **`data`**: Emitted when data is received from the device.
+- **`error`**: Emitted when an error occurs.
+
+## License
+
+GPL-3.0-only

package/dist/SerialService.d.cts

@@ -0,0 +1,64 @@
+import { SerialPort } from 'serialport';
+import { EventEmitter } from 'events';
+import type { SerialStatus as SerialStatusType, SerialConfig } from './types.ts';
+import { SerialStatus } from './types.ts';
+import { QueueManager } from './core/QueueManager.ts';
+/**
+ * Main service. Implements a robust state machine.
+ * Extends EventEmitter to notify the rest of the app about changes.
+ */
+export declare class SerialService extends EventEmitter {
+    protected port: SerialPort | null;
+    protected queue: QueueManager;
+    protected _status: SerialStatusType;
+    protected config: SerialConfig;
+    protected intentionalDisconnect: boolean;
+    protected reconnectTimer: NodeJS.Timeout | null;
+    constructor(config: SerialConfig);
+    get status(): SerialStatus;
+    /**
+     * Updates status and emits the corresponding event.
+     */
+    protected setStatus(newStatus: SerialStatus): void;
+    /**
+     * Starts the connection process.
+     * Handles both direct connection (known path) and scanning (VID/PID).
+     */
+    connect(): Promise<void>;
+    /**
+     * Physically opens the port and configures listeners.
+     */
+    protected openPort(path: string): void;
+    /**
+     * Manual disconnection.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Public method to send data. Uses internal queue.
+     */
+    send(data: string | Buffer, options?: {
+        alias?: string;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Low-level write logic, handled by QueueManager.
+     * Handles backpressure (drain).
+     */
+    protected performWrite(data: string | Buffer): Promise<void>;
+    /**
+     * Centralized connection failure handling.
+     */
+    protected handleConnectionFailure(reason: string): void;
+    /**
+     * Schedules next connection attempt with simple backoff.
+     */
+    protected scheduleReconnect(): void;
+    /**
+     * Resource cleanup.
+     */
+    protected cleanup(): void;
+    /**
+     * Executes connection handshake.
+     */
+    protected performHandshake(): void;
+}

package/dist/SerialService.d.ts

@@ -0,0 +1,64 @@
+import { SerialPort } from 'serialport';
+import { EventEmitter } from 'events';
+import type { SerialStatus as SerialStatusType, SerialConfig } from './types.ts';
+import { SerialStatus } from './types.ts';
+import { QueueManager } from './core/QueueManager.ts';
+/**
+ * Main service. Implements a robust state machine.
+ * Extends EventEmitter to notify the rest of the app about changes.
+ */
+export declare class SerialService extends EventEmitter {
+    protected port: SerialPort | null;
+    protected queue: QueueManager;
+    protected _status: SerialStatusType;
+    protected config: SerialConfig;
+    protected intentionalDisconnect: boolean;
+    protected reconnectTimer: NodeJS.Timeout | null;
+    constructor(config: SerialConfig);
+    get status(): SerialStatus;
+    /**
+     * Updates status and emits the corresponding event.
+     */
+    protected setStatus(newStatus: SerialStatus): void;
+    /**
+     * Starts the connection process.
+     * Handles both direct connection (known path) and scanning (VID/PID).
+     */
+    connect(): Promise<void>;
+    /**
+     * Physically opens the port and configures listeners.
+     */
+    protected openPort(path: string): void;
+    /**
+     * Manual disconnection.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Public method to send data. Uses internal queue.
+     */
+    send(data: string | Buffer, options?: {
+        alias?: string;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Low-level write logic, handled by QueueManager.
+     * Handles backpressure (drain).
+     */
+    protected performWrite(data: string | Buffer): Promise<void>;
+    /**
+     * Centralized connection failure handling.
+     */
+    protected handleConnectionFailure(reason: string): void;
+    /**
+     * Schedules next connection attempt with simple backoff.
+     */
+    protected scheduleReconnect(): void;
+    /**
+     * Resource cleanup.
+     */
+    protected cleanup(): void;
+    /**
+     * Executes connection handshake.
+     */
+    protected performHandshake(): void;
+}

package/dist/core/PortRegistry.d.cts

@@ -0,0 +1,24 @@
+/**
+ * Singleton that keeps track of which serial ports are in use
+ * by this application. Prevents conflicts if multiple SerialServices
+ * are instantiated for the same port.
+ */
+export declare class PortRegistry {
+    private static instance;
+    private lockedPorts;
+    private constructor();
+    static getInstance(): PortRegistry;
+    /**
+     * Attempts to register (lock) exclusive use of a port.
+     * Returns true if registered successfully, false if already occupied.
+     */
+    register(path: string): boolean;
+    /**
+     * Releases the port so it can be used again.
+     */
+    unregister(path: string): void;
+    /**
+     * Checks if a port is currently in use by the library.
+     */
+    isLocked(path: string): boolean;
+}

package/dist/core/PortRegistry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Singleton that keeps track of which serial ports are in use
+ * by this application. Prevents conflicts if multiple SerialServices
+ * are instantiated for the same port.
+ */
+export declare class PortRegistry {
+    private static instance;
+    private lockedPorts;
+    private constructor();
+    static getInstance(): PortRegistry;
+    /**
+     * Attempts to register (lock) exclusive use of a port.
+     * Returns true if registered successfully, false if already occupied.
+     */
+    register(path: string): boolean;
+    /**
+     * Releases the port so it can be used again.
+     */
+    unregister(path: string): void;
+    /**
+     * Checks if a port is currently in use by the library.
+     */
+    isLocked(path: string): boolean;
+}

package/dist/core/PortScanner.d.cts

@@ -0,0 +1,11 @@
+/**
+ * Utility static class to find devices.
+ * Solves the problem of "on which COM/tty is my Arduino?".
+ */
+export declare class PortScanner {
+    /**
+     * Search for a port matching the provided VID and/or PID.
+     * Normalizes strings to avoid case sensitivity issues.
+     */
+    static findPort(vendorId?: string, productId?: string): Promise<string | null>;
+}

package/dist/core/PortScanner.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Utility static class to find devices.
+ * Solves the problem of "on which COM/tty is my Arduino?".
+ */
+export declare class PortScanner {
+    /**
+     * Search for a port matching the provided VID and/or PID.
+     * Normalizes strings to avoid case sensitivity issues.
+     */
+    static findPort(vendorId?: string, productId?: string): Promise<string | null>;
+}

package/dist/core/QueueManager.d.cts

@@ -0,0 +1,33 @@
+/**
+ * QueueManager acts as an intermediate buffer.
+ * It prevents serial port saturation and guarantees messages
+ * leave in the order they arrived (FIFO).
+ */
+export declare class QueueManager {
+    private queue;
+    private isProcessing;
+    private _currentAlias;
+    private writeHandler;
+    constructor(writeHandler: (data: Buffer | string) => Promise<void>);
+    /**
+     * Adds a command to the queue and returns a promise
+     * that resolves when the command has been drained to the port.
+     */
+    add(data: Buffer | string, options?: {
+        alias?: string;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Getter for the alias of the command currently processing (or just processed).
+     * Useful for correlating responses.
+     */
+    get currentAlias(): string | undefined;
+    /**
+     * Clears the queue (useful on abrupt disconnections)
+     */
+    clear(): void;
+    /**
+     * Recursive processing loop
+     */
+    private process;
+}