OptiConnect SDK
OptiConnect SDK enables seamless integration with Opticon's BLE OPN-2500 and OPN-6000 barcode scanners. This SDK allows you to manage Bluetooth Low Energy (BLE) connections, handle scanner data streams, and programmatically control scanner settings via commands.
Note: This package is independent of the OptiConnect application, which provides additional device management features. The SDK provides lower-level BLE functionality directly interacting with Opticon's BLE devices.
Features
- Bluetooth discovery and connection management for OPN-2500 and OPN-6000 BLE scanners.
- Real-time data streaming, including barcode data reception and BLE device state monitoring.
- Programmatic control of scanner settings (e.g., scan modes, illumination, connection pooling, etc.).
- Exclusive connection management: Ensure stable device pairing in multi-device environments by assigning unique connection pool IDs, preventing previously paired devices from hijacking active connections.
- Command management and customization for BLE services and scanner configurations.
Getting Started
Prerequisites
OPN-2500 | OPN-6000 |
Installation
To install the SDK, add the following dependency to your pubspec.yaml
file:
dependencies:
opticonnect_sdk: ^1.0.0
Important
This SDK uses flutter_blue_plus under the hood for Bluetooth Low Energy (BLE) communications. We have provided the necessary permission configurations for Android and iOS within this README. You can refer to the flutter_blue_plus documentation for additional BLE-specific settings or for more advanced usage scenarios.
Android Setup
to enable Bluetooth discovery and connection on Android, add the following permissions to your AndroidManifest.xml file located at android/app/src/main/AndroidManifest.xml below the manifest entry at the top:
<uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />
<!-- New Bluetooth permissions for Android 12 or higher -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Legacy permissions for Android 11 or lower -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<!-- Legacy permission for Android 9 or lower -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28" />
iOS Setup
To enable Bluetooth and background functionality for BLE device scanning on iOS, you need to modify a few project files.
1. Update Info.plist
Add the following keys to your ios/Runner/Info.plist file to request Bluetooth and location permissions:
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app needs Bluetooth to communicate with scanners and retrieve data.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app requires location access to scan for BLE devices while in use.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app requires location access to scan for BLE devices even when in the background.</string>
<key>UIBackgroundModes</key>
<array>
<string>bluetooth-central</string>
</array>
2. Update Podfile
Ensure that the Podfile contains the required permissions for Bluetooth and location access by adding the following lines in your ios/Podfile:
post_install do |installer|
installer.pods_project.targets.each do |target|
flutter_additional_ios_build_settings(target)
target.build_configurations.each do |config|
config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
'$(inherited)',
## Enable required permissions
'PERMISSION_LOCATION=1', # Enable location permissions
'PERMISSION_BLUETOOTH=1', # Enable Bluetooth permissions
]
end
end
end
3. Enable Background Modes for Bluetooth LE Accessories in Xcode
To allow the app to use Bluetooth in the background, follow these steps:
- Open your iOS project in Xcode.
- Select the Runner target in the project navigator.
- Go to the Signing & Capabilities tab.
- Click the + Capability button in the top left.
- Select Background Modes from the list.
- Check the option for Uses Bluetooth LE Accessories.
MacOS Setup
Make sure you have granted access to the Bluetooth hardware:
- Open your MacOS project in Xcode.
- Go to Runners -> Targets -> Runner.
- Go to the Signing & Capabilities tab.
- Under App Sandbox, ensure that Bluetooth is enabled by checking the Bluetooth box under Hardware.
You can refer to the image below for guidance:
Libraries
- bluetooth_manager
- constants/commands_constants
- constants/symbology_constants
- entities/barcode_data
- entities/battery_level_status
- entities/ble_discovered_device
- entities/command_data
- entities/command_response
- entities/device_info
- entities/led_color
- entities/scanner_command
- enums/ble_adapter_state
- enums/ble_device_connection_state
- enums/direct_input_key
- enums/formattable_symbology
- enums/symbology_type
- helpers/direct_input_keys_helper
- opticonnect
- scanner_feedback
- scanner_info
- scanner_settings
- scanner_settings/code_specific/codabar
- scanner_settings/code_specific/code_2_of_5_and_s_code
- scanner_settings/code_specific/code_11
- scanner_settings/code_specific/code_39
- scanner_settings/code_specific/code_93
- scanner_settings/code_specific/code_128_and_gs1_128
- scanner_settings/code_specific/code_specific
- scanner_settings/code_specific/composite_codes
- scanner_settings/code_specific/ean_8
- scanner_settings/code_specific/ean_13
- scanner_settings/code_specific/gs1_databar
- scanner_settings/code_specific/iata
- scanner_settings/code_specific/msi_plessey
- scanner_settings/code_specific/telepen
- scanner_settings/code_specific/uk_plessey
- scanner_settings/code_specific/upc_a
- scanner_settings/code_specific/upc_e
- scanner_settings/code_specific/upc_e1
- scanner_settings/connection_pool
- scanner_settings/formatting
- scanner_settings/indicator_options
- scanner_settings/read_options
- scanner_settings/symbology
- scanner_settings_manager