Device Log (TSPeripheralLog)

The TSPeripheralLog module provides access to diagnostic logs on the device, including listing, downloading, and deleting log files. It is typically used for remote diagnostics and troubleshooting.

Prerequisites

1. TopStepComKit SDK has been successfully initialized
2. A Bluetooth connection with the peripheral device has been established
3. The peripheral device supports the log feature

Data Models

TSFileModel

A generic file model containing basic file information.

Property	Type	Description
path	NSString *	File path (local path or remote path on the device)
size	NSUInteger	File size in bytes; 0 if unknown

Factory Methods

+ (instancetype)modelWithPath:(NSString *)path;
+ (instancetype)modelWithPath:(NSString *)path size:(NSUInteger)size;

Callback Types

Callback	Description
void (^)(NSArray<TSFileModel *> *_Nullable logFiles, NSError *_Nullable error)	Log list callback, returning the log file array or an error
TSFileTransferProgressBlock	File transfer progress callback
TSFileTransferSuccessBlock	File transfer success callback
TSFileTransferFailureBlock	File transfer failure callback
TSCompletionBlock	Generic completion callback

Interface Methods

1. Log List Query

Fetch Device Log List

Retrieves the list of all available log files from the device.

- (void)fetchPeripheralLogList:(nullable TSPeripheralLogListBlock)completion;

Parameters

Name	Type	Description
completion	TSPeripheralLogListBlock	Completion callback returning the log file list or an error

Example

id<TSPeripheralLogInterface> logInterface = [TopStepComKit sharedInstance].peripheralLog;

[logInterface fetchPeripheralLogList:^(NSArray<TSFileModel *> *_Nullable logFiles, NSError *_Nullable error) {
    if (error) {
        TSLog(@"Failed to fetch log list: %@", error.localizedDescription);
        return;
    }
    TSLog(@"Found %lu log file(s)", (unsigned long)logFiles.count);
    for (TSFileModel *file in logFiles) {
        TSLog(@"path: %@, size: %lu bytes", file.path, (unsigned long)file.size);
    }
}];

---

2. Log Download

Download All Log Files

Downloads all log files from the device to a local directory in batch, with progress reporting.

- (void)startFetchAllPeripheralLogsAtLocalFolderPath:(NSString *_Nonnull)localFolderPath
                                             progress:(nullable TSFileTransferProgressBlock)progress
                                              success:(nullable TSFileTransferSuccessBlock)success
                                              failure:(nullable TSFileTransferFailureBlock)failure;

Parameters

Name	Type	Description
localFolderPath	NSString *	Local directory where log files will be saved; it must already exist
progress	TSFileTransferProgressBlock	Transfer progress callback (may be nil)
success	TSFileTransferSuccessBlock	Callback invoked after all files are transferred successfully (may be nil)
failure	TSFileTransferFailureBlock	Failure callback (may be nil)

Example

id<TSPeripheralLogInterface> logInterface = [TopStepComKit sharedInstance].peripheralLog;

NSString *documentsPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
NSString *logsFolder = [documentsPath stringByAppendingPathComponent:@"DeviceLogs"];

// Make sure the directory exists.
[[NSFileManager defaultManager] createDirectoryAtPath:logsFolder
                          withIntermediateDirectories:YES
                                           attributes:nil
                                                error:nil];

[logInterface startFetchAllPeripheralLogsAtLocalFolderPath:logsFolder
                                                  progress:^(CGFloat progress) {
    TSLog(@"Download progress: %.1f%%", progress * 100);
} success:^(NSArray<NSString *> *localPaths) {
    TSLog(@"All logs downloaded; %lu file(s) in total", (unsigned long)localPaths.count);
} failure:^(NSError *error) {
    TSLog(@"Log download failed: %@", error.localizedDescription);
}];

---

Download a Single Log File

Downloads one specified log file to a local directory.

- (void)startFetchPeripheralLogWithFile:(TSFileModel *_Nonnull)logFile
                        localFolderPath:(NSString *_Nonnull)localFolderPath
                               progress:(nullable TSFileTransferProgressBlock)progress
                                success:(nullable TSFileTransferSuccessBlock)success
                                failure:(nullable TSFileTransferFailureBlock)failure;

