signalk-server
Version:
An implementation of a [Signal K](http://signalk.org) server for boats.
577 lines (513 loc) • 33.1 kB
HTML
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Autopilot Providers - Signal K Server Documentation</title>
<!-- Custom HTML head -->
<meta name="description" content="A Guide for users and developers.">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="../../favicon.png">
<link rel="stylesheet" href="../../css/variables.css">
<link rel="stylesheet" href="../../css/general.css">
<link rel="stylesheet" href="../../css/chrome.css">
<link rel="stylesheet" href="../../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="../../highlight.css">
<link rel="stylesheet" href="../../tomorrow-night.css">
<link rel="stylesheet" href="../../ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<div id="body-container">
<!-- Provide site root to javascript -->
<script>
var path_to_root = "../../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var html = document.querySelector('html');
var sidebar = null;
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<a href="/" style="width:155px;height:30px;background-image:url(/signal-k-logo-image-text.svg);display:inline-block;background-repeat:no-repeat;background-position:center center;background-size:150px auto;"></a>
<ol class="chapter"><li class="chapter-item expanded affix "><a href="../../index.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">Getting Started</li><li class="chapter-item expanded "><a href="../../installation/install.html"><strong aria-hidden="true">1.</strong> Installation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../installation/raspberry_pi_installation.html"><strong aria-hidden="true">1.1.</strong> Installing on Raspberry Pi</a></li><li class="chapter-item expanded "><a href="../../installation/updating.html"><strong aria-hidden="true">1.2.</strong> Updating your installation</a></li><li class="chapter-item expanded "><a href="../../installation/command_line.html"><strong aria-hidden="true">1.3.</strong> Runtime environment & options</a></li></ol></li><li class="chapter-item expanded "><a href="../../security.html"><strong aria-hidden="true">2.</strong> Security</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../setup/generating_tokens.html"><strong aria-hidden="true">2.1.</strong> Generating tokens</a></li></ol></li><li class="chapter-item expanded "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="../../setup/configuration.html"><strong aria-hidden="true">3.</strong> Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../setup/seatalk/seatalk.html"><strong aria-hidden="true">3.1.</strong> Seatalk Connections</a></li></ol></li><li class="chapter-item expanded "><li class="part-title">Feature How Tos</li><li class="chapter-item expanded "><a href="../../features/anchoralarm/anchoralarm.html"><strong aria-hidden="true">4.</strong> Anchor Alarm</a></li><li class="chapter-item expanded "><a href="../../features/navdataserver/navdataserver.html"><strong aria-hidden="true">5.</strong> NMEA0183 Server</a></li><li class="chapter-item expanded "><a href="../../features/datalogging/datalogging.html"><strong aria-hidden="true">6.</strong> Data Logging</a></li><li class="chapter-item expanded affix "><li class="part-title">Support</li><li class="chapter-item expanded "><a href="../../support/help.html"><strong aria-hidden="true">7.</strong> Help & Support</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../support/faq.html"><strong aria-hidden="true">7.1.</strong> FAQs</a></li></ol></li><li class="chapter-item expanded "><a href="../../support/sponsor.html"><strong aria-hidden="true">8.</strong> Sponsor</a></li><li class="chapter-item expanded affix "><li class="part-title">Develop</li><li class="chapter-item expanded "><a href="../../develop/developer_notes.html"><strong aria-hidden="true">9.</strong> Notes for Developers</a></li><li class="chapter-item expanded "><a href="../../whats_new.html"><strong aria-hidden="true">10.</strong> What's New in V2</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../breaking_changes.html"><strong aria-hidden="true">10.1.</strong> Changes & Deprecations</a></li></ol></li><li class="chapter-item expanded "><a href="../../develop/webapps.html"><strong aria-hidden="true">11.</strong> WebApps</a></li><li class="chapter-item expanded "><a href="../../develop/plugins/server_plugin.html"><strong aria-hidden="true">12.</strong> Plugins</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../develop/plugins/deltas.html"><strong aria-hidden="true">12.1.</strong> Processing Data</a></li><li class="chapter-item expanded "><a href="../../develop/plugins/server_plugin_api.html"><strong aria-hidden="true">12.2.</strong> Server API</a></li><li class="chapter-item expanded "><a href="../../develop/plugins/resource_provider_plugins.html"><strong aria-hidden="true">12.3.</strong> Resource Providers</a></li><li class="chapter-item expanded "><a href="../../develop/rest-api/course_calculations.html"><strong aria-hidden="true">12.4.</strong> Course Providers</a></li><li class="chapter-item expanded "><a href="../../develop/plugins/autopilot_provider_plugins.html" class="active"><strong aria-hidden="true">12.5.</strong> Autopilot Providers</a></li></ol></li><li class="chapter-item expanded "><a href="../../develop/plugins/publishing.html"><strong aria-hidden="true">13.</strong> Publishing to the AppStore</a></li><li class="chapter-item expanded "><a href="../../develop/rest-api/open_api.html"><strong aria-hidden="true">14.</strong> REST APIs</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../develop/rest-api/course_api.html"><strong aria-hidden="true">14.1.</strong> Course API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../../develop/rest-api/course_calculations.html"><strong aria-hidden="true">14.1.1.</strong> Course Calculations</a></li></ol></li><li class="chapter-item expanded "><a href="../../develop/rest-api/resources_api.html"><strong aria-hidden="true">14.2.</strong> Resources API</a></li><li class="chapter-item expanded "><a href="../../develop/rest-api/notifications_api.html"><strong aria-hidden="true">14.3.</strong> Notifications API</a></li><li class="chapter-item expanded "><a href="../../develop/rest-api/autopilot_api.html"><strong aria-hidden="true">14.4.</strong> Autopilot API</a></li><li class="chapter-item expanded "><a href="../../develop/rest-api/anchor_api.html"><strong aria-hidden="true">14.5.</strong> Anchor API</a></li></ol></li><li class="chapter-item expanded "><a href="../../develop/contributing.html"><strong aria-hidden="true">15.</strong> Contribute</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<!-- Track and set sidebar scroll position -->
<script>
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
sidebarScrollbox.addEventListener('click', function(e) {
if (e.target.tagName === 'A') {
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
}
}, { passive: true });
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
sessionStorage.removeItem('sidebar-scroll');
if (sidebarScrollTop) {
// preserve sidebar scroll position when navigating via links within sidebar
sidebarScrollbox.scrollTop = sidebarScrollTop;
} else {
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
var activeSection = document.querySelector('#sidebar .active');
if (activeSection) {
activeSection.scrollIntoView({ block: 'center' });
}
}
</script>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Signal K Server Documentation</h1>
<div class="right-buttons">
<a href="../../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/SignalK/signalk-server/tree/master/docs/src" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="autopilot-provider-plugins"><a class="header" href="#autopilot-provider-plugins">Autopilot Provider plugins</a></h1>
<p><em>This document should be read in conjunction with the <a href="./server_plugin.html">SERVER PLUGINS</a> document as it contains additional information regarding the development of plugins that implement the Signal K Autopilot API.</em></p>
<hr />
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
<p>The Signal K Autopilot API defines endpoints under the path <code>/signalk/v2/api/vessels/self/autopilots</code> providing a way for all Signal K clients to perform common autopilot operations independent of the autopilot device in use. The API is defined in an <a href="/doc/openapi/?urls.primaryName=autopilot">OpenAPI</a> document.</p>
<p>Requests made to the Autopilot API are received by the Signal K Server, where they are validated and an authorisation check performed, before being passed on to a <strong>provider plugin</strong> to action the request on the autopilot device.</p>
<p>This de-coupling of request handling and autopilot communication provides the flexibility to support a variety of autopilot devices and ensures interoperability and reliabilty.</p>
<p>Autopilot API requests are passed to a <strong>provider plugin</strong> which will process and action the request facilitating communication with the autopilot device.</p>
<p>The following diagram provides an overview of the Autopilot API architectue.</p>
<img src="../../img/autopilot_provider.svg" width="600px">
<p><em>Autopilot API architecture</em></p>
<h2 id="provider-plugins"><a class="header" href="#provider-plugins">Provider Plugins:</a></h2>
<p>An autopilot provider plugin is a Signal K server plugin that implements the <strong>Autopilot Provider Interface</strong> which:</p>
<ul>
<li>Tells server the autopilot devices provided for by the plugin</li>
<li>Registers the methods used to action requests passed from the server to perform autopilot operations.</li>
</ul>
<p>The <code>AutopilotProvider</code> interface is defined in <em><code>@signalk/server-api</code></em></p>
<p>Multiple providers can be registered and each provider can manage one or more autopilot devices.</p>
<p><strong>Note: An Autopilot Provider plugin MUST:</strong></p>
<ul>
<li>Implement all Autopilot API interface methods.</li>
<li>Facilitate communication on the target autopilot device to send commands and retrieve both status and configuration information</li>
<li>Ensure the <code>engaged</code> path attribute value is maintained to reflect the operational status of the autopilot.</li>
<li>Map the <code>engage</code> and <code>disengage</code> operations to an appropriate autopilot device <code>state</code>.</li>
<li>Set the state as <code>off-line</code> if the autopilot device is not connected or unreachable.</li>
<li>Set the mode as <code>dodge</code> when the autopilot device is is in dodge mode.</li>
</ul>
<h3 id="registering-as-an-autopilot-provider"><a class="header" href="#registering-as-an-autopilot-provider">Registering as an Autopilot Provider</a></h3>
<p>A provider plugin must register itself with the Autopilot API during start up by calling the <code>registerAutopilotProvider</code>.</p>
<p>The function has the following signature:</p>
<pre><code class="language-typescript">app.registerAutopilotProvider(provider: AutopilotProvider, devices: string[])
</code></pre>
<p>where:</p>
<ul>
<li><code>provider</code>: is a valid <strong>AutopilotProvider</strong> object</li>
<li><code>devices</code>: is an array of identifiers indicating the autopilot devices managed by the plugin.</li>
</ul>
<p><em>Example: Plugin registering as an autopilot provider.</em></p>
<pre><code class="language-javascript">import { AutopilotProvider } from '@signalk/server-api'
module.exports = function (app) {
const plugin = {
id: 'mypluginid',
name: 'My autopilot Provider plugin'
}
const autopilotProvider: AutopilotProvider = {
getData: (deviceId) => { return ... },
getState: (deviceId) => { return ... },
setState: (state, deviceId) => { ... },
getMode: (deviceId) => { return ... },
setMode: (mode, deviceId) => { ... },
getTarget: (deviceId) => { return ... },
setTarget(value, deviceId) => { ... },
adjustTarget(value, deviceId) => { ... },
engage: (deviceId) => { ... },
disengage: (deviceId) => { ... },
tack:(direction, deviceId) => { ... },
gybe:(direction, deviceId) => { ... },
dodge:(value, deviceId) => { ... }
}
const pilots = ['pilot1', 'pilot2']
plugin.start = function(options) {
...
try {
app.registerAutopilotProvider(autopilotProvider, pilots)
}
catch (error) {
// handle error
}
}
return plugin
}
</code></pre>
<h3 id="sending-updates-and-notifications-from-autopilot-device"><a class="header" href="#sending-updates-and-notifications-from-autopilot-device">Sending Updates and Notifications from Autopilot device</a></h3>
<p>The Autopilot API is responsible for sending both update and notification <code>deltas</code> to Signal K clients.</p>
<p>Data received from an autopilot device, regardless of the communications protocol (NMEA2000, etc), should be sent to the Autopilot API by calling the <code>autopilotUpdate</code> interface method.</p>
<p>This will ensure:</p>
<ul>
<li>Default pilot status is correctly maintained</li>
<li><code>steering.autopilot.*</code> both V1 and V2 deltas are sent</li>
</ul>
<p><strong><em>Important! The values provided via <code>autopilotUpdate</code> will be sent in the relevant delta message, so ensure they are in the correct units (e.g. angles in radians, etc).</em></strong></p>
<p>The function has the following signature:</p>
<pre><code class="language-typescript">app.autopilotUpdate(deviceID: string, apInfo: {[key:string]: Value})
</code></pre>
<p>where:</p>
<ul>
<li><code>deviceId</code>: is the autopilot device identifier</li>
<li><code>appInfo</code>: object containing values keyed by <AutopilotInfo> attributes <em>(as defined in @signalk/server-api)</em></li>
</ul>
<p><em>Example Update:</em></p>
<pre><code class="language-javascript">app.autopilotUpdate('my-pilot', {
target: 1.52789,
mode: 'compass'
})
</code></pre>
<p>Notifications / Alarms are sent using one of the normalised alarm names below as the path and a <code>Notification</code> as the value.</p>
<ul>
<li>waypointAdvance</li>
<li>waypointArrival</li>
<li>routeComplete</li>
<li>xte</li>
<li>heading</li>
<li>wind</li>
</ul>
<p><em>Example Notification:</em></p>
<pre><code class="language-javascript">app.autopilotUpdate('my-pilot', {
alarm: {
path: 'waypointAdvance',
value: {
state: 'alert'
method: ['sound']
message: 'Waypoint Advance'
}
}
})
</code></pre>
<h3 id="provider-methods"><a class="header" href="#provider-methods">Provider Methods:</a></h3>
<p><strong><code>getData(deviceId)</code></strong>: This method returns an AutopilotInfo object containing the current data values and valid options for the supplied autopilot device identifier.</p>
<ul>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{AutopilotInfo}></code></p>
<p><em>Note: It is the responsibility of the autopilot provider plugin to map the value of <code>engaged</code> to the current <code>state</code>.</em></p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
GET /signalk/v2/api/vessels/self/autopilots/mypilot1
// AutopilotProvider method invocation
getData('mypilot1');
// Returns:
{
options: {
states: [
{
name: 'auto' // autopilot state name
engaged: true // actively steering
},
{
name: 'standby' // autopilot state name
engaged: false // not actively steering
}
]
modes: ['compass', 'gps', 'wind']
},
target: 0.326
mode: 'compass'
state: 'auto'
engaged: true
}
</code></pre>
<hr />
<p><strong><code>getState(deviceId)</code></strong>: This method returns the current state of the supplied autopilot device identifier. If the autopilot device is not connected or unreachable then <code>off-line</code> should be returned.</p>
<ul>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{string}></code></p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
GET /signalk/v2/api/vessels/self/autopilots/mypilot1/state
// AutopilotProvider method invocation
getState('mypilot1');
// Returns:
'auto'
</code></pre>
<hr />
<p><strong><code>setState(state, deviceId?)</code></strong>: This method sets the autopilot device with the supplied identifier to the supplied state value.</p>
<ul>
<li><code>state:</code> state value to set. Must be a valid state value.</li>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{void}></code></p>
<p>throws on error or if supplied state value is invalid.</p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
PUT /signalk/v2/api/vessels/self/autopilots/mypilot1/state {value: "standby"}
// AutopilotProvider method invocation
setState('standby', 'mypilot1');
</code></pre>
<hr />
<p><strong><code>getMode(deviceId)</code></strong>: This method returns the current mode of the supplied autopilot device identifier.</p>
<ul>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{string}></code></p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
GET /signalk/v2/api/vessels/self/autopilots/mypilot1/mode
// AutopilotProvider method invocation
getMode('mypilot1');
// Returns:
'compass'
</code></pre>
<hr />
<p><strong><code>setMode(mode, deviceId)</code></strong>: This method sets the autopilot device with the supplied identifier to the supplied mode value.</p>
<ul>
<li><code>mode:</code> mode value to set. Must be a valid mode value.</li>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{void}></code></p>
<p>throws on error or if supplied mode value is invalid.</p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
PUT /signalk/v2/api/vessels/self/autopilots/mypilot1/mode {value: "gps"}
// AutopilotProvider method invocation
setMode('gps', 'mypilot1');
</code></pre>
<hr />
<p><strong><code>setTarget(value, deviceId)</code></strong>: This method sets target for the autopilot device with the supplied identifier to the supplied value.</p>
<ul>
<li><code>value:</code> target value in radians.</li>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{void}></code></p>
<p>throws on error or if supplied target value is outside the valid range.</p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
PUT /signalk/v2/api/vessels/self/autopilots/mypilot1/target {value: 129}
// AutopilotProvider method invocation
setTarget(129, 'mypilot1');
</code></pre>
<hr />
<p><strong><code>adjustTarget(value, deviceId)</code></strong>: This method adjusts target for the autopilot device with the supplied identifier by the supplied value.</p>
<ul>
<li><code>value:</code> value in radians to add to current target value.</li>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{void}></code></p>
<p>throws on error or if supplied target value is outside the valid range.</p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
PUT /signalk/v2/api/vessels/self/autopilots/mypilot1/target {value: 2}
// AutopilotProvider method invocation
adjustTarget(2, 'mypilot1');
</code></pre>
<hr />
<p><strong><code>engage(deviceId)</code></strong>: This method sets the state of the autopilot device with the supplied identifier to a state that is actively steering the vessel.</p>
<ul>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{void}></code></p>
<p>throws on error.</p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
POST /signalk/v2/api/vessels/self/autopilots/mypilot1/engage
// AutopilotProvider method invocation
engage('mypilot1');
</code></pre>
<hr />
<p><strong><code>disengage(deviceId)</code></strong>: This method sets the state of the autopilot device with the supplied identifier to a state that is NOT actively steering the vessel.</p>
<ul>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{void}></code></p>
<p>throws on error.</p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
POST /signalk/v2/api/vessels/self/autopilots/mypilot1/disengage
// AutopilotProvider method invocation
disengage('mypilot1');
</code></pre>
<hr />
<p><strong><code>tack(direction, deviceId)</code></strong>: This method instructs the autopilot device with the supplied identifier to perform a tack in the supplied direction.</p>
<ul>
<li><code>direction</code>: 'port' or 'starboard'</li>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{void}></code></p>
<p>throws on error.</p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
POST /signalk/v2/api/vessels/self/autopilots/mypilot1/tack/port
// AutopilotProvider method invocation
tack('port', 'mypilot1');
</code></pre>
<hr />
<p><strong><code>gybe(direction, deviceId)</code></strong>: This method instructs the autopilot device with the supplied identifier to perform a gybe in the supplied direction.</p>
<ul>
<li><code>direction</code>: 'port' or 'starboard'</li>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{void}></code></p>
<p>throws on error.</p>
<p><em>Example:</em></p>
<pre><code class="language-javascript">// API request
POST /signalk/v2/api/vessels/self/autopilots/mypilot1/gybe/starboard
// AutopilotProvider method invocation
gybe('starboard', 'mypilot1');
</code></pre>
<hr />
<p><strong><code>dodge(value, deviceId)</code></strong>: This method instructs the autopilot device with the supplied identifier to enter / exit dodge mode and alter the current course by the supplied value (radians) direction.</p>
<ul>
<li><code>value</code>: +/- value in radians 'port (-ive)' or 'starboard' to change direction. <em>Setting the value to <code>null</code> indicates exit of dodge mode.</em></li>
<li><code>deviceId:</code> identifier of the autopilot device to query.</li>
</ul>
<p>returns: <code>Promise<{void}></code></p>
<p>throws on error.</p>
<p>To address different pilot behaviour, the <code>dodge</code> function can be used in the following ways:</p>
<p><strong>1. Enter dodge mode at the current course</strong></p>
<pre><code class="language-javascript">// API request
POST /signalk/v2/api/vessels/self/autopilots/mypilot1/dodge
// _AutopilotProvider method invocation
dodge(0, 'mypilot1');
</code></pre>
<p><strong>2. Enter dodge mode and change course</strong></p>
<pre><code class="language-javascript">// API request
PUT /signalk/v2/api/vessels/self/autopilots/mypilot1/dodge {"value": 5}
// AutopilotProvider method invocation
dodge(5, 'mypilot1');
</code></pre>
<p><strong>3. Cancel dodge mode</strong></p>
<pre><code class="language-javascript">// API request
DELETE /signalk/v2/api/vessels/self/autopilots/mypilot1/dodge
// AutopilotProvider method invocation
dodge(null, 'mypilot1');
</code></pre>
<hr />
<h3 id="unhandled-operations"><a class="header" href="#unhandled-operations">Unhandled Operations</a></h3>
<p>A provider plugin <strong>MUST</strong> implement <strong>ALL</strong> Autopilot API interface methods, regardless of whether the operation is supported or not.</p>
<p>For an operation that is not supported by the autopilot device, then the plugin should <code>throw</code> an exception.</p>
<p><em>Example:</em></p>
<pre><code class="language-typescript">{
// unsupported operation method definition
gybe: async (d, id) => {
throw new Error('Unsupprted operation!)
}
}
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../../develop/rest-api/course_calculations.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../../develop/plugins/publishing.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../../develop/rest-api/course_calculations.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="../../develop/plugins/publishing.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="../../elasticlunr.min.js"></script>
<script src="../../mark.min.js"></script>
<script src="../../searcher.js"></script>
<script src="../../clipboard.min.js"></script>
<script src="../../highlight.js"></script>
<script src="../../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>