public_git
/
pikvm
mirror of https://github.com/pikvm/pikvm.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Cleanup, part 1 of N 

- Write short intro for HID and Streamer sections
- Fix the structure in HI and Streamer
- Standardize descriptions
This commit is contained in:
Aleksandr Prokudin 2025-06-10 14:02:54 +02:00
parent 9cc4dada90
commit 88c7ffbf78
1 changed files with 113 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
docs/api.md
View File

@ -261,11 +261,19 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/log
-----
## HID
This API provides comprehensive control over virtual HID devices.
The PiKVM HID (Human Interface Device) API provides remote control capabilities for keyboard and mouse input devices. It allows users to perform the following operations:
- Get the device state and set/reset parameters.
- Send keyboard shortcuts and text to be typed in the host system.
- Send various mouse events: move to absolute coordinates and relatively, click virtual mouse buttons, and scroll the virtual mouse wheel.
### Get devices state
The `GET /hid` handle get the current HID devices state.
**Method**: `GET`
**Route**: `/hid`
**Description**: Gets the current HID devices state.
**Query parameters**: none.
@ -326,7 +334,11 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/hid
### Set parameters
The `POST /hid/set_params` handle helps configure HID device parameters.
**Method**: `POST`
**Route**: `/hid/set_params`
**Description**: Configures HID device parameters, such as the type of emulated keyboard and mouse.
**Query parameters**:
@ -339,7 +351,9 @@ The `POST /hid/set_params` handle helps configure HID device parameters.
**Example of use**:
``` sh
$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/set_params?jiggler=0
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/set_params?jiggler=0
```
??? note "Example output"
@ -360,9 +374,13 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/set_params?jiggler=0
### Set the connected state
The `POST /hid/set_connected` handle set the HID devices connection state.
**Method**: `POST`
**Available parameters**:
**Route**: `/hid/set_connected`
**Description**: Sets the HID devices connection state.
**Query parameters**:
| Parameter | Type | Optionality | Description | Acceptable values |
|-----------|------|-------------|-------------|-------------------|
@ -371,7 +389,9 @@ The `POST /hid/set_connected` handle set the HID devices connection state.
**Example of use**:
``` sh
$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/set_connected?connected=0
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/set_connected?connected=0
```
??? note "Example output"
@ -392,7 +412,11 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/set_connected?connec
### Reset devices' state
The `POST /hid/reset` handle resets HID devices to their initial state.
**Method**: `POST`
**Route**: `/hid/reset`
**Description**: Resets HID devices to their initial state.
**Query parameters**: none
@ -420,7 +444,11 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/reset
### Get keyboard layouts
The `GET /hid/keymaps` handle gets available keyboard layouts and the current defaults.
**Method**: `GET`
**Route**: `/hid/keymaps`
**Description**: Gets available keyboard layouts and the current defaults.
**Query parameters**: none
@ -490,7 +518,11 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/hid/keymaps
### Type text remotely
The `POST /hid/print` handle transmits user-defined text to emulate typing it on the PiKVM by sequencing key presses.
**Method**: `POST`
**Route**: `/hid/print`
**Description**: Transmits user-defined text to emulate typing it on the PiKVM by sequencing key presses.
**Query parameters**:
@ -503,7 +535,10 @@ The `POST /hid/print` handle transmits user-defined text to emulate typing it on
**Example of use**:
``` sh
$ curl -k -X POST -u admin:admin -d "Einige Worte" https://<pikvm-ip>/api/hid/print?keymap=de
$ curl -k -X POST \
-u admin:admin \
-d "Einige Worte" \
https://<pikvm-ip>/api/hid/print?keymap=de
```
??? note "Example output"
@ -524,7 +559,11 @@ $ curl -k -X POST -u admin:admin -d "Einige Worte" https://<pikvm-ip>/api/hid/pr
### Send a keyboard shortcut
The `POST /hid/events/send_shortcut` handle sends a keyboard shortcut, or key combination, to be emulated on the PiKVM.
**Method**: `POST`
**Route**: `/hid/events/send_shortcut`
**Description**: Sends a keyboard shortcut, or key combination, to be typed on the PiKVM.
**Query parameters**:
@ -535,7 +574,9 @@ The `POST /hid/events/send_shortcut` handle sends a keyboard shortcut, or key co
**Example of use**:
``` sh
$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/events/send_shortcut?keys=ControlLeft,KeyL
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/events/send_shortcut?keys=ControlLeft,KeyL
```
??? note "Example output"
@ -556,7 +597,11 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/events/send_shortcut
### Send a single key event
The `POST /hid/events/send_key` handle transmits a command to emulate a single key press on the PiKVM.
**Method**: `POST`
**Route**: `/hid/events/send_key`
**Description**: Transmits a command to emulate a single key press on the PiKVM.
**Query parameters**:
@ -569,7 +614,9 @@ The `POST /hid/events/send_key` handle transmits a command to emulate a single k
**Example of use**:
``` sh
$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/events/send_key?key=Delete
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/events/send_key?key=Delete
```
??? note "Example output"
@ -590,7 +637,11 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/events/send_key?key=
### Send mouse button events
The `POST /hid/events/send_mouse_button` handle sends mouse button press/release events.
**Method**: `POST`
**Route**: `/hid/events/send_mouse_button`
**Description**: Sends mouse button press/release events.
**Query parameters**:
@ -602,7 +653,9 @@ The `POST /hid/events/send_mouse_button` handle sends mouse button press/release
**Example of use**:
``` sh
$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/events/send_mouse_button?button=left
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/events/send_mouse_button?button=left
```
??? note "Example output"
@ -623,7 +676,11 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/events/send_mouse_bu
### Move the mouse pointer
The `POST /hid/events/send_mouse_move` handle moves the mouse pointer to user-defined coordinates where 0,0 is the center of the screen.
**Method**: `POST`
**Route**: `/hid/events/send_mouse_move`
**Description**: Sends a command to move the mouse pointer to user-defined coordinates where 0,0 is the center of the screen.
**Query parameters**:
@ -635,7 +692,9 @@ The `POST /hid/events/send_mouse_move` handle moves the mouse pointer to user-de
**Example of use**:
``` sh
$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/send_mouse_move?to_x=0&to_y=50
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/send_mouse_move?to_x=0&to_y=50
```
??? note "Example output"
@ -656,7 +715,11 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/send_mouse_move?to_x
### Move the mouse ppinter relatively
The `POST /hid/events/send_mouse_relative` handles moves the mouse pointer by a relative offset.
**Method**: `POST`
**Route**: `/hid/events/send_mouse_relative`
**Description**: Sends a command to move the mouse pointer by a relative offset in pixels.
**Query parameters**:
@ -668,7 +731,9 @@ The `POST /hid/events/send_mouse_relative` handles moves the mouse pointer by a
**Example of use**:
``` sh
$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/send_mouse_relative?delta_x=20&delta_y=200
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/send_mouse_relative?delta_x=20&delta_y=200
```
??? note "Example output"
@ -689,7 +754,11 @@ $ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/send_mouse_relative?
### Send mouse wheel scroll events
The `POST /hid/events/send_mouse_wheel` handle sends mouse wheel scroll events to the PiKVM.
**Method**: `POST`
**Route**: `/hid/events/send_mouse_wheel`
**Description**: Sends mouse wheel scroll events to be emulated on the host by PiKVM.
**Query parameters**:
@ -698,10 +767,12 @@ The `POST /hid/events/send_mouse_wheel` handle sends mouse wheel scroll events t
| `delta_x` | integer | required | Horizontal scroll delta | Any negative or positive integer value |
| `delta_y` | integer | required | Vertical scroll delta | Any negative or positive integer value |
**Example of use**: Send mouse wheel scroll events.
**Example of use**: Sends mouse wheel scroll events.
``` sh
$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/send_mouse_wheel?delta_x=0&delta_y=200
$ curl -k -X POST \
-u admin:admin \
https://<pikvm-ip>/api/hid/send_mouse_wheel?delta_x=0&delta_y=200
```
??? note "Example output"
@ -917,6 +988,12 @@ Parameters:
----
## Streamer
The PiKVM Streamer API provides remote access to video stream capture and management functionality of PiKVM devices. It allows users perform the following operations:
- Capture screenshots.
- Perform optical character recognition (OCR) on captured images.
- Monitor the streamer's operational status.
### Get streamer state
**Method**: `GET`
@ -979,7 +1056,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/streamer
| 400 | FIXME |
| 500 | FIXME |
### Take Snapshot
### Take snapshot
**Method**: `GET`
@ -1096,7 +1173,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/streamer/ocr
----
## Switch
This API provides handles to control the [PiKVM Switch](switch.md): get information, set active ports, and control beacons.
The PiKVM Switch API provides handles to control the [PiKVM Switch](switch.md): get information, set active ports, and control beacons.
The API heavily relies on specifying ports on the PiKVM Switch. There are two ways to do that: with continuous numbering or with float numbers. Both options are equally valid and supported.
@ -1109,7 +1186,7 @@ The API heavily relies on specifying ports on the PiKVM Switch. There are two wa
**Route**: `/switch`
**Description**: Return the information about the PiKVM Switch state.
**Description**: Returns the information about the PiKVM Switch state.
**Query parameters**: None.
@ -1138,7 +1215,7 @@ $ curl -k -u admin:admin https://<pikvm-ip>/api/switch
**Route**: `/switch/set_active_prev`
**Description**: Switch to the previous active port.
**Description**: Switches to the previous active port.
**Query parameters**: None.
@ -1169,7 +1246,7 @@ $ curl -k -X POST \
**Route**: `/switch/set_active_next`
**Description**: Switch to the next active port.
**Description**: Switches to the next active port.
**Query parameters**: None.
@ -1200,7 +1277,7 @@ $ curl -k -X POST \
**Route**: `/switch/set_active`
**Description**: Switch to a specific port.
**Description**: Switches to a specific port.
**Query parameters**:
@ -1235,7 +1312,7 @@ $ curl -k -X POST \
**Route**: `/switch/set_beacon`
**Description**: Control beacon lights on ports or uplink/downlink units.
**Description**: Controls beacon lights on ports or uplink/downlink units.
**Query parameters**:
@ -1273,7 +1350,7 @@ $ curl -k -X POST \
**Route**: `/switch/set_port_params`
**Description**: Configure parameters for a specific port.
**Description**: Configures parameters for a specific port.
**Query parameters**:
@ -1314,7 +1391,7 @@ $ curl -k -X POST \
**Route**: `/switch/set_colors`
**Description**: Set the beacon color for the PiKVM Switch and all switches in the downlink (where applicable).
**Description**: Sets the beacon color for the PiKVM Switch and all switches in the downlink (where applicable).
**Query parameters**:
@ -1386,7 +1463,7 @@ $ curl -k -X POST \
**Route**: `/switch/edids/create`
**Description**: Create a new EDID configuration from user-specified EDID name and data.
**Description**: Creates a new EDID configuration from user-specified EDID name and data.
**Query parameters**:
@ -1562,7 +1639,7 @@ $ curl -k -X POST \
| 500 | FIXME |
----
## Redfish API
## Redfish
The PiKVM Redfish API implements the industry-standard [DMTF Redfish specification](https://www.dmtf.org/standards/redfish) for remote server control. It allows you to monitor and control the power of the target system.
@ -1574,7 +1651,7 @@ Most endpoints require authentication using your PiKVM credentials. You can inte
**Route**: `/redfish/v1`
**Description**: Entry point for Redfish service discovery, returns basic service information and links to available resources. Doesn't require authentication.
**Description**: Returns the basic Redfish service information and links to available resources. Doesn't require authentication.
**Query parameters**: None.