EVVA Abrevva Android SDK

The EVVA Abrevva Android SDK is a collection of tools to work with electronical EVVA access components. It allows for scanning and connecting via BLE.

• Features
• Requirements
• Installation
• Examples

Features

• BLE Scanner for EVVA components
• Localize scanned EVVA components
• Disengage scanned EVVA components
• Read / Write data via BLE

Requirements

Platform	Installation	Status
iOS	see EVVA Abrevva IOS SDK	-
Android 10+ (API level 29)	Gradle	Fully Tested

Installation

Gradle

Gradle is a build automation tool for multi-language software development. For usage and installation instructions, visit their website. To integrate EVVA Abrevva Android SDK into your Android Studio project using Gradle, specify the dependency in your build.gradle File:

dependencies {
  implementation group: "com.evva.xesar", name: "abrevva-sdk-android", version: "3.0.0"
}

Examples

Initialize BleManager

To start off first initialize the SDK BleManager. You can pass an init callback closure for success indication.

import com.evva.xesar.abrevva.ble.BleDevice
import com.evva.xesar.abrevva.ble.BleManager

public class Example {
  private lateinit var bleManager: BleManager
  private var bleDeviceMap: MutableMap<String, BleDevice> = mutableMapOf()

  fun initialize() {
    this.bleManager = BleManager(context)
  }
}

Scan for EVVA components

Use the BleManager to scan for components in range. You can pass several callback closures to react to the different events when scanning or connecting to components.

fun scanForDevices() {
  val timeout: Long = 10_000

  this.bleManager.startScan(
    { device ->
      println("Found device: address=${device.address}")
      this.bleDeviceMap[device.address] = device
    },
    { success ->
      println("Scan started: success=${success}")
    },
    { success ->
      println("Scan stopped: success=${success}")
    },
    null, // optional EVVA mac filter
    null, // optional allow duplicates flag
    timeout
  )
}

Read EVVA component advertisement

Get the EVVA advertisement data from a scanned EVVA component.

device.advertisementData?.let {
  println(it.rssi)
  println(it.isConnectable)

  it.manufacturerData?.let { md ->
    println(md.batteryStatus)
    println(md.isOnline)
    println(md.officeModeEnabled)
    println(md.officeModeActive)
    // ...
  }
}

There are several properties that can be accessed from the advertisement.

data class BleDeviceAdvertisementData(
  val rssi: Int,
  val isConnectable: Boolean? = null,
  val manufacturerData: BleDeviceManufacturerData? = null
)

data class BleDeviceManufacturerData(
  val companyIdentifier: UShort,
  val version: UByte,
  val componentType: UByte,
  val mainFirmwareVersionMajor: UByte,
  val mainFirmwareVersionMinor: UByte,
  val mainFirmwareVersionPatch: UShort,
  val componentHAL: Int,
  val batteryStatus: Boolean,
  val mainConstructionMode: Boolean,
  val subConstructionMode: Boolean,
  val isOnline: Boolean,
  val officeModeEnabled: Boolean,
  val twoFactorRequired: Boolean,
  val officeModeActive: Boolean,
  val reservedBits: Int?,
  val identifier: String,
  val subFirmwareVersionMajor: UByte?,
  val subFirmwareVersionMinor: UByte?,
  val subFirmwareVersionPatch: UShort?,
  val subComponentIdentifier: String?,
)

Localize EVVA components

With the signalize method you can localize scanned EVVA components. On a successful signalization the component will emit a melody indicating its location.

fun signalizeDevice(device: BleDevice) {
  this.bleManager.signalize(device) { success ->
    println("Signalize: success=$success")
  }
}

Disengage EVVA components

For the component disengage you have to provide access credentials to the EVVA component. Those are generally acquired in the form of access media metadata from the Xesar software.

fun disengageDevice(device: BleDevice) {
  val mobileId = ""           // sha256-hashed hex-encoded version of `xsMobileId` found in blob data.
  val mobileDeviceKey = ""    // mobile device key string from `xsMOBDK` found in blob data.
  val mobileGroupId = ""      // mobile group id string from `xsMOBGID` found in blob data.
  val mediumAccessData = ""   // access data string from `mediumDataFrame` found in blob data.
  val isPermanentRelease = false

  bleManager.disengage(
    device, // scanned EVVA component
    mobileId,
    mobileDeviceKey,
    mobileGroupId,
    mediumAccessData,
    isPermanentRelease,
  ) { status ->
    println("Disengage: status=$status")
  }
}

There are several access status types upon attempting the component disengage.

enum class DisengageStatusType {
  // Component
  AUTHORIZED,
  AUTHORIZED_PERMANENT_ENGAGE,
  AUTHORIZED_PERMANENT_DISENGAGE,
  AUTHORIZED_BATTERY_LOW,
  AUTHORIZED_OFFLINE,
  UNAUTHORIZED,
  UNAUTHORIZED_OFFLINE,
  SIGNAL_LOCALIZATION,
  MEDIUM_DEFECT_ONLINE,
  MEDIUM_BLACKLISTED,
  ERROR,

  // Interface
  UNABLE_TO_CONNECT,
  UNABLE_TO_SET_NOTIFICATIONS,
  UNABLE_TO_READ_CHALLENGE,
  UNABLE_TO_WRITE_MDF,
  ACCESS_CIPHER_ERROR,
  BLE_ADAPTER_DISABLED,
  UNKNOWN_DEVICE,
  UNKNOWN_STATUS_CODE,
  TIMEOUT,
}