FTAP RELEASE NOTES: Version 2.1.07a

I'm calling this release as an "a" 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.

Feel free to send comments/questions/bug reports to the author (see the 
web page for contact info). 

Steve Finney, April, 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, miscellaneous code cleanups. 
        Late April, 2016.

