In order to know what you’re going to write to the tag, you need to know the Hue’s data format. The Hue data format is nicely designed to be both clear to read in JSON format, yet easy to parse in code. If you’re developing your own Internet-enabled appliances, it’s a worthwhile one to study. In Chapter 7, you’ll develop an NFC-enabled door lock that uses a JSON data format for the same reason: readability from both the human and machine perspectives.

Philips has an excellent developer reference that explains the whole API. For this app, what you need to know is that each light is described in a JSON object like so:

"1":
   {"state":
      {"on":true,"bri":65,"hue":44591,"sat":254,"xy":[0.1953,0.0959],
      "ct":500,"alert":"none","effect":"none","colormode":"hs","reachable":true},
   "type":"Extended color light",
   "name":"Living room",
   "modelid":"LCT001",
   "swversion":"65003148",
   "pointsymbol":
      {"1":"none","2":"none","3":"none","4":"none",
      "5":"none","6":"none","7":"none","8":"none"}
}

There’s a lot there, but you’re only going to modify a few of the properties. This is another aspect of the Hue data protocol worth copying: the device receiving the data (the Bridge) should accept any valid subset of the whole message, and if it can, take action.

For each light, you’ll change four subproperties of the state property: the on property, the brightness, the hue, and the saturation. Here’s a summary of the JSON you might write to change a light (without the comments, of course):

"1":                    // The light number
   {"state":            // the light's state, including:
      {"on":true,       // whether it's on or off
      "bri":65,         // the brightness (0 - 254)
      "hue":44591,      // the hue (0 - 65280 in the CIE colorspace)
      "sat":254},       // the saturation of the color (0 - 254)
   }
}

You might want to change the names of your lights to reflect where they’re located in your house as well. To try this, enter the following in the debug tool:

URL:

/api/MoodSetterApp/lights/1/

Body:

{"name": "First Light"}

The response should be:

[
   {
      "success": {
         "/lights/1/name": "First Light"
      }
   }
]

And to change the state, try:

URL:

/api/MoodSetterApp/lights/1/state

Body:

{"on": true, "bri": 65, "hue": 44591, "sat": 254}

You should get a success message for every property you changed (another good general principle to note), and the light should now be a pleasant blue-lavender color.

You can’t actually send the whole JSON object using the REST API at once. You have to set the state of a given light, then the name of a given light separately.

If you’re not familiar with lighting color theory, the hue and saturation properties may be new to you. Philips uses a colorspace called the CIE, a map devised in 1931 by the International Commission on Illumination (CIE) to describe the color of light in a uniform way. Briefly, the CIE scheme maps color into two parts: the luminance and chromaticity. The luminance refers to the relative value of a color on a black-to-white scale, while the chromaticity refers to the relative value of the color. You can think of it this way: black, white, and gray all have the same chromaticity, but vary in their luminance. Figure 6-4 shows the CIE color space chromaticity diagram.

Figure 6-4. The CIE color diagram (image courtesy of Wikipedia)

As you change the hue of a lamp, you’ll see it change around the CIE color space, moving from red at the low end, through all the other colors in the middle, and back to red. As you change the saturation, you’ll see the color fade from a vibrant color to a paler tint.

For a Hue hub with three lights, the default package, you might send a JSON object like this:

{"1":
   {"state":
      {"on":true,"bri":65,"hue":44591,"sat":254}
   },
"2":
   {"state":
      {"on":true,"bri":254,"hue":13122,"sat":211}
   },
"3":
   {"state":
      {"on":true,"bri":255,"hue":14922,"sat":144}
   }
}

This JSON object will be the payload of the first of two NDEF records you’ll write to the NFC tags used in this app. As mentioned before, you’ll send it as a MIME type, text/hue.

As you’ve probably noticed from the debug tool, the Hue’s request API is RESTful. To get data, you use the format /api/MoodSetterApp/ then add on the specifics you want and make an HTTP GET request. For example, to get the state of light 1, it’s /api/MoodSetterApp/lights/1/state. To change data, you use the same basic format with a PUT request. In the app you’re building, you’ll assemble a URL to make HTTP requests to the hub, one to PUT new data like so:

