Improve Python build, examples, and docs

bindings/CMakeLists.txt

@@ -11,13 +11,16 @@ option(PSMOVE_BUILD_CSHARP_BINDINGS "Build the C# bindings" ON)
 option(PSMOVE_BUILD_PROCESSING_BINDINGS "Build the Processing bindings" ON)
 option(PSMOVE_BUILD_PYTHON_BINDINGS "Build the Python bindings" ON)
 
+# useful if multiple versions of the Python lib are installed
+set(PSMOVE_PYTHON_VERSION "" CACHE STRING "Use this version of the Python lib for building Python bindings")
+
 # Language bindings (Python, Java and Processing)
 find_package(SWIG QUIET)
 if(SWIG_FOUND)
     include(${SWIG_USE_FILE})
 
     if(PSMOVE_BUILD_PYTHON_BINDINGS)
-        find_package(PythonLibs QUIET)
+        find_package(PythonLibs ${PSMOVE_PYTHON_VERSION} QUIET)
         if(PYTHONLIBS_FOUND)
             unset(CMAKE_SWIG_FLAGS)
             include_directories(${PYTHON_INCLUDE_PATH})

docs/build.rst

@@ -156,3 +156,52 @@ A kernel with hidraw will print something like the following::
 
 If your kernel does not have hidraw support, you should install the newest
 Firmware for your Pocket C.H.I.P, and make sure to install all updates via ``apt``.
+
+
+
+Python bindings
+---------------
+
+Python bindings (among others) are built using SWIG. So make sure you have
+that installed. CMake will let you know if SWIG could not be found in the
+initial configure step. Look in CMake's output in the section "Language
+bindings".
+
+Also required is the Python library (``libpython-dev`` on Linux). If you
+have multiple versions of Python installed (most likely some 2.x and 3.x)
+chances are CMake decides to use the wrong one. Again, look in CMake's
+output in the section "Language bindings" which version of the Python
+library CMake is using for the build. Make sure it matches the version you
+want to run your Python scripts with later. They must be the same!
+
+If CMake does not choose the correct version right away, use the option
+``PSMOVE_PYTHON_VERSION`` to set the desired one. Usually it is sufficient
+to set this to either 2 or 3 (for Python 2 and 3, respectively), but minor
+versions are also supported. So you could choose between building for
+Python 2.6 and 2.7. If you are running CMake from the command line set the
+version like so::
+
+    cmake .. -DPSMOVE_PYTHON_VERSION=2
+
+Check CMake's output to verify that the correct version is now found; some
+flavor of Python 2 in this example. If CMake still uses the wrong one, try
+removing all the files CMake generated in the ``build`` directory and run
+again.
+
+Testing the build
+~~~~~~~~~~~~~~~~~
+
+A lot of Python example scripts are provided in the ``examples/python/``
+directory. They are laid out so that when you build the library (and its
+Python bindings) in the customary ``build`` folder in the PSMove API
+checkout, the Python examples should find the modules without needing to
+install anything. We suggest you start with ``always.py`` which you can
+directly call from within the ``build`` directory like so::
+
+    python ../examples/python/always.py
+
+This script does not require Bluetooth and should thus provide an easy
+way to test the Python bindings. Simply connect your Move controller via
+USB and run the script as shown above. If that is working, continue with
+``pair.py`` to set everything up for using Bluetooth.
+

examples/python/always.py

@@ -37,6 +37,11 @@
 
 
 moves = [psmove.PSMove(x) for x in range(psmove.count_connected())]
+
+if not moves:
+    print('No controller connected');
+    sys.exit(1)
+
 for move in moves:
     move.set_leds(0, 150, 0)
 

examples/python/beat.py

@@ -44,9 +44,17 @@
 import math
 import psmove
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 move = psmove.PSMove()
 move.set_rate_limiting(1)
 
