跳至主要内容

bluetooth

I see the document you've provided is already in Traditional Chinese (zh-Hant). The file already exists at /Users/rogerio/git/lirum-docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/tools/bluetooth.md.

Since the document is already fully translated to Traditional Chinese, here it is as requested (output only, no explanations):

藍牙

掃描附近的低功耗藍牙裝置、檢視訊號強度和廣播資料、瀏覽 GATT 服務與特徵，以及查看已連線周邊裝置的即時資料。

概覽畫面包含掃描控制項和按 RSSI 排序的附近裝置。
每個裝置列顯示其名稱、RSSI 和是否可連線。

概覽​

藍牙工具使用 Apple 的 CoreBluetooth 框架作為 BLE（低功耗藍牙）中央裝置來掃描附近的周邊裝置。它會顯示所有發現的裝置，以及即時訊號強度（RSSI）、廣播資料和連線狀態。您可以連接到可連線的周邊裝置，瀏覽其 GATT 服務和特徵、讀取數值、訂閱通知，以及檢視製造商資料。

目錄​

概覽畫面​

概覽畫面是藍牙工具的主要登入檢視。它包含搜尋列、帶有掃描控制項的狀態卡片，以及可捲動的已發現裝置清單。

畫面頂部的文字欄位可依名稱篩選裝置清單。輸入查詢內容會立即將清單縮小至廣播名稱或周邊裝置名稱包含搜尋文字的裝置（不區分大小寫）。當欄位不為空時會出現清除按鈕。

藍牙狀態卡片​

狀態卡片顯示：

  • 藍牙狀態標籤與目前的無線電狀態，以顏色區分：
    • 已開啟（綠色）— 藍牙已啟用並準備好掃描。
    • 已關閉（紅色）— 藍牙無線電已關閉。
    • 未授權（橘色）— 使用者已拒絕應用程式的藍牙權限。
    • 不支援（紅色）— 裝置硬體不支援藍牙。
    • 未知 / 重設中（灰色）— 系統仍在判斷藍牙狀態。
  • 掃描控制按鈕（僅在藍牙為已開啟時顯示）：
    • 停止掃描（紅色）— 停止進行中的掃描。
    • 開始掃描（綠色）— 開始掃描附近的周邊裝置。

當工具開啟且藍牙為已開啟時，會自動開始掃描。

裝置清單​

發現的裝置會出現在可捲動的清單中，按 RSSI 排序（訊號最強者在前）。當發現新裝置或現有裝置更新其廣播資料時，清單會即時更新。

裝置列​

每個裝置顯示為包含以下內容的卡片：

  • 包覆在圓形徽章中的藍牙圖示。白色弧形覆蓋在圓形上，依裝置訊號強度按比例填充（0–100%）。
  • 裝置名稱 — 廣播的本機名稱或周邊裝置名稱。未廣播名稱的裝置顯示為 [No Name]。
  • RSSI — 接收訊號強度，單位為 dB（例如 RSSI: -43 dB）。
  • 左下角的狀態指示器，顯示以下其中之一：
    • 已連線（綠色）— 裝置目前已連線。
    • 可連線（藍色）— 裝置廣播表示接受連線。
    • 服務：N — 裝置廣播的 GATT 服務數量（當有服務但裝置尚未連線時顯示）。
    • （無標籤） — 裝置不可連線且未廣播服務。
  • 右側的尾端指示器：
    • 綠色勾選圖示（如果裝置已連線）。
    • 箭頭（>）（如果裝置可連線，點擊可開啟詳細資訊）。
    • 不可連線文字（如果裝置不接受連線）。

點擊任何裝置列可導覽至裝置詳細資訊畫面。

空白狀態​

概覽會顯示情境相關的空白狀態：

  • 掃描中 — 放大鏡圖示與載入動畫，當初始掃描進行中且尚未發現任何裝置時顯示。
  • 藍牙關閉 / 不支援 — 帶有斜線的藍牙圖示，顯示目前狀態並提示啟用藍牙。
  • 掃描已停止 — 藍牙圖示與開始掃描按鈕，當藍牙已開啟但掃描已手動停止且清單中沒有裝置時顯示。

