Ableton Push 2 MIDI and Display Interface Manual

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

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.

Table of Contents

1. Introduction
- 1.1. Purpose
- 1.2. Architecture Overview
2. MIDI Interface
3. Display Interface
- 3.1. USB Display Interface Access
- 3.2. Display Interface Protocol
4. Appendix A: MIDI Implementation Chart

1. Introduction

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.

1.1. Purpose

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.

1.2. Architecture Overview

Ableton Push 2 is connected to the host computer via USB 2.0. The USB interface provides two MIDI ports and a display interface, which are used by Live and other programs to control various aspects of Push 2.

Figure 1. Architecture Overview

2. MIDI Interface

2.1. MIDI Interface Access

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:

Figure 2. Push 2 User Port Used by Live

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:

Table 1. MIDI Port Names

OS	Port	Input	Output
Windows 7	Live	Ableton Push 2 nn	Ableton Push 2 nn
Windows 7	User	MIDIIN2 (Ableton Push 2) nn	MIDIOUT2 (Ableton Push 2) nn
MacOSX	Live	Ableton Push 2 Live Port	Ableton Push 2 Live Port
MacOSX	User	Ableton Push 2 User Port	Ableton Push 2 User Port
Linux	Live	Ableton Push 2 nn:0	Ableton Push 2 nn:0
Linux	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.

2.2. MIDI Messages

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	`0x90 … 0x9F`	`0nnnnnnn 0vvvvvvv`	set LED color	LEDs
			pad pressed	Pads
			encoder touched/released	Encoders
			touch strip touched/released	Touch Strip
Note off	`0x80`	`0nnnnnnn 00000000`	pad released	Pads
Control change	`0xB0 … 0xBF`	`0nnnnnnn 0vvvvvvv`	set LED color	LEDs
			button pressed/released	Buttons
			encoder turned	Encoders
			pedal position	Pedals
			touch strip position	Touch Strip
Pitch bend	`0xE0`	`0q000000 0ppppppp`	touch strip position	Touch Strip
Channel Pressure	`0xD0`	`0vvvvvvv`	global pad aftertouch	Aftertouch
Poly Key Pressure	`0xA0`	`0nnnnnnn 0vvvvvvv`	individual pad aftertouch	Aftertouch

2.3. MIDI Mapping

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.

Figure 3. MIDI Mapping

2.4. Sysex Commands

The sysex system exclusive ("sysex") commands are vendor-specific MIDI messages used to configure Push 2 and retrieve device states.

2.4.1. General Command Format

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.

Table 2. General Sysex Format

Message Data	Description
`0xF0`	SOX (start of sysex)
`0x00 0x21 0x1D`	Ableton sysex ID assigned by the MIDI Manufacturers Association
`0x01`	Device ID. Probably not needed for USB devices, but this is what most manufacturers do.
`0x01`	Model ID
ID	Command or reply ID (7 bits unsigned integer)
Arguments	A number of 7 bit values depending on command or reply ID (the maximum number of arguments is 17)
`0xF7`	EOX (end of sysex)
Example: `[F0 00 21 1D 01 01 14 04 03 42 F7]` = command with ID `0x14` and arguments `0x04 0x03 0x42`

2.4.2. Command List

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.

Table 3. Command List

