##
Realtime MIDI Library for the MIT Handy Board

##
Function Reference

Colby Leider
Department of Music, Dartmouth College
http://music.dartmouth.edu/~colby/hb.html
cnl@dartmouth.edu

### BASIC MIDI FUNCTIONS

midi_on
Arguments: None.
Functionality: Allows the Handy Board to send MIDI data through its serial interface.
midi_off
Arguments: None.
Functionality: Allows the Handy Board to interact with the serial port on a computer by resetting the 68HC11's Serial Control Interface (SCI) to 9600 baud and telling the Handy Board's pcode to receive incoming serial data. After the Handy Board has transmitted MIDI data, either this function must be invoked or the Handy Board must be power cycled and Interactive C restarted to allow the Handy Board to communicate with Interactive C again.
turbo_on
Arguments: None.
Functionality: Increases the rate at which sensors are polled by disabling pulse width modulation of motors and infrared transmission and reception.
turbo_off
Arguments: None.
Functionality: Reenables pulse width modulation of motors and infrared transmission and reception.
note_on
Arguments: integer channel; integer pitch; integer velocity
Functionality: Sends a MIDI Note On message.
note_off
Arguments: integer channel; integer pitch
Functionality: Sends a MIDI Note Off message.
poly_key_pressure
Arguments: integer MIDI channel; integer pitch; integer pressure_value
Functionality: Sends a MIDI Poly Channel Pressure message.
control_change
Arguments: integer MIDI channel; integer controller_number; integer controller_value
Functionality: Sends a MIDI Control Change message.
program_change
Arguments: integer MIDI channel; integer program_number
Functionality: Sends a MIDI Program Change message.
channel_pressure
Arguments: integer MIDI channel; integer pressure_value
Functionality: Sends a MIDI Channel Pressure message.
pitch_bend
Arguments: integer MIDI channel; integer pitch bend value
Functionality: Sends a 7-bit MIDI Pitch Bend message.
pitch_bend2
Arguments: integer MIDI channel; integer pitch bend least significant byte (LSB); integer pitch bend most significant byte (MSB)
Functionality: Sends a 14-bit MIDI Pitch Bend message.
modulation_depth
Arguments: integer MIDI channel; integer modulation depth value
Functionality: Changes the MIDI Modulation Depth.
main_volume
Arguments: integer MIDI channel; integer main volume value
Functionality: Sets the MIDI Main Volume.
pan
Arguments: integer MIDI channel; integer pan value
Functionality: Changes the MIDI pan value for a particular channel.
expression
Arguments: integer MIDI channel; integer expression value
Functionality: Sends a MIDI Expression message.
sustain_on
Arguments: integer MIDI channel
Functionality: Turns on the MIDI sustain pedal controller on the given channel.
sustain_off
Arguments: integer MIDI channel
Functionality: Turns off the MIDI sustain pedal controller on the given channel.
all_sound_off
Arguments: integer MIDI channel
Functionality: Sends a MIDI All Sound Off channel voice message on the given channel.
reset_all_controllers
Arguments: integer MIDI channel
Functionality: Sends a MIDI Reset All Controllers channel voice message on the given channel.
local_control
Arguments: integer MIDI channel; integer on/off ag
Functionality: Sends a MIDI Local Control On channel voice message if the on/off ag is 1. Sends a MIDI Local Control Off channel voice message otherwise.
all_notes_off
Arguments: integer MIDI channel
Functionality: Sends a MIDI All Notes Off (panic) message.
omni_mode_off
Arguments: integer MIDI channel
Functionality: Sends a MIDI Omni Mode Off channel voice message on the given channel.
omni_mode_on
Arguments: integer MIDI channel
Functionality: Sends a MIDI Omni Mode On channel voice message on the given channel.
mono_mode_on
Arguments: integer MIDI channel; integer number of channels
Functionality: Sends a MIDI Mono Mode On channel voice message on the given channel. The second argument, num_channels, indicates the number of channels which are sent the mono channel voice messages.
poly_mode_on
Arguments: integer MIDI channel
Functionality: Sends a MIDI Poly Mode On channel voice message on the given channel.
midi2octpc
Arguments: integer MIDI pitch
Functionality: Converts MIDI note number into octave.pitch-class (oct.pc) notation. For example, calling midi2octpc with an argument of 60 would return 8.00.
octpc2midi
Arguments: float oct.pitch-class
Functionality: Converts octave.pitch-class (oct.pc) into MIDI note number. For example, calling octpc2midi with an argument of 8.00 would return 60.
midi2oct
Arguments: integer MIDI pitch
Functionality: Returns an integer representing the octave of the specified MIDI pitch.
midi2pc
Arguments: integer MIDI pitch
Functionality: Returns an integer representing the modulo-12 pitch class of the specified MIDI pitch.

### BASIC SERIAL DATA FUNCTIONS

