TSBattery (Device Battery)

The TSBattery module provides interfaces for retrieving and monitoring device battery information, including overall battery status, per-part battery status for multi-battery devices (earbuds, split-battery glasses, headsets, etc.), and real-time battery change notifications.

Prerequisites

1. The device must be successfully connected via Bluetooth before invoking any battery APIs.
2. The SDK must be properly initialized.
3. Implement the TSBatteryInterface protocol via the SDK's interface provider.

Data Models

TSBatteryModel

Battery information model containing charging state, percentage, and the physical part identifier.

Property	Type	Description
chargeState	TSBatteryState	Current charging state of the device
percentage	UInt8	Battery percentage, range 0-100
part	TSBatteryPart	Physical part this battery belongs to (defaults to TSBatteryPartMain for single-battery devices)

Instance Methods

Method	Return Type	Description
partName	NSString *	Human-readable English name of the part (e.g. "Main", "Left")
initWithPercentage:chargeState:	instancetype	Convenience initializer for single-battery devices
initWithPart:percentage:chargeState:	instancetype	Designated initializer for multi-battery devices

Enumerations

TSBatteryState

Battery charging state.

Value	Raw	Description
TSBatteryStateUnknown	1	Charging state unknown
TSBatteryStateCharging	2	Connected to power and charging
TSBatteryStateUnConnectNoCharging	3	Not connected to power
TSBatteryStateConnectNotCharging	4	Connected to power but not charging
TSBatteryStateFull	5	Battery is fully charged

TSBatteryPart

Identifies which physical part a battery belongs to.

Value	Raw	Description
TSBatteryPartUnknown	0	Unknown part
TSBatteryPartMain	1	Main battery (watches, single-battery glasses)
TSBatteryPartLeft	2	Left part (e.g. left earbud, left temple)
TSBatteryPartRight	3	Right part (e.g. right earbud, right temple)
TSBatteryPartCase	4	Charging case
TSBatteryPartMic	5	Microphone
TSBatteryPartMainSpeaker	6	Main speaker
TSBatteryPartSideSpeaker	7	Side speaker
TSBatteryPartOther	8	Other parts

Callback Types

Callback	Signature	Description
TSBatteryBlock	void (^)(TSBatteryModel * _Nullable batteryModel, NSError * _Nullable error)	Single battery operation/change callback
TSBatteriesBlock	void (^)(NSArray<TSBatteryModel *> * _Nullable batteryModels, NSError * _Nullable error)	Multi-battery operation callback

API Reference

Get overall battery information

- (void)getBatteryInfoCompletion:(nullable TSBatteryBlock)completion;

Parameter	Type	Description
completion	TSBatteryBlock	Callback returning the overall battery model. For multi-battery devices, returns the lowest-percentage part.

Example

id<TSBatteryInterface> battery = [TopStepComKit shared].batteryInterface;
[battery getBatteryInfoCompletion:^(TSBatteryModel * _Nullable batteryModel, NSError * _Nullable error) {
    if (error) {
        TSLog(@"Get battery failed: %@", error);
        return;
    }
    TSLog(@"Battery: %d%% state=%d", batteryModel.percentage, (int)batteryModel.chargeState);
}];

Get battery information for all parts

- (void)getAllBatteriesInfoCompletion:(nullable TSBatteriesBlock)completion;

Parameter	Type	Description
completion	TSBatteriesBlock	Callback returning an array with one TSBatteryModel per physical part. Single-battery devices return a single-element array.

Example

id<TSBatteryInterface> battery = [TopStepComKit shared].batteryInterface;
[battery getAllBatteriesInfoCompletion:^(NSArray<TSBatteryModel *> * _Nullable models, NSError * _Nullable error) {
    if (error) {
        TSLog(@"Get all batteries failed: %@", error);
        return;
    }
    for (TSBatteryModel *m in models) {
        TSLog(@"%@: %d%%", [m partName], m.percentage);
    }
}];

Register battery change listener

- (void)registerBatteryDidChanged:(nullable TSBatteryBlock)completion;

Parameter	Type	Description
completion	TSBatteryBlock	Triggered whenever battery information changes. For multi-battery devices, called once per changed part; inspect batteryModel.part to identify it.

Example

id<TSBatteryInterface> battery = [TopStepComKit shared].batteryInterface;
[battery registerBatteryDidChanged:^(TSBatteryModel * _Nullable batteryModel, NSError * _Nullable error) {
    if (error) {
        TSLog(@"Battery listener error: %@", error);
        return;
    }
    TSLog(@"[%@] changed -> %d%% state=%d",
          [batteryModel partName], batteryModel.percentage, (int)batteryModel.chargeState);
}];

Important Notes

1. Always verify the device is connected before calling any battery API; otherwise the callback will return an error.
2. getBatteryInfoCompletion: returns a single overall value; for multi-battery devices it represents the lowest-percentage part — use getAllBatteriesInfoCompletion: to enumerate all parts.
3. For single-battery devices, getAllBatteriesInfoCompletion: returns a single-element array with part == TSBatteryPartMain, allowing unified iteration.
4. In the change listener, multi-battery devices invoke the callback per changed part; route updates by inspecting batteryModel.part.
5. The partName string is intended for logs/debug only; localize end-user display based on the part enum value.
6. TSBatteryModel cannot be created with init/new/copy; use initWithPercentage:chargeState: or initWithPart:percentage:chargeState:.
7. Battery percentage is always in the range 0–100.