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.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | InitializeOptions |

startScan(...)

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

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

| Param | Type | | ------------- | ------------------- | | seconds | number |

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.

| Param | Type | | -------------- | ----------------------------------------------------------------------------- | | deviceId | string | | appInfo | AppInfo | | callback | (value: callbackResult) => void |

Returns: Promise<string>

disconnect(...)

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

Disconnect from a scanner. Returns a Promise object.

| Param | Type | | -------------- | ------------------- | | deviceId | string |

getBasicProperties(...)

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

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

| Param | Type | Description | | ----------------- | ------------------- | ------------------------------------------------------------- | | deviceId | string | | | propertyKey | string | The propertyKey parameter is' battery 'or' firmware_version ' |

Returns: Promise<string>

getAllBarcodeProperties(...)

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

get all barcode type settings

| Param | Type | | -------------- | ------------------- | | deviceId | string |

Returns: Promise<string>

editPropertiesInfoByKey(...)

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

Modify data based on key

| Param | Type | Description | | ----------------- | ------------------- | ----------------------------------- | | deviceId | string | | | propertyKey | string | PropertyKeyList | | data | string | |

Returns: Promise<string>

getPropertiesInfoByKey(...)

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

Get data based on key.

| Param | Type | Description | | ----------------- | ------------------- | ----------------------------------- | | deviceId | string | | | propertyKey | string | PropertyKeyList |

Returns: Promise<string>

Interfaces

InitializeOptions

| Prop | Type | Description | Default | | ----------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | | androidNeverForLocation | boolean | If 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. (Android only) Requires adding 'neverForLocation' to AndroidManifest.xml https://developer.android.com/guide/topics/connectivity/bluetooth/permissions#assert-never-for-location | false |

ScanResult

| Prop | Type | Description | | ---------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | device | BleDevice | The peripheral device that was found in the scan. Android and web: device.name is always identical to localName. iOS: device.name is identical to localName the first time a device is discovered, but after connecting device.name is the cached GAP name in subsequent scans. | | localName | string | The name of the peripheral device from the advertisement data. | | rssi | number | Received Signal Strength Indication. | | txPower | number | Transmit power in dBm. A value of 127 indicates that it is not available. | | manufacturerData | { [key: string]: DataView; } | Manufacturer data, key is a company identifier and value is the data. | | serviceData | { [key: string]: DataView; } | Service data, key is a service UUID and value is the data. | | uuids | string[] | Advertised services. | | rawAdvertisement | DataView | Raw advertisement data (Android only). |

BleDevice

| Prop | Type | Description | | -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | deviceId | string | ID of the device, which will be needed for further calls. On Android this is the BLE MAC address. On iOS and web it is an identifier. | | name | string | Name of the peripheral device. | | uuids | string[] | |

DataView

| Prop | Type | | ---------------- | --------------------------------------------------- | | buffer | ArrayBuffer | | byteLength | number | | byteOffset | number |

| Method | Signature | Description | | -------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | getFloat32 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Float32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. | | getFloat64 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Float64 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. | | getInt8 | (byteOffset: number) => number | Gets the Int8 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. | | getInt16 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Int16 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. | | getInt32 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Int32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. | | getUint8 | (byteOffset: number) => number | Gets the Uint8 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. | | getUint16 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Uint16 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. | | getUint32 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Uint32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. | | setFloat32 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Float32 value at the specified byte offset from the start of the view. | | setFloat64 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Float64 value at the specified byte offset from the start of the view. | | setInt8 | (byteOffset: number, value: number) => void | Stores an Int8 value at the specified byte offset from the start of the view. | | setInt16 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Int16 value at the specified byte offset from the start of the view. | | setInt32 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Int32 value at the specified byte offset from the start of the view. | | setUint8 | (byteOffset: number, value: number) => void | Stores an Uint8 value at the specified byte offset from the start of the view. | | setUint16 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Uint16 value at the specified byte offset from the start of the view. | | setUint32 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Uint32 value at the specified byte offset from the start of the view. |

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.

| Prop | Type | Description | | ---------------- | ------------------- | ------------------------------------------------------------------------------- | | byteLength | number | Read-only. The length of the ArrayBuffer (in bytes). |

| Method | Signature | Description | | --------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | slice | (begin: number, end?: number | undefined) => ArrayBuffer | Returns a section of an ArrayBuffer. |

AppInfo

| Prop | Type | | ----------------- | ------------------- | | appId | string | | developerId | string | | appKey | string |

callbackResult

| Prop | Type | Description | | ---------- | ------------------- | ----------------------------------------------- | | type | number | Event type 1 is barcode 2 is scanner disconnect | | data | string | Type 1 returns barcode, type 2 returns deviceId |

Enums

PropertyKeyList

| Members | Description | | -------------------------------------- | ----------------------------------------------------------------------------------- | | "cache" | read barcode cache quantity or clean barcode cache value is 0 | | "restore_factory" | Restore factory settings value is 1 | | "enable_or_disable_all_barcodes" | enable or disable all barcodes 1 is enable 0 is disable | | "restore_default_barcode" | restore default barcode type value is 1 | | "bluetooth_name" | read/update bluetooth name key | | "volume" | read/update volume value 0 is mute, 2 is low, 4 is middle, 8 is loud | | "lighting_lamp_control" | Illumination key value 00 is scanning, 01 is Stay on,10 is Stay off | | "positioning_lamp_control" | Navigation Light key value 00 is scanning, 01 is Stay on,10 is Stay off | | "shake_reminder" | Vibration reminder 0 is close,1 is open | | "shake_intensity" | Vibration strength 0 is mute,1 is loud | | "position_light_twinkle" | Navigation Light flashing 0 is close,1 is opens | | "start_up_clean_cache" | This key Clear data from buffer at start-up 1 is enable 0 is disable | | "auto_upload_cache" | This key Auto uploading barcode cache 1 is enable 0 is disable | | "motor_swing_grade" | Motor PWM vibration intensity level 1-8 value 0000,0001,0010, 0011，。。。。1000 is loud | | "Codabar" | barcode type key value 1 is enable 0 is disable | | "Code 11" | | | "Code 128" | | | "Code 39" | | | "Code 93" | | | "GS1-128" | | | "USPS/FedEx" | | | "EAN-8" | | | "EAN-13" | | | "MSI" | | | "UPC-A" | | | "UPC-E0" | | | "UPC-E1" | | | "Chinese Post" | | | "IATA 25" | | | "Interleaved 25" | | | "Matrix 25" | | | "Standard 25" | | | "QR Code" | | | "Data Matrix" | | | "PDF 417" | | | "Aztec" | | | "Maxi" | | | "Han Xin" | |