pyBricks for EV3

警告
請注意：您目前觀看的是【EV3 pyBricks】環境的教學。 如果您使用的是 SPIKE 或是其他 EV3 軟體，請點擊上方按鈕回到主機選單重新選擇。

適用於在 LEGO® MINDSTORMS® EV3 主機上安裝 pyBricks 第三方韌體的使用者。在高階的 Pybricks MicroPython 環境下，玩家可以完全繞過官方的通訊與模式限制，以最精簡、高效的方式與 16 路循線感應器進行高速通訊！

注意
韌體版本 code.pybricks.com 正式版已內建 EV3 韌體（2026-10 是 v4.1.1）。本頁範例最早在 v4.0.0b10 上機測過，v4.1.1 寫法相同。

重要
模式切換等待延遲警告 由於 EV3 硬體底層的通訊機制限制，當程式在不同底層讀取模式之間進行切換時，仍然會產生通訊等待延遲。 強烈建議：為了確保程式穩定性與高速反應，請根據任務需求選定一種模式使用，不要在主迴圈中頻繁交叉呼叫不同模式的函數（下方函數已為您標註所屬模式群組）。

讀取方式與核心模式

在 EV3 Pybricks 環境中，本循線感應器提供兩種靈活的資料讀取管道，適應不同的專案需求：

**原生指令讀取 (device.mode)**：直接切換感應器的底層 UART 模式來獲取陣列數據，操作最為直接。
**導入專屬庫函數 (Library Functions)**：透過導入我們封裝好的 Python 函數，能獲得如同積木般直覺的獨立變數回傳，大幅簡化程式碼邏輯。

範例程式與函數下載 (打包下載)

我們為您提供了核心範例程式以及專屬庫函數。請依照您的開發習慣選擇：

⚡

方式一：原生指令讀取

使用 Pybricks 底層的 hub.port.X.device.mode(mode) 直接獲取陣列數據。

device.mode(0) Tuple (1 Byte)

新手模式：回傳標準位置平移值 [-16, 16]，0 為中央。

device.mode(1) Tuple (8 Bytes)

全覽除錯模式：回傳 16 路壓縮光值。相鄰兩路壓縮為一個兩位數（11~99）。

device.mode(2) Tuple (4 Bytes)

競技戰術專武：回傳高精度位置 [-100, 100]、線寬 [0, 16]、左邊界實體光值與右邊界實體光值。

⏳

等待 pyBricks 官方指令更新

由於官方尚未將對應的圖形與底層指令製作更新，本區塊原生範例程式將於日後補齊。
目前強烈建議您直接使用下方的「方式二：導入專屬庫函數」進行高階開發！

🔬

方式二：導入專屬庫函數

透過導入封裝好的 Python 副程式，能獲得獨立變數回傳，大幅降低程式碼複雜度。

可用函數一覽

— 由 MBC_line16_EV3_Lib.py 提供

⚙️ 初始化

line_init_port_multitask(port, multitask)

初始化感應器連接埠。port 傳入 EV3 埠物件（例如 hub.port.S1）。
👉 非多工模式：第二參數 multitask 請填入 False，呼叫函數時前方條件請選擇 call。
👉 多工模式：第二參數 multitask 請填入 True，呼叫函數時前方條件請選擇 await。

非多工狀態設定 (常規使用)

多工狀態設定 (非同步 / await)

🟢 模式 0 (新手/基礎循線)

[模式 0: 基礎]line_pos16() -16 ~ +16

取得整數解析度的循線位置。0 為正中央，負數偏左，正數偏右。

🟡 模式 1 (全覽/除錯/自訂算法)

[模式 1: 解碼]line_ir_ch(ch) 1 ~ 9

取得單一感應器通道的即時量化光值。ch=1~16。1=最暗，9=最亮。

🔵 模式 2 (競技/PID 循線專用)

[模式 2: 競技]line_pos100() -100 ~ +100

高解析度次像素級插值位置，專為高階 PID / PD 控制設計。

[模式 2: 競技]line_width() 0 ~ 16

取得特徵線寬（觸發的感測器數量）。可用於偵測路口與寬線。

[模式 2: 競技]line_edge_l() 0 ~ 100

取得左邊界感測器的實體光值（0=黑, 100=白），用於防掉線。

[模式 2: 競技]line_edge_r() 0 ~ 100

取得右邊界感測器的實體光值（0=黑, 100=白），用於防掉線。

重要
模式切換等待延遲警告 由於 EV3 硬體底層的通訊機制限制，當程式在不同底層讀取模式之間進行切換時，仍然會產生通訊等待延遲。 強烈建議：為了確保程式穩定性與高速反應，請根據任務需求選定一種模式使用，不要在主迴圈中頻繁交叉呼叫不同模式的函數（上方函數已為您標註所屬模式群組）。

實戰建議：強烈建議一般使用者與競賽選手全程使用 [模式 2: 競技] 的函數群；
只有當您需要讀取所有感測器原始數值，進行「自訂特殊演算法」開發時，才建議單獨使用 [模式 1: 解碼]。