掌控者 PS4/PS5 × SPIKE × Pybricks

這一頁只講 Pybricks（Python）：在 SPIKE Prime／Robot Inventor 上用它讀掌控者 PS4/PS5的安裝步驟、每個值怎麼讀、能用的命令與範例。要換產品、主機或軟體，用上方的切換列。

安裝與設定

你需要

• 感應器：掌控者 PS4/PS5（SPIKE 版）。
• 主機：SPIKE Prime 或 Robot Inventor。
• 電腦：Chrome 瀏覽器，打開 code.pybricks.com 就能寫，不用安裝。
• 主機韌體：要先換成 Pybricks 韌體 v4.1（code.pybricks.com 正式版是 v4.1.1；MBC SPIKE 積木網站燒的 v4.1.0 也可以）。本站範例都照 v4.1 寫。
• 函式庫：MBC_gamepad_Lib.py（要用「匯入函式庫」的寫法才需要）。自己寫新程式只要匯入 MBC_sensors.py，一個檔適用全部 MBC 感應器。

注意

Pybricks 3.6.1 版的函式庫與範例已不再更新（2026 年新款 SPIKE Prime 也不能用 3.6.1）。還沒升級的主機，舊檔放在下載專區的「舊版（不再更新）」。

安裝軟體

1. 用 Chrome 打開 code.pybricks.com。
2. 主機換成 Pybricks 韌體：最簡單的方法是到 MBC SPIKE 積木網站 上方選單「SPIKE 主機 → 安裝／更新 Pybricks 韌體」，約 3 分鐘。
3. 之後想回到樂高官方 App，用 SPIKE App 就能換回樂高原廠韌體。

讓軟體認得感應器

Pybricks 有兩種讀法，挑一種就好：

1. 內建指令（不用函式庫）：直接用 Pybricks 內建的感應器指令讀，不用載入額外檔案，最快上手。
2. 匯入函式庫：下載 MBC_gamepad_Lib.py，拿到高解析位置、全部通道等更多資料。

匯入函式庫的步驟：

1. 在 code.pybricks.com 左邊檔案區按「Import a file（匯入檔案）」。
2. 範例檔和 MBC_gamepad_Lib.py 兩個都要匯入，放在同一個專案列表裡。
3. 點開範例，按 ▶ 執行。

重要

新專案用 MBC_sensors.py；舊專案只換掉原本那一個檔。 MBC_sensors.py 一個檔適用全部 MBC 感應器（EXP6、Servo6 擴充器的函式庫另外下載），寫法是 from MBC_sensors import MBC_LINE8，類別名稱跟舊檔名裡的一樣。舊檔名（例如本頁範例用的 MBC_gamepad_Lib.py）保留給舊程式：用新版的同名檔換掉原本那個檔就好，程式不用改。但每個舊檔名都是整份共用檔，一個程式匯入 3 個以上舊檔名，會超過 SPIKE 程式槽約 51 KB 的上限；要混用多款感應器，就只匯入 MBC_sensors.py。

提示

檔名要跟程式裡 import 的名字完全一樣，函式庫才載得進來，否則會出現 ImportError。本站下載的函式庫檔名都沒有版本字尾，不用改名。

提示

函式庫建立物件時大多有 multitask 參數：填 False 是一般模式，一行一行執行；填 True 是多工模式，每個呼叫前要加 await，可以同時做很多件事。

接線

1. 用連接線把感應器插在主機的 C 孔（A～F 任一孔都可以）。
2. 程式裡的孔要選同一個：內建指令用 Port.A～Port.F；函式庫的 port 參數多半是 1～6，對應 A～F。
3. 接頭卡榫朝上，輕輕推進去。

配對手把（第一次用或要換手把）

1. 接收器接好、主機開機。插上去的時候不要按住接收器上的按鍵（會進入燒錄模式，接收器就不會動作；放開按鍵、拔掉重插就好）。
2. 第一次使用：接收器還沒記住任何手把時，一開機就會自動開放 30 秒配對（綠燈快速閃）。要換手把、或 30 秒已經過了：按一下接收器上的按鍵（Reset），會清掉舊的手把、重新開放 30 秒。
3. 在這 30 秒內讓手把進入配對模式，直到手把的燈條快速閃爍：PS4 手把同時長按 SHARE＋PS；PS5 手把同時長按 建立（Create）＋PS。
4. 連上之後接收器會記住這支手把，也不會再連別人的手把。之後開機，只要按手把的 PS 鍵就會自動連上。

提示

比賽現場請在自己的位置完成配對，避免 30 秒內有別隊手把也在配對模式。綁錯手把就再按一次 Reset 重新配對。

函式庫與範例下載（Pybricks 4.1）

