QIDITECH/moonraker
1
0
Fork 0
mirror of https://github.com/QIDITECH/moonraker.git synced 2026-01-31 16:48:44 +03:00
Code Issues Packages Projects Releases Wiki Activity

PLUS4的moonraker

Browse Source
This commit is contained in:
whb0514
2024-09-02 13:31:06 +08:00
parent 1006bcb85e
commit f8fad844d7
101 changed files with 27357 additions and 7021 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/api_changes.md
View File

@@ -1,10 +1,53 @@
##
This document keeps a record of all changes to Moonraker's web APIs.
This document keeps a record of notable changes to Moonraker's Web API.
### July 18th 2023
- Moonraker API Version 1.3.0
- Added [Spoolman](web_api.md#spoolman-apis) APIs.
- Added [Rollback](web_api.md#rollback-to-the-previous-version) API to
the `update_manager`
- The `update_manager` status response has new fields for items of the
`git_repo` and `web` types:
- `recovery_url`: Url of the repo a "hard" recovery will fetch from
- `rollback_version`: Version the extension will revert to when a rollback
is requested
- `warnings`: An array of strings containing various warnings detected
during repo init. Some warnings may explain an invalid state while
others may alert users to potential issues, such as a `git_repo` remote
url not matching the expected (ie: configured) url.
- Additionally, the `need_channel_update` field has been removed as the method
changing channels is done exclusively in the configuration.
### February 20th 2023
- The following new endpoints are available when at least one `[sensor]`
section has been configured:
- `GET /server/sensors/list`
- `GET /server/sensors/sensor`
- `GET /server/sensors/measurements`
See [web_api.md](web_api.md) for details on these new endpoints.
- A `sensors:sensor_update` notification has been added. When at least one
monitored sensor is reporting a changed value Moonraker will broadcast this
notification.
See [web_api.md](web_api.md) for details on this new notification.
### February 17 2023
- Moonraker API Version 1.2.1
- An error in the return value for some file manager endpoints has
been corrected. Specifically, the returned result contains an `item` object
with a `path` field that was prefixed with the root (ie: "gcodes").
This is inconsistent with the websocket notification and has been corrected
to remove the prefix. This affects the following endpoints:
- `POST /server/files/directory` | `server.files.post_directory`
- `DELETE /server/files/directory` | `server.files.delete_directory`
- `POST /server/files/move` | `server.files.move`
- `POST /server/files/copy` | `server.files.copy`
### March 4th 2022
- Moonraker API Version 1.0.1
- The `server.websocket.id` endpoint has been deprecated. It is
recommended to use `server.connection.idenitfy` method to identify
recommended to use `server.connection.identify` method to identify
your client. This method returns a `connection_id` which is
the websocket's unique id. See
[the documentation](web_api.md#identify-connection) for details.

181
docs/changelog.md Normal file
View File

@@ -0,0 +1,181 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog].
## [Unreleased]
### Added
- **notifier**: The `attach` option now supports Jinja2 templates.
- **notifier**: The `attach` option may now contain multiple attachments,
each separated by a newline.
- **notifier**: Added support for a configurable `body_format`
- **power**: Added support for generic `http` type switches.
- **metadata**: Added support for OrcaSlicer
- **zeroconf**: Added support for a configurable mDNS hostname.
- **zeroconf**: Added support for UPnP/SSDP Discovery.
- **spoolman**: Added integration to the
[Spoolman](https://github.com/Donkie/Spoolman) filament manager.
- **update_manager**: Added support for update rollbacks
- **update_manager**: Added support for stable `git_repo` updates
- **server**: Added a `--unixsocket` command line option
- **server**: Command line options may also be specified as env variables
- **server**: Added a `route_prefix` option
- **webcam**: Webcam APIs can now specify cameras by `uid` or `name`
- **deps**: Added support for optional `msgspec` and `uvloop` packages
- **extensions**: Agents may now register remote methods with Klipper
- **file_manager**: Add `check_klipper_config_path` option
- **button**: Added `debounce_period` option
- **history**: Added a check for previous jobs not finished (ie: when power is
lost during a print). These jobs will report their status as `interrupted`.
- **build**: Added support for optional speedup dependencies `uvloop` and `msgspec`
- **update_manager**: Added support for "zipped" application updates
- **file_manager**: Added `enable_config_write_access` option
- **machine**: Add support for system peripheral queries
- **mqtt**: Added the `status_interval` option to support rate limiting
- **mqtt**: Added the `enable_tls` option to support ssl/tls connections
- **history**: Added `user` field to job history data
- **history**: Added support for auxiliary history fields
- **spoolman**: Report spool ids set during a print in history auxiliary data
- **sensor**: Added support for history fields reported in auxiliary data
- **power**: Added support for `uhubctl` devices
- **update_manager**: Add support for pinned git commits
### Fixed
- **simplyprint**: Fixed import error preventing the component from loading.
- **update_manager**: Moonraker will now restart the correct "moonraker" and
"klipper" services if they are not the default values.
- **job_queue**: Fixed transition when auto is disabled
- **history**: Added modification time to file existence checks.
- **dbus_manager**: Fixed PolKit warning when PolKit features are not used.
- **job_queue**: Fixed a bug where the `job_transition_gcode` runs when the
queue is started. It will now only run between jobs during automatic
transition.
- **klippy_connection**: Fixed a race condition that can result in
skipped subscription updates.
- **configheler**: Fixed inline comment parsing.
- **authorization**: Fixed blocking call to `socket.getfqdn()`
- **power**: Fixed "on_when_job_queued" behavior when the internal device
state is stale.
### Changed
- **build**: Bumped apprise to version `1.8.0`.
- **build**: Bumped lmdb to version `1.4.1`
- **build**: Bumped tornado to version `6.4.0`
- **build**: Bumped jinja2 to version `3.1.4`
- **build**: Bumped zeroconf to version `0.131.0`
- **build**: Bumped libnacl to version `2.1.0`
- **build**: Bumped distro to version `1.9.0`
- **build**: Bumped pillow to version `10.3.0`
- **build**: Bumped streaming-form-data to version `1.15.0`
- **machine**: Added `ratos-configurator` to list of default allowed services
- **update_manager**: It is now required that an application be "allowed"
for Moonraker to restart it after an update.
- **update_manager**: Git repo validation no longer requires a match for the
remote URL and/or branch.
- **update_manager**: Fixed potential security vulnerabilities in `web` type updates.
This change adds a validation step to the install, front-end developers may refer to
the [configuration documentation](./configuration.md#web-type-front-end-configuration)
for details.
- **update_manager**: The `env` option for the `git_repo` type has been deprecated, new
configurations should use the `virtualenv` option.
- **update_manager**: The `install_script` option for the `git_repo` has been
deprecated, new configurations should use the `system_dependencies` option.
- **update_manager**: APIs that return status report additional fields.
See the [API Documentation](./web_api.md#get-update-status) for details.
- **proc_stats**: Improved performance of Raspberry Pi CPU throttle detection.
- **power**: Bound services are now processed during initialization when
`initial_state` is configured.
- **gpio**: Migrate from libgpiod to python-periphery
- **authorization**: The authorization module is now loaded as part of Moonraker's
core.
- **database**: Migrated the underlying database from LMDB to Sqlite.
- **history**: Use dedicated SQL tables to store job history and job totals.
- **authorization**: Use a dedicated SQL table to store user data.
## [0.8.0] - 2023-02-23
!!! Note
This is the first tagged release since a changelog was introduced. The list
below contains notable changes introduced beginning in Feburary 2023. Prior
notable changes were kept in [user_changes.md] and [api_changes.md].
### Added
- Added this changelog!
- Added pyproject.toml with support for builds through [pdm](https://pdm.fming.dev/latest/).
- **sensor**: New component for generic sensor configuration.
- [Configuration Docs](configuration.md#sensor)
- [API Docs](web_api.md#sensor-apis)
- [Websocket Notification Docs](web_api.md#sensor-events)
- **file_manager**: Added new [scan metadata](web_api.md#scan-gcode-metadata) endpoint.
- **file_manager**: Added new [thumbnails](web_api.md#get-gcode-thumbnails) endpoint.
- **file_manager**: Added [file_system_observer](configuration.md#file_manager)
configuration option.
- **file_manager**: Added [enable_observer_warnings](configuration.md#file_manager)
configuration option.
- **file_manager**: Added ability to upload to symbolic links.
- **metadata**: Added support for Simplify3D V5 metadata parsing
- **machine**: Added [shutdown_action](configuration.md#machine) configuration
option.
- **machine**: Added service detection to the `supervisord_cli` provider.
- **machine**: Added `octoeverywhere` to the list of default allowed service.
- **power**: Added support for "Hue" device groups.
- **websockets**: Added support for [direct bridge](web_api.md#bridge-websocket)
connections.
- **update_manager**: Added new [refresh](web_api.md#refresh-update-status) endpoint.
- **update_manager**: Added support for pinned pip upgrades.
- **websockets**: Added support for post connection authentication over the websocket.
- **scripts**: Added database backup and restore scripts.
### Changed
- Converted Moonraker source into a Python package.
- The source from `moonraker.py` has been moved to `server.py`. The remaining code in
`moonraker.py` serves as a legacy entry point for launching Moonraker.
- **file_manager**: Improved inotify synchronization with API requests.
- **file_manager**: Endpoint return values are now consistent with their
respective websocket notifications.
- **machine**: The [provider](configuration.md#machine) configuration option
now expects `supervisord_cli` instead of `supervisord`.
- **update_manager**: Relaxed requirement for git repo tag detection. Now only two
parts are required (ie: v1.5 and v1.5.0 are acceptable).
### Deprecated
- **file_manager**: The `enable_inotify_warnings` configuration option has been
deprecated in favor of `enable_observer_warnings`.
### Fixed
- **file_manager**: Fix edge condition where `create_file` notifications
may be sent before a `create_dir` notification.
- **power** - Fixed URL encoding issues for http devices.
- **template**: A ConfigError is now raised when a template fails to
render during configuration.
- **machine**: Fixed support for Supervisord Version 4 and above.
- **update_manager**: Added package resolution step to the APT backend.
- **update_manger**: Fixed PackageKit resolution step for 64-bit systems.
- **update_manager**: Fixed Python requirements file parsing. Comments are now ignored.
### Removed
- Pycurl dependency. Moonraker no longer uses Tornado's curl based http client.
## [0.7.1] - 2021-07-08
- Experimental pre-release
<!-- Links -->
[keep a changelog]: https://keepachangelog.com/en/1.0.0/
[semantic versioning]: https://semver.org/spec/v2.0.0.html
[user_changes.md]: user_changes.md
[api_changes.md]: api_changes.md
<!-- Versions -->
[unreleased]: https://github.com/Arksine/moonraker/compare/v0.8.0...HEAD
[0.8.0]: https://github.com/Arksine/moonraker/compare/v0.7.1...v0.8.0
[0.7.1]: https://github.com/Arksine/moonraker/releases/tag/v0.7.1

1637
docs/configuration.md
View File

File diff suppressed because it is too large Load Diff

47
docs/contributing.md
View File

@@ -1,10 +1,28 @@
# Contributing to Moonraker
While Moonraker exists as a service independently from Klipper, it relies
on Klipper to be useful. Thus, the tentative plan is to eventually merge
the Moonraker application into the Klipper repo after Moonraker matures,
at which point this repo will be archived. As such, contibuting guidelines
are near those of Klipper:
Prior to submitting a pull request prospective contributors must read this
entire document. Care should be taken to [format git commits](#git-commit-format)
correctly. This eases the review process and provides the reviewer with
confidence that the submission will be of sufficient quality.
Prospective contributors should consider the following:
- Does the contribution have significant impact? Bug fixes to existing
functionality and new features requested by 100+ users qualify as
items of significant impact.
- Has the submission been well tested? Submissions with substantial code
change must include details about the testing procedure and results.
- Does the submission include blocking code? Moonraker is an asynchronous
application, thus blocking code must be avoided.
- If any dependencies are included, are they pure python? Many low-powered SBCs
running Armbian do not have prebuilt wheels and are not capable of building wheels
themselves, thus breaking updates on these systems.
- Does the submission change the API? If so, could the change potentially break
frontends using the API?
- Does the submission include updates to the documentation?
When performing reviews these are the questions that will be asked during the
initial stages.
#### New Module Contributions
@@ -105,24 +123,23 @@ By making a contribution to this project, I certify that:
```
#### Code Style
Python methods should be fully annotated. Variables should be annotated where
the type cannot be inferred. Moonraker uses the `mypy` static type checker for
code validation with the following options:
the type cannot be inferred. Moonraker uses `mypy` version 1.5.1 for static
type checking with the following options:
- `--ignore-missing-imports`
- `--follow-imports=silent`
No line in the source code should exceed 80 characters. Be sure there is no
No line in the source code should exceed 88 characters. Be sure there is no
trailing whitespace. To validate code before submission one may use
`pycodestyle` with the following options:
`flake8` version 6.1.0 with the following options:
- `--ignore=E226,E301,E302,E303,W503,W504`
- `--max-line-length=80`
- `--max-doc-length=80`
- `--max-line-length=88`
- `--max-doc-length=88`
Generally speaking, each line in submitted documentation should also be no
longer than 80 characters, however there are situations where this isn't
possible, such as long hyperlinks or example return values. Documentation
isn't linted, so it
longer than 88 characters, however there are situations where this isn't
possible, such as long hyperlinks or example return values.
Don't peek into the member variables of another class. Use getters or
Avoid peeking into the member variables of another class. Use getters or
properties to access object state.

4
docs/doc-requirements.txt
View File

@@ -1,2 +1,2 @@
mkdocs==1.3.0
pymdown-extensions==9.1
mkdocs-material==9.5.4
compact_tables@git+https://github.com/Arksine/markdown-compact-tables@v1.0.0

4
docs/index.md
View File

@@ -2,7 +2,7 @@
Moonraker is a Python 3 based web server that exposes APIs with which
client applications may use to interact with the 3D printing firmware
[Klipper](https://github.com/KevinOConnor/klipper). Communcation between
[Klipper](https://github.com/Klipper3d/klipper). Communication between
the Klippy host and Moonraker is done over a Unix Domain Socket. Tornado
is used to provide Moonraker's server functionality.
@@ -14,7 +14,7 @@ Client developers may refer to the [Client API](web_api.md)
documentation.
Backend developers should refer to the
[contibuting](contributing.md) section for basic contribution
[contributing](contributing.md) section for basic contribution
guidelines prior to creating a pull request. The
[components](components.md) document provides a brief overview
of how to create a component and interact with Moonraker's

501
docs/installation.md
View File

@@ -31,10 +31,10 @@ missing one or both, you can simply add the bare sections to `printer.cfg`:
[display_status]
[virtual_sdcard]
path: ~/gcode_files
path: ~/printer_data/gcodes
```
### Enabling the Unix Socket
### Enabling Klipper's Unix Domain Socket Server
After Klipper is installed it may be necessary to modify its `defaults` file in
order to enable the Unix Domain Socket. Begin by opening the file in your
@@ -69,12 +69,9 @@ KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klip
the default LSB script. In this case, you need to modify the
klipper.service file.
You may also want to take this opportunity to change the location of
printer.cfg to match Moonraker's `config_path` option (see the
[configuration document](configuration.md#primary-configuration)
for more information on the config_path). For example, if the `config_path`
is set to `~/printer_config`, your klipper defaults file might look
like the following:
You may also want to take this opportunity to configure `printer.cfg` and
`klippy.log` so they are located in Moonraker's `data_path`, for example:
```
# Configuration for /etc/init.d/klipper
@@ -82,14 +79,17 @@ KLIPPY_USER=pi
KLIPPY_EXEC=/home/pi/klippy-env/bin/python
KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer_config/printer.cfg -l /tmp/klippy.log -a /tmp/klippy_uds"
KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer_data/config/printer.cfg -l /home/pi/printer_data/logs/klippy.log -a /tmp/klippy_uds"
```
If necessary, create the config directory and move printer.cfg to it:
Moonraker's install script will create the data folder, however you
may wish to create it now and move `printer.cfg` to the correct
location, ie:
```
cd ~
mkdir printer_config
mv printer.cfg printer_config
mkdir ~/printer_data
mkdir ~/printer_data/logs
mkdir ~/printer_data/config
mv printer.cfg ~/printer_data/config
```
### Installing Moonraker
@@ -101,10 +101,15 @@ cd ~
git clone https://github.com/Arksine/moonraker.git
```
Now is a good time to create [moonraker.conf](configuration.md). If you are
using the `config_path`, create it in the specified directory otherwise create
it in the HOME directory. The [sample moonraker.conf](./moonraker.conf) in
the `docs` directory may be used as a starting point.
The install script will attempt to create a basic configuration if
`moonraker.conf` does not exist at the expected location, however if you
prefer to have Moonraker start with a robust configuration you may create
it now. By default the configuration file should be located at
`$HOME/printer_data/config/moonraker.conf`, however the location of the
data path may be configured using the script's command line options.
The [sample moonraker.conf](./moonraker.conf) may be used as a starting
point, full details can be found in the
[confguration documentation](./configuration.md).
For a default installation run the following commands:
```
@@ -112,29 +117,40 @@ cd ~/moonraker/scripts
./install-moonraker.sh
```
Or to install with `moonraker.conf` in the `config_path`:
```
cd ~/moonraker/scripts
./install-moonraker.sh -f -c /home/pi/printer_config/moonraker.conf
```
The install script has a few command line options that may be useful,
particularly for those upgrading:
- `-r`:
Rebuilds the virtual environment for existing installations.
Sometimes this is necessary when a dependency has been added.
- `-f`:
Force an overwrite of Moonraker's systemd script. By default the
the systemd script will not be modified if it exists.
- `-c /home/pi/moonraker.conf`:
Specifies the path to Moonraker's config file. The default location
is `/home/<user>/moonraker.conf`. When using this option to modify
an existing installation it is necessary to add `-f` as well.
- `-a <alias>`:
The installer uses this option to determine the name of the service
to install. If `-d` is not provided then this options will also be
used to determine the name of the data path folder. If omitted this
defaults to `moonraker`.
- `-d <path to data folder>`:
Specifies the path to Moonraker's data folder. This folder organizes
files and directories used by moonraker. See the `Data Folder Structure`
section for details. If omitted this defaults to `$HOME/printer_data`.
- `-c <path to configuration file>`
Specifies the path to Moonraker's configuation file. By default the
configuration is expected at `<data_folder>/config/moonraker.conf`. ie:
`/home/pi/printer_data/config/moonraker.conf`.
- `-l <path to log file>`
Specifies the path to Moonraker's log file. By default Moonraker logs
to `<data_folder>/logs/moonraker.log`. ie:
`/home/pi/printer_data/logs/moonraker.log`.
- `-z`:
Disables `systemctl` commands during install (ie: daemon-reload, restart).
This is useful for installations that occur outside of a standard environment
where systemd is not running.
- `-x`:
Skips installation of [polkit rules](#policykit-permissions). This may be
necessary to install Moonraker on systems that do not have policykit
installed.
- `-s`:
Installs Moonraker's [speedup](#optional-speedups) Python packages in the
Python environment.
Additionally, installation may be customized with the following environment
variables:
@@ -143,17 +159,20 @@ variables:
- `MOONRAKER_REBUILD_ENV`
- `MOONRAKER_FORCE_DEFAULTS`
- `MOONRAKER_DISABLE_SYSTEMCTL`
- `MOONRAKER_SKIP_POLKIT`
- `MOONRAKER_CONFIG_PATH`
- `MOONRAKER_LOG_PATH`
- `MOONAKER_LOG_PATH`
- `MOONRAKER_DATA_PATH`
- `MOONRAKER_SPEEDUPS`
When the script completes it should start both Moonraker and Klipper. In
`/tmp/klippy.log` you should find the following entry:
`klippy.log` you should find the following entry:
`webhooks client <uid>: Client info {'program': 'Moonraker', 'version': '<version>'}`
Now you may install a client, such as
[Mainsail](https://github.com/mainsail-crew/mainsail) or
[Fluidd](https://github.com/cadriel/fluidd).
[Fluidd](https://github.com/fluidd-core/fluidd).
!!! Note
Moonraker's install script no longer includes the nginx dependency.
@@ -162,42 +181,267 @@ Now you may install a client, such as
debian/ubuntu distros).
### Data Folder Structure
As mentioned previously, files and folders used by Moonraker are organized
in a primary data folder. The example below illustrates the folder
structure using the default data path of `$HOME/printer_data`.
```
/home/pi/printer_data
├── backup
│   └── 20220822T202419Z
│   ├── config
│   │   └── moonraker.conf
│   └── service
│   └── moonraker.service
├── certs
│   ├── moonraker.cert (optional)
│   └── moonraker.key (optional)
├── config
│   ├── moonraker.conf
│   └── printer.cfg
├── database
│   └── moonraker-sql.db
├── gcodes
│   ├── test_gcode_one.gcode
│   └── test_gcode_two.gcode
├── logs
│   ├── klippy.log
│   └── moonraker.log
├── systemd
│ └── moonraker.env
├── moonraker.secrets (optional)
└── moonraker.asvc
```
If it is not desirable for the files and folders to exist in these specific
locations it is acceptable to use symbolic links. For example, it is common
for the gcode folder to be located at `$HOME/gcode_files`. Rather than
reconfigure Klipper's `virtual_sdcard` it may be desirable to create a
`gcodes` symbolic link in the data path pointing to this location.
!!! Note
It is still possible to directly configure the paths to the configuration
and log files if you do not wish to use the default file names of
`moonraker.conf` and `moonraker.log`
When Moonraker attempts to update legacy installations symbolic links
are used to avoid an unrecoverable error. Additionally a `backup`
folder is created which contains the prior configuration and/or
systemd service unit, ie:
```
/home/pi/printer_data
├── backup
│   └── 20220822T202419Z
│   ├── config
│   │   ├── include
│   │   │   ├── extras.conf
│   │   │   ├── power.conf
│   │   │   └── updates.conf
│   │   └── moonraker.conf
│   └── service
│   └── moonraker.service
├── certs
│   ├── moonraker.cert -> /home/pi/certs/certificate.pem
│   └── moonraker.key -> /home/pi/certs/key.pem
├── config -> /home/pi/klipper_config
├── database -> /home/pi/.moonraker_database
├── gcodes -> /home/pi/gcode_files
├── logs -> /home/pi/logs
├── systemd
│ └── moonraker.env
└── moonraker.secrets -> /home/pi/moonraker_secrets.ini
```
!!! Warning
The gcode and config paths should not contain symbolic links
that result in an "overlap" of on another. Moonraker uses
inotify to watch files in each of these folders and takes action
when a file change is detected. The action taken depends on the
"root" folder, thus it is important that they be distinct.
### The systemd service file
The default installation will create `/etc/systemd/system/moonraker.service`.
Below is a common example of service file, installed on a Raspberry Pi:
```ini
# systemd service file for moonraker
[Unit]
Description=API Server for Klipper SV1
Requires=network-online.target
After=network-online.target
[Install]
WantedBy=multi-user.target
[Service]
Type=simple
User=pi
SupplementaryGroups=moonraker-admin
RemainAfterExit=yes
WorkingDirectory=/home/pi/moonraker
EnvironmentFile=/home/pi/printer_data/systemd/moonraker.env
ExecStart=/home/pi/moonraker-env/bin/python $MOONRAKER_ARGS
Restart=always
RestartSec=10
```
Following are some items to take note of:
- The `Description` contains a string that Moonraker uses to validate
the version of the service file, (notice `SV1` at the end, ie: Service
Version 1).
- The `moonraker-admin` supplementary group is used to grant policykit
permissions.
- The `EnvironmentFile` field contains Moonraker's arguments. See the
[environment file section](#the-environment-file) for details.
- The `ExecStart` field begins with the python executable, followed by
by the enviroment variable `MOONRAKER_ARGS`. This variable is set in
the environment file.
### Command line usage
This section is intended for users that need to write their own
installation script. Detailed are the command line arguments
available to Moonraker:
```
usage: moonraker.py [-h] [-c <configfile>] [-l <logfile>] [-n]
usage: moonraker.py [-h] [-d <data path>] [-c <configfile>] [-l <logfile>] [-u <unixsocket>] [-n] [-v] [-g] [-o]
Moonraker - Klipper API Server
optional arguments:
options:
-h, --help show this help message and exit
-d <data path>, --datapath <data path>
Location of Moonraker Data File Path
-c <configfile>, --configfile <configfile>
Location of moonraker configuration file
Path to Moonraker's configuration file
-l <logfile>, --logfile <logfile>
log file name and location
Path to Moonraker's log file
-u <unixsocket>, --unixsocket <unixsocket>
Path to Moonraker's unix domain socket
-n, --nologfile disable logging to a file
-v, --verbose Enable verbose logging
-g, --debug Enable Moonraker debug features
-o, --asyncio-debug Enable asyncio debug flag
```
The default configuration is:
- config file path- `~/moonraker.conf`
- log file path - `/tmp/moonraker.log`
- logging to a file is enabled
If one needs to start moonraker without generating a log file, the
- `data path`: `$HOME/printer_data`
- `config file`: `$HOME/printer_data/config/moonraker.conf`
- `log file`: `$HOME/printer_data/logs/moonraker.log`
- `unix socket`: `$HOME/printer_data/comms/moonraker.sock`
- logging to a file is enabled
- Verbose logging is disabled
- Moonraker's debug features are disabled
- The asyncio debug flag is set to false
!!! Tip
While the `data path` option may be omitted it is recommended that it
always be included for new installations. This allows Moonraker
to differentiate between new and legacy installations.
!!! Warning
Moonraker's `--unixsocket` option should not be confused with Klipper's
`--api-server` option. The `unixsocket` option for Moonraker specifies
the path where Moonraker will create a unix domain socket that serves its
JSON-RPC API.
If is necessary to run Moonraker without logging to a file the
`-n` option may be used, for example:
```
~/moonraker-env/bin/python ~/moonraker/moonraker/moonraker.py -n -c /path/to/moonraker.conf
~/moonraker-env/bin/python ~/moonraker/moonraker/moonraker.py -d ~/printer_data -n
```
In general it is not recommended to install moonraker with this option.
While moonraker will still log to stdout, all requests for support must
be accompanied by moonraker.log.
These options may be changed by editing
`/etc/systemd/system/moonraker.service`. The `install-moonraker.sh` script
may also be used to modify the config file location.
!!! Tip
It is not recommended to install Moonraker with file logging disabled
While moonraker will still log to stdout, all requests for support
must be accompanied by `moonraker.log`.
Each command line argument has an associated enviroment variable that may
be used to specify options in place of the command line.
- `MOONRAKER_DATA_PATH="<data path>"`: equivalent to `-d <data path>`
- `MOONRAKER_CONFIG_PATH="<configfile>"`: equivalent to `-c <configfile>`
- `MOONRAKER_LOG_PATH="<logfile>"`: equivalent to `-l <logfile>`
- `MOONRAKER_UDS_PATH="<unixsocket>"`: equivalent to `-u <unixsocket>`
- `MOONRAKER_DISABLE_FILE_LOG="y"`: equivalent to `-n`
- `MOONRAKER_VERBOSE_LOGGING="y"`: equivalent to `-v`
- `MOONRAKER_ENABLE_DEBUG="y"`: equivalent to `-g`.
- `MOONRAKER_ASYNCIO_DEBUG="y"`: equivalent to `-o`
!!! Note
Command line arguments take priority over environment variables when
both are specified.
[The environment file](#the-environment-file) may be used to set Moonraker's
command line arguments and/or environment variables.
### The environment file
The environment file, `moonraker.env`. is created in the data path during
installation. A default installation's environment file will contain the path
to `moonraker.py` and the data path option, ie:
```
MOONRAKER_DATA_PATH="/home/pi/printer_data"
MOONRAKER_ARGS="-m moonraker"
PYTHONPATH="/home/pi/moonraker"
```
A legacy installation converted to the updated flexible service unit
might contain the following. Note that this example uses command line
arguments instead of environment variables, either would be acceptable:
```
MOONRAKER_ARGS="/home/pi/moonraker/moonraker/moonraker.py -d /home/pi/printer_data -c /home/pi/klipper_config/moonraker.conf -l /home/pi/klipper_logs/moonraker.log"
```
Post installation it is simple to customize
[arguments and/or environment variables](#command-line-usage)
supplied to Moonraker by editing this file and restarting the service.
The following example sets a custom config file path, log file path,
enables verbose logging, and enables debug features:
```
MOONRAKER_DATA_PATH="/home/pi/printer_data"
MOONRAKER_CONFIG_PATH="/home/pi/printer_data/config/moonraker-1.conf"
MOONRAKER_LOG_PATH="/home/pi/printer_data/logs/moonraker-1.log"
MOONRAKER_VERBOSE_LOGGING="y"
MOONRAKER_ENABLE_DEBUG="y"
MOONRAKER_ARGS="-m moonraker"
PYTHONPATH="/home/pi/moonraker"
```
# Optional Speedups
Moonraker supports two optional Python packages that can be used to reduce
its CPU load:
- [msgspec](https://github.com/jcrist/msgspec): Replaces the builtin `json`
encoder/decoder. Requires Python >= 3.8.
- [uvloop](https://github.com/MagicStack/uvloop/): Replaces the default asyncio
eventloop implementation.
If these packages are installed in Moonraker's python environment Moonraker will
load them. For existing installations this can be done manually with a command
like:
```
~/moonraker-env/bin/pip install -r ~/moonraker/scripts/moonraker-speedups.txt
```
After installing the speedup packages it is possible to revert back to the
default implementation by specifying one or both of the following
environment variables in [moonraker.env](#the-environment-file):
- `MOONRAKER_ENABLE_MSGSPEC="n"`
- `MOONRAKER_ENABLE_UVLOOP="n"`
### PolicyKit Permissions
@@ -267,6 +511,37 @@ enable_system_updates: False
Previously installed PolicyKit rules can be removed by running
`set-policykit-rules.sh -c`
### Completing Privileged Upgrades
At times an update to Moonraker may require a change to the systemd service
file, which requires sudo permission to complete. Moonraker will present
an announcement when it need's the user's password and the process can
be completed by entering the password through Moonraker's landing page.
Some users prefer not to provide these credentials via the web browser and
instead would like to do so over ssh. These users may run
`scripts/finish-upgrade.sh` to provide Moonraker the necessary credentials
via ssh:
```
Utility to complete privileged upgrades for Moonraker
usage: finish-upgrade.sh [-h] [-a <address>] [-p <port>] [-k <api_key>]
optional arguments:
-h show this message
-a <address> address for Moonraker instance
-p <port> port for Moonraker instance
-k <api_key> API Key for authorization
```
By default the script will connect to a Moonraker instances on the local
machine at port 7125. If the instance is not bound to localhost or is
bound to another port the user may specify a custom address and port.
The API Key (`-k`) option is only necessary if the localhost is not authorized
to access Moonraker's API.
### Retrieving the API Key
Some clients may require an API Key to connect to Moonraker. After the
@@ -290,6 +565,86 @@ Retrieve the API Key via the browser from a trusted client:
{"result": "8ce6ae5d354a4365812b83140ed62e4b"}
### Database Backup and Restore
Moonraker stores persistent data using an Sqlite database. By default
the database file is located at `<data_folder>/database/moonraker-sql.db`.
API Endpoints are available to backup and restore the database. All
backups are stored at `<data_folder>/backup/database/<backup_name>` and
restored from the same location. Database files may contain sensitive
information, therefore they are not served by Moonraker. Another protocol
such as SCP, SMB, etc is required to transfer a backup off of the host.
Alternatively it is possible to perform a manual backup by copying the
existing database file when the Moonraker service has been stopped.
Restoration can be performed by stopping the Moonraker service and
overwriting the existing database with the backup.
#### LDMB Database (deprecated)
Previous versions of Moonraker used a [LMDB Database](http://www.lmdb.tech/doc/)
for persistent storage of procedurally generated data. LMDB database files are
platform dependent, and thus cannot be easily transferred between different
machines. A file generated on a Raspberry Pi cannot be directly transferred
to an x86 machine. Likewise, a file generated on a 32-bit version of Linux
cannot be transferred to a 64-bit machine.
Moonraker includes two scripts, `backup-database.sh` and `restore-database.sh`
to help facilitate database backups and transfers.
```shell
~/moonraker/scripts/backup-database.sh -h
Moonraker Database Backup Utility
usage: backup-database.sh [-h] [-e <python env path>] [-d <database path>] [-o <output file>]
optional arguments:
-h show this message
-e <env path> Moonraker Python Environment
-d <database path> Moonraker LMDB database to backup
-o <output file> backup file to save to
```
```shell
~/moonraker/scripts/restore-database.sh -h
Moonraker Database Restore Utility
usage: restore-database.sh [-h] [-e <python env path>] [-d <database path>] [-i <input file>]
optional arguments:
-h show this message
-e <env path> Moonraker Python Environment
-d <database path> Moonraker LMDB database path to restore to
-i <input file> backup file to restore from
```
Both scripts include default values for the Moonraker Environment and Database
Path. These are `$HOME/moonraker-env` and `$HOME/printer_data/database`
respectively. The `backup` script defaults the output value to
`$HOME/database.backup`. The `restore` script requires that the user specify
the input file using the `-i` option.
To backup a database for a default Moonraker installation the user may ssh into
the machine and run the following command:
```shell
~/moonraker/scripts/backup-database.sh -o ~/moonraker-database.backup
```
And to restore the database:
```shell
sudo service moonraker stop
~/moonraker/scripts/restore-database.sh -i ~/moonraker-database.backup
sudo service moonraker start
```
The backup file contains [cdb like](https://manpages.org/cdb/5) entries
for each key/value pair in the database. All keys and values are base64
encoded, however the data is not encrypted. Moonraker's database may
contain credentials and other sensitive information, so users should treat
this file accordingly. It is not recommended to keep backups in any folder
served by Moonraker.
### Recovering a broken repo
Currently Moonraker is deployed using `git`. Without going into the gritty
@@ -327,16 +682,44 @@ git clone https://github.com/Klipper3d/klipper.git
sudo systemctl restart klipper
```
### Additional Notes
### Debug options for developers
- Make sure that Moonraker and Klipper both have read and write access to the
directory set in the `path` option for the `[virtual_sdcard]` in
`printer.cfg`.
- Upon first starting Moonraker is not aware of the gcode file path, thus
it cannot serve gcode files, add directories, etc. After Klippy enters
the "ready" state it sends Moonraker the gcode file path.
Once Moonraker receives the path it will retain it regardless of Klippy's
state, and update it if the path is changed in printer.cfg.
Moonraker accepts several command line arguments that can be used to
assist both front end developers and developers interested in extending
Moonraker.
Please see [configuration.md](configuration.md) for details on how to
configure moonraker.conf.
- The `-v` (`--verbose`) argument enables verbose logging. This includes
logging that reports information on all requests received and responses.
- The `-g` (`--debug`) argument enables Moonraker's debug features,
including:
- Debug endpoints
- The `update_manager` will bypass strict git repo validation, allowing
updates from unofficial remotes and repos in a `detached HEAD` state.
- The `-o` (`--asyncio-debug`) argument enables the asyncio debug flag. This
will substantially increase logging and is intended for low level debugging
of the asyncio event loop.
!!! Warning
The debug option should not be enabled in production environments. The
database debug endpoints grant read/write access to all namespaces,
including those typically exclusive to Moonraker. Items such as user
credentials are exposed.
Installations using systemd can enable debug options by editing `moonraker.env`
via ssh:
```
nano ~/printer_data/systemd/moonraker.env
```
Once the file is open, append the debug option(s) (`-v` and `-g` in this example) to the
value of `MOONRAKER_ARGS`:
```
MOONRAKER_ARGS="/home/pi/moonraker/moonraker/moonraker.py -d /home/pi/printer_data -c /home/pi/klipper_config/moonraker.conf -l /home/pi/klipper_logs/moonraker.log -v -g"
```
Save the file, exit the text editor, and restart the Moonraker service:
```
sudo systemctl restart moonraker
```

3
docs/moonraker.conf
View File

@@ -6,8 +6,7 @@
[server]
# Bind server defaults of 0.0.0.0, port 7125
enable_debug_logging: True
config_path: ~/printer_config
enable_debug_logging: False
[authorization]
enabled: True

19
docs/printer_objects.md
View File

@@ -47,7 +47,7 @@ The `gcode_move` object reports the current gcode state:
- `speed_factor`: AKA "feedrate", this is the current speed multiplier
- `speed`: The current gcode speed in mm/s.
- `extrude_factor`: AKA "extrusion multiplier".
- `absolute_coorinates`: true if the machine axes are moved using
- `absolute_coordinates`: true if the machine axes are moved using
absolute coordinates, false if using relative coordinates.
- `absolute_extrude`: true if the extruder is moved using absolute
coordinates, false if using relative coordinates.
@@ -236,7 +236,11 @@ The `virtual_sdcard` object reports the state of the virtual sdcard:
"print_duration": 0.0,
"filament_used": 0.0,
"state": "standby",
"message": ""
"message": "",
"info": {
"total_layer": null,
"current_layer": null
}
}
```
The `print_stats` object reports `virtual_sdcard` print state:
@@ -260,6 +264,17 @@ The `print_stats` object reports `virtual_sdcard` print state:
- `"error"` - Note that if an error is detected the print will abort
- `message`: If an error is detected, this field contains the error
message generated. Otherwise it will be a null string.
- `info`: This is a dict containing information about the print provided by the
slicer. Currently this is limited to the `total_layer` and `current_layer` values.
Note that these values are set by the
[SET_PRINT_STATS_INFO](https://www.klipper3d.org/G-Codes.html#set_print_stats_info)
gcode command. It is necessary to configure the slicer to include this command
in the print. `SET_PRINT_STATS_INFO TOTAL_LAYER=total_layer_count` should
be called in the slicer's "start gcode" to initalize the total layer count.
`SET_PRINT_STATS_INFO CURRENT_LAYER=current_layer` should be called in the
slicer's "on layer change" gcode. The user must substitute the
`total_layer_count` and `current_layer` with the appropriate
"placeholder syntax" for the slicer.
!!! Note
After a print has started all of the values above will persist until

7
docs/src/css/extras.css Normal file
View File

@@ -0,0 +1,7 @@
[data-md-color-scheme="slate"] {
--md-table-color: rgb(20, 20, 20);
}
thead th {
background-color: var(--md-table-color)
}

79
docs/user_changes.md
View File

@@ -1,6 +1,81 @@
##
This file will track changes that require user intervention,
such as a configuration change or a reinstallation.
This file tracks configuration changes and deprecations. Additionally
changest to Moonraker that require user intervention will be tracked
here.
### December 24th 2023
- The `gpio` component no longer depends on `libgpiod`. Instead,
Moonraker now uses the [python-periphery](https://github.com/vsergeev/python-periphery)
library to manage GPIOs. This comes with several benefits:
- Distributions that do no ship with `libgpiod` will not fail during
installation if the `python3-libgpiod` package isn't present.
- Distributions with a Kernel Version of 5.5 or higher support bias
flags (ie: pull up or pull down). Previously this functionality
was tied to the `libgpiod` version. Specifically, Debian Buster
ships with a Kernel that supports bias, however the `libgpiod`
version does not.
- Version 2.0+ of `libgpiod` includes dramatic API changes that are
wholly incompatible with prior versions. Therefore maintaining
future versions would effectively require supporting two APIs.
- The `[button]` component now includes a `debounce_period` option.
This addition is the result of a behavior change in how gpio state
changes are debounced. Debouncing will now delay the event by the
time specified in the `debounce_period`. Additional state changes
received during this delay will not trigger a button event. The
`[button]` module retains the `minimum_event_time` option which will
ignore events shorter than the specified time.
### July 18th 2023
- The following changes have been made to `[update_manager <name>]`
extensions of the `git_repo` type:
- The `env` option has been deprecated. New configurations should
use the `virtualenv` option in its place.
- The `install_script` option has been deprecated. New configurations
should use the `system_dependencies` option to specify system package
dependencies.
- Configuration options for `[spoolman]` have been added
- Configuration options for `[sensor]` have been added
### Februrary 8th 2023
- The `provider` option in the `[machine]` section no longer accepts
`supervisord` as an option. It has been renamed to `supervisord_cli`.
### January 2nd 2023
- The `bound_service` option for `[power]` devices has been deprecated in
favor of `bound_services`. Currently this change does not generate a
warning as it can be reliably resolved internally.
### October 14th 2022
- The systemd service file is now versioned. Moonraker can now detect when
the file is out of date and automate corrections as necessary.
- Moonraker's command line options are now specified in an environment file,
making it possible to change these options without modifying the service file
and reloading the systemd daemon. The default location of the environment
file is `~/printer_data/systemd/moonraker.env`.
- Moonraker now manages files and folders in a primary data folder supplied
by the `-d` (`--data-path`) command line option. As a result, the following
options have been deprecated:
- `ssl_certificate_path` in `[server]`
- `ssl_key_path` in `[server]`
- `database_path` in `[database]`
- `config_path` in `[file_manager]`
- `log_path` in `[file_manager]`
- `secrets_path` in `[secrets]`
- Debugging options are now supplied to Moonraker via the command line.
The `-v` (`--verbose`) option enables verbose logging, while the `-g`
(`--debug`) option enables debug features, including access to debug
endpoints and the repo debug feature in `update_manager`. As a result,
the following options are deprecated:
- `enable_debug_logging` in `[server]`
- `enable_repo_debug` in `[update_manager]`
### July 27th 2022
- The behavior of `[include]` directives has changed. Included files
are now parsed as they are encountered. If sections are duplicated
options in the last section parsed take precendence. If you are
using include directives to override configuration in `moonraker.conf`
the directives should be moved to the bottom of the file.
- Configuration files now support inline comments.
### April 6th 2022
- The ability to configure core components in the `[server]`section

4307
docs/web_api.md
View File

File diff suppressed because it is too large Load Diff