search

foxxyz / loupedeck

Node.js API for Loupedeck Controllers
MIT License
87 stars 10 forks source link

readme

Loupedeck: Node.js Interface

tests

Unofficial Node.js API for Loupedeck Live, Loupedeck Live S, Loupedeck CT and Razer Stream controllers.

Loupedeck Live Interface Razer Stream Controller Interface Razer Stream Controller X Interface Loupedeck Live S Interface Loupedeck CT Interface

Supports:

Requirements

This library has been tested with firmware versions 0.1.3, 0.1.79, 0.2.5, 0.2.8 and 0.2.23. Other versions may work.

Installation

npm install loupedeck

By default, loupedeck uses RGB565 (16-bit) buffers for drawing (with small exceptions, see below). To enable a more pleasant API that allows for drawing using Canvas API callbacks, also install canvas:

npm install canvas

Usage Examples

Note: Ensure Loupedeck software is not running as it may conflict with this library

Automatic Discovery

import { discover } from 'loupedeck'

// Detects and opens first connected device
const device = await discover()

// Observe connect events
device.on('connect', () => {
    console.info('Connection successful!')
})

// React to button presses
device.on('down', ({ id }) => {
    console.info(`Button pressed: ${id}`)
})

// React to knob turns
device.on('rotate', ({ id, delta }) => {
    console.info(`Knob ${id} rotated: ${delta}`)
})

Manual Instantiation

import { LoupedeckLiveS } from 'loupedeck'

const device = new LoupedeckLiveS({ path: '/dev/tty.usbmodem101', autoConnect: false })
await device.connect()
console.info('Connection successful!')

device.on('down', ({ id }) => {
    console.info(`Button pressed: ${id}`)
})

For all examples, see the examples folder. Running some examples requires canvas to be installed (see above).

📝 API Docs

discover() : Promise<LoupedeckDevice>

Find the first connected Loupedeck device and return it.

Returns an instance of LoupedeckLive, LoupedeckLiveS, LoupedeckCT, RazerStreamController, RazerStreamControllerX, or throws an Error in case none or unsupported devices are found.

Class LoupedeckLive

Implements and supports all methods from the LoupedeckDevice interface.

new LoupedeckLive({ path : String?, host : String?, autoConnect : Boolean? })

Create a new Loupedeck Live device interface.

Most use-cases should omit the host/path parameter, unless you're using multiple devices or know specifically which IP or device path you want to connect to. Either use path OR host, never both.

Class LoupedeckCT

Same interface as LoupedeckLive.

Class LoupedeckLiveS

Same interface as LoupedeckLive.

Class RazerStreamController

Same interface as LoupedeckLive.

Class RazerStreamControllerX

Same interface as LoupedeckLive.

Does not implement vibration or button colors.

Interface LoupedeckDevice

Shared device interface. Do not instantiate this manually, use one of the above classes instead or the discover() function.

All incoming messages are emitted as action events and can be subscribed to via device.on().

LoupedeckDevice.list({ ignoreSerial : Boolean?, ignoreWebsocket : Boolean?} = {}) : Promise<Array>

Static method to scan for and return a list of all detected devices. This includes ones which are already opened.

Device info can be directly passed on to the constructor below.

Event: 'connect'

Emitted when connection to the device succeeds. Includes an info object containing:

Event: 'disconnect'

Emitted when a device disconnects for any reason. First argument for the event is an Error object in case of an abnormal disconnect (otherwise undefined).

Event: 'down'

Emitted when a button or knob is pressed down.

Arguments:

Event: 'rotate'

Emitted when a knob is rotated.

Arguments:

Event: 'touchstart'

Emitted when any part of the screen is touched for the first time.

Arguments:

Event: 'touchmove'

Emitted when a touch moves across the screen.

Arguments:

Event: 'touchend'

Emitted when a touch is no longer detected.

Arguments:

Event: 'up'

Emitted when a button or knob is released.

Arguments:

device.close() : Promise

Close device connection.

Returns Promise which resolves once the device has been closed.

device.connect() : Promise

Manually connect. Resolves on success.

device.drawBuffer({ id : String, width : Number, height : Number, x? : Number, y? : Number, autoRefresh? : Boolean }, buffer : Buffer) : Promise

Draw graphics to a particular area using a RGB16-565 pixel buffer.

Lower-level method if drawKey() or drawScreen() don't meet your needs.

Returns a Promise which resolves once the command has been acknowledged by the device.

device.drawCanvas({ id : String, width : Number, height : Number, x? : Number, y? : Number, autoRefresh? : Boolean }, callback : Function) : Promise

Draw graphics to a particular area using the Canvas API. Requires canvas to be installed.

Lower-level method if drawKey() or drawScreen() don't meet your needs.

Returns a Promise which resolves once the command has been acknowledged by the device.

device.drawKey(key : Number, buffer/callback : Buffer/Function) : Promise

Draw graphics to a specific key.

Second argument can be either a RGB16-565 buffer or a callback. Width and height of callback will typically be 90, as keys are mostly 90x90px (RSCX being the exception - those keys are 96x96px).

Returns a Promise which resolves once the command has been acknowledged by the device.

device.drawScreen(screenID : String, buffer/callback : Buffer/Function) : Promise

Draw graphics to a specific screen. Screen sizes are as follows:

Loupedeck CT:

Loupedeck Live / Razer Stream Controller:

Loupedeck Live S:

Razer Stream Controller X:

Returns a Promise which resolves once the command has been acknowledged by the device.

device.getInfo() : Promise

Request device information. Returns a promise resolving to object containing:

If the device is not connected, the promise will reject.

device.setBrightness(brightness : Number) : Promise

Set screen brightness.

Returns a Promise which resolves once the command has been acknowledged by the device.

device.setButtonColor({ id : String, color : String }) : Promise

Set a button LED to a particular color. (Unavailable on RSCX)

Returns a Promise which resolves once the command has been acknowledged by the device.

device.vibrate(pattern? : byte) : Promise

Make device vibrate. (Unavailable on RSCX)

Returns a Promise which resolves once the command has been acknowledged by the device.

Touch Objects

Touch objects are emitted in the touchstart, touchmove, and touchend events and have the following properties:

Contributing & Tests

  1. Install development dependencies: npm install
  2. Run tests: npm test

Thanks

Big thanks go out to Max Maischein's earlier work in Perl on this topic.

License

MIT