From CENS Urban Sensing

Contents 1 Latest Version = Tag 6 2 Installing the Application 2.1 Installing the application using the phone's web browser 2.2 If the above method doesn't work for you... 2.3 Now you must do this each time you install (or reinstall) the application 3 Quick Guide for using the application 3.1 Starting the application 3.2 Exiting the application 4 Notes on errors you may see 4.1 Common Errors 5 Using the application 5.1 Record Screen 5.1.1 Fields 5.1.2 Options 5.2 Upload Screen 5.2.1 Fields 5.2.2 Options 5.3 GPS Screen 5.3.1 Fields 5.3.2 Options 6 Where's the Data?

Latest Version = Tag 6

Changes for Tag 6:

• Changed the project id to be 105 instead of 84.
• Fixed bug: Month of date-time was off-by-one.
• Fixed bug: The status of the GPS device would read "Not Started" if the GPS device had a GPS connection before you started the application. This is now fixed.

Changes for Tag 5:

• Fixed bug: When going from no GPS lock to a GPS lock, sometimes the phone doesn't see it, and continues to report isValid = False. I think this is fixed, or at least, is less likely to happen. However, if the GPS device fails to notice that it's now outside, there's nothing the phone can do about it. You have to reboot the GPS device.
• Fixed bug: Multiple uploads of the same record when there are less than 10 records available to upload.
• Fixed bug: Rapid capture of GPS (more than once a second), instead of capturing every 10 seconds (or whatever you set it at) like it should be doing.
• Fixed bug: Error alert for "LocationException: Null". This is now hidden from the user.
• Fixed bug: The GPS Enable/Disable field is present, but not used. This field has been removed.
• Feature: Decreased the timeout for acquiring a location from the GPS device. This makes the application feel more responsive.
• Feature: In the Record screen, dynamically display GPS status.
• Feature: In the GPS screen, dynamically update GPS information.
• Known/Reported bug: The GPS screen indicates that the GPS device is "Available", even if it's not.

Installing the Application

Installing the application using the phone's web browser

1. Open the web browser: for most phones, click on the main page, select the 'globe' icon.
2. Browse to http://www.lecs.cs.ucla.edu/~adparker/locationscape
3. If & when you are prompted for what kind of connection to use, select "Internet GPRS"
4. Click on the latest release, and install it into your phone's memory card (the external card, not the internal one. The reason is so that the application will keep its data in the same memory location in which it is installed, and your external card has a lot more memory.)
5. If you already have a previous version installed, just install on top of it.

If the above method doesn't work for you...

1. ONLY IF THE ABOVE FAILED, then download the JAR and JAD files directly onto your computer, found here:
   1. http://www.lecs.cs.ucla.edu/~adparker/locationscape/tag6/Locationscape.jar
   2. http://www.lecs.cs.ucla.edu/~adparker/locationscape/tag6/Locationscape.jad
2. And then copy the files over to your phone and use the file manager to browse to the .JAD file and click on it. The installer application should start.

Now you must do this each time you install (or reinstall) the application

1. After you have downloaded and installed the application, you need to give the application permission to retrieve location information.
2. Note: app mgr is really slow, especially if you have a lot of applications installed.
3. On your phone, go to Menu ->Tools-> Application Manager. There will be two entries for Locationscape. Select the one that says "Locationscape, installed". The other one, that you can ignore, is called "Locationscape.jad, Not installed."
4. Choose "Suite Settings" -> Positioning -> "Ask First Time", then "Back", "Exit"

Quick Guide for using the application

Starting the application

1. Make sure your GPS device is turned on.
2. Start the application
3. Make sure the "User Name" field is set to your user name (this is what gets stored in Sensorbase).
4. Go to "Actions" and select "Start Recording"
5. Go to "Options" -> "Upload Screen"
6. In the Upload Screen, select "Options" -> "Enable Upload".

Exiting the application

1. Hit Exit.

Notes on errors you may see

It's a little too verbose in reporting errors, which will get fixed.

Common Errors

For the errors below, with the exception of "Unhandled Exception", you normally don't have to do anything except acknowledge the alert. The application should just keep running.

