Initial Commit

Author: halfbyte

.gitignore

@@ -0,0 +1,3 @@
+package-lock.json
+node_modules
+.node-version

LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright (c) 2018, Jan Krutisch <jan@krutisch.de>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -0,0 +1,58 @@
+# ableton-push-canvas-display
+
+Ableton Push 2 has a high resolution color display that can be updated via libusb very easily.
+The hardest part is drawing pretty graphics. Usually people use frameworks like JUCE for that, but
+with node and the web, we have something simple, that should also work: The canvas.
+
+This package does that hard work of converting the image data from a canvas to the slightly weird
+push framebuffer format and sending it via USB.
+
+## How to use
+
+Since this uses node libusb bindings, you need to have a node environment. This means that it
+actually works in electron, even in the renderer process. That also means that you can send a canvas
+that is actually rendered in a web page.
+
+Here's a minimal example that assumes a set up canvas. The canvas should be 960x160 (the display
+size of Push 2).
+
+```JavaScript
+const { initPush, sendFrame } = require('ableton-push-canvas-display')
+
+function render() {
+  ctx.clearRect(...)
+  ctx.strokeLine(...)
+  sendFrame(ctx, (err) => {
+    render() // you probably want to do something like requestAnimationFrame or so.
+  })
+}
+
+initPush((err) => {
+  if (!err) {
+    render()
+  }
+})
+```
+
+If you can't or don't want to use a web canvas, there's a npm package called "canvas" that
+replicates the API using libcairo which works as an image source as well.
+
+## Pitfalls
+
+If you don't clear the canvas with a solid background, the results will look weird, as the
+conversion process doesn't take the alpha channel into account. As soon as you render to a solid
+background, the alpha masks (for antia aliasing for example) are baked and it should look ok.
+
+For performance reasons I'm using direct access to typed arrays which means that things can go wrong
+in terms of endianness if you are not on a little endian machine. (which is VERY rare nowadays)
+
+The libusb bulk transfer process takes up almost all of the 16 ms we have to make this a 60fps
+operation on my iMac, so there could be some jank sometimes. I have to test this on other hardware
+to see if it needs additional optimisations.
+
+## Status
+
+This needs tests (sort of hard to test without actual hardware, but I guess I could at least test
+the conversion process properly).
+
+It is not handling multiple push devices. Not sure that this is actually a valid usecase for me.

examples/simple-anim.js

@@ -0,0 +1,39 @@
+const Canvas = require('canvas')
+const path = require('path')
+const { initPush, sendFrame } = require(path.join(__dirname, '..', 'index.js'))
+
+const canvas = new Canvas(960,160)
+const ctx = canvas.getContext('2d')
+
+function drawFrame(ctx, frameNum) {
+  ctx.strokeStyle = "#ff0"
+  ctx.fillStyle = "#000"
+  ctx.fillRect(0, 0, 960, 160)
+  ctx.fillStyle = "hsl(" + frameNum % 360 +",100%,50%)"
+  ctx.lineWidth = 4
+  ctx.fillRect((frameNum * 2) % 960, (frameNum * 2) % 160, 20, 20)
+  ctx.beginPath()
+  ctx.arc(100, 100, 50, 0, (frameNum / 20.0) % (2 * Math.PI))
+  ctx.lineTo(100, 100)
+  ctx.stroke()
+
+  ctx.font = '800 20px "SF Pro Display"';
+  ctx.fillStyle = '#fff'
+  ctx.fillText("Awesome!", 50, 100);
+}
+
+let frameNum = 0
+
+function nextFrame() {
+  drawFrame(ctx, frameNum)
+  frameNum++
+  sendFrame(ctx, function() {
+    process.nextTick(function() {
+      nextFrame()
+    })
+  })
+}
+
+initPush(function() {
+  nextFrame()
+})

index.js