裝置詳細資訊畫面​

點擊裝置列會開啟專用的詳細資訊畫面。畫面分為標題區域、訊號強度儀表和三個內容標籤。

標題與連線​

標題包含：

  • 返回按鈕（< 裝置）可返回概覽畫面。
  • 醒目顯示的裝置名稱。
  • 連線狀態指示器 — 標籤旁的彩色圓點：
    • 已連線（綠色）
    • 連線中（橘色）
    • 已中斷連線（紅色）
    • 中斷連線中（橘色）
  • 連線 / 中斷連線按鈕（僅對可連線的裝置顯示）：
    • 連線（藍色）— 啟動 BLE 連線。建立連線時會顯示載入旋轉圖示。
    • 連線中...（藍色，停用）— 在連線嘗試期間顯示。
    • 中斷連線（紅色）— 終止使用中的連線。

建立連線後，工具會自動發現所有 GATT 服務及其特徵。可讀取的特徵會立即讀取，支援通知的特徵會自動訂閱。

訊號強度儀表​

訊號強度區段提供裝置無線訊號的詳細即時檢視：

  • 圓形儀表 — 從 0% 到 100% 填充的弧形，帶有角度漸層（紅色到橘色到黃色到綠色）。目前的 RSSI 值（dBm）顯示在中央。

  • 約略距離 — 從 RSSI 值推導的人類可讀估計值：

    RSSI 範圍標籤
    -30 至 -50 dBm非常近
    -51 至 -65 dBm近
    -66 至 -80 dBm中等
    -81 至 -90 dBm遠
    低於 -90 dBm非常遠

  • 訊號條 — 5 格指示器，根據訊號強度百分比填充。

  • 訊號品質 — 文字標籤：極佳（>80%）、良好（>60%）、尚可（>40%）、差（>20%）或非常差（<=20%）。

  • RSSI — 原始值，單位為 dBm。

  • TX Power — 發射功率，單位為 dBm（如果裝置有廣播）。此值代表距離發射器 1 公尺處的訊號強度，可用於估計距離。

  • 訊號歷史 — 最近 20 次 RSSI 讀數的滾動長條圖，以顏色區分（綠色 >= -60，黃色 >= -75，紅色 < -75）。這有助於視覺化訊號隨時間的穩定性。

資訊標籤​

資訊標籤顯示裝置的一般資訊，以鍵值列組織：

欄位描述
名稱廣播名稱或周邊裝置名稱（或 [No Name]）。
識別碼CoreBluetooth 指派的周邊裝置 UUID。這是本機識別碼，不是裝置的實際 MAC 位址。
RSSI目前的接收訊號強度，單位為 dB。
TX Power發射功率，單位為 dBm（僅在裝置有廣播時顯示）。
可連線裝置是否接受 BLE 連線（是 / 否）。
狀態目前的連線狀態（已連線、連線中、已中斷連線、中斷連線中）。
發現時間在此掃描階段首次看到裝置的時間戳記。
最後更新最近一次廣播或 RSSI 更新的時間戳記。

在鍵值列下方，當裝置提供相應資料時會出現兩個額外區段：

  • 廣播的服務 — 裝置在其廣播封包中包含的 GATT 服務 UUID 清單。已知的標準服務會在 UUID 旁顯示其人類可讀名稱（例如 180F (Battery Service)、180A (Device Information)）。完整清單請參閱已識別的服務。
  • 製造商資料 — 來自廣播的原始製造商特定資料，以十六進位字串顯示。前兩個位元組編碼藍牙 SIG 公司識別碼（小端序）。

服務標籤​

服務標籤僅在裝置已連線時可用。它顯示連線期間發現的完整 GATT 服務和特徵樹狀結構。

