Plugin mixins are the heart of OctoPrint's plugin system. They are special base classes
which are to be subclassed and extended to add functionality to OctoPrint. Plugins declare their instances that
implement one or multiple mixins using the
__plugin_implementation__ control property. OctoPrint's plugin core
collects those from the plugins and offers methods to access them based on the mixin type, which get used at multiple
locations within OctoPrint.
Using mixins always follows the pattern of retrieving the matching implementations from the plugin subsystem, then calling the specific mixin's methods as defined and necessary.
The following snippet taken from OctoPrint's code for example shows how all
implementations are collected and then all assets they return via their
get_assets methods are retrieved and
rendition of the UI.
asset_plugins = pluginManager.get_implementations(octoprint.plugin.AssetPlugin) for name, implementation in asset_plugins.items(): all_assets = implementation.get_assets() if "js" in all_assets: for asset in all_assets["js"]: assets["js"].append(url_for('plugin_assets', name=name, filename=asset)) if preferred_stylesheet in all_assets: for asset in all_assets[preferred_stylesheet]: assets["stylesheets"].append((preferred_stylesheet, url_for('plugin_assets', name=name, filename=asset))) else: for stylesheet in supported_stylesheets: if not stylesheet in all_assets: continue for asset in all_assets[stylesheet]: assets["stylesheets"].append((stylesheet, url_for('plugin_assets', name=name, filename=asset))) break
- The Plugin Tutorial
- Tutorial on how to write a simple OctoPrint module utilizing mixins for various types of extension.
If a method is to be called on a plugin implementation for which a sorting context is defined (see the mixin documentation for information on this), OctoPrint's plugin subsystem will ensure that the order in which the implementation calls are done is as follows:
- Plugins with a return value that is not
get_sorting_keyfor the provided sorting context will be ordered among each other first. If the returned order number is equal for two or more implementations, they will be sorted first by whether they come bundled with OctoPrint or not, then by their identifier.
- After that follow plugins which returned
None(the default). They are first sorted by whether they come bundled with OctoPrint or not, then by their identifier.
Consider four plugin implementations implementing the
StartupPlugin mixin, called
plugin_d, the latter coming bundled with OctoPrint.
plugin_d don't override
1 for the sorting context
import octoprint.plugin class PluginB(octoprint.plugin.StartupPlugin): def get_sorting_key(self, context): if context == "StartupPlugin.on_startup": return 1 return None def on_startup(self, *args, **kwargs): self._logger.info("PluginB starting up") def on_after_startup(self, *args, **kwargs): self._logger.info("PluginB started up") __plugin_implementation__ = PluginB()
import octoprint.plugin class PluginC(octoprint.plugin.StartupPlugin): def get_sorting_key(self, context): if context == "StartupPlugin.on_startup": return 1 return None def on_startup(self, *args, **kwargs): self._logger.info("PluginC starting up") def on_after_startup(self, *args, **kwargs): self._logger.info("PluginC started up") __plugin_implementation__ = PluginC()
# in this example this is bundled with OctoPrint import octoprint.plugin class PluginD(octoprint.plugin.StartupPlugin): def on_startup(self, *args, **kwargs): self._logger.info("PluginD starting up") def on_after_startup(self, *args, **kwargs): self._logger.info("PluginD started up") __plugin_implementation__ = PluginD()
OctoPrint will detect that
plugin_c define a order number, and since it's identical for both,
1, will order both plugins based first on their bundling status and then on their plugin identifier.
plugin_d don't define a sort key and hence will be
put after the other two, with
plugin_d coming before
plugin_a since it comes bundled with OctoPrint.
The execution order of the
on_startup method will hence be
Now, the execution order of the
on_after_startup method will be determined based on another sorting context,
StartupPlugin.on_after_startup for which all of the plugins return
None. Hence, the execution order of the
on_after_startup method will be ordered first by bundle status, then by plugin identifier:
This will result in the following messages to be generated:
OctoPrint's plugin subsystem will inject a bunch of properties into each mixin implementation. An overview of these properties follows.
The plugin's identifier.
The plugin's name, as taken from either the
__plugin_name__ control property or the package info.
The plugin's version, as taken from either the
__plugin_version__ control property or the package info.
octoprint.plugin.core.PluginInfo object associated with the plugin.
The plugin's base folder where it's installed. Can be used to refer to files relative to the plugin's installation location, e.g. included scripts, templates or assets.
The plugin's additional data folder path. Can be used to store additional files needed for the plugin's operation (cache,
data files etc). Plugins should not access this property directly but instead utilize
which will make sure the path actually does exist and if not create it before returning it.
logging.Logger instance logging to the log target
OctoPrint's plugin manager object, an instance of
OctoPrint's printer profile manager, an instance of
OctoPrint's event bus, an instance of
OctoPrint's analysis queue for analyzing GCODEs or other files, an instance of
OctoPrint's slicing manager, an instance of
OctoPrint's file manager, an instance of [
OctoPrint's printer management object, an instance of
OctoPrint's user manager, an instance of
OctoPrint's connectivity checker, an instance of
Available plugin mixins#
BlueprintPluginmixin allows plugins to define their own full fledged endpoints for whatever purpose, be it a more sophisticated API than what is possible via the
SimpleApiPluginor a custom web frontend.
EnvironmentDetectionPluginmixin allows enrichting OctoPrint's environmental information collections with additional data, and to react to successfully collected environmental information.
EventHandlerPluginmixin allows OctoPrint plugins to react to any of [OctoPrint's events][dev-guide.events]. OctoPrint will call the
on_eventmethod for any event fired on its internal event bus, supplying the event type and the associated payload.
- Via the
ProgressPluginmixin plugins can let themselves be called upon progress in print jobs or slicing jobs, limited to minimally 1% steps.
- Including the
SettingsPluginmixin allows plugins to store and retrieve their own settings within OctoPrint's configuration.
ShutdownPluginallows hooking into the shutdown of OctoPrint. It's usually used in conjunction with the
StartupPluginmixin, to cleanly shut down additional services again that where started by the
StartupPluginpart of the plugin.
- Utilizing the
SimpleApiPluginmixin plugins may implement a simple API based around one GET resource and one resource accepting JSON commands POSTed to it.
- Via the
SlicerPluginmixin plugins can add support for slicing engines to be used by OctoPrint.
StartupPluginallows hooking into the startup of OctoPrint. It can be used to start up additional services on or just after the startup of the server.
- Using the
TemplatePluginmixin plugins may inject their own components into the OctoPrint web interface.
UiPluginmixin allows plugins to completely replace the UI served by OctoPrint.
WizardPluginmixin allows plugins to report to OctoPrint whether the
wizardtemplates they define via the
TemplatePluginshould be displayed to the user, what details to provide to their respective wizard frontend components and what to do when the wizard is finished by the user.
For more detailed information on each of the available plugin mixins, please click on their respective links.