Improve touchstrip support, other minor fixes

Author: ffont

README.md

@@ -5,10 +5,12 @@ Utils to interface with [Ableton's Push 2](https://www.ableton.com/en/push/) fro
 These utils follow Ableton's [Push 2 MIDI and Display Interface Manual](https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc) for comunicating with Push 2. I recommend reading Ableton's manual before using this tool.
 
 So far I only implemented some utils to **interface with the display** and some utils for **interaction with pads, buttons, encoders and the touchstrip**. More detailed interaction with each of these elements (e.g. changing color palettes, support for led blinking, advanced touchstrip configuration, etc.) has not been implemented. Contributions are welcome :)
-*EDIT*: customization of color palettes and led animations is now implemented!
+**UPDATE**: customization of color palettes and led animations is now implemented!
 
 I only testd the package in **Python 3** and **macOS**. Some things will not work on Python 2 but it should be easy to port. I don't know how it will work on Windows/Linux. ~~It is possible that MIDI port names (see [push2_python/constants.py](https://github.com/ffont/push2-python/blob/master/push2_python/constants.py#L12-L13)) need to be changed to correctly reach Push2 in Windows/Linux~~. **UPDATE**: MIDI port names should now be cross-platform, but I have not tested them on Linux/Windows.
 
+Code examples are shown at the end of this readme file. For an example of a full application that I built using `push2-python` and that allows you to turn your Push2 into a standalone MIDI controller (using a Rapsberry Pi!), check the [Pysha](https://github.com/ffont/pysha) source source code repository.
+
 
 ## Table of Contents
 
@@ -83,7 +85,7 @@ MIDI configuration calls happen in the same thread because of limitations of the
 
 ### Setting action handlers for buttons, encoders, pads and the touchstrip
 
-You can easily set action handlers that will trigger functions when the physical pads, buttons, encoders or the touchtrip are used. You do that by **decorating functions** that will be triggered in response to the physical actions. For example, you can set up an action handler that will be triggered when
+You can easily set action handlers that will trigger functions when the physical pads, buttons, encoders or the touchstrip are used. You do that by **decorating functions** that will be triggered in response to the physical actions. For example, you can set up an action handler that will be triggered when
 the left-most encoder is rotated in this way:
 
 ```python

push2_python/__init__.py

@@ -37,7 +37,7 @@ class Push2(object):
     pads = None
     buttons = None
     encoders = None
-    touchtrip = None
+    touchstrip = None
     use_user_midi_port = False
     last_active_sensing_received = None
     function_call_interval_limit_overwrite = PUSH2_RECONNECT_INTERVAL
@@ -64,7 +64,7 @@ def __init__(self, use_user_midi_port=False):
         self.pads = Push2Pads(self)
         self.buttons = Push2Buttons(self)
         self.encoders = Push2Encoders(self)
-        self.touchtrip = Push2TouchStrip(self)
+        self.touchstrip = Push2TouchStrip(self)
 
         # Initialize MIDI IN connection with push
         self.configure_midi(skip_midi_out=True)
@@ -219,7 +219,7 @@ def on_midi_message(self, message):
                 # are not interested in (probably some internal state which Ableton uses but we don't care about?)
 
                 # Send received message to each "part" so it is processes accordingly
-                for func in [self.pads.on_midi_message, self.buttons.on_midi_message, self.encoders.on_midi_message, self.touchtrip.on_midi_message]:
+                for func in [self.pads.on_midi_message, self.buttons.on_midi_message, self.encoders.on_midi_message, self.touchstrip.on_midi_message]:
                     action_taken = func(message)
                     if action_taken:
                         break  # Early return from for loop to avoid running unnecessary checks
@@ -447,7 +447,13 @@ def function(push):
 
 
 def on_touchstrip():
-    """Shortcut for registering handlers for ACTION_TOUCHSTRIP_TOUCHED events.
+    """Shortcut for registering handlers for ACTION_TOUCHSTRIP_TOUCHED events. Push2's 
+    touchstrip can be configured to work eithher as a pitch bend "wheel" (the default)
+    or as a modualtion "wheel". When configured as pitch bend, the touchstrip values received
+    in this method (see below) will correspond to pitch bend values [-8192, 8128]. If configured as
+    modulation wheel, this function will receive the value of the modulation [0, 127]. Both
+    modes can be configured by calling "set_modulation_wheel_mode" or "set_pitch_bend_mode" methods
+    in Push2.touchstrip.
     Functions decorated with this decorator will be called with the following positional
     arguments:
         * Push2 object instance

push2_python/constants.py

@@ -64,7 +64,7 @@ def is_push_midi_out_port_name(port_name, use_user_port=False):
 MIDO_NOTEOFF = 'note_off'
 MIDO_POLYAT = 'polytouch'
 MIDO_AFTERTOUCH = 'aftertouch'
-MIDI_PITCWHEEL = 'pitchwheel'
+MIDO_PITCWHEEL = 'pitchwheel'
 MIDO_CONTROLCHANGE = 'control_change'
 
 PUSH2_SYSEX_PREFACE_BYTES = [0xF0, 0x00, 0x21, 0x1D, 0x01, 0x01]

push2_python/touchstrip.py

@@ -1,6 +1,6 @@
 import mido
 import weakref
-from .constants import MIDI_PITCWHEEL, ACTION_TOUCHSTRIP_TOUCHED
+from .constants import MIDO_PITCWHEEL, MIDO_CONTROLCHANGE, ACTION_TOUCHSTRIP_TOUCHED, PUSH2_SYSEX_PREFACE_BYTES, PUSH2_SYSEX_END_BYTES
 from .classes import AbstractPush2Section
 
 
@@ -9,8 +9,26 @@ class Push2TouchStrip(AbstractPush2Section):
     See https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc#Touch%20Strip
     """
 
+    def set_modulation_wheel_mode(self):
+        """Configure touchstrip to act as a modulation wheel
+        See https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc#2101-touch-strip-configuration
+        """
+        msg = mido.Message.from_bytes(PUSH2_SYSEX_PREFACE_BYTES + [0x17, 0x0C] + PUSH2_SYSEX_END_BYTES)
+        self.push.send_midi_to_push(msg)
+
+    def set_pitch_bend_mode(self):
+        """Configure touchstrip to act as a pitch bend wheel (this is the default)
+        See https://github.com/Ableton/push-interface/blob/master/doc/AbletonPush2MIDIDisplayInterface.asc#2101-touch-strip-configuration
+        """
+        msg = mido.Message.from_bytes(PUSH2_SYSEX_PREFACE_BYTES + [0x17, 0x68] + PUSH2_SYSEX_END_BYTES)
+        self.push.send_midi_to_push(msg)
+
     def on_midi_message(self, message):
-        if message.type == MIDI_PITCWHEEL:
+        if message.type == MIDO_PITCWHEEL:
             value = message.pitch
             self.push.trigger_action(ACTION_TOUCHSTRIP_TOUCHED, value)
             return True
+        elif message.type == MIDO_CONTROLCHANGE:
+            value = message.value
+            self.push.trigger_action(ACTION_TOUCHSTRIP_TOUCHED, value)
+            return True

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 setup(name='push2-python',
-      version='0.3',
+      version='0.4',
       description='Utils to interface with Ableton\'s Push 2 from Python',
       url='https://github.com/ffont/push2-python',
       author='Frederic Font',