Necessitates Proper Modularity

    @xencelabs-quick-keys/node
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.0 • Public • Published

    @xencelabs-quick-keys/node

    Node CI codecov

    npm version license

    @xencelabs-quick-keys/node is a shared library for interfacing with the various models of the Xencelabs Quick Keys.

    Intended use

    This library has nothing to do with the software produced by the manufacturer. There is nothing here to install and run. This is a library to help developers make alternatives to that software

    Install

    $ npm install --save @xencelabs-quick-keys/node

    Native dependencies

    All of this library's native dependencies ship with prebuilt binaries, so having a full compiler toolchain should not be necessary to install @xencelabs-quick-keys/node.

    However, in the event that installation does fail (or if you are on a platform that our dependencies don't provide prebuilt binaries for, such as a Raspberry Pi), you will need to install a compiler toolchain to enable npm to build some of @xencelabs-quick-keys/node's dependencies from source. Expand the details block below for full instructions on how to do so.

    Compiling dependencies from source
    • Windows
      npm install --global windows-build-tools
    • MacOS
      • Install the Xcode Command Line Tools:
      xcode-select --install
    • Linux (including Raspberry Pi)
      • Follow the instructions for Linux in the "Compiling from source" steps for
      • Try installing @xencelabs-quick-keys/node
      • If you still have issues, ensure everything is updated and try again:
        sudo apt-get update && sudo apt-get upgrade

    Linux

    On linux, the udev subsystem blocks access to the device without some special configuration. Save the following to /etc/udev/rules.d/50-xencelabs.rules and reload the rules with sudo udevadm control --reload-rules

    SUBSYSTEM=="input", GROUP="input", MODE="0666"
    SUBSYSTEM=="usb", ATTRS{idVendor}=="28bd", ATTRS{idProduct}=="5202", MODE:="666", GROUP="plugdev"
    SUBSYSTEM=="usb", ATTRS{idVendor}=="28bd", ATTRS{idProduct}=="5203", MODE:="666", GROUP="plugdev"
    KERNEL=="hidraw*", ATTRS{busnum}=="1", ATTRS{idVendor}=="28bd", ATTRS{idProduct}=="5202", MODE="0666"
    KERNEL=="hidraw*", ATTRS{busnum}=="1", ATTRS{idVendor}=="28bd", ATTRS{idProduct}=="5203", MODE="0666"
    

    Unplug and replug the device and it should be usable

    Features

    • Multiplatform support: Windows, MacOS, Linux, and even Raspberry Pi!
    • Key down and key up events
    • Wheel turn events
    • Set text labels of buttons
    • Show text overlays
    • Set the wheel speed
    • Set the display orientation
    • Set the display brightness
    • Set the wheel color
    • TypeScript support

    API

    The root methods exposed by the library are as follows. For more information it is recommended to rely on the typescript typings for hints or to browse through the source to see what methods are available

    /**
     * Scan for and list detected devices
     */
    export function listXencelabsQuickKeys(): XencelabsQuickKeysInfo[]
    
    /**
     * Get the info of a device if the given path is a compatible device
     */
    export function getXencelabsQuickKeysInfo(path: string): XencelabsQuickKeysInfo | undefined
    
    /**
     * Open a device
     * @param devicePath The path of the device to open. If not set, the first will be used
     */
    export function openXencelabsQuickKeys(devicePath?: string): XencelabsQuickKeysNode

    The XencelabsQuickKeys type can be found here

    Example

    import { XencelabsQuickKeysManagerInstance } from '@xencelabs-quick-keys/node'
    
    // start listening for devices
    XencelabsQuickKeysManagerInstance.on('connect', (myDevice) => {
    	// Device has connected
    
    	// Open the streams for data read and write
    	await myDevice.startData()
    
    	myDevice.on('down', (keyIndex) => {
    		console.log('key %d down', keyIndex)
    	})
    
    	myDevice.on('up', (keyIndex) => {
    		console.log('key %d up', keyIndex)
    	})
    
    	// Fired whenever an error is detected by the `node-hid` library.
    	// Always add a listener for this event! If you don't, errors will be silently dropped.
    	myDevice.on('error', (error) => {
    		console.error(error)
    	})
    
    	myDevices.on('wheel', (e) => {
    		console.log('wheel %s', e)
    	})
    
    	// Fill the first button text. This is asynchronous.
    	await myDevices.setKeyText(4, 'test')
    	console.log('Successfully wrote text to key 4.')
    })
    XencelabsQuickKeysManagerInstance.on('disconnect', (myDevice) => {
    	// Device has disconnected
    })
    
    // Prompt the user to grant access to some devices
    XencelabsQuickKeysManagerInstance.requestXencelabsQuickKeys().catch((e) => {
    	console.error(`scan failed: ${e}`)
    })

    Contributing

    The xencelabs-quick-keys team enthusiastically welcomes contributions and project participation! There's a bunch of things you can do if you want to contribute! Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear.

    Please refer to the Changelog for project history details, too.

    Install

    npm i @xencelabs-quick-keys/node

    DownloadsWeekly Downloads

    10

    Version

    0.4.0

    License

    MIT

    Unpacked Size

    20.3 kB

    Total Files

    19

    Last publish

    Collaborators

    • julusian