Add menu screen and input endpoints to OpenAPI specification

Ultimate_OpenAPI_specs.yaml

@@ -17,6 +17,226 @@ components:
       in: header
       name: X-Password
       description: "The API password, if one is configured in the Network Settings."
+  schemas:
+    Errors:
+      type: object
+      required: [ errors ]
+      properties:
+        errors:
+          type: array
+          items:
+            type: string
+    MenuScreenBytes:
+      type: string
+      format: binary
+      description: |
+        Exactly 2000 bytes. Bytes 0..999 are the 40x25 firmware UI character
+        matrix. Bytes 1000..1999 are the matching 40x25 colour-attribute
+        matrix. Both matrices are row-major: offset = row * 40 + column.
+        In each colour-attribute byte, bits 0..3 are the foreground colour
+        and bits 4..7 are the background colour.
+      minLength: 2000
+      maxLength: 2000
+    InputTransition:
+      type: string
+      enum:
+        - press
+        - release
+        - tap
+    KeyboardInputName:
+      type: string
+      enum:
+        - inst_del
+        - return
+        - cursor_left_right
+        - f7
+        - f1
+        - f3
+        - f5
+        - cursor_up_down
+        - "0"
+        - "1"
+        - "2"
+        - "3"
+        - "4"
+        - "5"
+        - "6"
+        - "7"
+        - "8"
+        - "9"
+        - a
+        - b
+        - c
+        - d
+        - e
+        - f
+        - g
+        - h
+        - i
+        - j
+        - k
+        - l
+        - m
+        - n
+        - o
+        - p
+        - q
+        - r
+        - s
+        - t
+        - u
+        - v
+        - w
+        - x
+        - y
+        - z
+        - left_shift
+        - right_shift
+        - plus
+        - minus
+        - period
+        - colon
+        - at
+        - comma
+        - pound
+        - star
+        - semicolon
+        - clr_home
+        - equals
+        - arrow_up
+        - slash
+        - arrow_left
+        - ctrl
+        - space
+        - commodore
+        - run_stop
+        - restore
+      description: |
+        REST input name from the C64 keyboard matrix. `restore` is special:
+        firmware accepts it only as the sole input in a keyboard event with
+        transition `tap`.
+    JoystickInputName:
+      type: string
+      enum:
+        - up
+        - down
+        - left
+        - right
+        - fire
+        - fire2
+        - fire3
+    KeyboardInputEvent:
+      type: object
+      additionalProperties: false
+      required:
+        - kind
+        - inputs
+        - transition
+      properties:
+        kind:
+          type: string
+          const: keyboard
+        inputs:
+          type: array
+          minItems: 1
+          maxItems: 8
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/KeyboardInputName'
+        transition:
+          $ref: '#/components/schemas/InputTransition'
+    JoystickInputEvent:
+      type: object
+      additionalProperties: false
+      required:
+        - kind
+        - port
+        - inputs
+        - transition
+      properties:
+        kind:
+          type: string
+          const: joystick
+        port:
+          type: integer
+          enum:
+            - 1
+            - 2
+        inputs:
+          type: array
+          minItems: 1
+          maxItems: 7
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/JoystickInputName'
+        transition:
+          $ref: '#/components/schemas/InputTransition'
+    ReleaseAllInputEvent:
+      type: object
+      additionalProperties: false
+      required:
+        - kind
+      properties:
+        kind:
+          type: string
+          const: release_all
+    InputEvent:
+      oneOf:
+        - $ref: '#/components/schemas/KeyboardInputEvent'
+        - $ref: '#/components/schemas/JoystickInputEvent'
+        - $ref: '#/components/schemas/ReleaseAllInputEvent'
+    InputRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - events
+      properties:
+        events:
+          type: array
+          minItems: 1
+          maxItems: 64
+          items:
+            $ref: '#/components/schemas/InputEvent'
+    KeyboardInputState:
+      type: object
+      required:
+        - inputs
+      properties:
+        inputs:
+          type: array
+          items:
+            $ref: '#/components/schemas/KeyboardInputName'
+    JoystickInputState:
+      type: object
+      required:
+        - port
+        - inputs
+      properties:
+        port:
+          type: integer
+          enum:
+            - 1
+            - 2
+        inputs:
+          type: array
+          items:
+            $ref: '#/components/schemas/JoystickInputName'
+    InputStateResponse:
+      allOf:
+        - $ref: '#/components/schemas/Errors'
+        - type: object
+          required:
+            - keyboard
+            - joysticks
+          properties:
+            keyboard:
+              $ref: '#/components/schemas/KeyboardInputState'
+            joysticks:
+              type: array
+              minItems: 2
+              maxItems: 2
+              items:
+                $ref: '#/components/schemas/JoystickInputState'
 security:
   - passwordHeader: []
 tags:
@@ -253,6 +473,103 @@ paths:
       responses:
         '200':
           description: "OK"
+  /machine:menu_screen:
+    get:
+      tags:
+        - Machine Control
+      summary: Read active firmware menu screen
+      description: |
+        Returns the active 40x25 firmware menu text-mode screen as two raw
+        matrices. The first 1000 bytes are character bytes; the second 1000
+        bytes are colour-attribute bytes. This endpoint is intended to be used
+        with `/v1/machine:menu_button` and `/v1/machine:input` to drive and
+        inspect the firmware menu over REST.
+      operationId: machine_menu_screen
+      responses:
+        '200':
+          description: Readable 40x25 menu screen returned
+          headers:
+            Content-Length:
+              schema:
+                type: integer
+                enum: [2000]
+          content:
+            application/octet-stream:
+              schema:
+                $ref: '#/components/schemas/MenuScreenBytes'
+        '404':
+          description: No readable menu screen is currently available
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Errors'
+              examples:
+                unavailable:
+                  value:
+                    errors:
+                      - Menu screen unavailable.
+  /machine:input:
+    get:
+      tags:
+        - Machine Control
+      summary: Get REST-injected input state
+      description: Returns the currently active keyboard and joystick inputs injected through the REST input endpoint. Ultimate 64-class hardware is required; this endpoint is not supported on Ultimate-II/Ultimate-II+ hardware and returns HTTP 501 there.
+      operationId: machine_input_get
+      responses:
+        '200':
+          description: Input state returned
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InputStateResponse'
+        '501':
+          description: Keyboard and joystick injection are not supported on this hardware
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Errors'
+    post:
+      tags:
+        - Machine Control
+      summary: Inject keyboard and joystick input
+      description: |
+        Applies a validated batch of keyboard, joystick, and release-all events,
+        then returns the resulting input state. The firmware validates the
+        complete batch before applying any event; invalid batches return HTTP
+        400 and leave the current input state unchanged. When the firmware menu
+        is active, keyboard events are translated to menu keystrokes.
+        Ultimate 64-class hardware is required; this endpoint is not supported
+        on Ultimate-II/Ultimate-II+ hardware and returns HTTP 501 there.
+      operationId: machine_input_post
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InputRequest'
+      responses:
+        '200':
+          description: Events applied
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InputStateResponse'
+        '400':
+          description: Invalid body, content type, or event batch
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Errors'
+        '501':
+          description: Keyboard and joystick injection are not supported on this hardware
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Errors'
   /machine:reset:
     put:
       tags: