BleConnect

The BleConnect module provides comprehensive Bluetooth Low Energy (BLE) device management capabilities, including device discovery, connection, authentication, and binding. It handles the complete connection lifecycle from initial scanning through authentication to full readiness, with granular state tracking and error handling at each stage.

Prerequisites

• iOS 12.0 or later
• Bluetooth Low Energy (BLE) capable device
• NSBluetoothPeripheralUsageDescription permission in Info.plist
• NSBluetoothCentralUsageDescription permission in Info.plist
• User must grant Bluetooth permissions at runtime

Data Models

TSPeripheral

Complete peripheral device information container.

Property	Type	Description
systemInfo	TSPeripheralSystem *	System-level information including Bluetooth connection details, MAC address, and device identification
screenInfo	TSPeripheralScreen *	Screen properties including size, shape, border radius, and preview dimensions
projectInfo	TSPeripheralProject *	Project-level information including firmware version, serial number, and device identifiers
capability	TSPeripheralCapability *	Device capability information including supported features and functionalities
limitation	TSPeripheralLimitations *	Device feature limitations including maximum counts for alarms, reminders, and contacts

TSPeripheralSystem

System-level information for peripheral devices.

Property	Type	Description
peripheral	CBPeripheral *	Core Bluetooth peripheral object for device communication
central	CBCentralManager *	Bluetooth central manager controlling connections and scanning
uuid	NSString *	UUID string from CBPeripheral.identifier (read-only)
mac	NSString *	Device MAC address in colon-separated format (e.g., "DE:82:47:15:28:B0")
bleName	NSString *	Device Bluetooth name broadcasted for user identification
RSSI	NSNumber *	Bluetooth signal strength indicator (RSSI value)
advertisementData	NSDictionary *	Raw advertisement data dictionary containing service UUIDs and manufacturer data

TSPeripheralProject

Project-related information for peripheral devices.

Property	Type	Description
projectId	NSString *	Unique identifier for the project type
companyId	NSString *	Company identifier from BLE manufacturer data (typically 4-character hex string)
brand	NSString *	Device brand name (maximum 16 characters)
model	NSString *	Device model identifier (maximum 16 characters)
firmVersion	NSString *	Current firmware version (semantic versioning format)
virtualVersion	NSString *	Special version number for internal version control
serialNumber	NSString *	Unique device serial number
mainProjNum	NSString *	Main project number used in FitCloudKit
subProjNum	NSString *	Sub project number for variant identification

TSPeripheralScreen

Screen information for peripheral devices.

Property	Type	Description
shape	TSPeriphShape	Device physical shape (circle, square, vertical rectangle, horizontal rectangle)
screenSize	CGSize	Screen size in pixels
screenBorderRadius	CGFloat	Screen border radius in pixels
dialPreviewSize	CGSize	Watch face preview image size in pixels
dialPreviewBorderRadius	CGFloat	Watch face preview image corner radius in pixels
videoPreviewSize	CGSize	Video preview stream size in pixels
videoPreviewBorderRadius	CGFloat	Video preview stream corner radius in pixels

TSPeripheralCapability

Device capability container organizing feature support into distinct modules.

Property	Type	Description
featureAbility	TSFeatureAbility *	Coarse-grained feature module support flags (YES/NO)
messageAbility	TSMessageAbility *	Fine-grained message type support details (which types supported)
dailyActivityAbility	TSDailyActivityAbility *	Fine-grained daily activity type support (which types supported)
sleepAlgorithm	NSInteger	Device sleep algorithm type (0=LongestNight, 1=LongestOnly)

TSFeatureAbility

Feature module capability flags indicating which major features are supported.

