Skip to content

Latest commit

 

History

History
529 lines (365 loc) · 14.8 KB

README.md

File metadata and controls

529 lines (365 loc) · 14.8 KB

Open Contour Shuttle

A multiplatform userland driver, configuration editor, event manager & generator for Contour ShuttleXpress & ShuttlePRO v2.

GUI prototype

Status

Proof of concept!

Welcoming any contributions, especially:

  • comments
  • tests: particularly on platforms other than Microsoft Windows or versions earlier than 11
  • implement currently unsupported hardware:
    • ShuttlePRO v2

Features / TODO list

  • Device support

    • ShuttleXpress
    • (WIP) ShuttlePRO v2
  • Platform support

    • Microsoft Windows
      • GUI
      • Tray icon shortcut to GUI
      • Run as a windows service?
      • Add configurator to control panel?
    • Apple Mac OS X
    • GNU/Linux
    • Android?
    • Apple iOS/iPadOS?
  • State management engine

    • Find and open device
      • USB HID via hidapi
    • Decode raw values
      • Observer pattern Events
    • (WIP) Central broker
    • Responders plugin system
  • (WIP) GUI

    • Qt6 via PySide6
    • Main window
    • Icon
    • Title
    • System tray icon
    • Display state graphically
    • Status
      • Connection
      • Events
    • Menu?
    • About window
    • Log window
      • Aggregate & display logs
      • Clear logs
      • Write logs to file
    • Configuration UI
      • Generate configurations
      • Load existing configurations
      • Write/Store configurations
    • Emulation mode when no hardware is connected
    • Separate from the engine
    • Custom graphical widgets?
      • Wheel (Rotating image with color tick)
      • Dial (Rotating image)
      • Button (Depict depressed state)

Events

State changes.

  • USB:
    • connected
    • disconnected
  • Buttons 1 to 5:
    • press
    • release
  • Wheel:
    • centered (position 0)
    • position change (-7 to 7)
    • direction: up
    • direction: down
  • Dial:
    • direction: up
    • direction: down
    • absolute position (0 to 255)

Observers

Gets notified upon events

  • GUI
  • (WIP) Responder plugins Broker

Broker

Maps events observation to responses depending on the current configuration and available responder plugins.

  • Configuration system

  • Responder plugins

    • API specification
    • Sample implementation
  • runtime profiles support

    • configure multiple profiles
      • default global
      • named
        • (optional) linked to one or more specific external states:
          • application in focus
          • current desktop/monitor?
          • session/user?
          • external trigger event?
    • (auto?) switch profiles dynamically
      • using buttons
      • detect running application
        • Microsoft Windows
          • win32ui
        • Mac OS X
        • GNU/Linux

Responders

Plugin based system.

Generates external events triggered by the broker.

  • (POC) generate keyboard strokes and/or modifiers

    • SendKeys?
    • pywin32 shell.SendKeys?
    • (POC) pynput! (Also support mouse)
    • Frequency (Once/Hold…)
  • (POC) generate mouse events

    • (POC) pynput! (Also support mouse)
    • click
    • wheel
  • generate MIDI

    • Arbitrary (User defined)
    • MCU compatible
    • HUI compatible
  • generate OSC

  • call APIs?

  • launch applications

    • ?

Contour format settings

May be used as samples for interoperability.

Contour

GitHub

Similar and/or related projects

A simple barebones driver written in Python for the Contour ShuttlePRO V1 Control Surface.

  • Language: Python
  • License: Unspecified/Proprietary (Copyright 2016 c0deous?)
  • OS: GNU/Linux
  • Dependencies: python-evdev

A cncjs pendant to connect a Contour Design ShuttleXpress to the raspberry pi that is running cncjs.

  • Language: Javascript/NodeJS
  • License: MIT (Copyright (c) 2021 Ben Suffolk)
  • OS: GNU/Linux
  • Dependencies: udev, cnjs, shuttle-control-usb

Neumann KH 750 DSP remote control with Contour ShuttleXpress.

  • Language: Javascript/NodeJS
  • License: MIT (Copyright (c) 2021 floxch)
  • OS: Multiplatform?
  • Dependencies: multicast-dns, node-hid, node-notifier, node-osc