Command ID	Sends Reply	Command Name	Chapter
`0x03`		Set LED Color Palette Entry	RGB LED Color Processing
`0x04`	yes	Get LED Color Palette Entry
`0x05`		Reapply Color Palette
`0x06`		Set LED Brightness	Global LED Brightness
`0x07`	yes	Get LED Brightness	Global LED Brightness
`0x08`		Set Display Brightness	Display Backlight
`0x09`		Get Display Brightness	Display Backlight
`0x0A`	yes	Set MIDI Mode	MIDI Mode
`0x0B`		Set LED PWM Frequency Correction	PWM Frequency
`0x13`	yes	Sample Pedal Data	Pedal Sampling
`0x14`		Set LED White Balance	White Balance
`0x15`	yes	Get LED White Balance	White Balance
`0x17`		Set Touch Strip Configuration	Touch Strip
`0x18`	yes	Get Touch Strip Configuration
`0x19`		Set Touch Strip LEDs
`0x1A`	yes	Request Statistics	Statistics
`0x1B`		Set Pad Parameters	Pad Parameters
`0x1D`	yes	Read 400g Pad Values From Flash	Individual Pad Calibration
`0x1E`		Set Aftertouch Mode	Aftertouch
`0x1F`	yes	Get Aftertouch Mode	Aftertouch
`0x20`		Set Pad Velocity Curve Entry	Velocity Curve
`0x21`	yes	Get Pad Velocity Curve Entry	Velocity Curve
`0x22`		Set Temporary 400g Pad Values	Individual Pad Calibration
`0x23`	yes	Flash LED White Balance	White Balance
`0x28`		Select Pad Settings	Pad Settings
`0x29`	yes	Get Selected Pad Settings	Pad Settings
`0x30`		Configure Pedal	Pedal Configuration
`0x31`		Set Pedal Curve Limits
`0x32`		Set Pedal Curve Entries

2.5. MIDI Mode

Push 2 works in three MIDI modes that define the behavior of the two MIDI I/O ports.

In Live mode

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.

In User mode

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.

In Dual mode

Incoming non-sysex MIDI from both ports is accepted.
All outgoing non-sysex MIDI is sent to both ports.

In all three modes

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	`0x0A`
Command Arguments	m	mode (0=Live, 1=User, 2=Dual)
Reply Arguments	m	mode (0=Live, 1=User, 2=Dual)
Example: `[F0 00 21 1D 01 01 0A 01 F7]` = set MIDI mode to User Reply: `[F0 00 21 1D 01 01 0A 01 F7]` = MIDI mode set to User

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.

2.6. LEDs

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).

2.6.1. Setting LED Colors

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) or 1011 (for cc) and the note or controller number nnnnnnn (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).

Examples

Binary	Hexadecimal	Decimal	Result
`10010000 01100011 01111111`	`0x90 0x63 0x7F`	`144 99 127`	set the top right pad RGB LED to red
`10010000 00100100 01111110`	`0x90 0x24 0x7E`	`144 36 126`	set the bottom left pad RGB LED to green
`10110000 00111100 00000000`	`0xB0 0x3C 0x00`	`176 60 0`	turn the mute button RGB LED off
`10110000 00011100 01111111`	`0xB0 0x1C 0x7F`	`176 28 127`	set the master button white LED to max
`10110000 00000011 00000000`	`0xB0 0x03 0x00`	`176 3 0`	turn the tempo button white LED off
`10111111 01110111 01111111`	`0xBF 0x77 0x7F`	`191 119 127`	let the undo button white LED blink slowly
`10110001 00111100 01111101`	`0xB1 0x3C 0x7D`	`177 60 125`	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.

2.6.2. RGB LED Color Processing

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

Figure 4. RGB LED Color Processing

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	`0x03`
Command Arguments	i	color index (0..127)
	r (LSB)	lower 7 bits	red color
	r (MSB)	higher 1 bit	red color
	g (LSB)	lower 7 bits	green color
	g (MSB)	higher 1 bit	green color
	b (LSB)	lower 7 bits	blue color
	b (MSB)	higher 1 bit	blue color
	w (LSB)	lower 7 bits	white color
	w (MSB)	higher 1 bit	white color
Example: `[F0 00 21 1D 01 01 03 7D 00 00 00 00 7F 01 7E 00 F7]` = set entry 125 to 0/0/255 and 126

Get LED Color Palette Entry				ID	`0x04`
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: `[F0 00 21 1D 01 01 04 7D F7]` = get entry 125 Reply: `[F0 00 21 1D 01 01 04 7D 00 00 00 00 7F 01 7E 00 F7]` = entry 125 is 0/0/255 and 126

Reapply Color Palette		ID	`0x05`
Command Arguments	none
Example: `[F0 00 21 1D 01 01 05 F7]` = trigger palette reapplication

2.6.3. White LED Color Processing

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.

Figure 5. White LED Color Processing

2.6.4. Touch Strip LED Color Processing

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.

Figure 6. Touchstrip LED Color Processing

2.6.5. Default Color Palettes

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.

Table 4. Default Color Palettes (subset)

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

2.6.6. White Balance

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.

