Skip to content

Latest commit

 

History

History
1179 lines (789 loc) · 22.7 KB

README.md

File metadata and controls

1179 lines (789 loc) · 22.7 KB
Raw

Signal K client for Deno

signalk_client is a library to facilitate communication with a Signal K server.

It provides the following classes to interact with the Signal K HTTP and STREAM APIs as well as exposing STREAM Events:

api: class for interacting with Signal K HTTP API

stream: class for interacting with Signal K STREAM API

apps: class to enable interaction with applications installed on the Signal K server.

See signalk-client API below for details.

Usage

import { SignalKClient } from 'https://deno.land/x/signalk_client/mod.ts'

The simplest way to get started is to connect to a Signal K server and open a websocket to its data stream.

To do this:

  1. Use connectStream(...) to connect to the server and open the data stream.

  2. Subscribe to the stream events to process the received data

Example:

const signalk = new SignalKClient();

// **** Subscribe to Signal K Stream events ***

signalk.stream.events.on(
    'connect',
    (ev:Event) => {
        console.log('** Connect Event: ', ev);
    }
);

signalk.stream.events.on(
    'close',
    (ev:Event) => {
        console.log('** Close Event: ', ev);
    }
);

signalk.stream.events.on(
    'error',
    (ev:Event) => {
        console.log('** Error Event: ', ev);
    }
);

signalk.stream.events.on(
    'message',
    (ev:Event) => {
        console.log('** Message Event: ', ev);
    }
);

// **** CONNECT to Server and open STREAM ****
signalk.connectStream('192.168.99.100', 80, false, 'self');

Once connected you can then interact with both the STREAM and HTTP APIs in the following ways:

  • Use the stream object to interact with the websocket connection.
// **** send data to STREAM API ****
signalk.stream.send({..data..});
  • Use the api object to interact Signal K HTTP API path. /signalk/v1/api/

Example:

// **** make HTTP API request ****
try {
    const response = await signalk.api.get('vessels/self/navigation/position');
}
catch {
    ...
}

Connect and open Stream on Demand

If you want to just use the HTTP API or defer the connection to the STREAM API based on user interaction use the connect(..) method.

  1. Use connect(...) to connect to the server and perform endpoint discovery.

  2. When you are ready to connect to the STREAM API use openStream() ( or stream.open() ) with a null or undefined url parameter. This will cnnect to the discovered stream endpoint.

Example:

const signalk = new SignalKClient();

// **** Subscribe to Signal K Stream events ***

signalk.stream.events.on(
    'connect',
    (ev:Event) => {
        console.log('** Connect Event: ', ev);
    }
);

signalk.stream.events.on(
    'close',
    (ev:Event) => {
        console.log('** Close Event: ', ev);
    }
);

signalk.stream.events.on(
    'error',
    (ev:Event) => {
        console.log('** Error Event: ', ev);
    }
);

signalk.stream.events.on(
    'message',
    (ev:Event) => {
        console.log('** Message Event: ', ev);
    }
);

// **** CONNECT to Server ****
signalk.connect('192.168.99.100', 80, false, 'self');

... 

signalk.openStream( null, 'self');

OR

signalk.stream.open( null, 'self');

Use with non-HTTP enabled Signal K server

By default the connect methods will cause an HTTP request to be sent to the server /signalk path to discover the server's advertised endpoints.

To interact with the server without using endpoint discovery use the openStream(<hostname>, <port>) method specifying the host ip address and port.

Note: No HTTP endpoint discovery is performed when using openXX() methods and specifying a host.

Example:

const signalk = new SignalKClient();

// **** Subscribe to Signal K Stream events ***

signalk.stream.events.on(
    'connect',
    (ev:Event) => {
        console.log('** Connect Event: ', ev);
    }
);

signalk.stream.events.on(
    'close',
    (ev:Event) => {
        console.log('** Close Event: ', ev);
    }
);

signalk.stream.events.on(
    'error',
    (ev:Event) => {
        console.log('** Error Event: ', ev);
    }
);

signalk.stream.events.on(
    'message',
    (ev:Event) => {
        console.log('** Message Event: ', ev);
    }
);

