Android SDK

The SDK can only be used by issuing a token that works with in combination with your app identifier. Please contact development@vecore.nl to issue your token.

Latest version

The latest version of the Android SDK is version

-

. Please see the changelog for details.

Project set-up

Add the module to your project in Android Studio.

Download the latest android SDK (v-)

The current set of dependencies are as follows:

    def room_version = "2.1.0"

    implementation "androidx.room:room-runtime:$room_version"
    implementation "androidx.room:room-ktx:$room_version"
    kapt "androidx.room:room-compiler:$room_version"

    implementation 'androidx.appcompat:appcompat:1.4.1'
    implementation 'org.greenrobot:eventbus:3.1.1'
    implementation 'net.danlew:android.joda:2.9.1'
    implementation 'com.squareup.retrofit2:retrofit:2.6.1'
    implementation 'com.squareup.retrofit2:converter-gson:2.6.1'
    implementation 'com.squareup.okhttp3:logging-interceptor:3.8.0'
    implementation 'com.google.android.gms:play-services-tasks:18.0.1'
    implementation "androidx.core:core-ktx:1.7.0"
    implementation "androidx.lifecycle:lifecycle-livedata-ktx:2.4.0"

    ext.kotlin_version = '1.5.21'

Also, you'll need these Proguard rules for a release build.

Permissions

    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

Implementation

The SDK checks the provided license key when initialized, so it makes sense to only to that once during the app lifetime.

In your Application:

public class MyApp extends Application {
    public VecoreSDK sdk;
    @Override
    public void onCreate() {
        super.onCreate();
        sdk = VecoreSDK.getInstance(this);
        sdk.authorize("MY KEY");
    }
}

In your activity:

sdk.setCallbackListener(new VecoreSDKCallback() {
        @Override
        public void onStateChanged(int newState) {
            switch (newState) {
                case VecoreSDK.State.STATE_CONNECTED: status.setText("Connected to peripheral"); hideProgress(); break;
                case VecoreSDK.State.STATE_CONNECTING: status.setText("Connecting to peripheral"); showProgress(); break;
                case VecoreSDK.State.STATE_DISCONNECTED: status.setText("Disconnected"); hideProgress(); open.setVisibility(View.GONE); close.setVisibility(View.GONE); break;
                case VecoreSDK.State.STATE_DISCONNECTING: status.setText("Disconnecting from peripheral"); showProgress(); break;
                case VecoreSDK.State.STATE_UNAUTHORIZED: status.setText("Unauthorized to connect to peripheral"); showProgress(); break;
                case VecoreSDK.State.STATE_AUTHORIZED: open.setVisibility(View.VISIBLE); close.setVisibility(View.VISIBLE); break;

                case VecoreSDK.State.STATE_LICENSE_VALIDATED: break;
                case VecoreSDK.State.STATE_LICENSE_INVALID: break;
                case VecoreSDK.State.STATE_ERROR: break;

            }
        }

        @Override
        public void onCommandResult(int command, boolean result) {

        }
    });

sdk.authorize("MY KEY");

Preloading a reservation

In version 1.0 the SDK stores reservation details and connection keys. To allow vehicle connection without an available network, you can preload the reservation and a set of connection keys:

sdk.preloadReservation(reservationId, privateManageKey)

The listener will receive a status update:

Value	Int	Description
STATE_POSITIVE	32	Preloading OK
STATE_ERROR	4096	Reservation or connection keys could not be fetched

You can preload a reservation any time, but be advised that the reserved resource might change up to 25 minutes before starting.

Connecting to a device

Use the privateManageKey, found in a Reservation, to connect to a specific vehicle.

sdk.connectToVehicle(privateManageKey);

VecoreSDK connection states

In VecoreSDK.State

Value	Int	Description
STATE_DISCONNECTED	0	There is currently no active connection
STATE_CONNECTING	2	The device is currently connecting to vehicleID
STATE_CONNECTED	3	The device is connected to vehicleID, awaiting authorization
STATE_JWT_INVALID	4	Box reports: JWT invalid
STATE_JWT_NO_KEY	6	No JWT keys available, even after sync.
STATE_POSITIVE	8	Generic positive state
STATE_SEARCHING	9	The device is busy searching vehicleID
STATE_UNAUTHORIZED	11	The device is connected, but you don't have a valid reservation
STATE_AUTHORIZED	12	The device is connected and is ready to send commands.
STATE_LICENSE_VALIDATED	13	The supplied license key is valid
STATE_LICENSE_INVALID	14	The supplied license key is invalid
STATE_ERROR	15	The connection is unavailable due to hardware or another connection is currently active.
STATE_NEED_INTERNET	17	The SDK cannot continue without an internet connection
STATE_JWT_FETCH_FAILED	19	Fetching new JWT tokens has failed. There might be an API issue.
STATE_BOX_UNSPECIFIED	20	The box responsed to our authentication request with an unspecified code. Check the vehicle/reservation logs in the portal.

Sending commands

sdk.sendCommand(VecoreSDK.Command.COMMAND_OPEN);

Disconnecting from a device

The connection to a vehicle isn't automatically terminated, so disconnect before starting a new search.

sdk.disconnectFromVehicle(vehicleId);

Request a status update

sdk.requestConnectionStatusUpdate();

Staging environment

To use our staging environment, notify the SDK before calling authorize():

sdk.setDebugEnvironmentEnabled(true);
sdk.authorize("MY KEY");

Notes

Please note

cleanup

sdk!!.cleanup() forcefully disconnects BLE peripherals and unbinds the BLE service.

Changelog

Changes to the Android SDK are described below. Contact Vecore to issue API / SDK keys or for any other inquiry. Please navigate to the Vecore website (opens new window) for contact details.