(by Randy Sargent, Newton Research Labs)
serial_putchar
Arguments: integer value
Functionality: Transmits the integer argument out the 68HC11 SCI serial interface
disable_pcode_serial
Arguments: None.
Functionality: Tells the Handy Board's pcode not to receive incoming serial data (necessary to receive characters using serial_getchar).
reenable_pcode_serial
Arguments: None.
Functionality: Tells the Handy Board's pcode to receive incoming serial data (necessary to allow the Handy Board to interact with Interactive C again).
serial_getchar
Arguments: None.
Functionality: Returns the value of the received serial character.

### ANALOG PORT ROUTINES

read_analog
Arguments: integer port_number (in the range 0 6 inclusive); integer pointer value; integer offset; integer scale
Functionality: Sets the memory location pointed to by value to contain the current digitized value of the sensor voltage in port_number, multiplied by scale with a DC offset of offset.
return_analog
Arguments: integer port_number (in the range 0 6 inclusive); integer offset; integer scale
Functionality: Returns the current digitized value of the sensor voltage in port_number, multipled by scale with a DC offset of offset.
read_averaged_analog
Arguments: integer port_number (in the range 0 6 inclusive); integer pointer value; integer offset; integer scale
Functionality: Sets the memory location pointed to by value to contain the arithmetic average of the most recently digitized values of the sensor voltages in port_number, multiplied by scale with a DC offset of offset. The number of readings to average is given by the macro _NUM_VALUES_TO_AVERAGE.
return_averaged_analog
Arguments: integer port_number (in the range 0 6 inclusive); integer offset; integer scale
Functionality: Returns the arithmetic average of the most recently digitized value of the sensor voltage in port_number, multipled by scale with a DC offset of offset. The number of readings to average is given by the macro _NUM_VALUES_TO_AVERAGE.

### LCD ROUTINES

display_analogs
Arguments: None.
Functionality: Prints to the LCD screen the values associated with the analog input ports 0-6 and the onboard user knob in realtime.
display_digitals
Arguments: None.
Functionality: Prints to the LCD screen the values associated with the digital input ports 7-15 in realtime.
test_motors
Arguments: None.
Functionality: Sequentially turns on and off motors both backwards and forwards that are connected to the Handy Board's motor ports.
test_ir
Arguments: None.
Functionality: Continually displays received values from Sony-compatible remote controls on the LCD. Before calling this function, the le sony-ir.icb (available at the Handy Board home page) must be loaded.

### INTEGER & ARRAY OPERATORS