Property	Type	Description
originAbility	NSData *	Raw ability data from device (maximum 16 bytes)
supportCapabilities	TSPeripheralSupportAbility	Parsed capability flags indicating supported features
isSupportStepCounting	BOOL	Step counting support
isSupportDistanceCounting	BOOL	Distance counting support
isSupportCalorieCounting	BOOL	Calorie counting support
isSupportHeartRate	BOOL	Heart rate monitoring support
isSupportBloodPressure	BOOL	Blood pressure monitoring support
isSupportBloodOxygen	BOOL	Blood oxygen monitoring support
isSupportStress	BOOL	Stress monitoring support
isSupportSleep	BOOL	Sleep monitoring support
isSupportTemperature	BOOL	Temperature monitoring support
isSupportECG	BOOL	ECG monitoring support
isSupportFemaleHealth	BOOL	Female health features support
isSupportInitiateWorkout	BOOL	Initiate workout feature support
isSupportWeightManagement	BOOL	Weight management support
isSupportReminders	BOOL	Reminders support
isSupportCallManagement	BOOL	Call management support
isSupportAppNotifications	BOOL	App notifications support
isSupportMusicControl	BOOL	Music control support
isSupportWeatherDisplay	BOOL	Weather display support
isSupportFindMyPhone	BOOL	Find my phone feature support
isSupportAlarmClock	BOOL	Alarm clock support
isSupportWorldClock	BOOL	World clock support
isSupportMapNavigation	BOOL	Map navigation support
isSupportShakeCamera	BOOL	Shake to take photo support
isSupportCameraPreview	BOOL	Camera video preview support
isSupportEWallet	BOOL	E-wallet support
isSupportBusinessCard	BOOL	Business card support
isSupportPhotoAlbum	BOOL	Photo album support
isSupportEBook	BOOL	E-book support
isSupportVoiceRecording	BOOL	Voice recording support
isSupportAppStore	BOOL	App store support
isSupportMotionGames	BOOL	Motion sensing games support
isSupportSportUpload	BOOL	Sport upload support
isSupportERNIEBot	BOOL	ERNIE Bot support
isSupportChatGPT	BOOL	ChatGPT support
isSupportLoversFeature	BOOL	Lovers feature support
isSupportContacts	BOOL	Contacts feature support
isSupportEmergencyContacts	BOOL	Emergency contacts support
isSupportMuslimPrayer	BOOL	Muslim prayer reminders support
isSupportQiblaCompass	BOOL	Qibla compass support
isSupportNFCPayment	BOOL	NFC payment support
isSupportVoiceAssistant	BOOL	Voice assistant support
isSupportFacePush	BOOL	Watch face push support
isSupportCustomFace	BOOL	Custom watch face support
isSupportSlideshowFace	BOOL	Slideshow watch face support
isSupportDialComponent	BOOL	Dial component support
isSupportTimeSettings	BOOL	Time settings support
isSupportLanguage	BOOL	Language settings support
isSupportUserInfoSettings	BOOL	User information settings support
isSupportDailyActivity	BOOL	Daily activity support
isSupportFirmwareUpgrade	BOOL	Firmware upgrade support
isSupportUnitSettings	BOOL	Unit settings support
isSupportEarbudsAPIs	BOOL	Earbuds APIs support
isSupportAIChat	BOOL	AI chat support
isSupportAIChatAudioUsingSco	BOOL	AI chat audio using SCO support
isSupportScreenLock	BOOL	Screen lock support
isSupportGameLock	BOOL	Game lock support

TSMessageAbility

Message notification ability managing which specific message types are supported.

Property	Type	Description
(No public properties)	-	All data is encapsulated; use query methods to check support

TSDailyActivityAbility

Daily activity ability managing which activity types are supported and displayed.

Property	Type	Description
(No public properties)	-	All data is encapsulated; use query methods to check support

TSPeripheralConnectParam

Connection parameters for device connection and binding.

Property	Type	Description
userId	NSString *	User ID for device connection (required, must not be empty)
userInfo	TSUserInfoModel *	User information model for device personalization
authCode	NSString *	Authentication code from QR code scanning during binding
allowConnectWithBT	BOOL	Flag indicating whether Bluetooth connection is allowed
brand	NSString *	Phone brand information (e.g., "Apple", "Samsung")
model	NSString *	Phone model information (e.g., "iPhone 12", "iPhone 13 Pro")
systemVersion	NSString *	Phone system version (e.g., "iOS 15.0")

TSPeripheralScanParam

Advanced scan parameters for device discovery.