url: 'http://' + hub.ipaddress + '/api/' + hub.username
            + '/lights/' + lightId + '/state',

The other will GET data from the hub:

url: 'http://' + hub.ipaddress + '/api/' + hub.username,

Since the API is just REST URLs and JSON, you can simplify the app by using zepto.js, a slimmed-down version of the popular JQuery library. You’ll see that in the HTML head in The User Interface.

After that, it’s time for the usual housekeeping functions, initialize() and bindEvents(). As you can see here bindEvents() initializes listeners for all your user controls, as well as for pausing and resuming the app:

   /*
      Application constructor
   */
   initialize: function() {
      this.bindEvents();
      console.log("Starting Mood Setter app");
   },

   /*
      binds events that are required on startup to listeners.
   */
   bindEvents: function() {
      document.addEventListener('deviceready', this.onDeviceReady, false);

      // hue faders from the UI: brightness, hue, saturation:
      bri.addEventListener('touchend', app.setBrightness, false);
      hue.addEventListener('touchend', app.setHue, false);
      sat.addEventListener('touchend', app.setSaturation, false);
      lightOn.addEventListener('change', app.setLightOn, false);
      lightNumber.addEventListener('change', app.getHueSettings, false);

      // buttons from the UI:
      modeButton.addEventListener('click', app.setMode, false);
      songs.addEventListener('change', app.onSongChange, false);
      playButton.addEventListener('touchstart', app.toggleAudio, false);
      stopButton.addEventListener('touchstart', app.stopAudio, false);

      // pause and resume functionality for the whole app:
      document.addEventListener('pause', this.onPause, false);
      document.addEventListener('resume', this.onResume, false);
   },

In the onDeviceReady() handler, you’re going to make the initial query to the Hue hub for settings using a function called findControllerAddress() that you’ll write shortly. You’ll also set the read/write mode of the app. You’re also going to set up three NFC listeners. The first two will listen for any NFC-formatable or NDEF tag, so you can write to it in write mode. The third will listen for MIME-types, specifically for the text/hue type. Any tag with a record containing that MIME-type should contain data for you to set the lights, and ideally, a second record for playing music as well. In the MIME media handler, you’ll need to differentiate between read and write mode. You’ll see that later on.

The handler ends with a call to a new function, getSongs(), which you’ll see shortly. It looks up the directory you assigned for music and populates the selector in the HTML with the names and URIs of the songs:

   /*
       runs when the device is ready for user interaction.
   */
   onDeviceReady: function() {
      app.clear();                   // clear any messages onscreen
      app.findControllerAddress();   // find address and get settings
      app.setMode();                 // set the read/write mode for tags

      // listen for NDEF Formatable tags (for write mode):
      nfc.addNdefFormatableListener(
         app.onWritableNfc,          // tag successfully scanned
         function (status) {         // listener successfully initialized
            console.log("Listening for NDEF-formatable tags.");
         },
         function (error) {          // listener fails to initialize
            app.display("NFC reader failed to initialize " +
               JSON.stringify(error));
         }
      );

      // listen for NDEF tags so you can overwrite MIME message onto them
      nfc.addNdefListener(
         app.onWritableNfc,          // NDEF type successfully found
         function() {                // listener successfully initialized
            console.log("listening for Ndef tags");
         },
         function(error) {           // listener fails to initialize
            console.log("ERROR: " + JSON.stringify(error)); }
      );

      // listen for MIME media types of type 'text/hue' (for read or write)
      // Android calls the most specific listener, so text/hue tags end up here
      nfc.addMimeTypeListener(
         app.mimeType,               // what type you're listening for
         app.onMimeMediaNfc,         // MIME type successfully found
         function() {                // listener successfully initialized
            console.log("listening for mime media tags");
         },
         function(error) {           // listener fails to initialize
            console.log("ERROR: " + JSON.stringify(error)); }
      );

      app.getSongs();                // load the drop-down menu with songs
   },

After onDeviceReady(), add your old workhorse handlers, display() and clear(), for showing messages in the message div. They’re the same as usual here:

   /*
      appends @message to the message div:
   */
   display: function(message) {
      var textNode = document.createTextNode(message),
         lineBreak = document.createElement("br");      // a line break

      messageDiv.appendChild(lineBreak);                // add a line break
      messageDiv.appendChild(textNode);                 // add the message node
   },

   /*
      clears the message div:
   */
   clear: function() {
      messageDiv.innerHTML = "";
   },

