No description or website provided.
Latest commit 7e71300 Aug 15, 2016 @duncancarroll duncancarroll SDK 1.1
Permalink
Failed to load latest commit information.
README SDK 1.0 RC Feb 11, 2016
AutomaticSDKSampleApp.zip SDK 1.1 Aug 15, 2016
README.md Update README.md Jul 26, 2016
automatic-android-sdk-release.aar SDK 1.1 Aug 15, 2016
changelog SDK 1.0 RC-2 Feb 13, 2016
public_apis.zip SDK 1.0 RC Feb 11, 2016

README.md

Automatic Android SDK

  1. Creating an App
  2. Adding the SDK to your Android App
  3. Initialization + Authentication
  4. ELM Streaming
  5. Supported ELM327 Commands
  6. Receiving Real-Time Events
  7. Testing With An ECU Simulator
  8. Making REST API Calls

IMPORTANT LINKS


The Automatic SDK is the best way to build Android apps powered by Automatic.

With the Automatic Android SDK, your users can log in to your app with their Automatic accounts. Think Facebook or Twitter login—but rather than bringing a users' social graph, instead unlocking a wealth of automotive data that you can use to supercharge your app.

Log in with Automatic

Once a user approves your app's request to access their data, your app could:

  • Access your users' trips to analyze driving habits
  • Query your users' cars to provide up-to-date resale values estimates
  • Populate your users' profiles without a lengthy signup form
  • Receive "pushed" events such as Ignition On, Ignition Off, etc.
  • so much more

We can't wait to see what you build. Let's get to it!

1. Creating an App

  • Each SDK app must first create an app on the Automatic Developer site.
  • Important: Currently, apps must have the Client Type field set to "Public / Native" or authentication will fail.

2. Adding the SDK to your Android App

  1. Android Studio is the preferred IDE to develop Android app. Add the SDK aar library to your project. Add the following line to your build.gradle, within your dependencies {} block:

    compile(name:'automatic-android-sdk-release', ext:'aar')
  2. Add your client id (found within the Automatic Developer Apps Manager) to your AndroidManifest.xml, inside your <application> tag:

    <meta-data android:name="com.automatic.sdk.client_id" android:value="your_client_id" />

3. Initialization + Authentication

  1. Before your app can access any of the SDKs features, your user must authenticate with Automatic. To allow them to do this from inside your app, you must include a "Login With Automatic" button to your app's UI:

    <com.automatic.android.sdk.LoginButton
        android:id="@+id/automatic_login"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" />
  2. Initialize the SDK, ideally within an Application context or any other context such as your Launcher which is run every time your app loads. Pass it the scopes which you have access to. Note that if your scopes are invalid, you will receive an "Invalid Request" upon authorizing. To receive "pushed" events such as Ignition On / Off, Location, be sure to call useServiceBinding():

    // Scopes that your application has registered with Automatic on the Automatic developer apps manager page.
    public static final Scope[] scopes = {Scope.Public, Scope.VehicleVin, Scope.Trips, Scope.Location, Scope.VehicleEvents, Scope.VehicleProfile, Scope.UserProfile, Scope.Behavior, Scope.AdapterBasic};
    Automatic.initialize(
        new Automatic.Builder(this)
            .addScopes(scopes)
            .useServiceBinding()
            ... etc);
  3. In the Activity you're using to handle the "Login With Automatic" flow, pass the SDK a context, and an implementation of AutomaticLoginCallbacks:

    • Login using the "Login With Automatic" button. Make a call to addLoginButton() and pass in a reference to your LoginButton:

      Automatic.get().addLoginButton(mLoginButton, mYourContext, AutomaticLoginCallbacks);
    • You can also login without the login button:

      // pass in a callback to handle success / failure
      Automatic.get().setLoginCallbackListener(new AutomaticLoginCallbacks() {
              @Override
              public void onLoginSuccess() {
                  // success!
              }
              @Override
              public void onLoginFailure(SdkError error) {
                  // failed.
              }
          });
      Automatic.get().loginWithAutomatic(mYourContext);

      Or simply:

      Automatic.get().loginWithAutomatic(mYourContext, AutomaticLoginCallbacks);

