291. 控制器捕获与串行读取

捕获控制器按钮并串行读取。

第 291 / 356 · tests/chapter_07_controller_input/test_291_controller_capture_and_serial_read.py

本步骤中创建的文件

emulator/input/controller.py

为什么需要这一步

NES CPU 不会从 $4016 一次性获取完整的控制器状态字节。它每次只接收一个按钮位。在将该协议接入 CpuBus 之前，纯 Controller 对象应当能够：

参考资料

https://www.nesdev.org/wiki/Standard_controller
https://www.nesdev.org/wiki/Controller_reading_code

1. capture the current button booleans into a stable snapshot
2. expose the captured bits in NES serial order
3. handle strobe high vs strobe low behavior

关键术语：选通信号选通信号（strobe）是由 CPU 写入的控制信号。对于 NES 控制器，选通信号控制控制器是继续捕获实时按钮状态，还是逐步读取已捕获的串行位。

最小示例

controller.a = True
controller.write_strobe(1)
controller.write_strobe(0)
controller.read_bit()  # returns A bit

常见误解

"The controller should return all buttons as one byte."

模拟器内部可能将捕获的按钮状态存储为一个字节，但面向 CPU 的协议每次只读取一位。

建议的实现示例

def capture_buttons(self) -> None:
    value = 0

    if self.a:
        value |= BUTTON_A
    if self.b:
        value |= BUTTON_B
    if self.select:
        value |= BUTTON_SELECT
    if self.start:
        value |= BUTTON_START
    if self.up:
        value |= BUTTON_UP
    if self.down:
        value |= BUTTON_DOWN
    if self.left:
        value |= BUTTON_LEFT
    if self.right:
        value |= BUTTON_RIGHT

    self.captured_buttons = value
    self.read_index = 0


def write_strobe(self, value: int) -> None:
    self.strobe = (value & 1) == 1

    if self.strobe:
        self.capture_buttons()


def read_bit(self) -> int:
    if self.strobe:
        self.capture_buttons()

    if self.read_index >= 8:
        return 1

    bit = (self.captured_buttons >> self.read_index) & 1
    self.read_index += 1
    return bit

超出本步骤范围

CpuBus $4016 路由
pygame 键盘映射
控制器端口 2
Famicom 扩展控制器
DMC/控制器读取毛刺行为

运行本课

uv run pytest tests/chapter_07_controller_input/test_291_controller_capture_and_serial_read.py -v

示例实现

最小示例

controller.a = True
controller.write_strobe(1)
controller.write_strobe(0)
controller.read_bit()  # returns A bit

建议的实现示例

def capture_buttons(self) -> None:
    value = 0

    if self.a:
        value |= BUTTON_A
    if self.b:
        value |= BUTTON_B
    if self.select:
        value |= BUTTON_SELECT
    if self.start:
        value |= BUTTON_START
    if self.up:
        value |= BUTTON_UP
    if self.down:
        value |= BUTTON_DOWN
    if self.left:
        value |= BUTTON_LEFT
    if self.right:
        value |= BUTTON_RIGHT

    self.captured_buttons = value
    self.read_index = 0


def write_strobe(self, value: int) -> None:
    self.strobe = (value & 1) == 1

    if self.strobe:
        self.capture_buttons()


def read_bit(self) -> int:
    if self.strobe:
        self.capture_buttons()

    if self.read_index >= 8:
        return 1

    bit = (self.captured_buttons >> self.read_index) & 1
    self.read_index += 1
    return bit

查看测试代码test_291_controller_capture_and_serial_read.py

from emulator.input.controller import (
    BUTTON_A,
    BUTTON_DOWN,
    BUTTON_RIGHT,
    BUTTON_SELECT,
    BUTTON_START,
    Controller,
)


def test_capture_buttons_packs_current_buttons_into_captured_snapshot():
    """
    Objective:
    capture_buttons() converts current boolean button fields into one captured byte
    using NES hardware serial order.
    """
    controller = Controller(a=True, start=True, right=True)

    controller.capture_buttons()

    assert controller.captured_buttons == BUTTON_A | BUTTON_START | BUTTON_RIGHT
    assert controller.read_index == 0


def test_capture_buttons_is_a_snapshot_not_live_alias():
    """
    Objective:
    Captured state should remain stable until the next capture.

    This teaches why captured_buttons is a better name than pressed_buttons.
    """
    controller = Controller(a=True)
    controller.capture_buttons()

    controller.a = False

    assert controller.captured_buttons == BUTTON_A


def test_read_bit_returns_buttons_in_nes_serial_order():
    """
    Objective:
    read_bit() exposes one button at a time in hardware order:

        A, B, Select, Start, Up, Down, Left, Right
    """
    controller = Controller(a=True, select=True, down=True, right=True)
    controller.capture_buttons()

    bits = [controller.read_bit() for _ in range(8)]

    assert bits == [1, 0, 1, 0, 0, 1, 0, 1]
    assert controller.read_index == 8


def test_read_bit_returns_one_after_all_8_buttons_are_read():
    """
    Objective:
    After the eight standard controller bits, this tutorial model returns 1 for
    further reads.
    """
    controller = Controller()
    controller.capture_buttons()

    for _ in range(8):
        controller.read_bit()

    assert controller.read_bit() == 1
    assert controller.read_bit() == 1


def test_write_strobe_high_captures_current_buttons_and_sets_strobe():
    """
    Objective:
    Writing a value with bit 0 set turns strobe on and captures current buttons.
    """
    controller = Controller(start=True, down=True)

    controller.write_strobe(0x01)

    assert controller.strobe is True
    assert controller.captured_buttons == BUTTON_START | BUTTON_DOWN
    assert controller.read_index == 0


def test_write_strobe_uses_only_bit_0():
    """
    Objective:
    The controller strobe signal is controlled by bit 0 of the written value.
    Higher bits should not matter.
    """
    controller = Controller(select=True)

    controller.write_strobe(0xFE)

    assert controller.strobe is False

    controller.write_strobe(0xFF)

    assert controller.strobe is True
    assert controller.captured_buttons == BUTTON_SELECT


def test_strobe_high_keeps_capturing_and_returns_a_button_repeatedly():
    """
    Objective:
    While strobe is high, read_bit() keeps recapturing live state and returns the A
    button bit instead of advancing through the serial sequence.
    """
    controller = Controller(a=True, right=True)
    controller.write_strobe(1)

    assert [controller.read_bit() for _ in range(4)] == [1, 1, 1, 1]
    assert controller.read_index == 1

    controller.a = False

    assert controller.read_bit() == 0


def test_strobe_low_allows_serial_reads_to_advance():
    """
    Objective:
    The normal CPU polling pattern is strobe high, then strobe low, then eight
    serial reads.
    """
    controller = Controller(a=True, b=False, start=True, right=True)

    controller.write_strobe(1)
    controller.write_strobe(0)

    bits = [controller.read_bit() for _ in range(8)]

    assert bits == [1, 0, 0, 1, 0, 0, 0, 1]

测试函数 (8)

test_capture_buttons_packs_current_buttons_into_captured_snapshot
test_capture_buttons_is_a_snapshot_not_live_alias
test_read_bit_returns_buttons_in_nes_serial_order
test_read_bit_returns_one_after_all_8_buttons_are_read
test_write_strobe_high_captures_current_buttons_and_sets_strobe
test_write_strobe_uses_only_bit_0
test_strobe_high_keeps_capturing_and_returns_a_button_repeatedly
test_strobe_low_allows_serial_reads_to_advance