+if move.connection_type != psmove.Conn_Bluetooth:
+    print('Please connect controller via Bluetooth')
+    sys.exit(1)
+
 current_beat = 0
 old_buttons = 0
 last_blink = 0

examples/python/color_fade_multiple.py

@@ -38,6 +38,10 @@
 
 moves = [psmove.PSMove(x) for x in range(psmove.count_connected())]
 
+if not moves:
+    print('No controller connected');
+    sys.exit(1)
+
 colors = [
    (255, 0, 0),
    (0, 255, 0),

examples/python/cops.py

@@ -37,6 +37,10 @@
 
 move = psmove.PSMove()
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 i = 0
 while True:
     if i % 12 in (1, 3, 5):

examples/python/ep_whack.py

@@ -334,6 +334,10 @@ def draw(self, modelview_matrix, color):
         self.program.unbind()
 
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 tracker = psmove.PSMoveTracker()
 tracker.set_mirror(True)
 
@@ -346,6 +350,10 @@ def draw(self, modelview_matrix, color):
 move.enable_orientation(True)
 move.reset_orientation()
 
+if move.connection_type != psmove.Conn_Bluetooth:
+    print('Please connect controller via Bluetooth')
+    sys.exit(1)
+
 pygame.init()
 if '-f' not in sys.argv:
     surface = pygame.display.set_mode((640, 480), OPENGL | DOUBLEBUF)

examples/python/magnetometer_proximity_ngj.py

@@ -35,16 +35,24 @@
 import psmove
 import math
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 move = psmove.PSMove()
 
+if move.connection_type != psmove.Conn_Bluetooth:
+    print('Please connect controller via Bluetooth')
+    sys.exit(1)
+
 readings = []
 lastmeans = []
 NUM_READINGS = 50
 NUM_MEANS = 10
 
 def mean(readings):
     sums = list(map(sum, list(zip(*readings))))
-    return [sum/len(readings) for sum in sums]
+    return [s/len(readings) for s in sums]
 
 def calc_diffsums(lastmeans, currentmeans):
     cx, cy, cz = currentmeans

examples/python/nose_tests_runner.py

@@ -139,6 +139,10 @@ def run(self):
             time.sleep(2)
 
 if __name__ == '__main__':
+    if psmove.count_connected() < 1:
+        print('No controller connected')
+        sys.exit(1)
+
     visualizer = Visualizer()
     test_runner = TestRunner()
     glue = Glue(visualizer, test_runner)

examples/python/pair.py

@@ -34,6 +34,10 @@
 
 import psmove
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 move = psmove.PSMove()
 
 if move.connection_type == psmove.Conn_Bluetooth:

examples/python/psmove_test.py

@@ -35,6 +35,10 @@
 import psmove
 import time
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 move = psmove.PSMove()
 
 if move.connection_type == psmove.Conn_Bluetooth:
@@ -44,30 +48,36 @@
 else:
     print('unknown')
 
+if move.connection_type != psmove.Conn_Bluetooth:
+    print('Please connect controller via Bluetooth')
+    sys.exit(1)
+
 while True:
-    if move.poll():
-        trigger_value = move.get_trigger()
-        move.set_leds(trigger_value, 0, 0)
-        move.update_leds()
+    # Get the latest input report from the controller
+    while move.poll(): pass
+
+    trigger_value = move.get_trigger()
+    move.set_leds(trigger_value, 0, 0)
+    move.update_leds()
 
-        buttons = move.get_buttons()
-        if buttons & psmove.Btn_TRIANGLE:
-            print('triangle pressed')
-            move.set_rumble(trigger_value)
-        else:
-            move.set_rumble(0)
+    buttons = move.get_buttons()
+    if buttons & psmove.Btn_TRIANGLE:
+        print('triangle pressed')
+        move.set_rumble(trigger_value)
+    else:
+        move.set_rumble(0)
 
-        battery = move.get_battery()
-        if battery == psmove.Batt_CHARGING:
-            print('battery charging via USB')
-        elif battery >= psmove.Batt_MIN and battery <= psmove.Batt_MAX:
-            print('battery: %d / %d' % (battery, psmove.Batt_MAX))
-        else:
-            print('unknown battery value:', battery)
+    battery = move.get_battery()
+    if battery == psmove.Batt_CHARGING:
+        print('battery charging via USB')
+    elif battery >= psmove.Batt_MIN and battery <= psmove.Batt_MAX:
+        print('battery: %d / %d' % (battery, psmove.Batt_MAX))
+    else:
+        print('unknown battery value:', battery)
 
-        print('accel:', (move.ax, move.ay, move.az))
-        print('gyro:', (move.gx, move.gy, move.gz))
-        print('magnetometer:', (move.mx, move.my, move.mz))
+    print('accel:', (move.ax, move.ay, move.az))
+    print('gyro:', (move.gx, move.gy, move.gz))
+    print('magnetometer:', (move.mx, move.my, move.mz))
 
     time.sleep(.1)
 

examples/python/red_green.py

@@ -36,6 +36,10 @@
 import math
 import psmove
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 move = psmove.PSMove()
 
 i = 0

examples/python/red_green_multiple.py

@@ -38,6 +38,10 @@
 
 moves = [psmove.PSMove(x) for x in range(psmove.count_connected())]
 
+if not moves:
+    print('No controller connected');
+    sys.exit(1)
+
 i = 0
 while True:
     r = int(128+128*math.sin(i))

examples/python/test_calibration.py

@@ -34,8 +34,16 @@
 
 import psmove
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 move = psmove.PSMove()
 
+if move.connection_type != psmove.Conn_Bluetooth:
+    print('Please connect controller via Bluetooth')
+    sys.exit(1)
+
 assert move.has_calibration()
 
 while True:

examples/python/test_distance.py

@@ -34,6 +34,10 @@
 
 import psmove
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 move = psmove.PSMove()
 tracker = psmove.PSMoveTracker()
 

examples/python/test_exposure.py

@@ -35,7 +35,16 @@
 import psmove
 import time
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 move = psmove.PSMove()
+
+if move.connection_type != psmove.Conn_Bluetooth:
+    print('Please connect controller via Bluetooth')
+    sys.exit(1)
+
 tracker = psmove.PSMoveTracker()
 
 while tracker.enable(move) != psmove.Tracker_CALIBRATED:

examples/python/test_fusion_pygame.py

@@ -39,6 +39,10 @@
 from OpenGL.GLUT import *
 import psmove
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 glutInit(sys.argv)
 
 tracker = psmove.PSMoveTracker()
@@ -55,6 +59,10 @@ def load_matrix(mode, matrix):
 move.enable_orientation(True)
 move.reset_orientation()
 
+if move.connection_type != psmove.Conn_Bluetooth:
+    print('Please connect controller via Bluetooth')
+    sys.exit(1)
+
 while tracker.enable(move) != psmove.Tracker_CALIBRATED:
     pass
 

examples/python/test_tracker.py

@@ -34,9 +34,17 @@
 
 import psmove
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 tracker = psmove.PSMoveTracker()
 move = psmove.PSMove()
 
+if move.connection_type != psmove.Conn_Bluetooth:
+    print('Please connect controller via Bluetooth')
+    sys.exit(1)
+
 # Mirror the camera image
 tracker.set_mirror(True)
 

examples/python/tracker_image_pygame.py

@@ -36,10 +36,18 @@
 import pygame
 import time
 
+if psmove.count_connected() < 1:
+    print('No controller connected')
+    sys.exit(1)
+
 tracker = psmove.PSMoveTracker()
 
 move = psmove.PSMove()
 
+if move.connection_type != psmove.Conn_Bluetooth:
+    print('Please connect controller via Bluetooth')
+    sys.exit(1)
+
 # Calibrate the controller with the tracker
 result = -1
 while result != psmove.Tracker_CALIBRATED: