# Interface Plugin

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

A plugin can:

- Interact with the ServerAPI, including the full data model.
- Provide a webapp interface.
- Provide access to resources such as `route,` `waypoint`,`POI`, or `charts` via the Resources API by operating as a Resources Provider Plugin.
- Perform common autopilot operations by acting as an Autopilot Provider Plugin
- Perform course calculations by integrating with the Course API.
- process requests

Warning

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

#### Example

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;
    }

#### See

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;
}

- Defined in plugin.ts:53

##### Index

### Configuration

schema
enabledByDefault?
uiSchema?

### Identification

id
name

### Lifecycle

start
stop

### Other

description?
getOpenApi?
statusMessage?
signalKApiRoutes?

### Rest API

registerWithRouter?

## Configuration

### schema

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`.)

#### Example

      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
          }
        }
      };

- Defined in plugin.ts:132

### `Optional` enabledByDefault

enabledByDefault?: boolean

- Defined in plugin.ts:98

### `Optional` uiSchema

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

#### Example

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

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

- Defined in plugin.ts:153

## Identification

### id

id: string

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

- Defined in plugin.ts:60

### name

name: string

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

- Defined in plugin.ts:66

## Lifecycle

### start

- start(config: object, restart: (newConfiguration: object) => void): void

  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

  - Defined in plugin.ts:83

### stop

- stop(): void | Promise<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>

  - Defined in plugin.ts:93

## Other

### `Optional` description

description?: string

- Defined in plugin.ts:68

### `Optional` getOpenApi

getOpenApi?: () => object

- Defined in plugin.ts:178

### `Optional` statusMessage

statusMessage?: () => string | void

- Defined in plugin.ts:180

### `Optional` signalKApiRoutes

- signalKApiRoutes(router: IRouter): IRouter

  #### Parameters

  - router: IRouter

  #### Returns IRouter

  - Defined in plugin.ts:182

## Rest API

### `Optional` registerWithRouter

- registerWithRouter(router: IRouter): 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.

  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

  - Defined in plugin.ts:176