zkk
2f184c317d
# Conflicts: # moonraker/components/file_manager/metadata.py resolved by ada08d4574e13099a392bba4b3ebe34485807c0a version
278 lines
8.0 KiB
Markdown
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.
|
|
///
|