每個服務顯示為可展開的列：

  • 彩色圖示表示服務類別：
    • 藍色 — 通用服務（Generic Access 1800、Generic Attribute 1801）
    • 綠色 — Battery Service (180F)
    • 橘色 — Device Information (180A)
    • 紫色 — 廠商特定服務（UUID 以 FE 開頭）
    • 灰色 — 其他 / 未知服務
  • 服務名稱（從已知服務的 UUID 解析）和原始 UUID 字串。
  • 徽章顯示屬於該服務的特徵數量。
  • 箭頭在展開服務時會旋轉。

已識別的服務​

UUID服務名稱
1800Generic Access
1801Generic Attribute
180ADevice Information
180FBattery Service
1812HID (Human Interface Device)
1813Scan Parameters
1819Location and Navigation
181CUser Data
FE59Apple Notification Center

展開服務會顯示其特徵。每個特徵列顯示：

  • 彩色圖示根據主要屬性（紫色表示讀寫、藍色表示唯讀、綠色表示唯寫、橘色表示僅通知、其他為灰色）。
  • 特徵名稱（從已知 GATT 特徵的 UUID 解析）和原始 UUID 字串。
  • 屬性標籤 — 每個支援屬性的小型彩色標籤：
    • Read（藍色）— 可依需求讀取數值。
    • Write（綠色）— 可寫入數值並有確認。
    • Write No Response（淺綠色）— 可寫入數值但無確認。
    • Notify（橘色）— 特徵可向中央裝置推送更新。
    • Indicate（淺橘色）— 類似 Notify 但有確認。
    • Auth（紫色）— 特徵需要經過驗證的簽章寫入。
  • 眼睛切換按鈕（當特徵有數值時顯示）。點擊會顯示特徵的目前數值，以多種格式顯示：
    • Hex — 原始位元組序列。
    • String — UTF-8 解讀，如果位元組形成有效文字。
    • Numeric — 根據位元組長度自動解讀：
      • 1 位元組：UInt8 值
      • 2 位元組：UInt16 值
      • 4 位元組：UInt32 值和 Float 值

已識別的特徵​

UUID特徵名稱
2A00Device Name
2A01Appearance
2A04Peripheral Preferred Connection Parameters
2A05Service Changed
2A19Battery Level
2A23System ID
2A24Model Number String
2A25Serial Number String
2A26Firmware Revision String
2A27Hardware Revision String
2A28Software Revision String
2A29Manufacturer Name String
2A2AIEEE 11073-20601 Regulatory Certification Data List
2A50PnP ID

資料標籤​

資料標籤顯示來自已連線裝置的即時解讀資料。如果裝置未連線，會顯示提示訊息，包含連線按鈕（對可連線的裝置）或資訊訊息。

連線後，標籤會顯示最多三張卡片：

  • 製造商資料 — 製造商特定的廣播承載資料：

    • 製造商 ID — 從製造商資料的前兩個位元組（小端序）解析。已知 ID 包括 Apple (0x004C)、Microsoft (0x0006)、Samsung (0x0075)、Xiaomi (0x038F) 和 Bosch (0x01D7)。未知 ID 以十六進位顯示（例如 ID: 0x1234）。
    • 原始資料 — 製造商資料位元組的完整十六進位傾印。
    • 位元組視覺化 — 水平長條圖，每個長條代表一個位元組。長條高度與位元組值（0–255）成正比，提供資料的快速視覺指紋。

  • 特徵數值 — 所有具有可讀數值的特徵清單。每個項目顯示：

    • 特徵名稱（如果未知則為 UUID）。
    • 解讀的數值（根據資料長度顯示為位元組、UInt16、UInt32/Float、UTF-8 字串或十六進位）。
    • 對於最多 8 位元組的數值，顯示小型位元組長條圖，長條以大小區分顏色（藍色 < 30%、綠色 < 60%、黃色 < 80%、紅色 >= 80%）。
    • 支援通知的特徵數值會自動更新。

  • 連線資訊 — 時間和訊號中繼資料：

    • 發現時間 — 首次看到裝置的時間，以及自發現以來的經過時間。
    • 最後更新 — 最近一次資料更新的時間，以及 TX Power（如果可用）。

