Struct launchy::launchpad_mk2::Output

pub struct Output { /* private fields */ }

The object handling any messages to the launchpad. To get started, initialize with [(Output::guess)OutputDevice::guess] and then send messages to your liking. The connection to the launchpad will get closed when this object goes out of scope.

For example:

let mut output = Output::guess()?;

output.light_all(PaletteColor::BLACK); // clear screen

// make a red cross in the center
output.light_row(4, PaletteColor::RED);
output.light_row(5, PaletteColor::RED);
output.light_column(4, PaletteColor::RED);
output.light_column(5, PaletteColor::RED);

// light top left button magenta
output.light(Button::GridButton { x: 0, y: 0 }, PaletteColor::MAGENTA);

Representing color

The Launchpad Mk2 has two different ways to represent color. You can either use one of the 128 built-in palette colors, or you can create a custom color with custom rgb components. Why would you choose the palette colors when you can just create your required colors yourself? Well some operations on the Mk2 only support palette colors. Besides, sending palette color midi messages is simply faster. Therefore you should aim to use the palette colors when possible.

Implementations

impl Output

pub fn test_api(&mut self) -> Result<(), MidiError>

This is a function testing various parts of this API by executing various commands in order to find issues either in this library or in your device

pub fn set_button( &mut self, button: Button, color: PaletteColor, light_mode: LightMode ) -> Result<(), MidiError>

Set a button to a certain color with a certain light_mode.

For example to start a yellow pulse on the leftmost control button:

let button = Button::ControlButton { index: 0 };
let color = PaletteColor::YELLOW;
let light_mode = LightMode::Pulse;
output.set_button(button, color, light_mode)?;

pub fn set_buttons( &mut self, buttons: impl IntoIterator<Item = impl Borrow<(Button, PaletteColor)>>, light_mode: LightMode ) -> Result<(), MidiError>

Like set_button(), but for multiple buttons. This method lights multiple buttons with varying color. The light mode can’t be varied between buttons.

For example to start a yellow flash on the leftmost control button and a red flash on the button to the right:

output.set_buttons(&[
    (Button::ControlButton { index: 0 }, PaletteColor::YELLOW),
    (Button::ControlButton { index: 1 }, PaletteColor::RED),
], LightMode::Flash)?;

pub fn light_multiple_rgb<I, T>(&mut self, buttons: I) -> Result<(), MidiError>where I: IntoIterator<Item = T>, T: Borrow<(Button, RgbColor)>, I::IntoIter: ExactSizeIterator,

Light multiple buttons with varying color. This method support RGB.

For example to light the top left button green and the top right button red:

output.light_multiple_rgb(&[
    (Button::GridButton { x: 0, y: 0 }, RgbColor::new(0, 0, 63)),
    (Button::GridButton { x: 7, y: 0 }, RgbColor::new(63, 0, 0)),
])?;

pub fn light_columns( &mut self, buttons: impl IntoIterator<Item = impl Borrow<(u8, PaletteColor)>> ) -> Result<(), MidiError>

Light multiple columns with varying colors. This method does not light up the control buttons

For example to light the first column yellow and the second column blue:

output.light_columns(&[
    (0, PaletteColor::YELLOW),
    (1, PaletteColor::BLUE),
])?;

pub fn light_rows( &mut self, buttons: impl IntoIterator<Item = impl Borrow<(u8, PaletteColor)>> ) -> Result<(), MidiError>

Light multiple row with varying colors. This method does light up the side buttons.

Note: the row are counted starting at the control row! For example to light the control row magenta and the first grid row green:

output.light_rows(&[
    (0, PaletteColor::MAGENTA),
    (1, PaletteColor::GREEN),
])?;

pub fn light_all(&mut self, color: PaletteColor) -> Result<(), MidiError>

Light all buttons, including control and side buttons.

For example to clear the screen:

output.light_all(PaletteColor::BLACK)?;

pub fn send_clock_tick(&mut self) -> Result<(), MidiError>

By default, Launchpad MK2 will flash and pulse at 120 BPM. This can be altered by sending these clock ticks by calling send_clock_tick(). These ticks should be sent at a rate of 24 per beat.

To set a tempo of 100 BPM, 2400 clock ticks should be sent each minute, or with a time interval of 25ms.

Launchpad MK2 supports tempos between 40 and 240 BPM, faster clock ticks are apparently ignored.

For example to send clock ticks at 200 BPM:

let beats_per_minute = 200;
let clock_ticks_per_second = beats_per_minute * 60 * 24;
let clock_tick_interval = std::time::Duration::from_millis(1000 / clock_ticks_per_second);
loop {
    output.send_clock_tick()?;
    std::thread::sleep(clock_tick_interval);
}

pub fn request_device_inquiry( &mut self, query: DeviceIdQuery ) -> Result<(), MidiError>

Requests the Launchpad Mk2 to send a so-called device inquiry. The device inquiry contains information about the device ID and the firmware revision number.

In order to be able to receive the Launchpad Mk2’s response to this request, you must have a Launchpad Mk2 input object set up.

pub fn request_version_inquiry(&mut self) -> Result<(), MidiError>

Requests the Launchpad Mk2 to send a so-called version inquiry. The version inquiry contains information about the current bootloader and firmware versions, as well as the size of the bootloader in KB.

In order to be able to receive the Launchpad Mk2’s response to this request, you must have a Launchpad Mk2 input object set up.

pub fn scroll_text( &mut self, text: &[u8], color: PaletteColor, should_loop: bool ) -> Result<(), MidiError>

Starts a text scroll across the screen. The screen is temporarily cleared. You can specify the color of the text and whether the text should loop indefinitely.

In addition to the standard ASCII characters, Launchpad MK2 recognises plain values 1 – 7 as speed commands (where 1 is the slowest and 7 is fastest). This allows the scrolling speed to be manipulated mid-text. The default speed is 4.

When the text ends, Launchpad MK2 restores the LEDs to their previous settings. As the text either ends or loops, a message will be sent to the Input.

For example to scroll the text “Hello, world!” in blue; “Hello” scrolling slow and “world” fast:

output.scroll_text(b"\x01Hello, \x07world!", PaletteColor::BLUE, false)?;

pub fn enter_fader_mode( self, fader_type: FaderType ) -> Result<FaderMode, MidiError>

Transforms this Output object to go into “fader mode”. In fader mode, you have the ability to utilize the Mk2’s built-in fader functionality.

Launchpad MK2 has two virtual fader modes, one with volume style faders and one with pan style (the two styles cannot be mixed).

The fader will light up according to its current value with volume faders lighting from the bottom up, and pan faders lighting from the centre out.

When a button is pressed to change the level of a fader, Launchpad MK2 will move the fader to that position and send interim values to smooth the transition. For each interim value, a message is sent to Input.

See FaderMode for documentation on FaderMode’s methods.

For example to place three pan faders:

• A green one on the left, turned all the way down
• Another green one next to the first fader, turned all the way up
• A white one on the right, centered

let mut fader_setup = output.enter_fader_mode(FaderType::Volume)?;

fader_setup.designate_faders(&[
    Fader::new(0, PaletteColor::GREEN, 0),
    Fader::new(1, PaletteColor::GREEN, 127),
    Fader::new(7, PaletteColor::WHITE, 63),
])?;

let mut output = fader_setup.exit()?;

pub fn enter_bootloader(&mut self) -> Result<(), MidiError>

Force the Launchpad MK2 into bootloader mode

pub fn light( &mut self, button: Button, color: PaletteColor ) -> Result<(), MidiError>

Light a button with a color from the Mk2 palette. Identical to set_button(<button>, <color>, LightMode::Plain).

For example to light the “Volume” side button cyan:

output.light(Button::VOLUME, PaletteColor::CYAN)?;

pub fn flash( &mut self, button: Button, color: PaletteColor ) -> Result<(), MidiError>

Starts a flashing motion between the previously shown color on this button and palette color color, with a duty cycle of 50% and a bpm of 120. The bpm can be controlled using send_clock_tick().

Identical to set_button(<button>, <color>, LightMode::FLASH).

For example to start a red flash on the “Session” button at the top:

output.flash(Button::UP, PaletteColor::RED)?;

pub fn pulse( &mut self, button: Button, color: PaletteColor ) -> Result<(), MidiError>

Start a pulse; a rhythmic increase and decreases in brightness. The speed can be controlled using send_clock_tick(). Identical to set_button(<button>, <color>, LightMode::PULSE).

For example to start a magenta pulse on the top right grid button:

output.pulse(Button::GridButton { x: 7, y: 0 }, PaletteColor::MAGENTA)?;

pub fn light_column( &mut self, column: u8, color: PaletteColor ) -> Result<(), MidiError>

Light a single column, specified by column (0-8).

For example to light the entire side button column white:

output.light_column(8, PaletteColor::WHITE)?;

pub fn light_row( &mut self, row: u8, color: PaletteColor ) -> Result<(), MidiError>

Light a single row, specified by row (0-8). Note: the row counting begins at the control row! So e.g. when you want to light the first grid row, pass 1 not 0.

For example to light the first grid row green:

output.light_row(1, PaletteColor::GREEN)?;

pub fn light_rgb( &mut self, button: Button, color: RgbColor ) -> Result<(), MidiError>

Light a single button with an RGB color.

For example to light the bottom right button cyan:

output.light_rgb(Button::GridButton { x: 7, y: 7 }, RgbColor::new(0, 63, 63))?;

pub fn light_multiple( &mut self, buttons: impl IntoIterator<Item = impl Borrow<(Button, PaletteColor)>> ) -> Result<(), MidiError>

Light multiple buttons with varying colors. Identical to set_buttons(<pairs>, LightMode::Plain)

For example to light both User 1 and User 2 buttons orange:

output.light_multiple(&[
    (Button::USER_1, PaletteColor::new(9)),
    (Button::USER_2, PaletteColor::new(9)),
])?;

pub fn flash_multiple( &mut self, buttons: impl IntoIterator<Item = impl Borrow<(Button, PaletteColor)>> ) -> Result<(), MidiError>

Start flashing multiple buttons with varying colors. Identical to set_buttons(<pairs>, LightMode::Flash)

For example to flash both User 1 and User 2 buttons orange:

output.flash_multiple(&[
    (Button::USER_1, PaletteColor::new(9)),
    (Button::USER_2, PaletteColor::new(9)),
])?;

pub fn pulse_multiple( &mut self, buttons: impl IntoIterator<Item = impl Borrow<(Button, PaletteColor)>> ) -> Result<(), MidiError>

Start pulsing multiple buttons with varying colors. Identical to set_buttons(<pairs>, LightMode::Pulse)

For example to pulse both User 1 and User 2 buttons orange:

output.pulse_multiple(&[
    (Button::USER_1, PaletteColor::new(9)),
    (Button::USER_2, PaletteColor::new(9)),
])?;

pub fn clear(&mut self) -> Result<(), MidiError>

Clears the entire field of buttons. Equivalent to output.light_all(PaletteColor::BLACK).

Trait Implementations

impl OutputDevice for Output

const MIDI_CONNECTION_NAME: &'static str = "Launchy Mk2 output"

const MIDI_DEVICE_KEYWORD: &'static str = "Launchpad MK2"

fn from_connection(connection: MidiOutputConnection) -> Result<Self, MidiError>

Initiate from an existing midir connection.

fn send(&mut self, bytes: &[u8]) -> Result<(), MidiError>

fn guess() -> Result<Self, MidiError>