FTAP RELEASE NOTES: Version 2.1.07b I'm calling this release as an "b" version (less scary than calling it a "beta" version) because so far no one has run it except me. I'll be more confident after a few people (who are not me) report that they have successfully compiled and run this on their system, and have run the loop test and the supplied analysis script (see below). However, I don't anticipate any major problems or changes. 2.1.07b differs from 2.1.07a in that the increased limits on number of triggers have been fixed and tested more thoroughly. This includes code changes to tapmidi.h, lists.c, and ftap.c, small changes to the Reference Manual (see Section 4.7.2 if you plan to use more than about 500 time triggers), as well as parameter files for testing triggers in "params/test". Feel free to send comments/questions/bug reports to the author (see the web page for contact info). Steve Finney, July, 2016. Official FTAP web page: www.sfinney.com/ftap ---------------------------------------------------------------------- FTAP is a Linux-based, MIDI-based program for running tapping and music experiments, available in source code form under the GNU Public License Agreement. FTAP can process MIDI input and output data with millisecond accuracy and precision. If you're reading this, you hopefully already know why you're interested in it, so I will not convince you that you should be. See the included User's Guide and Reference manual for more details, and see the FTAP web page for additional information and the latest updates. You should not need to be a technical person to use FTAP, but you will need some basic Linux knowledge (e.g., what a shell script is). Find someone to help you if these release notes don't make sense to you. The 'bin' directory contains a 'ftap' binary which can be installed wherever you want it (your personal 'bin' directory for initial evaluation, perhaps "/usr/local/bin" later). There are no required auxiliary files. Evaluation and most testing can be done with normal user permissions on any Linux machine with a MIDI interface. However, to get reliable millisecond timing for actual data collection, FTAP should be run as setuid 'root' on a dedicated experimental machine; this allows SCHED_FIFO scheduling, memory locking, and sub-millisecond use of the "/dev/rtc". If you do not understand the security implications of this, see the Reference Manual and have a conversation with a knowledgeable Linux sysadmin. ---------------------------------------------------------------------------- DISTRIBUTION HIERARCHY: src/: FTAP sources (in C), and some shell scripts. bin/: Intel binary for FTAP compiled on my system. params/: A bunch of parameter files to demonstrate some of FTAP's capabilities, and to get you started. The "demo" subdirectory is probably the best place to start. The "benchmark" directory contains the loop test and some shell scripts. doc/: FFTAP documentation, both a User's Manual and a Reference Manual. These should be reasonably accurate and complete, but are a little rough. There is currently no man page. utils/: a directory containing subdirectories with potentially useful auxiliary C source (not all of which is currently being maintained or likely to work). See the README there. ----------------------------------------------------------------------------- CHANGES FROM 2.1.05 TO 2.1.06 (also included in 2.1.07) Add a SESSION parameter for designs in which the same subject performs in multiple sessions. This is now a component in the output file name, and also appears in the header of the output file. Add a few (now 5) FACTOR(N) parameters to allow documentation of the experimental conditions in the output file itself. Note that the values in the header of the ouput file may change on occasion (that is, new values may be added at arbitrary locations). If you write code to parse these values in the output file, make sure you do it by keyword (e.g., "SUB" or "FACTOR1", not by expected position in the file. Fixed a minor output ordering bug (see lists.c). Also: undocumented preliminary code to call a function on a trigger, with a PULSE example. CHANGES FROM 2.1.06 TO 2.1.07 Fix up the C file "#includes" so that FTAP will compile on a 2016 vintage system (Ubuntu 14.04 with gcc 4.8.4). Compilers were much more lax in 2001. Please let me know if additional changes are required on your particular system. Add a MIDIDEV parameter that allows override of the default "/dev/midi" access point. E.g., invoke as: ftap looptest "MIDIDEV /dev/midi2" Change RTC ("/dev/rtc") handling so that it is possible to run FTAP for evaluation purposes without root privileges. Create a more rigorous looptest. The "looptest_60s" runs for a minute, rather than the 4 seconds of the standard "looptest". There is also a "run_looptest.sh" shell script that executes "looptest_60s" ten times, and a shell script and Python program ("run_loopcheck.sh" and "loopcheck.py") to automatically analyze the output (mean, standard deviation, and max); the results are written to a file named "loopcheck.out". To run loopcheck.py, you will need the "numpy" package; on Ubuntu, this can be installed with the command "sudo apt-get install python-numpy". See the Reference manual "looptest" section for further details.. Change the number of FACTOR parameters from 6 to 5. The Proportional Delay (PPT) delay mode is now included by default. The applicable FEED_DMODE value has been changed from 50 to 4. Increase some limits in "ftaplimits.h": MAXNOTES from 15000 to 100000 (useful for the expanded looptest), MAX_TRIG_EVENTS from 60 to 5000 (apparently EEG work requires a large number), MAXPATTERN from 20 to 40 and MAX_TE_EVENTS from 2000 to 20000 (just because). Memory is less of a concern than it was in 2001. Some debug information has been added to the header of the output file: PERMISSIONS and BUILD_TIME. Various semi-gratuitous code cleanups that may confuse anyone doing a "diff". POSSIBLE FUTURE 2.1.08 RELEASE Add ability to output signals to the parallel port. Add additional delay and pitch feedback modes. Clean up and document the "call a function on a trigger" interface (the parallel port feature will be implemented using this). Other features will be considered. ---------------------------------------------------------------------- BETA TEST REQUEST Since I have only compiled and tested FTAP 2.1.07 on my own personal system (Ubuntu 14.04 Linux, gcc 4.8, on a quad-core Athlon, using various USB-MIDI interfaces), I don't want to declare this release ready for prime time until it has been compiled and tested on other systems. In particular, I am interested in the following. If you run into any issues performing these tests, please let me know. If it is not clear how to perform these tests, please let me know so that I can improve the documentation. If you run the tests successfully, please let me know (and tell me your configuration). 1. Compile the source (see below) 2. Run the expanded looptest ("run_looptest.sh" and "run_loopcheck.sh" in "params/benchmark") with your compiled version. Do this with root privileges. See the web page for information about currently available MIDI hardware interfaces that have passed (or failed) the looptest, and let me know what HW interface you used. 3. Verify that the supplied FTAP binary can be run on your system without root privileges (ideally using the MIDIDEV override). Thanks! ---------------------------------------------------------------------- COMPILATION The included binary should run on most Intel or AMD PC's, and should be sufficient for you to evaluate FTAP and write parameter files. If you are going to collect data with root privileges, I suggest you compile the source on your own system and verify the compiled binary with the looptest. This will verify that your binary matches the source code (which you can then look at if you want to). Running an unknown setuid binary is not generally a good idea. This is also partly for my benefit: I would like to know about problems compiling FTAP on other systems, e.g., include files, compilers, libraries. Currently, there is no makefile in the src directory. The "makeftap" shell script will compile ftap; commented out code will make it setuid root (you will need root privileges to do this). FTAP was not originally tested on 64 bit machines (FTAP running on a supercomputer!?! Ridiculous... :-) ), and has a bug if compiled as a 64-bit binary. It works fine compiled as a 32-bit binary, and the resulting binary should run fine on either 32- or 64-bit systems (let me know if you find an issue). 'makeftap.sh' passes '-m32' to gcc; you may also need to install some additional libraries if you're compiling on a 64-bit system. On my Ubuntu system, I had to do the following: sudo apt-get install gcc-multilib (Details: when compiled as 64-bit, no keystrokes are received when running the looptest. I saw something that suggested it was related to a time comparison: e.g., maybe an issue with int vs long types, maybe involving signed vs unsigned. If you find the 64-bit bug and will GPL your fix, please send it to me. I am not currently planning to spend time on it.) ---------------------------------------------------------------------- DEVICES (MIDI interface, Input, Output) Some MIDI hardware interfaces work better than others, and you should try to confirm that your MIDI input and output devices do not add significant latency. See the web page for the latest info. ---------------------------------------------------------------------- LINUX TECHNICAL DETAILS FTAP, having been originally written around 2001, uses the then-available (and still supported) OSS-style raw MIDI interface, rather than the current recommended ALSA API. In addition, it uses the hard-wired device name "/dev/midi", although on most ALSA systems the actual name will be something like "/dev/midi2". Setting up a symbolic link is a quick fix, though this may need to be redone on each reboot. Also, the dynamic device file system in contemporary Linux means that under some circumstances the name of the MIDI device can change. See the Reference Manual. The ideal situation would be a 'udev' entry that automatically set up the link, but I haven't taken the time to figure out how to do this. If you can tell me, I'd like to add it to the documentation. When invoking FTAP, I sometimes get a "/dev/midi: Device or resource busy" message with my USB-MIDI interface if I haven't used it for a few days. "http://tedfelix.com/linux/linux-midi.html" points at pulse-audio as the probable issue, and the following command sometimes will clean it up without a reboot. Sometimes I've had to reboot. If someone understands how to stop pulse-audio from respawing and opening the MIDI device, let me know. sudo echo "suspend 1" | pacmd ---------------------------------------------------------------------- RELEASE HISTORY:: 2.1.05: First important public release. 2001 or so. 2.1.06: A version that cleaned up some compilation problems, fixed a few issues, and added some minor features. These are described in the current release notes. 2.1.06 was considered a "beta" release, and did not include documentation updates. 2.1.06 was used as the basis for two different sets of parallel port modifications, not included here. 2004 or so. 2.1.07a: A clean-up release: compiles cleanly under Ubuntu 14.04 (compilers are pickier than they were 15 years ago!), documentation updated, added MIDIDEV parameter to allow easy override of the default "/dev/midi", add additional info to the header of the output file, increased some limits (total number of notes, number of triggers), miscellaneous code cleanups. Late April, 2016. 2.1.07b: Fix the increased (60->5000) trigger limits (some things didn't work right with more than 256 triggers). July, 2016.