Lightroom plugin for support contourdesign ShuttlePro v2.

  • Language: C++/Lua
  • License: GPL-3.0 (Copyright 2018 abrilevskiy?) + Proprietary (Copyright (c) 2003 Contour Design, Inc. & Copyright 2016 Adobe Systems Incorporated)
  • OS: Microsoft Windows
  • Dependencies: ShuttleSDK.dll

Node-RED nodes for USB ShuttleXpress device.

  • Language: Javascript/NodeJS
  • License: MIT (Copyright (c) 2019 legacymachine aka Legacy Machine Works, LLC aka Josh Dudley)
  • OS: Multiplatform
  • Dependencies: node-hid

NodeJS API for USB ShuttleXpress Device.

  • Language: Javascript/NodeJS
  • License: MIT (Copyright (c) 2019 legacymachine aka Legacy Machine Works, LLC aka Josh Dudley)
  • OS: Multiplatform
  • Dependencies: node-hid

A little Swift program to make a ShuttleXpress do what I want.

  • Language: Swift
  • License: BSD-2-Clause (Copyright (c) 2016, Benno Rice)
  • OS: Apple Mac OS X
  • Dependencies: Mac OS X 10.12 SDK

Controlling Ardour with Open Sound Control from Contour Design ShuttlePRO & ShuttlePRO v2.

  • Language: C
  • License: GPL-2.0 (Copyright (C) 2001-2007 Dan Dennedy)
  • OS: GNU/Linux
  • Dependencies: liblo

Contour Design Shuttle Pro V2 drivers for Linux, in Go, with modifiers and just more slick.

  • Language: Go
  • License: MIT (Copyright (c) 2017 Alexandre Bourget)
  • OS: GNU/Linux
  • Dependencies: udev

A Library to use Contour Design ShuttleXpress and ShuttlePro v2 in Node.js projects without the driver.

  • Language: Javascript/NodeJS
  • License: MIT (Copyright (c) 2020 James Hope)
  • OS: Multiplatform?
  • Dependencies: node-hid, usb-detection, udev

ShuttlePro fork.

Daemon for Contour Shuttle devices to translate button/jogwheel events to keystrokes sent to uinput.

  • Language: C
  • License: GPL-3.0 (Copyright 2013 Eric Messick, Copyleft 2015 Joshua Besneatte)
  • OS: GNU/Linux
  • Dependencies: libx11, libxtst, udev, uinput

ShuttlePRO fork.

User program for interpreting key, shuttle, and jog events from a Contour Design ShuttlePRO v2

  • Language: C
  • License: GPL-3.0 (Copyright 2013 Eric Messick, Copyright 2018 Albert Graef, Copyright 2019 Pascal de Bruijn)
  • OS: GNU/Linux
  • Dependencies: libx11, libxtst, udev

Contour's ShuttleExpress for jogging a GRBL CNC machine under cncjs and Linux using USB/hidraw.

  • Language: Javascript/NodeJS
  • License: MIT (Copyright (c) 2020 Duffmann aka Nelio Santos)
  • OS: GNU/Linux
  • Dependencies: commander, inquirer, jsonwebtoken, lodash.get, node-hid, serialport, socket.io-client, udev, vorpal

Event handler for Contour Design ShuttleXpress.

  • Language: Perl
  • License: Apache-2.0 (Copyright 2015 Tobias Johnson)
  • OS: GNU/Linux
  • Dependencies: udev

Sends MIDI from the Shuttle Contour to SDR Console.

  • Language: Go
  • License: Apache-2.0 (Copyright 2021 dg1psi)
  • OS: Multiplatform?
  • Dependencies: hidapi, loopmidi

A simple .NET wrapper for the Contour Shuttle SDK. Written in C#.

  • Language: C#
  • License: Unspecified/Proprietary (Copyright © Edward MacDonald 2018)
  • OS: Microsoft Windows?
  • Dependencies: ShuttleSDK.dll

A python app to allow usage of the Contour ShuttlePro V2 in Linux.

  • Language: Python
  • License: Unspecified/Proprietary (Copyright 2020 Brendan McGloin?)
  • OS: GNU/Linux
  • Dependencies: click, evdev, Xlib

User program for interpreting key, shuttle, and jog events from a Contour Design ShuttlePRO v2.

  • Language: C
  • License: GPL-3.0 (Copyright 2013 Eric Messick)
  • OS: GNU/Linux
  • Dependencies: libx11, libxtst, udev

ShuttlePRO fork.