Next come your first event handlers, onPause(), onResume(), and the NFC event handlers. These are the only events your app will listen for that aren’t generated directly by the user controls. They’re pretty basic. The first two check the state of media playback, and either pause or resume it as appropriate:

   /*
      This is called when the app is resumed
   */
   onResume: function() {
      if (app.musicState === Media.MEDIA_PAUSED) {
         app.startAudio();
      }
   },

   /*
      runs when an NdefListener or NdefFormatableListener event occurs.
   */
   onWritableNfc: function(nfcEvent) {
      if (app.mode === "write") {
         app.makeMessage();  // in write mode, write to the tag
      }
   },

The NFC event handlers will do just that: handle NFC events. The onWritableNfc handler is the handler for both the NdefListener and the NdefFormatableListener. The formatable listener lets you write to any blank tag that can be formatted, and the more generic NdefListener lets you overwrite existing NFC tags with MIME media-types when you’re in write mode. For example, if you had a tag that you’d used for a previous application, and that application used a MIME type that’s not the one you’re listening for in the MimeTypeListener, the NdefListener would catch it.

The onMimeMediaNfc() handler gets called only when one of your tags with the MIME-type text/hue shows up. If you’re in read mode, it reads the tag and attempts to change the music and the lights. If you’re in write mode, it overwrites the tag:

   /*
      runs when an NdefListener or NdefFormatableListener event occurs.
   */
   onWritableNfc: function(nfcEvent) {
      if (app.mode === "write") {
         app.makeMessage();  // in write mode, write to the tag
      }
   },

   /*
      runs when a MimeMedia event occurs.
   */
   onMimeMediaNfc: function(nfcEvent) {
      var tag = nfcEvent.tag;

      if (app.mode === "read") {   // in read mode, read the tag
         // when app is launched by scanning text/hue tag
         // you need to add a delay so the call to get the
         // hub address can finish before you call the api.
         // if you have the address, delay 0, otherwise, delay 50:
         var timeout = hub.ipaddress ? 0 : 500;

         setTimeout(function() {
            app.readTag(tag);
         }, timeout);

      } else {               // if you're in write mode
         app.makeMessage();  // in write mode, write to the tag
      }
   },

Since tag actions depend on the mode you’re in, you need a mode handler. This is the event handler for the mode button. You can see where it’s initialized in bindEvents(), previously. It simply changes the app.mode variable, and the text of the tag mode div so the user knows what mode she’s in:

   /*
      Sets the tag read/write mode for the app.
   */
   setMode: function() {
      if (app.mode === "write") {    // change to read mode
         app.mode = "read";
         tagModeMessage.innerHTML = "Tap a tag to read its settings.";
      } else {                       // change to write mode
         app.mode = "write";
         tagModeMessage.innerHTML = "Tap a tag to write current settings.";
      }
      modeValue.innerHTML = app.mode; // set text in the UI
   },

Once the basic initialization housekeeping is done, you need to query the hub, get the settings you need, and copy them into the hub object. The querying is all done using the jQuery ajax function, from the Zepto JS library that you’re using. The findControllerAddress() function shown here makes an Ajax query to Meet Hue’s IP locator page to see if it returns any local hub IP addresses. If if finds one, it sets hub.ipaddress. If not, it prompts the user that no hub was found:

   /*
      Find the Hue controller address and get its settings
   */
   findControllerAddress: function() {
      $.ajax({
         url: 'http://www.meethue.com/api/nupnp',
         dataType: 'json',
         success: function(data) {
            // expecting a list with a property called internalipaddress:
            if (data[0]) {
               hub.ipaddress = data[0].internalipaddress;
               app.getHueSettings();    // copy the Hue settings locally
            } else {
               navigator.notification.alert(
                  "Couldn't find a Hue on your network");
            }
         },
         error: function(xhr, type){    // alert box with the error
            navigator.notification.alert(xhr.responseText +
               " (" + xhr.status + ")", null, "Error");
         }
      });
   },

