Writing a Plugin

All plugins must follow the following naming convention:

up_[name].py

The up_ stands for ultrasonics plugin, and is needed for the plugin to be detected. The plugin [name] must match the plugin name inside the handshake.

The included plugin up_skeleton is the basic plugin structure which you can copy.

Plugin Functions

Every plugin contains at least three vital components:

handshake

This is a dictionary which contains general information about the plugin, as outlined in the table below.

key	description
name	The name of the plugin. Must match the name of the file and containing folder.
description	A short description of the plugin.
type	A list containing the type of plugin, from "inputs", "outputs", "modifiers", "triggers". A plugin can have more than one type.
mode	A list containing the suitable plugin mode, either songs, or playlists.
version	The plugin version number (in string format). Use semantic versioning. Plugin updates will migrate existing plugin settings, unless the major version is different.
settings	A list of persistent global settings for the plugin. If your plugin doesn't need persistent settings, leave as "settings": []. For more info see the Settings Builders wiki page.

run(settings_dict, **kwargs)

The run function is called when your plugin is supposed to run. Input variables include:

variable	description
settings_dict	A dictionary containing the settings supplied for this instance of the plugin.
database	A dictionary containing the global persistent plugin settings.
global_settings	A dictionary containing global ultrasonics settings.
component	A string indicating the component the plugin is being used as. For example, if your plugin is suitable can run as type "inputs" or "outputs", this variable will contain "inputs" or "outputs".
applet_id	The unique ID of the applet which this instance of the plugin is part of.
songs_dict	If a modifier or output plugin, this list contains all the playlists gathered from input plugins. For more info see the songs_dict wiki page.

If the plugin is running as an input or modifier plugin, it must return a songs_dict, otherwise don't return anything.

builder(**kwargs)

The builder function is called when the plugin is selected during the applet build process. Input variables include:

variable	description
database	A dictionary containing the global persistent plugin settings.
global_settings	A dictionary containing global ultrasonics settings.
component	A string indicating the component the plugin is being used as.

It must return a settings_dict, which is used to configure this specific instance of the plugin. If there are no settings to configure, just return an empty string "".

test(database, **kwargs) (Optional)

If you want to ensure that the user has entered the global persistent settings correctly, include a test function. This function will run after the user has entered their settings. Supplied are the following input variables:

variable	description
database	A dictionary containing the global persistent plugin settings the user has just entered.
global_settings	A dictionary containing global ultrasonics settings.

If the function runs without error, the user will be allowed to save the database values. If an exception is raised, an error will display and the plugin's logs will be pushed to the browser console for debugging.

Logs

A log for the plugin can be created with the line:

log = logs.create_log(__name__)

Then, use standard Python logging, e.g. log.info(f"Looking for songs in playlist {playlist}").