StandardDriverInterface

The Standard Driver Interface is an interface that is shared by all MeldCX AgentM drivers
Note: All drivers will handle the attach and removal events, they will manage the closing of communication channel after a removal and handle the connection of an attached device.

Members

(async) driverName

The name of this driver

Example

// Inside an async function
console.log(`The name of this driver is ${driver.driverName}`);

Methods

(async) cancel() → {Promise.<undefined>}

Cancel any in progress command

Example

import AgentCancelledException from '@meldcx/agent-errors/AgentCancelledException';

// Inside an async function

// Register an event handler on a button, the handler will cancel the long running task
buttonCancel.onclick = async() => {
 console.log('Cancelling some long running function');
 await driver.cancel();
 console.log('Cancel has been requested');
};

try {
 console.log('someLongRunningFunction is starting');
 const result = await driver.someLongRunningFunction();
 console.log('someLongRunningFunction completed');
} catch (ex) {
 if (ex instanceof AgentCancelledException) {
     console.info('someLongRunningFunction was cancelled');
     // All is well, handle the clean up appropriately.

     return;
 }

 // Some other error we cannot handle has occured
 throw ex;
}

(async) close() → {Promise.<undefined>}

Close the communication to the peripheral
Note: All drivers will handle the attach and removal events, they will manage the closing of communication channel after a removal and handle the connection of an attached device.

Example

// Inside an async function

try {
 console.log('The drivers communication channel is closing');
 await driver.close();
 console.log('The driver is closing');
} catch (ex) {
 if (ex instanceof AgentNotAttachedException) {
     console.warn('The peripheral is not attached');
     // Note: This error can be avoided by checking if the device is attached using the `isAttached()` function
 }

 if (ex instanceof AgentAlreadyDisconnectedException) {
     console.warn('The communication channel is already closed');
     // Note: This error can be avoided by checking if the device is disconnected using the `isConnected()` function
 }
}

(async) disable() → {Promise.<undefined>}

Disable the peripheral, this is only available for select peripherals

Example

// Inside an async function

try {
 console.log('Enabling the peripheral');
 const isEnabled = await driver.isEnabled();
 if (isEnabled === true) return console.warn('Already enabled');
 await driver.enabled();
 console.log('Driver enabled');
} catch (ex) {
 if (ex instanceof AgentNotAttachedException) {
   console.warn('The peripheral is not attached');
   // Note: This error can be avoided by checking if the device is attached using the `isAttached()` function
 }

 if (ex instanceof AgentDisconnectedException) {
   console.warn('The communication channel is not connected');
   // Note: This error can be avoided by checking if the device is disconnected using the `isConnected()` function
 }s
}

(async) enable() → {Promise.<undefined>}

Enable the peripheral, this is only available for select peripherals

Example

// Inside an async function

try {
 console.log('Disabling the peripheral');
 const isEnabled = await driver.isEnabled();
 if (isEnabled === false) return console.warn('Already disabled');
 await driver.disable();
 console.log('Driver disabled');
} catch (ex) {
 if (ex instanceof AgentNotAttachedException) {
   console.warn('The peripheral is not attached');
   // Note: This error can be avoided by checking if the device is attached using the `isAttached()` function
 }

 if (ex instanceof AgentDisconnectedException) {
   console.warn('The communication channel is not connected');
   // Note: This error can be avoided by checking if the device is disconnected using the `isConnected()` function
 }s
}

(async) getDeviceInfo()

Retrieve information about the device, driver and its state.

Example

// Inside an async function

const lookupOperationalStatus = {
 '1': 'Operational',
 '2': 'Unknown',
 '3': 'Error',
 '4': 'Inactive'
};

const lookupConnectivityStatus = {
 '1': 'Connected',
 '2': 'Disconnected'
};

const info = await driver.getDeviceInfo();