hub.ipaddress = data[0].internalipaddress;

After you’ve found the hub, you need to register your username and app name with it. The following functions, ensureAuthorized() and authorize(), take care of that. The first, ensureAuthorized(), just checks with the hub to see if your username and app name are registered with it. If it fails, it calls authorize() and attempts to get authorization. Both of these prompt the user when they fail, as you need to press the hub’s link button to authorize a new user and app:

   /*
      Checks that the username is authorized for this hub.
   */
   ensureAuthorized: function() {
      var message;      // response from the hub

      // query the hub:
      $.ajax({
         type: 'GET',
         url: 'http://' + hub.ipaddress + '/api/' + hub.username,
         success: function(data){      // successful reply from the hub
            if (data[0].error) {
               // if not authorized, users gets an alert box
               if (data[0].error.type === 1) {
                  message = "Press link button on the hub.";
               } else {
                  message = data[0].error.description;
               }
               navigator.notification.alert(message,
                  app.authorize, "Not Authorized");
            }
         },
         error: function(xhr, type){    // error message from the hub
            navigator.notification.alert(xhr.responseText +
               " (" + xhr.status + ")", null, "Error");
         }
      });
   },

   /*
      Authorizes the username for this hub.
   */
   authorize: function() {
      var data = {                      // what you'll send to the hub:
         "devicetype": hub.appTitle,    // device type
         "username": hub.username       // username
      },
      message;                          // reply from the hub

      $.ajax({
         type: 'POST',
         url: 'http://' + hub.ipaddress + '/api',
         data: JSON.stringify(data),
         success: function(data){       // successful reply from the hub
            if (data[0].error) {
               // if not authorized, users gets an alert box
               if (data[0].error.type === 101) {
                  message = "Press link button on the hub, then tap OK.";
               } else {
                  message = data[0].error.description;
               }
               navigator.notification.alert(message,
                  app.authorize, "Not Authorized");
            } else {                   // if authorized, give an alert box
               navigator.notification.alert("Authorized user " +
                  hub.username);
               app.getHueSettings();   // if authorized, get the settings
            }
         },
         error: function(xhr, type){   // error reply from the hub
            navigator.notification.alert(xhr.responseText +
               " (" + xhr.status + ")", null, "Error");
         }
      });
   },

Once you’re registered with the hub, you need to get the settings from it and copy them to your local hub object. Both findHueSettings() and authorize(), shown previously, call the function that follows. It doesn’t copy all of the hub’s settings, just the ones you need for setting on/off, brightness, hue, and saturation for the lights that the hub is controlling:

   /*
      Get the settings from the Hue and store a subset of them locally
      in hub.lights.  This is for both setting the controls, and for
      writing to tags:
   */
   getHueSettings: function() {
      // query the hub and get its current settings:

      $.ajax({
         type: 'GET',
         url: 'http://' + hub.ipaddress + '/api/' + hub.username,
         success: function(data) {
            if (!data.lights) {
               // assume they need to authorize
               app.ensureAuthorized();
            } else {
               // the full settings take more than you want to
               // fit on a tag, so just get the settings you want:
               for (var thisLight in data.lights) {
                  hub.lights[thisLight] = {};
                  hub.lights[thisLight].name = data.lights[thisLight].name;
                  hub.lights[thisLight].state = {};
                  hub.lights[thisLight].state.on =
                     data.lights[thisLight].state.on;
                  hub.lights[thisLight].state.bri =
                     data.lights[thisLight].state.bri;
                  hub.lights[thisLight].state.hue =
                     data.lights[thisLight].state.hue;
                  hub.lights[thisLight].state.sat =
                     data.lights[thisLight].state.sat;
               }
               app.setControls();
            }
         }
      });
   },