Parameters

Name	Type	Description
logFile	TSFileModel *	The log file to download (obtained from the list returned by fetchPeripheralLogList:)
localFolderPath	NSString *	Local directory where the file will be saved; it must already exist
progress	TSFileTransferProgressBlock	Transfer progress callback (may be nil)
success	TSFileTransferSuccessBlock	Success callback (may be nil)
failure	TSFileTransferFailureBlock	Failure callback (may be nil)

Example

id<TSPeripheralLogInterface> logInterface = [TopStepComKit sharedInstance].peripheralLog;

// Fetch the list first, then download a specific file.
[logInterface fetchPeripheralLogList:^(NSArray<TSFileModel *> *_Nullable logFiles, NSError *_Nullable error) {
    if (!logFiles.count) { return; }

    TSFileModel *targetLog = logFiles.firstObject;
    NSString *documentsPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];

    [logInterface startFetchPeripheralLogWithFile:targetLog
                                 localFolderPath:documentsPath
                                        progress:^(CGFloat progress) {
        TSLog(@"Download progress: %.1f%%", progress * 100);
    } success:^(NSArray<NSString *> *localPaths) {
        TSLog(@"Log downloaded to: %@", localPaths.firstObject);
    } failure:^(NSError *error) {
        TSLog(@"Download failed: %@", error.localizedDescription);
    }];
}];

---

Cancel Log Download

Cancels any ongoing log download operation.

- (void)cancelLogFetch:(nullable TSCompletionBlock)completion;

Parameters

Name	Type	Description
completion	TSCompletionBlock	Completion callback for the cancel operation (may be nil)

Example

id<TSPeripheralLogInterface> logInterface = [TopStepComKit sharedInstance].peripheralLog;

[logInterface cancelLogFetch:^(NSError *_Nullable error) {
    if (!error) {
        TSLog(@"Log download cancelled");
    } else {
        TSLog(@"Cancel failed: %@", error.localizedDescription);
    }
}];

---

3. Log Deletion

Delete All Log Files

Deletes every log file stored on the device.

- (void)deleteAllPeripheralLogs:(nullable TSCompletionBlock)completion;

Parameters

Name	Type	Description
completion	TSCompletionBlock	Completion callback (may be nil)

Example

id<TSPeripheralLogInterface> logInterface = [TopStepComKit sharedInstance].peripheralLog;

[logInterface deleteAllPeripheralLogs:^(NSError *_Nullable error) {
    if (!error) {
        TSLog(@"All device logs removed");
    } else {
        TSLog(@"Delete failed: %@", error.localizedDescription);
    }
}];

---

Delete a Single Log File

Deletes one specified log file on the device.

- (void)deletePeripheralLogWithFile:(TSFileModel *_Nonnull)logFile
                         completion:(nullable TSCompletionBlock)completion;

Parameters

Name	Type	Description
logFile	TSFileModel *	The log file to delete (obtained from the list returned by fetchPeripheralLogList:)
completion	TSCompletionBlock	Completion callback (may be nil)

Example

id<TSPeripheralLogInterface> logInterface = [TopStepComKit sharedInstance].peripheralLog;

[logInterface fetchPeripheralLogList:^(NSArray<TSFileModel *> *_Nullable logFiles, NSError *_Nullable error) {
    if (!logFiles.count) { return; }

    [logInterface deletePeripheralLogWithFile:logFiles.firstObject
                                   completion:^(NSError *_Nullable deleteError) {
        if (!deleteError) {
            TSLog(@"Specified log file deleted");
        } else {
            TSLog(@"Delete failed: %@", deleteError.localizedDescription);
        }
    }];
}];

---

Notes

1. Query first, then act: Both download and delete operations require first calling fetchPeripheralLogList: and passing a TSFileModel instance from the returned list.
2. Local directory must exist: The localFolderPath passed to download APIs must already exist; otherwise the download will fail.
3. Cancellation: After calling cancelLogFetch:, any in-flight transfer is discarded (not persisted locally). Files already completed are kept.
4. Deletion is irreversible: Deletion directly clears device storage and cannot be undone. In production, download a backup first when necessary.
5. Completion callbacks: All callbacks are invoked on the main thread, so UI updates can be done directly inside them.