diff --git a/Ultimate_OpenAPI_specs.yaml b/Ultimate_OpenAPI_specs.yaml index 9fd990e..d391e63 100644 --- a/Ultimate_OpenAPI_specs.yaml +++ b/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: diff --git a/u2plus-open-api-spec.yaml b/u2plus-open-api-spec.yaml index 79542b9..45d7acb 100644 --- a/u2plus-open-api-spec.yaml +++ b/u2plus-open-api-spec.yaml @@ -36,16 +36,32 @@ paths: "errors": [ ] } schema: - allOf: - - $ref: '#/components/schemas/Errors' - type: object - properties: - version: - type: string + $ref: '#/components/schemas/VersionResponse' '404': description: Not Found '504': description: Gateway Timeout + /info: + get: + operationId: getInfo + summary: Get device information + description: Returns hardware metadata (product, firmware version, FPGA/core versions, hostname). Available on Ultimate firmware 3.12 and newer. On earlier releases the endpoint responds with HTTP 404. + tags: + - About + responses: + '200': + description: Successful operation. + content: + application/json: + schema: + $ref: '#/components/schemas/InfoResponse' + '404': + description: Not Found + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Errors' /machine:reset: put: operationId: resetMachine @@ -117,7 +133,7 @@ paths: '404': description: Not Found content: - application/json: { } + application/json: {} /machine:poweroff: put: operationId: powerOffMachine @@ -137,6 +153,56 @@ paths: - $ref: '#/components/schemas/Errors' '404': description: Not Found + /machine:menu_button: + put: + operationId: toggleMenuButton + summary: Toggle Ultimate menu button + description: Toggles the Ultimate firmware menu, equivalent to pressing the physical menu button. If the menu is closed it opens; if the menu is open it closes. + tags: + - Machine operations + responses: + '200': + description: Button event queued + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Errors' + /machine:menu_screen: + get: + operationId: getMenuScreen + 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` to inspect the firmware menu over REST. + tags: + - Machine operations + 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:readmem: get: operationId: readMemory @@ -795,7 +861,7 @@ paths: requestBody: content: application/octet-stream: - schema: { } + schema: {} responses: '200': description: Successful operation. @@ -825,7 +891,7 @@ paths: Undefined subsystem command: value: |- { - "errors" : [ "Undefined subsystem command" ]x + "errors" : [ "Undefined subsystem command" ] } '507': description: Unknown @@ -907,7 +973,7 @@ paths: requestBody: content: application/octet-stream: - schema: { } + schema: {} responses: '200': description: Successful operation. @@ -1013,6 +1079,8 @@ paths: ], "errors": [] } + schema: + $ref: '#/components/schemas/DriveListResponse' /drives/{drive}:mount: put: operationId: putMountDiskImage @@ -1176,7 +1244,7 @@ paths: requestBody: content: application/octet-stream: - schema: { } + schema: {} responses: '200': description: Successful operation. @@ -1594,15 +1662,15 @@ paths: Valid options are one of the following:
`a`, `b` - in: query - name: mod + name: mode schema: type: string + enum: + - "1541" + - "1571" + - "1581" required: true description: The available values are `1541`, `1571` and `1581`. - requestBody: - content: - application/octet-stream: - schema: {} responses: '200': description: Successful operation. @@ -1840,14 +1908,7 @@ paths: "errors": [] } schema: - allOf: - - $ref: '#/components/schemas/Errors' - type: object - properties: - categories: - type: array - items: - type: string + $ref: '#/components/schemas/ConfigListResponse' '404': description: Endpoint not found post: @@ -2642,3 +2703,85 @@ components: type: array items: type: string + VersionResponse: + allOf: + - $ref: '#/components/schemas/Errors' + - type: object + required: + - version + properties: + version: + type: string + InfoResponse: + allOf: + - $ref: '#/components/schemas/Errors' + - type: object + properties: + product: + type: string + firmware_version: + type: string + fpga_version: + type: string + core_version: + type: string + description: Present on Ultimate 64 devices. + hostname: + type: string + unique_id: + 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 + DriveListResponse: + allOf: + - $ref: '#/components/schemas/Errors' + - type: object + properties: + drives: + type: array + items: + type: object + additionalProperties: + type: object + properties: + enabled: + type: boolean + bus_id: + type: integer + type: + type: string + rom: + type: string + image_file: + type: string + image_path: + type: string + last_error: + type: string + partitions: + type: array + items: + type: object + properties: + id: + type: integer + path: + type: string + ConfigListResponse: + allOf: + - $ref: '#/components/schemas/Errors' + - type: object + properties: + categories: + type: array + items: + type: string