设备日志（TSPeripheralLog）

TSPeripheralLog 模块提供从设备获取、下载和管理诊断日志的功能。通过该模块，您可以获取设备上的日志文件列表、将日志下载到本地、删除设备上的日志，适用于远程诊断和问题排查场景。

前提条件

1. 已成功初始化 TopStepComKit SDK
2. 已建立与外围设备的蓝牙连接
3. 外围设备支持日志功能

数据模型

TSFileModel

通用文件模型，包含文件的基本信息。

属性名	类型	说明
path	NSString *	文件路径（本地路径或设备端远程路径）
size	NSUInteger	文件大小（字节），未知时为 0

工厂方法

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

回调类型

回调类型	说明
void (^)(NSArray<TSFileModel *> *_Nullable logFiles, NSError *_Nullable error)	日志列表获取回调，返回日志文件数组或错误
TSFileTransferProgressBlock	文件传输进度回调
TSFileTransferSuccessBlock	文件传输成功回调
TSFileTransferFailureBlock	文件传输失败回调
TSCompletionBlock	通用完成回调

接口方法

1. 日志列表查询

获取设备日志列表

从设备获取所有可用日志文件的列表。

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

参数

参数名	类型	说明
completion	TSPeripheralLogListBlock	获取完成回调，返回日志文件列表或错误

代码示例

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

[logInterface fetchPeripheralLogList:^(NSArray<TSFileModel *> *_Nullable logFiles, NSError *_Nullable error) {
    if (error) {
        TSLog(@"获取日志列表失败: %@", error.localizedDescription);
        return;
    }
    TSLog(@"共发现 %lu 个日志文件", (unsigned long)logFiles.count);
    for (TSFileModel *file in logFiles) {
        TSLog(@"日志路径: %@，大小: %lu 字节", file.path, (unsigned long)file.size);
    }
}];

---

2. 日志下载

下载所有日志文件

将设备上的所有日志文件批量下载到本地指定目录，支持进度监控。

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

参数

参数名	类型	说明
localFolderPath	NSString *	日志文件保存的本地目录路径，目录须已存在
progress	TSFileTransferProgressBlock	传输进度回调，可为 nil
success	TSFileTransferSuccessBlock	全部传输成功回调，可为 nil
failure	TSFileTransferFailureBlock	传输失败回调，可为 nil

代码示例

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

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

// 确保目录存在
[[NSFileManager defaultManager] createDirectoryAtPath:logsFolder
                          withIntermediateDirectories:YES
                                           attributes:nil
                                                error:nil];

[logInterface startFetchAllPeripheralLogsAtLocalFolderPath:logsFolder
                                                  progress:^(CGFloat progress) {
    TSLog(@"下载进度: %.1f%%", progress * 100);
} success:^(NSArray<NSString *> *localPaths) {
    TSLog(@"所有日志下载完成，共 %lu 个文件", (unsigned long)localPaths.count);
} failure:^(NSError *error) {
    TSLog(@"日志下载失败: %@", error.localizedDescription);
}];

---

下载单个日志文件

下载指定的单个日志文件到本地目录。

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

参数

参数名	类型	说明
logFile	TSFileModel *	需要下载的日志文件模型（来自 fetchPeripheralLogList: 返回的列表）
localFolderPath	NSString *	日志文件保存的本地目录路径，目录须已存在
progress	TSFileTransferProgressBlock	传输进度回调，可为 nil
success	TSFileTransferSuccessBlock	传输成功回调，可为 nil
failure	TSFileTransferFailureBlock	传输失败回调，可为 nil

代码示例

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

// 先获取日志列表，再下载指定文件
[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(@"下载进度: %.1f%%", progress * 100);
    } success:^(NSArray<NSString *> *localPaths) {
        TSLog(@"日志已下载到: %@", localPaths.firstObject);
    } failure:^(NSError *error) {
        TSLog(@"下载失败: %@", error.localizedDescription);
    }];
}];

---

取消日志下载

取消当前正在进行的日志下载操作。

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

参数

参数名	类型	说明
completion	TSCompletionBlock	取消操作完成回调，可为 nil

代码示例

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

[logInterface cancelLogFetch:^(NSError *_Nullable error) {
    if (!error) {
        TSLog(@"日志下载已取消");
    } else {
        TSLog(@"取消失败: %@", error.localizedDescription);
    }
}];

---

3. 日志删除

删除所有日志文件

删除设备上存储的全部日志文件。

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

参数

参数名	类型	说明
completion	TSCompletionBlock	删除操作完成回调，可为 nil

代码示例

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

[logInterface deleteAllPeripheralLogs:^(NSError *_Nullable error) {
    if (!error) {
        TSLog(@"设备日志已全部清除");
    } else {
        TSLog(@"删除失败: %@", error.localizedDescription);
    }
}];

---

删除单个日志文件

删除设备上指定的日志文件。

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

参数

参数名	类型	说明
logFile	TSFileModel *	需要删除的日志文件模型（来自 fetchPeripheralLogList: 返回的列表）
completion	TSCompletionBlock	删除操作完成回调，可为 nil

代码示例

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(@"指定日志文件已删除");
        } else {
            TSLog(@"删除失败: %@", deleteError.localizedDescription);
        }
    }];
}];

---

注意事项

1. 先查询后操作：下载和删除操作均需要先调用 fetchPeripheralLogList: 获取文件列表，再传入 TSFileModel 进行操作
2. 本地目录须存在：调用下载接口时，localFolderPath 对应的目录必须已经创建，否则下载会失败
3. 取消操作：调用 cancelLogFetch: 后正在传输的数据不会保存到本地，已完成的文件不受影响
4. 删除不可撤销：删除操作直接清除设备存储，无法恢复，生产环境中建议先下载备份再删除
5. 完成回调：所有操作的回调均在主线程执行，可直接更新 UI