Table 5. Color Groups

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	`0x14`
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: `[F0 00 21 1D 01 01 14 03 2C 02 F7]` = set WB factor of red pad LEDs to 300

Get LED White Balance			ID	`0x15`
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: `[F0 00 21 1D 01 01 15 09 F7]` = get white button WB factor Reply: `[F0 00 21 1D 01 01 15 09 00 04 F7]` = white button WB factor is 512

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	`0x23`
Command Arguments	c	color group (0…10)
	b (LSB)	lower 7 bits of white balance factor or `0x7F`
	b (MSB)	higher 4 bits of white balance factor or `0x7F`
Reply Arguments	c	color group (0…10)
	r	0 for success, `0x7F` for failure
Example: `[F0 00 21 1D 01 01 23 07 01 02 F7]` = flash green display button WB factor to be 257 Reply: `[F0 00 21 1D 01 01 23 07 00 F7]` = green display button WB factor flashed successfully

2.6.7. Global LED Brightness

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	`0x06`
Command Arguments	b	brightness (0…127)
Example: `[F0 00 21 1D 01 01 06 40 F7]` = set LED brightness to 64

Get LED Brightness			ID	`0x07`
Command Arguments	none
Reply Arguments	b	brightness (0..127)
Example: `[F0 00 21 1D 01 01 07 F7]` = get LED brightness Reply: `[F0 00 21 1D 01 01 07 10 F7]` = LED brightness is 16

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.

2.6.8. LED Animation

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.

Table 6. LED Transition Types

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.

Figure 7. LED Transitions

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.

2.6.9. PWM Frequency

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	`0x0B`
Command Arguments	n (LSB)	lowest 7 bits	correction factor
	n	middle 7 bits
	n (MSB)	highest 7 bit
Example: `[F0 00 21 1D 01 01 0B 05 3D 02 F7]` = set LED PWM to 60 Hz

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.

2.7. Buttons

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.

Examples

Binary	Hexadecimal	Decimal	Event
`10110000 00001001 01111111`	`0xB0 0x09 0x7F`	`176 9 127`	metronome button pressed
`10110000 00001001 00000000`	`0xB0 0x09 0x00`	`176 9 0`	metronome button released

2.8. Pads

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.

Examples

Binary	Hexadecimal	Decimal	Event
`10010000 00100100 01111111`	`0x90 0x24 0x7F`	`176 36 127`	left bottom pad hit hard
`10010000 00101011 00000001`	`0x90 0x2B 0x01`	`176 43 1`	right bottom pad pressed softly
`10000000 01100011 00000000`	`0x80 0x63 0x00`	`176 99 0`	right top pad released

2.8.1. Velocity Curve

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	`0x20`
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: `[F0 00 21 1D 01 01 20 10 3E 41 44 46 49 4B 4D 50 52 54 56 59 5B 5D 5F 62 F7]` = set pad velocities for indices 16…31, corresponding to weights 32…62 g

Get Pad Velocity Curve Entry			ID	`0x21`
Command Arguments	i	index (0…127)
Reply Arguments	i	index (0…127)
	v	velocity
Example: `[F0 00 21 1D 01 01 21 11 F7]` = get pad velocity at index 17 (34g) Reply: `[F0 00 21 1D 01 01 21 11 3E F7]` = velocity for index 17 is 62

2.8.2. Pad Parameters

The "Set Pad Parameters" sysex commands allows to set some parameters that apply to all 64 pads.

Set Pad Parameters				ID	`0x1B`
Command Arguments	t0 (LSB)	lower 7 bits	parameter 0 (unused)
	t0 (MSB)	higher 5 bits	parameter 0 (unused)
	t1 (LSB)	lower 7 bits	parameter 1 (unused)
	t1 (MSB)	higher 5 bits	parameter 1 (unused)
	a0 (LSB)	lower 7 bits	lower aftertouch threshold, must be > 400
	a0 (MSB)	higher 5 bits	lower aftertouch threshold, must be > 400
	a1 (LSB)	lower 7 bits	upper aftertouch threshold, must be greater then the lower threshold a0
	a1 (MSB)	higher 5 bits
