H211: Fall 2010

Casa Arduino

Casa Arduino, written by Michael Adams, allows you to write Arduino programs using Scheme. The name ``Casa Arduino'' is Italian for ``house of Arduino''.

How Casa Arduino Works

Casa Arduino is actually two pieces of software: an interpreter that runs on Arduino, and Scheme code that runs on your laptop or desktop computer and sends commands to the Arduino (and hence the interpreter) using the USB serial port connection.

Downloading Casa Arduino

You can download the latest version of Casa Arduino here. The older, version 2, can be found here.

Unzip the .zip file and move it to the location of your choice.

Compiling and Uploading Casa Arduino to your Arduino

Before we can send commands to the Arduino using Scheme, we must first compile and upload the interpreter that will run on the Arduino.

If you are working on a Linux machine in LH115, first do the standard dance. Login, open a terminal, type:

sudo arduino-fix-permissions

then logout and log back in. Then start the Arduino integrated development environment (IDE):

/l/arduino/arduino

Next, connect your Arduino to your computer using a USB cable.

Select the 'Tools->Board' menu item from the Arduino IDE. Make sure "Arduino Uno" is selected.

Next select the 'Tools->Serial Port' menu item. Make sure the serial port for the Arduino is selected. On the Linux machines in LH115, the selected serial port should be "/dev/ttyACM0".

Now open the Ardunio interpreter sketch by selecting the 'File->Open' menu item. Replace the path name in the 'Open File' dialog box with the path to the 'casa_arduino.pde' sketch. For example, if I unzipped the Casa Arduino software to the 'h211' directory in my home directory, I would enter the path:

/u/webyrd/h211/casa_arduino_v2/casa_arduino.pde

If you opened the sketch correctly, you will see five tabs in the Arduino IDE window. Important: When compiling and uploading the Casa Arduino code in the Arduino IDE, you should open the 'casa_arduino.pde' file using the 'File->Open' menu. Don't open the .pde file by double-clicking on it or by dragging it into the Arduino IDE window. This is because the 'casa_arduino.pde' file is linked to four other .pde files. If you open the 'casa_arduino.pde' correctly, you should see five tabs in the window: 'casa_arduino', 'eval', 'lib', 'print', 'read'. Now compile and upload the Arduino sketch. Make sure you see the message at the bottom of the IDE window saying that the sketch was successfully uploaded.

Communicating with Arduino using Scheme

Open up a terminal, and cd to the top-level Casa Arduino directory (that is, 'casa_arduino_v2'). Start Chez Scheme *from this directory*. Important: Be sure to start Chez Scheme inside the top-level Casa Arduino directory. If you aren't in the correct directory, you wil get an error message when importing 'casa-arduino' or loading an example program. At the Scheme REPL, import the Casa Arduino Scheme library:

(import (casa-arduino))

If you get the error message

Exception: library (casa-arduino) not found

it means you didn't start Scheme from the correct directory!

Now that you have loaded the Casa Arduino library, you can open a connection to your Arduino:

(define conn (make-connection "/dev/ttyACM0"))

Of course you'll need to enter the correct USB port name if you aren't using a Linux machine in LH115.

