This tutorial assumes you have a working knowledge of how to create an Android
application. Setting up the development environment and understanding Android
fundamentals is outside the scope of OpenXC, and already Google provides great
documentation and tutorials - we won’t repeat them here. The best place to start
is Android Studio’s User Guide.
Once you’re comfortable with creating an Android app, continue on with this
tutorial to enrich it with data from your vehicle.
We'll mention this again at the end of the
tutorial, but you will need to install the
before your application will work.
Download the complete starter
application from GitHub (click the
“ZIP” button on the right hand column or use Git), and extract it to your
Open the project with Android Studio.
This project is ready to go, so if you want to quickly see something running
jump ahead to the testing section. To know more about how this
application works or to add the necessary code to a different app, continue
Using the Library
The Starter project is based off of the same “Hello World” application that you
should have already created in Google’s tutorial. The first difference is that
we’ve specified that the Starter app will use the OpenXC library as a
This is already done in the Starter project and no changes have to be made. But to make your own app from scratch, go
to the app/build.gradle file and add the openxc library to the build
dependencies. This is mentioned in the Android Library Setup
You can now proceed to the next steps to start using the library in your
Note: If for some reason you are unable to use the remote openxc-android library, you can use a local copy. This requires replacing three files in the starter app, and one file in the imported library. All of the required files are included in each of the respective repositories with a .local extension. Below is a list of the files and locations:
Replace the standard versions of the files with the .local files. For example, in the OpenXC Starter app, replace the app\build.gralde file with the app\build.gradle.local file. Restart your IDE, run the Gradle build process, and your starter app should now be using a local copy of the openxc-android library.
The AndroidManifest.xml is the core of every Android application - it tells
the Android OS what views are available, which services are used and what sensors
your app needs.
Every OpenXC application, the Starter app included, needs to use the
VehicleManager service. The next difference between the “Hello World” app and
the Starter app is the addition of this line to the manifest:
This should go between the <application> tags, like this:
The next changes are all in Java code - for the Starter app, it’s in
StarterActivity.java in the src folder. In order to use the VehicleManager
in Java code, we have to initiate the our mVehicleManager variable and then
bind with it when the application starts.
Initiate our Starter App variables as shown here:
Then add the ServiceConnection in the StarterActivity to bind with the
In the onResume() method of the activity, we request to bind with the service
using the new ServiceConnection instance:
Now, when your app starts it will also start the OpenXC VehicleManager and if
the Enabler is running, it will be ready to receive data from the
The activity now has a connection to the vehicle service, and we want it to be
notified whenever the speed of the vehicle changes. Look for the
EnginerSpeed.Listener object in the StarterActivity:
This mSpeedListener is referred to from
ServiceConnection.onServiceConnected() method we previously, where it’s handed
to the VehicleManager for future updates. Every time a new value for
EngineSpeed is received by the VehicleManager, the receive(Measurement)
method of the new Listener will be called with the data.
Custom Message Listener
In order to listen to a custom message from the vehicle, follow these steps:
Generate a firmware that can send custom message.
Create a custom message listener and add it to the VehicleManager
Lastly, the Starter app adds one more element to the user interface so there’s a
place to display the current speed. In the main layout file for the activity,
res/layout/activity_starter.xml, the existing “hello world” TextView is
replaced with these two:
These widgets have IDs and are using the RelativeLayout to make sure they
don’t print on top of each other.
In the app’s onCreate method, we grab a reference to that text object in Java
Finally, look back at the EngineSpeed.Listener we created before - it’s
updated the UI every time a new measurement arrives:
That’s all you need to do to get measurements from OpenXC. You can see the full
list of Measurement Java classes that you can use in the
Your Android device likely doesn’t have any vehicle data flowing through it yet.
The next step is to use a pre-recorded vehicle trace file to simulate a real
vehicle interface on your desk.
Install the Enabler app if you haven’t already. That application
helps control the source of vehicle data, e.g. a vehicle interface or a trace
Download the driving trace and copy it to the SD card of your Android
device. In the case of using an emulator, follow these steps:
Open Android Device Monitor
Drag and drop the trace file into the sd card folder
With an Android device, you can do this in a few ways:
Mount the Android device as USB disk.
Use the File Manager from the Android Device Monitor (included with the
Copy the file with abd on the command line:
$ adb push driving.json /sdcard/openxc-driving.json
Download the file directly onto the device using the built-in browser
Finally, the last steps:
Run the OpenXC Enabler app on the device
In the Enabler, Go to Settings -> Data Sources and change the vehicle
interface to a Pre-recorded Trace File.
At the bottom of the screen under Trace File Playback, select a trace file
for playback. You need a file manager app on your device to browse for a
file. Later Android devices come with a manager pre-installed. Older devices
may need to download another app, such as the OI File
In the file manager, browse to the trace file you downloaded.
Return to the front view of the Enabler - the message count should be
increasing, indicating the trace is playing.
Run the Starter app app and you should see the engine speed changing in the