3diy
/
moonraker
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add new doc structure for peripheral requests 

This adds a new structure for API documentation, making each
aspect visible and uniform.  The parameters, response, and
schema are collapsible, allowing for easier navigation.

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Eric Callahan 2024-01-23 17:37:09 -05:00
parent 931e88b9f0
commit 6ec37fdacc
No known key found for this signature in database
GPG Key ID: 5A1EB336DFB4C71B
2 changed files with 107 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
docs/web_api.md
View File

@ -1697,13 +1697,11 @@ incorrect or if any pending sudo requests fail.
Returns a list of all USB devices currently detected on the system. Returns a list of all USB devices currently detected on the system.
HTTP request: ```http title="HTTP Request"
```http
GET /machine/peripherals/usb GET /machine/peripherals/usb
``` ```
JSON-RPC request: ```json title="JSON-RPC Request"
```json
{ {
"jsonrpc": "2.0", "jsonrpc": "2.0",
"method": "machine.peripherals.usb", "method": "machine.peripherals.usb",
@ -1711,10 +1709,7 @@ JSON-RPC request:
} }
``` ```
Returns: /// api-example-response
An object containing a list of attached USB device info:
```json ```json
{ {
"usb_devices": [ "usb_devices": [
@ -1791,14 +1786,18 @@ An object containing a list of attached USB device info:
] ]
} }
``` ```
///
Response Schema: /// api-response-schema
open: True
Response
| Field | Type | Description | | Field | Type | Description |
| ------------- | :---: | ------------------------------------------------------ | | ------------- | :---: | ------------------------------------------------------ |
| `usb_devices` | array | An array of objects containing USB device information. | | `usb_devices` | array | An array of objects containing USB device information. |
USB Device Schema:
USB Device
| Field | Type | Description | | Field | Type | Description |
| -------------- | :-----: | --------------------------------------------------- | | -------------- | :-----: | --------------------------------------------------- |
@ -1821,19 +1820,18 @@ USB Device Schema:
| `description` | string? | The full device description string as reported by | | `description` | string? | The full device description string as reported by |
| | | the usb.ids file. This will be `null` if no |^ | | | the usb.ids file. This will be `null` if no |^
| | | description is found. |^ | | | description is found. |^
///
#### List Serial Devices #### List Serial Devices
Returns a list of all serial devices detected on the system. These may be USB Returns a list of all serial devices detected on the system. These may be USB
CDC-ACM devices or hardware UARTs. CDC-ACM devices or hardware UARTs.
HTTP request: ```http title="HTTP Request"
```http
GET /machine/peripherals/serial GET /machine/peripherals/serial
``` ```
JSON-RPC request: ```json title="JSON-RPC Request"
```json
{ {
"jsonrpc": "2.0", "jsonrpc": "2.0",
"method": "machine.peripherals.serial", "method": "machine.peripherals.serial",
@ -1841,8 +1839,7 @@ JSON-RPC request:
} }
``` ```
Returns: /// api-example-response
```json ```json
{ {
"serial_devices": [ "serial_devices": [
@ -1885,30 +1882,35 @@ Returns:
] ]
} }
``` ```
///
Response Schema: /// api-response-schema
open: True
Response
| Field | Type | Description | | Field | Type | Description |
| ---------------- | ----- | --------------------------------------------------------- | | ---------------- | ----- | --------------------------------------------------------- |
| `serial_devices` | array | An array of objects containing serial device information. | | `serial_devices` | array | An array of objects containing serial device information. |
Serial Device Schema: Serial Device
| Field | Type | Description |
| ------------------ | :-----: | ------------------------------------------------------------------- |
| `device_type` | string | The type of serial device. Can be `hardware_uart` or `usb`. |
| `device_path` | string | The absolute file path to the device. |
| `device_name` | string | The device file name as reported by sysfs. |
| `driver_name` | string | The name of the device driver. |
| `path_by_hardware` | string? | A symbolic link to the device based on its physical connection, |
| | | ie: usb port. Will be `null` if no matching link exists. |^
| `path_by_id` | string? | A symbolic link the the device based on its reported IDs. Will be |
| | | `null` if no matching link exists. |^
| `usb_location` | string? | An identifier derived from the reported usb bus and device numbers. |
| | | Can be used to match results from `/machine/peripherals/usb`. Will |^
| | | be `null` for non-usb devices. |^
| Field | Type | Description |
| ------------------ | :-----: | ----------------------------------------------------------- |
| `device_type` | string | The type of serial device. Can be `hardware_uart` or `usb`. |
| `device_path` | string | The absolute file path to the device. |
| `device_name` | string | The device file name as reported by sysfs. |
| `driver_name` | string | The name of the device driver. |
| `path_by_hardware` | string? | A symbolic link to the device based on its physical |
| | | connection, ie: usb port. Will be `null` if no |^
| | | matching link exists. |^
| `path_by_id` | string? | A symbolic link the the device based on its reported IDs. |
| | | Will be `null` if no matching link exists. |^
| `usb_location` | string? | An identifier derived from the reported usb bus and . |
| | | device numbers Can be used to match results from |^
| | | `/machine/peripherals/usb`. Will be `null` for non-usb |^
| | | devices. |^
///
#### List Video Capture Devices #### List Video Capture Devices
@ -1916,12 +1918,11 @@ Retrieves a list of V4L2 video capture devices on the system. If
the python3-libcamera system package is installed this request will the python3-libcamera system package is installed this request will
also return libcamera devices. also return libcamera devices.
```http ```http title="HTTP Request"
GET /machine/peripherals/video GET /machine/peripherals/video
``` ```
JSON-RPC request: ```json title="JSON-RPC Request"
```json
{ {
"jsonrpc": "2.0", "jsonrpc": "2.0",
"method": "machine.peripherals.video", "method": "machine.peripherals.video",
@ -1929,8 +1930,7 @@ JSON-RPC request:
} }
``` ```
Returns: /// api-example-response
```json ```json
{ {
"v4l2_devices": [ "v4l2_devices": [
@ -2112,15 +2112,18 @@ Returns:
] ]
} }
``` ```
///
Response Schema: /// api-response-schema
open: True
Response
| Field | Type | Description | | Field | Type | Description |
| ------------------- | :---: | ------------------------------------- | | ------------------- | :---: | ------------------------------------- |
| `v4l2_devices` | array | An array of V4L2 Device objects. | | `v4l2_devices` | array | An array of V4L2 Device objects. |
| `libcamera_devices` | array | An array of Libcamera Device objects. | | `libcamera_devices` | array | An array of Libcamera Device objects. |
V4L2 Device Schema: V4L2 Device
| Field | Type | Description | | Field | Type | Description |
| ------------------ | :-----: | -------------------------------------------------------- | | ------------------ | :-----: | -------------------------------------------------------- |
@ -2143,7 +2146,7 @@ V4L2 Device Schema:
| `usb_location` | string? | An identifier derived from the reported usb bus and | | `usb_location` | string? | An identifier derived from the reported usb bus and |
| | | device numbers. Will be `null` for non-usb devices. |^ | | | device numbers. Will be `null` for non-usb devices. |^
Libcamera Device Schema: Libcamera Device
| Field | Type | Description | | Field | Type | Description |
| -------------- | :----: | ------------------------------------------------------- | | -------------- | :----: | ------------------------------------------------------- |
@ -2152,13 +2155,14 @@ Libcamera Device Schema:
| `modes` | array | An array of `Libcamera Mode` objects, each describing a | | `modes` | array | An array of `Libcamera Mode` objects, each describing a |
| | | mode supported by the device. |^ | | | mode supported by the device. |^
Libcamera Mode Schema: Libcamera Mode
| Field | Type | Description | | Field | Type | Description |
| ------------- | :----: | ----------------------------------------------------------- | | ------------- | :----: | ----------------------------------------------------------- |
| `format` | string | The pixel format of the mode. | | `format` | string | The pixel format of the mode. |
| `resolutions` | array | An array of strings describing the resolutions supported by | | `resolutions` | array | An array of strings describing the resolutions supported by |
| | | the mode. Each entry is reported as `<WIDTH>x<HEIGHT>` |^ | | | the mode. Each entry is reported as `<WIDTH>x<HEIGHT>` |^
///
#### Query Unassigned Canbus UUIDs #### Query Unassigned Canbus UUIDs
@ -2186,13 +2190,11 @@ node IDs.
query multiple unassigned nodes it is vital that they reset all nodes query multiple unassigned nodes it is vital that they reset all nodes
on the network before running Klipper. on the network before running Klipper.
HTTP Request: ```http title="HTTP Request"
```http
GET /machine/peripherals/canbus?interface=can0 GET /machine/peripherals/canbus?interface=can0
``` ```
JSON-RPC request: ```json title="JSON-RPC Request"
```json
{ {
"jsonrpc": "2.0", "jsonrpc": "2.0",
"method": "machine.peripherals.canbus", "method": "machine.peripherals.canbus",
@ -2203,26 +2205,38 @@ JSON-RPC request:
} }
``` ```
Parameters: /// api-parameters
open: True
| Name | Type | Description | | Name | Type | Description |
| ----------- | :----: | ----------------------------------------------------- | | ----------- | :----: | ----------------------------------------------------- |
| `interface` | string | The cansocket interface to query. Default is `can0`. | | `interface` | string | The cansocket interface to query. Default is `can0`. |
///
Returns: /// api-example-response
```json ```json
{ {
"can_uuids": ["11AABBCCDD"] "can_uuids": ["11AABBCCDD"]
} }
``` ```
///
Response Schema: /// api-response-schema
open: True
Response
| Field | Type | Description | | Field | Type | Description |
| ----------- | :---: | --------------------------------------------------------- | | ----------- | :---: | ---------------------------------------------------------------- |
| `can_uuids` | array | An array of discovered UUIDs as strings. If no UUIDS are | | `can_uuids` | array | An array of discovered CAN UUID objects, or an empty array if no |
| | | found the result is an empty array. |^ | | | unassigned CAN nodes are found. |^
Can UUID
| Field | Type | Description |
| ------------- | :----: | ----------------------------------------------------------- |
| `uuid` | string | The UUID of the unassigned node. |
| `application` | string | The name of the application running on the unassigned Node. |
| | | Should be "Klipper" or "Katapult". |^
///
### File Operations ### File Operations

39
mkdocs.yml
View File

@ -71,6 +71,45 @@ markdown_extensions:
- pymdownx.tasklist: - pymdownx.tasklist:
custom_checkbox: true custom_checkbox: true
- pymdownx.tilde - pymdownx.tilde
- pymdownx.blocks.details:
types:
- name: details-new
class: new
- name: details-settings
class: settings
- name: details-note
class: note
- name: details-abstract
class: abstract
- name: details-info
class: info
- name: details-tip
class: tip
- name: details-success
class: success
- name: details-question
class: question
- name: details-warning
class: warning
- name: details-failure
class: failure
- name: details-danger
class: danger
- name: details-bug
class: bug
- name: details-example
class: example
- name: details-quote
class: quote
- name: api-example-response
class: example
title: "Example Response"
- name: api-response-schema
class: info
title: "Response Schema"
- name: api-parameters
class: info
title: "Parameters"
- tables - tables
- compact_tables: - compact_tables:
auto_insert_break: true auto_insert_break: true