ellipsis-com 0.0.1

package/src/ComType.ts

@@ -0,0 +1,27 @@
+import { ComMacro } from './ComMacro';
+
+
+export class ComType {
+    startupDelay: number = 0
+
+    constructor(
+        public name: string,
+        public baud: number,
+        public macros: {
+            init: ComMacro[];
+            [operationId: string]: ComMacro[];
+        },
+        startupDelay?: number
+    ) {
+        if(startupDelay) {
+            this.startupDelay = startupDelay
+        }
+    }
+
+    toString() {
+        return `ComType(name='${this.name}', baud=${this.baud})`
+            + `[${Object.entries(this.macros).map(([m, macros]) => (
+                `\n\t${m}: [${macros.map(cm => cm.toString()).join(', ')}]`
+            )).join('')}\n]`;
+    }
+}

package/src/test/ComManager.test.ts

@@ -0,0 +1,204 @@
+import { ComManager } from '../ComManager'
+import { SerialPort } from 'serialport'
+import { ComPort } from '../ComPort'
+import { ComMacro } from '../ComMacro'
+import { ComType } from '../ComType'
+
+const MOCK_PORTS = [
+  {
+    path: '/dev/mock1',
+    manufacturer: 'ellipsis',
+    serialNumber: '123456',
+    pnpId: 'pnpId123',
+    locationId: 'location123',
+    vendorId: 'EL001',
+    productId: 'MOCK001'
+  },
+  {
+    path: '/dev/mock2',
+    manufacturer: 'ellipsis',
+    serialNumber: '123457',
+    pnpId: 'pnpId123',
+    locationId: 'location123',
+    vendorId: 'EL001',
+    productId: 'MOCK001'
+  },
+  {
+    path: '/dev/tty.Bluetooth-Incoming-Port',
+    manufacturer: undefined,
+    serialNumber: undefined,
+    pnpId: undefined,
+    locationId: undefined,
+    vendorId: undefined,
+    productId: undefined
+  }
+]
+
+const mockType: ComType = {
+    name: 'mock',
+    baud: 9600,
+    macros: {
+        init: [new ComMacro('init', /INITTED/)],
+        help: [new ComMacro('help', /SOME INSTRUCTIONS/)]
+    }
+}
+
+const sleep = (ms: number) => {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+describe('ComManager', () => {
+    let comManager: ComManager
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        (SerialPort as any).resetMocks();
+        (SerialPort as any).setMockPorts(MOCK_PORTS)
+        comManager = new ComManager()
+        comManager.refreshInterval = -1
+        comManager.defaultTimeout = 10
+    })
+
+    afterEach(() => {
+        (SerialPort as any).resetMocks()
+    })
+
+    describe('scanPorts', () => {
+        it('should find available ports', async () => {
+            await comManager.scanPorts()
+            expect(comManager.ports.length).toBe(MOCK_PORTS.length)
+            expect(comManager.ports[0].path).toBe(MOCK_PORTS[0].path)
+            expect(comManager.ports[1].path).toBe(MOCK_PORTS[1].path)
+            expect(comManager.ports[2].path).toBe(MOCK_PORTS[2].path)
+        })
+
+        it('should associate types to ports', async () => {
+            comManager.types = [mockType]
+            await comManager.scanPorts();
+
+            // Simulate the first port responding to the init macro and the others not responding:
+            (SerialPort as any).setNextResponse('INITTED')
+
+            await comManager.scanPorts()
+
+            // First should have the type set:
+            expect(comManager.ports[0].type).toBe(mockType)
+            expect(comManager.ports[1].type).toBeNull()
+            expect(comManager.ports[2].type).toBeNull()
+
+            // Only first has a type and so others should be closed:
+            expect(comManager.ports[0].state).toBe('background')
+            expect(comManager.ports[1].state).toBe('closed')
+            expect(comManager.ports[2].state).toBe('closed')
+        })
+
+        it('should successfully scan ports on init', async () => {
+            // Simulate the first port responding to the init macro and the others not responding:
+            (SerialPort as any).setNextResponse('INITTED')
+            await comManager.init([mockType])
+            
+            // First should have the type set:
+            expect(comManager.ports[0].type).toBe(mockType)
+            expect(comManager.ports[1].type).toBeNull()
+            expect(comManager.ports[2].type).toBeNull()
+
+            // Only first has a type and so others should be closed:
+            expect(comManager.ports[0].state).toBe('background')
+            expect(comManager.ports[1].state).toBe('closed')
+            expect(comManager.ports[2].state).toBe('closed')
+        })
+    })
+
+    describe('get port', () => {
+        it('should return the correct port by type and index', async () => {
+            // Simulate the first port responding to the init macro and the others not responding:
+            (SerialPort as any).setNextResponse('INITTED')
+            await comManager.init([mockType])
+
+            const port = comManager.getComPort('mock', 0)
+            expect(port).toBe(comManager.ports[0])
+        })
+
+        it('should throw an error if port not found by index', async () => {
+            // Simulate the first port responding to the init macro and the others not responding:
+            (SerialPort as any).setNextResponse('INITTED')
+            await comManager.init([mockType])
+
+            expect(() => comManager.getComPort('mock', 99)).toThrow()
+        })
+
+        it('should return the correct port by type and name', async () => {
+            // Simulate the first port responding to the init macro and the others not responding:
+            (SerialPort as any).setNextResponse('INITTED')
+            await comManager.init([mockType])
+            comManager.ports[0].name = '123456' // set name to serial number for testing
+
+            const port = comManager.getComPort('mock', '123456')
+            expect(port).toBe(comManager.ports[0])
+        })
+
+        it('should throw an error if port not found by name', async () => {
+            // Simulate the first port responding to the init macro and the others not responding:
+            (SerialPort as any).setNextResponse('INITTED')
+            await comManager.init([mockType])
+            comManager.ports[0].name = '123456' // set name to serial number for testing
+
+            expect(() => comManager.getComPort('mock', 'nonexistent')).toThrow()
+        })
+    })
+
+    describe('send', () => {
+        it('should send messages to the correct port by index', async () => {
+            (SerialPort as any).setNextResponse('INITTED')
+            await comManager.init([mockType])
+
+            const sendPromise = comManager.send('mock', 0, 'help');
+            (SerialPort as any).setNextResponse('SOME INSTRUCTIONS') // simulate response from device
+            await Promise.resolve(sendPromise) // wait for send to complete
+        })
+
+        it('should send messages to the correct port by name', async () => {
+            (SerialPort as any).setNextResponse('INITTED')
+            await comManager.init([mockType])
+            comManager.ports[0].name = '123456' // set name to serial number for testing
+
+            const sendPromise = comManager.send('mock', '123456', 'help');
+            (SerialPort as any).setNextResponse('SOME INSTRUCTIONS') // simulate response from device
+            await Promise.resolve(sendPromise) // wait for send to complete
+        })
+    })
+
+    describe('refresh interval', () => {
+        it('should refresh the port list at the specified interval', async () => {
+            (SerialPort as any).setNextResponse('INITTED')
+            comManager.refreshInterval = 500
+            await comManager.init([mockType])
+            expect(comManager.ports[0].type).toBe(mockType)
+
+            // Check that the port was correctly initialized:
+            const mockPort = comManager.getComPort('mock', 0)
+            expect(mockPort).toBeDefined()
+            expect(mockPort.type).toBe(mockType);
+
+            const sendSpy = jest.spyOn(mockPort, 'send');
+
+            // Make sure the port will be refreshed by receiving a response to the hello message:
+            (SerialPort as any).setNextResponse('INITTED')
+
+            // Wait for refresh to happen - port init should have been sent and port should be open:
+            await sleep(comManager.refreshInterval + 200) // add a buffer to make sure the refresh has completed
+            expect(sendSpy).toHaveBeenCalledWith('init')
+            expect(mockPort.state).toBe('background')
+            sendSpy.mockClear()
+
+            // Wait for next refresh to happen which will not receive a response and should close the port:
+            await sleep(comManager.refreshInterval)
+            expect(mockPort.state).toBe('closed')
+
+            // Cancel autorefresh:
+            comManager.refreshInterval = -1
+            clearInterval((comManager as any).refreshIntervalHandle) // ensure rescans don't run after the test finishes
+        })
+    })
+})
+            

