@xencelabs-quick-keys/node

@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
  • Install windows-build-tools:

  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

// TODO

The XencelabsQuickKeys type can be found here

Example

import { XencelabsQuickKeysManagerInstance } from '@xencelabs-quick-keys/node'

// start listening for devices
XencelabsQuickKeysManagerInstance.on('connect', async (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)
	})

	myDevice.on('wheel', (e) => {
		console.log('wheel %s', e)
	})

	// Fill the first button text. This is asynchronous.
	await myDevice.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.scanDevices().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.