Example: `[F0 00 21 1D 01 01 1B 00 00 00 00 44 09 22 0C F7]` = set pad aftertouch range to 1220 … 1570

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.

2.8.3. Pad Settings

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	`0x28`
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: `[F0 00 21 1D 01 01 28 03 06 02 F7]` = set sixth pad in third row to low sensitivity

Get Selected Pad Settings			ID	`0x29`
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: `[F0 00 21 1D 01 01 29 03 06 F7]` = get settings selected for scene 3 track 6 Reply: `[F0 00 21 1D 01 01 29 03 06 00 F7]` = regular sensitivity is selected for this pad

2.8.4. Individual Pad Calibration

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	`0x1D`
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	400g value for track 1 (leftmost)
	v1 (LSB)	lower 7 bits	400g value for track 2
	v1 (MSB)	higher 5 bits	400g value for track 2
	v2 (LSB)	lower 7 bits	400g value for track 3
	v2 (MSB)	higher 5 bits	400g value for track 3
	v3 (LSB)	lower 7 bits	400g value for track 4
	v3 (MSB)	higher 5 bits	400g value for track 4
	v4 (LSB)	lower 7 bits	400g value for track 5
	v4 (MSB)	higher 5 bits	400g value for track 5
	v5 (LSB)	lower 7 bits	400g value for track 6
	v5 (MSB)	higher 5 bits	400g value for track 6
	v6 (LSB)	lower 7 bits	400g value for track 7
	v6 (MSB)	higher 5 bits	400g value for track 7
	v7 (LSB)	lower 7 bits	400g value for track 8 (rightmost)
	v7 (MSB)	higher 5 bits	400g value for track 8 (rightmost)
Example: `[F0 00 21 1D 01 01 1D 04 F7]` = get 400g values for scene 4 (fourth row of pads) Reply: `[F0 00 21 1D 01 01 1D 04 41 0C 42 0C 43 0C 44 0C 45 0C 46 0C 47 0C 48 0C F7]` = values for scene 4 range from 1601 to 1608

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	`0x22`
Command Arguments	s	scene (1=top … 8=bottom)
	v0 (LSB)	lower 7 bits	400g value for track 1 (leftmost)
	v0 (MSB)	higher 5 bits	400g value for track 1 (leftmost)
	v1 (LSB)	lower 7 bits	400g value for track 2
	v1 (MSB)	higher 5 bits	400g value for track 2
	v2 (LSB)	lower 7 bits	400g value for track 3
	v2 (MSB)	higher 5 bits	400g value for track 3
	v3 (LSB)	lower 7 bits	400g value for track 4
	v3 (MSB)	higher 5 bits	400g value for track 4
	v4 (LSB)	lower 7 bits	400g value for track 5
	v4 (MSB)	higher 5 bits	400g value for track 5
	v5 (LSB)	lower 7 bits	400g value for track 6
	v5 (MSB)	higher 5 bits	400g value for track 6
	v6 (LSB)	lower 7 bits	400g value for track 7
	v6 (MSB)	higher 5 bits	400g value for track 7
	v7 (LSB)	lower 7 bits	400g value for track 8 (rightmost)
	v7 (MSB)	higher 5 bits	400g value for track 8 (rightmost)
Example: `[F0 00 21 1D 01 01 22 01 40 0C 40 0C 40 0C 40 0C 40 0C 40 0C 40 0C 40 0C F7]` = set all 400g values for scene 1 (topmost row of pads) to 1600

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).

2.8.5. Aftertouch

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 vvvvvvv reflects 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.

Examples

Binary	Hexadecimal	Decimal	Event
`11010000 01111111`	`0xD0 0x7F`	`208 127`	maximum channel pressure
`11010000 00000000`	`0xD0 0x00`	`208 0`	no channel pressure (i.e. released)
`10100000 00100100 01111111`	`0xA0 0x24 0x7F`	`160 36 127`	maximum key pressure on bottom left pad
`10100000 00100100 00000001`	`0xA0 0x24 0x01`	`160 36 1`	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	`0x1E`
Command Arguments	m	aftertouch mode (0 = channel pressure, 1 = polyphonic key pressure)
Example: `[F0 00 21 1D 01 01 1E 1 F7]` = set pad aftertouch mode to "polyphonic key pressure"

