250a Firmware Lab
Lab 3: Firmware Programming
Due on Wednesday, October 19th at 5PM
For this lab you need your MaxKit, and Satellite CCRMA .
Contents
Firmware Programming On Arduino
Compiling and uploading firmware code in the Arduino Program
For this class, we assume that you will be adapting existing working code for your own applications. While this is certainly easier than writing firmware from scratch, it does require understanding how existing code functions.
Log into your Satellite.
Start the Arduino software by typing the command arduino & in the XTerminal to your Satellite. Please upload the following firmware programs from your Arduino program's Examples folders to your Arduino controller and see how they function. Do attach LEDs, buttons, as is appropriate:
* Examples->Digital->Blink * Examples->Digital->BlinkWithoutDelay * Examples->Digital->Button
Custom Communication
One reason that you might want to program the Arduino microcontroller is to enable greater control over the communications from the Arduino. In this segment of the laboratory, we learn a wider variety of ways to send data from the Arduino hardware to the computer than we have previously used.
Serial communication with the Arduino software
You might have noticed in the previous lab segment that it can be very hard to know what is going wrong when the Arduino hardware is in autonomous mode. Here, we send serial communications between the Arduino hardware and the Arduino software.
- Examples->Analog->Smoothing: Use the Serial Monitor (icon on the far left on the Arduino software toolbar) to get data back from the Arduino.
- Examples->Communication->SerialCallandResponse.
Serial communication with PD
Now let's try using serial to communicate with PD.
First let's try outputting information to the Arduino hardware:
- Load Examples->Communication->PhysicalPixel
- The PD patch for communicating with this firmware is already stored in your ~/250a/lab3 directory on the Satellite. (It is also located here)
Next let's try getting information from the Arduino hardware:
- Load Examples->Communication->Graph
- The PD patch for communicating with this firmware is already stored in your ~/250a/lab3 directory. (It is also located here)
Low-latency sensing
Encoder input
One final reason that you would want direct control over the Arduino firmware is that you might have very low-latency sensing needs. As an example of this, we show you here how to use encoder input with the Arduino.
Quit Pd to ensure that Pd isn't using the USB/serial connection to the Arduino. Change to the ~/250a/lab3/encoder directory by typing
cd ~/250a/lab3/encoder
(Files encoder.zip here).
in the terminal. Start up the Arduino software using the command arduino & and upload the sketch encoder.pde to the Arduino. Then quit the Arduino IDE and start up Pd by typing pd encoder.pd
Now you need to build this schematic to interface the encoder: http://cm-wiki.stanford.edu/mediawiki/images/c/c1/Encoder_filter.png. Pin two is the middle pin on the rotary encoder, and pins 1 and 3 are the other directly adjacent pins. It can be a bit difficult to plug the encoder into the solderless protoboard, but you can do it if you straighten out the pins first.
Note: In the schematic, AVR Phase A is digital pin 2 or the Arduino, and AVR Phase B is digital pin 3.
Now you're ready to send out the position of the encoder over the serial bus. The values should start near zero and increase or decrease, depending on which direction you turn the encoder. How are negative numbers represented? Why does the encoder always start near 0 when the program on the Arduino is restarted?
Make A Musical Interaction
As the final main deliverable of the lab, you should cause your Satellite CCRMA kit make some sound that depends on how you manipulate the sensors. For example, you could make a musical instrument, a music controller, a mock-up sound art installation, or some other sonic interaction. Now that you have had some experience synthesizing sound, your sound synthesis patch should involve more than just a few osc~s. Think about what you want to design before you get started.
For your musical interaction, you can write your own firmware, or you can use Firmata. If you choose to use Firmata, then you need to re-flash Firmata to the Arduino. (See instructions from Lab 2.)
Start up the Jack audio server by executing the command qjackctl & at the terminal and clicking on the Start button. In order to be able to hear audio, you will need to plug a pair of ear buds, headphones, or loudspeakers into the 1/8" (2.54mm) jack labeled AUDIO OUT on the beagleboard.
It is probably easiest to make your patch by modifying ~/on-startup/windy-day.pd, which Edgar demonstrated in class. To start it up, first change to the directory ~/on-startup by typing cd ~/on-startup in the terminal. Then type pd windy-day.pd & to startup pd.
Optional: Autonomous Satellite CCRMA
By this point you should be done with your musical interaction. If you would like to go the extra mile, we will now show you how to make your musical interaction autonomous in the sense that it can operate all by itself, free from any external laptop computer. We will show you how to do this using the example windy-day.pd.
To Enable A Default Patch On Boot
In the terminal, change to the on-startup directory by typing
cd ~/on-startup
and type ls -la to see what files are in there. You can see that the link (aka alias) default_patch.pd points to windy-day.pd. In order to enable the default patch to load on boot, rename the file load_default_patch_disabled to load_default_patch using the command
mv load_default_patch_disabled load_default patch
The cat command can be used to display the contents of any ASCII file. To look at the contents of load_default_patch, type cat load_default_patch. As you can see, it starts up Jack using the text-based jackd instead of qjackctl, and then it loads default_patch.pd in pd with the graphical user interface (GUI) disabled.
Now your kit should be ready for autonomous Satellite CCRMA. To test it, just reboot the kit by typing sudo reboot and entering the password temppwd. As it is rebooting, plug a pair of ear buds, headphones, or loudspeakers into the 1/8" (2.54mm) jack labeled AUDIO OUT on the beagleboard. Within about a minute, your kit should be fully rebooted. To check this, you can try logging in with SSH. Either way, it should start running windy_day.pd upon startup.
Once your kit is fully rebooted, if you touch the anaog input pins on the Arduino A0-A7, it should start making some sound. However, unless you connect up a sensor circuit to some of the analog inputs, the exact behavior may be complicated. In particular, it will depend on the electrical properties of your body (how much sweat is on your fingers, whether you are touching a grounded device such as a laptop with any part of your body. Ask for help if you cannot get any sound.
Finally, log back into your Satellite. Type ps -A at the prompt to get a list of the currently running processes. jackd is the Jack audio sound server, and pdextended is the pd process. To stop the default patch from running, type ./stop_default. To see how stop_default works, type cat stop_default. (The ./ was necessary in order to run the script stop_default because the current user directory ~ is not in the user path, so linux needs the ./ to indicate to look for stop_default in the current directory.)
Optional: Programming Linux
We don't actually expect you to do anything here, we are just providing some more information that is maybe helpful for you linux gurus. Since Satellite CCRMA runs Ubuntu linux on an OMAP chip, many standard software packages have been compiled for it. This is why we were easily able to install software such as Jack, Audacity, ChucK, Faust, Jacktrip, and the Arduino software.
If you are lucky, you can install your favorite software using the apt-get utility. To get a list of packages available on the OMAP's ARM architecture, type
sudo apt-cache pkgnames
You will notice that this list is way too long to look at. You can pipe it to the text file using the command
sudo apt-cache pkgnames > packages.txt
and then look at it using emacs packages.txt, or you search for a particular package, such as
sudo apt-cache pkgnames | grep emacs.
Or, you can compile linux software yourself on the Satellite. The gcc, g++ tools etc. are already installed.
Type the df command. You can see that there is not a whole lot more than 1GB available on the SD card, so you should only install software if you decide that you need it.
Halt Your Board Properly When Finished!
Remember to shut down your board when you are done before powering it off! (Of course as Spencer pointed out, if you are operating truly autonomously, of course you cannot login and run the halt command. Nevertheless, if it is not too inconvenient please try to shut down properly if you can. If you do not, then you may find that your SD memory card becomes corrupted.) As described above, you can do this by executing the command sudo halt and then waiting 30 seconds before disconnecting the power cables.
Wrap-Up
Instead of submitting your actual pd patch (because this is a little bit involved), it is okay to simply include some text in your email to Ed and Wendy describing what your patch did. Also please write a few sentences about what part of the lab was the most difficult, and please document any bugs that you find so that we can fix them! In fact, we may add some troubleshooting sections to the bottom of this Wiki.
Thanks so much! We are looking forward to seeing demos of your musical interactions at the beginning of the next lab session!
