Configuration tool for Enhancia Neova ring controller
|
Chris Webb
4a6e3b56d9
Fix hub and ring firmware version detection
The config bytes corresponding to major and minor version numbers for hub and ring firmware were interpreted the wrong way round. Version 1.1 was reported correctly but version 1.2 was reported as 2.1. Switch the interpretation of these bytes. |
||
|---|---|---|
| COPYING | Import preliminary version of ringctl | |
| README | Allow free allocation of gestures to bank slots | |
| ringctl | Fix hub and ring firmware version detection | |
Configuration tool for Enhancia Neova ring controller ===================================================== ringctl is a command-line script to configure an Enhancia Neova MIDI ring controller, covering the same functions as the graphical Neova Dashboard application. Connected by USB to a Linux, BSD or macOS host, the Neova hub will register as both a standard ACM serial port and a class-compliant MIDI port. Ring gestures are converted to pitch bend and controller messages which are received by the host or instrument on the USB MIDI port. Meanwhile, the USB serial port streams direct sensor and battery information, and it is also used for configuration and firmware upgrades. Installation and testing ------------------------ The script requires Python 3.8 or later. Run in situ with 'python3 ringctl' or 'python ringctl'. To install, ensure the #! interpreter at the top of the script is right for your system, then copy it into a directory on your path. On Linux, the serial device looks like /dev/ttyACM0, whereas on BSD it is of the form /dev/cuaU0. Shell tab completion is useful on macOS, which opts for long, ugly names like /dev/cu.usbmodem0000000000001. Test ringctl by running it with just the device as a single argument. It should detect the hub and report the configuration to stdout. For example: $ ringctl /dev/ttyACM0 hub 1.1 ring 1.1 bank 1 1 channel 1 1 1 1 vibrato 50.0 40.2 1 2 1 bend -40.2 -20.0 20.0 40.2 1 3 1 tilt 1 0 127 0.0 62.1 1 4 1 roll 2 0 127 0.0 62.1 2 channel 1 2 1 1 vibrato 50.0 40.2 2 2 1 bend -40.2 -20.0 20.0 40.2 2 3 1 tilt 1 0 127 0.0 62.1 2 4 1 roll 2 0 127 0.0 62.1 3 channel 1 3 1 1 vibrato 50.0 40.2 3 2 1 bend -40.2 -20.0 20.0 40.2 3 3 1 tilt 1 0 127 0.0 62.1 3 4 1 roll 2 0 127 0.0 62.1 4 channel 1 4 1 1 vibrato 50.0 40.2 4 2 1 bend -40.2 -20.0 20.0 40.2 4 3 1 tilt 1 0 127 0.0 62.1 4 4 1 roll 2 0 127 0.0 62.1 Common errors include 'Permission denied' if you lack read-write access to the device, and 'Not a tty' or hanging if you use the wrong device. When the Neova Dashboard is installed on macOS, a background daemon runs continuously even when the application is not running. This steals output from the hub and will prevent ringctl from working. The daemon also eats battery by spinning in a short-timeout poll() loop, whether or not a hub is connected. Hopefully the manufacturer will eliminate it in a future release. Please report other problems or bugs to Chris Webb <chris@arachsys.com>. Showing current settings ------------------------ Neova has four gesture banks which can be selected using the A, B, C, D buttons while the shift button is held. Each of these has four slots which can be independently configured with any of the available gestures and toggled on/off with the A, B, C, D buttons. To show the hub/ring versions and the gestures configured in each BANK SLOT pair, use ringctl DEVICE or ringctl DEVICE show The output format for each bank and slot is the same as is expected by the configuration commands described below: BANK channel CHANNEL BANK SLOT ENABLE vibrato GAIN THRESHOLD BANK SLOT ENABLE bend LMIN LMAX RMIN RMAX BANK SLOT ENABLE tilt CONTROL LOW HIGH MIN MAX BANK SLOT ENABLE roll CONTROL LOW HIGH MIN MAX Slots with no gesture configured are omitted from the listing. Selecting a gesture bank ------------------------ To select a gesture bank from 1 to 4, use ringctl DEVICE bank BANK or change it using the hub buttons. The MIDI output will now correspond to the gestures in the enabled slots of this bank. Configuring the output MIDI channel ----------------------------------- To configure the output MIDI channel for a bank, use ringctl DEVICE BANK channel CHANNEL for CHANNEL between 1 and 16. Configuring vibrato ------------------- Vibrato is activated by shaking your hand left to right. The speed and intensity of the motion will be reflected in the frequency and depth of an output pitch bend oscillation. To configure this gesture in a slot, use ringctl DEVICE BANK SLOT ENABLE vibrato GAIN THRESHOLD ENABLE sets the initial state of the gesture: 0 if disabled or 1 if enabled. It can later be toggled on and off with the corresponding hub button, and when enabled, the slot LED will glow pink to indicate vibrato is active. GAIN and THRESHOLD are percentages from 0.0 to 100.0. Higher GAIN deepens the pitch oscillation for a given finger motion, and higher THRESHOLD increases the degree of motion required before the gesture activates. These parameters are reported by 'ringctl DEVICE show' in the same order and format as required by this command. Configuring pitch bend ---------------------- Pitch bend is activated by rolling your hand to the left to bend down or to the right to bend up. The pitch deflection increases with the angle of roll. To configure this gesture in a slot, use ringctl DEVICE BANK SLOT ENABLE bend LMIN LMAX RMIN RMAX ENABLE sets the initial state of the gesture: 0 if disabled or 1 if enabled. It can later be toggled on and off with the corresponding hub button, and when enabled, the slot LED will glow purple to indicate bend is active. LMIN, LMAX, RMIN and RMAX are angles from -100.0 degrees to +100.0 degrees, such that LMIN < LMAX < RMIN < RMAX, where a level hand position corresponds to 0.0 degrees. As leftward roll reaches LMAX, pitch starts to bend down, with full deflection at LMIN. Similarly, as rightward roll reaches RMIN, pitch starts to bend up, with full deflection at RMAX. Configuring tilt ---------------- Tilt is activated by tipping your hand to point upwards or downwards. The controller or pitch deflection varies with the angle of tilt. To configure this gesture in a slot, use ringctl DEVICE BANK SLOT ENABLE tilt CONTROL LOW HIGH MIN MAX ENABLE sets the initial state of the gesture: 0 if disabled or 1 if enabled. It can later be toggled on and off with the corresponding hub button, and when enabled, the slot LED will glow yellow to indicate tilt is active. CONTROL is the MIDI controller number (0-127) to generate, or -1 for pitch bend. Controller output is constrained to lie between LOW and HIGH (0-127). MIN, MAX are angles from -100.0 degrees to +100.0 degrees, where a level hand position corresponds to 0.0 degrees. As your hand tilts between MIN and MAX, controller output varies continuously between LOW and HIGH. Configuring roll ---------------- Roll is activated by rolling your hand to the left or right. The controller or pitch deflection varies with the angle of roll. To configure this gesture in a slot, use ringctl DEVICE BANK SLOT ENABLE roll CONTROL LOW HIGH MIN MAX ENABLE sets the initial state of the gesture: 0 if disabled or 1 if enabled. It can later be toggled on and off with the corresponding hub button, and when enabled, the slot LED will glow turquoise to indicate roll is active. CONTROL is the MIDI controller number (0-127) to generate, or -1 for pitch bend. Controller output is constrained to lie between LOW and HIGH (0-127). MIN, MAX are angles from -100.0 degrees to +100.0 degrees, where a level hand position corresponds to 0.0 degrees. As your hand rolls between MIN and MAX, controller output varies continuously between LOW and HIGH. Removing a gesture ------------------ To remove the gesture from a slot, leaving it empty, use ringctl DEVICE BANK SLOT remove It is not necessary to remove gestures to replace them: just overwrite them. Storing the configuration ------------------------- Configuration changes made using the above commands can be written to flash in the hub using ringctl DEVICE store so that they will not be lost when it is powered down. Implementation notes -------------------- Serial port access is inevitably ugly, but the code should be reasonably portable between Linux and BSD-like systems. Terminal attributes are saved before modification so they can be restored on exit. Parameter values between -100.0 and 100.0 are encoded in the serial protocol as 32-bit little-endian integers. The high bit represents the sign, and the lower bits are proportional to x ** k where k is chosen such that x = 50.0 corresponds to 0x42480000, and x = 100.0 corresponds to 0x42c80000. See the definitions of encode() and decode() in the ringctl script for details. Unfortunately, protocol messages are neither framed nor encode their own length, so we can only assume the expected number of bytes follow a given message header. This will be fragile as the protocol evolves. Copying ------- This software was written by Chris Webb <chris@arachsys.com> and is distributed as Free Software under the terms of the MIT license in COPYING.