Get Aftertouch Mode			ID	`0x1F`
Command Arguments	none
Reply Arguments	m	aftertouch mode (see above)
Example: `[F0 00 21 1D 01 01 1F F7]` = get aftertouch mode Reply: `[F0 00 21 1D 01 01 1F 0 F7]` = aftertouch mode is "channel pressure"

2.9. Encoders

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 0xxxxxx or 1yyyyyy gives 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.

Examples

Binary	Hexadecimal	Decimal	Event
`10110000 01001111 00000001`	`0xB0 0x4F 0x01`	`176 79 1`	master encoder turned right by 1 step
`10110000 01001111 00001010`	`0xB0 0x4F 0x0A`	`176 79 10`	master encoder turned right by 10 steps
`10110000 00001110 01111111`	`0xB0 0x0E 0x7F`	`176 14 127`	tempo encoder turned left by 1 step
`10110000 00001110 01111100`	`0xB0 0x0E 0x7C`	`176 14 124`	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.

Examples

Binary	Hexadecimal	Decimal	Event
`10010000 01000111 01111111`	`0x90 0x47 0x7F`	`144 71 127`	leftmost track encoder touched
`10010000 01000111 00000000`	`0x90 0x47 0x00`	`144 71 0`	leftmost track encoder released

2.10. Touch Strip

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.

Examples

Binary	Hexadecimal	Decimal	Event
`10010000 00001100 01111111`	`0x90 0x0C 0x7F`	`144 12 127`	touch strip touched
`10010000 00001100 00000000`	`0x90 0x0C 0x00`	`144 12 0`	touch strip released

2.10.1. Touch Strip Configuration

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	`0x17`
Command Arguments	t	configuration flags
Example: `[F0 00 21 1D 01 01 17 68 F7]` = set touch strip configuration to 1101000

Get Touch Strip Configuration			ID	`0x18`
Command Arguments	none
Reply Arguments	t	configuration flags
Example: `[F0 00 21 1D 01 01 18 F7]` = get touchstrip configuration Reply: `[F0 00 21 1D 01 01 18 25 F7]` = touchstrip configuration is 0100101

    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.

Touchstrip Configuration Flags Examples

Binary	Hexadecimal	Decimal	Configuration	Typical Application
`1101000`	`0x68`	`104`	Default: Push 2 controls LEDs as single point with autoreturn to center, sends pitch bend	Pitch bend control
`0001100`	`0x0C`	`12`	Push 2 controls LEDs as bar starting at bottom, no autoreturn, sends modulation	Volume control
`0000011`	`0x03`	`3`	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.

LEDs Controlled By

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.

Host Sends

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: `[F0 00 21 1D 01 01 19 27 24 27 24 27 24 27 24 27 24 27 24 27 24 27 4 F7]` = set each fourth touch strip LED to full brightness, the others are half lit

Values Sent As

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).

Touchstrip Value Examples

Binary	Hexadecimal	Decimal	Event
`11100000 01000000 01111111`	`0xE0 0x40 0x7F`	`224 64 127`	pitch bend at top
`11100000 01000000 01000000`	`0xE0 0x40 0x40`	`224 64 64`	pitch bend 1 step above center
`11100000 00000000 01000000`	`0xE0 0x00 0x40`	`224 0 64`	pitch bend at center
`11100000 01000000 00111111`	`0xE0 0x40 0x3F`	`224 64 63`	pitch bend 1 step below center
`11100000 00000000 00000000`	`0xE0 0x00 0x00`	`224 0 0`	pitch bend at bottom
`10110000 00000001 01111111`	`0xB0 0x01 0x7F`	`176 1 127`	mod wheel at top
`10110000 00000001 01000001`	`0xB0 0x01 0x41`	`176 1 65`	mod wheel 1 step above center
`10110000 00000001 01000000`	`0xB0 0x01 0x40`	`176 1 64`	mod wheel at center
`10110000 00000001 00111111`	`0xB0 0x01 0x3F`	`176 1 63`	mod wheel 1 step below center
`10110000 00000001 00000000`	`0xB0 0x01 0x00`	`176 1 0`	mod wheel at bottom

