Abrevva Capacitor Plugin

The EVVA Abrevva Capacitor Plugin 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

• Capacitor >= 5.0.0
• Java 17+ (Android)
• Android SDK (Android)
• Android 10+ (API level 29) (Android)
• Xcode 15.4 (iOS)
• iOS 15.0+ (iOS)

Installation

Capacitor 6

npm install @evva/abrevva-capacitor
npx cap sync

Capacitor 5

npm install @evva/[email protected]
npx cap sync

Examples

Initialize and scan for EVVA components

import { AbrevvaBLEClient, BleDevice } from "@evva/abrevva-capacitor";

class ExampleClass {
  private devices: BleDevice[];
  
  async startScan(event: any) {
    this.devices = [];
   
    await AbrevvaBLEClient.initialize()
    await AbrevvaBLEClient.startScan({ timeout: 5_000 }, (device: BleDevice) => {
      this.devices.push(device);
    }, (success: boolean) => {
      console.log(`Scan started, success: ${success}`);
    }, (success: boolean) => {
      console.log(`Scan stopped, success: ${success}`);
    });
  }
}

Read EVVA component advertisement

Get the EVVA advertisement data from a scanned EVVA component.

const ad = device.advertisementData
console.log(ad?.rssi)
console.log(ad?.isConnectable)

const md = ad?.manufacturerData
console.log(md?.batteryStatus)
console.log(md?.isOnline)
console.log(md?.officeModeEnabled)
console.log(md?.officeModeActive)
// ...

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

export interface BleDeviceAdvertisementData {
  rssi?: number;
  isConnectable?: boolean;
  manufacturerData?: BleDeviceManufacturerData;
}

export interface BleDeviceManufacturerData {
  companyIdentifier?: string;
  version?: number;
  componentType?: "handle" | "escutcheon" | "cylinder" | "wallreader" | "emzy" | "iobox" | "unknown";
  mainFirmwareVersionMajor?: number;
  mainFirmwareVersionMinor?: number;
  mainFirmwareVersionPatch?: number;
  componentHAL?: string;
  batteryStatus?: "battery-full" | "battery-empty";
  mainConstructionMode?: boolean;
  subConstructionMode?: boolean;
  isOnline?: boolean;
  officeModeEnabled?: boolean;
  twoFactorRequired?: boolean;
  officeModeActive?: boolean;
  identifier?: string;
  subFirmwareVersionMajor?: number;
  subFirmwareVersionMinor?: number;
  subFirmwareVersionPatch?: number;
  subComponentIdentifier?: string;
}

Localize EVVA component

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

const success = await AbrevvaBLEClient.signalize('deviceId');

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.

const status = await AbrevvaBLEClient.disengage(
  'deviceId',
  'mobileId',
  'mobileDeviceKey',
  'mobileGroupId',
  'mediumAccessData',
  false,
);

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

export enum DisengageStatusType {
  /// Component
  Authorized = "AUTHORIZED",
  AuthorizedPermanentEngage = "AUTHORIZED_PERMANENT_ENGAGE",
  AuthorizedPermanentDisengage = "AUTHORIZED_PERMANENT_DISENGAGE",
  AuthorizedBatteryLow = "AUTHORIZED_BATTERY_LOW",
  AuthorizedOffline = "AUTHORIZED_OFFLINE",
  Unauthorized = "UNAUTHORIZED",
  UnauthorizedOffline = "UNAUTHORIZED_OFFLINE",
  SignalLocalization = "SIGNAL_LOCALIZATION",
  MediumDefectOnline = "MEDIUM_DEFECT_ONLINE",
  MediumBlacklisted = "MEDIUM_BLACKLISTED",
  Error = "ERROR",

  /// Interface
  UnableToConnect = "UNABLE_TO_CONNECT",
  UnableToSetNotifications = "UNABLE_TO_SET_NOTIFICATIONS",
  UnableToReadChallenge = "UNABLE_TO_READ_CHALLENGE",
  UnableToWriteMDF = "UNABLE_TO_WRITE_MDF",
  AccessCipherError = "ACCESS_CIPHER_ERROR",
  BleAdapterDisabled = "BLE_ADAPTER_DISABLED",
  UnknownDevice = "UNKNOWN_DEVICE",
  UnknownStatusCode = "UNKNOWN_STATUS_CODE",
  Timeout = "TIMEOUT",
}

API

• Interfaces

Interfaces

AbrevvaBLEInterface

