Fix #34: Add missing chapter references to command list

README.md

@@ -28,6 +28,7 @@ Please add an [issue](https://github.com/Ableton/push-interface/issues) with you
 * https://github.com/garrensmith/abletonpush
 * https://github.com/wookay/PushInterface.jl
 * https://github.com/ffont/push2-python
+* https://crates.io/crates/push2_display (Rust display driver)
 
   Please Note: The external links are being provided as a convenience and for informational purposes only. They do not constitute an endorsement or an approval by the Ableton of any of the linked contents. Ableton bears no responsibility for the accuracy, legality or
   the content of the referred site or for that of subsequent links.

doc/AbletonPush2MIDIDisplayInterface.asc

@@ -235,34 +235,34 @@ arguments are avoided.
 |===
 |Command ID|Sends Reply|Command Name|Chapter
 |+0x03+ | |Set LED Color Palette Entry .3+|<<RGB LED Color Processing>>
-|+0x04+ |yes|Get LED Color Palette Entry
-|+0x05+ | |Reapply Color Palette
+|+0x04+ |yes|Get LED Color Palette Entry |<<RGB LED Color Processing>>
+|+0x05+ | |Reapply Color Palette |<<RGB LED Color Processing>>
 |+0x06+ | |Set LED Brightness .2+|<<Global LED Brightness>>
-|+0x07+ |yes|Get LED Brightness
+|+0x07+ |yes|Get LED Brightness |<<Global LED Brightness>>
 |+0x08+ | |Set Display Brightness .2+|<<Display Backlight>>
-|+0x09+ | |Get Display Brightness
+|+0x09+ |yes|Get Display Brightness .2+|<<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 .2+|<<White Balance>>
-|+0x15+ |yes|Get LED White Balance
+|+0x15+ |yes|Get LED White Balance |<<White Balance>>
 |+0x17+ | |Set Touch Strip Configuration .3+|<<Touch Strip>>
-|+0x18+ |yes|Get Touch Strip Configuration
-|+0x19+ | |Set Touch Strip LEDs
+|+0x18+ |yes|Get Touch Strip Configuration |<<Touch Strip>>
+|+0x19+ | |Set Touch Strip LEDs |<<Touch Strip>>
 |+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 .2+|<<Aftertouch>>
-|+0x1F+ |yes|Get Aftertouch Mode
+|+0x1F+ |yes|Get Aftertouch Mode |<<Aftertouch>>
 |+0x20+ | |Set Pad Velocity Curve Entry .2+|<<Velocity Curve>>
-|+0x21+ |yes|Get Pad Velocity Curve Entry
+|+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 .2+|<<Pad Settings>>
-|+0x29+ |yes|Get Selected Pad Settings
+|+0x29+ |yes|Get Selected Pad Settings |<<Pad Settings>>
 |+0x30+ | |Configure Pedal .3+|<<Pedal Configuration>>
-|+0x31+ | |Set Pedal Curve Limits
-|+0x32+ | |Set Pedal Curve Entries
+|+0x31+ | |Set Pedal Curve Limits |<<Pedal Configuration>>
+|+0x32+ | |Set Pedal Curve Entries |<<Pedal Configuration>>
 |===
 
 
@@ -441,6 +441,29 @@ Reply: ++[F0 00 21 1D 01 01 **04 7D 00 00 00 00 7F 01 7E 00** F7]++ = entry 125
 6+|Example: ++[F0 00 21 1D 01 01 **05** F7]++ = trigger palette reapplication
 |===
 
+Converting RGB Values to Color Palette Indices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Push 2 LEDs do not accept direct RGB values. Colors must be specified using
+color palette indices (0-127). To convert an arbitrary RGB color to the closest
+available palette index:
+
+1. Retrieve the complete color palette by querying all 128 entries (0-127)
+   using the "Get LED Color Palette Entry" command (0x04).
+
+2. For each palette entry, calculate the distance between your target RGB
+   color and the palette entry's RGB values. Common distance metrics include:
+   - Euclidean distance in RGB space: sqrt((R1-R2)² + (G1-G2)² + (B1-B2)²)
+   - Perceptual color distance (e.g., using LAB color space) for better
+     visual matching
+
+3. Select the palette index with the minimum distance.
+
+Alternatively, you can modify the palette to add custom colors by using the
+"Set LED Color Palette Entry" command (0x03) to overwrite existing palette
+entries with your desired RGB values. After modifying palette entries, send
+the "Reapply Color Palette" command (0x05) to apply the changes.
+
 White LED Color Processing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -501,6 +524,12 @@ will be retained, most likely.
                 |7   |127         |white
 |===
 
+NOTE: The table above shows only a subset of the RGB color palette values.
+To retrieve the complete default RGB color palette (all 128 entries from index 0 to 127),
+use the "Get LED Color Palette Entry" sysex command (0x04) described in the
+<<RGB LED Color Processing>> chapter. Query each color index from 0 to 127 to
+obtain the full palette with RGB and white values for each entry.
+
 [id="White Balance"]
 White Balance
 ^^^^^^^^^^^^^
@@ -687,6 +716,11 @@ 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.
 
+NOTE: In User mode, MIDI system real time messages (start, stop, continue, clock)
+must be sent on Port 2, as Port 1 MIDI messages are ignored in User mode.
+If no MIDI start message has been received on the active port, animations
+may not run at the default 120 bpm tempo until a MIDI start message is sent.
+
 As usual with MIDI-over-USB interfaces, system real time
 messages should not be sent in the middle of other MIDI messages.