SDK Integration Steps
1. Initialize QNSDK
Use QNBleApi.initSdk for initialization. For details, refer to the Development Process.
2. Set Scan Callback Listener for Height and Weight Scale
Before starting Bluetooth scanning, set up the listener via QNBleApi.setBleDeviceDiscoveryListener. Call this method once, and set it to null/nil when scanning is no longer needed.
Android Example:
QNBleApi mQNBleApi = QNBleApi.getInstance(context);
mQNBleApi.setBleDeviceDiscoveryListener(new QNBleDeviceDiscoveryListener() {
@Override
public void onDeviceDiscover(QNBleDevice device) {
//Height scale devices found during scanning will be called back here
}
...
});
iOS Example:
// Set delegate
QNBleApi *bleApi = [QNBleApi sharedBleApi];
bleApi.discoveryListener = self;
bleApi.connectionChangeListener = self;
bleApi.dataListener = self;
bleApi.bleStateListener = self;
3. Start Bluetooth Scanning
Ensure Bluetooth is enabled.
- Android: Additionally verify
Location PermissionandLocation Serviceare enabled. - iOS: Confirm Bluetooth usage permission is granted (required since iOS 13).
Android Notes:
- For apps with
targetSdkVersion >= 23, location permission is required for BLE scanning (details).- Location Service is not mandatory but may be required on some devices.
iOS Note:
- System Bluetooth usage permission must be authorized.
Use QNBleApi.startBleDeviceDiscovery to start scanning. Scanned devices are returned via QNBleDeviceDiscoveryListener.
Configure scan settings via QNConfig.
Android Example:
QNBleApi.getInstance(context).startBleDeviceDiscovery(new QNResultCallback() {
@Override
public void onResult(int code, String msg) {
//This method does not callback Bluetooth devices, but indicates whether scanning started successfully
if (code != CheckStatus.OK.getCode()) {
Toast.makeText(context, code+":"+msg).show();
}
}
});
iOS Example:
//Start scanning
[[QNBleApi sharedBleApi] startBleDeviceDiscovery:^(NSError *error) {
//This callback indicates whether the scanning method started successfully
if (error) {
NSLog([NSString stringWithFormat:@"Failed to start scanning method, reason: %@",error]);
}
}];
4. Set Connection State Listener for Height and Weight Scale
Set Bluetooth connection state listener via QNBleApi.setBleConnectionChangeListener to receive connection state changes.
Android Example:
QNBleApi.getInstance(this).setBleConnectionChangeListener(new QNBleConnectionChangeListener() {
//Connecting
@Override
public void onConnecting(QNBleDevice device) {
}
//Connected, note that other Bluetooth operations cannot be performed at this time
@Override
public void onConnected(QNBleDevice device) {
}
//Service discovered
@Override
public void onServiceSearchComplete(QNBleDevice device) {
}
//Disconnecting, will be called back immediately when disconnect is called
@Override
public void onDisconnecting(QNBleDevice device) {
}
// Disconnected, callback after disconnection
@Override
public void onDisconnected(QNBleDevice device) {
}
//Connection error occurred, refer to the appendix for error codes
@Override
public void onConnectError(QNBleDevice device, int errorCode) {
}
//Can execute other Bluetooth operation API methods
@Override
public void onStartInteracting(QNBleDevice device) {
}
});
iOS Example:
- (void)onConnecting:(QNBleDevice *)device {
}
- (void)onConnected:(QNBleDevice *)device {
}
- (void)onServiceSearchComplete:(QNBleDevice *)device {
}
- (void)onDisconnecting:(QNBleDevice *)device {
}
- (void)onDisconnected:(QNBleDevice *)device {
}
- (void)onConnectError:(QNBleDevice *)device error:(NSError *)error {
}
5. Set Data Measurement Listener for Height and Weight Scale
Set measurement data listener via QNBleApi.setDataListener，to receive measurement states and data.
Android Example:
QNBleApi.getInstance(this).setDataListener(new QNScaleDataListener() {
@Override
public void onSetHeightScaleConfigState(QNBleDevice device, boolean isLanguageSuccess, boolean isWeightUnitSuccess, boolean isHeightUnitSuccess, boolean isVolumeSuccess) {
}
@Override
public void onGetHeightScaleConfig(QNBleDevice device, QNHeightDeviceFunction function) {
}
@Override
public void onResetHeightScaleState(QNBleDevice device, boolean isSuccess) {
}
@Override
public void onClearHeightScaleWifiConfigState(QNBleDevice device, boolean isSuccess) {
}
@Override
public void onGetHeightScaleWifiConfig(QNBleDevice device, boolean isSuccess, String ssid) {
}
@Override
public void onScanHeightScaleWifiSsidResult(QNBleDevice device, String ssid, int rssi) {
}
@Override
public void onScanHeightScaleWifiSsidFinish(QNBleDevice device, int resultCode) {
}
//Barcode scanner gets scanning results
@Override
public void onGetBarCode(String devMac, String barCode) {
}
//Barcode scanner failed to get scanning results
@Override
public void onGetBarCodeFail(String devMac) {
}
//Barcode scanner connection status change
@Override
public void onGetBarCodeGunState(String devMac, boolean isConnected) {
}
//Real-time weight data callback
@Override
public void onGetUnsteadyWeight(QNBleDevice device, double weight) {
}
//Measurement result data callback
@Override
public void onGetScaleData(QNBleDevice device, QNScaleData data) {
}
//Stored data callback
@Override
public void onGetStoredScale(QNBleDevice device, List<QNScaleStoreData> storedDataList) {
}
...
});
iOS Example:
- (void)onGetUnsteadyWeight:(QNBleDevice *)device weight:(double)weight {
}
- (void)onGetScaleData:(QNBleDevice *)device data:(QNScaleData *)scaleData {
}
- (void)onGetStoredScale:(QNBleDevice *)device data:(NSArray<QNScaleStoreData *> *)storedDataList {
}
/// Get barcode
- (void)onGetBarCode:(NSString *)barCode mac:(NSString *)mac {
self.unstableWeightLabel.text = [NSString stringWithFormat:@"Barcode content: %@",barCode];
}
- (void)onGetBarCodeFail:(NSString *)mac {
self.unstableWeightLabel.text = [NSString stringWithFormat:@"Failed to get barcode: %@",barCode];
}
- (void)onGetBarCodeGunState:(BOOL)isConnect mac:(NSString *)mac {
if (isConnect) {
self.unstableWeightLabel.text = @"Device connected to barcode scanner";
}else {
self.unstableWeightLabel.text = @"Barcode scanner disconnected";
}
}
- (void)onSetHeightScaleConfigState:(BOOL)isLanguageSuccess
isWeightUnitSuccess:(BOOL)isWeightUnitSuccess
isHeightUnitSuccess:(BOOL)isHeightUnitSuccess
isVolumeSuccess:(BOOL)isVolumeSuccess
device:(QNBleDevice *)device {
}
- (void)onGetHeightScaleConfig:(QNHeightDeviceFunction *)function device:(QNBleDevice *)device {
}
- (void)onResetHeightScaleState:(BOOL)state device:(QNBleDevice *)device {
}
- (void)onGetHeightScaleWifiConfig:(BOOL)state ssid:(NSString *)ssid device:(QNBleDevice *)device {
}
- (void)onClearHeightScaleWifiConfigState:(BOOL)state device:(QNBleDevice *)device {
}
- (void)onScanHeightScaleWifiSsidResult:(NSString *)ssid rssi:(int)rssi device:(QNBleDevice *)device {
}
- (void)onScanHeightScaleWifiSsidFinish:(int)state device:(QNBleDevice *)device {
}
6. Connect to Height and Weight Scale
After receiving a device callback, initiate connection via QNBleApi.connectHeightScaleDevice if it matches your logic.
Android Example:
QNBleApi.getInstance(this).connectHeightScaleDevice(mBleDevice, deviceConfig, (code, msg) -> {
//Indicates whether the method executed successfully
if (code != CheckStatus.OK.getCode()) {
Toast.makeText(context, code+":"+msg).show();
}
})
iOS Example:
QNHeightDeviceConfig *config = [[QNHeightDeviceConfig alloc]init];
QNUser *user = [[QNUser alloc]init];
user.gender = @"female";
user.birthday = [NSDate dateWithString:@"1995-01-01" format:@"yyyy-MM-dd"];
config.curUser = user;
[_bleApi connectHeightScaleDevice:device config:config callback:^(NSError *error) {
if (error) {
NSLog(@"%@", error.localizedDescription);
}
}];
Wi-Fi Configuration
To configure Wi-Fi, pass a QNWiFiConfig
7. Disconnect Device
Actively disconnect viaQNBleApi.disconnectDevice
Android Example:
QNBleApi.getInstance(RulerActivity.this).disconnectDevice(mac, new QNResultCallback() {
@Override
public void onResult(int code, String msg) {
}
});
iOS Example:
[_bleApi disconnectDeviceWithMac:nil callback:^(NSError *error) {
}];
// or
[_bleApi disconnectDeviceWithMac:device.mac callback:^(NSError *error) {
}];
8. Height and Weight Scale Configuration Management
After successful connection, you can perform various configuration management operations on the height and weight scale.
8.1 Get Height Scale Configuration
Use QNBleApi.getHeightScaleConfig to get current height scale configuration information.(currently only supports CP30G).
Android Example:
QNBleApi.getInstance(this).getHeightScaleConfig((code, msg) -> {
});
iOS Example:
[_bleApi getHeightScaleConfig:^(NSError *error) {
if (error) {
NSLog(@"%@", error.localizedDescription);
}
}];
Configuration information will be returned through the OnGetHeightScaleConfig callback of QNScaleDataListener.
8.2 Set Height Scale Configuration
Use QNBleApi.setHeightScaleConfig to update height scale related configuration.
Android Example:
QNHeightDeviceFunction function = new QNHeightDeviceFunction();
function.setLanguage(lang);
function.setWeightUnit(weight);
function.setHeightUnit(height);
function.setVolume(volume);
QNBleApi.getInstance(this).setHeightScaleConfig(function, (code, msg) -> {
});
iOS Example:
QNHeightDeviceFunction *function = [[QNHeightDeviceFunction alloc] init];
// Set related configuration parameters
function.weightUnit = QNUnitKG;
function.heightUnit = QNHeightUnitCM;
function.voiceLanguage = QNLanguageZH;
function.volume = QNVolumeOne;
[_bleApi setHeightScaleConfig:function callback:^(NSError *error) {
if (error) {
NSLog(@"%@", error.localizedDescription);
}
}];
Setting results will be returned through the OnSetHeightScaleConfigState callback of QNScaleDataListener.
8.3 Reset to Factory Settings
Use QNBleApi.resetHeightScale to restore height scale to factory settings (currently only supports CP30G).
Android Example:
QNBleApi.getInstance(this).resetHeightScale((code, msg) -> {
});
iOS Example:
[_bleApi resetHeightScale:^(NSError *error) {
if (error) {
NSLog(@"%@", error.localizedDescription);
}
}];
Reset results will be returned through the OnResetHeightScaleState callback of QNScaleDataListener.
9. WiFi Configuration Management
Height and weight scales support WiFi configuration functionality, allowing WiFi configuration management operations.
9.1 Scan Available WiFi
Use QNBleApi.scanHeightScaleWifiSsid to scan available WiFi names for height scale.
Android Example:
QNBleApi.getInstance(this).scanHeightScaleWifiSsid((code, msg) -> {
});
iOS Example:
[_bleApi scanHeightScaleWifiSsid:^(NSError *error) {
if (error) {
NSLog(@"%@", error.localizedDescription);
}
}];
Scanned WiFi names will be returned through the OnScanHeightScaleWifiSsidResult callback of QNScaleDataListener, and scan completion will be notified through the OnScanHeightScaleWifiSsidFinish callback.
9.2 Start WiFi Pairing
Use QNBleApi.startPairHeightScaleWifi to start height scale WiFi pairing.
Android Example:
QNWiFiConfig pairWifiConfig = new QNWiFiConfig();
pairWifiConfig.setSsid("wifiName");
pairWifiConfig.setPwd("wifiPwd");
pairWifiConfig.setServeUrl("serverUrl");
pairWifiConfig.setEncryptionKey("encryption");
pairWifiConfig.setFotaUrl("otaUrl");
QNBleApi.getInstance(this).startPairHeightScaleWifi(pairWifiConfig, (code, msg) -> {
});
iOS Example:
QNWifiConfig *wifiConfig = [[QNWifiConfig alloc] init];
wifiConfig.ssid = @"wifiName";
wifiConfig.pwd = @"wifiPwd";
wifiConfig.serveUrl = @"serverUrl";
wifiConfig.encryptionKey = @"encryption";
wifiConfig.fotaUrl = @"otaUrl";
[_bleApi startPairHeightScaleWifi:wifiConfig callback:^(NSError *error) {
if (error) {
NSLog(@"%@", error.localizedDescription);
}
}];
9.3 Get WiFi Configuration
Use QNBleApi.getHeightScaleWifiConfig to get height scale WiFi configuration (currently only supports CP30G).
Android Example:
QNBleApi.getInstance(this).getHeightScaleWifiConfig((code, msg) -> {
});
iOS Example:
[_bleApi getHeightScaleWifiConfig:^(NSError *error) {
if (error) {
NSLog(@"%@", error.localizedDescription);
}
}];
WiFi configuration information will be returned through the OnGetHeightScaleWifiConfig callback of QNScaleDataListener.
9.4 Clear WiFi Configuration
Use QNBleApi.clearHeightScaleWifiConfig to clear height scale WiFi configuration (currently only supports CP30G).
Android Example:
QNBleApi.getInstance(this).clearHeightScaleWifiConfig((code, msg) -> {
});
iOS Example:
[_bleApi clearHeightScaleWifiConfig:^(NSError *error) {
if (error) {
NSLog(@"%@", error.localizedDescription);
}
}];
Clear results will be returned through the OnClearHeightScaleWifiConfigState callback of QNScaleDataListener.