ext-port v2.0.1

Ext-Port

An extensible framework for working with Serial-Ports that required explicitly defined protocols. Also exposes minimal well-known protocols such as Modbus.

Note: This package is recommended to be used with TypeScript however all definitions are defaulted to counter this if need be. However full-functionality will be more accessible through TypeScript (such as dynamic protocol typing).

Installation

npm install ext-port

Port Framework

As a wrapper-utility, ext-port allows defining typed parsers for a chosen serial-port. This can be done by creating an Ext.Parser implementation and setting the parser option with this value. This package also allows for better strategies for extending/inheriting serial-port interfaces.

Port Stream

By default, the Ext.Port.Stream will act similarly to the serialport::SerialPort implementation. When instantiated as below, the port defaults to an Ext.Bus<Buffer, Buffer> protocol that expects stream data to be incoming and outgoing as buffers.

import { Ext } from 'ext-port';

// simple instantiation as before
const port = new Ext.Port.Stream({ path: '/dev/ROBOT', baudRate: 38400 });

port.on('incoming', (chunk: Buffer) => /** ... */); // port event-data
port.on('outgoing', (chunk: Buffer) => /** ... */); // written buffer

Properties and Methods

Since all extensible ports inherit from the base serialport::SerialPort class, the functionality is almost identical. To improve functionality however, the callback-based methods have been replaced with Promise based alternatives.

Defining a Parser

Parsers can be created by extending the Ext.Parser.Abstract class. Using TypeScript this enforces the inheritance of defining the m_transform and m_flush methods necessary for parsing incoming data.

import { Ext } from 'ext-port';

/// Protocol Definition.
type MyProtocol = Ext.Bus<string, string>;

/// Parser Implementation
class MyParser extends Ext.Parser.Abstract<MyProtocol> {
    /**
     * Converts the incoming buffer into pushable values.
     * @param chunk                         Chunk to transform.
     * @param encoding                      Encoding to use.
     */
    protected m_transform(chunk: Buffer, encoding: BufferEncoding): string[] {
        return [chunk.toString()];
    }

    /** For completeness, defining an empty flush value. */
    protected m_flush(): string[] {
        return [];
    }
}

// simple construction now with type-inference
const port = new Ext.Port.Stream({ path: '/dev/ROBOT', baudRate: 9600, parser: new MyParser() });

port.on('incoming', (chunk: string) => /** ... */); // port event-data
port.on('outgoing', (chunk: string) => /** ... */); // written buffer

This allows us to construct complex transform-streams with ease. Alongside this, an Ext.Codec can be attached to an Ext.Parser.Abstract to define encode, decode, serialize and deserialize properties for parsing. This is useful when transforming to/from complex data-types.

Note: All the base parsers from serialport can be placed as the parser option as well. This library was designed around this functionality and extending transform streams to simplify using this library as a wrapper over the serialport functionality.

Defining a Codec

Codecs can be created by extending any of the Ext.Codec abstractions. These include:

• Ext.Codec.Abstract – The base codec abstraction.
• Ext.Codec.Merge – Allows combining a pair of codecs.
• Ext.Codec.Primitive – Codec for primitive types (eg: Buffer).
• Ext.Codec.PassThrough – Ensures primitive values are 'passed-through' (eg: no-change).
• Ext.Codec.Complex – Adds simple JSON serialization for complex items (necessary for emitting out of transform streams).

Pre-defined Protocols

The primary purpose of this library is to help defining common protocols (with data-transformations). This could be useful for parsing GPS or Modbus as examples. The following have been implemented for users.

• Modbus

License

MIT