console.log(`Device connectivity status: ${lookupConnectivityStatus[info.status.connectivityStatus]}`);
console.log(`Device operation status: ${lookupOperationalStatus[info.status.operationalStatus]}`);
console.log(`Device usb vendorId: 0x${info.device.vendorId.toString('16')}`);
console.log(`Device usb productId: 0x${info.device.productId.toString('16')}`);
console.log(`Device usb manufacturer: ${info.device.manufacturerName}`);
console.log(`Device usb product: ${info.device.productName}`);
console.log(`Device usb serial no: ${info.device.serial}`);
console.log(`Device driver version: ${info.driverVersion}`);
console.log(`Device manufacturer: ${info.manufacturer}`);
console.log(`Device model: ${info.model}`);
console.log(`Device current firmware: ${info.currentFirmware}`);
console.log(`Device requires supported firmware? ${info.requiresSupportedFirmware ? 'Yes' : 'No'}`);
console.log(`Device supported firmware(s): ${info.supportedFirmwares.join()}`);
console.log(`Device supported descriptor(s): ${info.supportedDescriptors.map(({vendorId, productId}) => `vid: 0x${vendorId.toString(16)} & pid: ${productId.toString(16)}`).join()}`);

(async) isAttached() → {Promise.<Boolean>}

Is the device physically connected

Example

// Inside an async function
const isAttached = await driver.isConnected();
console.log(`The device ${isAttached 'is' : 'is not'} attached`);

(async) isConnected() → {Promise.<Boolean>}

Is the device communication open and connected

Example

// Inside an async function
const isConnected = await driver.isConnected();
console.log(`The device ${isConnected ? 'is' : 'is not'} connected`);

(async) isEnabled() → {Promise.<Boolean>}

Is the device enabled

Example

// Inside an async function
const isEnabled = await driver.isEnabled();
console.log(`The device ${isEnabled ? 'is' : 'is not'} enabled`);

onAttached(cb) → {function}

Parameters:

Name	Type	Description
`cb`	function	The callback function to register

Example

// Inside an async function
driver.onAttached(() => {
 console.log('Device is attached');
});

onConnected(cb) → {function}

Parameters:

Name	Type	Description
`cb`	function	The callback function to register

Example

// Inside an async function
driver.onConnected(() => {
 console.log('Device is connected');
});

onDisconnected(cb) → {function}

Parameters:

Name	Type	Description
`cb`	function	The callback function to register

Example

// Inside an async function
driver.onDisconnected(() => {
 console.log('Device is disconnected');
});

onRemoved(cb) → {function}

Parameters:

Name	Type	Description
`cb`	function	The callback function to register

Example

// Inside an async function
driver.onRemoved(() => {
 console.log('Device is removed');
});

(async) open() → {Promise.<undefined>}

Open the communication to the peripheral
Note: All drivers will handle the attach and removal events, they will manage the closing of communication channel after a removal and handle the connection of an attached device.

Example

// Inside an async function

try {
 console.log('The drivers communication channel is opening');
 await driver.open();
 console.log('The driver is opened');
} catch (ex) {
 if (ex instanceof AgentNotAttachedException) {
     console.warn('The peripheral is not attached');
     // Note: This error can be avoided by checking if the device is attached using the `isAttached()` function
 }

 if (ex instanceof AgentAlreadyConnectedException) {
     console.warn('The communication channel is already opened');
     // Note: This error can be avoided by checking if the device is connected using the `isConnected()` function
 }
}

(async) setTimeout(timeout) → {Promise.<undefined>}

Set the default timeout value in milliseconds, !Important!
This may be set to a number up to 120 seconds (2 minutes)

Parameters:

Name	Type	Description
`timeout`	Number	The length of time to wait before timing out in Milliseconds

Example

// Inside an async function
const timeToWaitForFunctions = 60000;
await driver.setTimeout(timeToWaitForFunctions);

// The functions will now wait for 60 seconds before throwing the AgentTimedOutException