Preparing search index...

    Interface Plugin

    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(options?: { reason: PluginStopReason }): void | Promise<void>;
        registerWithRouter?(router: PluginRouter): void;
        signalKApiRoutes?(router: IRouter): IRouter;
    }
    Index
    schema enabledByDefault? uiSchema?
    id name
    start stop
    description? getOpenApi? statusMessage? signalKApiRoutes?
    registerWithRouter?
    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'
      }
    }
    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.

    • 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, after configuration changes and when the server stops. 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.

      options.reason says why the plugin is stopped, for a plugin whose cleanup depends on it: one that manages an external service may want to keep it running across a server restart but shut it down when the plugin is disabled. See PluginStopReason.

      Parameters

      Returns void | Promise<void>

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

    • 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.

      Routes registered directly on the router require admin authentication. To open a route up to readwrite or readonly users, register it through PluginRouter.access:

      plugin.registerWithRouter = (router) => {
        router.access('readonly').get('/data/:id', handler)
        router.access('readwrite').post('/data', handler)
        router.delete('/data/:id', handler) // no access() call — admin only
      }
      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

      Returns void

    On This Page
    Configuration
    Identification
    Lifecycle
    Other
    Rest API