BLE SDK
Wir bieten ein SDK zur Entwicklung eigener Android-Apps an, welche den BLE-Modus nutzen. Kontaktieren Sie uns gerne für weitere Informationen.
Android BLE SDKUser Guide
Integration, API Reference, Device Control, and Scanner Commands
|
SDK package |
blelibrary-v1.1.aar |
|
Sample project |
BleSDKMemo |
|
Development environment |
Android Studio Chipmunk | 2021.2.1 |
|
Android SDK |
API Level 29 |
Important: Configure the scanner to BLE mode before using this SDK.
1. Overview
This Android BLE SDK is designed for the supported range of Bluetooth barcode scanners. It provides device discovery, BLE connection management, data reception, error handling, and scanner control functions.
Before integration, set the scanner Bluetooth interface to BLE mode. The Android-side SDK communicates with the scanner over BLE. The scanner firmware parses supported text commands and executes the corresponding device or scan-engine function.
1.1 Package Contents
- blelibrary-v1.1.aar — Android library package.
- BleSDKMemo — sample Android Studio project demonstrating SDK integration and API usage.
- This user guide — integration instructions, API reference, protocol commands, and examples.
1.2 Reference Environment
|
Item |
Reference |
|
IDE |
Android Studio Chipmunk | 2021.2.1 |
|
Android SDK |
API Level 29 |
|
Core library |
blelibrary-v1.1.aar |
|
Core manager class |
com.postech.blelibrary.bluetooth.BleManager |
1.3 Integration Prerequisites
- The scanner is powered on and configured for BLE mode.
- Bluetooth is available and enabled on the Android device.
- The application has the Bluetooth permissions required by its Android target version.
- The BLE service has been bound before scanning or connecting.
- A scanner connection has been established before sending device commands.
2. SDK Integration
2.1 Add the AAR Library
Copy blelibrary-v1.1.aar into the app module’s libs directory.
app/└── libs/ └── blelibrary-v1.1.aar
Then add the local AAR dependency in the app module configuration. Use the included BleSDKMemo project as the primary reference for the exact project setup used with this package.
2.2 Recommended Application Flow
|
Step |
Action |
Relevant API |
|
1 |
Obtain the singleton SDK manager. |
BleManager.getInstance() |
|
2 |
Bind the BLE service. |
BindService(context, callback) |
|
3 |
Start BLE device discovery. |
scanBleDevice(true, callback) |
|
4 |
Connect to the selected scanner. |
connect(macAddress, autoConnect) |
|
5 |
Register listeners for connection, errors, and received data. |
setConnectStatusListener(...), setErrorCallback(...), setOnDataReceive(...) |
|
6 |
Send scanner commands after connection succeeds. |
sendSingleCmd(...), hardware helper methods |
|
7 |
Disconnect and unbind when the application exits. |
disconnected(), unBindService(context) |
3. BleManager API Reference
BleManager is the core SDK management class. Use the singleton instance throughout the application.
|
Return Type |
Method |
Description |
|
static BleManager |
getInstance() |
Returns or initializes the singleton manager instance. |
|
void |
BindService(Context context, OnBindServiceCallback callback) |
Binds the BLE service. The callback reports whether service binding succeeded. |
|
void |
unBindService(Context context) |
Unbinds the service and releases resources. Call this when the application exits. |
|
void |
scanBleDevice(boolean isOpen, OnBleScanResultCallback callback) |
Starts or stops BLE scanner discovery. The callback reports discovered devices and scan errors. |
|
void |
connect(String macAddress, boolean autoConnect) |
Connects to a scanner using its Bluetooth MAC address. |
|
void |
disconnected() |
Disconnects the currently connected scanner. |
|
void |
sendSingleCmd(int cmd) |
Sends one integer command supported by the SDK. |
|
void |
sendSingleCmd(String cmd) |
Sends one text command or protocol string to the scanner. |
|
BleManager |
setConnectStatusListener(ConnectStatusListener listener) |
Registers a listener for scanner connection-state changes. |
|
BleManager |
setErrorCallback(ErrorCallback listener) |
Registers a listener for Bluetooth and address errors. |
|
void |
setOnDataReceive(OnDataReceive callback) |
Registers a callback for data received from the scanner. |
|
void |
sendScannerBeep(int durationMs) |
Triggers one buzzer beep. |
|
void |
sendScannerBeepMode(int mode, int interval) |
Triggers a firmware-defined buzzer pattern. |
|
void |
sendScannerMotor(int durationMs) |
Runs the vibration motor for the specified duration. |
|
void |
sendScannerLedGreen(int onTimeMs, int flashCount) |
Controls the green LED. |
|
void |
sendScannerLedRed(int onTimeMs, int flashCount) |
Controls the red LED. |
4. Callback Interfaces
4.1 OnBindServiceCallback
|
Method |
Description |
|
success() |
The BLE service was bound successfully. |
|
fail() |
The BLE service binding failed. |
4.2 ConnectStatusListener
The connectionState(int state) callback reports the scanner connection state.
|
State |
Meaning |
|
0 |
Disconnected |
|
1 |
Connecting |
|
2 |
Connected |
|
3 |
Connection failed |
4.3 ErrorCallback
The errorState(int state) callback reports Bluetooth or device-address errors.
|
State |
Meaning |
|
4 |
The Android device does not support Bluetooth. |
|
5 |
Bluetooth is disabled. |
|
6 |
The scanner device address is invalid. |
4.4 OnBleScanResultCallback
|
Method |
Description |
|
scanBleDevice(BluetoothDevice bluetoothDevice) |
Called when a BLE device is discovered. |
|
scanError(String error) |
Called when an error occurs during BLE scanning. |
5. Scanner Hardware Feedback Control
The SDK can send text protocol strings over BLE to control the scanner buzzer, vibration motor, and LEDs. ScannerHwCommands builds the protocol string, and BleManager.sendSingleCmd(String) transmits it. The service must be bound and the scanner must be connected before these methods are called.
|
Protocol |
Firmware Behavior |
Android SDK Method |
Example |
|
{Beep/<duration>} |
Pwm_Output(duration). Duration must be a positive integer below 60000. |
sendScannerBeep(int durationMs) |
{Beep/200} |
|
{Beep_Mode/<mode>/<interval>} |
Writes the firmware Beep_Control_Struct. Mode and interval follow firmware definitions. |
sendScannerBeepMode(int mode, int interval) |
{Beep_Mode/6/50} |
|
{Motor/<duration>} |
Moto_Out(duration). Duration must be below 60000. |
sendScannerMotor(int durationMs) |
{Motor/400} |
|
{Led/<onTime>/<count>} |
Controls the green good-read LED. |
sendScannerLedGreen(int onTimeMs, int flashCount) |
{Led/200/1} |
|
{Led_Red/<onTime>/<count>} |
Controls the red LED. |
sendScannerLedRed(int onTimeMs, int flashCount) |
{Led_Red/200/3} |
5.1 Buzzer Mode Values
|
Mode Value |
Firmware Definition |
|
0x02 |
One low-frequency beep |
|
0x04 |
High-frequency beep followed by low-frequency beep |
|
0x06 |
Three low-frequency beeps |
|
0x08 |
Low-frequency beep followed by high-frequency beep |
|
0x0B |
High-frequency beep followed by a long low-frequency beep |
5.2 Code Example
BleManager ble = BleManager.getInstance();// Call only after BindService and connect have succeeded.ble.sendScannerBeep(200); // {Beep/200}ble.sendScannerBeepMode(6, 50); // {Beep_Mode/6/50}ble.sendScannerMotor(400); // {Motor/400}ble.sendScannerLedGreen(200, 1); // {Led/200/1}ble.sendScannerLedRed(200, 3); // {Led_Red/200/3}// Raw protocol command:ble.sendSingleCmd("{Beep/200}");
When sending multiple commands sequentially, allow approximately 30 ms between adjacent commands. The reference interval is ScanMatchHelper.CMD_INTERVAL_MS in the ScannerBLE app module.
6. Scanner Information and Control Commands
This section reflects the current firmware command handling in USER/src/BT_BarConfig.c, USER/src/Bar_Scanner.c, and USER/inc/BT_BarConfig.h. Commands may be sent over the BLE transparent channel with BleManager.sendSingleCmd(String cmd), or wrapped in SDK helper methods where available.
SPP and BLE use the same ASCII text command format. The Android SDK is primarily intended for BLE. When the scanner is in SPP mode, a host may send the same ASCII commands through SPP.
6.1 Command Format
|
Item |
Specification |
|
Transmit format |
ASCII text enclosed in braces, for example: {GB100}{G2016} |
|
Encoding |
ASCII text. Do not append an extra binary header unless required by the application protocol. |
|
BLE API |
BleManager.getInstance().sendSingleCmd("{GB100}{G2016}") |
|
Response channel |
BLE mode: Bluetooth_BLE_Send(); SPP mode: Bluetooth_SPP_Send(). |
|
Firmware entry |
USART3_RxClue() → Scanner_Configure(). |
6.2 Readable Scanner Information
|
Function |
Command |
Response |
Notes |
|
Firmware version |
{GB100}{G2016} |
{G2016/FSC-BT 4.0 Software Version 1.0.2\r\n} |
GetVersion or sendSingleCmd |
|
Product ID |
{GB100}{G2012} |
{G2012/STM32_ID:...} |
GetScanerID |
|
Battery status |
{GB100}{G2014} |
{G2014/Battery Voltage:4.02V,Ratio:85%\r\n} |
GetBattery |
|
SPP Bluetooth name |
{GB100}{G1000?} |
{G1000/<name>} |
Reads the current module name |
|
HID Bluetooth name |
{GB100}{G1002?} |
{G1002/<name>} |
Current firmware also reads the module name |
|
Prefix |
{GB100}{G1004?} |
{G1004/<0|1>/<prefix>} |
0 = disabled; 1 = enabled |
|
Suffix |
{GB100}{G1006?} |
{G1006/<0|1>/<suffix>} |
0 = disabled; 1 = enabled |
|
Buzzer configuration |
{GB100}{G1020?} |
{G1020/<mode>} |
mode is the firmware BeepFlag |
|
Output mode |
{GB100}{G1024?} |
{G1024/1|2|3} |
1 = USB; 2 = Serial; 3 = Bluetooth |
|
Sleep time |
{GB100}{G1026?} |
{G1026/<seconds>} |
Unit: seconds |
|
Power-off time |
{GB100}{G1050?} |
{G1050/<minutes>} |
Unit: minutes |
6.3 Writable Configuration and Controls
|
Function |
Command |
Parameter |
Response / Behavior |
|
Set SPP name |
{G1000/<name>} |
Bluetooth name string |
May reboot or refresh advertising. |
|
Set HID name |
{G1002/<name>} |
Bluetooth name string |
Current firmware writes AT+NAME as well. |
|
Set prefix |
{G1004/<0|1>/<prefix>} |
0 = off; 1 = on |
BLE returns {GB800}. |
|
Set suffix |
{G1006/<0|1>/<suffix>} |
0 = off; 1 = on |
BLE returns {GB800}. |
|
Set buzzer mode |
{G1020/<mode>} |
Firmware BeepFlag value |
BLE returns {GB800}. |
|
Set output mode |
{G1024/1} or {G1024/2} |
1 = Serial; 2 = USB |
Query may return 3 for Bluetooth. BLE returns {GB800}. |
|
Set sleep time |
{G1026/<seconds>} |
1–4 decimal digits |
Unit: seconds. BLE returns {GB800}. |
|
Set power-off time |
{G1050/<minutes>} |
1–4 decimal digits |
Unit: minutes. SPP returns {GB800}. |
|
Start scan |
{Start} |
None |
No fixed response. |
|
Close sleep timer |
{off/Sleep} |
None |
No fixed response. |
|
Enable read output |
{on/Read} |
None |
BLE returns {GB800}. |
|
Disable read output |
{off/Read} |
None |
BLE returns {GB800}. |
|
Restore defaults |
{Init} |
None |
The scanner performs a soft reset. |
|
Enter IAP mode |
{TOIAP} |
None |
The scanner reboots into IAP. |
|
Single beep |
{Beep/<ms>} |
Duration |
No fixed response. |
|
Buzzer pattern |
{Beep_Mode/<mode>/<interval>} |
Decimal integers |
No fixed response. |
|
Vibration |
{Motor/<ms>} |
Duration |
No fixed response. |
|
Motor on |
{MotorON} |
None |
No fixed response. |
|
Motor off |
{MotorOFF} |
None |
No fixed response. |
|
Good-read feedback |
{DataOK} |
None |
Triggers buzzer and motor feedback. |
|
LED control |
{Led/<ms>} or {Led_Red/<ms>} |
Duration |
No fixed response. |
7. Symbology Configuration
The firmware converts symbology commands into low-level scan-engine configuration commands. Use {Name/1} to enable a symbology and {Name/0} to disable it.
|
Symbology |
Symbology |
Symbology |
Symbology |
|
Code128 |
Code39 |
UPCA |
UPCE |
|
UPCE1 |
EAN8 |
EAN13 |
BooklandEAN |
|
IssnEAN |
GS1128 |
ISBT128 |
TriopticCode39 |
|
Code39Prefix |
Code39FullASCII |
Code11 |
Interleaved2of5 |
|
I2of5Reduced |
DTF |
Codabar |
CLSIEditing |
|
NOTISEditing |
MSI |
Chinese2of5 |
Matrix2of5 |
|
GS1DataBar14 |
GS1DataBarLimited |
GS1DataBarExpanded |
CC-C |
|
CC-AB |
TLC39 |
PDF47 |
MicroPDF47 |
|
Code128Emulation |
DataMatrix |
Maxiccode |
QRcode |
|
MicroQR |
Aztec |
HanXin |
USPostnet |
|
USPlanet |
UKPostal |
JapanPostal |
Australia |
|
KixCode |
UPU_FICSPostal |
Code93 |
USPS4CB |
7.1 Code ID Output
|
Function |
Command |
Description |
|
Symbol Code ID |
{Code ID/2} |
Enables Symbol Code ID output. |
|
AIM Code ID |
{Code ID/1} |
Enables AIM Code ID output. |
|
Disable Code ID |
{Code ID/0} |
Disables Code ID output. |
For scan-engine configuration, the current firmware sends {OK} through SPP when a command succeeds and {ERR} when it fails or times out. The BLE branch does not provide a dedicated {OK}/{ERR} response for this path. Android BLE applications should therefore implement a timeout and, where required, read-back verification.
8. Android Command Examples
|
Purpose |
Java Call |
|
Read firmware version |
BleManager.getInstance().sendSingleCmd("{GB100}{G2016}"); |
|
Read battery status |
BleManager.getInstance().sendSingleCmd("{GB100}{G2014}"); |
|
Start scanning |
BleManager.getInstance().sendSingleCmd("{Start}"); |
|
Enable QR Code |
BleManager.getInstance().sendSingleCmd("{QRcode/1}"); |
|
Disable Code ID |
BleManager.getInstance().sendSingleCmd("{Code ID/0}"); |
|
Set prefix to A- |
BleManager.getInstance().sendSingleCmd("{G1004/1/A-}"); |
8.1 Operational Notes
- Keep approximately 30 ms between consecutive commands.
- After commands that reboot the scanner, restore defaults, or change the Bluetooth name, wait until the scanner advertises again or reconnects before sending another command.
- For commands without a fixed response, use application-side timeout handling where confirmation is required.
- Use the included BleSDKMemo project as the implementation reference for service binding, device discovery, connection, and callbacks.
9. Quick Integration Checklist
- ☐ Scanner configured to BLE mode
- ☐ blelibrary-v1.1.aar added to the app module
- ☐ BLE service successfully bound
- ☐ Scanner discovered and connected
- ☐ Connection and error listeners registered
- ☐ Data receive callback registered
- ☐ Commands sent only after connection state = 2
- ☐ Approximately 30 ms delay used for sequential commands
- ☐ Reconnect handling implemented for reboot/name-change commands
- ☐ Service unbound and resources released on application exit