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: Manage connection pools using 4-character hexadecimal IDs to ensure exclusive device pairing. Prevent previously paired devices from hijacking active connections by assigning unique connection pool IDs.
- 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