Signal K
    Preparing search index...

    Interface Plugin

    Plugins are components that extend functionality of the server and can be installed via the Signal K AppStore.

    A plugin can:

    Warning

    Typing is incomplete. If you find a missing or inaccurate type, please report it.

    Signal K server plugins are NodeJs javascript or typescript projects that return an object that implements this interface.

    import { Plugin, ServerAPI } from '@signalk/server-api';

    module.exports = (app: ServerAPI): Plugin => {
      const plugin: Plugin = {
        id: 'my-signalk-plugin',
        name: 'My Great Plugin',
        start: (settings, restartPlugin) => {
          // start up code goes here.
        },
        stop: () => {
          // shutdown code goes here.
        },
        schema: () => {
          properties: {
            // plugin configuration goes here
          }
        }
      };

      return plugin;
    }

    Developing Server Plugins

    interface Plugin {
        id: string;
        name: string;
        schema: object | (() => object);
        description?: string;
        enabledByDefault?: boolean;
        getOpenApi?: () => object;
        statusMessage?: () => string | void;
        uiSchema?: object | (() => object);
        start(config: object, restart: (newConfiguration: object) => void): void;
        stop(): void | Promise<void>;
        registerWithRouter(router: IRouter): void;
        signalKApiRoutes(router: IRouter): IRouter;
    }
    Index

    Configuration

    schema enabledByDefault? uiSchema?

    Identification

    id name

    Lifecycle

    start stop

    Other

    description? getOpenApi? statusMessage? signalKApiRoutes?

    Rest API

    registerWithRouter?

    Configuration

    schema: object | (() => object)

    A JSON Schema object describing the structure of the configuration data.

    This is used by the server to render the plugin's configuration screen in the Admin UI. The configuration data is stored by the server in $SIGNALK_NODE_CONFIG_DIR/plugin-config-data/<plugin-name>.json. (Default value of SIGNALK_NODE_CONFIG_DIR is $HOME/.signalk.)

      plugin.schema = {
        type: 'object',
        required: ['some_string', 'some_other_number'],
        properties: {
          some_string: {
            type: 'string',
            title: 'Some string that the plugin needs'
          },
          some_number: {
            type: 'number',
            title: 'Some number that the plugin needs',
            default: 60
          },
          some_other_number: {
            type: 'number',
            title: 'Some other number that the plugin needs',
            default: 5
          }
        }
      };
    enabledByDefault?: boolean
    uiSchema?: object | (() => object)

    A uiSchema object which is used to control how the user interface is rendered in the Admin UI.

    For more information, see react-jsonschema-form-extras

    Make all data in an object called 'myObject' collapsible:

    uiSchema['myObject'] = {
      'ui:field': 'collapsible',
      collapse: {
        field: 'ObjectField',
        wrapClassName: 'panel-group'
      }
    }

    Identification

    id: string

    Used to identify the plugin in the server, for example when storing the plugin's configuration and in http endpoints.

    name: string

    Human oriented name for the plugin. This is used in the server's plugin configuration UI.

    Lifecycle

    • This function is called to start the plugin.

      It is called:

      • during server startup for enabled plugins (by configuration or by default)
      • when a plugin is enabled in the admin UI
      • after stop when the configuration of an enabled plugin has been updated in the admin UI

      Parameters

      • config: object

        the configuration data entered via the Plugin Config screen

      • restart: (newConfiguration: object) => void

        a function that can be called by the plugin to restart itself

      Returns void

    • This function is called when the plugin is disabled or after configuration changes. Use this function to "clean up" the resources consumed by the plugin i.e. unsubscribe from streams, stop timers / loops and close devices. If there are asynchronous operations in your plugin's stop implementation you should return a Promise that resolves when stopping is complete.

      Returns void | Promise<void>

    Other

    description?: string
    getOpenApi?: () => object
    statusMessage?: () => string | void

    • Parameters

      • router: IRouter

      Returns IRouter

    Rest API

    • Plugins can implement this method to provide an API. Like start and stop, this function will be called during plugin startup with an Express router as the parameter.

      The router will be mounted at /plugins/<pluginId> and you can use standard Express (.get() .post() .use(), etc) methods to add HTTP path handlers.

      Note

      GET /plugins/<pluginid> and POST /plugins/<pluginid>/configure are reserved by server (see below).

      It should be noted that Express does not have a public API for deregistering subrouters, so stop does not do anything to the router.

      If a plugin does provide an API, it is strongly recommended that it implement getOpenApi to document its operation. Doing so promotes interoperability with other plugins / webapps by making it easy to find and use the functionality built into plugins. It is also a means to avoid duplication, promote reuse and the possibility of including them in the Signal K specification.

      Parameters

      • router: IRouter

      Returns void

    On This Page

    Configuration
    Identification
    Lifecycle
    Other
    Rest API