291. Captura del mando y lectura serie

Capturar los botones del mando y leerlos en serie.

Lección 291 de 356 · tests/chapter_07_controller_input/test_291_controller_capture_and_serial_read.py

Archivos creados en este paso

emulator/input/controller.py

Por qué existe este paso

La CPU de la NES no recibe el estado del mando como un byte completo desde $4016. Recibe un bit de botón cada vez. Antes de conectar ese protocolo a CpuBus, el objeto puro Controller debe saber cómo:

Referencias

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

Término clave: strobe Un strobe es una señal de control escrita por la CPU. Para el mando de la NES, el strobe controla si el mando sigue capturando el estado en vivo de los botones o avanza por los bits serie ya capturados.

Ejemplo mínimo

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

Concepto erróneo habitual

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

El emulador puede almacenar internamente los botones capturados como un solo byte, pero el protocolo orientado a la CPU lee un bit cada vez.

Ejemplo de implementación sugerido

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

Fuera de alcance

Enrutamiento de $4016 en CpuBus
Mapeo de teclado de pygame
Puerto de mando 2
Mandos de expansión de Famicom
Comportamiento de glitch de lectura de DMC/mando

Ejecutar esta lección

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

Implementación de ejemplo

Ejemplo mínimo

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

Ejemplo de implementación sugerido

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

Ver código del testtest_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]

Funciones de test (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