Method	Signature
initialize	(options?: InitializeOptions | undefined) => Promise<void>
isEnabled	() => Promise<BooleanResult>
isLocationEnabled	() => Promise<BooleanResult>
startEnabledNotifications	() => Promise<void>
stopEnabledNotifications	() => Promise<void>
openLocationSettings	() => Promise<void>
openBluetoothSettings	() => Promise<void>
openAppSettings	() => Promise<void>
startScan	(options?: BleScannerOptions | undefined) => Promise<void>
stopScan	() => Promise<void>
addListener	(eventName: "onEnabledChanged", listenerFunc: (result: BooleanResult) => void) => PluginListenerHandle
addListener	(eventName: string, listenerFunc: (event: ReadResult) => void) => PluginListenerHandle
addListener	(eventName: "onScanResult", listenerFunc: (result: BleDevice) => void) => PluginListenerHandle
addListener	(eventName: "onScanStart", listenerFunc: (success: BooleanResult) => void) => PluginListenerHandle
addListener	(eventName: "onScanStop", listenerFunc: (success: BooleanResult) => void) => PluginListenerHandle
connect	(options: DeviceIdOptions & TimeoutOptions) => Promise<void>
disconnect	(options: DeviceIdOptions) => Promise<void>
read	(options: ReadOptions & TimeoutOptions) => Promise<ReadResult>
write	(options: WriteOptions & TimeoutOptions) => Promise<void>
signalize	(options: SignalizeOptions) => Promise<void>
disengage	(options: DisengageOptions) => Promise<StringResult>
startNotifications	(options: ReadOptions) => Promise<void>
stopNotifications	(options: ReadOptions) => Promise<void>

InitializeOptions

Prop	Type
androidNeverForLocation	boolean

BooleanResult

Prop	Type
value	boolean

BleScannerOptions

Prop	Type
macFilter	string
allowDuplicates	boolean
timeout	number

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

ReadResult

Prop	Type
value	string

BleDevice

Prop	Type
deviceId	string
name	string
advertisementData	BleDeviceAdvertisementData

BleDeviceAdvertisementData

Prop	Type
rssi	number
isConnectable	boolean
manufacturerData	BleDeviceManufacturerData

BleDeviceManufacturerData

Prop	Type
companyIdentifier	string
version	number
componentType	'handle' | 'escutcheon' | 'cylinder' | 'wallreader' | 'emzy' | 'iobox' | 'unknown'
mainFirmwareVersionMajor	number
mainFirmwareVersionMinor	number
mainFirmwareVersionPatch	number
componentHAL	string
batteryStatus	'battery-full' | 'battery-empty'
mainConstructionMode	boolean
subConstructionMode	boolean
isOnline	boolean
officeModeEnabled	boolean
twoFactorRequired	boolean
officeModeActive	boolean
identifier	string
subFirmwareVersionMajor	number
subFirmwareVersionMinor	number
subFirmwareVersionPatch	number
subComponentIdentifier	string

DeviceIdOptions

Prop	Type
deviceId	string

TimeoutOptions

Prop	Type
timeout	number

ReadOptions

Prop	Type
deviceId	string
service	string
characteristic	string

WriteOptions

Prop	Type
deviceId	string
service	string
characteristic	string
value	string

SignalizeOptions

Prop	Type
deviceId	string

StringResult

Prop	Type
value	string

DisengageOptions

Prop	Type
deviceId	string
mobileId	string
mobileDeviceKey	string
mobileGroupId	string
mediumAccessData	string
isPermanentRelease	boolean

AbrevvaCryptoInterface

Method	Signature
encrypt	(options: { key: string; iv: string; adata: string; pt: string; tagLength: number; }) => Promise<{ cipherText: string; authTag: string; }>
encryptFile	(options: { sharedSecret: string; ptPath: string; ctPath: string; }) => Promise<void>
decrypt	(options: { key: string; iv: string; adata: string; ct: string; tagLength: number; }) => Promise<{ plainText: string; authOk: boolean; }>
decryptFile	(options: { sharedSecret: string; ctPath: string; ptPath: string; }) => Promise<void>
decryptFileFromURL	(options: { sharedSecret: string; url: string; ptPath: string; }) => Promise<void>
generateKeyPair	() => Promise<{ privateKey: string; publicKey: string; }>
computeSharedSecret	(options: { privateKey: string; peerPublicKey: string; }) => Promise<{ sharedSecret: string; }>
computeED25519PublicKey	(options: { privateKey: string; }) => Promise<{ publicKey: string; }>
sign	(options: { privateKey: string; data: string; }) => Promise<{ signature: string; }>
verify	(options: { publicKey: string; data: string; signature: string; }) => Promise<void>
random	(options: { numBytes: number; }) => Promise<{ value: string; }>
derive	(options: { key: string; salt: string; info: string; length: number; }) => Promise<{ value: string; }>