[!IMPORTANT] This package was renamed please use the new package name! @evva/abrevva-react-native

This project is an open-source option to help developers kickstart their project with our SDK. It is not a fully-fledged product! Feel free to use it as is, or create your own solution by utilizing our SDK directly. If you decide to use this plugin, we highly encourage you to create issues/PRs if you run into any challenges someone might also face in the future.

The Example App in this project still uses the old React Native architecture (React Native < 0.67) and is for demonstration purposes only. Please always use the latest React Native version in your app! - There are CVEs in older versions. See: CVE-2025-11953

Our package is compatible with newer React Native versions and will be available as a Turbo Module in the foreseeable future.

The EVVA React-Native Module 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 in range
• Localize EVVA components encountered by a scan
• Disengage EVVA components encountered by a scan
• Read / Write data via BLE

Requirements

• react-native <= 0.74.3
• Java 17+ (Android)
• Android SDK (Android)
• Android 10+ (API level 29+) (Android)
• iOS 15.0+ (iOS)

Installation

Set up an app with a matching ReactNative version:

$ npx @react-native-community/cli init MyApp --version 0.74.3

Add Abrevva to your project:

$ npm i @evva/abrevva-react-native

Android

Set the minimum SDK version to 29 in your module's build gradle:

minSdkVersion = 29
compileSdkVersion = 35
targetSdkVersion = 35

Depending on the used ReactNative version you might need to adjust the AGP version in your module-level build.gradle based on potential warnings:

dependencies {
    classpath("com.android.tools.build:gradle:8.3.0")
    ...

In your app's Manifest file add any needed install-time permissions:

<!-- Scan and connect to BLE components -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
                 android:usesPermissionFlags="neverForLocation"
                 tools:targetApi="s"/>
<uses-permission android:maxSdkVersion="30"
                 android:name="android.permission.BLUETOOTH"/>
<uses-permission android:maxSdkVersion="30"
                 android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:maxSdkVersion="30"
                 android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:maxSdkVersion="30"
                 android:name="android.permission.ACCESS_FINE_LOCATION"/>

<!-- Use coding station to write media -->
<uses-permission android:name="android.permission.NFC" />

In your app-level build.gradle you might want to exclude META-INF files to avoid gradle build issues:

packagingOptions {
    resources.excludes.add("META-INF/*")
}

Finally perform a gradle sync.

iOS

In your app's Podfile add a post_install hook to resolve a nasty CocoaPods limitation with XCFrameworks.

post_install do |installer|
    react_native_post_install(
      installer,
      config[:reactNativePath],
      :mac_catalyst_enabled => false
    )
    installer.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end

Execute bundle exec pod install inside of your projects ios/ folder.

Examples

Initialize and scan for EVVA components

import { AbrevvaBle } from '@evva/abrevva-react-native';

class ExampleClass {
  private devices: BleDevice[];
  
  async startScan(event: any) {
    this.devices = [];
   
    await AbrevvaBle.initialize();
    await AbrevvaBle.startScan(
      (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 EVVA components. On a successful signalization the component will emit a melody indicating its location.

const success = (await AbrevvaBle.signalize('deviceId')).value;

Perform disengage on 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 AbrevvaBle.disengage(
  device.deviceId,
  'mobileId',         // sha256-hashed hex-encoded version of `xsMobileId` found in blob data.
  'mobileDeviceKey',  // mobile device key string from `xsMOBDK` found in blob data.
  'mobileGroupId',    // mobile group id string from `xsMOBGID` found in blob data.
  'mobileAccessData', // access data string from `mediumDataFrame` found in blob data.
  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",
}

Coding Identification Media

Use the CodingStation to write or update access data onto an EVVA identification medium.

import { AbrevvaCodingStation } from '@evva/abrevva-react-native';

class ExampleClass {
    final url = '';
    final clientId = '';
    final username = '';
    final password = '';

  async writeMedium() {
    try {
      await AbrevvaCodingStation.register(url, clientId, username, password);
      await AbrevvaCodingStation.connect();
      await AbrevvaCodingStation.write();
      await AbrevvaCodingStation.disconnect();
    } catch (e) {
      console.log(`Error: $e`);
    }
  }
}