The function you just wrote, which gets the settings, implies a complementary function to put new settings back to the Hue hub. You’ll need such a function for whenever the user changes the lighting controls. So here’s putHueSettings(), which takes a JSON object, converts it to a string, and sends it to the hub:

   /*
      sends settings to the Hue hub.
   */
   putHueSettings: function(settings, lightId) {
      // if no lightId is sent, assume the current light:
      if (!lightId) {
         lightId = hub.currentLight;
      }

      // if the light's not on, you can't set the other properties.
      // so delete the other properties before sending them.
      // if "on" is a property and it's false:
      if (settings.hasOwnProperty("on") && !settings.on) {
         // go through all the other properties:
         for (var prop in settings) {
            // if this property is not inherited:
            if (settings.hasOwnProperty(prop)
               && prop != "on") {      // and it's not the "on" property
               delete(settings[prop]); // delete it
            }
         }
      }

      // set the property for the light:
      $.ajax({
         type: 'PUT',
         url: 'http://' + hub.ipaddress + '/api/' + hub.username +
            '/lights/' + lightId + '/state',
         data: JSON.stringify(settings),
         success: function(data){
            if (data[0].error) {
               navigator.notification.alert(JSON.stringify(data),
                  null, "API Error");
            }
         },
         error: function(xhr, type){
            navigator.notification.alert(xhr.responseText + " (" +
               xhr.status + ")", null, "Error");
         }
      });
   },

This function doesn’t care what the settings are, nor does it bother to update the local hub object with the settings. It leaves all of that to the functions that call it. However, it handles one important error: the Hue won’t let you set a given light’s hue, brightness, and saturation if the light is off. So this function checks to see if the settings being sent contain an “on” property and if it’s false. If so, then the function eliminates the other properties and just sends the “on” property (which is set to false).

The next set of functions are the user interface control event handlers.

With the hub settings obtained by getHueSettings(), you can set the user interface controls to match the current settings of the lights they’re controlling. At the end of a successful request, getHueSettings() calls the following function, setControls(), to update the value of the UI controls:

   /*
      Set the value of the UI controls using the values from the Hue:
   */
   setControls: function() {
      hub.currentLight = lightNumber.value;

      // set the names of the lights in the dropdown menu:
      // (in a more fully developed app, you might generalize this)
      lightNumber.options[0].innerHTML = hub.lights["1"].name;
      lightNumber.options[1].innerHTML = hub.lights["2"].name;
      lightNumber.options[2].innerHTML = hub.lights["3"].name;

      // set the state of the controls with the current choice:
      var thisLight = hub.lights[hub.currentLight];
      hue.value = thisLight.state.hue;
      bri.value = thisLight.state.bri;
      sat.value = thisLight.state.sat;
      lightOn.checked = thisLight.state.on;
   },

The user interface controls for the lighting are handled by a series of event handlers, each of which sets a specific property of the light. Figure 6-5 shows a detail of the lighting controls. The drop-down menu’s event handler is getHueSettings(), which gets the current settings and updates the other controls.

Figure 6-5. The lighting controls for the app

The on, brightness, hue, and saturation controls apply to whatever light is chosen in the Light Location drop-down menu. Each of the individual event handlers gets the value from the control, then sets that value in the local hue object. Finally, each handler uses the new setting to update the Hue hub:

   /*
      These functions set the properties for a Hue light:
      Brightness, Hue, Saturation, and On State
   */
   setBrightness: function() {
      // get the value from the UI control:
      var thisBrightness = parseInt(bri.value, 10);
      // get the property from hub object:
      var thisLight = hub.lights[hub.currentLight];
      // change the property in hub object:
      thisLight.state.bri = thisBrightness;
      // update Hue hub with the new value:
      app.putHueSettings({ "bri": thisBrightness });
   },

   setHue: function() {
      // get the value from the UI control:
      var thisHue = parseInt(hue.value, 10);
      // get the property from hub object:
      var thisLight = hub.lights[hub.currentLight];
      // change the property in hub object:
      thisLight.state.hue = thisHue;
      // update Hue hub with the new value:
      app.putHueSettings( { "hue": thisHue } );
   },

   setSaturation: function() {
      // get the value from the UI control:
      var thisSaturation = parseInt(bri.value, 10);
      // get the property from hub object:
      var thisLight = hub.lights[hub.currentLight];
      // change the property in hub object:
      thisLight.state.sat = thisSaturation;
      // update Hue hub with the new value:
      app.putHueSettings({ "sat": thisSaturation });
   },

   setLightOn: function() {
      // get the value from the UI control:
      var thisOn = lightOn.checked;
      // get the property from hub object:
      var thisLight = hub.lights[hub.currentLight];
      // change the property in hub object:
      thisLight.state.on = thisOn;
      // update Hue hub with the new value:
      app.putHueSettings( { "on": thisOn } );
   },

