Skip to content

Module Internals

Jump to bottom
Giedrius edited this page Jul 20, 2020 · 1 revision

patchbox-module.json

The most important file of a Patchbox Module is the patchbox-module.json. It contains essential information, like version info, display name, as well as the technical details like the various scripts for installing, launching, stopping and the list of system services the module depends on.

See the complete reference here.

Install Script

The provided install script should install any necessary software and files for the module to run. Debian packages are preferred for this. We may be able to provide hosting for your Debian package, if you think it should be on http://apt.blokas.io/, please contact us!

Of course your script may compile the source code if it must, but ideally, it shouldn't take too long to complete.

See MODEP for an example install script.

In case the script exits with non 0 value, the installation is considered failed.

If the version in the patchbox-module.json was incremented since the last time a module was installed, the install script will run again, and should be capable of upgrading the installed older version.

Launch Script & Services

A launcher script can be provided to start the desired software, especially if it must do something non-trivial. The script is invoked with the configured argument, if launch_mode is set to require one. See Pure Data for an example.

Alternatively, you may create systemd .service file(s) for your module and list them in the services section of the patchbox-module.json. These services will get started when activating the module. See MODEP module and its modep-mod-ui.service or modep-mod-host.service for .service file examples. See systemd documentation for information on its syntax and capabilities.

List Script

A list script can be set to provide possible start arguments for the module, usually a path to the patch/file to be started with the module.

The script should output the selections with one item per line.

See Pure Data for an example script.

Stop Script

On stopping, a stop script should stop the software that was started by the launch script.

See Pure Data for an exmaple script.

The systemd services are stopped automatically on module deactivation.

Custom Pisound Button Config

It's possible to provide a custom configuration for the Pisound's button - upon activating a Patchbox Module, the custom config is activated. When the module is deactivated, the previous system-wide config gets restored.

To get custom button actions for your module, place the scripts that should get triggered inside a pisound-btn subfolder of your module sources. (See ORAC for an example). Make sure the scripts have 'execute' permission, if not, you have to do chmod +x *.sh on the scripts.

Then create a pisound-btn.conf, referencing the custom button scripts using relative path to them in pisound-btn. See ORAC for an example.

And you have to mention this config availability in the patchbox-module.json file in the depends_on section:

...
"depends_on": [
    {
        "service": "pisound-btn.service",
        "config": "pisound-btn.conf"
    },
    ...
],
...

See ORAC's patchbox-module.json for an example.

Custom amidiauto Config

If your module requires particular MIDI routing rules to take place, a custom amidiauto.conf can be provided, to be enabled automatically on module activation. The previous config gets restored automatically on module deactivation.

To get custom amidiauto.conf, first create it in your module source, see ORAC for an example.

Then you have to reference it in the depends_on section of the patchbox-module.json:

...
"depends_on": [
    {
        "service": "amidiauto.service",
        "config": "amidiauto.conf"
    },
    ...
],
...

See ORAC's patchbox-module.json for an example.

Clone this wiki locally