// **** Open the STREAM ****
signalk.openStream('192.168.99.100', 80, false, 'self');

SignalKClient API

SignalKClient contains the following classes to interact with Signal K API's:

api: class for interacting with Signal K HTTP API

stream: class for interacting with Signal K STREAM API

apps: class to enable interaction with applications installed on the Signal K server.

Follow the links for the relevant documentation.

Attributes

  • server
  • version
  • authToken
  • uuid
  • signalkUuid
  • proxied

Methods

  • hello()
  • connect()
  • disconnect()
  • connectStream()
  • connectPlayback()
  • openStream()
  • openPlayback()
  • snapshot()
  • accessRequest()
  • checkAccessRequest()
  • get()
  • put()
  • post()
  • login()
  • logout()
  • isLoggedIn()
  • setAppId()
  • setAppVersion()
  • appDataVersions()
  • appDataKeys()
  • appDataGet()
  • appDataSet()
  • appDataPatch()

Attributes:

server:

Information returned from Signal K server hello response.

{
    endpoints: {},
    info: {},
    apiVersions: []
}

apiVersions Constains list of api versions supported by the Signal K server.

version:

Get / Set preferred Signal K API version to use when the server supports more than one version. This must be used prior to connecting to the server. If the Signal K server does not supports the specified version v1 will be used.

Note: Signal K API is currently only available in v1.

Example:

    // ** set target version **
    signalk.version=2;

    // ** connect to server **
    signalk.connect(...);

    // ** get the version currently in use **
    console.log(signalk.version)

authToken:

A token string to be used for authentication when interacting with the Signal K server.

Use the login() method to authenticate to the server and retrieve a token for the specified user.

Example:

signalk.authToken = "<auth_token_string>";

Once you have supplied an authToken it will be used for all subsequent operations.

uuid:

Returns a v4 UUID string

Example:

let uuid = signalk.uuid;

// returns 27b88354-9fe0-4952-9ce6-c9d4eaea6d9e

signalkUuid:

Returns a formatted Signal K resource identifier

Example:

let uuid = signalk.signalkUuid;

// returns urn:mrn:signalk:uuid:27b88354-9fe0-4952-9ce6-c9d4eaea6d9e

proxied:

Boolean value to indicate whether the Signal K server that is being connected to is behind a proxy server.

  • false (default): Uses endpoints received in the hello() response.

  • true: Replaces protocol, host & port values of endpoint values received in the hello() response with those from connection.

Example: proxied = false (default)

proxied = false;

// Signal K server url: http://myServer.org:3000
signalk.connect('myServer.org');

// hello response
{
    ...
    endpoints: {
        "signalk-http":"http://myServer.org:3000/signalk/v1/api/",
        "signalk-ws":"ws://myServer.org:3000/signalk/v1/stream"
    }
} 

// endpoints used are those received in hello response.

Example: proxied = true

proxied = true;

// Proxied Signal K server url: https://myServer.org:3100
signalk.connect('myServer.org', 3100, true);

//hello response 
{
    ...
    endpoints: {
        "signalk-http":"http://myServer.org:3000/signalk/v1/api/",
        "signalk-ws":"ws://myServer.org:3000/signalk/v1/stream"
    }
} 

// received endpoint values are modified to include the proxy url values.
endpoints: {
    "signalk-http":"https://myServer.org:3100/signalk/v1/api/",
    "signalk-ws":"wss://myServer.org:3100/signalk/v1/stream"
}

Methods:

hello(hostname, port, useSSL): Promise

Send discovery request to the Signal K server /signalk path.

Note: SignalKClient is not considered connected after using this method.

Parameters:

  • hostname: host name or ip address

  • port: port number

  • useSSL: true: uses secure socket protocols (https / wss)

Returns: Observable

Example:

// **** make Discovery request ****
const response = await signalk.hello("myServer", 80, false);

connect(hostname, port, useSSL, subscribe): Promise

This method performs the following:

  1. Issues a hello() request
  2. Populates the server attibute with the received data

Parameters:

  • hostname: host name or ip address

  • port: port number

  • useSSL: true: uses secure socket protocols (https / wss)

  • subscribe: Signal K subcription request value: 'all', 'self' or 'none'. (Uses server default if null)

