inateck-scanner-js-sdk v0.0.3

inateck-scanner-js-sdk

A Inateck BLE Scanner module for Ionic react.

Install

npm install inateck-scanner-js-sdk
npm install @capacitor-community/bluetooth-le
npx cap sync

iOS

On iOS, add the NSBluetoothAlwaysUsageDescription to Info.plist, otherwise the app will crash when trying to use Bluetooth (see here).

If the app needs to use Bluetooth while it is in the background, you also have to add bluetooth-central to UIBackgroundModes (for details see here).

./ios/App/App/Info.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleDevelopmentRegion</key>
	<string>en</string>
  ...
+	<key>NSBluetoothAlwaysUsageDescription</key>
+	<string>Uses Bluetooth to connect and interact with peripheral BLE devices.</string>
+	<key>UIBackgroundModes</key>
+	<array>
+		<string>bluetooth-central</string>
+	</array>
</dict>
</plist>

Android

On Android, no further steps are required to use the plugin (if you are using Capacitor 2, see here).

(Optional) Android 12 Bluetooth permissions

If your app targets Android 12 (API level 31) or higher and your app doesn't use Bluetooth scan results to derive physical location information, you can strongly assert that your app doesn't derive physical location. This allows the app to scan for Bluetooth devices without asking for location permissions. See the Android documentation.

The following steps are required to scan for Bluetooth devices without location permission on Android 12 devices:

• In android/variables.gradle, make sure compileSdkVersion and targetSdkVersion are at least 31 (changing those values can have other consequences on your app, so make sure you know what you're doing).
• Make sure you have JDK 11+ (it is recommended to use JDK that comes with Android Studio).
• In android/app/src/main/AndroidManifest.xml, add android:exported="true" to your activity if not already added (setting android:exported is required in apps targeting Android 12 and higher).
• In android/app/src/main/AndroidManifest.xml, update the permissions:

      <!-- Permissions -->
  +   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="30" />
  +   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
  +   <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
  +     android:usesPermissionFlags="neverForLocation"
  +     tools:targetApi="s" />

• Set the androidNeverForLocation flag to true when initializing the ScannerManager.

  import {ScannerManager} from "inateck-scanner-js-sdk"
  await ScannerManager.initialize({ androidNeverForLocation: true });

Note: If you include neverForLocation in your android:usesPermissionFlags, some BLE beacons are filtered from the scan results.

Usage

import {ScannerManager} from "inateck-scanner-js-sdk"

async function connectScanner(){
  try {
    await ScannerManager.initialize({ androidNeverForLocation: true });
    ScannerManager.startScan().then((list)=>{
      if(list.length>0){
        const appInfo = {
          appId: 'M693be162686a',
          developerId: 'bb57d8e1-f911-47ba-b510-693be162686a',
          appKey: 'MC0CFQC85w0MsxDng4wHBICX7+iCOiSqfAIUdSerA4/MJ2kYBGAGgIG/YHemNr8=',

        }
        ScannerManager.connect(list[0].device.deviceId,appInfo,(value)=>{
          console.log(value)
        }).then((data)=>{
          console.log(data)
          ScannerManager.getBasicProperties(list[0].device.deviceId,"firmware_version").then((data)=>{
            console.log("firmware_version "+data)
          })
          ScannerManager.getBasicProperties(list[0].device.deviceId,"battery").then((data)=>{
            console.log("readBatteryLevel "+data)
          })
        }).catch((err) => {
          console.error(err);
        })
      }
    }).catch((err) => {
      console.error(err);
    })
  } catch (error) {
    console.error(error);
  }
}

async function updateIlluminationControl(deviceId:string){
  ScannerManager.editPropertiesInfoByKey(deviceId,"lighting_lamp_control","01").then((data)=>{
    console.log("update Illumination Control "+data)
  }).catch((err) => {
    console.error(err);
  })
}

async function cleanCache(deviceId:string){
  ScannerManager.editPropertiesInfoByKey(deviceId,"cache","0").then((data)=>{
    console.log("clean Cache "+data)
  }).catch((err) => {
    console.error(err);
  })
}

async function getBarcodesTypeSetting(deviceId:string){
  ScannerManager.getAllBarcodeProperties(deviceId).then((data)=>{
    console.log(data)
  }).catch((err) => {
    console.error(err);
  })
}

async function hasAutoUpdateCache(deviceId:string){
  ScannerManager.getPropertiesInfoByKey(deviceId,"auto_upload_cache").then((data)=>{
    console.log(data)
  }).catch((err) => {
    console.error(err);
  })
}

API

• initialize(...)
• startScan(...)
• stopScan()
• connect(...)
• disconnect(...)
• getBasicProperties(...)
• getAllBarcodeProperties(...)
• editPropertiesInfoByKey(...)
• getPropertiesInfoByKey(...)
• Interfaces
• Enums

initialize(...)

initialize(options?: InitializeOptions | undefined) => Promise<void>

Initialize Bluetooth Low Energy (BLE). If it fails, BLE might be unavailable on this device. On Android it will ask for the location permission. On iOS it will ask for the Bluetooth permission. For an example, see usage.

startScan(...)

startScan(seconds?: number | undefined) => Promise<ScanResult[]>

Init the module and Scan for availables peripherals. Returns a Promise ScanResult[].

Returns: Promise<ScanResult[]>

stopScan()

stopScan() => Promise<void>

Stop scanning for BLE scanner

connect(...)

connect(deviceId: string, appInfo: AppInfo, callback: (value: callbackResult) => void) => Promise<string>

Attempts to connect to a peripheral. In many cases if you can't connect you have to scan for the peripheral before. the callbacks will be invoked when the device is disconnected or a barcode is received.Returns a Promise object.

Returns: Promise<string>

disconnect(...)

disconnect(deviceId: string) => Promise<void>

Disconnect from a scanner. Returns a Promise object.

getBasicProperties(...)

getBasicProperties(deviceId: string, propertyKey: string) => Promise<string>

Read the current battery level or firmware version of the specified scanner

Returns: Promise<string>

getAllBarcodeProperties(...)

getAllBarcodeProperties(deviceId: string) => Promise<string>

get all barcode type settings

Returns: Promise<string>

editPropertiesInfoByKey(...)

editPropertiesInfoByKey(deviceId: string, propertyKey: string, data: string) => Promise<string>

Modify data based on key

Returns: Promise<string>

getPropertiesInfoByKey(...)

getPropertiesInfoByKey(deviceId: string, propertyKey: string) => Promise<string>

Get data based on key.

Returns: Promise<string>

Interfaces

InitializeOptions

ScanResult

BleDevice

DataView

ArrayBuffer

Represents a raw buffer of binary data, which is used to store data for the different typed arrays. ArrayBuffers cannot be read from or written to directly, but can be passed to a typed array or DataView Object to interpret the raw buffer as needed.

AppInfo

callbackResult

Enums

PropertyKeyList