Property	Type	Description
userId	NSString *	User ID for device connection
serviceUUIDs	NSArray<CBUUID *> *	Service UUIDs to filter peripherals (nil to discover all)
solicitedServiceUUIDs	NSArray<CBUUID *> *	Solicited service UUIDs filter (nil to not filter)
deviceName	NSString *	Device name filter (nil to discover all)
macAddress	NSString *	MAC address filter (nil to discover all)
onlyUnconnected	BOOL	Only return unconnected peripherals (default NO)
allowDuplicates	BOOL	Allow duplicate discovery of same peripheral (default NO)
scanTimeout	NSInteger	Scan timeout in seconds (0 = no timeout)

TSPeripheralLimitations

Device feature limitations defining hardware and firmware constraints.

Property	Type	Description
maxAlarmCount	UInt8	Maximum number of alarm clocks (0 = not supported)
maxContactCount	UInt8	Maximum number of contacts (0 = not supported)
maxEmergencyContactCount	UInt8	Maximum number of emergency contacts (0 = not supported, 255 = unlimited)
maxPushDialCount	UInt8	Maximum number of custom watch face slots (0 = not supported)
maxInnerDialCount	UInt8	Number of pre-installed watch faces
maxWorldClockCount	UInt8	Maximum number of world clocks (0 = not supported, 255 = unlimited)
maxSedentaryReminderCount	UInt8	Maximum number of sedentary reminders (0 = not supported, 255 = unlimited)
maxWaterDrinkingReminderCount	UInt8	Maximum number of water drinking reminders (0 = not supported, 255 = unlimited)
maxMedicationReminderCount	UInt8	Maximum number of medication reminders (0 = not supported, 255 = unlimited)
maxCustomReminderCount	UInt8	Maximum number of custom reminders (0 = not supported, 255 = unlimited)

TSBluetoothSystem

Complete Bluetooth system information including both BLE and Classic Bluetooth.

Property	Type	Description
bleInfo	TSBluetoothInfo *	BLE (Bluetooth Low Energy) adapter information
btInfo	TSBluetoothInfo *	BT (Classic Bluetooth) adapter information

TSBluetoothInfo

Bluetooth adapter information model.

Property	Type	Description
macAddress	NSString *	Bluetooth MAC address in colon-separated format (may be nil on iOS)
name	NSString *	Bluetooth adapter name
status	TSBleStatus	Bluetooth adapter connection status

Enumerations

TSBleConnectionState

Bluetooth connection state during the connection lifecycle.

Value	Name	Description
0	eTSBleStateDisconnected	Not connected (initial state or after any failure)
1	eTSBleStateConnecting	Establishing BLE physical connection
2	eTSBleStateAuthenticating	Performing bind/login authentication
3	eTSBleStatePreparingData	Fetching device information after authentication
4	eTSBleStateConnected	Connected and ready for data operations

TSScanCompletionReason

Reasons why BLE scanning completes.

Value	Name	Description
1000	eTSScanCompleteReasonTimeout	Scan timeout reached
1001	eTSScanCompleteReasonBleNotReady	Bluetooth not ready
1002	eTSScanCompleteReasonPermissionDenied	Bluetooth permissions denied
1003	eTSScanCompleteReasonUserStopped	User manually stopped scan
1004	eTSScanCompleteReasonSystemError	System error occurred
1005	eTSScanCompleteReasonNotSupport	Bluetooth not supported

TSBleStatus

Bluetooth adapter connection status.

Value	Name	Description
0	TSBleDisconnected	Not connected
1	TSBleConnected	Connected (physical connection established)
2	TSBleReady	Ready (connected and Notify/SPP opened)

TSPeriphShape

Device physical shape characteristics.

Value	Name	Description
0	eTSPeriphShapeUnknow	Unknown shape
1	eTSPeriphShapeCircle	Circular device
2	eTSPeriphShapeSquare	Square device
3	eTSPeriphShapeVerticalRectangle	Vertical rectangle device
4	eTSPeriphShapeTransverseRectangle	Horizontal rectangle device