• 全部下載（.zip）：MBC_sensors.py、MBC_gamepad_Lib.py 和 6 個新手範例
• 單獨下載函式庫：MBC_sensors.py（新專案用這個，一個檔適用全部 MBC 感應器，寫 from MBC_sensors import MBC_GAMEPAD）・MBC_gamepad_Lib.py（本頁範例與舊程式用）

注意

Pybricks 3.6.1 版範例已不再更新，舊檔放在下載專區的「舊版（不再更新）」。舊範例裡按鍵算出來是小數（例：印出 1.0），拿來判斷有沒有按還是對的；要印整數就外面包 int()。Pybricks 4.x 請用 SPIKE 新手範例 或 MBC 函式庫。

全部按鍵合成一個數字：buttons() 和 buttons_psx()

函式庫有兩種「16 個鍵合成一個數字」的寫法。按鍵是同一組，只是每個鍵代表的數字不一樣：

• **新手用 buttons()／pressed()**：方向鍵、圖形鍵的數字跟官方 App「反射光」一樣，本頁範例都用這個。
• buttons_psx() 用 PS2 手把原本的按鍵順序，PS2 和 PS4 接收器送出的數字相同；Arduino（I2C）讀到的十六鍵也是這個排列，程式要跟 Arduino 共用同一套按鍵數字時用它。只有 SPIKE 版能用（讀模式 9 的第 7 個數字）。
• 沒連上手把時兩個都是 0。

from pybricks.parameters import Port
from pybricks.tools import wait
from MBC_gamepad_Lib import MBC_GAMEPAD, PSX_CROSS

pad = MBC_GAMEPAD(Port.C)
while True:
    pad.update()                 # 每圈先更新一次
    n = pad.buttons_psx()        # PSX 排列的十六鍵
    if n & PSX_CROSS:            # ✕ 有按
        print('CROSS')
    if pad.pressed_psx('L1'):    # 用名稱判斷也可以
        print('L1')
    wait(50)

重要

Pybricks 4.1 以上、不裝函式庫（內建 ColorSensor 積木）時：按鍵（reflection() 要先取整數）和 LX、LY、RX（ambient()）照常讀得到，RY 讀不到（4.1 的 ambient() 只剩 1 位小數）。要 RY 請改裝 MBC 函式庫（讀模式 9，新舊韌體都行）；新韌體的替代讀法上機確認後補上。

第一次測試

1. 主機開機，在 code.pybricks.com 連上主機。
2. 匯入並打開本頁的範例 1，按 ▶。
3. 主控台印出的數字跟著感應器前方的東西變化，就是接好了。

常見問題

• 出現 ImportError？ 函式庫沒有匯入到同一個專案，或檔名跟 import 的名字不同。把檔名改成 MBC_gamepad_Lib.py 再匯入一次。
• 範例跑不起來、指令不認得？ 主機韌體太舊：本站範例照 Pybricks v4.1 寫，先把主機更新到 v4.1。3.6.1 已不再更新，舊版檔案在下載專區。
• 感應器拔線（或線鬆了）怎麼辦？ 程式不會停下來：函式庫會回傳上一次讀到的值，並在主控台印一次提醒（中英並列：MBC: Port C 讀不到感應器，先回傳上一次的值 / no sensor, using the last value）；開機時就沒接上的話回傳 None。要在程式裡檢查，用物件的 sensor_ok()：最近一次有讀到是 True，讀不到是 False（多工模式要寫 await）。插回去後函式庫會繼續讀；如果是開機時就沒接上、又用多工模式，要重新執行程式。
• 標「只有 Pybricks 版」的範例讀到怪數字？ 那個範例用的是感應器 2026-10 以後韌體的新模式，舊韌體讀到的會是別的數字。
• 換回官方 App 後連不上？ 主機現在是 Pybricks 韌體：用 SPIKE App 換回樂高原廠韌體。

讀值

程式假設感應器插 A 孔。「MBC 函式庫」寫法要先把函式庫 .py 一起匯入 Pybricks。

十六鍵 buttons16

範圍	意思
0~65535 bit	全部按鍵一個 16 bit（PSX 排列）：bit0 SELECT(SHARE)、1 L3、2 R3、3 START(OPTIONS)、4 上、5 右、6 下、7 左、8 L2、9 R2、10 L1、11 R1、12 ▲、13 ●、14 ✕、15 ■；1 = 按下；未連線 = 0

from pybricks.iodevices import PUPDevice
from pybricks.parameters import Port

dev = PUPDevice(Port.A)   # 感應器插 A 孔

w = dev.read(9)[6]
buttons16 = w & 0xFFFF   # 十六鍵（int16 轉回 0~65535；按住 ■ 時讀到負數）

MBC 函式庫

from pybricks.parameters import Port
from MBC_gamepad_Lib import MBC_GAMEPAD

pad = MBC_GAMEPAD(Port.A)
pad.update()   # 每圈先更新一次
buttons16 = pad.buttons_psx()