These event handlers are the functions that ensure that the UI controls, the local hue object, and the remote Hue hub are in sync.

When you get to the tag-reading functionality, you’ll need a function that takes all the lighting properties from the tag and writes them to the Hue hub. You can assume that this function is getting the states for all the lights passed to it as a parameter. Group that function with the previous functions:

   /*
      Sets the state for all the lights. Assumes it's getting
      a JSON object like this:
      {
       "1": {"state": {"on":true,"bri":65,"hue":44591,"sat":254}},
       "2": {"state": {"on":true,"bri":254,"hue":13122,"sat":211}},
       "3": {"state": {"on":true,"bri":255,"hue":14922,"sat":144}}
      }
   */
   setAllLights: function(settings) {
      for (var thisLight in settings) {
          app.putHueSettings(settings[thisLight].state, thisLight);
      }
   },

Now that the lighting user interface elements are taken care of, it’s time to write the event handlers for the music playback. Figure 6-6 shows a detail of those controls.

Figure 6-6. The music controls for the app

The first music event handler to write is the getSongs() handler. This handler is called in the onDeviceReady() handler. It uses PhoneGap’s File API to read the directory listing of the music directory and get a list of all the song names and URIs to populate the music selector in the UI.

This function is heavily dependent on callbacks, so it helps to start reading it from the bottom. It starts by looking for the directory using resolveLocalFileSystemURI(), and when that succeeds, it calls foundDirectory(). That looks for the directory entries, and when it succeeds, it calls foundFiles() to fill the selector in the HTML. There’s a common failure handler for all of these in case they fail: an alert box pops up with the cause of the failure.

   /*
      gets a list of the songs in your music directory and
      populates an options list in the UI with them
   */
    getSongs: function() {
      // failure handler for directoryReader.readEntries():
      var failure = function(error) {
         alert("Error: " + JSON.stringify(error));
      };

      // success handler for directoryReader.readEntries():
      var foundFiles = function(files) {
         if (files.length > 0) {
            // clear existing songs
            songs.innerHTML = "";
         } else {
            navigator.notification.alert(
               "Use `adb` to add songs to " + app.musicPath, {}, "No Music");
         }

         // once you have the list of files, put the valid ones in the selector:
         for (var i = 0; i < files.length; i++) {
            // if the filename is a valid file:
            if (files[i].isFile) {
               // create an option element:
               option = document.createElement("option");
               // value = song's filepath:
               option.value = files[i].fullPath;
               // label = song name:
               option.innerHTML = files[i].name;
               // select the first one and add it to the selector:
               if (i === 0) { option.selected = true; }
               songs.appendChild(option);
            }
         }
         app.onSongChange();        // update the current song
      };

      // success handler for window.resolveLocalFileSystemURI():
      var foundDirectory = function(directoryEntry) {
         var directoryReader = directoryEntry.createReader();
         directoryReader.readEntries(foundFiles, failure);
      };

      // failure handler for window.resolveLocalFileSystemURI():
      var missingDirectory = function(error) {
         navigator.notification.alert("Music directory " + app.musicPath +
            " does not exist", {}, "Music Directory");
      };

      // look for the music directory:
      window.resolveLocalFileSystemURI(app.musicPath,
        foundDirectory, missingDirectory);
   },

The function just shown and the event listener for the song picker call a function called onSongChange(), which changes the URI of the song. This, in turn, calls setSong(), which pulls the song name out of the URI it’s handed, and sets up the conditions for playing a new song:

   /*
      changes the song URI and sets the new song:
   */
   onSongChange: function(event) {
      var uri = songs[songs.selectedIndex].value;
      app.setSong(uri);
   },

   /*
      sets the song URI
   */
   setSong: function(uri) {
      if (uri !== app.songUri) {
         app.stopAudio();            // stop whatever is playing
         app.songPlaying = null;     // clear the media object
         app.musicState = 0;         // clear the music state
         app.songUri = uri;          // saves the URI of the song
         // uses the filename for a title
         app.songTitle = uri.substring(uri.lastIndexOf('/')+1);
         $(songs).val(uri);          // ensure the UI matches selection
      }
   },