@@ -0,0 +1,102 @@
+const USB = require('usb')
+const PUSH_VID = 0x2982
+const PUSH_PID = 0x1967
+const PUSH_FRAME_SIZE = 327680
+const PUSH_LINE_SIZE = 2048
+const PUSH_BUFFER_SIZE = PUSH_FRAME_SIZE
+const PUSH_XOR_PATTERN = 0xFFE7F3E7
+const PUSH_BUFFER_COUNT = PUSH_FRAME_SIZE / PUSH_BUFFER_SIZE
+const PUSH_FRAME_HEADER = [0xFF, 0xCC, 0xAA, 0x88, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 ]
+
+var endpoint;
+var interface;
+
+const frameData = new ArrayBuffer(327680)
+
+/* The actual conversion function */
+function convertImage(image, frame) {
+  var y,h,x,w;
+  for(y=0;y<160;y++) {
+    const frameLineStart = PUSH_LINE_SIZE * y
+    const frameLine = new Uint16Array(frame, frameLineStart, PUSH_LINE_SIZE / 2)
+    for(x=0;x<1024;x++) {
+      var word = 0
+      if (x < 960) {
+        const off = (y * 3840) + x * 4
+        const r = image[off + 0] >> 3
+        const g = image[off + 1] >> 2
+        const b = image[off + 2] >> 3
+        word = (r & 0b11111) | ((g & 0b111111) << 5) | ((b & 0b11111) << 11)
+      }
+      var mask = 0xF3E7
+      if (x & 1 > 0) {
+        mask = 0xFFE7
+      }
+      frameLine[x] = word ^ mask
+    }
+  }
+}
+/* this is thi actual device init */
+function _init(push) {
+  if (push == null) { return; }
+  push.open()
+  const pushInterface = push.interface(0)
+  pushInterface.claim()
+  endpoint = pushInterface.endpoint(1)
+}
+
+/**
+ * initialize the push device. his will open the push device and claim the display interface.
+ * This function also sets up callbacks for later device addition, so that the push gets
+ * initialized if added to the system later
+ * @param { function(error) } callback - callback will be called after init. Follows node's "error first" async convention
+ */
+function initPush(callback) {
+  var push = USB.findByIds(PUSH_VID, PUSH_PID)
+  USB.on('attach', function(device) {
+    if (device.deviceDescriptor.idVendor === PUSH_VID && device.deviceDescriptor.idProduct === PUSH_PID) {
+      _init(device)
+    }
+  })
+  USB.on('detach', function(device) {
+    if (device.deviceDescriptor.idVendor === PUSH_VID && device.deviceDescriptor.idProduct === PUSH_PID) {
+      endpoint = null
+    }
+  })
+  if (push == null) {
+    callback(new Error("Push not found"))
+  }
+  _init(push)
+  callback()
+}
+
+/**
+ * sends the current content of the given canvas context to the push.
+ * The function assumes the canvas has the correct dimenstions.
+ * It's fine to call this function even if initPush returned an error, as Push may have
+ * been added to the system at a later time.
+ * @param { Context2D } ctx - the canvas context. Both a native web canvas and node-canvas work.
+ * @param { function(error) } callback - callback will be called after init. Follows node's "error first" async convention
+ */
+function sendFrame(ctx, callback) {
+  if (!endpoint) { callback(new Error("No Push available")); return; } // push not available
+  convertImage(ctx.getImageData(0,0,960,160).data, frameData)
+  endpoint.transfer(Buffer.from(PUSH_FRAME_HEADER), function (error) {
+    if (!error) {
+      endpoint.transfer(Buffer.from(frameData), function (error) {
+        if (!error) {
+          callback()
+        } else {
+          callback(error)
+        }
+      })
+    } else {
+      callback(error)
+    }
+  })
+}
+
+module.exports = {
+  initPush: initPush,
+  sendFrame: sendFrame
+}

package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ableton-push-canvas-display",
+  "version": "1.0.0",
+  "description": "send contents of a canvas 2d context to the Ableton Push 2 display",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/halfbyte/ableton-push-canvas-display.git"
+  },
+  "engines": {
+    "nodejs": ">=8.0.0"
+  },
+  "keywords": [
+    "music",
+    "hardware",
+    "usb"
+  ],
+  "author": "Jan Krutisch <jan@krutisch.de>",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/halfbyte/ableton-push-canvas-display/issues"
+  },
+  "homepage": "https://github.com/halfbyte/ableton-push-canvas-display#readme",
+  "dependencies": {
+    "usb": "^1.3.1"
+  },
+  "devDependencies": {
+    "canvas": "^1.6.11"
+  }
+}