模式 5 v[0] 🔒；模式 0 (edu) byte 6 🔒；模式 6 v[2]；模式 9 v[6] 🔒。備註：Pybricks reflection() 編碼：跟 PS2 同一套 11 鍵 complexXY = SELECT（SHARE）<<10 | R1<<9 | L1<<8 | ■<<7 | ✕<<6 | ●<<5 | ▲<<4 | 左<<3 | 下<<2 | 右<<1 | 上；L2、R2、L3、R3、START（OPTIONS） 讀不到（PS4 .ino:768）。2026-10-30 起（方案 A，使用者定案）：模式 5 總和 S = ceil((10×complexXY + RY)×3.072)，R = G = S/3、B = S−2R → Pybricks 4.1.x int(reflection()) = complexXY（不變）、round(reflection()×10) % 10 = RY（1~9）；3.6.1／4.0.0 的 reflection() 照舊 = complexXY; PSX 排列（#65 已改，原本是 Bluepad32 排列）; PSX 排列; PSX 排列（D3，PS2／PS4 相同；函式庫 buttons_psx()）

方向鍵 dpad

範圍	意思
0~15 bit	上 1、右 2、下 4、左 8，同時按相加（0~15）

from pybricks.iodevices import PUPDevice
from pybricks.parameters import Port

dev = PUPDevice(Port.A)   # 感應器插 A 孔

w = dev.read(9)[0]
dpad = w & 0x0F   # 方向鍵（bit 0~3）

MBC 函式庫

from pybricks.parameters import Port
from MBC_gamepad_Lib import MBC_GAMEPAD

pad = MBC_GAMEPAD(Port.A)
pad.update()   # 每圈先更新一次
dpad = pad.pressed('UP')

模式 0 (edu) byte 1 🔒；模式 0 (toy) byte 0 🔒；模式 1 byte 0；模式 6 v[0] lo；模式 7 v[0] lo 🔒；模式 9 v[0] lo 🔒。備註：低 nibble；高 nibble = 形狀鍵; 低 nibble；高 nibble = 形狀鍵; 低 nibble；高 nibble = 形狀鍵; 低 nibble；高 nibble = 形狀鍵

形狀鍵 shapeKeys

範圍	意思
0~15 bit	▲ 1、● 2、✕ 4、■ 8，同時按相加（0~15）

from pybricks.iodevices import PUPDevice
from pybricks.parameters import Port

dev = PUPDevice(Port.A)   # 感應器插 A 孔

w = dev.read(9)[0]
shapeKeys = (w >> 4) & 0x0F   # 形狀鍵（bit 4~7）

MBC 函式庫

from pybricks.parameters import Port
from MBC_gamepad_Lib import MBC_GAMEPAD

pad = MBC_GAMEPAD(Port.A)
pad.update()   # 每圈先更新一次
shapeKeys = pad.pressed('TRIANGLE')

模式 0 (edu) byte 1 🔒；模式 0 (toy) byte 0 🔒；模式 1 byte 0；模式 6 v[0] hi；模式 7 v[0] hi 🔒；模式 9 v[0] lo 🔒。備註：高 nibble; 高 nibble; 高 nibble; 高 nibble

肩鍵 shoulderKeys

範圍	意思
0~15 bit	L2 1、R2 2、L1 4、R1 8，同時按相加（0~15）

from pybricks.iodevices import PUPDevice
from pybricks.parameters import Port

dev = PUPDevice(Port.A)   # 感應器插 A 孔

w = dev.read(9)[1]
shoulderKeys = w & 0x0F   # 肩鍵（bit 0~3）

MBC 函式庫

from pybricks.parameters import Port
from MBC_gamepad_Lib import MBC_GAMEPAD

pad = MBC_GAMEPAD(Port.A)
pad.update()   # 每圈先更新一次
shoulderKeys = pad.pressed('L1')

模式 0 (edu) byte 0 🔒；模式 2 byte 0；模式 6 v[1] lo；模式 7 v[1] lo 🔒；模式 9 v[1] lo 🔒；模式 0 (toy) byte 6 🔒；模式 0 (toy) byte 1 🔒。備註：低 nibble；高 nibble = 功能鍵; 低 nibble；高 nibble = 功能鍵; 低 nibble；高 nibble = 功能鍵; 原始藍 = 肩 | 功能<<4（0~255）; 單鍵編號（L2=1 R2=2 L1=3 R1=4 SELECT（SHARE）=5 L3=6 R3=7 START（OPTIONS）=8，沒按 0；同時按只回編號最小的那個）

功能鍵 funcKeys

範圍	意思
0~15 bit	SELECT(SHARE) 1、L3 2、R3 4、START(OPTIONS) 8，同時按相加（0~15）

from pybricks.iodevices import PUPDevice
from pybricks.parameters import Port

dev = PUPDevice(Port.A)   # 感應器插 A 孔

w = dev.read(9)[1]
funcKeys = (w >> 4) & 0x0F   # 功能鍵（bit 4~7）

MBC 函式庫

from pybricks.parameters import Port
from MBC_gamepad_Lib import MBC_GAMEPAD

pad = MBC_GAMEPAD(Port.A)
pad.update()   # 每圈先更新一次
funcKeys = pad.pressed('START')

模式 0 (edu) byte 0 🔒；模式 0 (toy) byte 1 🔒；模式 2 byte 0；模式 6 v[1] hi；模式 7 v[1] hi 🔒；模式 9 v[1] lo 🔒；模式 0 (toy) byte 6 🔒。備註：高 nibble; 單鍵編號 1~8（掃 功能鍵<<4|肩鍵 的 bit0→7：1 L2 2 R2 3 L1 4 R1 5 SELECT（SHARE） 6 L3 7 R3 8 START（OPTIONS））; 高 nibble; 高 nibble; 原始藍 = 肩 | 功能<<4（0~255）

from pybricks.iodevices import PUPDevice
from pybricks.parameters import Port

dev = PUPDevice(Port.A)   # 感應器插 A 孔

connected = dev.read(3)[0]   # 已連線

from pybricks.parameters import Port
from MBC_gamepad_Lib import MBC_GAMEPAD

pad = MBC_GAMEPAD(Port.A)
pad.update()   # 每圈先更新一次
connected = pad.connected()

電量 battery

範圍	意思
0~100 %	手把電量 0~100（PS2 接收器恆 0）

from pybricks.iodevices import PUPDevice
from pybricks.parameters import Port

dev = PUPDevice(Port.A)   # 感應器插 A 孔

battery = dev.read(3)[1]   # 電量

MBC 函式庫

from pybricks.parameters import Port
from MBC_gamepad_Lib import MBC_GAMEPAD

pad = MBC_GAMEPAD(Port.A)
pad.update()   # 每圈先更新一次
battery = pad.battery()

模式 3 byte 1

搖桿 1~4 軸 stick

範圍	意思
1~9（5 = 中間）	SPIKE 讀到的是換算值 1~9（5 = 中間）。I2C 暫存器：10 LX、11 LY、12 RX、13 RY：−100 ~ +100，0 = 中間，右／上為正；未連線 0

from pybricks.iodevices import PUPDevice
from pybricks.parameters import Port

dev = PUPDevice(Port.A)   # 感應器插 A 孔

stick = list(dev.read(9)[2:6])   # [LX, LY, RX, RY]

MBC 函式庫

from pybricks.parameters import Port
from MBC_gamepad_Lib import MBC_GAMEPAD

pad = MBC_GAMEPAD(Port.A)
pad.update()   # 每圈先更新一次
stick = pad.stick('LX')

模式 0 (edu) byte 2 🔒；模式 0 (toy) byte 2 🔒；模式 4 v[0]；模式 7 v[2] 🔒；模式 9 v[2] 🔒。備註：LX×10+LY（各 1~9，5 = 中間）；byte 4~5 = RX×10+RY; 原始紅 = LX×10+LY、原始綠 = RX×10+RY（各 1~9，5 = 中間）; v0 = LX | LY<<8、v1 = RX | RY<<8（各 1~9，5 = 中間）; LX×1000+LY×100+RX×10+RY（各 1~9）；個位數 RY 在 4.1.x 的 ambient() 讀不到，4.1.x 改從模式 5 reflection() 的小數位讀（見按鍵 buttons16）; v[2..5] = LX LY RX RY，1~9，5 = 中間

這個軟體讀不到：L2 類比、R2 類比、系統鍵、手把類型。要用這些值請改用 Arduino／mBlock／micro:bit。

命令

SPIKE 接頭是唯讀的，這個軟體不能送命令：校準用感應器上的按鈕，切黑白線、門檻等設定改用 Arduino I2C、mBlock 或 micro:bit。

範例

範例 1：按鍵測試

這個範例會做什麼：主機螢幕一直顯示「按鍵的數字」。按不同的鍵，數字就不一樣，可以用來確認每一個鍵都正常。

要準備什麼

• SPIKE 主機 1 台
• 掌控者 PS4/PS5 接收器＋PS4 或 PS5 手把（已配對，見上面）

怎麼接：接收器插 C 孔。

下載程式

# 掌控者PS4 範例 1：按鍵測試（螢幕顯示按鍵數字）
# 接線：掌控者PS4 接收器 → C 埠
from pybricks.hubs import PrimeHub
from pybricks.parameters import Port
from pybricks.tools import wait
from MBC_gamepad_Lib import MBC_GAMEPAD

hub = PrimeHub()
pad = MBC_GAMEPAD(Port.C)       # 接收器插在 C 埠

while True:
    pad.update()                # 先讀一次手把
    n = pad.buttons()           # 全部按鍵合成一個數字：沒按 = 0，上 = 1、右 = 2、下 = 4、左 = 8…
    hub.display.text(str(n))    # 主機螢幕捲動顯示這個數字
    print(n)                    # 電腦畫面也印出來
    wait(100)                   # 等 0.1 秒再讀下一次

一步一步看懂程式

1. 一直重複：下面的積木會一直做，直到你按停止。
2. 讀按鍵：官方 App 用「反射光」，讀到方向鍵和圖形鍵；MBC 積木網站和 Pybricks 用「全部按鍵」，16 個鍵都讀得到。
3. 顯示在螢幕上：數字會在螢幕上捲過去（按住按鍵，等它捲完）。
4. 等 0.1 秒再讀下一次。

跑起來應該看到什麼

常見問題

• 一直是 0，按什麼都沒反應？ → 手把還沒連上：看接收器的綠燈。一直亮＝按手把 PS 鍵重新連線；快速閃＝還在等配對，照上面「配對手把」做。
• 手把一直連上又斷掉？ → 接收器記住的是別支手把：按一下接收器的按鍵（Reset），重新配對。
• 主機說找不到感應器、或數字怪怪的？ → 接收器可能是 EV3 版韌體，要用 SPIKE 版。

範例 2：搖桿數值

這個範例會做什麼：主機螢幕顯示左搖桿上下的位置（1 ～ 9）。放開是 5，往上推變大、往下拉變小。

要準備什麼：同範例 1。

怎麼接：接收器插 C 孔。

下載程式

# 掌控者PS4 範例 2：搖桿數值（螢幕顯示左搖桿上下的位置）
# 接線：掌控者PS4 接收器 → C 埠
from pybricks.hubs import PrimeHub
from pybricks.parameters import Port
from pybricks.tools import wait
from MBC_gamepad_Lib import MBC_GAMEPAD

hub = PrimeHub()
pad = MBC_GAMEPAD(Port.C)       # 接收器插在 C 埠

while True:
    pad.update()                # 先讀一次手把
    y = pad.stick('LY')         # 左搖桿上下：1（拉到最下）~ 5（中間）~ 9（推到最上）
    hub.display.number(y)       # 主機螢幕顯示這個數字
    print('LX', pad.stick('LX'), 'LY', y, 'RX', pad.stick('RX'), 'RY', pad.stick('RY'))   # 電腦畫面印出 4 個方向
    wait(100)

一步一步看懂程式

1. 讀左搖桿上下：
   • 官方 App：「原始紅色」讀到的是 X×10＋Y（例如 59＝左右在中間 5、往上推到底 9），所以用「除以 10 的餘數」把 Y 拿出來（59 → 9）。
   • MBC 積木網站：直接選「左搖桿 Y（1~9）」。
   • Pybricks：pad.stick('LY')。
2. 顯示在螢幕上。MBC 積木網站和 Pybricks 也會在電腦畫面印出數字（Pybricks 4 個方向都印）。
3. 等 0.1 秒再讀下一次。

跑起來應該看到什麼

• 放開搖桿：5。
• 慢慢往上推：6、7、8、9。
• 慢慢往下拉：4、3、2、1。

常見問題

• 一直是 5，推了也不會變？ → 手把沒連上時搖桿也是 5：看接收器的綠燈有沒有熄掉（熄掉才是連上）。
• 想看右搖桿或左右方向？ → MBC 積木網站：把下拉選單換成「右搖桿 Y」或「左搖桿 X」；官方 App：右搖桿用「原始綠色」，左右方向用「除以 10 取整數」；Pybricks：把 'LY' 換成 'RY'、'LX'、'RX'。

範例 3：按鍵控制燈和聲音

這個範例會做什麼：按 ▲ 主機燈變綠色、按 ● 變紅色、按 ✕ 變藍色、按 ■ 變粉紅色（跟 PS4 手把上符號的顏色一樣），都沒按就關燈。按 L1 嗶一聲低音、按 R1 嗶一聲高音。

要準備什麼：同範例 1。

怎麼接：接收器插 C 孔。

下載程式

# 掌控者PS4 範例 3：按鍵控制燈和聲音
# 接線：掌控者PS4 接收器 → C 埠
# ▲ 綠燈、● 紅燈、✕ 藍燈、■ 粉紅燈（跟手把上的顏色一樣），都沒按就關燈；L1 低音嗶、R1 高音嗶
from pybricks.hubs import PrimeHub
from pybricks.parameters import Color, Port
from pybricks.tools import wait
from MBC_gamepad_Lib import MBC_GAMEPAD

hub = PrimeHub()
pad = MBC_GAMEPAD(Port.C)               # 接收器插在 C 埠

while True:
    pad.update()                        # 先讀一次手把
    if pad.pressed('TRIANGLE'):         # ▲
        hub.light.on(Color.GREEN)
    elif pad.pressed('CIRCLE'):         # ●
        hub.light.on(Color.RED)
    elif pad.pressed('CROSS'):          # ✕
        hub.light.on(Color.BLUE)
    elif pad.pressed('SQUARE'):         # ■
        hub.light.on(Color.MAGENTA)
    else:                               # 4 個都沒按
        hub.light.off()

    if pad.pressed('L1'):
        hub.speaker.beep(262, 100)      # 低音 Do（262 Hz），響 0.1 秒
    if pad.pressed('R1'):
        hub.speaker.beep(523, 100)      # 高音 Do（523 Hz）
    wait(50)

一步一步看懂程式

1. 先把按鍵讀進「變數」（變數＝有名字的盒子，可以放一個數字）：官方 App 用兩個盒子，「按鍵」放反射光（方向鍵＋圖形鍵）、「肩鍵」放顏色（L1、R1…）。MBC 積木網站和 Pybricks 不用自己存，直接問「某個鍵有沒有被按下」。
2. 如果 ▲ 有按 → 綠燈。
3. 否則，如果 ● 有按 → 紅燈；否則如果 ✕ → 藍燈；否則如果 ■ → 粉紅燈。
4. 都不是 → 關燈。
5. 另外兩個「如果」：L1 有按 → 嗶低音（官方 App 音符 60、另外兩種 262 Hz，都是「Do」）；R1 有按 → 嗶高音（音符 72／523 Hz，高八度的 Do）。
6. 官方 App 判斷「▲ 有按」的寫法：(按鍵 ÷ 16) 取整數，除以 2 的餘數 = 1。● 換成 32、✕ 換成 64、■ 換成 128；L1 是 (肩鍵 ÷ 4)、R1 是 (肩鍵 ÷ 8)。

跑起來應該看到什麼

• 按住 ▲：綠燈；放開：燈熄。
• 同時按 ▲ 和 ●：綠燈（上面的「如果」先成立就不看下面的）。
• 按住 L1：一直嗶嗶嗶低音。

常見問題

• 官方 App 按 L1、R1 沒聲音？ → 肩鍵是用「顏色」積木讀的（本頁依韌體和官方範例整理，尚未逐一上機確認）。先跑範例 1 確認方向鍵、圖形鍵正常；再把範例 1 的「反射光」換成「顏色」，按 L1 應該顯示 4、R1 顯示 8。
• 燈的顏色怎麼換？ → 官方 App：點「set Power Button light to」積木上的顏色圓點；MBC 積木網站：點「主機燈號設為」的下拉選單；Pybricks：把 Color.GREEN 換成 Color.YELLOW 之類。

範例 4：方向鍵開車

這個範例會做什麼：按住方向鍵，車子就往那個方向走；放開就停。上＝前進、下＝後退、左＝原地左轉、右＝原地右轉。

要準備什麼

• 範例 1 的東西，再加上
• 兩輪小車（兩顆馬達當輪子）

怎麼接

• 接收器插 C 孔
• 左輪接 E、右輪接 F

下載程式

# 掌控者PS4 範例 4：方向鍵開車（按住才走，放開就停）
# 接線：掌控者PS4 接收器 → C 埠；左輪馬達 → E 埠；右輪馬達 → F 埠
from pybricks.parameters import Direction, Port
from pybricks.pupdevices import Motor
from pybricks.tools import wait
from MBC_gamepad_Lib import MBC_GAMEPAD

pad = MBC_GAMEPAD(Port.C)                          # 接收器插在 C 埠
left = Motor(Port.E, Direction.COUNTERCLOCKWISE)   # 左輪：反過來裝，所以設成逆時針才是往前
right = Motor(Port.F)                              # 右輪

while True:
    pad.update()                    # 先讀一次手把
    if pad.pressed('UP'):           # 上 → 前進（功率 50%）
        left.dc(50)
        right.dc(50)
    elif pad.pressed('DOWN'):       # 下 → 後退
        left.dc(-50)
        right.dc(-50)
    elif pad.pressed('LEFT'):       # 左 → 原地左轉：左輪往後、右輪往前
        left.dc(-30)
        right.dc(30)
    elif pad.pressed('RIGHT'):      # 右 → 原地右轉
        left.dc(30)
        right.dc(-30)
    else:                           # 都沒按 → 停
        left.dc(0)
        right.dc(0)
    wait(50)

一步一步看懂程式

1. 告訴主機輪子怎麼裝：左右兩顆馬達是面對面裝的，所以左輪要「反過來轉」才會往前。
   • MBC 積木網站：「E 接 樂高 馬達　馬達正轉 逆時針」（F 是順時針）；Pybricks：Direction.COUNTERCLOCKWISE。這樣設好之後，兩輪都給正的數字就是往前。
   • 官方 App 的馬達積木沒有這個設定，所以左輪 E 的數字要加負號：往前是 E -50、F 50。