min
Arguments: integer x; integer y
Functionality: Returns an integer representing the value min(x, y).
fmin
Arguments: float x; float y
Functionality: Returns a float representing the value min(x, y).
lmin
Arguments: long x; long y
Functionality: Returns a long representing the value min(x, y).
max
Arguments: integer x; integer y
Functionality: Returns an integer representing the value max(x,y).
fmax
Arguments: float x; float y
Functionality: Returns a float representing the value max(x,y).
lmax
Arguments: long x; long y
Functionality: Returns a long representing the value max(x,y).
round
Arguments: float x
Functionality: Returns the value of x rounded off to the nearest integer.
trunc
Arguments: float x
Functionality: Returns the value of x truncated at the floating point.
abs
Arguments: integer x
Functionality: Returns an integer representing the value abs(x).
fabs
Arguments: float x
Functionality: Returns a float representing the value abs(x).
labs
Arguments: long x
Functionality: Returns a long representing the value abs(x).
print_array
Arguments: array of integers
Functionality: Prints each value of the array to the LCD screen separated by 500 milliseconds (useful for debugging).
print_farray
Arguments: array of floats
Functionality: Prints each value of the array to the LCD screen separated by 200 milliseconds (useful for debugging).
print_larray
Arguments: array of longs
Functionality: Prints each value of the array to the LCD screen separated by 200 milliseconds (useful for debugging).
array_min
Arguments: array of integers
Functionality: Returns the minimum-valued member of the array.
array_fmin
Arguments: array of floats
Functionality: Returns the minimum-valued member of the array.
array_lmin
Arguments: array of longs
Functionality: Returns the minimum-valued member of the array.
array_max
Arguments: array of integers
Functionality: Returns the maximum-valued member of the array.
array_fmax
Arguments: array of floats
Functionality: Returns the maximum-valued member of the array.
array_lmax
Arguments: array of longs
Functionality: Returns the maximum-valued member of the array.
array_avg
Arguments: array of integers
Functionality: Returns a float representing the arithmetic mean of the elements in the array.
array_favg
Arguments: array of floats
Functionality: Returns a float representing the arithmetic mean of the elements in the array.
array_lavg
Arguments: array of longs
Functionality: Returns a float representing the arithmetic mean of the elements in the array.
sum
Arguments: array of integers
Functionality: Returns an integer representing the sum of the array.
fsum
Arguments: array of floats
Functionality: Returns a float representing the sum of the array.
lsum
Arguments: array of longs
Functionality: Returns a long representing the sum of the array.
in
Arguments: array of integers; integer element
Functionality: Returns 1 if the specified element is in the array, 0 otherwise.
fin
Arguments: array of floats; float element
Functionality: Returns 1 if the specified element is in the array, 0 otherwise.
lin
Arguments: array of longs; long element
Functionality: Returns 1 if the specified element is in the array, 0 otherwise.
approx_in
Arguments: array of integers; integer element; float tolerance
Functionality: Returns 1 if the array contains the specified element to within the specified tolerance value, 0 otherwise.
approx_fin
Arguments: array of floats; float element; float tolerance
Functionality: Returns 1 if the array contains the specified element to within the specified tolerance value, 0 otherwise.
approx_lin
Arguments: array of longs; long element; float tolerance
Functionality: Returns 1 if the array contains the specified element to within the specified tolerance value, 0 otherwise.
choose
Arguments: array of integers
Functionality: Returns a randomly-chosen element from the list.
fchoose
Arguments: array of floats
Functionality: Returns a randomly-chosen element from the list.
lchoose
Arguments: array of longs
Functionality: Returns a randomly-chosen element from the list.
at
Arguments: array of integers; integer location
Functionality: Returns the integer value indexed by the specified location (with wrapped indexing). For example, given an array of four integers (indexed in C by the locations 0 3, at(5) would return the value indexed by 1 (5 mod 4 = 1).
fat
Arguments: array of floats; integer location
Functionality: Returns the float value indexed by the specified location (with wrapped indexing). For example, given an array of four floats (indexed in C by the locations 0 3, at(5) would return the value indexed by 1 (5 mod 4 = 1).
lat
Arguments: array of longs; integer location
Functionality: Returns the long value indexed by the specified location (with wrapped indexing). For example, given an array of four floats (indexed in C by the locations 0 3, the function call at(5) would return the value indexed by 1 (5 mod 4 = 1).

### EXAMPLES OF HIGHER-LEVEL MIDI FUNCTIONS

midi_test
Arguments: None.
Functionality: Calls midi_on() to enable MIDI on the Handy Board and then sequentially plays middle C (MIDI note 60) with maximum velocity on each MIDI channel (1 16).
ramp
Arguments: integer MIDI channel; integer base pitch; integer velocity; float time delay in seconds; integer multiplier; integer number of notes
Functionality: Emits a linear ramp of note on messages...
arpeggiate
Arguments: integer MIDI channel; integer base pitch; integer velocity; float time delay in seconds; integer array of offsets
Functionality: Arpeggiates a chord based on the given parameters...
flutter
Arguments: integer MIDI channel; integer base pitch; integer velocity; integer pitch variance; float time delay in seconds; integer number of notes
Functionality: Emits note on messages within a specified variance about the base pitch, delayed by a given time delay.
harmonize
Arguments: integer MIDI channel; integer base pitch; integer velocity; integer array of offsets
Functionality: Plays a chord by emitting note on messages built upon the base pitch whose members are offset according to the given array.
random_midi
Arguments: float duration in seconds
Functionality: Plays a random MIDI note and then turns it off after the specified duration in seconds. This function chooses a random MIDI channel, pitch, velocity, and program number.
midi_hpf
Arguments: integer pitch; integer cutoff
Functionality: MIDI high pass filter. If the given pitch is greater than or equal to the specified cutoff,
midi_hpf returns that value. Otherwise, it returns a zero. This would be useful in an application where a sensor occasionally returned a value outside a useful range (for instance, a MIDI note number below 20). midi_hpf would ensure that only notes above this value are played.
midi_lpf
Arguments: integer pitch; integer cutoff
Functionality: MIDI low pass lter. If the given pitch is less than or equal to the specified cutoff, midi_lpf returns that value. Otherwise, it returns a zero.
midi_bpf
Arguments: integer pitch; integer cutoff1; integer cutoff2
Functionality: MIDI band pass lter. If the given pitch is within the specified cutoffs (i.e., cutoff1 <= pitch <= cutoff2), midi_bpf returns that value. Otherwise, it returns a zero.
midi_notch
Arguments: integer pitch; integer cutoff1; integer cutoff2
Functionality: MIDI notch lter. If the given pitch is outside the specified cutoffs (i.e., cutoff1 <= pitch <= cutoff2), midi_notch returns that value. Otherwise, it returns a zero.
stutter
Arguments: integer MIDI channel; integer base pitch; integer velocity; integer number of notes; integer stutter factor
Functionality: Emits note on messages with the given channel, pitch, and velocity information, each separated by a randomized time delay calculated according to the stutter factor.
noodle
Arguments: None.
Functionality: Emits note on/off message pairs on random MIDI channels with random pitch and velocity values; the note on and off messages are each separated by a randomized time delay from 0.15 to 0.65 seconds.