You’ll see setSong() called directly without onSongChange() later, when you read a new song from an NFC tag.

The play/pause control is handled by a function called toggleAudio(), which checks the state of the media controller, and either starts playback, pauses it, or resumes it, as appropriate:

  /*
      toggles audio playback depending on current state of playback.
   */
   toggleAudio: function(event) {
      switch(app.musicState) {
         case undefined:             // if playback is undefined
         case Media.MEDIA_NONE:      // or if no media is playing
            app.startAudio();        // start playback
            break;
         case Media.MEDIA_STARTING:  // if media is starting
            state = "music starting";// no real change
            break;
         case Media.MEDIA_RUNNING:   // if playback is running
            app.pauseAudio();        // pause it
            break;
         case Media.MEDIA_PAUSED:    // if playback is paused
         case Media.MEDIA_STOPPED:   // or stopped
            app.playAudio();         // resume playback
            break;
      }
   },

The startAudio() function is called by the play button, and you’ll need it for when you read tags with valid song URIs on them as well. If there’s no playback currently, this function will check to see if it’s got a song name, and if so, start playback with it.

As you saw earlier, the Media API uses three callback functions: success, error, and status. All three of those are shown here as well. They don’t do much, except for the status handler, which updates the playback status:

   /*
      Start playing audio from your device
   */
   startAudio: function() {
      var success = false;

      // attempt to instantiate a song:
      if (app.songPlaying === null) {
         // Create Media object from songUri
         if (app.songUri) {

            app.songPlaying = new Media(
               app.songUri,      // filepath of song to play
               app.audioSuccess, // success callback
               app.audioError,   // error callback
               app.audioStatus   // update the status callback
            );
         } else {
            navigator.notification.alert("Pick a song!");
         }
      }

      // play the song:
      app.playAudio();
   },

   /*
      called when playback successfully initiated.
   */
   audioSuccess: function() {
      console.log("Audio success");
   },

   /*
      displays an error if there's a problem with playback.
   */
   audioError: function(error) {

      // Without timeout message is overwritten by "Currently Playing: ..."
      setTimeout(function() {
         app.display("Unable to play song.");
      }, 300);

   },

   /*
      updates the running audio status.
   */
   audioStatus: function(status) {
      app.musicState = status;
   },

The play, pause, and stop handlers are all very similar. They check to see that there’s current media playback, take their action, update the button labels, and print the status and song name to the message div. Here they are:

   /*
      resumes audio playback and changes state of the play button.
   */
   playAudio: function() {
      if (app.songPlaying) {             // if there's current playback
         app.songPlaying.play();         // play
         playButton.innerHTML = "Pause"; // update the play/pause button

         // clear the message div and display song name and status:
         app.clear();
         app.display("Currently playing: " + app.songTitle);
      }
   },

   /*
      pauses audio playback and changes state of the play button.
   */
   pauseAudio: function() {
      if (app.songPlaying) {             // if there's current playback
         app.songPlaying.pause();        // pause
         playButton.innerHTML = "Play";  // update the play/pause button

         // clear the message div and display song name and status:
         app.clear();
         app.display("Paused playing: " + app.songTitle);
      }
   },

   /*
      stops audio playback and changes state of the play button.
   */
   stopAudio: function() {
       if (app.songPlaying) {            // if there's current playback
         app.songPlaying.stop();         // stop
         playButton.innerHTML = "Play";  // update the play/pause button

         // clear the message div and display song name and status:
         app.clear();
         app.display("Stopped playing: " + app.songTitle);
      }
   },

