Add menu screen REST API

[chrisgleissner]

Summary

This PR adds a REST endpoint for reading the currently displayed firmware menu screen:

GET /v1/machine:menu_screen

The endpoint returns the active 40x25 text-mode screen as raw character and colour-attribute matrices. This avoids capturing the UDP video stream and converting a bitmap image back into text.

Together with the existing REST input endpoint, clients can now drive and inspect the menu entirely through REST.

Related PRs

Documentation for the new endpoint was added to GideonZ/1541u-documentation#27

API Contract

GET /v1/machine:menu_screen

Normal REST API password handling applies. If the device requires authentication and the request does not provide the correct X-Password header, the shared API router returns 403 Forbidden.

200 OK

Returned when a readable 40x25 menu screen is active.

Content-Type: application/octet-stream
Content-Disposition: attachment
Content-Length: 2000

The response body is exactly 2000 bytes:

Range	Size	Content
0..999	1000 bytes	40x25 character matrix
1000..1999	1000 bytes	40x25 colour-attribute matrix

Both matrices are row-major:

offset = row * 40 + column

Each colour-attribute byte contains both colours:

Bits	Meaning
0..3	Foreground colour
4..7	Background colour

404 Not Found

Returned when no readable menu screen is currently available.

Content-Type: application/json

The JSON response contains the normal API errors array, including:

{
  "errors": ["Menu screen unavailable."]
}

Related Fix

This PR also fixes PUT /v1/machine:menu_button.

The documented behaviour is toggle semantics:

• Closed menu: open it.
• Open menu: close it.

On an Ultimate 64 Elite I in UI Overlay mode, the endpoint always opened the menu instead of toggling it. This PR makes the implementation match the documented REST API behaviour:

https://1541u-documentation.readthedocs.io/en/latest/api/api_calls.html

Implementation Notes

• Screen_MemMappedCharMatrix now keeps a per-cell colour-attribute shadow buffer and exposes a bounded matrix-copy method.
• UserInterface::copy_active_screen_matrix() selects an available active UI, verifies it is 40x25, and copies the character plane followed by the colour plane into the REST response buffer.
• The route uses a fixed-size stack buffer and returns the shared JSON error response when no snapshot can be copied.

Validation

Validation included:

• Host screen snapshot regression test.
• menu_screen_test.py in one-shot mode.
• menu_screen_test.py in 2-minute soak-test mode while navigating the menu through REST.
• Manual verification with menu_screen_tool.py in both UI Freeze and UI Overlay mode.

Sample Images

The following side-by-side images were captured using C64 Stream:

• Streaming from an Ultimate 64 Elite I on the right side.
• Kubuntu 24.04 terminal on the left side. The terminal shows output from menu_screen_tool.py, which renders data returned by GET /v1/machine:menu_screen.

Freeze UI Mode

Overlay UI Mode

[Copilot]

Pull request overview

Note

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

Adds the ability to fetch and render the firmware menu screen as a binary “screen matrix” snapshot over the REST API, along with tooling and a PC-side test to validate the snapshot contract.

Changes:

• Introduces GET /v1/machine:menu_screen returning a fixed-size 40x25x2 matrix payload (chars + colour/attribute plane).
• Extends the UI/screen implementation to support copying a stable “active screen matrix” snapshot.
• Adds developer tools (renderer + on-device contract/soak checker) and a PC build target/test for the snapshot logic.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
tools/api/menu_screen_tool.py	New CLI tool to fetch and render menu_screen as ANSI output.
tools/api/menu_screen_test.py	New integration/soak test tool that validates API contract/auth/unavailable states.
target/pc/linux/screensnapshottest/Makefile	New PC target to build/run the screen snapshot unit test.
software/userinterface/userinterface.h	Adds constants and API for copying the active screen matrix.
software/userinterface/userinterface.cc	Implements active UI screen snapshot copy with safety checks.
software/test/user_interface/src/screen_snapshot_test.cc	Adds a focused test for Screen_MemMappedCharMatrix::copy_matrix.
software/io/c64/screen.h	Adds copy_matrix API and ownership for per-cell colour codes.
software/io/c64/screen.cc	Implements snapshot copying and tracks per-cell colour codes across output/clear/scroll.
software/application/ultimate/ultimate.cc	Adds a helper to push the active menu button via overlay when accessible.
software/api/route_machine.cc	Adds GET machine:menu_screen and improves PUT machine:menu_button behavior.

---

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

[chrisgleissner]

Hi @GideonZ ,

here is a PR for the new REST endpoint we discussed.

Thanks for your review. If there's anything you'd like me to change, let me know.

I've done the usual tests: unit, E2E, soak, manual with screenshots.

Thanks
Christian