loupedeck

Loupedeck Device Interface

Usage no npm install needed!

<script type="module">
  import loupedeck from 'https://cdn.skypack.dev/loupedeck';
</script>

README

Loupedeck: Node.js Interface

tests

Unofficial Node.js API for Loupedeck Live controllers.

Loupedeck Live Interface

⚠️ 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 12+
  • Loupedeck

This library has been tested with firmware versions 0.1.79 and 0.2.5. Other versions may work.

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({ path : String?, host : String?, autoConnect : Boolean? })

Create a new Loupdeck 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.

  • path: (Firmware 0.2.X only) Serial device path (example: /dev/cu.ttymodem-1332 or COM2) (default: autodiscover)
  • host: (Firmware 0.1.X only) 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.close()

Close device connection.

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:

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:

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:

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.

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