batonImprov Environment

---

batonImprov is an environment which handles MIDI input/output between the computer and Max Mathews' Radio Batons, as well as MIDI output to a synthesizer. Example uses of the environment are given in the batonImprov examples directory. There is currently one Windows 95 console interface for the batonImprov environment which is described further below.

User functions:

There are 13 functions which must be defined by the user in the batonImprov environment (although they can be defined as blank as in the template program further below.

Maintenance functions:

void description(void);

Place print statements in this function which describe what your program does and how to use the program. This function is of great importance to add value to your program. This function is called in the Improv program with the "D" character command.



void initialization(void);

This function is called once when the Improv program is first started. Place variable initializations and similar things here.



void finishup(void);

This function is called once when the program is quit. Place any commands here you to want to occur at that time.

Behavior functions:

void mainloopalgorithms(void);

This function will be called as fast as possible by the Improv program. Actions which look at the current position of the batons might be good to place here as well as actions based on timers.



void keyboardchar(int key);

This function is called whenever a non-command character is pressed on the computer keyboard. You can define a behavior for characters in this function. All characters that can be accessed without the shift key are available to the programming user: a-z, 0-9, the symbols: ,./;'[]-= as well as any control-charcters, or alt-characters and the ESC key. Also, any key not defined above may be used, although at your own risk since that key may be needed in a later version of the Improv program.



void stick1trig(void);

This function is called each time stick 1 passes throught the horizontal trigger plane. Place commands in here which will be executed whenever stick 1 passes through the trigger plane.



void stick2trig(void);

Place commands in here which will be executed whenever stick 2 passes through the trigger plane.



void b14plustrig(void);

Place commands here which will be executed whenever the b14+ button is pressed.



void b15plustrig(void);

Place commands here which will be executed whenever the b15+ button is pressed.



void b14minusdowntrig(void);

Place commands here which will be executed whenever a footpedal connected to b14- is depressed.



void b14minusuptrig(void);

Place commands here which will be executed whenever a footpedal connected to b14- is released.



void b15minusdowntrig(void);

Place commands here which will be executed whenever a footpedal connected to b15- is depressed.



void b15minusuptrig(void);

Place commands here which will be executed whenever a footpedal connected to b15- is released.

Global variables

There are three primary global variables in the batonImprov environment:

RadioBaton baton;

The MIDI I/O interface to the radio baton controller.



MidiOutput synth;

The MIDI Output interface to the synthesizer.



long t_time;

A timer that keeps track of the time in milliseconds (1/1000 of a second).

Shown below is a schematic of the device connections inteneded for the batonImprov environment. Note that the global objects synth and baton descibed below represents a MIDI synthesizer/keyboard and radio baton as shown in the figure below.



In addition to the three primary global variables, there are some other global variables which are identical to variables inside of the baton object: Baton state variables: The values below are integers in the range from 0 to 127 (7-bit MIDI data). The x-axis goes from left (0) to right (127). The y-axis goes from near (0) to far (127). The z-axis goes from low (127) to high (~0). Positions of the sticks are updated about 50 times per second. Triggers are updated when the sticks pass through the horizontal trigger plane.

position variables:

• short xt1 -- current x-axis position of stick 1. (baton.x1p)
• short yt1 -- current y-axis position of stick 1. (baton.y1p)
• short zt1 -- current z-axis position of stick 1. (baton.z1p)
  
  
• short xt2 -- current x-axis position of stick 2. (baton.x2p)
• short yt2 -- current y-axis position of stick 2. (baton.y2p)
• short zt2 -- current z-axis position of stick 2. (baton.z2p)
  
  
• short pt1 -- current position of potentiometer (dial) 1 (baton.d1p)
• short pt2 -- current position of potentiometer (dial) 2 (baton.d2p)
• short pt3 -- current position of potentiometer (dial) 3 (baton.d3p)
• short pt4 -- current position of potentiometer (dial) 4 (baton.d4p)





trigger variables:

• short wh1 -- whack velocity of stick 1 trigger (baton.w1t)
• short xw1 -- trigger x-axis position of stick 1 (baton.x1t)
• short yw1 -- trigger x-axis position of stick 1 (baton.y1t)
  
  
• short wh2 -- whack velocity of stick2 trigger (baton.w1t)
• short xw2 -- trigger x-axis position of stick 2 (baton.x1t)
• short yw2 -- trigger x-axis position of stick 2 (baton.y1t)

Program template:

The basic structure of a batonImprov program is shown below. You must: (1) include a particular interface (in this case the default console interface defined in the file "batonImprov.h", and (2) define the thirteen user functions (which can be defined as empty as shown below). See the batonImprov examples directory for examples of what to put into the function definitions below.

          #include "batonImprov.h"

          void description(void) { } 
          void initialization(void) { }
          void finishup(void) { }
          void mainloopalgorithms(void) { }
          void stick1trig(void) { }
          void stick2trig(void) { }
          void b14plustrig(void) { }
          void b15plustrig(void) { }
          void b14minusuptrig(void) { }
          void b14minusdowntrig(void) { }
          void b15minusuptrig(void) { }
          void b15minusdowntrig(void) { }
          void keyboardchar(int key) { }

Here is a template file which you can use to create a synthImprov program: batonTemplate.cpp.

Default console interface for the batonImprov environment

The default console interface for the batonImprov environment can be loaded into the batonImprov program by adding the preprocessor line:

      #include "batonImprov.h"

somewhere near the top of your batonImprov program. Described below are the basic commands defined in the console interface. Note that all commands are defines with characters which use the shift key. ch3> batonImprov console interface commands
• "?" print basic interface commands
• "A" baton alive test
• "B" toggle buf display (display of raw sensor measurements)
• "C" calibrate the radio batons with calibration file
• "D" print programmer's description of the program
• "E" toggle MIDI input error message printing
• "I" set MIDI input port for radio baton controller.
• "L" set stick levels (sets the horizontal trigger plane height)
• "M" print more interface commands
• "N" set MIDI output port for synthesizer
• "O" set MIDI output port for radio baton controller
• "P" toggle position display
• "Q" quit program
• "R" toggle position reporting from radio baton controller
• "S" silence synthesizer
• "W" write calibration file
• "X" toggle MIDI in trace
• "Y" toggle MIDI out trace
• "Shift-1" center stick 1
• "Shift-2" center stick 2
• "Shift-3" increase z-axis sensitivity
• "Shift-4" decrease z-axis sensitivity
• "Shift-5" increase x-, y-axis sensitivity
• "Shift-6" decrease x-, y-axis sensitivity