How to send a stream with your Android phone (PhoneGap + jQuery Mobile).

 

0. Introduction

This easy tutorial describes how to make an Android application with PhoneGap & jQuery Mobile to send streams to Carriots.
In this project you will learn how to:

  • Set up your development environment
  • Make an easy Android application with PhoneGap & jQuery Mobile
  • Send streams to Carriots with your Android application

Difficulty:

Ingredients:

  • Your favorite IDE, in our case Eclipse
  • Android SDK
  • ADT Plugin
  • The latest copy of PhoneGap (in our case cordova-2.9.0)
  • The latest copy of JQuery Mobile (in our case JQueryMobile 1.3.2)
  • An Android phone

Music to listen: Kavinsky - Nightcall

 

1. Project Schema

This project is a quick way to create an Android application and understand how to send streams to Carriots using PhoneGap and jQuery Mobile.

Here is overall diagram of the project:

  • Schema

All the data streams sent by the phone are collected and stored in Carriots. Carriots is a huge database that collects all the information that your sensors send.

In addition to storing data, the true power of Carriots is to let you build Apps very quickly with few lines of Groovy code.

With Carriots you can build very complex Apps to support all the logic of your product on the cloud and integrate it with other devices and IT systems. But for now let’s keep it simple.

 

2. Setup the IDE

If you are a new Android developer, the best way to start is download the ADT Bundle.

ADT Bundle includes everythings you need to begin developing apps:

  • Eclipse + ADT plugin
  • Android SDK Tools
  • Android Platform-tools
  • The latest Android platform
  • The latest Android system image for the emulator

Setting Up the ADT Bundle

  • Download ADT Bundle
  • Unpack the ZIP file and save it to an appropiate location
  • Open the adt-bundle-your_platform/eclipse/ directory and launch eclipse
  • That's all!. Your IDE is already loaded with the Android Developer Tools plugin and the SDK ready to run
Aviso Be careful and do not move the eclipse or sdk directory, ADT will not be able to locate the SDK and you'll need to manually update the ADT preferences

 

3. Setup a new PhoneGap project

This point describes how to set up your development environment for PhoneGap.

PhoneGap is an open source framework for quickly building cross-platform mobile apps using HTML5, Javascript and CSS.

Launch Eclipse

Select menu item -> New project -> Android Application Project

  • New Project

Complete the remaining windows with the desired values ​​for your project.

Creating directories

In the project root directory, create this directories:

  • /libs
  • /assets/www

Copy PhoneGap libraries

  • Download PhoneGap Files (in our case 2.9.0 version)
  • Copy lib/android/cordova.js to /assets/www
  • Copy lib/android/cordova-2.9.0.jar to /libs
  • Copy lib/android/xml folder to /res
  • Add cordova-2.9.0.jar in the project Build Path.
    Right click on the libs folder, go to Build Path -> Configure Build Path -> Libraries Tab and add cordova-2.9.0.jar to the project
  • Refresh the project (F5)

Edit the main activity java file in src folder

  • Add import org.apache.cordova.*;
  • Change the visibility from private class MainActivity to public class MainActivity
  • Change the class's extend from Activity to DroidGap
  • Replace setContentView()line by super.loadUrl("file:///android_asset/www/demo1.html");
  • MainActivity.java

Configure the file AndroidManifest.xml

  • Type the following permissions between uses-sdk and application tags
  • Type on tag activity the following configuration:

Check that everything is correct

  • Create a new file named demo1.html in /assets/www with the following code:
  • Run in the simulator.
    Right click on the project and Run As -> Android Application
  • Run in your device.
    Make sure USB debugging is enabled on your device and plug it into your system. Right click on the project and Run As -> Android Application

 

4. Including JQuery Mobile

To create a complete look and feel for our app, we need JQuery mobile.

  • Create a css folder under assets/www. This will be the place for your applications css files
  • Create a vendor folder under assets/www
  • Create a jquery.mobile folder under assets/www/css. This will be the place for your JQuery Mobile css files
  • Download JQuery File (in our case 2.0.3 version)
  • Download JQueryMobile Zip File (in our case 1.3.2 version)
  • Copy .css files and the images folder from your JQueryMobile zip file to assets/www/css/jquery.mobile folder
  • css files
  • Copy .js files to assets/www/vendor
  • js files
  • Add in the head tag to demo1.html file a meta tag to provide information which will be used by JQuery Mobile to improve the device rendering
  • Add the JQuery Mobile stylesheets to demo1.html file
  • Add JQuery and JQuery Mobile .js files to demo1.html file
  • Modified demo1.html file with the following code to check that JQuery Mobile is working
  • The code will be like this:
  • Final code
  • And the result:
  • Result

 

5. Carriots Project and Device Registration

Device

If you're registered in Carriots, you have a default device already created for you.
Check your control panel and see what it looks like.
Basically you need the device id_developer that might be something like defaultDevice@myusername.
But if you want, you can create a new device and use it in this example.

Apikey

Now, go to your control panel “My account menu” and check your Apikey.
It's a big alphanumeric token like:
98346673a6377ef1fde2357ebdcb0da582b150b00cabcd5a0d83045425407ab4.
You need this number to complete the example.

6. Data Transferred from your phone to Carriots

From ypur phone you have to build a HTTP request and send the data.

  • HTTP request
    POST /streams HTTP/1.1
    Host: api.carriots.com
    Accept: application/json
    Content-Type: application/json
    carriots.apikey: YOUR APIKEY HERE
  • Data
    {
    "protocol":"v2",
    "device":"YOUR DEVICE's ID_DEVELOPER HERE",
    "at":"now",
    "data":{"test":"OK"}
    }

7. Building the project

It's time to build our interface and send a stream to Carriots

  • Edit the file demo1.html body tag and replace with the following code:
  • Create a file named application.js under assets/www. This will be the place for your javascript code
  • Add application.js file to demo1.html head tag
  • The code will be something like this:
  • demo1.html
  • In application.js file, type the code to send a stream to Carriots
Aviso Note that some values should be replaced by your own values.
  • Run in simulator or device (where you prefer), and push button to send a stream to Carriots
  • Android App (JQuery Mobile + PhoneGap)

 

8. Checking Data is collected in Carriots

If you get here, your device must be sending streams when you turn on and turn off the lights.

Its time to test our control panel and check if we have new streams.
Go to “Data management” → “Data streams” and you will see your data.

  • menu option

 

9. From here on: Enhancing the project

Now you know how to create a simple App for your Android phone and send streams to Carriots. But you can enhance this project in many ways.

In a second part of this tutorial, you will learn how to send to Carriots your custom data.