Important: If you are running Mac OS X, you must use a USB serial port name containing "cu.". For example, in the Arduino IDE you may see two port names under the 'Tools->Serial Port' menu: "/dev/tty.usbmodem1d11" (let's say) and "/dev/cu.usbmodem1d11". You *must* use the 'cu' serial port name or Scheme will not be able to connect to the Arduino!

Now that we have a connection to the Arduino, we can send the Arduino commands using the 'send' function. For example, let's set digital pin 9 to HIGH (that is, to 5 volts). If an LED to connected to pin 9 and to ground, the LED should light up.

(send conn (list (pinMode 9 'OUTPUT) (digitalWrite 9 'HIGH)))

'send' takes two arguments: a connection object returned by 'make-connection', and a list of Arduino commands. Important: make sure that you always pass 'send' a list of commands. For example, if you want to set pin 9 to low, you should write

(send conn (list (digitalWrite 9 'HIGH) ))

instead of

(send conn (digitalWrite 9 'HIGH))

A call to 'send' returns a list of values associated with the Arduino commands that were sent. Side-effecting commands such as 'pinMode' and 'digitalWrite' return #, which commands like 'analogRead' and 'digitalRead' return useful values.

Arduino Commands

You can use the following commands within the list passed to a 'send' command. The behavior of these commands is similar to the Arduino C equivalents.

(pin-mode <pin-number> <mode>)

where <pin-number> is an integer corresponding to a digital pin (1 through 13), and where is either the symbol INPUT or the symbol OUTPUT. For example,

    
(pinMode 9 'OUTPUT)

sets pin 9 to output mode.

(digitalWrite <pin-number> <value>)

where <pin-number> is an integer corresponding to a digital pin (1 through 13), and where <value> is either the symbol HIGH or the symbol LOW. For example,

(digitalWrite 9 'HIGH)

would turn on an LED connected to pin 9.

(digitalRead <pin-number>)

where <pin-number> is an integer corresponding to a digital pin (1 through 13). The value returned will be either the symbol LOW or the symbol HIGH.

(analogWrite <pin-number> <value>)

where <pin-number> is an integer corresponding to a digital pin that can perform pulse-width modulation (PWM), and <value> is an integer between 0 and 255. Pins that can perform PWM are maked with a ~ on the main Arduino board (but not on the shield); on the Arduino Uno, these are digital pins 3, 5, 6, 9, 10, and 11. Common Gotcha: despite the name, the 'analogWrite' commmand does not work on analog pins (pins A0 through A5).

For example,

	  
(analogWrite 9 127)

would set an LED connected to pin 9 to half of its maximum brightness.

(analogRead <pin-number>)

where <pin-number> is an integer corresponding to an analog pin (pins 0 through 5). The value returned is an integer between 0 and 1023. Gotcha: make sure to call 'analogRead' on an analog pin. This differs from 'analogWrite', which must be called on a digital pin.

			    
(delay <milliseconds>)

where <milliseconds> is a non-negative integer specifying the number of milliseconds the Arduino should pause. For example,

(delay 1000)

would pause the Arduino (and the Scheme code communicating with the Arduino) for one second.

(servoAttach <servo-number> <pin-number>)

where <pin-number> is a non-negative integer (for example 0 or 1) [is there restrictions on these numbers?], and <pin-number> is digital pin [is there a restriction on this pin number?]. Epic Gotcha: after calling 'servoAttach', pulse-width modulation is disabled on pins 9 and 10, regardless of whether servos are attached to those pins. For this reason, it is a good idea to connect servos to pins 9 and 10, and use the other PWM pins (3, 5, 6, and 11) to fade LEDs or whatever.

(servoWrite <servo-number> <angle>)

where <pin-number> is the non-negatve integer used to attach the servo using the 'servoAttach' call, and <angle> is an integer between 0 and 180 representing the servo position in degrees (where 90 degrees is the centered position). Gotcha: make sure to call 'servoAttach' before calling 'servoWrite'.

Example Programs

The 'casa_arduino_v2/examples' directory contains several Scheme programs (fade.ss, blink.ss, sweep.ss) similar to example sketches that come with the Arduino IDE. You should try running and modifying these examples.

To load a program in the 'examples' subdirectory, start Chez in the top level Casa Arduino directory (for example, '/u/webyrd/h211/casa_arduino_v2'). Then define the *usb-port-name* variable to contain the serial port name for your Arduino. (Make sure to connect the Arduino first!). On the Linux machines in LH115, you would type:

> (define *usb-port-name* "/dev/ttyACM0")

Then load the desired example program. Be sure to include the path to the 'examples' directory:

> (load "examples/fade.ss")

Limitations, Gotchas and Troubleshooting

When compiling and uploading the Casa Arduino code in the Arduino IDE, you should open the 'casa_arduino.pde' file using the 'File->Open' menu. Don't open the .pde file by double-clicking on it or by dragging it into the Arduino IDE window. This is because the 'casa_arduino.pde' file is linked to four other .pde files. If you open the 'casa_arduino.pde' correctly, you should see five tabs in the window: 'casa_arduino', 'eval', 'lib', 'print', 'read'.

Be sure to start Chez Scheme inside the top-level Casa Arduino directory ('casa_arduino_v2'). If you aren't in the correct directory, you wil get an error message when importing casa-arduino or loading an example program:

> (import (casa-arduino))
Exception: library (casa-arduino) not found
Type (debug) to enter the debugger.

Exception: library (read-chez) not found
Type (debug) to enter the debugger.

If you are using 'analogWrite', make sure you are writing to a digital pin that supports pulse-width modulation (PWM). Pins that can perform PWM are maked with a ~ on the main Arduino board (but not on the shield); on the Arduino Uno, these are digital pins 3, 5, 6, 9, 10, and 11. Common Gotcha: despite the name, the 'analogWrite' commmand does not work on analog pins (pins A0 through A5).