Returns: Promise

Example:

const response = await signalk.connect("myServer", 80, false);

disconnect()

Disconnects from Signal K server and closes all connections.

Example:

signalk.disconnect();

connectStream(hostname, port, useSSL, subscribe): Promise<boolean>

Connect to Signal K server and and open a connection to the STREAM API after performing service endpoint discovery.

This method performs the following:

  1. Calls connect()
  2. Opens a connection to the discovered Stream endpoint.

Parameters:

  • hostname: host name or ip address

  • port: port number

  • useSSL: true: uses secure socket protocols (https / wss)

  • subscribe: Signal K subcription request value: 'all', 'self' or 'none'. (Uses server default if null)

Returns: Promise

Example:

// **** Subscribe to Signal K Stream events ***

signalk.stream.events.on(
    'connect',
    (ev:Event) => {
        console.log('** Connect Event: ', ev);
    }
);

signalk.stream.events.on(
    'close',
    (ev:Event) => {
        console.log('** Close Event: ', ev);
    }
);

signalk.stream.events.on(
    'error',
    (ev:Event) => {
        console.log('** Error Event: ', ev);
    }
);

signalk.stream.events.on(
    'message',
    (ev:Event) => {
        console.log('** Message Event: ', ev);
    }
);

// **** CONNECT to Delta Stream ****
signalk.connectStream('192.168.99.100', 80, false, 'self');

connectPlayback(hostname, port, useSSL, options): Promise<boolean>

Connect to Signal K server and and open a connection to the PLAYBACK STREAM API after performing service endpoint discovery.

This method performs the following:

  1. Calls connect()
  2. Calls openPlayback().

Parameters:

  • hostname: host name or ip address

  • port: port number

  • useSSL: true: uses secure socket protocols (https / wss)

  • options: Signal K Playback options

{ 
    startTime: *Date / Time to start playback from.
    playbackRate: A number defining the rate at which data is sent.
    subscribe: 'all', 'self' or 'none'. *(Uses server default if null)*
}

Returns: Promise

Example:

// **** Subscribe to Signal K Stream events ***

signalk.stream.events.on(
    'connect',
    (ev:Event) => {
        console.log('** Connect Event: ', ev);
    }
);

signalk.stream.events.on(
    'close',
    (ev:Event) => {
        console.log('** Close Event: ', ev);
    }
);

signalk.stream.events.on(
    'error',
    (ev:Event) => {
        console.log('** Error Event: ', ev);
    }
);

signalk.stream.events.on(
    'message',
    (ev:Event) => {
        console.log('** Message Event: ', ev);
    }
);  

// **** CONNECT to Playback Stream ****

const response = await signalk.connectPlayback('myServer', 80, false, {
    subscribe: 'self',
    playbackRate: 1,
    startTime: '2019-01-19T07:14:58Z'
});

openStream(url, subscribe, token)

Connect direct to Signal K server DELTA stream using the supplied parameters without performing endpoint discovery.

This method is for use when there is no HTTP API available.

Paramaters:

  • url: url of Signal K stream endpoint.

  • subscribe: Signal K subcription request value: 'all', 'self' or 'none'. (Uses server default if null)

  • token: Authentication token.

Returns: true or throws on error Subscribe to signalk.stream.eventsto receive results of actions.

// **** Subscribe to Signal K Stream events ***

signalk.stream.events.on(
    'connect',
    (ev:Event) => {
        console.log('** Connect Event: ', ev);
    }
);

signalk.stream.events.on(
    'close',
    (ev:Event) => {
        console.log('** Close Event: ', ev);
    }
);

signalk.stream.events.on(
    'error',
    (ev:Event) => {
        console.log('** Error Event: ', ev);
    }
);

signalk.stream.events.on(
    'message',
    (ev:Event) => {
        console.log('** Message Event: ', ev);
    }
);   

// **** Open the Signal K Stream ****
const result = await signalk.openStream( 'stream_url', 'self');

openPlayback(url, options, token)