2. 一直重複：讀按鍵。
3. 如果 上 有按 → 兩輪都往前（功率 50%）。
4. 否則如果 下 → 兩輪都往後。
5. 否則如果 左 → 左輪往後、右輪往前 → 原地左轉（功率 30%，轉慢一點比較好控制）。
6. 否則如果 右 → 原地右轉。
7. 都沒按 → 兩輪功率 0，停下來。

跑起來應該看到什麼：按住上，車子往前走；放開，車子停。

常見問題

• 按上卻往後退？ → 馬達的裝法跟樂高標準小車相反：MBC 積木網站把 E、F 的「正轉」方向對調；Pybricks 左輪改成 Direction.CLOCKWISE、右輪改成 Motor(Port.F, Direction.COUNTERCLOCKWISE)；官方 App 把所有數字的正負號都對調。
• 按上卻原地打轉？ → 只有一邊的方向反了：只改那一顆馬達的正負號（或正轉方向）。
• 手把沒電或走太遠斷線了？ → 接收器超過 0.3 秒收不到手把，就會把按鍵全部放開、搖桿回到中間，車子會自己停下來。

範例 5：雙搖桿坦克開車

這個範例會做什麼：像開坦克一樣：左搖桿管左輪、右搖桿管右輪。兩支都往前推＝前進、都往後拉＝後退、一前一後＝原地轉彎。推越多跑越快，放開就停。

要準備什麼：同範例 4。

怎麼接：接收器插 C 孔；左輪接 E、右輪接 F。

下載程式

# 掌控者PS4 範例 5：雙搖桿坦克開車（左搖桿管左輪、右搖桿管右輪）
# 接線：掌控者PS4 接收器 → C 埠；左輪馬達 → E 埠；右輪馬達 → F 埠
from pybricks.hubs import PrimeHub
from pybricks.parameters import Color, Direction, Port
from pybricks.pupdevices import Motor
from pybricks.tools import wait
from MBC_gamepad_Lib import MBC_GAMEPAD

hub = PrimeHub()
pad = MBC_GAMEPAD(Port.C)                          # 接收器插在 C 埠
left = Motor(Port.E, Direction.COUNTERCLOCKWISE)   # 左輪：反過來裝，所以設成逆時針才是往前
right = Motor(Port.F)                              # 右輪

# 開始前的保護：等兩支搖桿都在中間（4~6）才開始，車子才不會一開機就衝出去
while True:
    pad.update()
    if 4 <= pad.stick('LY') <= 6 and 4 <= pad.stick('RY') <= 6:
        break
    wait(20)
hub.light.on(Color.GREEN)                          # 綠燈 = 可以開了

while True:
    pad.update()                                   # 先讀一次手把
    ly = pad.stick('LY')                           # 左搖桿上下 1~9
    ry = pad.stick('RY')                           # 右搖桿上下 1~9
    # 死區：搖桿在中間附近（4~6）就當成 0，放開手車子就停
    if 4 <= ly <= 6:
        left_power = 0
    else:
        left_power = (ly - 5) * 25                 # 7 → 50%、9 → 100%、3 → -50%、1 → -100%
    if 4 <= ry <= 6:
        right_power = 0
    else:
        right_power = (ry - 5) * 25
    left.dc(left_power)
    right.dc(right_power)
    wait(20)

一步一步看懂程式

1. 開始前的保護：先「等到」兩支搖桿都在中間（4 ～ 6）才開始，然後亮綠燈。這樣一開機搖桿剛好被碰到時，車子不會突然衝出去。
2. 一直重複：讀左搖桿上下（Y）和右搖桿上下（Y）。官方 App 是「原始紅色」和「原始綠色」除以 10 的餘數。
3. 死區：搖桿在 4 ～ 6 就把功率設成 0。手放開時搖桿不一定剛好回到 5，有了死區車子才會乖乖停住。
4. 否則：功率＝**(搖桿 − 5) × 25**。推到 7 是 50%、推到底 9 是 100%；拉到 3 是 -50%、拉到底 1 是 -100%。
5. 把功率給馬達：左輪 E 用左搖桿的功率、右輪 F 用右搖桿的功率。官方 App 的左輪要 × -1（原因同範例 4）。

跑起來應該看到什麼

• 程式一開始：放開搖桿就亮綠燈，車子不動。
• 兩支搖桿一起往前推：前進，推越多越快。
• 左搖桿往前、右搖桿往後：原地右轉。
• 放開：停車。

常見問題

• 按了執行，一直沒亮綠燈？ → 搖桿沒在中間：兩支搖桿都放開，就會亮綠燈開始。
• 推一點點車子不會動？ → 這是死區，推到 7 以上（或拉到 3 以下）才會動。想要更靈敏，可以把「4 ～ 6」改成「5 ～ 5」，但放開時車子可能會慢慢滑。
• 太快不好控制？ → 把「× 25」改成「× 15」（推到底變 60%）。
• 前後顛倒或原地打轉？ → 同範例 4 的常見問題。

