View source for 250a Haptics Lab 2012 zz

= Haptics Lab Using the FireFader for Music 250a =
by Edgar Berdahl and edited by Wendy Ju

See [https://ccrma.stanford.edu/courses/250a/schedule.html this quarter's schedule] for due dates.

The goal of this lab is to introduce actuation and active force feedback.   Each haptic effect can easily be coupled to a sound because the feedback loop is controlled directly in pd. Different haptic effects suggest different sounds; different sounds suggest different effects.  What are the most interesting mappings?  Which are appropriate, controllable, even "expressive"?  Try each sound control with and without haptic feedback enabled.  Are there some that simply cannot be played without haptics?

<!-- <div align="center">
[[Image:overview_fs.jpg]]

Hardware design of Force stick by Bill Verplank
</div> -->


== Feel The Motors ==
Find the foam-core board that has motors mounted on it and try them out. 

For the DC motors, connect one alligator clip to the 6V supply on the ''Triple Output Power Supply'' from Hewlett Packard, and connect the other alligator clip to ground, which is labeled COM. '''Careful! Don't use the 18V supply instead--you could burn out the motors!''' By adjusting the +6V knob, you can change what voltage you are applying to each of the DC motors. Which way does the solenoid pull? What are small motors good for and what are large motors good for?

For the AC motors, use the ''Tektronix Function Generator.'' Try sine waves in the audible range 20Hz-20kHz on the white-colored AC motor. For it to be loud, it needs to be connected to something that can vibrate. Try changing the sound by coupling it to the foam core or the violin body or something else. The other, smaller AC motor can be used to vibrate objects with iron or steel in them or magnets. Try to use it to vibrate the magnet glued to the foam core. Try to use it to vibrate the violin string directly, which contains some steel inside it. (Hint: You will have to place it very closely to the string without touching the string.) Do you know at which frequencies the violin string responds the most?

<div align="center">
[[Image:motor_board.jpg]]
</div>

== Connect the FireFader to Your Beagle Board ==

Be careful with the FireFader. It is possible to break it, for instance if it goes unstable! If it goes unstable, you should immediately cut the power by turning off the power switch on the FireFader. The power cable for the FireFader has a yellow end on it, on which is written 12V (or 15V). '''Be very careful NEVER to plug this into the Beagle Board because you would break it.''' (The Beagle Board needs to receive only 5V.)

* Disconnect the Arduino Nano that you normally use from your Beagle Board.
* Then connect your Beagle Board instead to the Arduino Nano on the FireFader.
* You will see that a circuit has already been created on the bread board. This is essentially the circuit for the H-bridge motor driver L298 (see p. 6 of the [http://www.cse.dmu.ac.uk/~mgongora/Resources/L298N.pdf datasheet]) with the large LEDs connected in parallel with the motor.

== Setup the Software on Your Satellite CCRMA Kit ==
* First startup your kit
* Connect your Satellite CCRMA kit to your laptop and boot it.
* Use a terminal window to login to Satellite CCRMA as usual using the command <tt>ssh -XY ccrma@192.168.105.106</tt> with the password ''temppwd''
* Download the <https://ccrma.stanford.edu/courses/250a/labs/hapticslab2012.zip lab files> to your laptop.
* Copy the lab files to your home directory ~ using Cyber duck.
* Unzip the files: change into your ~ directory, and type <tt>hapticslab2012.zip</tt>.

* You shouldn't need to reinstall the FireFader Firmware, but in case there is an issue, you can
** run the command <tt>arduino&</tt> to start the Arduino software. (If it asks you if you want to install a newer version of the Arduino software, tell it ''no''.)
** Use the Arduino software to open <tt>~/hapticslab2012/haptics_firmware/haptics_firmware.pde</tt>. Upload this code to the Arduino.
** Look at the main loop '''loop()''' in the source code for this firmware for a minute. You can see that it reads data from the serial connection from pd and uses this to set the PWM pins using '''analogWrite()'''. Then it writes data to the serial connection to pd about the position of the Fire Fader. Additional data from the analog input pins 1-3 is also sent over the serial, but these pins aren't currently used.

== touch_ground~ ==
* First start audio. You can use this using ''start-jackd'' as usual, but if you use the following command the audio quality will be slightly better:

'' jackd --silent -R -P62 --timeout 200 -dalsa -dhw:0 -p512 -n3 -i2 -o2 -s -S -r22050 -Xseq & ''

* To start pd for this lab, use the following command

'' pd -sleepgrain 1 & ''

* Plug in your speakers or earbuds.
* in Pd, add the following directories to your path by going to File->Path->New:
 <tt>/home/ccrma/hapticslab2012/datadir/pdhelp</tt>
 <tt>/home/ccrma/hapticslab2012/datadir/puredatadir</tt>
* Open pd and load the patch <tt>~/hapticslab2012/datadir/puredatadir/touch_ground~-help.pd</tt>
* Read the text of the patch so that you can understand how the layout of the patch relates to the equivalent mechanical system of the FireFader being connected by a touch link to ground.
<div align="center">
[[Image:touchground.png]]
</div>
* Turn on audio by clicking on ''compute audio,'' which also allows the haptic forces to be computed.
* Verify that by moving the FireFader back and forth, you can make the hslider shown in the patch change.
* Plug in the 12V yellow power connector to the FireFader.
* Switch the FireFader on while holding onto the fader.
** You should be able to feel a spongy "wall" when you move the FireFader to the left of the center position. (If not, then check your setup.)
** Because of the spring action of the touch link, the force increases when you move to the right. However, if you move far enough to the right, then the motors can no longer increase the force level any further due to mechanical limitations.
** Try decreasing the stiffness of the contact~ link to 150 N/m. How does this feel?
* Consider a hypothetical situation involving two springs with stiffness ''k'' N/m. If you connect the two springs in series, is the net stiffness ''2k'' or ''0.5k''? What if you connect the two springs in parallel?
* When you are done with the patch, turn the motor amplifier board off again. (The motor can get hot if left on while exerting a force.)

Note: Systems with feedback can become unstable if the right conditions arise. This is why it is a good idea to turn off the motor amplifier board when you are not using the system. (Otherwise, consider what can happen with a public address system if you leave it alone and it starts to squeal/howl.)
<div align="center">
[[Image:Touchgroundfull.png]]
</div>

== pluck_a_mass_on_spring~.pd ==
* Close any other open patches, and then open <tt>~/hapticslab2012/datadir/puredatadir/pluck_a_mass_on_spring~-help.pd</tt>
* Read the patch and notice how the layout of the patch matches the equivalent mechanical system of a FireFader connected by a springy link~ to a virtual mass.
<div align="center">
[[Image:Pluckmassonspring.png]]
</div>

* On the left, the position of the FireFader is shown with an hslider, and on the right the position of the virtual mass m is shown with an hslider.
* Turn on the motors and wiggle the FireFader back and forth. Can you feel the virtual mass?
* What happens if you change the virtual mass from 1.2kg to 0.6kg?
* What happens if you change the damping in the link~ from 1 N/(m/s) to 0 N/(m/s)?
* Is it a bad idea to make the damping negative? (Be ready to cut the power if you try this!!)

== pluck_a_resonator~.pd ==
* Open this patch and see if you can guess what will happen. Now try it!
* Read the patch and notice how the layout of the patch matches the equivalent mechanical system.
** For example, note how one virtual resonator is formed by mass~ ''m'' connected to ground ''g'' by link ''l''. The second resonator is formed by mass~ ''m2'' connected to ground ''g2'' by link ''l2''.
** In case you are wondering about the equivalent mechanical system, here is a similar one: the FireFader is plucking a single virtual resonator.
<div align="center">
[[Image:Pluckresonator.png]]
</div>
* Why does the pitch increase when you can feel the virtual resonators? Hint: contact-pluck~ ''c'' behaves like a spring when the FireFader is connected to the resonators. Another hint: Consider whether ''c'' is connected in parallel or in series with the virtual resonators.

== pluck_six_half_strings~ ==
* First try interacting with the string without any haptic force feedback. Then turn on the power to the motor amplifier board and try to pluck the string. Is it easier to play with or without haptic feedback?
* Clicking on the bang in the main patch will cause an impulse to be send into the string. What do you have to do with the FireFader in order to be able to feel the impulse?
* Open up the subpatch to have a look inside.
* Try to imagine what it would look like if the <tt>delread~</tt> and <tt>delwrite~</tt> pairs were bypassed? Again, the layout of the patch should provide some indication for the equivalent mechanical model
<div align="center">
[[Image:Plucksixhalfstrings.png]]
</div>
* Optional: How could you change either of the <tt>DWG-end~</tt> objects to increase the fundamental frequency of the string's sound?
* If you would like to learn more about physical modeling then take Julius Smith's course Music 420 in the winter quarter. For some specific information about this particular physical modeling method, see [http://ccrma.stanford.edu/realsimple/waveguideintro/ this brief tutorial].
* '''Remember to turn off the power to the motor amplifier board when you are finished.'''

== Percussion_hri~ ==

<div align="center">
[[Image:PercussionHRI.png]]
</div>

* Now hold onto the FireFader while you turn on the motor amplifier board with the other hand. '''(Be careful because this patch is especially likely to become unstable! If the FireFader should become unstable, turn off the motor amplifier board again.)'''
* You should now feel a virtual "robot" that tends to shake the FireFader about 3 times per second.
* Look at the mechanical analog inside <tt>pd subpatch-blocked-at-1</tt>. Again the FireFader is connected by a link to ground. However, this time the "virtual mass" is implemented using <tt>osc~ 3</tt> and neighboring objects.


* Note that in the previous patch, the same physical model was used to synthesize both the audio feedback and the haptic force feedback, in this case, the output from the haptic feedback model is used to control the shaker~.

==Build Your Own==
Make your very own musical controller using the FireFader and one of the above patches as a starting point.
Here are some ideas, but feel free to follow your own interests:
<ol><li>Make a record scratching interface allowing you to feel the record.</li>
<li>Or try to impart kinetic energy from your body into a physical model of an instrument.</li>
<li>Or can you program the haptic interface so that it allows you to feel a texture?</li>
<li>Or use the same physical model to calculate both the haptic force feedback and the audio feedback. For instance, you could create multiple virtual objects that you can pluck by giving them different mechanical ground positions.</li>
<li>Or if you would like to try some advanced three-dimensional force feedback using the NovInt Falcon, you can use the same physical modeling formalism with [http://ccrma.stanford.edu/~eberdahl/Projects/HSPv2.zip HSP for Max/MSP].</li>
</ol>

Make us proud. Post the video of your controller at [[Music 250a Lab Video Wiki]]. And be ready show off your controller at the next lab session!


==Note==
This lab was inspired by an [https://ccrma.stanford.edu/courses/250a/labs/lab5-winter-2007-haptics/ older lab exercise] for this class by Bill Verplank as well as work done at Claude Cadoz's laboratory.