9c550a8f9a
Moonraker's external API documentation has been significantly overhauled in an effort to improve clarity and readability. All parameters and responses are documented with specifications. Tables and other elements are used to make documentation more visible and less verbose. Spelling and other corrections have also been added. Signed-off-by: Eric Callahan <arksine.code@gmail.com>
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.
|
|
///
|