LEDs Show

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.

Bar Starts At

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.

Do Autoreturn

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.

Autoreturn To

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.

2.11. Pedals

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.

2.11.1. Pedal Sampling

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	`0x13`
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	pedal 1 (right) contact 0 (ring)
	d1 (LSB)	lower 7 bits	pedal 1 (right) contact 1 (tip)
	d1 (MSB)	higher 5 bit	pedal 1 (right) contact 1 (tip)
	d2 (LSB)	lower 7 bits	pedal 2 (left) contact 0 (ring)
	d2 (MSB)	higher 5 bit	pedal 2 (left) contact 0 (ring)
	d3 (LSB)	lower 7 bits	pedal 2 (left) contact 1 (tip)
	d3 (MSB)	higher 5 bit	pedal 2 (left) contact 1 (tip)
Example: `[F0 00 21 1D 01 01 13 09 F7]` = sample pedal data for 512 samples (2⁹, approx 0.4 sec) Reply: `[F0 00 21 1D 01 01 13 68 07 5C 0B 50 0F 44 13 F7]` = results are 1000, 1500, 2000 and 2500

2.11.2. Pedal Configuration

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	`0x30`
Command Arguments	x	pedal contact 0 = right jack, ring 1 = right jack, tip 2 = left jack, ring 3 = left jack, tip
	c	cc number to send (0…126) or 127 to turn contact off
	m	in which mode to send CC messages 0 - send always (default) 1 - send in Live mode only 2 - send in User mode only 3 - send in Dual mode only
	p	to which port to send CC messages 0 - send to port according to MIDI mode (default) 1 - send to Live port 2 - send to User port 3 - send to both ports
Example: `[F0 00 21 1D 01 01 30 02 0B 00 02 F7]` = configure left jack ring contact to send control change 11 ("expression") in all MIDI modes to User port

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 P₀, P₁, …, P₃₁ that correspond to the equidistant voltage values V₀, V₁, …, V₃₁, where

V_i = V_hd + (V_td - V_hd) * i / 32 , for i = 0…31

V_td and V_hd are voltages in range 0 … 4095 that correspond to the heel/toe down values given to the "Set Pedal Curve Limits" command below. V_hd may be less than V_td (normal signal) or larger than V_td (inverted signal), but not equal to V_td. In practice, they should differ by at least 32 units, otherwise the movement cannot be detected reliably.

The positions P_i are in range from 0 (heel down) to 255 (toe down), which map directly to CC values of 0 … 127. P₀ should be 0, P₃₂ is not transferred but assumed to be 255. The positions curve must be rising steadily (P_i < = P_i+1), independently of the relation between V_td and V_hd.

For digital ("sustain") pedals, positions P₀…P₁₆ may be 0 and P₁₇…P₃₂ equal to 255. In this case, the interval between P₁₆ and P₁₇ is not interpolated, but either 0 (between V_hd and V₁₆) or 127 (between V₁₆ and V_td) is sent as CC value.

The "Set Pedal Curve Limits" command sets V_td and V_hd for a certain pedal contact.

Set Pedal Curve Limits				ID	`0x31`
Command Arguments	x	pedal contact 0 = right jack, ring 1 = right jack, tip 2 = left jack, ring 3 = left jack, tip
	h (LSB)	lower 7 bits	heel down value V_hd (corresponds to MIDI value 0)
	h (MSB)	higher 5 bits
	t (LSB)	lower 7 bits	toe down value V_td (corresponds to MIDI value 127)
	t (MSB)	higher 5 bits
Example: `[F0 00 21 1D 01 01 31 01 00 19 58 04 F7]` = configure right jack tip contact curve as inverse to span values of 3200 to 600

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	`0x32`
Command Arguments	x	pedal contact 0 = right jack, ring 1 = right jack, tip 2 = left jack, ring 3 = left jack, tip
	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: `[F0 00 21 1D 01 01 32 00 04 1E 00 26 00 2D 00 32 00 F7]` = set curve indices 4 … 7 of right pedal ring contact to positions 30, 38, 45, 50

2.12. Display Backlight

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	`0x08`
Command Arguments	b (LSB)	lower 7 bits	brightness
	b (MSB)	higher 1 bit