4. ELM Streaming

Note: Before using the Streaming SDK, you must have already created an Automatic account using the core app, and completed the Setup process with each adapter + phone pair that you plan to use. Each device's firmware must also be updated to use version 1.0.124 or higher. Gen 2 and above adapters are supported.

The Automatic SDK supports the streaming of a subset of ELM 327 commands over a standard BluetoothSocket. You hand us credentials, and we had you back a live socket. There are just a few changes needed to get started:

  1. Make sure you've completed Step 3 above. Now you need to find out the BT mac address of the adapter.

    • You can ask the Automatic core app for the mac address of the currently connected adapter through service binding. Please refer to sample app for more details:

              // bind to the Automatic core app
              Automatic.get().bindService(new ServiceBindingCallback() {
                  @Override
                  public void onBindingResponse(boolean success, SdkError sdkError) {
                      if (success) {
                          // successfully bound and authenticated
                          ...
                      }
                  }
              });
              ...
              ...
              // once bound and authenticated
              if (Automatic.get().isServiceAuthenticated()) {
                  // set callback listener
                  Automatic.get().setAutomaticCoreAppQueryListener(mAutomaticCoreAppQueryListener);
                  // send request to the Automatic core app through service binding
                  Automatic.get().queryConnectedAdapterInfo();
              }
    • Or find adapter mac address in the Bluetooth bonded device list. Refer to findMacFromList() in the sample app:

      BluetoothAdapter bluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
      Set<BluetoothDevice> pairedDevices = bluetoothAdapter.getBondedDevices();

      In case the phone is paired with multiple Automatic adapters therefore multiple similar items in bonded device list. The Bluetooth naming convention of Automatic adapter is "XX-Automatic Adapter", where XX is the first two letters of the 6-char pin on the back of the adapter. Your app could display the BT bonded list to let user pick the correct one, or let user enter the 6-char pin.

  2. Call connectElmStreaming(String mac, ELMSocket.ElmSocketCallback elmSocketCallback) with adapter mac address and implement ELMSocket.ElmSocketCallback() to receive the ELMSocket. ELMSocket handles I/O with sendCommand() and a CommandCallback.

     Automatic.get().connectElmStreaming(mAdapterMac, new ELMSocket.ElmSocketCallback() {
                @Override
                public void onSocketAuthenticated(ELMSocket elmSocket) {
                    Log.v(TAG, "ELM Socket connected!";
                    mElmSocket = socket;
                    // Register ELM command callback
                    mElmSocket.setCommandCallback(mCommandCallback);
                    // Now you can send ELM commands to the adapter
                    mElmSocket.sendCommand("ELM command")
                }
                @Override
                public void onFailure(SdkError error) {
                    // failure.  
                }
                @Override
                public void onDisconnected(SdkError error) {
                    // try to reconnect?
                }
            });
  3. If client app prefers to handle raw BT socket I/O themselves, call connectElmStreaming(String mac, ELMSocket.ElmSocketCallback elmSocketCallback, boolean clientHandleBtSocket) then get the raw BT socket from ELMSocket object.

    Automatic.get().connectElmStreaming(mAdapterMac, new ELMSocket.ElmSocketCallback() {
                @Override
                public void onSocketAuthenticated(ELMSocket elmSocket) {
                    // get the raw BT socket and handle I/O in the client
                    BluetoothSocket btSocket = elmSocket.getSocket();
                    ...
                }
                ...
            }, true);
  4. Disconnect when finished via Automatic.get().disconnectElm()

    • Currently only one app can be connected at a time to the ELM socket. This means that if John's Streaming SDK App is using the socket, Joe's SDK App will fail to connect until John has disconnected.
    • Currently, only one Bluetooth connection attempt is made before failing with Error.BT_CONNECT_FAILED. Because Bluetooth can be flaky, it is recommended that you retry the connection a few times before giving up.

5. Supported ELM327 Commands

The Automatic Streaming SDK supports only a subset of the full ELM 327 command set. The full supported command set is available here, and a highly condensed list is available below.

  • These commands work normally:
AT@1
ATCAF
ATD
ATE
ATH
ATI
ATL
ATS
  • These commands are identical:
ATWS
ATZ (does not reboot the adapter)
  • These commands require authentication because they return engine data:
ATDPN
ATRV
  • These commands return OK, but are otherwise ignored:
ATCP
ATM
ATSH
ATSP0
ATSPA0
ATST
  • OBD Commands:
01xx
09xx

Additional notes:

  • Other OBD modes are not currently accessible. We hope to add more in the future.
  • Defaults are as documented in the ELM 327 data sheet. However, developers should use ATE0 and ATS0 (and keep the defaults ATCAF1, ATH0, and ATL0) for the fastest PID rate.
  • As an extension, we support the CAN multipid request syntax (e.g., 01040C0D0F101F) on all protocols. However, the response is always returned in CAN format, regardless of the actual OBD bus protocol (the one returned by ATDPN)

6. Testing With An ECU Simulator

Testing ELM Streaming is best done with an ECU Simulator such as this. When testing, the following sequence and behaviors should be kept in mind:

  • Power On: When the adapter (dongle) is plugged into power you should hear one double-beep. (ba-BEEP!).

  • Ignition On: The adapter waits until it receives an ignition signal from the car, or until it senses significant movement. Either case will kick it into "Drive Mode", and you will hear a four-beep sound (Bip-BEEP-bip-BEEP!). This can take some time, especially in the simulator, due to protocol discovery. If you send ELM commands during protocol discovery, you may see a NO_DATA response. A good rule of thumb is to open the main Automatic app, and wait for it to say "Currently Driving" before initiating the connection to the Streaming SDK.

  • Drive Mode: Once the adapter is in Drive Mode, it will not go into sleep mode until it receives an ignition off signal. To send an "ignition off" signal to the adapter, you can turn speed to max and RPM to zero (just remember to reset them to their normal positions afterward.) If the adapter is not in drive mode, it may enter sleep mode to save battery.

Using the above procedure, you should be able to

7. Receiving Real-Time Events

The Automatic SDK offers the ability for your app to bind to the main Automatic App (if it is installed on the user's phone), and receive instantaneous events from the car such as Ignition On / Off, MIL On / Off, Location Changed, Trip Ended, etc, which would normally only be available via Webhook. This binding is managed by a simple set of callback interfaces which you can implement anywhere in your app. Note: You must have the proper scope in order to receive events. If you do not have the required scope, you will not receive events.

  1. First ensure that you have Steps 2 and 3 above. Then, register a BroadcastReceiver to filter for the action com.automatic.ACTION_PING, with the following code:

    <receiver android:name="com.your.app.YourBroadcastReceiver" >
        <intent-filter>
            <action android:name="com.automatic.ACTION_PING" />
        </intent-filter>
    </receiver>

    This receiver allows the Automatic App to wake your app up when an event occurs, such as Ignition On. The best practice here is to invoke a Service which then handles subsequent events. For an example of this behavior, please see the Broadcast Receiver example within the SDK Sample App.

  2. The Service will automatically handle binding and event pushing once you've registered the BroadcastReceiver, however if you need to bind / unbind from the service manually, you can call Automatic.bindService() or Automatic.unbindService() You can also monitor the state of the Service Binding via a ConnectionStateListener.

  3. For example code, please see the SDK Sample App

8. Making REST API Calls

For complete REST API documentation, see the Developer Documentation and the SDK Sample App

Use restApi() to make calls against the REST API, for example:

    Automatic.get().restApi().getTrips(new Callback<ResultSet<Trip>>() {
        @Override
        public void success(ResultSet<Trip> trips, Response response) {
            // you got some trips!
        }

        @Override
        public void failure(RetrofitError retrofitError) {
            // handle failure
        }
    });