TSPeripheralSupportAbility

Bit flags indicating peripheral feature support (uint64_t).

Bit Range	Category	Flags
0-15	Health Features	TSPeripheralSupportStepCounting, TSPeripheralSupportDistanceCounting, TSPeripheralSupportCalorieCounting, TSPeripheralSupportHeartRate, TSPeripheralSupportBloodPressure, TSPeripheralSupportBloodOxygen, TSPeripheralSupportStress, TSPeripheralSupportSleep, TSPeripheralSupportTemperature, TSPeripheralSupportECG, TSPeripheralSupportFemaleHealth, TSPeripheralSupportInitiateWorkout, TSPeripheralSupportDailyActivity, TSPeripheralSupportWeightManagement
16-33	Smart Features	TSPeripheralSupportReminders, TSPeripheralSupportCallManagement, TSPeripheralSupportAppNotifications, TSPeripheralSupportMusicControl, TSPeripheralSupportWeatherDisplay, TSPeripheralSupportFindMyPhone, TSPeripheralSupportAlarmClock, TSPeripheralSupportWorldClock, TSPeripheralSupportMapNavigation, TSPeripheralSupportShakeCamera, TSPeripheralSupportCameraPreview, TSPeripheralSupportEWallet, TSPeripheralSupportBusinessCard, TSPeripheralSupportPhotoAlbum, TSPeripheralSupportEBook, TSPeripheralSupportVoiceRecording, TSPeripheralSupportAppStore, TSPeripheralSupportMotionGames
34-36	AI Features	TSPeripheralSupportSportUpload, TSPeripheralSupportERNIEBot, TSPeripheralSupportChatGPT
37-39	Social Features	TSPeripheralSupportLoversFeature, TSPeripheralSupportContacts, TSPeripheralSupportEmergencyContacts
40-41	Religious Features	TSPeripheralSupportMuslimPrayer, TSPeripheralSupportQiblaCompass
42-46	Hardware Features	TSPeripheralSupportNFCPayment, TSPeripheralSupportVoiceAssistant, TSPeripheralSupportFacePush, TSPeripheralSupportCustomFace, TSPeripheralSupportSlideshowFace
47-51	System Settings	TSPeripheralSupportTimeSettings, TSPeripheralSupportLanguageSettings, TSPeripheralSupportUserInfoSettings, TSPeripheralSupportFirmwareUpgrade, TSPeripheralSupportUnitSettings
52-63	Reserved	TSPeripheralSupportEarbudsAPIs, TSPeripheralSupportDialComponent, TSPeripheralSupportAIChat, TSPeripheralSupportAIChatAudioUsingSco, TSPeripheralSupportScreenLock, TSPeripheralSupportGameLock

Callback Types

TSScanDiscoveryBlock

Device discovery callback during scanning.

typedef void(^TSScanDiscoveryBlock)(TSPeripheral *_Nonnull peripheral);

Parameter	Type	Description
peripheral	TSPeripheral *	Discovered peripheral with device name, ID, and other information

TSScanCompletionBlock

Scan completion callback.

typedef void(^TSScanCompletionBlock)(TSScanCompletionReason reason, NSError * _Nullable error);

Parameter	Type	Description
reason	TSScanCompletionReason	Reason for scan completion (timeout, user stopped, error, etc.)
error	NSError *	Optional error details if scan failed

TSBleConnectionStateCallback

Bluetooth connection state change callback.

typedef void (^TSBleConnectionStateCallback)(TSBleConnectionState connectionState);

Parameter	Type	Description
connectionState	TSBleConnectionState	Current connection state during the connection lifecycle

TSBleConnectionCompletionBlock

Bluetooth connection completion callback.

typedef void (^TSBleConnectionCompletionBlock)(TSBleConnectionState connectionState, NSError *_Nullable error);

Parameter	Type	Description
connectionState	TSBleConnectionState	Final connection state (eTSBleStateConnected on success, eTSBleStateDisconnected on failure)
error	NSError *	Optional error details if connection failed

API Reference

Get current Bluetooth connection state

- (void)getConnectState:(TSBleConnectionStateCallback)completion;

