README
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 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
LoupedeckDevice
Class 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
orCOM2
) (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 tofalse
if you'd prefer to callconnect()
. yourself.
'connect'
Event: Emitted when connection to the device succeeds.
'down'
Event: Emitted when a button or knob is pressed down.
Arguments:
id
: Button ID (seedevice.js
for valid button names)
'rotate'
Event: Emitted when a knob is rotated.
Arguments:
id
: Button ID (seedevice.js
for valid button names)delta
: Rotation direction,-1
for counter-clockwise,1
for clockwise.
'touchstart'
Event: Emitted when any part of the screen is touched for the first time.
Arguments:
changedTouches
: Array of new touches created during this eventtouches
: Array of all currently held touches on screen
'touchmove'
Event: Emitted when a touch moves across the screen.
Arguments:
changedTouches
: Array of touches changed during this eventtouches
: Array of all currently held touches on screen
'touchend'
Event: Emitted when a touch is no longer detected.
Arguments:
changedTouches
: Array of touches removed during this eventtouches
: Array of all currently held touches on screen (if any)
'up'
Event: Emitted when a button or knob is released.
Arguments:
id
: Button ID (seedevice.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 drawheight
: Height of area to drawx
: 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 contextwidth
: Width of drawing areaheight
: 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 contextwidth
: Width of drawing areaheight
: Height of drawing area
device.drawScreen(screenID : String, callback : Function)
Draw graphics to a specific screen. Screen sizes are as follows:
left
: 60x270pxcenter
: 360x270pxright
: 60x60px
screenID
: Screen to write to [left
,center
,right
]callback
: Function to handle draw calls. Receives the following arguments:context
: 2d canvas graphics contextwidth
: Width of drawing areaheight
: Height of drawing area
device.getInfo() : Object
Request device information. Returns:
serial
: Device serial numberversion
: 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 (seedevice.js
for valid button names)color
: Any valid CSS color string
device.vibrate(pattern? : byte)
Make device vibrate.
pattern
: A valid vibration pattern (seeHAPTIC
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 identifierx
: 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 oncenter
screen)
Contributing & Tests
- Install development dependencies:
npm install
- Run tests:
npm test
Thanks
Big thanks go out to Max Maischein's earlier work in Perl on this topic.
License
MIT