Example: `[F0 00 21 1D 01 01 08 7F 01 F7]` = set display brightness to 255

Get Display Brightness				ID	`0x09`
Command Arguments	none
Reply Arguments	b (LSB)	lower 7 bits	brightness
	b (MSB)	higher 1 bit
Example: `[F0 00 21 1D 01 01 09 F7]` = get display brightness Reply: `[F0 00 21 1D 01 01 09 40 00 F7]` = display brightness is 64

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.

2.13. Device Inquiry

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.

Table 7. Device Inquiry Command

Message Data	Description
`0xF0`	SOX (start of sysex)
`0x7E`	Universal Non-Realtime Sysex ID
`0x01`	Device ID (may as well be `0x7F` for "all devices")
`0x06`	SubID1: General Information
`0x01`	SubID2: Identity Request
`0xF7`	EOX (end of sysex)
Example: `[F0 7E 01 06 01 F7]` = request identity

Push 2 will answer with the following message:

Table 8. Device Inquiry Reply

Message Data	Description
`0xF0`	SOX
`0x7E`	Universal Non-Realtime Sysex ID
`0x01`	Device ID
`0x06`	SubID1: General Information
`0x02`	SubID2: Identity Reply
`0x00 0x21 0x1D`	Manufacturers Sysex ID code
`0x67 0x32`	device family code, 2x7 bits, LSB first (Product ID from USB header)
`0x02 0x00`	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	software build
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)
`0xF7`	EOX
Example reply: `[F0 7E 01 06 02 00 21 1D 67 32 02 00 01 00 2F 00 73 4D 1F 08 00 01 F7]` = manufacturer 00 21 1D (Ableton), device family 0x1967 (Push), family member 2, version 1.0, build 47, serial number 17295091, board revision 1

2.14. Statistics

The "Request Statistics" sysex command provides some useful information about the Push 2 device.

Request Statistics				ID	`0x1A`
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: `[F0 00 21 1D 01 01 1A F7]` = request statistics Reply: `[F0 00 21 1D 01 01 1A 01 00 3F 07 00 00 00 F7]` = external power supply, run ID `0`, uptime 959 sec

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.

3. Display Interface

3.1. USB Display Interface Access

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 https://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:
// https://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);
}

3.2. Display Interface Protocol

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.

3.2.1. Frame Header

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 }

3.2.2. Pixel Data

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.

3.2.3. Pixel Color Encoding

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

3.2.4. XORing Pixel Data

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.

3.2.5. Frame Buffering

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.

3.2.6. Allocating Libusb Transfers

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);
}

4. Appendix A: MIDI Implementation Chart

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) Mode 2: Omni-On, Mono (Yes/No) Mode 3: Omni-Off, Poly (Yes/No) Mode 4: Omni-Off, Mono (Yes/No) Multi Mode (Yes/No)		No Yes No 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 Sample Dump Standard (Yes/No) Device Inquiry (Yes/No) File Dump (Yes/No) MIDI Tuning (Yes/No) Master Volume (Yes/No) Master Balance (Yes/No) Notation Information (Yes/No) Turn GM1 System On (Yes/No) Turn GM2 System On (Yes/No) Turn GM System Off (Yes/No) DLS-1 (Yes/No) File Reference (Yes/No) Controller Destination (Yes/No) Key-based Instrument Ctrl (Yes/No) Master Fine/Coarse Tune (Yes/No) Other Universal System Exclusive	--- No Yes No No No No No No No No No No No No No No	--- No Yes No No No No No No No No No No No No No No
Manufacturer System Exclusive	Yes	Yes	Manufacturer: Ableton, ID: 00H 21H 1DH
NRPNs (Yes/No)	No	No
RPN 00 (Pitch Bend Sensitivity) (Yes/No) RPN 01 (Channel Fine Tune) (Yes/No) RPN 02 (Channel Coarse Tune) (Yes/No) RPN 03 (Tuning Program Select) (Yes/No) RPN 04 (Tuning Bank Select) (Yes/No) RPN 05 (Modulation Depth Range) (Yes/No)	No No No No No No	No No No 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) Continue (Yes/No) Stop (Yes/No)	No No No	Yes Yes 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!