zkk 2f184c317d 合并最新内容,适配开门检测机型
# Conflicts:
#	moonraker/components/file_manager/metadata.py   resolved by ada08d4574e13099a392bba4b3ebe34485807c0a version
2025-03-31 11:37:27 +08:00

278 lines
8.0 KiB
Markdown

# Extensions
Moonraker has limited support for 3rd party extensions through the
use of its API. Extensions must establish a Websocket or Unix Socket
connection and [identify](./server.md#identify-connection) themselves
as an `agent`.
The endpoints in this section can be broken down into two categories:
- Endpoints used by Front Ends and other clients to manage and manipulate
extensions.
- Endpoints specific to agents that provide functional enhancements not
available to other client types.
## Extension Management
### List Extensions
Returns a list of all available extensions. Currently Moonraker can only
be officially extended through connected `agents`.
```{.http .apirequest title="HTTP Request"}
GET /server/extensions/list
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.extensions.list",
"id": 4564
}
```
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"agents": [
{
"name": "moonagent",
"version": "0.0.1",
"type": "agent",
"url": "https://github.com/arksine/moontest"
}
]
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| -------- | :------: | --------------------------------------------------- |
| `agents` | [object] | An array of [Agent Info](#agent-info-spec) objects. |
| Field | Type | Description |
| --------- | :----: | -------------------------------------------------- |
| `name` | string | The name provided by the registered agent. |
| `version` | string | The version of the software reported by the agent. |
| `type` | string | The client type. Will always be `agent`. |
| `url` | string | A url to the agent software's webpage. |
{ #agent-info-spec } Agent Info
///
### Call an extension method
This endpoint may be used to call a method on a connected agent.
The request effectively relays a JSON-RPC request from a front end
or other client to the agent. Agents should document their
available methods so Moonraker client developers can interact
with them.
```{.http .apirequest title="HTTP Request"}
POST /server/extensions/request
Content-Type: application/json
{
"agent": "moonagent",
"method": "moontest.hello_world",
"arguments": {"argone": true, "argtwo": 9000}
}
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.extensions.request",
"params":{
"agent": "moonagent",
"method": "moontest.hello_world",
"arguments": {"argone": true, "argtwo": 9000}
},
"id": 4564
}
```
Parameters:
/// api-parameters
open: True
| Name | Type | Default | Description |
| ----------- | :-------------: | ------------ | -------------------------------- |
| `agent` | string | **REQUIRED** | The name of the registered agent |
| | | | hosting the requested method. |^
| `method` | string | **REQUIRED** | The name of the method to call. |
| `arguments` | array \| object | null | The arguments to send with the |
| | | | method. This may be an array |^
| | | | containing positional arguments |^
| | | | or an object containing keyword |^
| | | | arguments. A value of `null` |^
| | | | will omit arguments from the |^
| | | | request. |^
///
/// api-response-spec
open: True
The result received from the agent will be returned directly. See
the agent's documentation for response specifications
///
## Agent specific endpoints
/// Note
These endpoints are only available to connections that have
identified themselves as an `agent` type.
///
### Send an agent event
Sends a [JSON-RPC notification](./jsonrpc_notifications.md#agent-events)
containing the supplied event info to all of Moonraker's persistent
connections.
```{.http .apirequest title="HTTP Request"}
Not Available
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "connection.send_event",
"params":{
"event": "my_event",
"data": {"my_arg": "optional data"}
}
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ------- | :----: | ------------ | -------------------------------------------- |
| `event` | string | **REQUIRED** | The name of the event. This may be any |
| | | | name other than those reserved by Moonraker. |^
| `data` | any | undefined | The data to send with the event. This can be |
| | | | any valid JSON decodable value. If omitted |^
| | | | no data is sent with the event. |^
//// Note
The `connected` and `disconnected` events are reserved for use
by Moonraker and may not be sent from agents.
////
///
```{.apiresponse title="Response when JSON-RPC 'id' present"}
ok
```
/// note
An agent may send an event without specifying the JSON-RPC `id` field.
In this case Moonraker will not return a response.
///
### Register a method with Klipper
Registers a "remote method" with Klipper that can be called
from GCode Macros.
```{.http .apirequest title="HTTP Request"}
Not Available
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "connection.register_remote_method",
"params": {
"method_name": "firemon_alert_heated"
}
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ------------- | :----: | ------------ | --------------------------------------------- |
| `method_name` | string | **REQUIRED** | The name of the remote method to register |
| | | | with Klipper. It is recommended for agents |^
| | | | to use a unique identifier, such as a prefix, |^
| | | | to prevent collisions with other remote |^
| | | | methods registered with Klipper. |^
///
```{.apiresponse title= Response"}
ok
```
/// Note
Methods registered by agents will persist until the agent disconnects.
Upon connection it is only necessary that they register their desired
methods once.
///
#### Remote Method Example
Presume an application named `firemon` has connected to Moonraker's websocket
and identified itself as an `agent`. After identification it registers a
remote method named `firemon_alert_heated` using the JSON-RPC request
example above.
In addition, the user has following `gcode_macro` configured in `printer.cfg`:
```ini
# printer.cfg
[gcode_macro ALERT_HEATED]
gcode:
{% if not params %}
{action_call_remote_method("firemon_alert_heated")}
{% else %}
{% set htr = params.HEATER|default("unknown") %}
{% set tmp = params.TEMP|default(0)|float %}
{action_call_remote_method(
"firemon_alert_heated", heater=htr, temp=tmp)}
{% endif %}
```
When the `ALERT_HEATED HEATER=extruder TEMP=200` gcode is executed by Klipper,
the agent will receive the following JSON-RPC request from Moonraker:
```{.json .apiresponse title="Remote Method Call"}
{
"jsonrpc": "2.0",
"method": "firemon_alert_heated",
"params": {
"heater": "extruder",
"temp": 200
}
}
```
When the `ALERT_HEATED` gcode is executed with no parameters, the agent will
receive the following JSON-RPC request from Moonraker:
```{.json .apiresponse title="Remote Method Call"}
{
"jsonrpc": "2.0",
"method": "monitor_alert_heated"
}
```
/// Note
Remote methods called from Klipper never contain the JSON-RPC "id" field,
as Klipper does not accept return values to remote methods.
///