Python Examples¶

Sample Python code for controlling hardware and choreographing performances can be found in the Python examples folder. The Python examples may be downloaded individually or as a single archive as examples.zip.

These scripts use Python 3 with a few additional packages as described in System Requirements.

Brief descriptions of the examples:

• exercise1.py GUI interface for mapping events from MPD218 drum pad to winch commands.
• exercise3.py GUI interface for mapping events from local or remote MIDI sources to winch or simulator commands.
• exercise4.py GUI interface for mapping events from local or remote MIDI sources to winch or simulator commands.
• sim1.zip GUI performance simulator, documented in more detail on sim1.py simulation testbed. Uses the kf Python library.
• sim2.zip GUI performance simulator, documented in more detail on sim2.py simulation testbed. Uses the kf Python library.
• sim3.zip GUI performance simulator, documented in more detail on sim2.py simulation testbed. Uses the kf Python library.
• exercise5.zip GUI performance interface, forked from sim1.py simulation testbed. Uses the kf Python library.

Python Tools¶

Several utility and test programs can be found in the Python tools folder. The Python tools may be downloaded individually or as a single archive as tools.zip.

These are all standalone scripts using Python 3 and a few additional packages as described in System Requirements.

Brief descriptions of the tools:

• virtual_mpd218.py GUI simulator for the Akai MPD218 4x4 MIDI drum pad, intended for offline testing of drum pad user interfaces. Emits MIDI messages.
• winch_simulator.py GUI simulator for the capstan winches, intended for offline testing of choreography controllers. Receives commands encoded as OSC messages in UDP network packets.
• osc_button_box.py General-purpose button and slider GUI user interface. Emits OSC messages in UDP network packets.
• osc_display.py Test program for monitoring OSC stream, provides a GUI for receiving OSC UDP packets and printing all contents.
• midi_display.py Test program for monitoring MIDI stream, provides a GUI for connecting to a MIDI source and printing all messages.
• list_MIDI_ports.py Test program for checking MIDI status, provides a console-based output of MIDI ports available via python-rtmidi.
• dmx_controller.py Test program for lighting control, provides a GUI for directly connecting to a single Enttec DMXUSB Pro and manipulating output.
• midi_osc_bridge.py GUI utility for relaying MIDI from local source (e.g. IAC driver on macOS) over the network in an OSC UDP packet.

Running the Python Samples on an IDeATe macOS Laptop¶

The IDeATe MacBook Pro laptops have several different Python systems installed, so running the sample code requires a little care. The following example is based on the sim2.zip package; running other samples will be similar.

1. First, download the package (e.g. sim2.zip) to whatever location is convenient (e.g. Desktop or Downloads).
2. Double-clicking on the zip file under macOS will unpack it to a new folder named sim2.
3. Within the new sim2 folder is a sim2.py script file and a kf folder which contains the library modules.
4. Double-clicking on the sim2.py script will not run it, but will instead open it in some version of the IDLE Python editor.
5. Right-clicking or control-clicking on it will bring up a context menu. Within that menu is the Open With submenu. Please select Python Launcher (3.5.4).
6. The first launch will probably fail. Please bring up the Python Launcher application and open its Preferences pane. For Interpreter, please enter /opt/local/bin/python3.5. This is the specific interpreter which includes the libraries required by the course software.
7. Subsequent launches using Open With/Python Launcher should work.

The alternative approach is to launch the Terminal command line. E.g., if the package was unpacked on the Desktop, the following Terminal commands would launch sim2:

cd
cd Desktop/sim2
/opt/local/bin/python3.5 sim2.py

Currently, IDLE 3.5 is not working, but in the future we hope to make it possible to launch the sample code directly from the editor.

Arduino Sketches¶

The StepperWinch Arduino Sketch runs on the stepper-based capstan winch controller. Thes sketch controls four stepper motors as capstan drives for moving control lines. It receives control messages from an external source over a USB serial port. The protocol is event-driven with local filtering and motion smoothing, much like a MIDI instrument driven by note events.

Git Repositories¶

All course sample code and designs are also available via a private git repository stored on Andrew AFS. This is primarily intended for expert users and students contributing to the sample code, but you may request a project repository if desired.

To clone a repository, substitute your own Andrew ID into one of the following:

git clone AndrewID@unix.andrew.cmu.edu:/afs/andrew/course/16/376/s2019/tools
git clone AndrewID@unix.andrew.cmu.edu:/afs/andrew/course/16/376/s2019/examples
git clone AndrewID@unix.andrew.cmu.edu:/afs/andrew/course/16/376/s2019/StepperWinch