From 93c5d5885c86aa23e0bf9cc18df261128dfbc9aa Mon Sep 17 00:00:00 2001 From: Benjamin Klum Date: Mon, 4 Nov 2024 10:47:12 +0100 Subject: [PATCH] #1301 Add basic Stream Deck docs --- .../modules/ROOT/pages/installation.adoc | 2 + doc/realearn/modules/ROOT/nav.adoc | 1 + .../ROOT/pages/sources/stream-deck.adoc | 67 +++++++++++++++++++ .../main-panel/input-output-section.adoc | 17 ++++- main/src/domain/stream_deck_device.rs | 2 +- 5 files changed, 85 insertions(+), 4 deletions(-) create mode 100644 doc/realearn/modules/ROOT/pages/sources/stream-deck.adoc diff --git a/doc/helgobox/modules/ROOT/pages/installation.adoc b/doc/helgobox/modules/ROOT/pages/installation.adoc index 4127fe129..6c6bdb715 100644 --- a/doc/helgobox/modules/ROOT/pages/installation.adoc +++ b/doc/helgobox/modules/ROOT/pages/installation.adoc @@ -47,6 +47,8 @@ sudo apt-get install -y libxdo-dev sudo zypper install xdotool ---- +IMPORTANT: If you want to use ReaLearn with the Stream Deck on Linux, xref:realearn::sources/stream-deck.adoc#linux[more setup] is necessary. + == Installing Helgobox Please choose: diff --git a/doc/realearn/modules/ROOT/nav.adoc b/doc/realearn/modules/ROOT/nav.adoc index 3c54e6407..95f39b48a 100644 --- a/doc/realearn/modules/ROOT/nav.adoc +++ b/doc/realearn/modules/ROOT/nav.adoc @@ -38,6 +38,7 @@ *** xref:sources/midi/display.adoc[] *** xref:sources/midi/specific-program-change.adoc[] ** xref:sources/osc.adoc[] +** xref:sources/stream-deck.adoc[] ** xref:sources/keyboard.adoc[] ** xref:sources/reaper.adoc[] *** xref:sources/reaper/midi-device-changes.adoc[] diff --git a/doc/realearn/modules/ROOT/pages/sources/stream-deck.adoc b/doc/realearn/modules/ROOT/pages/sources/stream-deck.adoc new file mode 100644 index 000000000..66c3ebc88 --- /dev/null +++ b/doc/realearn/modules/ROOT/pages/sources/stream-deck.adoc @@ -0,0 +1,67 @@ += Source "Stream Deck" + +With this source, you can leverage your Stream Deck with ReaLearn, for example the link:https://www.elgato.com/en/en/p/stream-deck-mk2-black[Elgato Stream Deck MK.2]. This includes reacting to buttons and sending xref:key-concepts.adoc#feedback[] to the button displays. + +== Supported devices + +The following StreamDeck devices are currently supported: + +* Original +* Original v2 +* Mini +* Revised Mini +* XL +* MK.2 + +[[linux]] +== Enabling Stream Deck support on Linux + +If you use Stream Deck on Linux, you also need to explicitly allow normal users access to the device, otherwise ReaLearn won't be able to connect to it. + +=== 1. Find the Vendor and Product ID + +Plug in the Stream Deck and identify its vendor and product IDs: + +[source,bash] +---- +lsusb +---- + +Look for a line similar to: + +`Bus 001 Device 002: ID 0fd9:006d Elgato Systems GmbH` + +In this example, `0fd9` is the vendor ID, and `006d` is the product ID (these may vary). + +=== 2. Create a udev Rule + +Create a new udev rule file in `/etc/udev/rules.d/`: + +[source,bash] +---- +sudo nano /etc/udev/rules.d/99-streamdeck.rules +---- + +Add the following rule, replacing `0fd9` and `006d` with the correct vendor and product IDs if necessary: + +[source] +---- +SUBSYSTEM=="usb", ATTR{idVendor}=="0fd9", ATTR{idProduct}=="006d", MODE="0660", GROUP="plugdev" +KERNEL=="hidraw*", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006d", MODE="0660", GROUP="plugdev" +---- + +This rule sets permissions to `0660`, allowing the device owner and users in the `plugdev` group access to the device with the specified vendor and product IDs. + +=== 3. Reload udev Rules + +Reload the udev rules to apply changes: + +[source,bash] +---- +sudo udevadm control --reload-rules +---- + +=== 4. Unplug and Replug the Device + +Unplug the Stream Deck and plug it back in to apply the new rule. +Alternatively, you can execute `sudo udevadm trigger`. diff --git a/doc/realearn/modules/ROOT/pages/user-interface/main-panel/input-output-section.adoc b/doc/realearn/modules/ROOT/pages/user-interface/main-panel/input-output-section.adoc index 910d1dbf0..38bd3bd7a 100644 --- a/doc/realearn/modules/ROOT/pages/user-interface/main-panel/input-output-section.adoc +++ b/doc/realearn/modules/ROOT/pages/user-interface/main-panel/input-output-section.adoc @@ -61,9 +61,20 @@ Can deal with bundles:::: By default, ReaLearn aggregates multiple OSC messages Some devices (e.g. from Behringer) can't deal with OSC bundles. Untick the checkbox in this case and ReaLearn will send single OSC messages. +Stream Deck: :: +Disables Stream Deck control. + +Stream Deck: _Some device_:: +When selected, this ReaLearn instance will _additionally_ listen to button presses of the chosen Stream Deck device. See xref:sources/stream-deck.adoc[] for details. ++ +Unlike MIDI or OSC, choosing a Stream Deck device automatically enables feedback to the Stream Deck buttons, so you won't find a Stream Deck entry in the <>. + +_Unavailable Stream Deck devices_:: +This submenu contains supported Stream Deck devices that are currently not connected. + [[computer-keyboard]] Computer keyboard:: -This is a checkbox. -If enabled, this ReaLearn instance will additionally listen to key press and release events. + +If enabled, this ReaLearn instance will _additionally_ listen to key press and release events. [#output] == Output menu @@ -71,7 +82,7 @@ If enabled, this ReaLearn instance will additionally listen to key press and rel Here you can choose to which xref:key-concepts.adoc#output-port[] ReaLearn should send MIDI/OSC xref:key-concepts.adoc#feedback[]. :: -This means, no feedback will be sent at all. +This means, ReaLearn won't send any feedback to MIDI or OSC devices. This is the default. [[fx-output]] MIDI: :: diff --git a/main/src/domain/stream_deck_device.rs b/main/src/domain/stream_deck_device.rs index 3a5a8b336..c57e6a87a 100644 --- a/main/src/domain/stream_deck_device.rs +++ b/main/src/domain/stream_deck_device.rs @@ -47,7 +47,7 @@ const ELGATO_VENDOR_ID: u16 = 0x0fd9; const SUPPORTED_DEVICES: &[StreamDeckDevice] = &[ StreamDeckDevice::new(ELGATO_VENDOR_ID, pids::ORIGINAL, "Original"), - StreamDeckDevice::new(ELGATO_VENDOR_ID, pids::ORIGINAL_V2, "Original V2"), + StreamDeckDevice::new(ELGATO_VENDOR_ID, pids::ORIGINAL_V2, "Original v2"), StreamDeckDevice::new(ELGATO_VENDOR_ID, pids::MINI, "Mini"), StreamDeckDevice::new(ELGATO_VENDOR_ID, pids::XL, "XL"), StreamDeckDevice::new(ELGATO_VENDOR_ID, pids::MK2, "MK2"),