• Non-200 Response --- This means that Sensorbase returned a non-200 response. Most likely, some transient network error occurred and the upload failed for any number of reasons. If you get this every now and then (like once every couple of minutes) that's OK. If it happens more frequently, then there's something really wrong, either with the data being uploaded (maybe the table format got changed, and you're running an old version of Locationscape, or user/password failed when logging into sensorbase, or the record store on the phone is horribly corrupted, or sensorbase.org/alpha/upload.php got removed, or...)
  • If you keep getting this over and over, maybe the record store is corrupted. Try "Clear Records" in the Record Screen, or uninstall and then reinstall the application (just doing a reinstall is not enough, since that doesn't delete the record store).

• Unhandled Exception --- This is bad. It is more likely to happen if you have it set to query GPS information more frequently than once a second while simultaneously uploading. Anyway, something bad happened that I need to fix. You should exit and restart the application.

Using the application

There are 3 screens:

1. Record Screen
2. Upload Screen
3. GPS Screen

You use the "Options" menu to switch between the screens.

Record Screen

• This is the first screen that comes up. This is where you control if and how data is captured.

Fields

• Records Queued: This is the number of records that are queued up on the phone, ready for upload. Records are persistent across application invocations.
• User name: This is an editable field that contains your use name. Please change this to be your user name. This will be saved across application invocations.
• GPS State: This is the current state of the GPS Device.
• Actions:
  • Stop Recording: Stop capturing data.
  • Start Recording: Start capturing data.
  • Clear Records: Delete all the records from the queue.
  • Show Location: Query the GPS device for your current location (this will be going away, as I have something nicer, described later.)
  • Repeat every(ms): How often to query the location, in millliseconds. I would recommend not going below 1000 milliseconds.

Options

• -> Record Screen Jump to the Record Screen.
• -> GPS Screen Jump to the GPS Screen.

Upload Screen

• This is where you control and monitor the upload of your data.

Fields

• Debug Ignore this. It's going away.
• Status
  • Idle This is the starting state. It's not doing anything.
  • Uploading It's actively trying to upload data.
  • WAITING It wants to upload, but is waiting for more data to be captured.
  • SLEEPING It encountered an error and is going to sleep for a bit before trying to upload again.
  • STOPPED You told it to stop uploading.
• Records Queued Number of records waiting to be uploaded.
• Records Sent Number of records that have been successfully uploaded since the application has started.

Options

• -> Record Screen Jump to the Record Screen.
• * Enable Upload Start uploading!
• * Disable Upload Stop uploading!

GPS Screen

• This screen shows you details of the GPS data retrieved "on demand" from the GPS device.

Fields

• timestamp [MILLISECONDS] The time stamp at which the data was collected. This timestamp should represent the point in time when the measurements were made. Implementations make best effort to set the timestamp as close to this point in time as possible. The time returned is the time of the local clock in the terminal in milliseconds using the same clock and same time representation as System.currentTimeMillis().

• isValid Whether or not the GPS unit said that the location data was valid.

• State The current state of this LocationProvider. Valid values are AVAILABLE, OUT_OF_SERVICE, and TEMPORARILY_UNAVAILABLE

• lat [DEGREES] Positive values indicate eastern longitude and negative values western longitude. The longitude is given in WGS84 datum.

• lon [DEGREES] Positive values indicate northern latitude and negative values southern latitude. The latitude is given in WGS84 datum.

• altitude [METERS] Altitude is defined to mean height above the WGS84 reference ellipsoid. 0.0 indicates a location at the ellipsoid surface, negative values mean the location is below the ellipsoid surface,

• horizontalAccuracy [METERS] The horizontal accuracy is the RMS (root mean square) of east accuracy (latitudinal error in meters, 1-sigma standard deviation), north accuracy (longitudinal error in meters, 1-sigma).

• verticalAccuracy [METERS] The accuracy of the location in meters in vertical direction (orthogonal to the WGS84 reference ellipsoid surface, 1-sigma standard deviation).

• course [DEGREES] The course of travel made good in degrees relative to true north. The value is always in the range [0.0,360.0) degrees.

• speed [METERS / SECOND] The ground speed in meters per second (m/s) at the time of measurement. The speed is always a non-negative value. Note that unlike the coordinates, speed does not have an associated accuracy because the methods used to determine the speed typically are not able to indicate the accuracy.

Options

• -> Record Screen Jumps to the Record Screen.
• -> Upload Screen Jumps to the Upload Screen.
• * Update Display Fetches data from your GPS Device. Note that this can take several seconds.

Where's the Data?

Right now it's going into a table that only I can see. On the TODO list is to allow you to specify the sensorbase project and table. Sorry!