Add docs for new REST endpoints and Machine Code Monitor

[chrisgleissner]

What's Changed

• Add docs for new REST API endpoints /v1/machine:input and /v1/machine:menu_screen.
• Add OpenAPI YAML contract for entire REST API to facilitate auto-generated REST clients.
• Add docs for machine code monitor.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds new documentation and machine-readable specs to expand the Ultimate firmware docs, including a new Machine Code Monitor how-to and an OpenAPI 3.1 representation of the REST API.

Changes:

• Added a new “Machine Code Monitor” how-to page and linked it from the docs index.
• Added an OpenAPI 3.1 YAML spec for the REST API plus a dedicated docs page that links/includes it.
• Extended the REST API reference with menu-screen and REST input endpoint documentation.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
index.rst	Adds navigation entries for the new monitor doc and the OpenAPI page.
howto/machine_code_monitor.rst	Introduces a full how-to page for the machine code monitor UI and commands.
api/rest_api_openapi.yaml	Adds an OpenAPI 3.1 document describing the REST API endpoints and schemas.
api/openapi.rst	Adds a docs page to download and view the OpenAPI YAML spec.
api/api_calls.rst	Links to OpenAPI and documents additional REST endpoints (menu screen, input).
.gitignore	Adjusts build artifact ignore rule.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chrisgleissner]

Hi @GideonZ ,

here are the updated docs.

Changes:

• It also includes screenshots based on the latest version of the machine code monitor, see Machine code monitor fixes 1541ultimate#704
• Additionally it cover the new REST API added in Add menu screen REST API 1541ultimate#703
• Additionally, I added an OpenAPI version of the REST API which has helped me a lot in various other projects, such as C64 Bridge and C64 Stream. It is the industry standard (see https://spec.openapis.org/oas/v3.2.0.html) for describing a REST API in a formal manner, allowing for easy auto-generation of clients.

I verified the resulting HTML version and it's ready for merge.

Thanks
Christian

[matozoid]

Note that a yaml spec is being maintained at https://github.com/Grrrolf/u2plus-open-api-spec too.

[chrisgleissner]

Thanks @matozoid , I did not know about this and thus created my own version from scratch last year ago, focusing on the Ultimate 64 Elite I which was the only device I owned back then. I then used this for various projects, especially C64 Stream and C64 Bridge. The version included in this PR is based on it.

In order to ensure that others can benefit from our research efforts, I suggest we create a combined version of both OpenAPI Yaml specs and add them to the official docs, to be updated alongside the human-targeted docs whenever the REST API is extended. This also ensures they never get out of synch, as it's the onus on whoever adds / changes the REST API to not only align human-facing, but also machine readable docs.

As your version is more advanced than mine in terms of examples and separation of U2 and U64, I could raise a PR for your repo and then we add a link towards it to the official docs.

However, I wonder whether we really need two separate repos to host the documentation of the Ultimate 64. One is human facing, the other machine facing. But they almost must evolve in lockstep: As you add new REST endpoints or change them, you'll want to change their documentation to be consistent. And having to raise many PRs adds developer overhead but also increases the chance of inconsistencies. So I would suggest to incorporate an OpenAPI documentation directly in this repo rather than just via a link, of course with proper attribution to the original authors of the OpenAPI Yaml. Ongoing evolution could then be driven simply via normal PRs agains this repo.

Many thanks for your thoughts on this.

[matozoid]

I'm 100% for having a single best-of-all-worlds spec in the repo here. I assume @Grrrolf - the repo owner - would agree. Just waiting for him to pop up in the discussion :-)