Revision History
| Document Version | Firmware Version | Date | Changes |
|---|---|---|---|
1.0 |
1.0.47 |
Feb. 26, 2016 |
Initial Version |
1.1 |
1.0.60 |
Jan. 24, 2017 |
Pad Settings, Pedal Configuration, Dual MIDI mode |
© Copyright 2016-2017 Ableton AG. All rights reserved. Made in Germany.
The content of this manual is subject to German Law. A license to use this manual is hereby granted. No other license, express or implied, is granted or intended hereby. Any further use of this document, including but not limited to the reproduction and distribution, requires the prior written consent by Ableton. The content of this manual serves the purpose of providing non-binding information only and shall not be construed as a commitment of any kind by Ableton and can be subject to change at any time without notice. Despite making every effort to ensure that the information contained in this manual is accurate, Ableton shall not be liable for potential errors or inaccuracies, except for intent or gross negligence.
Ableton intentionally omits certain parts of the described interface. These omissions are indicated separately within the document. Ableton shall not be liable under any theory of liability for any direct, indirect, incidental, special, consequential or exemplary damages that may be incurred by the user overriding the intentional omissions and their related warnings.
"Ableton" and "Push" as well as their respective logos are registered trademarks of Ableton AG. All other product and company names are trademarks or registered trademarks of their respective owners.
- 1. Introduction
- 2. MIDI Interface
- 3. Display Interface
- 4. Appendix A: MIDI Implementation Chart
The second release of the Push device (called "Push 2" in this document) was introduced by Ableton in November 2015. This MIDI and Display Interface Manual describes how Push 2 communicates with the host computer via the USB link.
The most common way to use Push 2 is with Ableton Live. When Live sees the device, it automatically starts the "Push 2 script", which provides all the well-known functions of Push 2. Some users don’t want to limit their use of Push 2 to these standard functions, though. They want to develop their own extensions or applications. These communicate with the Push 2 device either from within Live (for example, from Max for Live) or from external applications, which either run in parallel to Live or standalone.
This document is intended to give the necessary information into the hands of technically skilled people who want to build such customized applications. The described interfaces allow to control the Push 2 LEDs and the display as well as to receive events from the controls like buttons, pads, encoders etc. Also, commands suitable to modify the default settings of the device are documented, for example to set color table entries, pad curves etc.
Some parts of the interface are not intended for public use and are therefore not documented. This mainly concerns things that could damage the device, like hacked firmware updates, or that could destroy calibration data gathered by measurements in the factory and saved in the Push 2 flash memory. There are some diagnostic features which are not documented, because they might be changed by Ableton whenever needed, are not tested as thoroughly as the documented functions and usually put an extra burden on the device that could compromise some of the regular functions. Please, don’t try to program the Push 2 MIDI interface yourself if you can’t make sure that undocumented or reserved commands and arguments are avoided.
Push 2 is accessed through two MIDI interfaces, each of which has an input and an output port. Only one application at a time can access a port. One port is called the Live port and is automatically used by Ableton Live to communicate with the Push 2 to implement the Push 2 Control Surface functions. The other port is called the User port and can be used either by other applications or by Live itself for remote control (by MIDI-assigning the controls of Push 2 to parameters in Live) or to send MIDI directly into the tracks. To use the User port in Live, configure the MIDI preferences so that the necessary Track/Remote switches of port 2 are On:
To access the User port from an external application running in parallel to Live, turn all Track/Sync/Remote switches in the MIDI preferences for port 2 Off. Live will then release the User port, allowing your application to open it.
The names of the MIDI ports depend on the operating system and may vary. The following table shows some typical names:
| OS | Port | Input | Output |
|---|---|---|---|
Windows 7 |
Live |
Ableton Push 2 nn |
Ableton Push 2 nn |
User |
MIDIIN2 (Ableton Push 2) nn |
MIDIOUT2 (Ableton Push 2) nn |
|
MacOSX |
Live |
Ableton Push 2 Live Port |
Ableton Push 2 Live Port |
User |
Ableton Push 2 User Port |
Ableton Push 2 User Port |
|
Linux |
Live |
Ableton Push 2 nn:0 |
Ableton Push 2 nn:0 |
User |
Ableton Push 2 nn:1 |
Ableton Push 2 nn:1 |
nn is an arbitrary number or blank
The MIDI mode selects over which port MIDI is sent or received. See MIDI Mode.
Standard MIDI messages are used for the basic Push 2 functions. Details are given in the linked chapters.
| Message | Status Byte | Data Bytes | Function/Event | Chapter |
|---|---|---|---|---|
Note on |
|
|
set LED color |
|
pad pressed |
||||
encoder touched/released |
||||
touch strip touched/released |
||||
Note off |
|
|
pad released |
|
Control change |
|
|
set LED color |
|
button pressed/released |
||||
encoder turned |
||||
pedal position |
||||
touch strip position |
||||
Pitch bend |
|
|
touch strip position |
|
Channel Pressure |
|
|
global pad aftertouch |
|
Poly Key Pressure |
|
|
individual pad aftertouch |
The figure below shows the note and controller numbers sent by control elements of Push 2 when pressed or turned. The same numbers are sent by Live to set the respective LEDs.
The sysex system exclusive ("sysex") commands are vendor-specific MIDI messages used to configure Push 2 and retrieve device states.
All sysex messages to and from Push 2 - except for device inquiry - have the format given in the table below.
Sysex messages sent to Push 2 are called commands, messages sent back to the host are called replies. Push 2 sends replies only as reaction to commands, no spontaneous sysex messages are sent. The reply id is always equal to the corresponding command id, although the argument list usually differs.
Commands should not be nested. Before sending the next command the host should wait for the reply, if any is expected, of the previous command. Otherwise, pending replies might be dropped.
| Message Data | Description |
|---|---|
|
SOX (start of sysex) |
|
Ableton sysex ID assigned by the MIDI Manufacturers Association |
|
Device ID. Probably not needed for USB devices, but this is what most manufacturers do. |
|
Model ID |
ID |
Command or reply ID (7 bits unsigned integer) |
Arguments |
A number of 7 bit values depending on command or reply ID |
|
EOX (end of sysex) |
Example: |
|
This is the list of sysex commands. The details are given in the respective chapters.
All unused command IDs are reserved. Some commands are undocumented, as they may destroy calibration data which was gathered by measurements in the factory and saved in the Push 2 flash memory. Some diagnostic features are not specified, because they might be changed by Ableton whenever needed, are not tested as thoroughly as the documented functions, and usually put an extra burden on the device that could compromise some of the regular functions. Please, don’t try to program the Push 2 MIDI/Display interface yourself if you can’t make sure that reserved commands and arguments are avoided.
| Command ID | Sends Reply | Command Name | Chapter |
|---|---|---|---|
|
Set LED Color Palette Entry |
||
|
yes |
Get LED Color Palette Entry |
|
|
Reapply Color Palette |
||
|
Set LED Brightness |
||
|
yes |
Get LED Brightness |
|
|
Set Display Brightness |
||
|
Get Display Brightness |
||
|
yes |
Set MIDI Mode |
|
|
Set LED PWM Frequency Correction |
||
|
yes |
Sample Pedal Data |
|
|
Set LED White Balance |
||
|
yes |
Get LED White Balance |
|
|
Set Touch Strip Configuration |
||
|
yes |
Get Touch Strip Configuration |
|
|
Set Touch Strip LEDs |
||
|
yes |
Request Statistics |
|
|
Set Pad Parameters |
||
|
yes |
Read 400g Pad Values From Flash |
|
|
Set Aftertouch Mode |
||
|
yes |
Get Aftertouch Mode |
|
|
Set Pad Velocity Curve Entry |
||
|
yes |
Get Pad Velocity Curve Entry |
|
|
Set Temporary 400g Pad Values |
||
|
yes |
Flash LED White Balance |
|
|
Select Pad Settings |
||
|
yes |
Get Selected Pad Settings |
|
|
Configure Pedal |
||
|
Set Pedal Curve Limits |
||
|
Set Pedal Curve Entries |
Push 2 works in three MIDI modes that define the behavior of the two MIDI I/O ports.
-
Incoming non-sysex MIDI from Port1 is accepted.
-
Incoming non-Sysex MIDI from Port2 is ignored.
-
All outgoing non-sysex MIDI is sent to Port 1.
-
Incoming non-sysex MIDI from Port1 is ignored.
-
Incoming non-Sysex MIDI from Port2 is accepted.
-
All outgoing non-sysex MIDI is sent to Port 2.
-
Incoming non-sysex MIDI from both ports is accepted.
-
All outgoing non-sysex MIDI is sent to both ports.
-
The "User" button always sends its MIDI note on/off to both Port 1 and 2.
-
The MIDI message setting the state of the "User" button LED is always accepted from both ports.
-
Incoming Sysex is accepted from both ports, replies are sent to the port from which the request was received.
-
The reply to the "Set MIDI Mode" sysex command always goes to both Port 1 and 2.
Initially, Push 2 is in Live mode. The mode is changed by the host using the "Set MIDI Mode" sysex command. See the Sysex Commands chapter for a description of the general Push 2 sysex command format.
Set MIDI Mode |
ID |
|
|||
Command Arguments |
m |
mode (0=Live, 1=User, 2=Dual) |
|||
Reply Arguments |
m |
mode (0=Live, 1=User, 2=Dual) |
|||
Example: |
|||||
This command is typically sent out by Live or other host applications to toggle between Live and User mode after receiving the note-on MIDI message issued when pressing the "User" button. The reply is always sent to both MIDI ports, even if Push 2 was already in the requested mode.
The dual mode is used for debugging or special application scenarios.
There are three types of LEDs used in Push 2: white LEDs, RGB-color LEDs and the LEDs of the touch strip (which are white too, but are managed differently).
The lighting of white and RGB LEDs is controlled by note-on or control change messages sent to Push 2:
Note On (nn): 1001cccc 0nnnnnnn 0vvvvvvv [10010000 = 0x90 = 144] Control Change (cc): 1011cccc 0nnnnnnn 0vvvvvvv [10110000 = 0xB0 = 176]
-
The channel (
cccc, 0…15) controls the LED animation, i.e. blinking, pulsing or one-shot transitions. Channel 0 means no animation. See LED Animation. -
The message type
1001(for nn) or1011(for cc) and the note or controller numbernnnnnnn(0…127) select which LED is addressed. See MIDI Mapping. -
The velocity
vvvvvvv(0…127) selects a color index, which is interpreted differently for white and RGB LEDs. See Default Color Palettes (subset).
| Binary | Hexadecimal | Decimal | Result |
|---|---|---|---|
|
|
|
set the top right pad RGB LED to red |
|
|
|
set the bottom left pad RGB LED to green |
|
|
|
turn the mute button RGB LED off |
|
|
|
set the master button white LED to max |
|
|
|
turn the tempo button white LED off |
|
|
|
let the undo button white LED blink slowly |
|
|
|
fast transition of mute button LED to blue |
Touch strip LEDs are either controlled by Push 2 itself or by Live, depending on the touch strip mode. Live controls the touch strip LEDs using the "Set Touch Strip LEDs" sysex message containing the color indices for all 31 LEDs. Touch strip LEDs are not animated.
The touch strip mode and sysex commands controlling the touchstrip are described in a separate Touch Strip chapter.
For all LEDs, the color index is passed through a color palette, then white balance and global brightness factors are applied. The palette, white balance and brightness can be set via sysex commands.
The PWM values used to drive the RGB LEDs are calculated as follows:
-
the color index for the addressed LED, as received by MIDI, is saved for later reapplication of color palette and brightness
-
the color index (0…127) is translated into 8 bit red/green/blue values using the color palette
-
the white balance factor (0…1024) for the respective color and group of LEDs as well as the global brightness are applied:
if (Brightness == 0) then PWM(rgb) = 0 else PWM(rgb) = Value(rgb) * (WB [R/G/B 1/2/3] / 1024) * (Brightness + 1) / 128
The RGB palette can be modified or retrieved, together with the white palette, using the sysex commands "Set/Get LED Color Palette Entry". After modifiying palette entries, the host should send the "Reapply Color Palette" sysex command to apply the new palette without resending the MIDI notes/control change messages containing the LED color indices.
Set LED Color Palette Entry |
ID |
|
|||
Command Arguments |
i |
color index (0..127) |
|||
r (LSB) |
lower 7 bits |
red color |
|||
r (MSB) |
higher 1 bit |
||||
g (LSB) |
lower 7 bits |
green color |
|||
g (MSB) |
higher 1 bit |
||||
b (LSB) |
lower 7 bits |
blue color |
|||
b (MSB) |
higher 1 bit |
||||
w (LSB) |
lower 7 bits |
white color |
|||
w (MSB) |
higher 1 bit |
||||
Example: |
|||||
Get LED Color Palette Entry |
ID |
|
|||
Command Arguments |
i |
color index (0..127) |
|||
Reply Arguments |
i |
color index (0..127) |
|||
r (LSB) |
lower 7 bits |
red color |
|||
r (MSB) |
higher 1 bit |
||||
g (LSB) |
lower 7 bits |
green color |
|||
g (MSB) |
higher 1 bit |
||||
b (LSB) |
lower 7 bits |
blue color |
|||
b (MSB) |
higher 1 bit |
||||
w (LSB) |
lower 7 bits |
white color |
|||
w (MSB) |
higher 1 bit |
||||
Example: |
|||||
Reapply Color Palette |
ID |
|
|||
Command Arguments |
none |
||||
Example: |
|||||
The PWM value for white LEDs is calculated similiarly to the RGB LEDs, but using the white palette and a different white balance factor. The palette can be modified together with the RGB color palette using the "Set/Get Palette Entry" sysex command described in the previous chapter.
The PWM values for the touch strip LEDs are calculated very much like for the RGB LEDs, but using the touch strip palette and a touch strip white balance factor. Another difference is that the color index ranges from 0 to 7, allowing to pack all touch strip LEDs into a short sysex message. If the touch strip is controlled by Push 2 itself, the color index is always 7 (full white). The touch strip palette is given in the next chapter. Unlike the other palettes, it cannot be modified.
The default color palettes for RGB, white and touchstrip LEDs might change in the future. Here are some prominent values that will be retained, most likely.
| Palette | Color Index | Value | Color |
|---|---|---|---|
RGB |
0 |
0, 0, 0 |
black |
… |
… |
||
122 |
204,204,204 |
white |
|
123 |
64, 64, 64 |
light gray |
|
124 |
20, 20, 20 |
dark gray |
|
125 |
0, 0, 255 |
blue |
|
126 |
0, 255, 0 |
green |
|
127 |
255, 0, 0 |
red |
|
White |
0 |
0 |
black |
16 |
32 |
dark gray |
|
48 |
84 |
light gray |
|
127 |
128 |
white |
|
Touch Strip |
0 |
0 |
black |
1 |
2 |
||
2 |
4 |
||
3 |
8 |
||
4 |
16 |
||
5 |
32 |
||
6 |
64 |
||
7 |
127 |
white |
The white balance is necessary for an even white across all LEDs. The balancing compensates technological differences in color temperature and brightness between RGB and white LEDs when driven with equal currents. Also, buttons, pads and the touch strip have a different color of the translucent material, which influences the color of the light shining through it. The white balance helps to adapt the LED colors to the color of the display. And finally, the buttons above and below the display have relatively small light slots, but carry important color information, therefore they are made a little brighter.
As a result, the LEDs are split into 11 color groups, for each of them a white balance factor is applied.
| Color group | LED group | LED color |
|---|---|---|
0 |
RGB buttons |
red |
1 |
green |
|
2 |
blue |
|
3 |
RGB pads |
red |
4 |
green |
|
5 |
blue |
|
6 |
Display buttons |
red |
7 |
green |
|
8 |
blue |
|
9 |
White buttons |
white |
10 |
Touch strip |
white |
Each white balance factor ranges from 0 to 1024.
The default white balance settings can be overwritten or retrieved using the "Set/Get LED White Balance" sysex commands. Care must be taken that the white balance does not make the Push 2 exceed the USB power limit of 500mA with all LEDs fully on, otherwise the host computer might refuse to work with the device. The settings are temporary, and are reset to default on reboot.
Set LED White Balance |
ID |
|
|||
Command Arguments |
c |
color group (0…10) |
|||
b (LSB) |
lower 7 bits of white balance factor |
||||
b (MSB) |
higher 4 bits of white balance factor |
||||
Example: |
|||||
Get LED White Balance |
ID |
|
|||
Command Arguments |
c |
color group (0…10) |
|||
Reply Arguments |
c |
color group (0…10) |
|||
b (LSB) |
lower 7 bits of white balance factor |
||||
b (MSB) |
higher 4 bits of white balance factor |
||||
Example: |
|||||
To modify the default white balance (persistently saved into flash memory
and applied on reboot), use the "Flash LED White Balance" command. Please
don’t invoke this function too often to avoid flash wear-out. Instead, use
"Set LED White Balance" to find good values and then flash only once.
Pass [0x7F, 0x7F] as white balance factor to reset the flash memory,
effectively restoring the firmware default.
Flash LED White Balance |
ID |
|
|||
Command Arguments |
c |
color group (0…10) |
|||
b (LSB) |
lower 7 bits of white balance factor or |
||||
b (MSB) |
higher 4 bits of white balance factor or |
||||
Reply Arguments |
c |
color group (0…10) |
|||
r |
0 for success, |
||||
Example: |
|||||
The global LED brightness, which ranges from 0 to 127, is applied to all LEDs. It can be set or obtained using the "Set/Get LED Brightness" sysex.
Set LED Brightness |
ID |
|
|||
Command Arguments |
b |
brightness (0…127) |
|||
Example: |
|||||
Get LED Brightness |
ID |
|
|||
Command Arguments |
none |
||||
Reply Arguments |
b |
brightness (0..127) |
|||
Example: |
|||||
When the Push 2 is USB powered (no external power supply), the global brightness is automatically limited to 8, to avoid exceeding the USB current limit.
When setting an LED color, except for the touch strip, an animation can be requested. This changes the LED color over time without the need for continuous MIDI messages from the host.
Animations are triggered by using channels 1-15.
-
The starting color of an animation is sent with a note on or control change message on channel 0.
-
The second color, the transition type and duration of the animation are sent with a note on or control change message on channel 1…15.
-
Transitions are stopped by setting a color on channel 0.
-
Sending another color on channels 1-15 stops the current transition and triggers a new one.
|
Note
|
In this document, channels are numbered as they are sent in the MIDI message, i.e. from 0 to 15. |
The encoding of transition type and duration by the channel is given in the table below.
| Channel | Transition | Duration as note | Duration as number of clock messages |
|---|---|---|---|
0 |
stop transition |
- |
- |
1 |
1-shot |
24th |
4 |
2 |
1-shot |
16th |
6 |
3 |
1-shot |
8th |
12 |
4 |
1-shot |
quarter |
24 |
5 |
1-shot |
half |
48 |
6 |
pulsing |
24th |
4 |
7 |
pulsing |
16th |
6 |
8 |
pulsing |
8th |
12 |
9 |
pulsing |
quarter |
24 |
10 |
pulsing |
half |
48 |
11 |
blinking |
24th |
4 |
12 |
blinking |
16th |
6 |
13 |
blinking |
8th |
12 |
14 |
blinking |
quarter |
24 |
15 |
blinking |
half |
48 |
The one-shot transition stops after the given duration, the blinking and pulsing transitions keep running.
When a one-shot is finished, the target color is taken over as the channel 0 value, therefore, to start another one-shot as a transition from the previous target color to a new target color, it is sufficient to send the new target color.
To get a smooth transition when changing otherwise non-animated colors, instead of sending the new color on channel 0, the host can just send the new color at channel 1, causing a quick one-shot.
Animations are timed by MIDI system real time messages sent by the host.
The MIDI start (0xFA) and continue (0xFB) messages reset the global
animation phase. This phase is used for blinking and pulsing
animations, which are therefore all synchronized. The MIDI clock message
(0xF8) advances the animation phase by 1/24th beat (i.e. a 1/96th note).
One-shot animations all run with their individual phase, i.e. they start when the host sends the target color and stop after the number of clock messages given in the table above.
After a MIDI stop message (0xFC), the animations continue to run at the
last received tempo. If the host never sent a MIDI start message, the animations
run at a tempo of 120 bpm.
As usual with MIDI-over-USB interfaces, system real time messages should not be sent in the middle of other MIDI messages.
The PWM frequency can be adjusted to avoid interference with shutter frequencies of video cameras, which otherwise lead to visual flicker in the video recordings. This is done by a correction factor. The default correction corresponds to a 100Hz PWM base frequency, which works with most video cameras. The maximum possibly frequency is 116 Hz. The usable range, where the LEDs do not show any flickering for human observers even in critical light conditions and viewing angles, starts at approx. 60 Hz.
The "Set LED PWM Frequency Correction" sysex command adjusts the LED PWM frequency.
Set LED PWM Frequency Correction |
ID |
|
|||
Command Arguments |
n (LSB) |
lowest 7 bits |
correction factor |
||
n |
middle 7 bits |
||||
n (MSB) |
highest 7 bit |
||||
Example: |
|||||
The correction factor "n" to be passed to the sysex command is a non-negative integer in the range 0…2097151. The resulting PWM base frequency f0 in Hz is calculated as:
f0 = 5000000 / (42752 + n)
To calculate the correction factor from the frequency:
n = (5000000 / f0) – 42752
For 100 Hz, n=7248, for 60 Hz, n=40581.
The buttons send the following MIDI control change messages:
Button Pressed: 10110000 0nnnnnnn 01111111 [10110000 = 0xB0 = 176] Button Released: 10110000 0nnnnnnn 00000000
-
The control change number
nnnnnnn(0…127) corresponds to the pressed button. See MIDI Mapping.
| Binary | Hexadecimal | Decimal | Event |
|---|---|---|---|
|
|
|
metronome button pressed |
|
|
|
metronome button released |
The pads send the following MIDI note-on/off messages:
Pad Pressed: 10010000 0nnnnnnn 0vvvvvvv [10010000 = 0x90 = 144, note on] Pad Released: 10000000 0nnnnnnn 00000000 [10000000 = 0x80 = 128, note off]
-
The note number
nnnnnnn(0…127) corresponds to the pad. See MIDI Mapping. -
The velocity
vvvvvvv(1…127) reflects how hard the pad was hit or pressed. The velocity is influenced by the velocity curve, the pad parameters and individual pad calibration.
| Binary | Hexadecimal | Decimal | Event |
|---|---|---|---|
|
|
|
left bottom pad hit hard |
|
|
|
right bottom pad pressed softly |
|
|
|
right top pad released |
The pad signal processing algorithm produces notes with a certain velocity (1…127) derived from the measured weight (0..4095 g). For this purpose, the firmware does an interpolation using a conversion table with 128 entries. The entries contain the velocities that correspond to the weights 0 g, 32 g, 64 g, 96 g, …, 4064 g. For weights above that, the velocity for 4064g (index 127) is taken.
The "Set/Get Pad Velocity Curve Entry" sysex commands allow to read and modify this table. The velocity range is 1…127.
Set Pad Velocity Curve Entry |
ID |
|
|||
Command Arguments |
i |
start index (one of 0, 16, 32, 48, 64, 80, 96, 112) |
|||
v0 |
velocity for index i |
||||
v1 |
velocity for index i + 1 |
||||
v2 |
velocity for index i + 2 |
||||
… |
|||||
v15 |
velocity for index i + 15 |
||||
Example: |
|||||
Get Pad Velocity Curve Entry |
ID |
|
|||
Command Arguments |
i |
index (0…127) |
|||
Reply Arguments |
i |
index (0…127) |
|||
v |
velocity |
||||
Example: |
|||||
The "Set Pad Parameters" sysex commands allows to set some parameters that apply to all 64 pads.
Set Pad Parameters |
ID |
|
|||
Command Arguments |
t0 (LSB) |
lower 7 bits |
parameter 0 (unused) |
||
t0 (MSB) |
higher 5 bits |
||||
t1 (LSB) |
lower 7 bits |
parameter 1 (unused) |
|||
t1 (MSB) |
higher 5 bits |
||||
a0 (LSB) |
lower 7 bits |
lower aftertouch threshold, must be > 400 |
|||
a0 (MSB) |
higher 5 bits |
||||
a1 (LSB) |
lower 7 bits |
upper aftertouch threshold, must be greater then the lower threshold a0 |
|||
a1 (MSB) |
higher 5 bits |
||||
Example: |
|||||
All values are in range 0…4095. At the moment, only the aftertouch threshold is used. It is adjusted by the Push 2 script together with the velocity curve. The set of pad parameters used by the firmware is subject to change.
The "Select/Get Selected Pad Settings" sysex commands allows to select one of three available sets of pad parameter values called settings, or to read the currently selected settings. The purpose is to reduce the sensitivity of pads that should not be triggered "by accident", like a loop selector near drum pads. By passing 0, 0 as scene and track, the settings for all pads can be selected.
Select Pad Settings |
ID |
|
|||
Command Arguments |
ss |
scene 1 (top) … 8 (bottom), or 0 (all pads) |
|||
tt |
track 1 (left) … 8 (right), or 0 (all pads) |
||||
nn |
settings (0-regular, 1-reduced sensitivity, 2-low sensitivity) |
||||
Example: |
|||||
Get Selected Pad Settings |
ID |
|
|||
Command Arguments |
ss |
scene 1 (top) … 8 (bottom) |
|||
tt |
track 1 (left) … 8 (right) |
||||
Reply Arguments |
ss |
scene 1 (top) … 8 (bottom) |
|||
tt |
track 1 (left) … 8 (right) |
||||
nn |
settings (0…2) |
||||
Example: |
|||||
Individual pad calibration is done using 400g values measured in the factory and written into the flash memory of the device. The "Read 400g Pad Values From Flash" sysex command allows to read these values.
Read 400g Pad Values From Flash |
ID |
|
|||
Command Arguments |
s |
scene (1=top … 8=bottom) |
|||
Reply Arguments |
s |
scene (1=top … 8=bottom) |
|||
v0 (LSB) |
lower 7 bits |
400g value for track 1 (leftmost) |
|||
v0 (MSB) |
higher 5 bits |
||||
v1 (LSB) |
lower 7 bits |
400g value for track 2 |
|||
v1 (MSB) |
higher 5 bits |
||||
v2 (LSB) |
lower 7 bits |
400g value for track 3 |
|||
v2 (MSB) |
higher 5 bits |
||||
v3 (LSB) |
lower 7 bits |
400g value for track 4 |
|||
v3 (MSB) |
higher 5 bits |
||||
v4 (LSB) |
lower 7 bits |
400g value for track 5 |
|||
v4 (MSB) |
higher 5 bits |
||||
v5 (LSB) |
lower 7 bits |
400g value for track 6 |
|||
v5 (MSB) |
higher 5 bits |
||||
v6 (LSB) |
lower 7 bits |
400g value for track 7 |
|||
v6 (MSB) |
higher 5 bits |
||||
v7 (LSB) |
lower 7 bits |
400g value for track 8 (rightmost) |
|||
v7 (MSB) |
higher 5 bits |
||||
Example: |
|||||
The values measured in the factory are the values that are in effect by default. They might be overwritten using the "Set Temporary 400g Pad Values" sysex command.
Set Temporary 400g Pad Values |
ID |
|
|||
Command Arguments |
s |
scene (1=top … 8=bottom) |
|||
v0 (LSB) |
lower 7 bits |
400g value for track 1 (leftmost) |
|||
v0 (MSB) |
higher 5 bits |
||||
v1 (LSB) |
lower 7 bits |
400g value for track 2 |
|||
v1 (MSB) |
higher 5 bits |
||||
v2 (LSB) |
lower 7 bits |
400g value for track 3 |
|||
v2 (MSB) |
higher 5 bits |
||||
v3 (LSB) |
lower 7 bits |
400g value for track 4 |
|||
v3 (MSB) |
higher 5 bits |
||||
v4 (LSB) |
lower 7 bits |
400g value for track 5 |
|||
v4 (MSB) |
higher 5 bits |
||||
v5 (LSB) |
lower 7 bits |
400g value for track 6 |
|||
v5 (MSB) |
higher 5 bits |
||||
v6 (LSB) |
lower 7 bits |
400g value for track 7 |
|||
v6 (MSB) |
higher 5 bits |
||||
v7 (LSB) |
lower 7 bits |
400g value for track 8 (rightmost) |
|||
v7 (MSB) |
higher 5 bits |
||||
Example: |
|||||
The overwritten values are in effect until the device is rebooted. Pad values are in range from 0 to 4095. The 400g reference value is 1690. Higher 400g values are compensated in the firmware by lowering the resulting velocities somewhat, for lower 400g values the velocities are boosted. The 400g values have no effect on the note-on threshold (both in the pad physics and in the algorithm interpreting the read values).
While a pad is pressed, it may send MIDI aftertouch messages. Depending on the aftertouch mode, either channel pressure or polyphonic key pressure is sent.
Channel Pressure: 11010000 0vvvvvvv [11010000 = 0xD0 = 208] Polyphonic Key Pressure: 10100000 0nnnnnnn 0vvvvvvv [10100000 = 0xA0 = 160]
-
The note number
nnnnnnn(0…127) corresponds to the pad. See MIDI Mapping. -
The value
vvvvvvvreflects how hard the pad is pressed.
In channel pressure mode, the pad with the highest pressure determines the value sent. The pressure range that produces aftertouch is given by the aftertouch threshold pad parameters. The value curve is linear to the pressure and in range 0 to 127. See Pad Parameters.
In polyphonic key pressure mode, aftertouch for each pressed key is sent individually. The value is defined by the pad velocity curve and in range 1…127. See Velocity Curve.
| Binary | Hexadecimal | Decimal | Event |
|---|---|---|---|
|
|
|
maximum channel pressure |
|
|
|
no channel pressure (i.e. released) |
|
|
|
maximum key pressure on bottom left pad |
|
|
|
minimum key pressure on bottom left pad |
The aftertouch mode can be set or retrieved using the "Set/Get Aftertouch Mode" sysex commands. The default is channel pressure.
Set Aftertouch Mode |
ID |
|
|||
Command Arguments |
m |
aftertouch mode (0 = channel pressure, 1 = polyphonic key pressure) |
|||
Example: |
|||||
Get Aftertouch Mode |
ID |
|
|||
Command Arguments |
none |
||||
Reply Arguments |
m |
aftertouch mode (see above) |
|||
Example: |
|||||
The encoders, when turned, send the following MIDI control change messages:
Turn Right: 10110000 0nnnnnnn 00xxxxxx [10110000 = 0xB0 = 176] Turn Left: 10110000 0nnnnnnn 01yyyyyy
-
The controller number
nnnnnnn(0…127) corresponds to the encoder. See MIDI Mapping. -
The value
0xxxxxxor1yyyyyygives the amount of accumulated movement since the last message. The faster you move, the higher the value.
The value is given as a 7 bit relative value encoded
in two’s complement. 0xxxxxx indicates a movement to
the right, with decimal values from 1 to 63 (in practice, values
above 20 are unlikely). 1yyyyyy means movement to the left, with
decimal values from 127 to 64.
The total step count sent for a 360° turn is approx. 210, except for the detented tempo encoder, where one turn is 18 steps.
| Binary | Hexadecimal | Decimal | Event |
|---|---|---|---|
|
|
|
master encoder turned right by 1 step |
|
|
|
master encoder turned right by 10 steps |
|
|
|
tempo encoder turned left by 1 step |
|
|
|
tempo encoder turned left by 4 steps |
When touched or released, the encoders send note on messages with velocity 127 or 0.
Encoder Touched: 10010000 0nnnnnnn 01111111 [10010000 = 0x90 = 144] Encoder Released: 10010000 0nnnnnnn 00000000
-
The note number
nnnnnnn(0…127) corresponds to the encoder. See MIDI Mapping.
| Binary | Hexadecimal | Decimal | Event |
|---|---|---|---|
|
|
|
leftmost track encoder touched |
|
|
|
leftmost track encoder released |
The touch strip is a bit more complicated, because it can be configured to run in different modes. The behavior will be explained as the different configuration flags are discussed.
Independently of the configuration, the touch strip sends note on messages with velocity 127 or 0 when the finger touches the strip or is lifted off.
Touch Strip Touched: 10010000 00001100 01111111 [10010000 = 0x90 = 144] Touch Strip Released: 10010000 00001100 00000000
-
The note number
00001100(decimal 12) refers to the touch strip. See MIDI Mapping.
| Binary | Hexadecimal | Decimal | Event |
|---|---|---|---|
|
|
|
touch strip touched |
|
|
|
touch strip released |
The sysex commands "Set/Get Touch Strip Configuration" define the touch strip behavior by a number of flags in a 7 bit configuration setting.
Set Touch Strip Configuration |
ID |
|
|||
Command Arguments |
t |
configuration flags |
|||
Example: |
|||||
Get Touch Strip Configuration |
ID |
|
|||
Command Arguments |
none |
||||
Reply Arguments |
t |
configuration flags |
|||
Example: |
|||||
Configuration Flags
---------------
bit |6|5|4|3|2|1|0|
--------------- | 0 | 1
| | | | | | | --------------------+-------------+----------
| | | | | | --- LEDs Controlled By | Push 2* | Host
| | | | | ----- Host Sends | Values* | Sysex
| | | | ------- Values Sent As | Pitch Bend* | Mod Wheel
| | | --------- LEDs Show | a Bar | a Point*
| | ----------- Bar Starts At | Bottom* | Center
| ------------- Do Autoreturn | No | Yes*
--------------- Autoreturn To | Bottom | Center*
*) The default settings are marked in bold.
| Binary | Hexadecimal | Decimal | Configuration | Typical Application |
|---|---|---|---|---|
|
|
|
Default: Push 2 controls LEDs as single point with autoreturn to center, sends pitch bend |
Pitch bend control |
|
|
|
Push 2 controls LEDs as bar starting at bottom, no autoreturn, sends modulation |
Volume control |
|
|
|
Host controls LEDs using Sysex, Push 2 sends pitch bend |
Drum rack MIDI range selection |
Below a description of each of the configuration flags is given.
-
If LEDs are controlled by Push 2 (flag = 0), the touch strip hardware sends the value both to the LEDs hardware as well as to the host, simultaneously. Values received from the host are ignored.
-
If LEDs are controlled by the host (flag = 1), the touch strip hardware sends the value to the host only. The host then might or might not send an update to the LEDs. The host might even ignore the values sent by the touch strip hardware and control the LEDs arbitrarily.
This flag is only relevant if the LEDs are controlled by the host.
-
If the flag is 0 ("send values"), the host may send pitch bend or mod wheel (depending on the "Values Sent As" flag) to control the LEDs. The sysex command "Set Touch Strip LEDs" is ignored.
-
If the flag is 1 ("send sysex"), the host may send the "Set Touch Strip LEDs" sysex command to set the LEDs. Pitch bend or mod wheel are ignored in this case. LED 0 is the bottom LED, LED30 is the top LED. The LEDn values are color indices from 0 to 7. See Default Color Palettes (subset).
Set Touch Strip LEDs |
ID |
0x19 |
|||||||
Command Arguments |
Argument |
Bits |
|||||||
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
||
b0 |
0 |
0 |
LED1 |
LED 0 |
|||||
b1 |
0 |
0 |
LED3 |
LED 2 |
|||||
b2 |
0 |
0 |
LED5 |
LED 4 |
|||||
b3 |
0 |
0 |
LED7 |
LED 6 |
|||||
b4 |
0 |
0 |
LED9 |
LED 8 |
|||||
b5 |
0 |
0 |
LED11 |
LED 10 |
|||||
b6 |
0 |
0 |
LED13 |
LED 12 |
|||||
b7 |
0 |
0 |
LED15 |
LED 14 |
|||||
b8 |
0 |
0 |
LED17 |
LED 16 |
|||||
b9 |
0 |
0 |
LED19 |
LED 18 |
|||||
b10 |
0 |
0 |
LED21 |
LED 20 |
|||||
b11 |
0 |
0 |
LED23 |
LED 22 |
|||||
b12 |
0 |
0 |
LED25 |
LED 24 |
|||||
b13 |
0 |
0 |
LED27 |
LED 26 |
|||||
b14 |
0 |
0 |
LED29 |
LED 28 |
|||||
b15 |
0 |
0 |
0 |
0 |
0 |
LED 30 |
|||
Example: |
|||||||||
This flag selects if pitch bend or mod wheel messages are sent. This selects which messages the touch strip hardware sends to the host, as well as which messages from the host are accepted to change the LEDs (the latter only if LEDs are controlled by the host and the host sends values).
Pitch Bend: 11100000 0q000000 0ppppppp [11100000 = 0xE0 = 224] Mod Wheel: 10110000 00000001 0vvvvvvv [10110000 = 0xB0 = 176]
-
The pitch bend message contains a 14 bit pitch value
pppppppq000000(0 … 16320, neutral pitch level is 8192 =10000000000000). Please note that the least significant 7 bits are sent first. Only 8 bits are used by Push 2, the 6 less significant bits are always zero. -
The mod wheel message is a control change for controller number 1. It contains a 7 bit modulation value
vvvvvvv(0 … 127, the center value is 64).
For both types of messages the zero value corresponds to the bottom of Push 2 (near the "Play" button), the maximum value is at the top (near the "Stop Clip" button).
| Binary | Hexadecimal | Decimal | Event |
|---|---|---|---|
|
|
|
pitch bend at top |
|
|
|
pitch bend 1 step above center |
|
|
|
pitch bend at center |
|
|
|
pitch bend 1 step below center |
|
|
|
pitch bend at bottom |
|
|
|
mod wheel at top |
|
|
|
mod wheel 1 step above center |
|
|
|
mod wheel at center |
|
|
|
mod wheel 1 step below center |
|
|
|
mod wheel at bottom |
This flag is only relevant if either the LEDs are controlled by Push 2 or the host sends values.
-
If the LEDs show a bar (flag = 0), then the current value from the touch strip hardware or from the host is taken to light up all LEDs from the bar start point (see next flag) up to the LED corresponding to the current value.
-
If the LEDs show a point (flag = 1), only the LED corresponding to the current value is lit.
This flag is only relevant if the LEDs show a bar.
-
If the bar starts at the bottom (flag = 0), then the lowest LED (near the play button) is the start point for the bar. The bar is always drawn upwards.
-
If the bar starts at the center (flag = 1), the middle LED (near the "New" button, at the same level as the horizontal center line of the pads) is the start point for the bar. The bar is drawn upwards if the current value is greater than the center value and downwards if it is less than the center value.
This flag decides if the touch strip hardware returns to a neutral value when the user lifts the finger off the strip. The neutral value may be at the bottom or the center of the strip depending on the "Autoreturn to" flag.
-
If autoreturn is to be done (flag = 1), then the touch strip hardware sends the neutral value as soon as the touch strip is released, just before the note-on message with velocity 0 that indicates the touch strip release.
-
If autoreturn is off (flag = 0), then the touch strip just sends the note-on message with velocity 0, leaving the value at the position where the finger was lift.
This flag is only relevant if the "Do autoreturn" flag is 1.
-
If autoreturn to bottom (flag = 0) is selected, the touch strip hardware resets itself to the value corresponding to the bottom of the touch strip when releasing the touch.
-
If autoreturn to center (flag = 1) is selected, the touch strip hardware jumps to the center value of the touch strip when the finger is lifted.
Push 2 has 2 pedal jacks, which can be connected to one or two pedals using mono or stereo jacks.
Pedal jack 1 is the one to the right when looking from the normal Push 2 user’s point of view, i.e. the one near the ON/OFF switch, pedal jack 2 is to the left of it, further away from the ON/OFF switch.
Since there are no unified industry standards for pedals, Push 2 can be configured to support many different kinds of (passive) pedals with 6.35mm (1/4 inch) phone plugs:
-
switched (ON/OFF) or expression and volume pedals (for certain mono volume pedals two cables/jacks are needed to connect a single pedal)
-
resistance range between 10k and 300k
-
all kinds of connection schemes, tip or ring, with or without offset pots etc.
-
linear or logarithmical or other tapers, heel down on or off, forward or inverted
-
it is also possible to use x/y controllers with two separate potentiometers, one at the tip and one at the ring
By default, the pedals are configured as ON/OFF switches, connected when pressed, sending control change messages:
-
64 "Sustain" for jack 1 (right)
-
69 "Hold 2" for jack 2 (left)
The pedal configuration process is typically started by sampling the pedal values, while asking the user to move the pedal to be configured. This allows to find out where the pedal is connected and how the measured values behave. Then the pedal jack parameters and the pedal value curve are configured. The pedal configuration is not persistent.
The "Sample Pedal Data" sysex command accumulates the ADC readings of the 4 pedal wires (left/right jack, tip/ring contact) over a certain sample count and sends a reply containing the averages for each of the wires.
Sample Pedal Data |
ID |
|
|||
Command Arguments |
n |
log2 of number of samples to average (0..19) |
|||
Reply Arguments |
d0 (LSB) |
lower 7 bits |
pedal 1 (right) contact 0 (ring) |
||
d0 (MSB) |
higher 5 bit |
||||
d1 (LSB) |
lower 7 bits |
pedal 1 (right) contact 1 (tip) |
|||
d1 (MSB) |
higher 5 bit |
||||
d2 (LSB) |
lower 7 bits |
pedal 2 (left) contact 0 (ring) |
|||
d2 (MSB) |
higher 5 bit |
||||
d3 (LSB) |
lower 7 bits |
pedal 2 (left) contact 1 (tip) |
|||
d3 (MSB) |
higher 5 bit |
||||
Example: |
|||||
|
Note
|
Beginning with firmware version 1.0.58, the new pedal configuration commands (codes 0x30, 0x31 and 0x32) replace their old versions (codes 0x11 and 0x12). |
The "Configure Pedal" sysex command defines, for one of four pedal contacts, if it is active, which MIDI control change message is sent, and when and to which port it is sent.
Configure Pedal |
ID |
|
|||
Command Arguments |
x |
pedal contact |
|||
c |
cc number to send (0…126) or 127 to turn contact off |
||||
m |
in which mode to send CC messages |
||||
p |
to which port to send CC messages |
||||
Example: |
|||||
The pedal curves for each contact define the mapping between measured voltage values and pedal positions, by specifying a voltage range and pedal positions at equal voltage intervals. The curve in each voltage/position interval is then linearly interpolated. The resulting position is mapped directly into CC values.
In other words, the curve contains positions P0, P1, …, P31 that correspond to the equidistant voltage values V0, V1, …, V31, where
Vi = Vhd + (Vtd - Vhd) * i / 32 , for i = 0…31
Vtd and Vhd are voltages in range 0 … 4095 that correspond to the heel/toe down values given to the "Set Pedal Curve Limits" command below. Vhd may be less than Vtd (normal signal) or larger than Vtd (inverted signal), but not equal to Vtd. In practice, they should differ by at least 32 units, otherwise the movement cannot be detected reliably.
The positions Pi are in range from 0 (heel down) to 255 (toe down), which map directly to CC values of 0 … 127. P0 should be 0, P32 is not transferred but assumed to be 255. The positions curve must be rising steadily (Pi < = Pi+1), independently of the relation between Vtd and Vhd.
For digital ("sustain") pedals, positions P0…P16 may be 0 and P17…P32 equal to 255. In this case, the interval between P16 and P17 is not interpolated, but either 0 (between Vhd and V16) or 127 (between V16 and Vtd) is sent as CC value.
The "Set Pedal Curve Limits" command sets Vtd and Vhd for a certain pedal contact.
Set Pedal Curve Limits |
ID |
|
|||
Command Arguments |
x |
pedal contact |
|||
h (LSB) |
lower 7 bits |
heel down value Vhd (corresponds to MIDI value 0) |
|||
h (MSB) |
higher 5 bits |
||||
t (LSB) |
lower 7 bits |
toe down value Vtd (corresponds to MIDI value 127) |
|||
t (MSB) |
higher 5 bits |
||||
Example: |
|||||
The "Set Pedal Curve Entries" sysex command is used to define the relation between the ADC value readings and pedal positions. To limit the size of a single sysex message, eight commands are needed to define a whole pedal curve. They can be sent in any order.
Set Pedal Curve Entries |
ID |
|
|||
Command Arguments |
x |
pedal contact |
|||
i |
index of first position (one of 0, 4, …, 28) |
||||
p (LSB) |
lower 7 bits |
position i |
|||
p (MSB) |
higher 1 bit |
||||
p (LSB) |
lower 7 bits |
position i + 1 |
|||
p (MSB) |
higher 1 bit |
||||
p (LSB) |
lower 7 bits |
position i + 2 |
|||
p (MSB) |
higher 1 bit |
||||
p (LSB) |
lower 7 bits |
position i + 3 |
|||
p (MSB) |
higher 1 bit |
||||
Example: |
|||||
To see something drawn on the display, the display backlight LEDs must be turned on. For this purpose, the "Set/Get Display Brightness" sysex command is used.
Set Display Brightness |
ID |
|
|||
Command Arguments |
b (LSB) |
lower 7 bits |
brightness |
||
b (MSB) |
higher 1 bit |
||||
Example: |
|||||
Get Display Brightness |
ID |
|
|||
Command Arguments |
none |
||||
Reply Arguments |
b (LSB) |
lower 7 bits |
brightness |
||
b (MSB) |
higher 1 bit |
||||
Example: |
|||||
The brightness range goes from 0 (off) to 255 (maximum).
When the Push 2 is USB powered (no external power supply) , the LED brightness is automatically limited to 100, with a reduced backlight current, resulting in a brightness of about 7% of the maximum possible backlight power.
The device inquiry allows to obtain the identity and version of the Push 2 device. The message format is specified by the MIDI standard. This allows to send inquiries to unknown devices. It also means that the device inquiry is formatted differently than all the other Push 2 sysex messages.
The device inquire sysex message has the following format.
| Message Data | Description |
|---|---|
|
SOX (start of sysex) |
|
Universal Non-Realtime Sysex ID |
|
Device ID (may as well be |
|
SubID1: General Information |
|
SubID2: Identity Request |
|
EOX (end of sysex) |
Example: |
|
Push 2 will answer with the following message:
| Message Data | Description | |
|---|---|---|
|
SOX |
|
|
Universal Non-Realtime Sysex ID |
|
|
Device ID |
|
|
SubID1: General Information |
|
|
SubID2: Identity Reply |
|
|
Manufacturers Sysex ID code |
|
|
device family code, 2x7 bits, LSB first (Product ID from USB header) |
|
|
device family member code, 2x7 bits, LSB first (Push 2) |
|
n |
major software revision (7 bits) |
|
m |
minor software revision (7 bits) |
|
k (LSB) |
lower 7 bits |
software build |
k (MSB) |
higher 7 bits |
|
s (LSB) |
bits 0… 6 |
serial number |
s |
bits 7…13 |
|
s |
bits 14…20 |
|
s |
bits 21…27 |
|
s (MSB) |
bits 28…31 |
|
r |
board revision (7 bits) |
|
|
EOX |
|
Example reply: |
||
The "Request Statistics" sysex command provides some useful information about the Push 2 device.
Request Statistics |
ID |
|
|||
Command Arguments |
r |
run ID to set (1…127, or 0 to keep it unchanged) |
|||
Reply Arguments |
p |
power supply status (1=external power supply, 0=USB power only) |
|||
r |
current run ID |
||||
t (LSB) |
bits 0… 6 |
uptime (seconds since last reboot) |
|||
t |
bits 7…13 |
||||
t |
bits 14…20 |
||||
t |
bits 21…27 |
||||
t (MSB) |
bits 28…31 |
||||
Example: |
|||||
The run ID is used to identify reboots. If a value in range 1…127 is given to the Request Statistics command, the value is set to this value. During a reboot the value is reset to zero. If a value of zero is later given to the Request Statistics command, the value remains unchanged and is returned in the reply. If zero is returned, the device has rebooted in the meantime. If the non-zero value that was set before is returned, the device did not reboot.
From USB point of view, Push 2 is a composite device with a MIDI interface and a generic bulk data interface used to drive the display. Libusb is used to access the display interface (see http://libusb.info). The library is freely available for Windows, MacOSX and Linux.
Below is some example code to open and close the display interface.
#ifdef _MSC_VER
#define _CRT_SECURE_NO_WARNINGS
#endif
#include <stdio.h>
#ifdef _WIN32
// see following link for a discussion of the
// warning suppression:
// http://sourceforge.net/mailarchive/forum.php?
// thread_name=50F6011C.2020000%40akeo.ie&forum_name=libusbx-devel
// Disable: warning C4200: nonstandard extension used:
// zero-sized array in struct/union
#pragma warning(disable:4200)
#include <windows.h>
#endif
#ifdef __linux__
#include <libusb-1.0/libusb.h>
#else
#include "libusb.h"
#endif
#define ABLETON_VENDOR_ID 0x2982
#define PUSH2_PRODUCT_ID 0x1967
static libusb_device_handle* open_push2_device()
{
int result;
if ((result = libusb_init(NULL)) < 0)
{
printf("error: [%d] could not initilialize usblib\n", result);
return NULL;
}
libusb_set_debug(NULL, LIBUSB_LOG_LEVEL_ERROR);
libusb_device** devices;
ssize_t count;
count = libusb_get_device_list(NULL, &devices);
if (count < 0)
{
printf("error: [%ld] could not get usb device list\n", count);
return NULL;
}
libusb_device* device;
libusb_device_handle* device_handle = NULL;
char ErrorMsg[128];
// set message in case we get to the end of the list w/o finding a device
sprintf(ErrorMsg, "error: Ableton Push 2 device not found\n");
for (int i = 0; (device = devices[i]) != NULL; i++)
{
struct libusb_device_descriptor descriptor;
if ((result = libusb_get_device_descriptor(device, &descriptor)) < 0)
{
sprintf(ErrorMsg,
"error: [%d] could not get usb device descriptor\n", result);
continue;
}
if (descriptor.bDeviceClass == LIBUSB_CLASS_PER_INTERFACE
&& descriptor.idVendor == ABLETON_VENDOR_ID
&& descriptor.idProduct == PUSH2_PRODUCT_ID)
{
if ((result = libusb_open(device, &device_handle)) < 0)
{
sprintf(ErrorMsg,
"error: [%d] could not open Ableton Push 2 device\n", result);
}
else if ((result = libusb_claim_interface(device_handle, 0)) < 0)
{
sprintf(ErrorMsg,
"error: [%d] could not claim interface 0 of Push 2 device\n", result);
libusb_close(device_handle);
device_handle = NULL;
}
else
{
break; // successfully opened
}
}
}
if (device_handle == NULL)
{
printf(ErrorMsg);
}
libusb_free_device_list(devices, 1);
return device_handle;
}
static void close_push2_device(libusb_device_handle* device_handle)
{
libusb_release_interface(device_handle, 0);
libusb_close(device_handle);
}
For each display frame, a frame header is sent, followed by the pixel data in 512 byte messages.
All other header formats or data message sizes are reserved. Some of them are used for undocumented functions like diagnostics or firmware flashing. Sending reserved messages may compromise the device function, up to making the device unusable, requiring to open the case and reflash the firmware. Please, don’t try to program the Push 2 Display interface yourself if you can’t make sure that reserved messages are avoided.
The frame header is the following fixed message of 16 bytes:
{ 0xFF, 0xCC, 0xAA, 0x88,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00 }
From USB point of view, each frame consists of 640 buffers of 512 bytes each, containing the pixel data. From a host point of view (i.e. when driving libusb), the pixel data is typically sent using larger buffers, for example of 16kbytes each. This is needed for efficiency and high frame rates.
The Push 2 Display shows 160 lines of 960 pixels of 16 bit each. The pixel data is sent line by line, starting with the topmost. For each line, 2kbytes are sent. They consist of 1920 bytes of pixel data and 128 filler bytes, which avoid line borders occuring in the middle of the 512 byte USB buffers. The pixels for each line are sent with leftmost pixel first.
The pixels are encoded as 16 bit RGB values according to the following table. In memory and over USB, the least significant byte is sent first (little endian).
bit |
15 |
14 |
13 |
12 |
11 |
10 |
09 |
08 |
07 |
06 |
05 |
04 |
03 |
02 |
01 |
00 |
value |
b4 |
b3 |
b2 |
b1 |
b0 |
g5 |
g4 |
g3 |
g2 |
g1 |
g0 |
r4 |
r3 |
r2 |
r1 |
r0 |
Before sending a line buffer, it must be XORED with the 32 bit signal
shaping pattern 0xFFE7F3E7 (i.e. the pixel data bits at positions
which are 1 in the pattern must be inverted). The pattern assumes little
endian representation, with the left pixel in the lower two bytes,
i.e. the first byte sent is xor’ed with 0xE7, the second with 0xF3, the
third with 0xE7, the fourth with 0xFF, the fifth with 0xE7, etc.
A display frame is displayed when its complete pixel data is received. The display runs at 60 fps. Frames are double-buffered and repeated if the next frame does not arrive in time. If no frame arrives within 2 seconds, the display is turned black.
The following code snippet shows how to allocate the frame header and pixel data buffer transfers for libusb.
#define PUSH2_BULK_EP_OUT 0x01
#define TRANSFER_TIMEOUT 1000 // milliseconds
unsigned char frame_header[16] = {
0xff, 0xcc, 0xaa, 0x88,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00
};
libusb_transfer* frame_header_transfer;
if ((frame_header_transfer = libusb_alloc_transfer(0)) == NULL)
{
printf("error: could not allocate frame header transfer handle\n");
}
else
{
libusb_fill_bulk_transfer(
frame_header_transfer,
device_handle,
PUSH2_BULK_EP_OUT,
frame_header,
sizeof(frame_header),
on_frame_header_transfer_finished,
NULL,
TRANSFER_TIMEOUT);
}
libusb_transfer* pixel_data_transfer;
if ((pixel_data_transfer = libusb_alloc_transfer(0)) == NULL)
{
printf("error: could not allocate transfer handle\n");
}
else
{
libusb_fill_bulk_transfer(
pixel_data_transfer,
device_handle,
PUSH2_BULK_EP_OUT,
buffer,
BUFFER_SIZE,
on_buffer_transfer_finished,
NULL,
TRANSFER_TIMEOUT);
}
The MIDI Implementation chart according to the requirements of the MIDI Manufacturers Association (www.midi.org) is given on the following three pages.
MIDI Implementation Chart v. 2.0 (Page 1 of 3) |
|||
Manufacturer: Ableton AG Model: Push 2 Version: 1.1 Date: Jan. 24, 2017 |
|||
Transmit |
Recognize |
Remarks |
|
1. Basic Information |
|||
MIDI channels |
32 |
32 |
Live port: L1-L16, User port: U1-U16 |
Note numbers |
0-10, 12, 36-99 |
36-99 |
pads, touch sensors (see drawing) |
Program change |
No |
No |
|
Bank Select response? (Yes/No) |
No |
||
Mode 1: Omni-On, Poly (Yes/No) |
No |
||
Note-On Velocity (Yes/No) |
Yes |
Yes |
pads, touch, LEDs |
Note-Off Velocity (Yes/No) |
No |
No |
|
Channel Aftertouch (Yes/No) |
Yes |
No |
configurable |
Poly (Key) Aftertouch (Yes/No) |
Yes |
No |
configurable |
Pitch Bend (Yes/No) |
Yes |
Yes |
touch strip (configurable) |
Active Sensing (Yes/No) |
No |
No |
|
System Reset (Yes/No) |
No |
No |
|
Tune Request (Yes/No) |
No |
No |
|
Universal System Exclusive |
--- |
--- |
|
Manufacturer System Exclusive |
Yes |
Yes |
Manufacturer: Ableton, ID: 00H 21H 1DH |
NRPNs (Yes/No) |
No |
No |
|
RPN 00 (Pitch Bend Sensitivity) (Yes/No) |
No |
No |
|
2. MIDI Timing and Synchronization |
|||
MIDI Clock (Yes/No) |
No |
Yes |
LED animation sync |
Song Position Pointer (Yes/No) |
No |
No |
|
Song Select (Yes/No) |
No |
No |
|
Start (Yes/No) |
No |
Yes |
used for LED animation sync |
MIDI Time Code (Yes/No) |
No |
No |
|
MIDI Machine Control (Yes/No) |
No |
No |
|
MIDI Show Control (Yes/No) |
No |
No |
|
3. Extensions Compatibility |
|||
General MIDI compatible? |
No |
No |
|
DLS compatible? |
No |
No |
|
Standard MIDI Files (Type(s)/No) |
No |
No |
|
XMF Files (Type(s)/No) |
No |
No |
|
SP-MIDI compatible? (Yes/No) |
No |
Yes |
|
MIDI Implementation Chart v. 2.0 (Page 2 of 3) |
||||
Manufacturer: Ableton AG Model: Push 2 Version: 1.1 Date: Jan. 24, 2017 |
||||
Control # |
Function |
Transmit |
Recognize |
Remarks |
0 |
Bank Select (MSB) |
No |
No |
|
1 |
Modulation Wheel (MSB) |
Yes |
Yes |
touch strip (configurable) |
2 |
Breath Controller (MSB) |
No |
No |
|
3 |
Yes |
Yes |
tap tempo button |
|
4 |
Foot Controller (MSB) |
No |
No |
|
5 |
Portamento Time (MSB) |
No |
No |
|
6 |
Data Entry (MSB) |
No |
No |
|
7 |
Channel Volume (MSB) |
No |
No |
|
8 |
Balance (MSB) |
No |
No |
|
9 |
Yes |
Yes |
metronome button |
|
10 |
Pan (MSB) |
No |
No |
|
11 |
Expression (MSB) |
No |
No |
|
12 |
Effect Control 1 (MSB) |
No |
No |
|
13 |
Effect Control 2 (MSB) |
No |
No |
|
14 |
Yes |
No |
tempo encoder |
|
15 |
Yes |
No |
swing encoder |
|
16 |
General Purpose Controller 1 (MSB) |
No |
No |
|
17 |
General Purpose Controller 2 (MSB) |
No |
No |
|
18 |
General Purpose Controller 3 (MSB) |
No |
No |
|
19 |
General Purpose Controller 4 (MSB) |
No |
No |
|
20 |
Yes |
Yes |
track 1 button below display |
|
21 |
Yes |
Yes |
track 2 button below display |
|
22 |
Yes |
Yes |
track 3 button below display |
|
23 |
Yes |
Yes |
track 4 button below display |
|
24 |
Yes |
Yes |
track 5 button below display |
|
25 |
Yes |
Yes |
track 6 button below display |
|
26 |
Yes |
Yes |
track 7 button below display |
|
27 |
Yes |
Yes |
track 8 button below display |
|
28 |
Yes |
Yes |
master button |
|
29 |
Yes |
Yes |
stop clip button |
|
30 |
Yes |
Yes |
setup button |
|
31 |
Yes |
Yes |
layout button |
|
32 |
Bank Select (LSB) |
No |
No |
|
33 |
Modulation Wheel (LSB) |
No |
No |
|
34 |
Breath Controller (LSB) |
No |
No |
|
35 |
Yes |
Yes |
convert switch |
|
36 |
Foot Controller (LSB) |
Yes |
Yes |
scene 8 button |
37 |
Portamento Time (LSB) |
Yes |
Yes |
scene 7 button |
38 |
Data Entry (LSB) |
Yes |
Yes |
scene 6 button |
39 |
Channel Volume (LSB) |
Yes |
Yes |
scene 5 button |
40 |
Balance (LSB) |
Yes |
Yes |
scene 4 button |
41 |
Yes |
Yes |
scene 3 button |
|
42 |
Pan (LSB) |
Yes |
Yes |
scene 2 button |
43 |
Expression (LSB) |
Yes |
Yes |
scene 1 button |
44 |
Effect Control 1 (LSB) |
Yes |
Yes |
arrow left button |
45 |
Effect Control 2 (LSB) |
Yes |
Yes |
arrow right button |
46 |
Yes |
Yes |
arrow up button |
|
47 |
Yes |
Yes |
arrow down button |
|
48 |
General Purpose Controller 1 (LSB) |
Yes |
Yes |
select button |
49 |
General Purpose Controller 2 (LSB) |
Yes |
Yes |
shift button |
50 |
General Purpose Controller 3 (LSB) |
Yes |
Yes |
note button |
51 |
General Purpose Controller 4 (LSB) |
Yes |
Yes |
session button |
52 |
Yes |
Yes |
add device button |
|
53 |
Yes |
Yes |
add track button |
|
54 |
Yes |
Yes |
octave down button |
|
55 |
Yes |
Yes |
octave up button |
|
56 |
Yes |
Yes |
repeat button |
|
57 |
Yes |
Yes |
accent button |
|
58 |
Yes |
Yes |
scale button |
|
59 |
Yes |
Yes |
user button |
|
60 |
Yes |
Yes |
mute button |
|
61 |
Yes |
Yes |
solo button |
|
62 |
Yes |
Yes |
page left button |
|
63 |
Yes |
Yes |
page right button |
|
MIDI Implementation Chart v. 2.0 (Page 3 of 3) |
||||
Manufacturer: Ableton AG Model: Push 2 Version: 1.1 Date: Jan. 24, 2017 |
||||
Control # |
Function |
Transmit |
Recognize |
Remarks |
64 |
Sustain Pedal |
Yes |
No |
foot pedal 1 (configurable) |
65 |
Portamento On/Off |
No |
No |
|
66 |
Sostenuto |
No |
No |
|
67 |
Soft Pedal |
No |
No |
|
68 |
Legato Footswitch |
No |
No |
|
69 |
Hold 2 |
Yes |
No |
foot pedal 2 (configurable) |
70 |
Sound Controller 1 (default: Sound Variation) |
No |
No |
|
71 |
Sound Controller 2 (default: Timbre / Harmonic Quality) |
Yes |
No |
track 1 encoder |
72 |
Sound Controller 3 (default: Release Time) |
Yes |
No |
track 2 encoder |
73 |
Sound Controller 4 (default: Attack Time) |
Yes |
No |
track 3 encoder |
74 |
Sound Controller 5 (default: Brightness) |
Yes |
No |
track 4 encoder |
75 |
Sound Controller 6 (GM2 default: Decay Time) |
Yes |
No |
track 5 encoder |
76 |
Sound Controller 7 (GM2 default: Vibrato Rate) |
Yes |
No |
track 6 encoder |
77 |
Sound Controller 8 (GM2 default: Vibrato Depth) |
Yes |
No |
track 7 encoder |
78 |
Sound Controller 9 (GM2 default: Vibrato Delay) |
Yes |
No |
track 8 encoder |
79 |
Sound Controller 10 (GM2 default: Undefined) |
Yes |
No |
master volume encoder |
80 |
General Purpose Controller 5 |
No |
No |
|
81 |
General Purpose Controller 6 |
No |
No |
|
82 |
General Purpose Controller 7 |
No |
No |
|
83 |
General Purpose Controller 8 |
No |
No |
|
84 |
Portamento Control |
No |
No |
|
85 |
Yes |
Yes |
play button |
|
86 |
Yes |
Yes |
record button |
|
87 |
Yes |
Yes |
new button |
|
88 |
Yes |
Yes |
duplicate button |
|
89 |
Yes |
Yes |
automate button |
|
90 |
Yes |
Yes |
fixed length button |
|
91 |
Effects 1 Depth (default: Reverb Send) |
No |
No |
|
92 |
Effects 2 Depth (default: Tremolo Depth) |
No |
No |
|
93 |
Effects 3 Depth (default: Chorus Send) |
No |
No |
|
94 |
Effects 4 Depth (default: Celeste [Detune] Depth) |
No |
No |
|
95 |
Effects 5 Depth (default: Phaser Depth) |
No |
No |
|
96 |
Data Increment |
No |
No |
|
97 |
Data Decrement |
No |
No |
|
98 |
Non-Registered Parameter Number (LSB) |
No |
No |
|
99 |
Non-Registered Parameter Number(MSB) |
No |
No |
|
100 |
Registered Parameter Number (LSB) |
No |
No |
|
101 |
Registered Parameter Number(MSB) |
No |
No |
|
102 |
Yes |
Yes |
track 1 button above display |
|
103 |
Yes |
Yes |
track 2 button above display |
|
104 |
Yes |
Yes |
track 3 button above display |
|
105 |
Yes |
Yes |
track 4 button above display |
|
106 |
Yes |
Yes |
track 5 button above display |
|
107 |
Yes |
Yes |
track 6 button above display |
|
108 |
Yes |
Yes |
track 7 button above display |
|
109 |
Yes |
Yes |
track 8 button above display |
|
110 |
Yes |
Yes |
device button |
|
111 |
Yes |
Yes |
browse button |
|
112 |
Yes |
Yes |
mix button |
|
113 |
Yes |
Yes |
clip button |
|
114 |
No |
No |
||
115 |
No |
No |
||
116 |
Yes |
Yes |
quantize button |
|
117 |
Yes |
Yes |
double loop button |
|
118 |
Yes |
Yes |
delete button |
|
119 |
Yes |
Yes |
undo button |
|
120 |
All Sound Off |
No |
No |
|
121 |
Reset All Controllers |
No |
No |
|
122 |
Local Control On/Off |
No |
No |
|
123 |
All Notes Off |
No |
No |
|
124 |
Omni Mode Off |
No |
No |
|
125 |
Omni Mode On |
No |
No |
|
126 |
Poly Mode Off |
No |
No |
|
127 |
Poly Mode On |
No |
No |
|