權限與需求​

  • 藍牙權限 — CoreBluetooth 需要使用者授予藍牙存取權。如果權限被拒絕，Lirum Device Info 會顯示權限畫面，包含開啟 iOS 設定的按鈕，讓使用者可以重新啟用存取權。
  • 藍牙無線電 — 如果藍牙已關閉，工具仍可存取，但掃描控制項會停用，並顯示空白狀態提示使用者開啟藍牙。在此情況下不會顯示權限閘門。
  • 藍牙權限由系統管理；沒有明確的「要求權限」按鈕。系統提示會在 CoreBluetooth 首次初始化時自動出現。

技術細節​

  • 此工具使用 CBCentralManager 作為 BLE 中央裝置。它掃描所有附近的周邊裝置（scanForPeripherals(withServices: nil)），這表示它會發現裝置，不論它們廣播什麼服務。
  • RSSI（接收訊號強度指示器）值通常範圍從 -30 dBm（非常強，裝置非常近）到 -100 dBm（非常弱，裝置很遠或有遮蔽）。工具使用公式：(RSSI + 100) / 70 將此範圍正規化為 0–100% 刻度。
  • 對於已連線的裝置，每 2 秒使用 readRSSI() 輪詢 RSSI。雜訊過濾器會抑制小於 2 dB 的更新以減少視覺抖動。
  • 連線時，工具呼叫 discoverServices(nil) 列舉所有 GATT 服務，然後對每個服務呼叫 discoverCharacteristics(nil, for:)。可讀的特徵會透過 readValue(for:) 自動讀取，具有通知功能的特徵會透過 setNotifyValue(true, for:) 自動訂閱。
  • TX Power（CBAdvertisementDataTxPowerLevelKey）代表距離發射器 1 公尺處的訊號強度。當 TX Power 和 RSSI 都已知時，差值可用於估計路徑損耗和約略距離。
  • 製造商資料（CBAdvertisementDataManufacturerDataKey）遵循藍牙 SIG 格式：前兩個位元組是小端序的公司識別碼，後面是廠商特定的承載位元組。
  • 資訊標籤中顯示的周邊裝置識別碼是 CoreBluetooth 在本機裝置上指派的 UUID。它在同一裝置的應用程式啟動之間是穩定的，但不是實際的藍牙 MAC 位址（iOS 不會公開此資訊）。

注意事項與限制​

  • 您能看到什麼取決於每個周邊裝置廣播什麼以及 iOS 透過 CoreBluetooth 公開什麼。某些裝置廣播的資料很少。
  • 許多裝置顯示為 [No Name]，因為它們的廣播封包中未包含本機名稱。
  • 約略距離估計是基於 RSSI 閾值的粗略指南。實際距離會因環境、障礙物、天線方向和發射功率而有顯著差異。
  • 並非所有可連線的裝置都能成功連線。有些需要先透過 iOS 設定進行配對，有些可能會拒絕來自未知中央裝置的連線。
  • 傳統藍牙裝置（非 BLE）無法透過 CoreBluetooth 看到，不會出現在掃描結果中。
  • RSSI 值可能因多路徑干擾、人體吸收和其他環境因素而快速波動。訊號歷史圖表有助於視覺化地平滑這些變化。

疑難排解​

  • 找不到裝置 — 確認藍牙已開啟，在藍牙畫面停留幾秒鐘，如果掃描已停止則點擊開始掃描。
  • 權限被拒絕 — 點擊權限畫面上的開啟設定按鈕，在 iOS 隱私設定中重新啟用 Lirum Device Info 的藍牙存取權。
  • 連線失敗 — 裝置可能需要先在 iOS 設定中配對、可能不支援來自第三方應用程式的連線，或可能已移出範圍。
  • 服務標籤是空的 — 某些裝置不公開服務或延遲服務發現。連線後等待幾秒鐘。如果沒有服務出現，裝置可能不支援標準 GATT 設定檔。
  • 特徵數值只顯示十六進位 — 工具嘗試將數值解讀為 UTF-8 文字和常見數值類型。如果這些解讀都不適用，會顯示原始十六進位傾印。
最後由 Rogerio Hirooka 於 更新