Connect direct to Signal K server PLAYBACK stream using the supplied parameters without performing endpoint discovery.

This method is for use when there is no HTTP API available.

Paramaters:

  • url: url of Signal K playback endpoint.

  • options: Signal K Playback options

{ 
    startTime: *Date / Time to start playback from.
    playbackRate: A number defining the rate at which data is sent.
    subscribe: 'all', 'self' or 'none'. *(Uses server default if null)*
}
  • token: Authentication token.

Returns: true or throws on error. Subscribe to signalk.stream.events to receive results of actions.

// **** Subscribe to Signal K Stream events ***

signalk.stream.events.on(
    'connect',
    (ev:Event) => {
        console.log('** Connect Event: ', ev);
    }
);

signalk.stream.events.on(
    'close',
    (ev:Event) => {
        console.log('** Close Event: ', ev);
    }
);

signalk.stream.events.on(
    'error',
    (ev:Event) => {
        console.log('** Error Event: ', ev);
    }
);

signalk.stream.events.on(
    'message',
    (ev:Event) => {
        console.log('** Message Event: ', ev);
    }
);  

// **** CONNECT to Signal K Stream ****
const result = signalk.openStream( 'playback_url', {
    subscribe: 'self',
    playbackRate: 1,
    startTime: '2019-01-19T07:14:58Z'
});

get(path)

Make a HTTP request to a path relative to Signal K server root path. http(s)://server:port/.

Parameters:

  • path: path relative to Signal K srver root

Returns: Observable

Example:

// ** connect to server **
signalk.connect(...);

...

// **** make HTTP GET request ****
const response = await signalk.get('/plugins');

put(path, value)

Make a HTTP PUT request to a path relative to Signal K server root path. http(s)://server:port/.

Parameters:

  • path: path relative to Signal K srver root

  • value: Value to assign

Returns: Observable

Example:

// ** connect to server **
signalk.connect(...);

...

// **** make HTTP PUT request ****
const response = await signalk.put('/plugins/plugin-name/acton');

post(path, value)

Make a HTTP POST request to a path relative to Signal K server root path. http(s)://server:port/.

Parameters:

  • path: path relative to Signal K srver root

  • value: Value to assign

Returns: Observable

Example:

// ** connect to server **
signalk.connect(...);

...

// **** make HTTP POST request ****
const response = await signalk.post('/plugins/plugin-name/acton');

snapshot(context, time): Promise

History Snapshot Retrieval

Request from the Signal K server the part of the full model at the requested time.

Parameters:

  • context: Signal K context e.g. 'vessels.<uuid_>', 'self'_

  • time: date/time in ISO format eg: 2018-08-24T15:19:09Z

Returns: Promise

Example:

// ** connect to server **
signalk.connect(...);

...
const response = await signalk.snapshot(
    'self',
    new Date().toISOString()
);

accessRequest(name, id?): Promise

Access Request

Request access from the Signal K server.

Parameters:

  • name: name assigned to sensor / process e.g. 'mySensor'

  • id (optional): uuid of the request. If not supplied one will be generated

Returns: Promise containing status and href which is the path to check the staus of the request.

Example:

// ** connect to server **
signalk.connect(...);

...
const response = await signalk.accessRequest(
    'mysensor',
    '3c789f47-e15c-4e54-8020-85fc5b7cf2a6'
);

checkAccessRequest(href): Promise

Check status of Access Request

Request access from the Signal K server.

Parameters:

  • href: Value provided in accessRequest response.

Returns: Promise containing the current status of the request. If APPROVED will contain the token to be included with subsequest requests to the server.

Example:

// ** connect to server **
signalk.connect(...);

...
const response = await signalk.checkAccessRequest(
    '/signalk/v1/requests/42ed97b5-6acd-4848-8d25-99da710f1d91'
);

AUTHENTICATION:

Signal K servers with security enabled will require an authentication token assigned to the authToken attribute to access protected HTTP and STREAM APIs.

You can assign authToken:

  • A valid token you have already generated

  • Retrieve a token for a specific user by usingthe login() method providing username / password

Note: if a Signal K server has security enabled and you have not provided a valid authToken an Error event will be triggered to notify of this situation.

