inateck-scanner-js-sdk
TypeScript icon, indicating that this package has built-in type declarations

0.0.3 • Public • Published

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(...)

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"

Readme

Keywords

Package Sidebar

Install

npm i inateck-scanner-js-sdk

Weekly Downloads

2

Version

0.0.3

License

MIT

Unpacked Size

350 kB

Total Files

32

Last publish

Collaborators

  • inateck