package/src/test/ComPort.test.ts

@@ -0,0 +1,140 @@
+import { ComMacro } from "../ComMacro"
+import { ComPort } from "../ComPort"
+import { SerialPort } from "serialport"
+
+const sleep = (ms: number) => {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+describe('ComPort', () => {
+    let comPort: ComPort
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        (SerialPort as any).resetMocks()
+        comPort = new ComPort('/dev/serialportMock')
+    })
+
+    afterEach(() => {
+        (SerialPort as any).resetMocks()
+    })
+
+    describe('connect', () => {
+        it('should open the port successfully', async () => {
+            const connectPromise = comPort.connect(9600)
+            expect(comPort.state).toBe('connecting')
+            await Promise.resolve(connectPromise) // wait for the open callback to be called
+            expect(comPort.state).toBe('background')
+        })
+
+        it('should handle open errors', async () => {
+            (SerialPort as any).setMockOpenError(new Error('Failed to open port'))
+            const connectPromise = comPort.connect(9600)
+            await expect(connectPromise).rejects.toThrow('Failed to open port')
+            expect(comPort.state).toBe('closed')
+            expect(comPort.lastError).toBe('Failed to open port')
+        })
+
+        it('should handle errors after opening', async () => {
+            await comPort.connect(9600);
+            (comPort as any).port.simulateError(new Error('Port error'))
+            expect(comPort.state).toBe('background')
+            expect(comPort.lastError).toBe('Port error')
+        })
+
+        it('should open on setting type', async () => {
+            const setTypePromise = comPort.setType({
+                name: 'serialportMock',
+                baud: 9600,
+                macros: {
+                    init: [new ComMacro('init', /INITTED/)]
+                }
+            })
+            expect(comPort.state).toBe('connecting');
+            (SerialPort as any).setNextResponse('INITTED') // simulate response from device
+            await Promise.resolve(setTypePromise) // wait for setType to complete
+            expect(comPort.state).toBe('closed') // should close after init macros run
+        })
+    })
+
+    describe('background', () => {
+        it('should receive background input', async () => {
+            await comPort.connect(9600);
+            (comPort as any).port.simulateData('Hello, World!')
+            expect(comPort.backgroundBuffer).toContain('Hello, World!')
+        })
+    })
+
+    describe('send', () => {
+        it('should send data successfully via a macro and receive a response', async () => {
+            await comPort.connect(9600);
+            const responsePromise = comPort.send([new ComMacro('HELP', /SOME INSTRUCTIONS/)]);
+            (SerialPort as any).setNextResponse('SOME INSTRUCTIONS') // simulate response from device
+            await Promise.resolve(responsePromise) // wait for the write callback to be called
+        })
+
+        it('should throw a timeout error if response not received in time', async () => {
+            comPort.timeout = 500; // set a short timeout for testing
+            await comPort.connect(9600);
+            const responsePromise = comPort.send([new ComMacro('HELP', /SOME INSTRUCTIONS/)]);
+            await expect(responsePromise).rejects.toThrow('Timeout after 500ms while reading from port /dev/serialportMock.')
+        })
+
+        it('should send a macro base on the operationId', async () => {
+            
+            (SerialPort as any).setNextResponse('INITTED') // simulate response from device
+            await comPort.setType({
+                name: 'serialportMock',
+                baud: 9600,
+                macros: {
+                    init: [new ComMacro('INIT', /INITTED/)],
+                    help: [new ComMacro('HELP', /SOME INSTRUCTIONS/)]
+                }
+            })
+            expect(comPort.type).toBeDefined();
+            
+            (SerialPort as any).setNextResponse('SOME INSTRUCTIONS') // simulate response from device
+            await comPort.send('help') // send should auto-connect based on type
+            expect(comPort.state).toBe('background') // should return to background after macro completes
+        })
+    })
+
+    describe('close', () => {
+        it('should close the port successfully', async () => {
+            await comPort.connect(9600);
+            expect(comPort.state).toBe('background')
+            await comPort.close()
+            expect(comPort.state).toBe('closed')
+        })
+    })
+
+    describe('congestion handling', () => {
+        it('should queue sends while busy and execute them sequentially', async () => {
+            await comPort.connect(9600);
+            expect(comPort.state).toBe('background')
+
+            // 1. Send two macros in quick succession:
+            const sendPromise1 = comPort.send([new ComMacro('CMD1', /RESP1/)])
+            const sendPromise2 = comPort.send([new ComMacro('CMD2', /RESP2/)])
+            // Note that state may be either busy or background depending on timing.
+            
+            // 2. After a brief delay the state should be 'busy':
+            await sleep(50)
+            expect(comPort.state).toBe('busy'); // first send should set state to busy
+
+            // 3. Simulate response for first command:
+            (comPort as any).port.simulateData('RESP1')
+            await sendPromise1 // wait for first send to complete
+            expect(comPort.state).toBe('background'); // should return to background after first macro completes
+
+            // 4. After another brief delay, the state should again be busy as the second send starts processing:
+            await sleep(500)
+            expect(comPort.state).toBe('busy'); // second send should now be processing and waiting for response
+
+            // 5. Simulate response for second command:
+            (comPort as any).port.simulateData('RESP2')
+            await sendPromise2 // wait for second send to complete
+            expect(comPort.state).toBe('background') // should return to background after both macros complete
+        })
+    })
+})

