halvves / webmonome

we've moved to sourcehut! this is just a mirror of: https://sr.ht/~merl/webmonome/

WebMonome

npm	0.0.1-alpha.8
size	1.96kb minzipped
dependencies	zero
license	MIT

communicate with devices beyond a translator

webmonome is a little library designed to enable communication with monome devices directly from the web browser (bypassing serialosc). while serialosc is the best choice 99% of the time, i thought that it might be nice to enable the creation of monome apps that required zero install/config.

usage

script include

<script src="https://unpkg.com/webmonome@alpha"></script>

const monome = new WebMonome();

const btn = document.createElement('button');
btn.innerHTML = 'connect';
btn.addEventListener('click', () => {
  monome.connect();
});
document.body.appendChild(btn);

const keydown = e => {
  monome.gridLed(e.x, e.y, true);
};

const keyup = e => {
  monome.gridLed(e.x, e.y);
};

monome.on('gridKeyDown', keydown);
monome.on('gridKeyUp', keyup);

import

npm install webmonome@alpha

import WebMonome from 'webmonome';

const monome = new WebMonome();

const btn = document.createElement('button');
btn.innerHTML = 'connect';
btn.addEventListener('click', () => {
  monome.connect();
});
document.body.appendChild(btn);

const keydown = e => {
  monome.gridLed(e.x, e.y, true);
};

const keyup = e => {
  monome.gridLed(e.x, e.y);
};

monome.on('gridKeyDown', keydown);
monome.on('gridKeyUp', keyup);

requirements

webmonome relies on the WebUSB api. information on browser support for the WebUSB api can be found over at caniuse.

webmonome also requires that serialosc is disabled. On macOS open Terminal and execute:

launchctl unload /Library/LaunchAgents/org.monome.serialosc.plist

To re-enable:

launchctl load /Library/LaunchAgents/org.monome.serialosc.plist

api

webmonome is currently very bare bones (as i'm still working out the kinks with WebUSB and the monome serial protocol), but there is enough there to perform most grid operations.

connect

• initialize WebUSB and connect to device:

  monome.connect()

system

system responses come in the form of events (see below), but this may be changed to include a callback or promise for ergonomics.

• request device information:

  monome.query()

• request device id:

  monome.getId()

• request grid size:

  monome.getGridSize()

grid ops

• set a single LED on or off:

  monome.gridLed(xCoord, yCoord, on)

  • xCoord: integer
  • yCoord: integer
  • on: boolean

• set all LEDs on or off:

  monome.gridLedAll(on)

  • on: boolean

• set on/off state for column of LEDs:

  monome.gridLedCol(xOffset, yOffset, state)

  • xOffset: integer
  • yOffset: integer (floored to multiples of 8 by the device firmware)
  • state: array of up to 8 0/1 bits

• set on/off state for row of LEDs:

  monome.gridLedRow(xOffset, yOffset, state)

  • xOffset: integer (floored to multiples of 8 by the device firmware)
  • yOffset: integer
  • state: array of up to 8 0/1 bits

• set on/off state for an 8x8 quad of LEDs:

  monome.gridLedMap(xOffset, yOffset, state)

  xOffset: integer yOffset: integer state: array of up to 64 0/1 bits

• set system wide grid intensity:

  monome.gridLedIntensity(intensity)

  • intensity: integer (0-15)

• set single LED to specific level:

  monome.gridLedLevel(xCoord, yCoord, level)

  • xCoord: integer
  • yCoord: integer
  • level: integer (0-15)

• set all LEDs to specific level:

  monome.gridLedLevelAll(level)

  • level: integer (0-15)

• set level state for column of LEDs:

  monome.gridLedLevelCol(num: xOffset, num: yOffset, []num: state)

  • xOffset: integer
  • yOffset: integer (floored to multiples of 8 by the device firmware)
  • state: array of up to 8 integers (0-15)

• set level state for row of LEDs:

  monome.gridLedLevelRow(num: xOffset, num: yOffset, []num: state)

  • xOffset: integer (floored to multiples of 8 by the device firmware)
  • yOffset: integer
  • state: array of up to 8 integers (0-15)

• set level state for an 8x8 quad of LEDs:

  monome.gridLedLevelMap(num: xOffset, num: yOffset, []num: state)

  • xOffset: integer
  • yOffset: integer
  • state: array of up to 64 integers (0-15)

event system

• subscribe to events:

  monome.addEventListener(eventName, callback)

  • eventName: string
  • callback: function

• unsubscribe from events:

  monome.removeEventListener(eventName, callback)

  • eventName: string
  • callback: function

events

• query {type: num, count: num}
• getId str
• getGridSize {x: num, y: num}
• gridKeyDown {x: num, y: num}
• gridKeyUp {x: num, y: num}

next steps

• remaining /sys/ commands
  • grid offsets
  • addr scan
  • firmware version
• arc ops
• add any additional ops in the monome serial protocol (reaching something similar to libmonome)

see also

• monome protocol
• libmonome
• serialosc

webmonome's Issues

Higher level LED methods?

The monome protocol specifies that messages for LED rows, columns, and maps target a "quad", i.e. an 8x8 segment with an x/y offset. The webmonome API reflects this, but I'm wondering if we could add some higher level methods to make it easier to set LED states in one call.

For example, in mlr, a single LED tracks the sample's play position. In JavaScript we might track this with an array of 16 items:

let row = [0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0]

To convey is to a device, we have to split the array into two chunks of 8, then call gridLedRow twice with offsets:

let chunks = chunk(row, 8) // [[0,0,0,0,0,0,0,0],[0,0,0,0,0,1,0,0]]
chunks.forEach((chunk, i) => monome.gridLedRow(i * 8, rowNumber, chunk))

I'm wondering if a nicer API might be:

monome.gridLedRow(rowNumber, row)

(and perhaps rename the current methods to gridLedRowQuad, or something?

Compatibility with 2008 Monome 64?

Thanks so much for creating this! I'm so glad it exists :)
I have a reasonably old Monome 64 (bought ~2008). I have been trying to get webmonome working, but am having some issues, and wondered if you had any ideas?

Connecting the device works, but when pressing keys, it throws RangeError: Offset is outside the bounds of the DataView on

webmonome/src/webmonome.js

Line 163 in 55c544c

count: result.data.getUint8(start++),

because start is 5, whereas the data view only has a byle length of 4. And possibly related, when pressing a key, the header is matching a query in the switch/case, whereas I'm wondering if that should match the keydown header value instead?

Programmatically setting LEDs also didn't work, so I'm wondering if it's an issue with it being a Monome 64 vs a 128? (The nodejs grid studies code with serialosc seems to work as expected.)

Let me know if you need more info, and thanks again!