Parameter	Type	Description
completion	TSBleConnectionStateCallback	Callback returning current connection state

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;

[bleConnect getConnectState:^(TSBleConnectionState connectionState) {
    switch (connectionState) {
        case eTSBleStateDisconnected:
            TSLog(@"Device is not connected");
            break;
        case eTSBleStateConnecting:
            TSLog(@"Device is connecting");
            break;
        case eTSBleStateAuthenticating:
            TSLog(@"Device is authenticating");
            break;
        case eTSBleStatePreparingData:
            TSLog(@"Device is preparing data");
            break;
        case eTSBleStateConnected:
            TSLog(@"Device is connected and ready");
            break;
    }
}];

Start searching for Bluetooth devices

- (void)startSearchPeripheral:(NSTimeInterval)timeout
           discoverPeripheral:(TSScanDiscoveryBlock)discoverPeripheral
                   completion:(TSScanCompletionBlock)completion;

Parameter	Type	Description
timeout	NSTimeInterval	Scan timeout in seconds (0 = default 30 seconds)
discoverPeripheral	TSScanDiscoveryBlock	Callback triggered when a new device is discovered
completion	TSScanCompletionBlock	Callback when scan completes or times out

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;

[bleConnect startSearchPeripheral:30.0
              discoverPeripheral:^(TSPeripheral *peripheral) {
    TSLog(@"Found device: %@", peripheral.systemInfo.bleName);
    TSLog(@"MAC: %@", peripheral.systemInfo.mac);
    TSLog(@"RSSI: %@", peripheral.systemInfo.RSSI);
} completion:^(TSScanCompletionReason reason, NSError *error) {
    if (error) {
        TSLog(@"Scan failed with error: %@", error.localizedDescription);
    } else {
        switch (reason) {
            case eTSScanCompleteReasonTimeout:
                TSLog(@"Scan timeout");
                break;
            case eTSScanCompleteReasonUserStopped:
                TSLog(@"Scan stopped by user");
                break;
            default:
                TSLog(@"Scan completed with reason: %ld", (long)reason);
        }
    }
}];

Start searching with advanced parameters

- (void)startSearchPeripheralWithParam:(TSPeripheralScanParam *)param
                    discoverPeripheral:(TSScanDiscoveryBlock)discoverPeripheral
                            completion:(TSScanCompletionBlock)completion;

Parameter	Type	Description
param	TSPeripheralScanParam *	Scan parameters including filters and timeout
discoverPeripheral	TSScanDiscoveryBlock	Callback triggered when a new device is discovered
completion	TSScanCompletionBlock	Callback when scan completes with reason and optional error

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;

TSPeripheralScanParam *scanParam = [[TSPeripheralScanParam alloc] init];
scanParam.userId = @"user123";
scanParam.deviceName = @"MyDevice";
scanParam.scanTimeout = 30;
scanParam.allowDuplicates = YES;

[bleConnect startSearchPeripheralWithParam:scanParam
                       discoverPeripheral:^(TSPeripheral *peripheral) {
    TSLog(@"Found device: %@", peripheral.systemInfo.bleName);
} completion:^(TSScanCompletionReason reason, NSError *error) {
    if (error) {
        TSLog(@"Scan error: %@", error.localizedDescription);
    } else {
        TSLog(@"Scan completed with reason: %ld", (long)reason);
    }
}];

Stop searching for Bluetooth devices

- (void)stopSearchPeripheral;

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;

[bleConnect stopSearchPeripheral];
TSLog(@"Scan stopped");

Connect to a Bluetooth device

- (void)connectWithPeripheral:(TSPeripheral *)peripheral
                        param:(TSPeripheralConnectParam *)param
                   completion:(TSBleConnectionCompletionBlock)completion;

Parameter	Type	Description
peripheral	TSPeripheral *	Peripheral device to connect to
param	TSPeripheralConnectParam *	Connection parameters with binding info including user ID
completion	TSBleConnectionCompletionBlock	Callback for connection result with state and optional error

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;
TSPeripheral *peripheral = /* discovered peripheral */;

