OBD’s Opportunities
On Board Diagnostic (OBD) is about plugin-in or embarking a device into a vehicle and using it to retrieve data (status) from it. This useful technology has been used for quite a time to diagnose problems with cars. Connecting these devices to the internet pushes their usefulness further, by enabling remote and real-time diagnostic of vehicles, turning them into connected entities. This capability opens up a lot of opportunities, such as implementing pay-as-you-drive models (e.g. insurance companies can create premiums that are tailored to the way you drive), improving fleet management (e.g. proactive – “lean” – maintenance of vehicles, better scheduling) or increased security (e.g. predict potential failures, detect accidents and trigger emergency procedures, etc.)
Xee provides a connected OBD device that you can easily plug into your car. They also expose the device’s features as REST APIs through their open platform, which we wrapped with a connector that you can use from within your scriptr.io scripts, making the implementation of applications for connected cars even easier. Let’s demonstrate this with a simple demo application, described in the following paragraphs.
Pre-requisites
Before implementing the demo app, you need the following:
- Subscribe to scriptr.io, if not already done,
- Import the Xee module from your scriptr.io workspace. On the bottom-left corner of the screen, click on “+ New Script” > “Import Modules”. From the dialog, scroll to “Xee” then click on “Import”. You can also check it out from Github,
- Sign up to a developer account on Xee Cloud
- Ideally, you should own a Xee device, otherwise, you can ask Xee for an alternative for testing
A simple car dashboard
Our simple demo application consists in exposing the status of some of our connected car’s components into a dashboard. To keep it simple, we’ll only display the fuel level, speed and engine speed, and will use sciptr.io’s powerful Google chart scripts to build the below dashboard.
Using the connector
Using the Xee connector is rather simple. Once you have imported it to your account, create an OAuth token for your end users (you can use your own Xee account as an end user account), by executing the getRequestCodeUrl and getAccessToken scripts respectively (obtaining tokens is described in details in the README.md file of the connector).
Once you have obtained an authentication token for an end user, require the “user” module into your script, then create an instance of the User class, passing your end user’s username:
var userModule = require("modules/xee/user.js");
var user = new userModule.User({username:"john.doe@mail.com"});
User instances are the entry points to all the features offered by Xee’s API, since they allow you to obtain the list of vehicles owned by your users (this list contains instances of the Vehicle class):
var allVehicles = user.listVehicles(); // list all the vehicles owned by this user
var aVehicle = allVechiles[0]; // pick the first vehicle on the list
var myCar = user.getVehicle({plateNumber:"BZ-602-GC"}); // you can also obtain a reference to a specific vehicle by id or vehicle's name
From an instance of vehicle, you can access all the data generated by Xee’s OBD, e.g
var lastKnowLocation = myCar.getLastKnowLocation();
var batteryVoltage = myCar.getBatteryVoltage();
var tripsThisWeekend = myCar.listTrips({begin:new Date("06/11/2016").toISOString(), end:new Date("06/12/2016").toISOString()});
// ... and many more
APIs to get the fuel level, vehicle speed, engine speed and car data
Based on the above, let’s go ahead and build four simple APIs that expose the fuel level, speed and engine speed (RPM), and basic data of a given connected vehicle. Let’s start with the first API: in your scriptr.io workspace, click on “+ New Script” and name your script “fuelLevel”. In the editor, type the following lines:
– Fuel level –
/*
* this API returns the fuel level of a connected car
*/
var userModule = require("modules/xee/user.js");
try {
var user = new userModule.User({username:"john.doe@mail.com"}); // replace the username with one of your end user's username
var vehicle = user.getVehicle({plateNumber:"BZ-602-GC"}); // replace with the actual plate number of a connected car
var fuelLevel = vehicle.getFuelLevel(); // get the current fuel level
return [ // We return a structure that is needed to display data as a Google chart Gauge (as seen later),
["Label", "Value"],
["fuellevel", Number(fuelLevel.value.toFixed(2))],
];
}catch(exception) {
return exception;
}
– Car data –
var userModule = require("modules/xee/user.js");
try {
var user = new userModule.User({username:"john.doe@mail.com"}); // replace the username with one of your end user's username
var vehicle = user.getVehicle({plateNumber:"BZ-602-GC"}); // replace with the actual plate number of a connected car
delete vehicle.client; // remove client information from the vehicle object before sending it
return vehicle;
}catch(exception) {
return exception;
}
We proceed similarly and create two other APIs (scripts – speed and engineSpeed) to respectively return the car’s speed and engine’s speed.
Display the fuel level, vehicle speed and engine speed on Gauges
Let’s now see how to display the values of the fuel level, speed and engine speed on gauges using Google chart scripts. In your scriptr.io workspace let’s create a script to display the fuel level: click on “+ New Script” > “Google Chart”. In the editor that is displayed, click on the “Start” tab, then scroll to the “fuelLevel” script.
Select “fuelLevel” then click on the “Charts” tab. Scroll to the bottom of the list of possible charts and click on “more”, then select the gauges. You can customize the gauge my specifying min/max values and different brackets by clicking on the “Customize” tab.
Proceed in a similar way to create the gauges for the car’s speed and engine speed respectively.
The dashboard
As you might have noticed, you can obtain links, iFrames or even HTML/JavaScript code to embed the result of your Google charts any scripts into HTML documents. In our case, we will embed our gauges as iFrames into an HTML page: in the Google chart script editor, click on the “Embed URL” at your right and copy/pste the iFrame code into an HTML file. Pretty simple!
My Car’s dashboard
Get the full code
You can get the full code from Github
