Headless Operator UI: OLED and Buttons

Where this fits now

The primary interface to a Kirin board is the Qt/QML touch GUI running fullscreen on the Pi’s DSI panel. The OLED and button panel described in this chapter came first and are no longer the main operator surface — but they have not been removed, and they are not vestigial:

  • --boot and --physical run the game loop headless, with the OLED as the only status output and the buttons as the only input. This is the path a board takes when it is running without a display attached.

  • On a board that does have the touch panel, the OLED remains useful as a secondary status mirror. The GUI plan explicitly declined to require its removal.

  • Bring-up happens in this order. A new board is verified through --oled-test, --sensor-diag and the button checks in this chapter before the GUI is trusted, because these paths have far fewer moving parts between the code and the hardware.

Note

If you are reading this to find out how a finished appliance presents itself to a player, you want the application part instead. This chapter is the wiring and the headless fallback.

OLED Display

Kirin supports a 128$\times$<!-- -->{=html}64 SSD1306-compatible OLED on the Raspberry Pi’s I2C bus. The default software configuration is /dev/i2c-1 at address 0x3C.

Signal

BCM GPIO / Header Pin

Connects To

SDA

GPIO 2 / Pin 3

OLED SDA

SCL

GPIO 3 / Pin 5

OLED SCL

3.3V

Pin 1 or Pin 17

OLED VCC

GND

Any Pi ground pin

OLED GND

OLED I2C wiring

The display controller is implemented in display_controller.h/.cpp. Physical mode uses it for high-level status messages: booting, hardware ready, waiting for the human move, engine thinking, executing a move, illegal board state, wrong storage slot, game over, and idle. Use --oled-test to initialize the display and show a test screen without starting a physical game.

Operator Buttons

Kirin supports three active-low buttons using Raspberry Pi internal pull-ups. Pressing a button connects its GPIO line to ground. The button controller is implemented in button_controller.h/.cpp.

Button

BCM GPIO / Header Pin

Meaning at Safe Prompt

Start

GPIO 20 / Pin 38

Idle: start play white; active game: run go

Stop

GPIO 21 / Pin 40

Active game: stop game; idle: exit physical mode

Reset

GPIO 24 / Pin 18

Home the gantry

Operator button wiring and behavior

Warning

The buttons are high-level UI controls, not an asynchronous emergency stop. They are polled only at safe physical-mode prompts and are not polled during blocking gantry motion, engine search, or waitForHumanMove.