Metacowboy / loupedeck

Node.js API for Loupedeck Controllers

Loupedeck: Node.js Interface

Unofficial Node.js API for Loupedeck Live controllers.

⚠️ Beta version: API is subject to change

Supports:

• Reading button presses
• Reading knob turns
• Reading touch events
• Setting button colors
• Setting screen brightness
• Vibrating device
• Writing screen graphics

Requirements

• Node 11+

Installation

npm install loupedeck

Usage Examples

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

const { LoupedeckDevice } = require('loupedeck')

// Detects and opens first connected device
const device = new LoupedeckDevice()

// 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}`)
})

For all examples, see the examples folder.

📝 API Docs

Class LoupedeckDevice

Main device class.

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

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

Create a new Loupdeck device interface.

Most use-cases should omit the host parameter, unless you're using multiple devices or know specifically which IP you want to connect to.

• host: Host or IP address to connect to (example: 127.100.1.1) (default: autodiscover)
• autoConnect: Automatically connect during construction. (default: true) Set to false if you'd prefer to call connect(). yourself.

Event: 'connect'

Emitted when connection to the device succeeds.

Event: 'down'

Emitted when a button or knob is pressed down.

Arguments:

• id: Button ID (see device.js for valid button names)

Event: 'rotate'

Emitted when a knob is rotated.

Arguments:

• id: Button ID (see device.js for valid button names)
• delta: Rotation direction, -1 for counter-clockwise, 1 for clockwise.

Event: 'touchstart'

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

Arguments:

• changedTouches: Array of new touches created during this event
• touches: Array of all currently held touches on screen

Event: 'touchmove'

Emitted when a touch moves across the screen.

Arguments:

• changedTouches: Array of touches changed during this event
• touches: Array of all currently held touches on screen

Event: 'touchend'

Emitted when a touch is no longer detected.

Arguments:

• changedTouches: Array of touches removed during this event
• touches: Array of all currently held touches on screen (if any)

Event: 'up'

Emitted when a button or knob is released.

Arguments:

• id: Button ID (see device.js for valid button names)

device.connect() : Promise

Manually connect if autoConnect set to false during construction. Resolves once a connection has been established.

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

Draw graphics to a particular area. Lower-level method if drawKey() or drawScreen() don't meet your needs.

• id: Screen to write to [left, center, right]
• width: Width of area to draw
• height: Height of area to draw
• x: Starting X offset (default: 0)
• y: Starting Y offset (default: 0)
• autoRefresh: Whether to refresh the screen after drawing (default: true)
• callback: Function to handle draw calls. Receives the following arguments:
  • context: 2d canvas graphics context
  • width: Width of drawing area
  • height: Height of drawing area

device.drawKey(key : Number, callback : Function)

Draw graphics to a specific key. Width and height of callback will be 90, as keys are 90x90px.

• key: Key index to write to [0-11]
• callback: Function to handle draw calls. Receives the following arguments:
  • context: 2d canvas graphics context
  • width: Width of drawing area
  • height: Height of drawing area

device.drawScreen(screenID : String, callback : Function)

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

• left: 60x270px
• center: 360x270px
• right: 60x60px

• screenID: Screen to write to [left, center, right]
• callback: Function to handle draw calls. Receives the following arguments:
  • context: 2d canvas graphics context
  • width: Width of drawing area
  • height: Height of drawing area

device.getInfo() : Object

Request device information. Returns:

• serial: Device serial number
• version: Firmware version

device.setBrightness(brightness : Number)

Set screen brightness.

• brightness: Number between (0, 1) (0 would turn the screen off, 1 for full brightness)

device.setColor({ id : String, color : String })

Set a button LED to a particular color.

• id: Button ID (see device.js for valid button names)
• color: Any valid CSS color string

device.vibrate(pattern? : byte)

Make device vibrate.

• pattern: A valid vibration pattern (see HAPTIC for valid patterns) (default: HAPTIC.SHORT)

Touch Objects

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

• id: Unique touch identifier
• x: Screen X-coordinate ([0, 480])
• y: Screen Y-coordinate ([0, 270])
• target:
  • screen: Identifier of screen this touch was detected on ([left, center, right])
  • key: Index of key touched ([0-11]) (undefined if not on center screen)

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