User program for interpreting key, shuttle, and jog events from a Contour Design ShuttlePRO v2

  • Language: C
  • License: GPL-3.0 (Copyright 2013 Eric Messick, Copyright 2018 Albert Graef, Copyright 2020 Ben Blain)
  • OS: GNU/Linux
  • Dependencies: libjack, libx11, libxtst, udev

ShuttlePro fork.

User program for interpreting key, shuttle, and jog events from a Contour Design ShuttlePRO v2.

  • Language: C
  • License: GPL-3.0 (Copyright 2013 Eric Messick, Copyright 2020 Harry G McGavran Jr)
  • OS: GNU/Linux
  • Dependencies: udev

A Linux userspace "driver" for the ShuttlePro V2 device, and some tools to read events from a wacom tablet.

  • Language: D
  • License: LGPL-3.0 (Copyright 2013 Robert Thomson)
  • OS: GNU/Linux
  • Dependencies: None

Lightroom plugin to use ShuttleXpress controller for Develop.

  • Language: C#
  • License: Unspecified/Proprietary (Copyright 2020 Ngoc Van Tran?)
  • OS: Microsoft Windows, Ubuntu?
  • Dependencies: .NET Core 3.1.100, ShuttleSDK64.dll

Android Library for interfacing with a Contour Design Shuttle Xpress 🕹️.

  • Language: Java
  • License: Apache-2.0 (Copyright 2017 Oliver Bell)
  • OS: Android
  • Dependencies: API 17

Use a Contour ShuttleXpress in Linux.

  • Language: Scheme
  • License: Unspecified/Proprietary (Copyright 2012 Paul Battley?)
  • OS: GNU/Linux
  • Dependencies: Xlib, udev

Shuttlexpress-MPD is a Music Player Daemon (MPD) client that uses a Contour ShuttleXpress to control the status of the playback of an MPD instance.

  • Language: C
  • License: GPL-2.0 (Copyright 2019 Matthew J. Wolf)
  • OS: GNU/Linux
  • Dependencies: mpd, udev, systemd

The ShuttleXpress widget helps you setup your own ShuttleXpress jog dial USB device and enables audio feedback as you toggle the buttons on the device.

  • Language: Javascript/HTML/CSS
  • License: Unspecified/Proprietary (Copyright 2016 John Lauer?)
  • OS: ChiliPeppr
  • Dependencies: ChiliPeppr

Development log

Finding the right library for Microsoft Windows

Attempt 1

Using pyUSB

Can’t access device without a kernel driver.

Kernel driver has been generated using libusb-win32, but you need to disable driver signature enforcement before installing.

The easier way is to use Zadig.

Attempt 2

Using pyWinUSB

Can get HID without driver installation on Microsoft Windows!

Let’s continue…

Success!

But...

Attempt 3

Using cython-hidapi

Crossplatform (Microsoft Windows, Mac OS X, GNU/Linux)

Success on Microsoft Windows without prior driver installation! Hope it’s the same on other platforms.

Building a GUI

PySide6 (QT6)

Prototype UI done

Exploring patterns

Settled for an observer pattern with a central broker and separate plugin based responders.

Legal notice

License

Copyright 2021 Raphaël Doursenaud

This software is released under the terms of the GNU General Public License, version 3.0 or later (GPL-3.0-or-later).

See LICENSE.

Dependencies & License Acknowledgment

  • Python v3.10
    Used under the terms of the PSF License Agreement.
  • libusb hidapi
    Copyright Alan Ott, Signal 11 Software.
    Used under the terms of the GNU General Public License, version 3.0 (GPL-3.0).
  • via Trezor cython-hidapi
    Copyright Pavol Rusnak, SatoshiLabs.
    Used under the terms of the GNU General Public License, version 3.0 (GPL-3.0).
  • Qt PySide6
    Used under the terms of the GNU Lesser General Public License v3.0 (LGPL-3.0).
  • UN-GCPDS Qt-Material
    Used under the BSD-2-Clause License.
  • Material Design Icons
    Used under the Pictogrammers Free License.

Trademarks

Contour, ShuttleXpress and ShuttlePro are trademarks of Contour Innovations LLC in the United States of America.

These are not registered or active trademarks in the European Union and France where I reside.

Other

Other trademarks are property of their respective owners and used fairly for descriptive and nominative purposes only.