Eric Callahan 35cb7501c6 docs: update analysis and metadata docs

Signed-off-by:  Eric Callahan

2025-02-17 15:32:45 -05:00

52 KiB

Raw Blame History

JSON-RPC notifications

Persistent connections to Moonraker (websocket, unix socket) will receive asynchronous via JSON-RPC notifications. A "notification" in JSON-RPC is a method call without an id parameter, for example:

{
    "jsonrpc": "2.0",
    "method": "{notification method name}"
}

OR with parameters:

{
    "jsonrpc": "2.0",
    "method": "{notification method name}",
    "params": [true, "pos_param_2", {"obj": "stuff"}]
}

To keep consistency Moonraker always sends parameters as positional arguments. Specifically, the params field will always contain an array. This can often lead to a somewhat strange format where the params field contains a single element array, where the element is an object.

All of the notifications sent by Moonraker are outlined in this document.

Gcode Responses

Gcode Responses received from Klipper are broadcast to all persistent connections. All of Klippy's gcode responses are forwarded over the websocket.

notify_gcode_response

{
    "jsonrpc": "2.0",
    "method": "notify_gcode_response",
    "params": ["response message"]
}

/// api-notification-spec open: True

Pos	Type	Description
0	string	The gcode response message.

///

Subscription Updates

Klipper object subscription data received as a result of invoking the subscribe endpoint.

notify_status_update