login(user, password): Promise

Authenticate with Signal K server and if successful apply the supplied JWT token value to authToken so it is used in subsequent operations so it is used in subsequent operations.

Parameters:

-user: User name

-password: User's password

Returns: Promise containing object.

{
  ok: true, //value of response ok
  status: 200, // value of response status
  token: '...' // auth token
}

Example:

const response = await signalk.connect(myserver, 80, false);

// ** login
const response = await signalk.login("myuser", "mypassword");

validate(): Promise

Validates / renews the auth token.

Parameters:

-user: User name

-password: User's password

Returns: Promise containing object.

{
  ok: true, //value of response ok
  status: 200, // value of response status
  token: '...' // auth token
}

Example:

const response = await signalk.connect(myserver, 80, false);

// ** login
const response = await signalk.validate();

logout()

Log out the current user.

Returns: Promise true= success, false= failure.

isLoggedIn(): Promise<boolean>

Returns true if user is logged in.

APPLICATION DATA:

Signal K servers with security enabled allow client applications to store data using the applicationData API path.

Applications can store data either per user using the user path or globally using the global path:

Use the following methods to interact with the applicationData API path.

See SignalK.org for details.

setAppId(appId)

Set the application id used for all subsequent applicationData actions.

This value will be used if appId is not supplied to a called method.

Parameters:

-appId: string value representing the application id.

Example:

signalk.setAppId("myapp");

setAppVersion(version)

Set the version used for all subsequent applicationData actions.

This value will be used if version is not supplied to a called method.

Parameters:

-version: string value representing the version of the data stored on the server.

Example:

signalk.setAppVersion("1.1");

appDataVersions(context, appId)

Return a list of versions under which data is stored for the supplied context.

Parameters:

-context: user or global. If not supplied defaults to user.

-appId: string value representing the application id. If not supplied the value set by setAppId() is used.

Returns: Promise

Example:

signalk.appDataVersions("user", "myapp");

appDataKeys(path, context, appId, version)

Return a list of keys stored under the path which data is stored for the supplied context, appId and version.

Parameters:

-path: pointer to the JSON key.

-context: user or global. If not supplied defaults to user.

-appId: string value representing the application id. If not supplied the value set by setAppId() is used.

-version: string value representing the stored data version. If not supplied the value set by setAppVerison() is used.

Returns: Promise.

Example:

signalk.appDataKeys("vessel/speed", "user", "myapp", "1.0");

appDataGet(path, context, appId, version)

Return the value stored at the supplied path for the supplied context, appId and version.

Parameters:

-path: pointer to the JSON key.

-context: user or global. If not supplied defaults to user.

-appId: string value representing the application id. If not supplied the value set by setAppId() is used.

-version: string value representing the stored data version. If not supplied the value set by setAppVerison() is used.

Returns: Promise.

Example:

signalk.appDataGet("vessel/speed", "user", "myapp", "1.0");

appDataSet(path, value, context, appId, version)

Store a value at the supplied path for the supplied context, appId and version.

Parameters:

-path: pointer to the JSON key under which to store the data.

-value: value to store.

-context: user or global. If not supplied defaults to user.

-appId: string value representing the application id. If not supplied the value set by setAppId() is used.

-version: string value representing the stored data version. If not supplied the value set by setAppVerison() is used.

Returns: Promise.

Example:

signalk.appDataSet("vessel/speed/sog", 1.5, "user", "myapp", "1.0");

appDataPatch(value, context, appId, version)

Add / Update / Remove multiple values at the supplied path for the supplied context, appId and version.

Parameters:

-value: Array of JSON Patch formatted objects representing the actions and values.

-context: user or global. If not supplied defaults to user.

-appId: string value representing the application id. If not supplied the value set by setAppId() is used.

-version: string value representing the stored data version. If not supplied the value set by setAppVerison() is used.

Returns: Promise.

Example:

signalk.appDataPatch(
  [
    { "op": "add", "path": "/vessel/speed", "value": { sog: 1.25 } },
    { "op": "remove", "path": "/vessel/speed/stw" },
  ],
  "user",
  "myapp",
  "1.0",
);