pyBricks for SPIKE Prime / Robot Inventor
+
+
警告
請注意：您目前觀看的是 【pyBricks 專區 (雙主機通用)】 的 MicroPython 高階開發教學。 如果您使用的是 EV3 或是其他官方系統軟體，請點擊上方按鈕回到主機選單重新選擇。
本頁適用於 LEGO® Education SPIKE™ Prime Set、LEGO® MINDSTORMS® Robot Inventor上安裝 pyBricks 第三方 MicroPython 韌體的使用者。
在 Pybricks 開發環境中，使用者可以利用 Python 指令進行高速、穩定的通訊。本感應器支援以內建的圖形指令進行簡易讀取，或導入我們的專屬庫函數獲得高解析度資料與更豐富的控制功能。
讀取方式與核心模式
在 Pybricks 開發環境中，本循線感應器提供兩種靈活的資料讀取管道，適應不同的專案需求：
- **內建感應器指令 (當作顏色感應器讀取)**：直接使用 Pybricks 內建 the
ColorSensor指令讀取基本的光電或特徵數據，無需載入額外代碼，操作最直覺。 - **導入專屬庫函數 (Library Functions)**：透過導入我們為 16路循線感應器特別編寫的 Python 庫函數，能直接獲得高解析度插值位置、完整 16 路反射光數值以及特徵線寬，提供更豐富的高階循線控制。
範例程式與庫下載 (打包下載)
注意
Pybricks 3.6.1 已不再更新，請改用 Pybricks 4.1（4.x 版 zip 另附
MBC_sensors.py，一個檔適用全部 MBC 感應器）。
我們為您提供了四個核心範例程式以及專屬庫函數。請依照您的開發模式選擇下載：
方式一：內建感應器指令
直接使用 Pybricks 內建指令讀取感應器，無需載入額外代碼，快速上手。
可用函數一覽
— 透過 Pybricks 內建ColorSensor 計算得出，無需額外載入庫檔案
getLinePos16()
-16 ~ +16
取得循線位置（整數解析度）。0 為正中央，負數偏左，正數偏右。適合基本 PID 循線控制。
getLineWidth16()
0 ~ 16
取得目前偵測到的特徵線寬（觸發的感測器數量）。可用於偵測十字路口、T 字路口等寬線特徵。
getLinePos100()
-100 ~ +100
取得高解析度次像素級插值位置。精度遠高於 getLinePos16()，適合高階 PID 精密循線。
getLineWidth100()
0 ~ 16
取得高精度模式下的特徵線寬。與 getLinePos100() 搭配使用，確保數據同步一致。
getLinePos16() 就搭配 getLineWidth16()，使用 getLinePos100() 就搭配 getLineWidth100()，這樣才能獲得最即時、最準確的讀取效果。
方式二：導入專屬庫函數
透過導入我們的專屬 Python 庫函數，獲得高解析度插值位置、完整 16 路數據與線寬等進階功能。
可用函數一覽
— 由MBC_line16_Lib.py 提供
line_init_port_multitask(port, multitask)
初始化感應器連接埠。port=1~6 對應 A~F；multitask=True 時啟用非同步模式（搭配 await 使用）。
line_pos16()
🎯 不挑校準品質
取得整數解析度的循線位置。0 為正中央，負數偏左，正數偏右。比較不挑校準品質，適合快速開發與初學者；但還是要先校準一次（沒校準時每一路都會被當成黑色）。
line_pos100()
🔬 需精確校準
取得高解析度次像素級插值位置，最佳 PID 循線選擇。使用前提是必須確實完成感應器校準，校準越精確數值越準確。
line_width()
0 ~ 16
取得特徵線寬（觸發的感測器數量）。可用於偵測路口與寬線特徵，同時適用於上述兩種位置函數。
line_ir_calibration()
list[16]
回傳 16 路校正後紅外線反射光值陣列（每值 0~15）。index 0 = 最左側 (ch1)，index 15 = 最右側 (ch16)。
line_ir_ch(ch)
0 ~ 15
取得單一通道的校正光值。ch=1~16，可高效連續呼叫（共用快取）。
line_junction()
0, 1, 2+
回傳偵測到的線群數量。0=無線、1=單線、2+=路口分叉。
line_junction_name()
str
回傳路口狀態的文字描述："none"、"line"、"junction"。
line_bin_raw()
0 ~ 65535
取得 16 位元二進位原始觸發遮罩。每個 bit 對應一路感測器 (bit0=ch1)，1=偵測到線。
line_on_sensors()
list[int]
回傳目前偵測到線的通道編號列表（1~16），例如 [7, 8, 9]。
line_read_all()
dict
一次讀取所有數據，回傳包含所有欄位的字典：ir_calibration、line_pos16、line_pos100、line_width、bin_raw、on_sensors、junction、junction_name。
16路循線感應器專屬 Pybricks 庫函數 (Library File)
這是配合「導入專屬庫」範例不可或缺的驅動核心。請下載此庫檔案，即可完美啟用高階插值位置與 16 路光電數值精細讀取。
重要提示：檔案放置位置
您必須將下載的庫檔案（依韌體版本而定，例如 MBC_line16_Lib_v361.py 或 MBC_line16_obj_Lib.py）與您的主程式放在同一個專案列表下。請參考下方截圖確認，否則程式執行時將會報錯找不到庫檔案！
⚠️ 檔名一定要改：範例程式寫的是 import MBC_line16_obj_Lib（3.6.1 版是 MBC_line16_Lib），所以下載後請把檔名改成 MBC_line16_obj_Lib.py（4.x 版下載的檔名已經是這個）或 MBC_line16_Lib.py（去掉 _v361），否則會出現 ImportError。最省事的做法是直接用上方的「打包下載」zip，裡面的檔名已經是對的。
提示
想要學更厲害的循線控制方法嗎？ 可以找這幾位厲害的教練上課唷！他們有非常豐富的比賽與教學經驗，保證讓你收穫滿滿～ 💯
