Skip to content

Latest commit

 

History

History
376 lines (245 loc) · 6.24 KB

HTTP_API.md

File metadata and controls

376 lines (245 loc) · 6.24 KB

HTTP API Functions:

The api object provides methods to facilitate interaction with the Signal K HTTP API path for the preferred api version as defined with the version attribute.

e.g. /signalk/v1/api

Note: Use the connect() method prior to using any of these API functions!

SignalKClient: Class for interacting with Signal K server

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

  • observeResponse

Methods

  • get()
  • put()
  • post()
  • delete()
  • getMeta()
  • getSelf()
  • getSelfId()
  • raiseAlarm()
  • clearAlarm()

Methods

get(path)

Make a request to a path relative to the Signal K server HTTP API path. i.e. /signalk/v1/api.

Parameters:

  • path: path relative to HTTP API

Returns: Promise

Example:

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

...

// **** make HTTP API request ****
const response = await signalk.api.get('/resources/waypoints');

put()

Send a HTTP PUT request to a path relative to the Signal K server HTTP API path. i.e. /signalk/v1/api.

Overloaded method enables values to be supplied in the following ways:

put(path, value)

results in HTTP PUT '<host_>/signalk/v1/api/<path>' {value: <value>}_

Note: context is set to vessels.self if path does not start with vessels.

put(context, path, value)

results in HTTP PUT '<host_>/signalk/v1/api/<context>/<path>' {value: {<value>} }_

put(context, path, key, value)

results in HTTP PUT '<host_>/signalk/v1/api/<context>/<path>/<key>' {value: {<value>} }_

Parameters:

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

  • path: path to Signal K resource (slash or dotted notation)

  • key: name of attribute the value is being written to

  • value: value to be written

Returns: Promise

Example:

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

...
const response = await signalk.api.put(
    'self',
    'environment/outside', 
    'temperature', 
    '297.4'
);

post(path, value)

Send a HTTP POST request to a path relative to the Signal K server HTTP API path. i.e. /signalk/v1/api.

Parameters:

  • path: path to Signal K resource (slash or dotted notation)

  • value: value to be written

Returns: Promise

Example:

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

...
const response = await signalk.api.post(
    'resource/waypoints', 
    {
        "urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742ccaa": {
            "position": {"latitude":-35.02577800787516,"longitude":138.02825595260182},
            "feature": {
                "type":"Feature",
                "geometry": {
                    "type":"Point",
                    "coordinates":[138.02825595260182,-35.02577800787516]
                },
                "properties":{"name":"gds","cmt":""},
                "id":""
            }
        }
    }
);

delete(path)

Send a HTTP DELETE request to a path relative to the Signal K server HTTP API path. i.e. /signalk/v1/api.

Parameters:

  • path: path to Signal K resource (slash or dotted notation)

Returns: Promise

Example:

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

...
const response = await signalk.api.delete(
    'resource/waypoints/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742ccaa'
);

getMeta(context, path)

Returns the metadata for the specified context and path in the Signal K tree.

Parameters:

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

  • path: path to Signal K resource (slash or dotted notation)

Returns: Promise

Example:

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

...

// **** Meta data request ****
const value = await signalk.api.getMeta('self', 'navigation.speedOverGround');

getSelf()

Returns the contents of the Signal K tree pointed to by self.

Returns: Promise

Example:

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

...

const value = await signalk.api.getSelf();

getSelfId()

Returns the uuid of the self identity.

Returns: Promise

Example:

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

...

const value = await signalk.getSelfId();

Alarms

raiseAlarm(context, name, alarm)

Send stream update to raise an alarm of the supplied name.

Parameters:

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

  • name: String containing a name for the alarm or an AlarmType (see AlarmType below).

  • alarm: An Alarm object (see Alarm below)

Returns: Promise

Examples:

signalk.api.raiseAlarm(
  "self",
  "Anchor",
  new Alarm(
    "Anchor dragging!",
    AlarmState.alarm,
    true,
    true,
  ),
);

// ** using special alarm type **

signalk.api.raiseAlarm(
  "self",
  AlarmType.sinking,
  new Alarm(
    "SINKING",
    AlarmState.alarm,
    true,
    true,
  ),
);

clearAlarm(context, name)

Send stream update to clear the alarm of the supplied name.

Parameters:

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

  • name: Alarm name e.g.MOB, Anchor.

Returns: Promise

Examples:

signalk.api.clearAlarm("self", "MOB");

Alarm

Alarm object that encapsulates an alarm message for use with raiseAlarm() method.

new Alarm(<message>, <state>, <visual>, <sound>)

Parameters:

  • message: Alarm message text
  • state: An AlarmState value.
  • visual: true / false
  • sound: true / false

value

Attribute that returns a formatted value for use with raiseAlarm() method.

Example:

    let al= new Alarm(
        'Anchor drag alarm';,
        AlarmState.alarm,
        true, 
        true
    ) 

    signalk.api.raiseAlarm('self', 'Anchor', al);

AlarmState

Set of valid Signal K alarm state values.

  • normal
  • alert
  • warn
  • alarm
  • emergency

AlarmType

Special alarm types:

  • mob
  • fire
  • sinking
  • flooding
  • collision
  • grounding
  • listing
  • adrift
  • piracy
  • abandon