package/src/test/Demo.ts

@@ -0,0 +1,52 @@
+import { ComManager } from '../ComManager'
+import { ComMacro } from '../ComMacro'
+
+/**
+ * This demo works with the arduino-demo sketch.
+ */
+async function demo() {
+    const manager = new ComManager()
+
+    // Initialise the manager with a com type that has some macros.
+    // The init macro is required and is used to identify the type of a port when it is connected. 
+    // The other macros are optional and can be used to define commands that can be sent to the device.
+    await manager.init(
+        [{
+            name: 'myType',
+            baud: 9600,
+            startupDelay: 2000, // optional delay to wait for device to startup after connecting and before sending init
+            macros: {
+                // Command to initialise and identify type - must have key 'init':
+                init: [new ComMacro('INFO', /MOCK\sDEVICE\sV\d+.?\d*[\n\r]+STATUS: OK[\n\r]+CMD DONE$/gm)], // regex to identify device as being of myType
+
+                // Basic command and response pattern - can be named anything:
+                getData: [new ComMacro('GET DATA', /CMD DONE$/gm)],
+
+                // Command with parameters:
+                setData: [new ComMacro('SET DATA {val}', /CMD DONE$/gm)],
+
+                // Command with a sequence of commands and responses:
+                deleteData: [
+                    new ComMacro('DEL DATA', /Are you sure\? \(Y\/N\)$/gm),
+                    new ComMacro('Y', /CMD DONE$/gm)
+                ]
+            }
+        }]
+    )
+
+    // Send the getData command to the first port of type 'myType':
+    let data = await manager.send('myType', 0, 'getData')
+    console.log('\nGet data response - ', data[0], '\n') // data is an array of responses matching the regex for the macro
+
+    // Send the setData command with a parameter:
+    await manager.send('myType', 0, 'setData', {val: 'abc123'})
+    data = await manager.send('myType', 0, 'getData')
+    console.log('\nData changed - ', data[0], '\n')
+
+    // Delete the data using the deleteData command which has a sequence of commands and responses:
+    await manager.send('myType', 0, 'deleteData')
+    data = await manager.send('myType', 0, 'getData')
+    console.log('\nAfter deletion - ', data[0], '\n')
+}
+
+demo()

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "commonjs",
+    "lib": ["ES2021"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "types": ["node", "jest"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}