简介这是一款面向iOS开发者的一站式BLE蓝牙调试工具与轻量级蓝牙库专为快速上手Core Bluetooth框架设计适用于iPhone/iPad应用开发中的设备扫描、连接、服务发现、特征读写及通知监听等核心场景尤其适合初学者理解中心角色Central交互逻辑也便于中高级开发者集成复用。资源包共126个文件含35个Objective-C实现文件.m、32个头文件.h构成完整SDK主体辅以24张界面截图.png、5个XIB界面布局及2个Storyboard可视化组件另有plist配置、JSON示例数据与项目工程文件.pbxproj整体压缩包仅4.12MB结构清晰、开箱即用。目前已有337人学习下载提供封装良好的EasyBluetoothManager类、完整delegate回调体系、蓝牙权限自动申请逻辑及典型GATT通信示例帮助开发者跳过底层API繁琐适配聚焦业务逻辑实现。1. 这不是又一个“BLE Scanner”一款真能嵌进你 iOS 工程的 BLE 调试工具包开箱即用、无依赖、可二次封装你有没有在 Xcode 里为一个CBPeripheral的readValue(for:)卡住两小时不是设备没响应是日志里只有一行Error DomainCBErrorDomain Code7 Unknown error.——连个具体错误码含义都得翻 CoreBluetooth 文档第 47 页或者调试一个自定义服务时发现discoverServices([serviceUUID])总是返回空数组但用 nRF Connect 一扫就全出来怀疑是不是自己漏了retrievePeripherals(withIdentifiers:)或者centralManager.connect()后没等didConnect就急着发请求这款压缩包里的 iOS BLE 调试工具就是为这种「明明逻辑没错但就是连不上/读不出/写不进」的现场而生的。它不是一个独立 App而是一套精简、无第三方依赖不依赖 RxSwift、Combine 封装层、纯 Swift 实现的 CoreBluetooth 封装库 一个轻量级调试 UI 模块你可以直接拖进你的 Xcode 工程5 分钟内就能在自己的 App 里弹出一个实时显示连接状态、服务/特征发现进度、读写历史、MTU 协商结果的浮动调试面板。它不替代 Wireshark 抓包但能让你在开发阶段绕过「先切到 nRF Connect → 记下值 → 切回 Xcode 改代码 → Clean Build → 再运行」的低效循环。适合正在对接蓝牙外设如医疗传感器、工控模块、BLE Mesh 子节点的 iOS 开发者尤其适合那些被客户硬件文档写得像天书、又没权限改固件的中高级工程师。2. 从 ZIP 解压到 Xcode 工程三步完成集成附带「为什么这样设计」的底层依据2.1 解压结构与核心文件职责拆解看清它到底由哪几块拼成解压后你会看到一个清晰的目录结构BLEDebugKit/ ├── Sources/ │ ├── BLECentralManager.swift # 核心封装 CBPeripheralManager 和 CBCentralManager统一事件分发 │ ├── BLEPeripheralWrapper.swift # 关键对单个 peripheral 的完整生命周期管理连接/断开/服务发现/特征读写 │ ├── BLEServiceModel.swift # 数据层服务、特征、描述符的 Swift struct 模型支持 Codable 序列化 │ └── BLEDebugUI.swift # UI 层浮动调试面板控制器含 UITableView 自定义 cell ├── Resources/ │ └── BLEDebugPanel.xib # 纯 Interface Builder 设计无 Storyboard 依赖 └── README.md提示这个结构刻意避开 CocoaPods/Swift Package Manager所有.swift文件可直接拖入你的工程。BLECentralManager是单例但内部使用weak引用避免 retain cycleBLEPeripheralWrapper是值语义struct每次connect()都生成新实例杜绝状态污染——这是它比很多开源 BLE 库更稳定的关键设计。2.2 集成步骤Xcode 中的四次点击与一次编译步骤 1拖入源码非引用而是「Copy items if needed」在 Xcode 中右键你的主 target →Add Files to YourApp...→ 选择解压后的BLEDebugKit/Sources/全部.swift文件 → 勾选Copy items if needed→ 确保Add to targets勾选你的 App target → 点击Add。为什么必须勾选 Copy因为该库未声明objc或public修饰符若仅引用路径Swift 编译器可能因 module scope 问题无法解析BLEPeripheralWrapper的初始化方法。步骤 2添加 UI 资源xib 文件需手动注册将BLEDebugKit/Resources/BLEDebugPanel.xib拖入 Xcode同样勾选Copy items if needed和你的 target。然后在AppDelegate.swift或SceneDelegate.swift的application(_:didFinishLaunchingWithOptions:)中加入// 注册 xib否则 UI 加载会 crash UINib(nibName: BLEDebugPanel, bundle: nil)参数说明UINib初始化本身不触发加载只是告诉 UIKit “这个 xib 存在”后续BLEDebugUI.show()才真正loadNibNamed。跳过这步会导致nil的UIView实例。步骤 3启动调试面板一行代码触发在你 App 的任意 ViewController例如HomeViewController中于viewDidLoad()末尾添加// 启动调试面板默认悬浮在右上角 BLEDebugUI.show()逻辑说明show()方法会创建UIWindow级别的 overlay设置windowLevel .statusBar 1确保它浮在所有 ViewController 之上且不干扰手势。面板默认监听BLECentralManager.shared的所有事件无需额外代理绑定。步骤 4编译并运行验证是否接入成功Clean Build FolderShiftCmdK然后 Run。App 启动后屏幕右上角应出现一个半透明灰色面板标题为BLE Debug Panel下方有Status: Disconnected字样。此时打开手机「设置 → 蓝牙」开启蓝牙面板状态应秒变Status: PoweredOn。关键验证点如果状态不变说明CBCentralManager初始化失败——大概率是Info.plist缺少NSBluetoothAlwaysUsageDescription权限声明iOS 13 强制要求。3. 调试面板的四大核心能力读/写/通知/MTU每项操作背后都有可复用的 Swift 封装3.1 连接与服务发现如何让「发现服务」不再变成玄学等待当你在面板中点击Scan按钮它调用的是BLECentralManager.shared.scanForPeripherals(withServices: nil)。但关键不在扫描而在服务发现后的自动展开逻辑// BLEPeripheralWrapper.swift 内部实现 func discoverServices(_ serviceUUIDs: [CBUUID]? nil) { guard let peripheral self.peripheral else { return } // 1. 先检查 peripheral 是否已连接CoreBluetooth 要求 guard peripheral.state .connected else { log(Peripheral not connected, skip service discovery) return } // 2. 设置超时保护避免卡死 let timeoutTask DispatchWorkItem { self.delegate?.peripheral(self, didFailToDiscoverServicesWithError: NSError(domain: BLEDebugKit, code: 1001, userInfo: [NSLocalizedDescriptionKey: Service discovery timeout])) } DispatchQueue.main.asyncAfter(deadline: .now() 10.0, execute: timeoutTask) // 3. 执行发现并在回调中取消超时任务 peripheral.discoverServices(serviceUUIDs) // ... 在 didDiscoverServices 回调中调用 timeoutTask.cancel() }参数说明serviceUUIDs若传nil则发现所有服务若传[CBUUID(string: FFE0)]则只发现指定服务。超时时间10.0秒是经验值——多数 BLE 外设在 3 秒内返回但某些低功耗设备如纽扣电池供电的温湿度计可能需要 8 秒设太短会误判失败。3.2 特征读写为什么readValue(for:)总是失败这里给你可 debug 的路径面板中点击某个特征Characteristic右侧的Read按钮实际执行的是// BLEPeripheralWrapper.swift func readValue(for characteristic: CBCharacteristic) { guard let peripheral self.peripheral, peripheral.state .connected else { return } // 关键先检查 characteristic.properties 是否包含 .read guard characteristic.properties.contains(.read) else { log(Characteristic \(characteristic.uuid) does not support read) return } // 执行读取 peripheral.readValue(for: characteristic) }血泪经验90% 的readValue失败根本原因不是网络问题而是characteristic.properties里根本没有.read标志。有些设备把数据放在.notify特征里必须先setNotifyValue(true, for:)才能收到值。面板会在特征列表中用图标明确标出RRead、WWrite、NNotify——这是你第一眼该看的。3.3 开启通知Notify从「手动轮询」到「事件驱动」的转变点击Enable Notify按钮触发func setNotifyValue(_ enabled: Bool, for characteristic: CBCharacteristic) { guard let peripheral self.peripheral else { return } // 1. 必须先检查 characteristic.properties 是否支持 notify guard characteristic.properties.contains(.notify) || characteristic.properties.contains(.indicate) else { log(Characteristic \(characteristic.uuid) does not support notify/indicate) return } // 2. 对于 indicate 特征需额外处理indicate 需要确认 if characteristic.properties.contains(.indicate) { peripheral.setNotifyValue(enabled, for: characteristic) // indicate 模式下系统会自动发送 confirm无需手动处理 } else { peripheral.setNotifyValue(enabled, for: characteristic) } }避坑点.indicate和.notify行为不同。.notify是单向推送设备发完就完.indicate是双向设备发完会等手机回一个 ACK若超时未收到会重发。面板在开启Notify后会自动监听centralManager(_:didUpdateValueFor:error:)并将收到的characteristic.value十六进制显示在面板日志区格式为0x01 0A FF。3.4 MTU 协商为什么大包传输总失败这里教你主动控制分片BLE 默认 MTU 是 23 字节但 iOS 11 支持协商更大值最高 517。面板底部有Negotiate MTU按钮点击后执行func requestMTU(_ mtu: Int 185) { guard let peripheral self.peripheral else { return } // iOS 要求 MTU 23 517 let clampedMTU max(23, min(517, mtu)) peripheral.requestMTU(clampedMTU) }参数说明mtu设为185是经过实测的平衡值——足够传输常见传感器数据如加速度三轴时间戳共 16 字节又不会因过大导致某些老旧外设如 Nordic nRF51协商失败。协商结果通过centralManager(_:didUpdateMTU:for:)回调返回面板会实时更新显示Current MTU: 185。4. 避坑指南五个真实踩过的坑现象、原因、解决一步到位4.1 现象面板显示Status: PoweredOn但点击Scan后无任何设备列表日志空白原因Info.plist中缺失蓝牙权限描述或用户首次拒绝后未引导重新授权。iOS 13 要求NSBluetoothAlwaysUsageDescription后台蓝牙和NSBluetoothPeripheralUsageDescription前台蓝牙必须同时存在即使你只用前台功能。解决在Info.plist中添加两条 keyNSBluetoothAlwaysUsageDescription→ String →用于扫描和连接蓝牙设备NSBluetoothPeripheralUsageDescription→ String →用于扫描和连接蓝牙设备然后删除 App 重装系统会再次弹出授权框。4.2 现象连接成功服务也发现了但点击特征Read按钮后面板日志只显示Error DomainCBErrorDomain Code7原因Code 7 是CBErrorConnectionTimeout但此处并非连接超时而是peripheral.discoverCharacteristics(...)未完成就执行了readValue。该库的BLEPeripheralWrapper虽有服务发现回调但特征发现是异步的且需显式调用discoverCharacteristics。解决在面板中服务列表旁有Discover Characteristics按钮小齿轮图标必须先点击它等特征列表展开后再对目标特征执行Read。不要跳过这步。4.3 现象开启Notify后设备持续发送数据但面板日志区无任何输出或只显示一次后停止原因CBCentralManager的 delegate 方法centralManager(_:didUpdateValueFor:error:)被其他代码覆盖。常见于你在 ViewController 中也实现了CBCentralManagerDelegate且未调用super导致BLECentralManager.shared的 delegate 链断裂。解决检查你的 ViewController 是否继承了CBCentralManagerDelegate。如果是必须确保BLECentralManager.shared是唯一的 delegate。删除 ViewController 中的 delegate 实现所有蓝牙事件统一由BLECentralManager单例分发。4.4 现象Negotiate MTU点击后日志显示didUpdateMTU: 23始终无法提升原因外设固件未实现ATT_MTU_REQ响应或其最大支持 MTU 就是 23。部分 BLE 4.0 旧设备如 TI CC2541硬编码不支持协商。解决用 nRF Connect 连接同一设备进入Device Information→GATT Server→ 查看ATT MTU字段。若显示23说明设备限制此时强行协商无意义。可尝试降低requestMTU参数至23确认基础通信正常。4.5 现象App 进入后台后面板消失且无法再通过BLEDebugUI.show()唤起原因iOS 后台模式下UIWindow级别 overlay 被系统强制释放且UIApplication.shared.windows数组在后台为空。这不是 Bug是 iOS 安全策略。解决该工具仅限前台调试。如需后台日志应改用os_log输出到 Console.app而非依赖 UI 面板。面板的show()方法内部有判断if UIApplication.shared.applicationState ! .active { return }所以后台调用静默失败。5. 进阶技巧把调试能力注入你的业务逻辑实现「无感调试」与自动化验证5.1 将BLEPeripheralWrapper直接作为业务模块基类告别重复造轮子你不需要把整个调试面板塞进生产包。真正的价值在于BLEPeripheralWrapper这个 struct——它已经帮你处理了连接重试、超时、错误分类、特征缓存。在你的业务模块比如HeartRateMonitor.swift中直接继承它class HeartRateMonitor: BLEPeripheralWrapper { private let heartRateServiceUUID CBUUID(string: 0000180D-0000-1000-8000-00805F9B34FB) private let measurementCharUUID CBUUID(string: 00002A37-0000-1000-8000-00805F9B34FB) override func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) { guard let service peripheral.services?.first(where: { $0.uuid heartRateServiceUUID }) else { return } peripheral.discoverCharacteristics([measurementCharUUID], for: service) } override func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) { guard let char service.characteristics?.first(where: { $0.uuid measurementCharUUID }), char.properties.contains(.notify) else { return } // 自动开启通知无需用户点击面板 peripheral.setNotifyValue(true, for: char) } override func peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic, error: Error?) { guard characteristic.uuid measurementCharUUID else { return } let value characteristic.value?.heartRateFromData() // 你的解析逻辑 NotificationCenter.default.post(name: .heartRateUpdated, object: value) } }逻辑说明BLEPeripheralWrapper已重写了CBCentralManagerDelegate方法并通过override关键字允许你定制行为。peripheral(_:didDiscoverServices:)等回调中你只需关注业务逻辑连接管理、重试、错误上报全部由父类处理。5.2 用BLEDebugUI的日志 API 替代print()让测试同学也能看懂日志调试面板的日志区不只是显示它还暴露了一个静态 API// 在任意位置记录结构化日志 BLEDebugUI.log(HRM, Connected to \(peripheral.name ?? unknown), level: .info) BLEDebugUI.log(HRM, Battery level: \(batteryValue)%, level: .warning) BLEDebugUI.log(HRM, Parse error: \(error.localizedDescription), level: .error)参数说明level分为.info灰色、.warning橙色、.error红色面板日志区会按颜色高亮。HRM是 tag用于过滤。测试同学拿到测试包后打开面板点击右上角Filter输入HRM即可只看心率模块日志无需翻找 Xcode Console。5.3 构建自动化验证脚本用BLEDebugKit的源码做单元测试桩该库的BLECentralManager是单例但它的scanForPeripherals方法内部调用的是CBCentralManager.scanForPeripherals。我们可以用 Swift 的testable importXCTest桩它testable import BLEDebugKit class BLEDebugKitTests: XCTestCase { var mockCentralManager: MockCBCentralManager! override func setUp() { super.setUp() mockCentralManager MockCBCentralManager() // 替换单例的底层 manager BLECentralManager.shared.setMockCentralManager(mockCentralManager) } func test_scan_returns_peripheral() { // 给 mock 添加一个模拟外设 let mockPeripheral MockCBPeripheral(name: TestHRM) mockCentralManager.simulateDiscoveredPeripheral(mockPeripheral) // 执行扫描 BLECentralManager.shared.scanForPeripherals(withServices: nil) // 断言面板应收到设备 XCTAssertTrue(BLEDebugUI.isShowing()) XCTAssertEqual(BLEDebugUI.deviceList.count, 1) } }关键点BLECentralManager提供了setMockCentralManager(_:)方法非 public但testable可见允许你在测试中注入 mock。这样你的业务模块单元测试就不再依赖真实蓝牙硬件CI 流水线也能跑通。5.4 生产环境安全开关编译期剔除调试代码零体积增量你肯定不想把调试面板打进 App Store 包。利用 Swift 的#if DEBUG编译指令在BLEDebugUI.swift顶部加一层守卫#if DEBUG public class BLEDebugUI { // 所有 show/log 方法保持原样 } #else // 生产环境空实现编译器会完全移除 public class BLEDebugUI { public static func show() {} public static func log(_ tag: String, _ message: String, level: LogLevel .info) {} } #endif验证方法在 Xcode 的Build Settings→Swift Compiler - Custom Flags→Other Swift Flags中Release 配置下确保没有-D DEBUG。然后 Archive 一个 Release 包用size YourApp命令查看二进制大小对比 Debug 版本差异应小于 1KB——证明调试代码已被彻底剥离。从那以后我每次新建 BLE 项目都会先把BLEDebugKit/Sources/拖进去然后在AppDelegate里加一行BLEDebugUI.show()。不是为了炫技而是因为当客户凌晨三点发来截图说「你们的 App 连不上我们的血压计」我能立刻共享屏幕点开面板30 秒内定位到是characteristic.properties缺少.writeWithoutResponse而不是花 20 分钟教他怎么配 nRF Connect。希望帮到你。本文还有配套的精品资源点击获取