An IoT Tutorial for Phonegap, and the Arduino Yun using the Bridge REST API

Date: 2015-05-25

This tutorial has four parts:

  1. The Introduction
  2. The Arduino Part
  3. The Phonegap Part
  4. How The Mobile App Works

The Introduction

Phonegap, a framework for creating mobile Apps with HTML5, CSS3, and Javascript, has the benefit of anything that can work on the web can done in Phonegap with a minimum of effort. In short, you can test on your webbrowser, then port the important parts to a mobile app.

The Arduino Yun is the wireless version of the popular embedded board series from Arduino. One of the most valuable tutorials in the Arduino arsenal is the the Bridge Tutorial. It uses the REST API to turn an LED on and off.

Yun with LED #13 Off.

It is also useful because:

The Arduino Part

Yun with LED #13 On.

For those not familar with the Arduino, the bridge tutorial is included in the IDE menu under Files->Examples->Bridge->Bridge. After loading the source code, one should validate that the Yun can be seen under Tools->Port. Next, upload the source code (widely known as a sketch), using the upload button, or Files->Upload (or ctrl+u). After uploading, the sketch will immediately start running. Open up the Serial Monitor Tools->Serial Monitor to get feed back from the Yun1.

The purpose of the bridge sketch is to attach to the local host interface on the Linux side of the Arduino Yun and respond to REST API requests. The bridge tutorial and the sketch provide additional details about using it.

As already stated, one benefit of this sketch is that one can use any webbrowser to check it. However, the REST API can also be queried by an AJAX call and get the same results. This makes it an ideal canidate for a simple Phonegap mobile App.

The Phonegap Part

Android version of the App

This mobile app uses Zepto.js. It is equivalent to JQuery, but is popular in the embedded community because it deals with the mechanics of the User Interface and NOT flashy addons.

There are two (2) event listeners and two (2) main functions.

The Event Listeners

The first listener listens for DOMContentLoaded; the second listener listens for deviceready.

The first listener binds the fastclick library to the body of the webpage. The second listener loads things that must wait until the the phonegap library is ready, and the device is ready.

The fastclick library removes the 300ms delay inherent to Android devices.

The phonegap library gives access to the hardware on the mobile device, and it gives us access to the network - be it the local area network, the phone network or the Internet.

The Main functions

The first main function is in the block that starts with if (device.platform === "iOS") It changes the UI (user interface) to accommodate Apple's iOS — for iPhone, iPads, and iPodTouch.

The second main function is the block that starts with $("#toggle13").click(function() It only becomes active then the button with the id=toggle13 is depressed. Once the function starts, it grabs any value available from the form field (id=targetIP). If no value was available, then it assigned the defaultHostIP and updates the form field.

It then proceeds to partially assemble the URI. After that, it assigns the appropriate value to toggle the LED, appends to the URI, and sets the appropriate value to ledIntermediateState2.

In the last part, the $.get(myurl, function (data) { makes the REST API call. The response is captured in the lambda function that updates text span with the id=led13.

// This fires only when the button is pressed. $("#toggle13").click(function() { //alert("toggle LED #13"); // extract the IP the user gives us. hostIP = $("#targetIP").val(); // if they did not give us one, use 'defaultHostIP'. if (! hostIP) { hostIP = defaultHostIP; // Insert the IP we will use in to the form $("#targetIP").val(hostIP); } // create our partial URL with REST API targetURL = "http://" + hostIP + "/arduino/digital/13/" ledIntermediateState = "error"; // if we ever see this, we have problems. // toggle the state based on our last state. if (ledState === 0) { ledState = 1; myurl = encodeURI(targetURL + "0"); ledIntermediateState = "IOT set to OFF"; } else { ledState = 0; myurl = encodeURI(targetURL + "1"); ledIntermediateState = "IOT set to ON"; } $("#led13").html(ledIntermediateState); // Actually make the call to the webserver. $.get(myurl, function (data) { //console.log(data); $("#led13").html(data); }); });

How The Mobile App Works

Here are the basic steps for running the App.

  1. C - Start your computer.
  2. Y - Plugin the Arduino Yun into your computer USB port.3
  3. A - Start the mobile App.
  4. YAC- Make sure all three devices are on the same network - very important.
  5. C - Start Arduino IDE.4
  6. C - Load the Bridge sketch in the IDE.
  7. C - Compile and upload the sketch on to the Yun.
  8. Y - Get the IP of your Yun.5
  9. C - Test the Bridge sketch with your webbrowser (ie. http://192.168.240.1/arduino/digital/13/
  10. A - Enter the IP of your Yun into mobile App.
  11. A - Tap the button to toggle the LED.6 7

NOTES

Footnotes

  1. Note: Some sketches require the Serial Monitor to be open. This often trips up new users. The Bridge sketch does not.
  2. This text is displayed just after the button is pressed, and gets updated when the Arduino responds. If you leave out fastclick.js, you might be able to see the text.
  3. You can, of course, use a wall wort to power your Yun, instead of plugging it in.
  4. Make sure you start it as Super User on Linux.
  5. If you are using a Macintosh you can also use the standard hostname, arduino.local.
  6. The first time you toggle the LED, the LED toggles to off.
  7. After tapping the button the first time the message will read LED #13: IOT set to OFF. After that it is updated by the server.