calumk / ftdi-d2xx

🔌 Pre-compiled FTDI D2XX drivers for Node.js (Node-API/CMake)

FTDI D2XX Driver for Node.js

Features

• Asynchronous, non-blocking functions (use Promises or async/await)
• Pre-compiled for Windows / macOS / Linux
• Compatible with Electron (see the note below)
• Includes static FTDI Driver vendor libraries
• Written in pure C language using Node-API
• Detailed error messages and codes are thrown without crashing Node.js
• Includes TypeScript typings for auto-completion and validation
• Compiled with CMake.js (no gyp / no Python required)

Installation

In your Node.js project folder, run:

npm install ftdi-d2xx

On the top of your JavaScript file, add:

const FTDI = require('ftdi-d2xx'); // CommonJS syntax (.js files)
// import FTDI from 'ftdi-d2xx'; // ESM syntax (.mjs files)

Quick example

let device;

async function quick_example() {

  try {
    // Get the connected devices info list 
    const list = await FTDI.getDeviceInfoList();
    console.log(`${list.length} device${list.length>1?'s':''} found:`, list);
    
    // If there is at least one device connected
    if(list.length) {
  
      // Try to open the first device from the list
      device = await FTDI.openDevice(list[0].serial_number); // alternatively openDevice({ usb_loc_id: list[0].usb_loc_id });
      console.log(`One device open:`, device);

      // Setup the device
      device.setTimeouts(1000, 1000); // set the max TX and RX duration in ms
      device.purge(FTDI.FT_PURGE_RX); // purge the RX buffer from previous received data
      //device.setBaudRate(115200); // set the UART baud rate (bits per second)
      //device.setDataCharacteristics(FTDI.FT_BITS_8, FTDI.FT_STOP_BITS_1, FTDI.FT_PARITY_NONE);
  
      // Send data from the TXD pin of the device
      await device.write(Uint8Array.from([1, 2, 3, 4]));
      console.log(`Data sent successfully.`);
  
      // Wait to receive from the RXD pin
      console.log(`Trying to receive data...`);
      const response = await device.read(4); // expected response byte length (will return either if this is reached or after an RX timeout)
      console.log(`${response.byteLength} bytes were received:`, response);

      // If TXD and RXD pins are connected together, you should get Uint8Array(4)[1, 2, 3, 4] immediately
      // If not, you should get Uint8Array(0)[] after 1 second of timeout

      // Close the device (device object must then be recreated using openDevice)
      device.close();

      // Be careful "not to loose" the device object before closing it, otherwise
      // the device will likely stay open and you will not be able to re-open it.
    }
  } catch (e) {
    console.error(e);
  }
}

// Run the example
await quick_example();

Docs

• FTDI D2XX Programmer's Guide
• ftdi-d2xx JavaScript implementation API

Note

On Windows, FT_Reload() is implemented under FTDI.setVIDPID().

Note

See the included FTDI D2XX driver library versions in the CHANGELOG.md file.

Note to Electron users

As you may already know, Electron runs in two processes: a main process and a renderer process (more info here).

For security reasons, in the newest releases of Electron, you can only access Node.js inside the main process. However, you probably want to interact with this API using buttons, or to display information in the renderer process. It lets you two options:

• Option 1 : Accessing this API only inside a preload.js file which has access to Node.js and can also export globals to the renderer process (recommended):
  • This file shall be associated to the BrowserWindow of your application using webPreferences.preload field with webPreferences.sandbox set to false to enable external modules loading (more info here).
  • This file shall contain (or require) all your functions calling this FTDI library.
  • This file shall contain a contextBridge to expose your functions globally to the renderer process (more info here).
  • Important: information exchanged in the pipe between main process and renderer process (Electron calls it IPC) is serialized. That means data is converted in a JSON-like file format before being passed. Only these data types are supported (more info here).
  • Note: for the above reason, exposing the FTDI library object or functions directly to the renderer process doesn't work (it would be a bad security practice anyway).
• Option 2 : Disabling the security and allowing Node.js to run in the renderer process (more info here - not recommended).

Important

If you use a compiler for your Electron project and you get errors, make sure to exclude this library from compilation as a native library.

To do

To be added if there is a need for it:

• Add FT_SetEventNotification in a separate worker, with JS event handlers
• Add FT_Rescan, FT_CyclePort, FT_SetResetPipeRetryCount, FT_StopInTask, FT_RestartInTask, FT_SetDeadmanTimeout. Hopefully with the latest drivers and recent hardware, these functions are not needed anymore.
• Add FT_SetChars function
• Add the other FT_EE_* functions

Development

• Download and install CMake on your computer
• Clone this repository, add your modifications if needed
• Run npm install inside the repository to install development dependencies locally (cmake-js and typedoc)
• Compile the code:
  • Running npm run cmake:rebuild-debug will rebuild the debug version of ftdi-d2xx.node for your platform and processor under build/Debug
  • Running npm run cmake:rebuild-release will build ftdi-d2xx.platform.processor.node under build/Release
  • Running npm run cmake:clean will clean the build folder
• Run npm run node:test to execute the /test.js file, which loads the Debug Build and runs basic initialization code followed by a REPL console to test function calls dynamically
• Run npm run typedoc to regenerate the API documentation
• Make a pull request to share your work

Sponsor

The original work for the library wrapper has been sponsored by ONWI, a small electronics design office and production unit based near Lyon, France.

Licensing

This library is distributed under the terms of the GNU LGPLv3.

It includes the official libftd2xx library provided by FTDI, which is released under their specific Driver Licence Terms (https://ftdichip.com/driver-licence-terms/). Please make sure you agree to all the License Terms before using this library. See the included library versions in the CHANGELOG.md file.

libftd2xx uses an unmodified version of libusb (http://libusb.info) which is distributed under the terms of the GNU Lesser General Public License. Source code for libusb is included in this distribution for reference (lib/libusb-source).