Introduction

These instructions will allow you to create a simple sketch in Dashcode and run it on an iPod Touch (2G) or iPhone with RunSketch to view inputs from a potentiometer connected directly to the iPod. The tutorial is broken into three parts: making the code, connecting the sensor and running the completed sketch #summary What you need to use NADA Mobile.

What You Need to Use NADA Mobile

At a minimum:

• iPhone or iPod Touch
• Apple iPhone Developer Program membership or jailbroken firmware 2.21 or later on your phone/ipod and Cydia
• Mac OS X 10.4 (it will run on Windows too, but we don't have a binary download for Windows yet)
• Dashcode (download info) the free HTML editor from Apple (you can use a text editor too, but this tutorial uses Dashcode)

If you want to use an external sensor on the device:

• A cable with a male, four-band 1/8" (3.5mm) plug, like this one or or this cheap (purple!) one.
• A passive resistive sensor, like a potentiometer or a photocell
• A resistor (200 kOhm usually, but it varies)
• Soldering iron and solder

Installing the software

If you came here from the installation instructions you can skip this part.

1. Download the latest release from the downloads page.
2. Unzip the archive and put the contents in your Applications folder (Mac OS X).
3. Install the part that goes on your iPhone/iPod:
• If you have a jailbroken device, you can follow these instructions to use Cydia.
• If you are an Apple iPhone Developer Program member you can follow the instructions to build the app from source here.

Writing the Code

1. Open Dashcode and choose to create a Custom Web Application project.
2. To make this Dashcode Web applications work with RunSketch you have to first add the RunSketch JavaScript library to your application.
   • From the File menu, choose Add File...
   • Navigate to the main "NADA Mobile" folder, then into the "JavaScriptLibrary" folder and choose "sketching.js".

   

   • Every time you make a sketch you'll need to add this file.

3. The main part of your application window contains a basic gray background on which to drag and drop components for your application.
   • At the top right-hand corner of the screen select the Inspector and Library icons to ensure the two panels are open.

   

4. In the Library panel, click on the drop-down menu and select Text.
   • Drag a Text Box into the workspace.

   

   • This text box will serve to display the value of your sensor reading.

5. In the Library panel, click on the drop-down menu again and select Shapes Drag a Rectangle into the workspace.

   

   • The size of this rectangle will serve to visualize the value of your sensor reading.

6. Next, open the Source Code Editor by selecting View and then Source Code.
   • The existing code will look like this.

   /* 
    This file was generated by Dashcode.  
    You may edit this file to customize your widget or web page 
    according to the license.txt file included in the project.
    */
   
   //
   // Function: load()
   // Called by HTML body element's onload event when the web application is ready to start
   //
   function load()
   {
       dashcode.setupParts();
   }
   

7. Copy and Paste the following code into the Source Code Editor before the existing code.

   function sketchOnAudioAmplitude(v) {
   //do something with 1/8" jack
   
   }
   function sketchOnIOPack(v0, v1, v2, v3) {
   //do something with IOPack values
   
   }
   function sketchOnAccelerate(x, y, z) {
   //the device's accelerometer just fired
   
   }
   function sketchOnLocation(lat, lon, alt) {
   //the device's GPS just fired
   
   }
   

   • Here, there are four empty functions, sketchOnAudioAmplitude, sketchOnIOPack, sketchOnAccelerate, and sketchOnLocation. Placing code within any of these functions allows you to access variables such as external sensor readings, internal accelerometer readings, and internal GPS readings.

8. Copy and Paste the following code into sketchOnAudioAmplitude.

   //1. make textbox display sensor reading
   text.innerHTML = v;
   
   //2. make rectangle size correspond with sensor reading
   rectangleShape.style.width = (2 * v) + "px";
   rectangleShape.style.height = rectangleShape.style.width;

   • The code under comment 1. sets the text as equal to the value of the sensor reading (v).
   • The code under comment 2. sets the width and height of the rectangle as equal to 2 x the value of the sensor reading (v)

9. This completes the simple application. Save the Dashcode file and open it on the Ipod Touch using Run Sketch (see Run Sketch setup for more information).

Connecting the Sensor

1. To connect a sensor using the Ipod's 8th inch jack, begin with a camcorder cable with three Audio/Video RCA plugs. It is important that the jack have four sections (3 rings and a tip) as shown below.

   

2. In order to connect the sensor properly, it is necessary to understand how the cable is wired.
   • The metal band surrounding each pin corresponds to Ground. These bands connect to a section of the 8th inch jack labeled below.

   

   • The three pins at the end of each colored plug correspond to Microphone In, Left Headpphone Out, and Right Headphone Out. These pins connect to three different sections on the 1/8th inch jack, but their exact connection is uncertain. Since cables vary, it is important to manually verify which pins connect to which sections on the jack. The following steps will help verify these connections.

   

3. To begin, use a multimeter to conduct a continuity test.
   • Turn the multimeter to the continuity test setting (the "beep" setting).
   • Touch one probe to a ring on the 8th inch jack and the other probe to a colored pin until you hear a beep.
   • Take note of which ring belongs to which pin.
   • In this example, Microphone In connects to the Red Pin, Left Headphone Out connects to the Yellow Pin, and Right Headphone Out connects to the White Pin. The remaining ring is Ground.

   

4. To connect the sensor to the cable, you will use Microphone In (in this example the red pin) as your "sensing" wire and Right Headphone Out (in this example the white pin) as your "power" wire. The yellow pin will remain and can be used for its ground. In order to get a good reading, you will probably need about 200k Ohms connected between your sensor output and the microphone pin.

   

   • Connect alligator clips to the pins as follows.

   

Running the Sketch

Once you have the hardware wired up, the software installed on your device, and a sketch ready in dashcode, you are ready to run a sketch!

1. Make sure your ipod/iphone is on the same network as your computer.

   

2. Open the SketchServer application.

   

3. Select your IP address on the airport network from the list. It will not be the same as the one in the screen capture below, but you can find it in your computer's network settings panel.

   

4. Click the "start" button.

   

5. On the iphone, tap the RunSketch app.

   

6. Now, tap the very lower right corner of the sketch. This will always be where you tap to get to the upload screen and change your sketch settings.

   

7. In the settings dialog, where it says "Sketch server:", type your computer's IP address on the wireless network, as listed in SketchServer.

   

8. Now, tap the "Open Sketch" button.

   

9. Back on the computer, you will be prompted to choose a sketch. Choose the Dashcode file you made earlier in the tutorial.

   

10. Once your sketch is transfered to the phone, it should start running!

    

11. Rotate the potentiometer, and see if the sketch changes...