Developer Guide
This page contains instructions for configuring and building the OpenTripPlanner (OTP) Android app from the source code.
OpenTripPlanner for Android source code (i.e., this Github repo) is licensed under the Apache 2.0 license. OTP Android uses classes from the main OTP project to aid in the deserialization of OTP REST API responses. These classes are maintained in a separate Github project, are licensed under the L-GPL license per the main OTP project.
Before diving into the source, its helpful to understand the different pieces that help the OTP Android app to function. Here's a list of some components that are used in the functionality of the OTP for Android app:
-
Google Play Services
- Map visualization and interaction with Maps API V2.
- Retrieve user's location with [Location APIs] (https://developer.android.com/google/play-services/location.html).
- OTP POJOs project - Defines the objects that are used in the deserialization of REST API responses from the OTP server. We use Jackson JSON Processor to deserialize JSON responses from the server.
- OTP Server Directory (a Google Docs spreadsheet) - maintains the centralized list of OTP Server deployments and their coverage areas, so the app knows which OTP server it should communicate with to plan trips based on the user's location.
- Google Places API - Used for point-of-interest search. Provides rich results based on Google's database for areas such as the U.S. Requires a developer key (see Customization section below).
- Nominatim - Also used for point-of-interest search. Provides results for points-of-interest that are recorded in OpenStreetMap, which may provide more information than Google Places API for international locations (depending on the quality of Google Maps in the area).
![flow diagram] (https://docs.google.com/drawings/d/18WOkJlVqGvrYz3fHdeqUViJqjGpiydZ9rN1pUcBJ5Bg/pub?w=1088&h=830)
-
[APP structure] (https://github.com/CUTR-at-USF/OpenTripPlanner-for-Android/wiki/App-structure) detailed explanation of the function and internal working of the more important packages and classes that compound the app.
-
[Workflow detailed example] (https://github.com/CUTR-at-USF/OpenTripPlanner-for-Android/wiki/Workflow-example) See app's internal and external behavior, with the user interaction, to set the parameters, make a request and see the results. Good way to get familiar with intercommunication and app processes.
We are using Gradle and Android Studio for the build process and IDE, respectively.
First, you'll need a JDK installed. We recommend JDK 1.7.
(If you're interested in building v2.0.2 or lower, please see Build Instructions (v2.0.2 and lower), which was based on Eclipse and Maven.)
The OTP Android app code is versioned using Git, so you can use your favorite Git client or the integrated Android Studio Git support to clone the OTP Android repository
Here's our Github repo:
https://github.com/CUTR-at-USF/OpenTripPlanner-for-Android.git
If you plan on submitting improvements, we suggest you fork our project (instead of cloning our repo directly) and work off of your forked repo so you can commit to your own OTP Android repository and use Github's Pull Request feature to submit improvements for our review.
You'll need your own Google Places API key to point-of-interest search. Follow the "Setting up your own Google Places API key" directions in the next section to set up your key.
Next, follow the README file build instructions.
Then, run the Android project on your device or an Android emulator (emulator should be at least Android 4.2.2 to work with Play Services).
To use the Google Places API, you need a developer key. This key should be your own private key, so by default we don't include a key in the repository.
To add your own key, create a text file “opentripplanner-android/src/main/res/raw/googleplaceskey.txt” in the Android project that contains only your developer key in plain text. The app will check for this key file when using the Google Places API, and if the key exists the app will use it.
Due to compatibility issues trying to simultaneously support older versions of the OTP REST API (v0.7.X) simultaneously with newer versions, we suggest that OTP server versions be v0.9.1 or higher to work with the OTP Android app. In OTP v0.9.0 and higher, you can check your OTP server version number using the serverInfo REST API method.
For example:
http://rtp.trimet.org/opentripplanner-api-webapp/ws/serverinfo
…which gives a result such as:
<serverInfo>
<serverVersion>
<version>0.9.1-SNAPSHOT</version>
<major>0</major>
<minor>9</minor>
<incremental>1</incremental>
<qualifier>SNAPSHOT</qualifier>
<commit>de91d05ef4bff7d22ef0b3bec8991625b3b2c797</commit>
</serverVersion>
<cpuName>Intel(R) Xeon(R) CPU X5660 @ 2.80GHz</cpuName>
<nCores>24</nCores>
</serverInfo>
In OTP v0.8.0 and lower, this REST API method doesn't exist.
To get started testing your OTP Server with the Android app, we suggest entering your OTP Server root REST API URL directly into the OTP Android app (see the OTP Server Directory (a Google Docs spreadsheet) for example root REST API URLs). To do this, go to the "Settings" menu in the app and uncheck "Auto Detect OTP Server". Then click on "Custom Server URL", and enter the root URL for your OTP REST API (e.g., http://opentripplanner.usf.edu/opentripplanner-api-webapp/ws). Plan a few trips to verify that you see a path on the screen from the origin to destination, and that if you tap on the small "directions" icon in the lower-left corner of the screen you see a list of written directions.
Once you've confirmed that this works, then we can add your OTP server to the OTP Server Directory to make it available to regular users of the app. See the first page of the OTP Server Directory for instructions on adding your OTP Server.
Once your OTP Server is added to the directory, it may take a few minutes to be available in the app.
When starting the app, OTP Android should try to auto-detect the server if your phone is within based on the "Bounds" field in the directory. If auto-detection doesn't work, you can manually select server. To force manual server selection, go to "Settings" and uncheck "Auto Detect OTP Server". Then, click on "Refresh server list" and it should take you back to the main screen and ask you to pick from the server list. If your server doesn't appear, try waiting a few minutes for the Google Docs spreadsheet to update and try again.
Try planning a few trips from/to locations that are known to work in your normal OTP web UI, and ensure that the app works with your server. If your server doesn't work with the app, we will have to remove the app from the directory until we can confirm it works.
We separate the Plain Old Java Objects (POJOs) used in the deserialization of the REST API responses into a different project. Check out the opentripplanner-pojos project for more information about the mobile REST API code.
See the README for Troubleshooting details for Gradle and Android Studio.
Mailing List - OpenTripPlanner Developer list - Just be sure to mention "OTP Android" in the subject line.