TSPeripheralConnectParam *connectParam = [[TSPeripheralConnectParam alloc] initWithUserId:@"user123"];
connectParam.authCode = @"ABC123";
connectParam.brand = @"Apple";
connectParam.model = @"iPhone 15";
connectParam.systemVersion = @"17.0";

[bleConnect connectWithPeripheral:peripheral
                           param:connectParam
                      completion:^(TSBleConnectionState connectionState, NSError *error) {
    if (error) {
        TSLog(@"Connection failed: %@", error.localizedDescription);
        return;
    }
    
    switch (connectionState) {
        case eTSBleStateConnecting:
            TSLog(@"Connecting to device...");
            break;
        case eTSBleStateAuthenticating:
            TSLog(@"Authenticating with device...");
            break;
        case eTSBleStatePreparingData:
            TSLog(@"Preparing device data...");
            break;
        case eTSBleStateConnected:
            TSLog(@"Device connected successfully!");
            break;
        case eTSBleStateDisconnected:
            TSLog(@"Connection failed");
            break;
    }
}];

Reconnect to a previously bound device

- (void)reconnectWithPeripheral:(TSPeripheral *)peripheral
                          param:(TSPeripheralConnectParam *)param
                     completion:(TSBleConnectionCompletionBlock)completion;

Parameter	Type	Description
peripheral	TSPeripheral *	Peripheral device to reconnect to
param	TSPeripheralConnectParam *	Connection parameters with same user ID as original binding
completion	TSBleConnectionCompletionBlock	Callback for reconnection result with state and optional error

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;
TSPeripheral *peripheral = /* previously bound peripheral */;

TSPeripheralConnectParam *reconnectParam = [[TSPeripheralConnectParam alloc] initWithUserId:@"user123"];
reconnectParam.brand = @"Apple";
reconnectParam.model = @"iPhone 15";
reconnectParam.systemVersion = @"17.0";

[bleConnect reconnectWithPeripheral:peripheral
                              param:reconnectParam
                         completion:^(TSBleConnectionState connectionState, NSError *error) {
    if (error) {
        TSLog(@"Reconnection failed: %@", error.localizedDescription);
        return;
    }
    
    if (connectionState == eTSBleStateConnected) {
        TSLog(@"Device reconnected successfully!");
    }
}];

Disconnect from the currently connected device

- (void)disconnectCompletion:(TSCompletionBlock)completion;

Parameter	Type	Description
completion	TSCompletionBlock	Callback that returns disconnection result

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;

[bleConnect disconnectCompletion:^(NSError *error) {
    if (error) {
        TSLog(@"Disconnect failed: %@", error.localizedDescription);
    } else {
        TSLog(@"Device disconnected successfully");
    }
}];

Unbind the currently connected device

- (void)unbindPeripheralCompletion:(TSCompletionBlock)completion;

Parameter	Type	Description
completion	TSCompletionBlock	Callback that returns unbinding result

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;

[bleConnect unbindPeripheralCompletion:^(NSError *error) {
    if (error) {
        TSLog(@"Unbind failed: %@", error.localizedDescription);
    } else {
        TSLog(@"Device unbound successfully");
    }
}];

Check if a device is currently connected

- (BOOL)isConnected;

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;

if ([bleConnect isConnected]) {
    TSLog(@"Device is connected");
} else {
    TSLog(@"Device is not connected");
}

Get Bluetooth adapter information

- (void)getBluetoothInfo:(void(^)(TSBluetoothSystem * _Nullable bluetoothInfo, NSError * _Nullable error))completion;

Parameter	Type	Description
completion	void(^)(TSBluetoothSystem *, NSError *)	Callback returning Bluetooth system information including BLE and BT adapter details

Code Example:

id<TSBleConnectInterface> bleConnect = /* obtained from SDK */;

[bleConnect getBluetoothInfo:^(TSBluetoothSystem *bluetoothInfo, NSError *error) {
    if (error) {
        TSLog(@"Failed to get Bluetooth info: %@", error.localizedDescription);
        return;
    }
    
    if (bluetoothInfo.bleInfo) {