Permalink
Switch branches/tags
Nothing to show
Find file Copy path
75fd228 Jan 26, 2017
1 contributor

Users who have contributed to this file

2129 lines (1808 sloc) 77.5 KB

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

© 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

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.

USB Link Overview
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:

UserPortInPrefs
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

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.

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.

MidiMapping
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

0x08

Set Display Brightness

Display Backlight

0x09

Get Display Brightness

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

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

0x20

Set Pad Velocity Curve Entry

Velocity Curve

0x21

yes

Get Pad Velocity Curve Entry

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

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 white

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:

  1. the color index for the addressed LED, as received by MIDI, is saved for later reapplication of color palette and brightness

  2. the color index (0…​127) is translated into 8 bit red/green/blue values using the color palette

  3. 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
RGB LED Processing
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

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

White LED Processing
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.

TS LED Processing
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.

LED Animation
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

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: [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

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: [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

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: [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

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: [F0 00 21 1D 01 01 13 09 F7] = sample pedal data for 512 samples (29, 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 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

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 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: [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

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

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