{
    "jsonrpc": "2.0",
    "method": "notify_status_update",
    "params": [
        {
            "gcode_move": {
                "speed": 1500,
            },
            "toolhead": {
                "status": "Ready"
            }
        },
        578243.57824499
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	An object containing changes to subscribed
		Klipper objects. Each key is the name of a
		printer object, each value will be an object
		containing fields that have changed since
		the last update.
1	float	A timestamp indicating the time the subscription
		data was sent. This time is relative to the
		monotonic clock used by Klipper.

///

/// Tip See Klipper's status reference for details on printer objects and the fields they report. ///

Klippy Ready

Indicates that the Klippy Host has entered the ready state.

notify_klippy_ready

{
    "jsonrpc": "2.0",
    "method": "notify_klippy_ready"
}

Klippy Shutdown

Indicates that the Klippy Host has entered the shutdown state.

notify_klippy_shutdown

{
    "jsonrpc": "2.0",
    "method": "notify_klippy_shutdown"
}

Klippy Disconnected

Indicates that Moonraker's connection to Klippy has terminated.

notify_klippy_disconnected

{
    "jsonrpc": "2.0",
    "method": "notify_klippy_disconnected"
}

File List Changed

Moonraker's file_manager will emit notifications when a change to one of its watched root directories is detected. This includes changes to files and subdirectories within the root.

notify_filelist_changed

{
    "jsonrpc": "2.0",
    "method": "notify_filelist_changed",
    "params": [
        {
            "item": {
                "root": "gcodes",
                "path": "subdir/my_file.gcode",
                "modified": 1676940082.8595376,
                "size": 384096,
                "permissions": "rw"
            },
            "source_item": {
                "path": "testdir/my_file.gcode",
                "root": "gcodes"
            },
            "action": "move_file"
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	A Changed Item Info object.

Field	Type	Description
`action`	string	The action
		that caused the notification.
`item`	object	The `destination item` affected by the change.
		#dest-item-info-spec
`source_item`	object	The `source item` affected by the change. Only
		present for `move_file` and `move_dir` actions.
		#source-item-info-spec
{ #fileinfo-changed-spec } Changed Item Info

Field	Type	Description
`path`	string	The path of the destination item relative to
		the root directory.
`root`	string	The root node of the destination item.
`modified`	float	The last modified date in Unix Time (seconds).
`size`	int	The size of the destination item.
`permissions`	string	Permissions available on the changed item
		(if applicable).
{ #dest-item-info-spec } Destination Item Info

Field	Type	Description
`path`	string	The path of the source item relative to
		the root directory.
`root`	string	The root node of the source item.
{ #source-item-info-spec } Source Item Info

Action	Description
`create_file`	A file has been created within the watched root.
`create_dir`	A subdirectory has been created within the watched root.
`delete_file`	A file has been deleted within the watched root.
`delete_dir`	A subdirectory has been deleted within the watched root.
`move_file`	A file in a watched root has been moved.
`move_dir`	A subdirectory in a watched root has been moved.
`modify_file`	A file in a watched root has been modified.
`root_update`	A root folder's location on disk has changed.
{ #filelist-changed-action-desc } Filelist Changed Action

///

/// tip Notifications are bundled where applicable. For example, when a directory containing children is deleted a single delete_dir notification is pushed. Likewise, when a directory is moved or copied, a single move_dir or create_dir notification is pushed. Children that are moved, copied, or deleted as a result of a parent's action will not receive individual notifications. ///

Update Manager Response

While the update_manager is in the process of updating one or more registered software items, it will emit notifications containing information about the current status of the update.

notify_update_response

{
    "jsonrpc": "2.0",
    "method": "notify_update_response",
    "params": [
        {
            "application": "{app_name}",
            "proc_id": 446461,
            "message": "Update Response Message",
            "complete": false
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	An update manager notification status object.

Field	Type	Description
`application`	string	The name of the software currently updating.
`proc_id`	int	A unique ID associated with the current update.
`message`	message	A message containing status and/or information
		about the current update.
`complete`	bool	When set to `true` it indicates that the update
		has finished and this will be the last status
		response notification sent for this update.

///

Update Manager Refreshed

After the update manager has performed a refresh of the registered software update state it will send a notification to all connections containing the complete current status.

notify_update_refreshed

/// collapse-code

{
    "jsonrpc": "2.0",
    "method": "notify_update_refreshed",
    "params": [
        {
            "busy": false,
            "github_rate_limit": 60,
            "github_requests_remaining": 57,
            "github_limit_reset_time": 1615836932,
            "version_info": {
                "system": {
                    "name": "system",
                    "configured_type": "system",
                    "package_count": 4,
                    "package_list": [
                        "libtiff5",
                        "raspberrypi-sys-mods",
                        "rpi-eeprom-images",
                        "rpi-eeprom"
                    ]
                },
                "moonraker": {
                    "channel": "dev",
                    "debug_enabled": true,
                    "is_valid": true,
                    "configured_type": "git_repo",
                    "corrupt": false,
                    "info_tags": [],
                    "detected_type": "git_repo",
                    "name": "moonraker",
                    "remote_alias": "arksine",
                    "branch": "master",
                    "owner": "arksine",
                    "repo_name": "moonraker",
                    "version": "v0.7.1-364",
                    "remote_version": "v0.7.1-364",
                    "rollback_version": "v0.7.1-360",
                    "current_hash": "ecfad5cff15fff1d82cb9bdc64d6b548ed53dfaf",
                    "remote_hash": "ecfad5cff15fff1d82cb9bdc64d6b548ed53dfaf",
                    "is_dirty": false,
                    "detached": true,
                    "commits_behind": [],
                    "git_messages": [],
                    "full_version_string": "v0.7.1-364-gecfad5c",
                    "pristine": true,
                    "recovery_url": "https://github.com/Arksine/moonraker.git",
                    "remote_url": "https://github.com/Arksine/moonraker.git",
                    "warnings": [],
                    "anomalies": [
                        "Unofficial remote url: https://github.com/Arksine/moonraker-fork.git",
                        "Repo not on official remote/branch, expected: origin/master, detected: altremote/altbranch",
                        "Detached HEAD detected"
                    ]
                },
                "mainsail": {
                    "name": "mainsail",
                    "owner": "mainsail-crew",
                    "version": "v2.1.1",
                    "remote_version": "v2.1.1",
                    "rollback_version": "v2.0.0",
                    "configured_type": "web",
                    "channel": "stable",
                    "info_tags": [
                        "desc=Mainsail Web Client",
                        "action=some_action"
                    ],
                    "warnings": [],
                    "anomalies": [],
                    "is_valid": true
                },
                "fluidd": {
                    "name": "fluidd",
                    "owner": "fluidd-core",
                    "version": "v1.16.2",
                    "remote_version": "v1.16.2",
                    "rollback_version": "v1.15.0",
                    "configured_type": "web",
                    "channel": "beta",
                    "info_tags": [],
                    "warnings": [],
                    "anomalies": [],
                    "is_valid": true
                },
                "klipper": {
                    "channel": "dev",
                    "debug_enabled": true,
                    "is_valid": true,
                    "configured_type": "git_repo",
                    "corrupt": false,
                    "info_tags": [],
                    "detected_type": "git_repo",
                    "name": "klipper",
                    "remote_alias": "origin",
                    "branch": "master",
                    "owner": "Klipper3d",
                    "repo_name": "klipper",
                    "version": "v0.10.0-1",
                    "remote_version": "v0.10.0-41",
                    "rollback_version": "v0.9.1-340",
                    "current_hash": "4c8d24ae03eadf3fc5a28efb1209ce810251d02d",
                    "remote_hash": "e3cbe7ea3663a8cd10207a9aecc4e5458aeb1f1f",
                    "is_dirty": false,
                    "detached": false,
                    "commits_behind": [
                        {
                            "sha": "e3cbe7ea3663a8cd10207a9aecc4e5458aeb1f1f",
                            "author": "Kevin O'Connor",
                            "date": "1644534721",
                            "subject": "stm32: Clear SPE flag on a change to SPI CR1 register",
                            "message": "The stm32 specs indicate that the SPE bit must be cleared before\nchanging the CPHA or CPOL bits.\n\nReported by @cbc02009 and @bigtreetech.\n\nSigned-off-by: Kevin O'Connor <kevin@koconnor.net>",
                            "tag": null
                        },
                        {
                            "sha": "99d55185a21703611b862f6ce4b80bba70a9c4b5",
                            "author": "Kevin O'Connor",
                            "date": "1644532075",
                            "subject": "stm32: Wait for transmission to complete before returning from spi_transfer()",
                            "message": "It's possible for the SCLK pin to still be updating even after the\nlast byte of data has been read from the receive pin.  (In particular\nin spi mode 0 and 1.)  Exiting early from spi_transfer() in this case\ncould result in the CS pin being raised before the final updates to\nSCLK pin.\n\nAdd an additional wait at the end of spi_transfer() to avoid this\nissue.\n\nSigned-off-by: Kevin O'Connor <kevin@koconnor.net>",
                            "tag": null
                        }
                    ],
                    "git_messages": [],
                    "full_version_string": "v0.10.0-1-g4c8d24ae-shallow",
                    "pristine": true,
                    "recovery_url": "https://github.com/Klipper3d/klipper.git",
                    "remote_url": "https://github.com/Klipper3d/klipper.git",
                    "warnings": [],
                    "anomalies": []
                }
            }
        }
    ]
}

///

/// api-notification-spec open: True

Pos	Type	Description
0	object	An Update Status Info
		object.

///

CPU Throttled

If the system supports CPU monitoring via vcgencmd Moonraker will emit notifications when the CPU's throttled state changes.

notify_cpu_throttled

{
    "jsonrpc": "2.0",
    "method": "notify_cpu_throttled",
    "params": [
        {
            "bits": 0,
            "flags": []
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	A CPU Throttled State object.

Field	Type	Description
`bits`	int	The current throttled state as an integer. A bitwise AND
		can be performed against this value to generate custom flag
		descriptions.
`flags`	[string]	A list of `Throttled Flags` describing the current state.
		#throttled-flags-desc
{ #throttled-state-spec } Throttled State

Flag	Bit Offset
Under-Voltage Detected	`1 << 0`
Frequency Capped	`1 << 1`
Currently Throttled	`1 << 2`
Temperature Limit Active	`1 << 3`
Previously Under-Volted	`1 << 16`
Previously Frequency Capped	`1 << 17`
Previously Throttled	`1 << 18`
Previously Temperature Limited	`1 << 16`
{ #throttled-flags-desc } Throttled Flags
///

/// note It is possible for clients to receive this notification multiple times if the system repeatedly transitions between an active and inactive throttled condition. ///

Moonraker Process Statistic Update

Moonraker performs live monitoring of host machine data and periodically emits a notification with the most recent statistics.

notify_proc_stat_update

/// collapse-code

{
    "jsonrpc": "2.0",
    "method": "notify_proc_stat_update",
    "params": [
        {
            "moonraker_stats": {
                "time": 1615837812.0894408,
                "cpu_usage": 1.99,
                "memory": 23636,
                "mem_units": "kB"
            },
            "cpu_temp": 44.008,
            "network": {
                "lo": {
                    "rx_bytes": 114555457,
                    "tx_bytes": 114555457,
                    "bandwidth": 2911.49
                },
                "wlan0": {
                    "rx_bytes": 48773134,
                    "tx_bytes": 115035939,
                    "bandwidth": 3458.77
                }
            },
            "system_cpu_usage": {
                "cpu": 2.53,
                "cpu0": 3.03,
                "cpu1": 5.1,
                "cpu2": 1.02,
                "cpu3": 1
            },
            "websocket_connections": 2
        }
    ]
}

///

/// api-notification-spec open: True

Pos	Type	Description
0	object	A proc stats response
		object. The `throttled_state` and `system_uptime` fields are
		omitted from the notification.

///

History Changed

When Moonraker's [history] component detects a new or completed job a notification will be emitted.

notify_history_changed

/// collapse-code

{
    "jsonrpc": "2.0",
    "method": "notify_history_changed",
    "params": [
        {
            "action": "added",
            "job": {
                "end_time": null,
                "filament_used": 20.09796999999998,
                "filename": "calicat_0.3mm_PLA_MK3S_33m.gcode",
                "metadata": {
                    "size": 538254,
                    "modified": 1646770808,
                    "uuid": "4022d6bd-e5f5-45d7-84af-f38bcc57a5d3",
                    "file processors": [],
                    "slicer": "PrusaSlicer",
                    "slicer_version": "2.4.0+linux-x64-GTK3",
                    "gcode_start_byte": 51238,
                    "gcode_end_byte": 528796,
                    "object_height": 34.4,
                    "estimated_time": 1954,
                    "nozzle_diameter": 0.4,
                    "layer_height": 0.3,
                    "first_layer_height": 0.2,
                    "first_layer_extr_temp": 225,
                    "first_layer_bed_temp": 60,
                    "filament_name": "Fusion PLA Carbon Rod Black",
                    "filament_type": "PLA",
                    "filament_total": 1754.96,
                    "filament_weight_total": 5.23,
                    "thumbnails": [
                        {
                            "width": 32,
                            "height": 24,
                            "size": 1829,
                            "relative_path": ".thumbs/calicat_0.3mm_PLA_MK3S_33m-32x32.png"
                        },
                        {
                            "width": 400,
                            "height": 300,
                            "size": 36586,
                            "relative_path": ".thumbs/calicat_0.3mm_PLA_MK3S_33m-400x300.png"
                        }
                    ]
                },
                "print_duration": 0.911540990229696,
                "status": "in_progress",
                "start_time": 1738671939.433274,
                "total_duration": 0.911540990229696,
                "auxiliary_data": [
                    {
                        "provider": "sensor hist_test",
                        "name": "power_consumption",
                        "value": 0,
                        "description": "Printer Power Consumption",
                        "units": "kWh"
                    },
                    {
                        "provider": "sensor hist_test",
                        "name": "max_current",
                        "value": 0,
                        "description": "Maximum current draw",
                        "units": "A"
                    },
                    {
                        "provider": "sensor hist_test",
                        "name": "min_current",
                        "value": 0,
                        "description": "Maximum current draw",
                        "units": "A"
                    },
                    {
                        "provider": "sensor hist_test",
                        "name": "avg_current",
                        "value": 0,
                        "description": "Maximum current draw",
                        "units": "A"
                    },
                    {
                        "provider": "sensor hist_test",
                        "name": "status",
                        "value": null,
                        "description": "Power Switch State",
                        "units": null
                    },
                    {
                        "provider": "sensor hist_test",
                        "name": "id",
                        "value": [],
                        "description": "Test ID",
                        "units": null
                    },
                    {
                        "provider": "sensor hist_test",
                        "name": "filament",
                        "value": 0,
                        "description": "filament tracker",
                        "units": "mm"
                    },
                    {
                        "provider": "spoolman",
                        "name": "spool_ids",
                        "value": [
                            1
                        ],
                        "description": "Spool IDs used",
                        "units": null
                    }
                ],
                "user": "testuser",
                "exists": true,
                "job_id": "000027"
            }
        }
    ]
}

///

/// api-notification-spec open: True

Pos	Type	Description
0	object	A Job History Notification object.

Field	Type	Description
`action`	string	The `action` that triggered the notification.
		#job-hist-notify-action
`job`	string	A Job History Entry
		object.
{ #job-hist-notify-spec } Job History Notification

Action	Description
`added`	A new job was added to the job history.
`finished`	A running job was completed. This includes
	jobs successfully completed, cancelled jobs,
	and jobs that encountered an error.
{ #job-hist-notify-action } Job History Notify Action

///

Authorized User Created

Moonraker's [authorization] component will emit a notification when a new user entry has been created.

notify_user_created

{
    "jsonrpc": "2.0",
    "method": "notify_user_created",
    "params": [
        {
            "username": "Eric"
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	An Auth Notification object.

Field	Type	Description
`username`	string	The username of the user entry associated with
		the notification.
{ #auth-notification-spec } Auth Notification

///

Authorized User Deleted

Moonraker's [authorization] component will emit a notification when an existing user entry has been deleted.

notify_user_deleted

{
    "jsonrpc": "2.0",
    "method": "notify_user_deleted",
    "params": [
        {
            "username": "Eric"
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	An Auth Notification object.

///

Authorized User Logged Out

Moonraker's [authorization] component will emit a notification when a user has logged out.

notify_user_logged_out

{
    "jsonrpc": "2.0",
    "method": "notify_user_logged_out",
    "params": [
        {
            "username": "Eric"
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	An Auth Notification object.

///

Service State Changed

If Moonraker's [machine] component is configured with its systemd integration enabled it will monitor the state of various systemd services. When a change is detected in service state Moonraker will emit a notification.

notify_service_state_changed

{
    "jsonrpc": "2.0",
    "method": "notify_service_state_changed",
    "params": [
        {
            "klipper": {
                "active_state": "inactive",
                "sub_state": "dead"
            }
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	A Service State Notification
		object.

Field	Type	Description
service_name	object	A Unit Status object. The key
		for this field is the service name.
		#unit-status-spec
{ #service-state-notify-spec } Service State Notification

Field	Type	Description
`active_state`	string	The new `ACTIVE` state reported by the provider for the service.
`sub_state`	string	The new `SUB` state reported by the provider for the service.
{ #unit-status-spec } Unit Status

///

Job Queue Changed

Moonraker's [job_queue] component emits a notification when the job queue state changes and when the queue is modified.

notify_job_queue_changed

{
    "jsonrpc": "2.0",
    "method": "notify_job_queue_changed",
    "params": [
        {
            "action": "state_changed",
            "updated_queue": null,
            "queue_state": "paused"
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	A Job Queue Notification
		object.

Field	Type	Description
`action`	string	The action that
		triggered the notification.
`queue_state`	string	The current queue
		state.
`updated_queue`	[object] \| null	An array of `Queued Job` objects reflecting
		the updated queue. Will be `null` if the
		queue has not changed.
		#queued-job-spec
{ #job-queue-notification-spec }

Field	Type	Description
`filename`	string	The name of the gcode file queued.
`job_id`	string	A unique ID assigned to the queued job.
`time_added`	float	The time (in Unix Time) the job was added to the queue.
`time_in_queue`	float	The cumulative amount of time, in seconds, the job has
		been pending in the queue.
{ #queued-job-spec } Queued Job

Action	Description
`state_changed`	The internal job queue state has changed.
`jobs_added`	One or more jobs have been added to the queue.
`jobs_removed`	One or more jobs have been removed from the queue.
`job_loaded`	A job has been popped from the queue and successfully
	started.
{ #job-queue-notify-action } Job Queue Notification Action

///

Button Event

Moonraker [button] component supports optional notifications sent when a button is pressed and/or released.

notify_button_event

{
    "jsonrpc": "2.0",
    "method": "notify_button_event",
    "params": [
        {
            "name": "my_button",
            "type": "gpio",
            "event": {
                "elapsed_time": 0.09323832602240145,
                "received_time": 698614.214597004,
                "render_time": 698614.214728513,
                "pressed": false
            },
            "aux": null
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	A Button Notification object.

Field	Type	Description
`name`	string	The name of the button sending the event.
`type`	string	The configured type of the button. Currently
		only the `gpio` type is supported.
`event`	object	A `Button Event` object.
		#button-event-spec
`aux`	any	Auxiliary data attached to the event. Can be
		any JSON encodable type. If no aux data is
		sent with the event the value will be `null`
{#button-notify-spec} Button Notification

Field	Type	Description
`elapsed_time`	float	The time elapsed (in seconds) since the
		last detected button event.
`received_time`	float	The time the event was detected relative
		to Moonraker's monotonic clock.
`render_time`	float	The time the button's template started
		rendering relative to Moonraker's monotonic
		clock.
`pressed`	bool	Set to `true` if the button is pressed.
{ #button-event-spec } Button Event
///

Announcement update event

Moonraker's [announcements] component will emit a notification when announcement entries are added or removed.

notify_announcement_update

/// collapse-code

{
    "jsonrpc": "2.0",
    "method": "notify_announcement_update",
    "params": [
        {
            "entries": [
                {
                    "entry_id": "arksine/moonlight/issue/3",
                    "url": "https://github.com/Arksine/moonlight/issues/3",
                    "title": "Test announcement 3",
                    "description": "Test Description [with a link](https://moonraker.readthedocs.io).",
                    "priority": "normal",
                    "date": 1647459219,
                    "dismissed": false,
                    "date_dismissed": null,
                    "dismiss_wake": null,
                    "source": "moonlight",
                    "feed": "moonlight"
                },
                {
                    "entry_id": "arksine/moonlight/issue/2",
                    "url": "https://github.com/Arksine/moonlight/issues/2",
                    "title": "Announcement Test Two",
                    "description": "This is a high priority announcement. This line is included in the description.",
                    "priority": "high",
                    "date": 1646855579,
                    "dismissed": false,
                    "date_dismissed": null,
                    "dismiss_wake": null,
                    "source": "moonlight",
                    "feed": "moonlight"
                }
                {
                    "entry_id": "arksine/moonraker/issue/349",
                    "url": "https://github.com/Arksine/moonraker/issues/349",
                    "title": "PolicyKit warnings; unable to manage services, restart system, or update packages",
                    "description": "This announcement is an effort to get ahead of a coming change that will certainly result in issues.  PR #346  has been merged, and with it are some changes to Moonraker's default behavior.",
                    "priority": "normal",
                    "date": 1643392406,
                    "dismissed": false,
                    "source": "moonlight",
                    "feed": "Moonraker"
                }
            ]
        }
    ]
}

///

/// api-notification-spec open: True

Pos	Type	Description
0	object	An Announcement Notification
		object.

Field	Type	Description
`entries`	[object]	An array of
		Announcement Entry
		objects.
{ #announcement-notify-spec } Announcement Notification

///

Announcement dismissed event

Moonraker's [announcements] component will emit a notification when an announcement is dismissed.

notify_announcement_dismissed

{
    "jsonrpc": "2.0",
    "method": "notify_announcement_dismissed",
    "params": [
        {
            "entry_id": "arksine/moonlight/issue/3"
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	An Announcement Dismissed Notification
		object.

Field	Type	Description
`entry_id`	string	The unique entry ID of the dismissed announcement.
{ #announcement-dismissed-notify-desc} Announcement Dismissed Notification

///

Announcement wake event

Moonraker's [announcements] component will emit a notification when an announcement "wakes" from a dismissed state.

notify_announcement_wake

{
    "jsonrpc": "2.0",
    "method": "notify_announcement_wake",
    "params": [
        {
            "entry_id": "arksine/moonlight/issue/1"
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	An Announcement Wake Notification
		object.

Field	Type	Description
`entry_id`	string	The unique entry ID of the awoken announcement.
		The announcement's `dismissed` field will
		be set to `false`.
{ #announcement-wake-notify-desc} Announcement Wake Notification

///

Sudo alert event

At times Moonraker may require sudo permission to perform a specific task. This is rare and generally involves an upgrade (ie: Moonraker's systemd service file needs to be modified). When Moonraker runs a command that requires sudo permission an alert will be sent via notification.

Pending sudo requests that cannot be executed until the user sets their sudo password will also emit a notification.

notify_sudo_alert

{
    "jsonrpc": "2.0",
    "method": "notify_sudo_alert",
    "params": [
        {
            "sudo_requested": true,
            "sudo_messages": [
                "Sudo password required to update Moonraker's systemd service."
            ]
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	A Sudo Alert Notification object

Pos	Type	Description
`sudo_requested`	bool	When `true` there are pending tasks that
		require super user permission.
`sudo_messages`	[string]	An array of messages describing the action
		or actions requiring sudo permission.
{ #sudo-alert-notify-spec} Sudo Alert Notification

//// note Each sudo message can fall into one of the following categories:

An explanation of a pending sudo request.
A response from a task that successfully ran with sudo permissions.
A response from a task that returned an error. ////

///

Webcams changed event

Moonraker's [webcam] component will send a notification when a webcam is added, removed, or updated.

notify_webcams_changed

/// collapse-code

{
    "jsonrpc": "2.0",
    "method": "notify_webcams_changed",
    "params": [
        {
            "webcams": [
                {
                    "name": "tc2",
                    "location": "printer",
                    "service": "mjpegstreamer",
                    "enabled": true,
                    "icon": "mdiWebcam",
                    "target_fps": 15,
                    "target_fps_idle": 5,
                    "stream_url": "http://printer.lan/webcam?action=stream",
                    "snapshot_url": "http://printer.lan/webcam?action=snapshot",
                    "flip_horizontal": false,
                    "flip_vertical": false,
                    "rotation": 0,
                    "aspect_ratio": "4:3",
                    "extra_data": {},
                    "source": "database"
                },
                {
                    "name": "TestCam",
                    "location": "printer",
                    "service": "mjpegstreamer",
                    "enabled": true,
                    "icon": "mdiWebcam",
                    "target_fps": 15,
                    "target_fps_idle": 5,
                    "stream_url": "/webcam/?action=stream",
                    "snapshot_url": "/webcam/?action=snapshot",
                    "flip_horizontal": false,
                    "flip_vertical": false,
                    "rotation": 0,
                    "aspect_ratio": "4:3",
                    "extra_data": {},
                    "source": "database"
                }
            ]
        }
    ]
}

///

/// api-notification-spec open: True

Pos	Type	Description
0	object	A Webcam Notification object.

Field	Type	Description
`webcams`	[object]	An array of Webcam Entry
		objects.
{ #webcam-notify-spec } Webcam Notification

///

Spoolman active spool ID changed

Moonraker's [spoolman] component will emit a notification when the current active spool ID has changed.

notify_active_spool_set

{
    "jsonrpc": "2.0",
    "method": "notify_active_spool_set",
    "params": [
        {
            "spool_id": 1
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	An Active Spool Set Notification
		object.

Field	Type	Description
`spool_id`	int \| null	The spool ID of the new active spool. A
		value of `null` indicates that no active
		spool is set and tracking is disabled.
{ #spoolman-active-spool-notify-spec } Active Spool Set Notification

///

Spoolman Status Changed

Moonraker's [spoolman] component holds a persistent websocket connection to the server. This allow Moonraker to remain aware of the server's status. Moonraker will emit a notification when the connection status to Spoolman changes.

notify_spoolman_status_changed

{
    "jsonrpc": "2.0",
    "method": "notify_spoolman_status_changed",
    "params": [
        {
            "spoolman_connected": false
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	A Spoolman Status Notification
		object.

Field	Type	Description
`spoolman_connected`	bool	A value of `true` indicates that Moonraker is
		currently connected to the Spoolman Server.
{ #spoolman-status-notify-spec } Spoolman Status Notification

///

Agent Events

Moonraker has limited support for third party extensions through client connections that identify themselves as agents. Agents are granted access to additional endpoints that allow them to extend Moonraker's functionality. One such method allows agents to send events that are broadcast to all of Moonraker's connected clients. Moonraker proxies agent events through a notification.

notify_agent_event

{
    "jsonrpc": "2.0",
    "method": "notify_agent_event",
    "params": [
        {
            "agent": "moonagent",
            "event": "connected",
            "data": {
                "name": "moonagent",
                "version": "0.0.1",
                "type": "agent",
                "url": "https://github.com/arksine/moontest"
            }
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	An Agent Event Notification
		object.

Field	Type	Description
`agent`	`string`	The name of the agent sending the event.
`event`	`string`	The name of the event. Can be any name
		other than those reserved
		by Moonraker.
`data`	any	Additional data sent with the event. Can be any JSON
		encodable value. If the event does not attach data this
		field will be omitted.
{ #agent-event-notify-spec } Agent Event Notification

Event	Description
`connected`	An agent has connected to Moonraker. The `data`
	field will contain an
	Agent Info object.
`disconnected`	An agent has disconnected from Moonraker. The `data`
	field is omitted for this event.
{ #reserved-agent-event-desc} Reserved Agent Events

///

/// note The agent that sends an event will not receive a notification for that event. It will however receive events from other agents. ///

Sensor Events

Moonraker's [sensor] component will take periodic measurements of configured sensors. When one or more new measurement is received a notification will be emitted containing the new measurement data.

notify_sensor_update

{
    "jsonrpc": "2.0",
    "method": "notify_sensor_update",
    "params": [
        {
            "sensor1": {
                "humidity": 28.9,
                "temperature": 22.4
            }
        }
    ]
}

/// api-notification-spec open: True

Pos	Type	Description
0	object	A Sensor Notification object.

Field	Type	Description
sensor_name	object	The object may contain multiple `sensors`, where
		each key is the name of a sensor and the value
		is a `Sensor Values` object.
		#sensor-values-spec
{ #sensor-notification-spec } Sensor Notification

Field	Type	Description
value_name	any	The object may contain multiple `values`, where
		each key is the name of a parameter tracked
		by the sensor, and the value is the most
		recent reported measurement.
{ #sensor-values-spec } Sensor Values

///

52 KiB Raw Blame History

JSON-RPC notifications

Gcode Responses

Subscription Updates

Klippy Ready

Klippy Shutdown

Klippy Disconnected

File List Changed

Update Manager Response

Update Manager Refreshed

CPU Throttled

Moonraker Process Statistic Update

History Changed

Authorized User Created

Authorized User Deleted

Authorized User Logged Out

Service State Changed

Job Queue Changed

Button Event

Announcement update event

Announcement dismissed event

Announcement wake event

Sudo alert event

Webcams changed event

Spoolman active spool ID changed

Spoolman Status Changed

Agent Events

Sensor Events

52 KiB

Raw Blame History