範例 6（進階）：連線狀態與電量

注意

這個範例只有 Pybricks 版。 它用的「連線狀態」和「電量」放在接收器的模式 3，樂高官方 App 和 MBC 積木網站讀不到。接收器韌體要是 2026-10 以後的版本，舊韌體讀到的會是別的數字。 程式碼就是範例，不需要截圖。

這個範例會做什麼：程式一開始亮紅燈，等到手把連上才亮綠燈、嗶一聲，並印出接收器種類和韌體版本；之後螢幕一直顯示手把電量（0～100，例如 80），手把關機或走太遠斷線就變回紅燈、螢幕顯示「--」。

要準備什麼：同範例 1（主機＋接收器＋已配對的 PS4 或 PS5 手把）。

怎麼接：接收器插 C 孔。

下載程式

# 掌控者PS4 範例 6：連線狀態與電量（等手把連上才開始，螢幕顯示電量）
# 接線：掌控者PS4 接收器 → C 埠
# 只有 Pybricks 版：連線狀態和電量放在接收器的「模式 3」，官方 App 和積木網站讀不到；接收器韌體要 2026-10 以後
from pybricks.hubs import PrimeHub
from pybricks.parameters import Color, Port
from pybricks.tools import wait
from MBC_gamepad_Lib import MBC_GAMEPAD

hub = PrimeHub()
pad = MBC_GAMEPAD(Port.C)                    # 接收器插在 C 埠

hub.light.on(Color.RED)                      # 紅燈 = 手把還沒連上
while not pad.connected():                   # 等到手把連上（True）才往下
    wait(200)
hub.light.on(Color.GREEN)                    # 綠燈 = 連上了
hub.speaker.beep()
print('接收器種類', pad.kind(), ' 韌體', pad.firmware_version())   # 例如 PS4 (1, 0)

while True:
    if pad.connected():
        battery = pad.battery()              # 手把電量 0~100
        hub.display.number(min(battery, 99)) # 螢幕最多只能顯示兩位數
        hub.light.on(Color.GREEN)
        print('已連線  電量', battery, '%')
    else:                                    # 手把關機或離太遠 → 斷線
        hub.display.text('--')
        hub.light.on(Color.RED)
        print('斷線了')
    wait(500)

一步一步看懂程式

1. pad.connected()：手把有沒有連上接收器（True／False）。開頭用「等到連上」取代範例 5 的「等搖桿在中間」，更可靠。
2. pad.kind()、pad.firmware_version()：接收器是 PS2 還是 PS4 款、韌體幾版（讀感應器的模式 8）。
3. 一直重複：連著就顯示 pad.battery()、綠燈；斷線就紅燈、「--」。螢幕最多顯示兩位數，所以 100 會顯示 99。
4. 這個範例沒有呼叫 pad.update()，因為沒有要讀按鍵。要讀按鍵的程式請照範例 1～5 的寫法，connected()、battery() 放在迴圈外或偶爾呼叫（每次呼叫接收器要切換模式，多花幾十 ms）。

跑起來應該看到什麼：手把還沒連：紅燈。按手把 PS 鍵連上的瞬間：綠燈＋嗶，螢幕顯示電量（例如 80）。把手把關掉：紅燈、「--」。

常見問題

• 電量數字不會變？ → 手把每隔一段時間才回報一次電量，充電中也不一定馬上更新，是正常的。
• 一直紅燈？ → 手把沒配對（看上面「配對手把」）、或接收器韌體太舊（2026-10 以前）沒有連線狀態，請更新韌體。
• 可以跟範例 5 合併嗎？ → 可以：把範例 5 開頭的「等搖桿在中間」換成「等到 pad.connected()」，也可以在電量低於 20 時亮橘燈提醒。

其他問題

• 主機認不到感應器？ 拔掉重插一次，等 2 秒；換一個孔試試。官方 App 會把它顯示成「顏色感應器」，這是正常的。
• 可以同時用官方 App 和 Pybricks 嗎？ 一次只能裝一種韌體：Pybricks 與 MBC 積木網站用 Pybricks 韌體，官方 App 用樂高原廠韌體；隨時可以用 SPIKE App 換回原廠韌體。

還有問題？到 聯絡我們 附上你用的軟體和程式截圖。

下載

• Pybricks 函式庫 MBC_gamepad_Lib.py
• 共用函式庫（新專案用，一個檔適用全部 MBC 感應器） MBC_sensors.py
• ps4_pybricks_spike_v4.x.zip
• 下載中心（全部產品的函式庫、韌體、型錄）

本頁依據

• 主機與軟體清單：_build/guides.json
• 值與命令：_build/protocol/ps4.json（單一真相來源）
• 安裝與設定：_build/guides/software/spike-pybricks.zh.md、_build/guides/product/ps4/spike-pybricks.zh.md
• 範例：sensors/ps4/spike-examples.md