With hub communication, music, and user interface out of the way, you can write the tag-reading and -writing functions. The first of these, readTag(), has the same structure as similar functions for reading that you’ve written already. It will read the tag, extract all the NDEF records in the NDEF message, and attempt to parse them. If it’s got a URI record, it will verify that the URI is a song’s address, and attempt to play it. If it’s got a MIME record of type text/hue, it will assume the record contains the JSON-encoded state for the lights, and attempt to send those settings to the hub:

   /*
      reads an NDEF-formatted tag.
   */
   readTag: function(thisTag) {
      var message = thisTag.ndefMessage,
         record,
         recordType,
         content;

      for (var thisRecord in message) {
         // get the next record in the message array:
         record = message[thisRecord];
         // parse the record:
         recordType = nfc.bytesToString(record.type);
         // if you've got a URI, use it to start a song:
         if (recordType === nfc.bytesToString(ndef.RTD_URI)) {

            content = ndef.uriHelper.decodePayload(record.payload);

            // make sure the song exists
            window.resolveLocalFileSystemURI(
               content,
               function() {
                  app.setSong(content);
                  app.startAudio();
               },
               function() {
                  navigator.notification.alert("Can't find " + content,
                     {}, "Missing Song");
               }
            );
         }

         // if you've got a hue JSON object, set the lights:
         if (recordType === 'text/hue') {
            // tag should be TNF_MIME_MEDIA with a type 'text/hue'
            // assume you get a JSON object as the payload
            // JSON object should have valid settings info for the hue
            // http://developers.meethue.com/1_lightsapi.html

            content = nfc.bytesToString(record.payload);
            content = JSON.parse(content);    // convert to JSON object

            app.setAllLights(content.lights); // use it to set lights
         }
      }
   },

For write mode, you’ll need to make an NDEF message with two NDEF records, one for the song and one for the lights. The lighting record should come first, so that it can trigger the MIME-type listener when you’re in read mode. Since the hub object contains some properties that are not part of the Hue protocol, you’ll need to extract the lights property and make a new object with just it. That’ll be your first NDEF record. The second will be the song name.

Once you’ve got your NDEF record assembled, you can use the same writeTag() function you’ve used before to write the message to the tag. And once you’re done with that, you’ve reached the end of the app!

   /*
      makes an NDEF message and calls writeTag() to write it to a tag:
   */
   makeMessage: function() {
      var message = [];

      // put the record in the message array:
      if (hub.lights !== {}) {
         var huePayload = JSON.stringify({"lights": hub.lights});
         var lightRecord = ndef.mimeMediaRecord(app.mimeType, huePayload);
         message.push(lightRecord);
      }
      if (app.songUri !== null) {
         var songRecord = ndef.uriRecord(app.songUri);
         message.push(songRecord);
      }

      //write the message:
      app.writeTag(message);
   },

   /*
      writes NDEF message @message to a tag:
   */
   writeTag: function(message) {
      // write the record to the tag:
      nfc.write(
         message,                  // write the record itself to the tag
         function () {             // when complete, run this callback function:
            app.clear();           // clear the message div
            app.display("Wrote data to tag.");     // notify user in message div
            navigator.notification.vibrate(100);   // vibrate the device as well
         },
         function (reason) {       // runs if the write command fails
            navigator.notification.alert(reason,
               function() {}, "There was a problem");
         }
      );
   }
};        // end of app

Again, the full source listing for this app can be found on GitHub.

When you run the app, it will check whether it’s registered with the Hue hub. If not, it will prompt you to press the link button in order to do so. Once it’s contacted the hub, it will populate the Light Location drop-down. From there, you’ll be able to change the lights and music independently of each other, and of the mode. If you’re in write mode, bringing an NDEF formatable tag in range will automatically write your current settings to that tag. In read mode, the app will automatically read the tag for a song and a set of lighting settings.

You may find that you need to hold the tag close to the phone without moving for a second or so in order to get all the settings to work. Pulling away before the device has read the tag and acted on it will cause read errors. This is the most you’ve probably written to a tag before, and it shows you that the interaction between reading and writing and the actions they are meant to trigger can have effects on the physical interaction between user, device, and tag. The more you can write your program to keep them independent of each other, the better the interaction will be.

Although your app will read tags just fine when it’s in the foreground, you really want it to read text/hue MIME types even when it’s in the background. You learned how to make this happen in Chapter 5. Open your AndroidManifest.xml file and add a new intent filter as follows:

 <intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <data android:mimeType="text/hue" />
 </intent-filter>

Once you’ve updated the app, quit it, and try tapping a tag that’s got a text/hue record on it. The app should launch automatically, change the lights, and play the music.