Fix #35: Clarify palette modification persistence

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

@@ -240,7 +240,7 @@ arguments are avoided.
 |+0x06+ | |Set LED Brightness .2+|<<Global LED Brightness>>
 |+0x07+ |yes|Get LED Brightness
 |+0x08+ | |Set Display Brightness .2+|<<Display Backlight>>
-|+0x09+ | |Get Display Brightness
+|+0x09+ |yes|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>>
@@ -441,6 +441,34 @@ 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.
+
+NOTE: Palette modifications made using "Set LED Color Palette Entry" are
+temporary and are reset to default values on device reboot. Unlike white
+balance settings, there is no command to persistently save palette
+modifications to flash memory.
+
 White LED Color Processing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -501,6 +529,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 +721,9 @@ 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.
+
 As usual with MIDI-over-USB interfaces, system real time
 messages should not be sent in the middle of other MIDI messages.