Repository navigation
Python: basic pybind11 interface to the microcontroller - #1612
Conversation
Adds _pa_core, a pybind11 module (new PA_PYTHON_BINDINGS cmake option, OFF by default) that wraps the existing CoreLib class NintendoSwitch::PybindSwitchProController so Python can act as a Nintendo Switch controller through a PABotBase2 serial device: status, queued button / d-pad / stick commands, flush and cancel, button/d-pad constants, and log-to-stderr/file controls. C++ exceptions surface as RuntimeError; blocking calls release the GIL. The pokemon_automation Python package sits on top of it: SwitchController (button names instead of bitfields), button parsing, list_serial_ports(), a hardware-free FakeController, a hardware self-test, and a pytest suite. See SerialPrograms/Source/PythonBindings/README.md. A new CI workflow builds the GUI-free core plus the module on Ubuntu and runs the pytest suite. PR #1519 is used as a reference.
23b3635 to
871232d
Compare
…ng CoreLib The rebased branch picked up AbstractController::cancel_all_and_wait() (cancel + wait for the device to acknowledge the neutral state, returns a bool), which replaced the old fire-and-forget cancel_all_commands(). Update the _pa_core binding, the pokemon_automation API (cancel_all_and_wait() now returns whether the device confirmed; close() uses it to guarantee a neutral state), the fake controller, the tests, and the docs. Also compile the third-party 3rdParty-Core/miniz-3.1.1/miniz.c with warnings off (/W0 on MSVC, -w on GCC/Clang): it is compiled straight into CoreLib, and newer compilers emit warnings in it that -Werror / /WX turn into build errors. It includes miniz.h from its own directory, so a SYSTEM include directory cannot shield it; suppressing the file itself is the portable fix.
…ties() The old copy in CMakeLists.txt only runs in the full build: with PA_CORE_ONLY the configure returns before reaching it, so miniz.c was still compiled with -Werror / /WX in core-only builds. Setting the source property from pa_apply_base_target_properties() (cmake/CoreLib.cmake) covers both build modes and every target that uses it; the two now-redundant copies are removed. Use if(MSVC) instead of if(WIN32) - the flag choice follows the compiler's command-line dialect (true for cl and for clang-cl), and COMPILE_OPTIONS instead of the deprecated COMPILE_FLAGS.
…e PA_CORE_ONLY miniz.c is compiled into every target that uses CORE_LIBRARY_SOURCES - CoreLib in both build modes, and SerialProgramsLib in the full build (which compiles its own copy of the core sources), so the fix belongs in the base CMakeLists.txt, not CoreLib.cmake. It must also run before the PA_CORE_ONLY early return, which is where the old copy at the bottom of the file (from #1098) was, and why core-only builds still failed. Source properties are global, so one set_source_files_properties() covers all targets; verified that in a full build both CoreLib's and SerialProgramsLib's miniz.c compile lines carry the suppression.
- 'simulatenously' -> 'simultaneously' - selftest code block: [port] is not shell syntax; show the optional argument as a real example instead - rename 'Running the test file' to 'Hardware self-test' (the pytest suite lives in tests/) and add the missing 'Running the unit tests' section, which the Layout section advertises but nothing in the file explained - add wait() to the method list (it is used in the example) - drop trailing whitespace
Add comments naming the C++ source each Python definition mirrors or depends on (repo-relative paths): the BUTTON_BITS/DPAD_POSITIONS constants and check_against_core() vs the enums in NintendoSwitch_ControllerButtons.h; the ControllerBackend protocol, status/flush/cancel_all_and_wait and press() vs PybindSwitchProController / AbstractController; the fake and the _core loader vs the module source and the wrapped class; and the test headers. Also note that DEFAULT_HOLD_MS/DEFAULT_RELEASE_MS are Python-side defaults (the C++ issue_buttons() takes explicit durations).
The command methods of SwitchController now match the names of the
_p a_core.Controller methods they wrap (and thus the C++
PybindSwitchProController methods):
- press() -> push_button() / push_dpad() (mixed combos now go to
controller_state(); each method rejects the other kind
with a pointer to the right method)
- hold() -> controller_state() (duration_ms first, like the C++
signature; no implicit release wait)
- stick(side) -> push_left_joystick() / push_right_joystick()
- flush() -> wait_for_all_requests()
- status() -> current_status()
- name() -> controller_name()
- wait(), cancel_all_and_wait(), is_ready() and close() already matched.
Button-name parsing is unchanged; _pa_core and FakeController are
untouched. Updated examples in the package docstrings, README,
switch_connection_test.py and the tests (31 tests now, including
rejection of mixed inputs in push_button()/push_dpad()).
Each call now queues exactly one tap, matching the single-command semantics of the C++ layer; repeated presses are just repeated calls (or a controller_state() with a longer hold).
…ation/Arduino-Source into python-pybind-basic
- controller.py: cancel_all_and_wait() docstring cited the old C++\n parameter name (timeout_millis -> timeout_ms).\n- README: 'insid' -> 'inside', 'run the all tests' -> 'run all the tests',\n queue examples used a nonexistent duration kwarg (now hold_ms, which is\n what push_left_joystick() actually takes), and mkdir bin -> mkdir -p bin\n so the instructions work on a re-run.\n- test_push_right_joystick now actually passes a [x, y] list, matching its\n docstring (lists are accepted via parse_stick_pair).
close() no longer lets a command slip in after the cancel: the closed flag is set under the command lock, and every command method re-checks it while holding the lock before sending, so commands starting while the cancel is in flight are rejected.
a9db077 to
b1698ea
Compare
…eturns
nullptr for an empty name, leaving m_connection null and crashing
current_status(). The constructor, destructor, controller() and
current_status() now tolerate a null connection ("No connection."), and
SwitchController rejects an empty port up front with a ValueError.
#1 Destruction race (PybindSwitchController.cpp): the connection thread is joined only when m_connection is destroyed, i.e. after m_controller, m_cv and m_lock already were. Destroying the controller while a connection is still establishing (e.g. SwitchController's timeout path) let the connect thread write to destroyed members. The destructor now resets m_connection first, so the thread is joined before any member is destroyed. #2 Empty port name: SerialPABotBase2_Descriptor::open_connection() returns nullptr for an empty name, leaving m_connection null and crashing current_status(). The constructor, destructor, controller() and current_status() now tolerate a null connection ("No connection."), and SwitchController rejects an empty port up front with a ValueError.
1b6d376 to
3d248db
Compare
|
I've looked through about half the files so far. Still working on the rest. I'm wondering if we should rename |
Matches the C++ class it wraps (PybindSwitchProController) and the device's controller type (the Pro Controller / wired controller). No backwards-compat alias: the package is pre-release (0.1.0).
START/SELECT/L3/LS/R3/RS and the "+"/"-" spellings no longer map to PLUS/MINUS/LCLICK/RCLICK. "+" remains a separator (a lone "+" parses to no input), and "-" and the former alias names are now unknown buttons with the usual ValueError. Removed the now-dead "+"/"-" special cases in _split()/parse_buttons(), the __init__ export, and the docs; the alias test now pins the new behavior.
Mysticial
left a comment
There was a problem hiding this comment.
Approved at a high level. Rubber stamping most of the Python details. API seems ok.
We'll want to follow up later with a Python TurboA or something just to feel it out before we commit to the API. But at least we're not a in a hurry, gen10 is a year away.
pa-devbot
left a comment
There was a problem hiding this comment.
AI review: Read through the whole diff and verified it locally: configured cmake .. -G Ninja -DPA_CORE_ONLY=ON -DPA_PYTHON_BINDINGS=ON (pybind11 3.1.0, Python 3.14), built _pa_core and SerialProgramsCommandLine, and ran the pytest suite — 38/38 pass, including the destroy-while-connecting and close-threading stress tests, repeatedly. All GitHub checks are green, including the new ubuntu-26.04 Python-bindings workflow and the main full build.
Things I specifically checked out:
- Destructor ordering (
PybindSwitchController.cpp): resettingm_connectionin the internal destructor runs beforem_lock/m_cv/m_controllerare destroyed, and~SerialPABotBase2_Connectioncancels and joins the connect thread before returning (SerialPABotBase2_Connection.cpp:52-55, join at :61), so apost_connection_ready()that is mid-flight can't touch dead members.ListenerSet::removeblocks until the removed listener's callback finishes, so the remove-then-reset order is safe. - Empty-port guards: correct —
SerialPABotBase2_Descriptor::open_connection()returns nullptr for an empty name (SerialPABotBase2_Descriptor.cpp:61-64), and allm_connectionuses are now guarded. - CMake: moving the miniz
/W0source-file property above thePA_CORE_ONLYearly return is needed — CoreLib compilesminiz.cin the core-only build too, with-Werror. - Module plumbing: GIL is released on every blocking call,
PokemonAutomation::Exception→RuntimeErrorworks (non-PA exceptions still fall through to pybind11's translators), and the log sink is properly locked (deque of last 1000 lines). - Python layer: parsing, contradictory d-pad rejection, and the close() "flag under lock, re-check under lock" scheme all hold up; the parameter reordering to match
pbf_*is clean and all call sites were updated.
Remaining comments are nits, mostly docstrings.
One design note (not a blocker): SwitchProController hard-codes delay = hold + release and doesn't expose delay_ms, so overlapping presses require dropping to the raw _pa_core module — that seems intentional for now, but the docstring currently reads like the Python method supports it (see inline).
| C++ reference: `_pa_core` is built from | ||
| SerialPrograms/Source/PythonBindings/PythonBindings_Module.cpp and wraps | ||
| `NintendoSwitch::PybindSwitchProController` | ||
| (SerialPrograms/Source/Integrations/PybindSwitchProController.h/.cpp), which |
There was a problem hiding this comment.
AI review: The file is PybindSwitchController.h/.cpp (the class is PybindSwitchProController), not PybindSwitchProController.h. This wrong path shows up in ~8 places: README.md:6, init.py:8, _core.py:11, controller.py:42/139/167/277, fake.py:9, tests/test_core.py:7, tests/test_fake_controller.py:4 (I'll let you pick which to fix — it's a search-and-replace of PybindSwitchProController.h → PybindSwitchController.h).
| `controller_state()`. | ||
|
|
||
| This function does not allow for overlapping button presses. For that, use controller_state(). | ||
| However, the pybind backend does expose `delay_ms`. If this is set to less than `hold_ms`, one may |
There was a problem hiding this comment.
AI review: This method doesn't expose delay_ms — it always sends delay = hold + release, so a reader can't act on this tip without dropping to _pa_core.Controller. Either reword to say so ("use the raw _pa_core backend to overlap") or add a delay_ms parameter.
|
|
||
| def close(self) -> None: | ||
| """Stop the device (cancelling queued commands and waiting briefly for the | ||
| neutral state) and drop the connection. |
There was a problem hiding this comment.
AI review: close() cancels commands and sets the flag, but the wrapped C++ controller (and with it the open serial port and its connect thread) lives on until this wrapper is garbage-collected. For a PABotBase2 that can only hold one connection that matters if the wrapper outlives the with block. Consider releasing the backend reference on close, or softening "drop the connection" to "stop the device".
|
|
||
| # Bit positions, mirroring the C++ `enum Button` in | ||
| # SerialPrograms/Source/NintendoSwitch/Controllers/NintendoSwitch_ControllerButtons.h. | ||
| # Do not edit by hand; tests/test_buttons.py checks these against the C++ enum. |
There was a problem hiding this comment.
AI review: It's actually tests/test_core.py::test_python_constants_match_cpp (via check_against_core()) that verifies these against the C++ enum; test_buttons.py only exercises parsing.
| elif sys.platform.startswith("linux"): | ||
| ports = glob.glob("/dev/ttyUSB*") + glob.glob("/dev/ttyACM*") + glob.glob("/dev/ttyS[0-9]*") | ||
| else: | ||
| ports = [f"COM{i}" for i in range(1, 64)] |
There was a problem hiding this comment.
AI review: Without pyserial, Windows returns COM1..COM63 as candidates, and switch_connection_test tries each with a 5 s timeout — up to ~5 minutes on a machine with no device. The README could nudge users toward the serial extra (pip install -e .[serial]) for port discovery.
| self._closed = False | ||
| self.port = port | ||
| if not self._backend.wait_for_ready(int(timeout_s * 1000)): | ||
| raise RuntimeError(f"Controller on {port} is not ready: {self._backend.current_status()}") |
There was a problem hiding this comment.
AI review: When a backend is passed, port is None and the failure reads "Controller on None is not ready".
| sw.push_button("L+R", hold_ms=200) # press L and R together | ||
| sw.push_dpad("up") # d-pad up | ||
| sw.push_left_joystick((0.0, 1.0), hold_ms=1500) # walk forward | ||
| sw.controller_state("B", "up", left_joystick=(0.0, 1.0), duration_ms=2000) # run forward |
There was a problem hiding this comment.
AI review: Minor: this example also holds d-pad up while "running forward" — running is B + left stick, so the "up" d-pad arg makes the example misleading.
pa-devbot
left a comment
There was a problem hiding this comment.
AI review: Re-reviewed the 4 new commits (8ec0607, 8dad423, fa5597a, 46581b7 — docs/comments only). All seven comments from my previous review are addressed:
PybindSwitchProController.h→PybindSwitchController.hin all 8 places ✓push_button()docstring now says the raw_pa_corebackend exposesdelay_ms✓close()docstring no longer claims it drops the connection ✓buttons.pynow points attests/test_core.py::test_python_constants_match_cpp✓- README warns about the Windows COM1–COM63 fallback and suggests pyserial ✓
- Not-ready error reads "port: not specified" when a backend was passed ✓
- Module-docstring example comment is now accurate ✓
Re-ran the full pytest suite locally on the updated tree: 38/38 pass (no C++ or logic changes, so the earlier build results still stand). Two tiny new nits below — both optional.
| self._closed = False | ||
| self.port = port | ||
| if not self._backend.wait_for_ready(int(timeout_s * 1000)): | ||
| raise RuntimeError(f"Controller is not ready (port: {port or 'not specified'}): {self._backend.current_status()}") |
There was a problem hiding this comment.
AI review: Four trailing spaces at the end of this line.
| python -m pokemon_automation.switch_connection_test /dev/ttyACM0 | ||
| ``` | ||
|
|
||
| If `port` is omitted, every port from `list_serial_ports()` is tried in turn. WARNING: In Windows, without pyserial, the script will try every port from COM1 to COM63, which can take several minutes. Consider installing pyserial with `pip install pyserial`. |
There was a problem hiding this comment.
AI review: Minor: "on Windows" rather than "In Windows".
Basic Python interface using pybind11, so a Python developer can send simple commands to the microcontroller. Used PR #1519 as a reference, but kept this to the small, well-understood part of it (no MCP server, video or OCR).
What's in it
_pa_core(new,SerialPrograms/Source/PythonBindings/PythonBindings_Module.cpp): a pybind11 module that wraps the existing CoreLib classNintendoSwitch::PybindSwitchProController— a thin 1:1 binding:Controller(port)+wait_for_ready(),is_ready(),current_status(),controller_name()push_button(),push_dpad(),push_left_joystick(),push_right_joystick(),controller_state(),wait(), pluswait_for_all_requests()(flush) andcancel_all_and_wait(timeout_ms)(cancel + wait for the device to confirm the neutral state, returns a bool)BUTTONS/DPAD_POSITIONSconstants generated from the C++ enumsset_log_stderr(),set_log_file(),log(),recent_logs()) — nothing goes to stdoutPokemonAutomation::Exception-> PythonRuntimeError; blocking calls release the GILpokemon_automationPython package on top of it:SwitchControllerwith button names instead of bitfields:sw.press("L+R"),sw.press("up", repeat=2),sw.stick("left", "up", duration_ms=1500),sw.hold("B", left="up"),sw.flush(),sw.cancel_all_and_wait();close()cancels with confirmation firstbuttons.py(name parsing, verified against the C++ enums),devices.list_serial_ports(),fake.FakeControllerfor tests without hardware,python -m pokemon_automation.selftest [port]for a quick hardware checkpip install -e SerialPrograms/Source/PythonBindingsworksPA_PYTHON_BINDINGSoption (OFF by default, so existing builds/CI are unaffected), wired into both the full andPA_CORE_ONLYbuilds. pybind11 is picked up from a system package orpip install pybind11, with a pinnedFetchContentfallback.3rdParty-Core/miniz-3.1.1/miniz.cis compiled into every target that usesCORE_LIBRARY_SOURCES— CoreLib in both build modes, and SerialProgramsLib in the full build. It now gets a per-file warning suppression (/W0on MSVC,-won GCC/Clang) set in the baseCMakeLists.txtbefore thePA_CORE_ONLYearly return (the old copy from File Unzip using miniz library #1098 sat below it, so core-only builds never got it; source properties are global, so one setting covers all targets). It includes its own header from its own directory, so no SYSTEM include directory can shield it, andif(MSVC)/COMPILE_OPTIONSreplace the oldif(MSVC)-with-COMPILE_FLAGSform.Example
Verified (aarch64 Linux)
-w; module builds clean_pa_coreisn't built)Notes / follow-ups
A CI workflow for this (core-only build + pytest on Ubuntu) is ready locally but the bot's token can't push
.github/workflows/files (noworkflowscope) — a maintainer can add it:PR Agent mcp server #1519 extends this with the full package (MCP server, video, OCR) — this PR is meant to land as the understood foundation for that.