Third Party Plugins

This walkthrough describes how a basic DWC plugin can be developed with DWC v3.4 and newer.

Duet3D plugin repository

Additional information on how to submit your plugin for hosting on the Duet3D plugin repository is available here

Install NodeJS and packages

In order to develop custom plugins it is necessary to set up a working NodeJS installation first. Once installed, open a console in the root directory of DWC. Then install all the dependencies for DWC next by entering

npm install

This will download and install all the required packages to build DWC and potential third-party plugins.

Starting the dev server

Once there, start the dev server allowing you to connect to the remote Duet that is running either in standalone or SBC mode:

npm run serve

When everything has been compiled, you should be able to connect to your dev server via localhost:8080. Note that you cannot connect to a remote board running software version 3 before you enable CORS on it. To achieve this, connect to your Duet once and run

M586 C"*"

This will ensure that CORS requests from your browser are properly handled so that your localhost setup can establish an HTTP connection.

Components

Before you continue development, it is highly recommended to make yourself familiar with the following components used by DWC:

• Vue (for reactive components)

• Vuetify (UI framework with all the different components)

• Material Design Icons (icon collection for UI elements)

• Flexbox (HTML layout system)

• VueRouter (for SPA browsing/routes)*

• Vuex (for storing settings and object model data. The machine module is guaranteed to hold info of the current or default machine)*

• chart.js (for temp and layer charts)*

* optional

To get a better idea of the Vue(x) data structures, it is highly recommended to install the Vue DevTools browser add-on as well.

Creating a plugin

To set up a base for your new plugin, create a new sub-directory under src/plugins with an identifier of your choice. Make sure this identifier consists only of alphanumeric characters underscores. Other characters are not permitted.

There are two files which are mandatory for a DWC plugin:

• plugin.json
• index.js

Create both using a text editor.

plugin.json

The file plugin.json holds installation information for your plugin. Refer to the DSF Plugin documentation for further details about its format and how to bundle the plugin for installation. A very basic example for DWC-only plugin looks like this:

{
  "id": "DemoPlugin",
  "name": "Demo Plugin",
  "author": "Plugin Author",
  "version": "1.0.0",
  "license": "GPL-3.0-or-later",
  "homepage": "https://my.site.com",
  "dwcVersion": "auto"
}

Note that the dwcVersion of this file is set to auto. This means whenever you build the plugin using the npm run build-plugin script, auto is replaced with the DWC version from package.json. For stable releases you could also set this to 3.5 to target all 3.5.X releases, and for this purpose there is now the auto-major placeholder (supported from v3.5.0).

index.js

The file index.js is the main entry point of your plugin and it is executed as soon as your plugin is loaded. Here you can register your own DWC routes and tabs. You can look through the source code of the integrated plugins in src/plugins to see how this can be achieved. The EndstopsPlugin is another good starting point.

Check out the src/routes/index.js file to see how you can

• register custom menu categories (registerCategory)
• register custom menu items and routes (registerRoute)
• register custom settings tabs on the General or Machine-Specific pages (registerSettingTab)

Plugin import

To load your plugin, you must add a new import statement to src/plugins/index.js. At the end of this file, you can find this line:

	// Add your own plugins here during development...

add this block below it:

	new DwcPlugin({
		id: 'DemoPlugin',
		name: 'Demo Plugin',
		author: 'Plugin Author',
		version: '1.0.0',
		loadDwcResources: () => import(
			/* webpackChunkName: "DemoPlugin" */
			'./DemoPlugin/index.js'
		)
	}),

When you modify this block for your own plugin, make sure the webpackChunkName always matches your plugin id. If they do not match, the plugin cannot be built correctly.

Once there, you can start your new integrated plugin from the Settings -> Plugins page.

Build

When your plugin is complete and you've got it working well as an integrated plugin, you can turn it into an external one. To achieve this, open a console once again in the DWC root directory and run

npm run build-plugin DemoPlugin

This will generate a DemoPlugin-1.0.0.zip file in the dist folder that can be installed using the "Install Plugin" button on the Settings -> Plugins page.

Limitations

At present a DWC plugin can

• create new routes
• create new settings tabs
• add new menu items
• access the entire Vuex store including object model(s)
• import custom NPM packages
• use Vuetify components and icons from the mdi collection

but it cannot

• modify existing parts of the UI
• replace components
• hide other menu items
• use custom Webpack imports

Additional features are planned for future versions (v3.5+). If you need more API calls, either discuss them on the forum and consider opening a new PR on GitHub.