signalk-server
Version:
An implementation of a [Signal K](http://signalk.org) server for boats.
479 lines (434 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 API - 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"><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" class="active"><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="working-with-the-autopilot-api"><a class="header" href="#working-with-the-autopilot-api">Working with the Autopilot API</a></h1>
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
<p>The Autopilot API defines the <code>autopilots</code> path under <code>self</code> <em>(e.g. <code>/signalk/v2/api/vessels/self/autopilots</code>)</em> for representing information from one or more autopilot devices.</p>
<p>The Autopilot API provides a mechanism for applications to issue requests to autopilot devices to perform common operations. Additionally, when multiple autopilot devices are present, each autopilot device is individually addressable.</p>
<p><em>Note: Autopilot provider plugins are required to enable the API operation and provide communication with autopilot devices. See <a href="../plugins/autopilot_provider_plugins.html">Autopilot Provider Plugins</a> for details.</em></p>
<h2 id="common-operations"><a class="header" href="#common-operations">Common Operations</a></h2>
<p>The following operations are supported:</p>
<ul>
<li>Setting the operating mode</li>
<li>Engaging / Disengaging the pilot</li>
<li>Setting / adjusting the course</li>
<li>Dodging port / starboard</li>
<li>Tacking / Gybing</li>
</ul>
<h2 id="the-default-autopilot"><a class="header" href="#the-default-autopilot">The <em>Default</em> Autopilot</a></h2>
<p>To ensure a consistent API calling profile and to simplify client operations, the Autopilot API will assign a <em>default</em> autopilot device which is accessible using the path <code>/signalk/v2/api/vessels/self/autopilots/_default</code>.</p>
<ul>
<li>
<p>When only one autopilot is present, it will be automatically assigned as the <em>default</em>.</p>
</li>
<li>
<p>When multiple autopilots are present, and a <em>default</em> is yet to be assigned, one will be assigned when:</p>
<ul>
<li>An update is received from a provider plugin, the autopilot which is the source of the update will be assigned as the <em>default</em>.</li>
<li>An API request is received, the first autopilot device registered, is assigned as the <em>default</em>.</li>
<li>A request is sent to the <code>/_providers/_default</code> API endpoint <em>(see <a href="#setting-the-default-provider">Setting the Default Autopilot</a>)</em>.</li>
</ul>
</li>
</ul>
<h3 id="getting-the-default-autopilot-identifier"><a class="header" href="#getting-the-default-autopilot-identifier">Getting the Default Autopilot Identifier</a></h3>
<p>To get the id of the <em>default</em> autopilot, submit an HTTP <code>GET</code> request to <code>/signalk/v2/api/vessels/self/autopilots/_providers/_default</code>.</p>
<p><em>Example:</em></p>
<pre><code class="language-typescript">HTTP GET "/signalk/v2/api/vessels/self/autopilots/_providers/_default"
</code></pre>
<p><em>Response:</em></p>
<pre><code class="language-JSON">{
"id":"raymarine-id"
}
</code></pre>
<h3 id="setting-an-autopilot-as-the-default"><a class="header" href="#setting-an-autopilot-as-the-default">Setting an Autopilot as the Default</a></h3>
<p>To set / change the <em>default</em> autopilot, submit an HTTP <code>POST</code> request to <code>/signalk/v2/api/vessels/self/autopilots/_providers/_default/{id}</code> where <code>{id}</code> is the identifier of the autopilot to use as the <em>default</em>.</p>
<p><em>Example:</em></p>
<pre><code class="language-typescript">HTTP POST "/signalk/v2/api/vessels/self/autopilots/_providers/_default/raymarine-id"
</code></pre>
<p>The autopilot with the supplied id will now be the target of requests made to <code>/signalk/v2/api/vessels/self/autopilots/_default/*</code>.</p>
<h2 id="listing-the-available-autopilots"><a class="header" href="#listing-the-available-autopilots">Listing the available Autopilots</a></h2>
<p>To retrieve a list of installed autopilot devices, submit an HTTP <code>GET</code> request to <code>/signalk/v2/api/vessels/self/autopilots</code>.</p>
<p>The response will be an object containing all the registered autopilot devices, keyed by their identifier, detailing the <code>provider</code> it is registered by and whether it is assigned as the <em>default</em>.</p>
<pre><code class="language-typescript">HTTP GET "/signalk/v2/api/vessels/self/autopilots"
</code></pre>
<p><em>Example: List of registered autopilots showing that <code>pypilot-id</code> is assigned as the default.</em></p>
<pre><code class="language-JSON">{
"pypilot-id": {
"provider":"pypilot-provider",
"isDefault": true
},
"raymarine-id": {
"provider":"raymarine-provider",
"isDefault": false
}
}
</code></pre>
<h2 id="autopilot-deltas"><a class="header" href="#autopilot-deltas">Autopilot Deltas</a></h2>
<p>Deltas emitted by the Autopilot API will have the base path <code>steering.autopilot</code> with the <code>$source</code> containing the autopilot device identifier.</p>
<p><em>Example: Deltas for <code>autopilot.engaged</code> from two autopilots (<code>raymarine-id</code>).</em></p>
<pre><code class="language-JSON">{
"context":"vessels.self",
"updates":[
{
"$source":"pypilot-id",
"timestamp":"2023-11-19T06:12:47.820Z",
"values":[
{"path":"steering.autopilot.engaged","value":false}
]
},
{
"$source":"raymarine-id",
"timestamp":"2023-11-19T06:12:47.820Z",
"values":[
{"path":"steering.autopilot.engaged","value":true}
]
}
]
}
</code></pre>
<h2 id="autopilot-notifications"><a class="header" href="#autopilot-notifications">Autopilot Notifications</a></h2>
<p>The Autopilot API will provide notifications under the path <code>notifications.steering.autopilot</code> with the <code>$source</code> containing the autopilot device identifier.</p>
<p>A set of normalised notification paths are defined to provide a consistant way for client apps to receive and process alarm messages.</p>
<ul>
<li><code>waypointAdvance</code></li>
<li><code>waypointArrival</code></li>
<li><code>routeComplete</code></li>
<li><code>xte</code></li>
<li><code>heading</code></li>
<li><code>wind</code></li>
</ul>
<p><em>Example:</em></p>
<pre><code class="language-JSON">{
"context":"vessels.self",
"updates":[
{
"$source":"pypilot-id",
"timestamp":"2023-11-19T06:12:47.820Z",
"values":[
{
"path": "notifications.steering.autopilot.waypointAdvance",
"value": {
"state": "alert",
"method": ["sound"],
"message": "Waypoint Advance"
}
}
]
}
]
}
</code></pre>
<h2 id="autopilot-offline--unreachable"><a class="header" href="#autopilot-offline--unreachable">Autopilot offline / unreachable</a></h2>
<p>If an autopilot device is not connected or unreachable, the provider for that autopilot device will set the <code>state</code> of the device to <code>off-line</code>.</p>
<h2 id="autopilot-operations"><a class="header" href="#autopilot-operations">Autopilot Operations</a></h2>
<p>All API operations are invoked by issuing requests to:</p>
<ol>
<li><code>/signalk/v2/api/vessels/self/autopilots/_default/*</code></li>
</ol>
<p>Targets the default autopilot device.</p>
<p>OR</p>
<ol start="2">
<li><code>/signalk/v2/api/vessels/self/autopilots/{id}/*</code></li>
</ol>
<p>Target the autopilot with the supplied <code>{id}</code></p>
<p><em>Example:</em></p>
<pre><code class="language-typescript">HTTP GET "/signalk/v2/api/vessels/self/autopilots/_default/state"
HTTP GET "/signalk/v2/api/vessels/self/autopilots/pypilot-id/mode"
</code></pre>
<h3 id="retrieving-autopilot-status"><a class="header" href="#retrieving-autopilot-status">Retrieving Autopilot Status</a></h3>
<p>To retrieve the current autopilot configuration as well as a list of available options for <code>state</code> and <code>mode</code> selections, submit an HTTP <code>GET</code> request to <code>/signalk/v2/api/vessels/self/autopilots/{id}</code>.</p>
<pre><code class="language-typescript">HTTP GET "/signalk/v2/api/vessels/self/autopilots/{id}"
</code></pre>
<p><em>Response:</em></p>
<pre><code class="language-JSON">{
"options":{
"state":["enabled","disabled"],
"mode":["gps","compass","wind"]
},
"state":"disabled",
"mode":"gps",
"target": 0,
"engaged": false
}
</code></pre>
<p>Where:</p>
<ul>
<li><code>options</code> contains arrays of valid <code>state</code> and <code>mode</code> selection options</li>
<li><code>state</code> represents the current state of the device</li>
<li><code>mode</code> represents the current mode of the device</li>
<li><code>target</code> represents the current target value with respect to the selected <code>mode</code></li>
<li><code>engaged</code> will be true when the autopilot is actively steering the vessel.</li>
</ul>
<h3 id="setting-the-autopilot-state"><a class="header" href="#setting-the-autopilot-state">Setting the Autopilot State</a></h3>
<p>Autopilot state can be set by submitting an HTTP <code>PUT</code> request to the <code>/signalk/v2/api/vessels/self/autopilots/{id}/state</code> endpoint containing a value from the list of available states.</p>
<pre><code class="language-typescript">HTTP PUT "/signalk/v2/api/vessels/self/autopilots/{id}/state" {"value": "disabled"}
</code></pre>
<h3 id="getting-the-autopilot-state"><a class="header" href="#getting-the-autopilot-state">Getting the Autopilot State</a></h3>
<p>The current autopilot state can be retrieved by submitting an HTTP <code>GET</code> request to the <code>/signalk/v2/api/vessels/self/autopilots/{id}/state</code> endpoint.</p>
<pre><code class="language-typescript">HTTP GET "/signalk/v2/api/vessels/self/autopilots/{id}/state"
</code></pre>
<p><em>Response:</em></p>
<pre><code class="language-JSON">{
"value":"enabled",
}
</code></pre>
<h3 id="setting-the-autopilot-mode"><a class="header" href="#setting-the-autopilot-mode">Setting the Autopilot Mode</a></h3>
<p>Autopilot mode can be set by submitting an HTTP <code>PUT</code> request to the <code>/signalk/v2/api/vessels/self/autopilots/{id}/mode</code> endpoint containing a value from the list of available modes.</p>
<pre><code class="language-typescript">HTTP PUT "/signalk/v2/api/vessels/self/autopilots/{id}/mode" {"value": "gps"}
</code></pre>
<h3 id="getting-the-autopilot-mode"><a class="header" href="#getting-the-autopilot-mode">Getting the Autopilot Mode</a></h3>
<p>The current autopilot mode can be retrieved by submitting an HTTP <code>GET</code> request to the <code>mode</code> endpoint.</p>
<pre><code class="language-typescript">HTTP GET "/signalk/v2/api/vessels/self/autopilots/{id}/mode"
</code></pre>
<p><em>Response:</em></p>
<pre><code class="language-JSON">{
"value":"gps",
}
</code></pre>
<h3 id="setting-the-target-value"><a class="header" href="#setting-the-target-value">Setting the Target value</a></h3>
<p>Autopilot target value can be set by submitting an HTTP <code>PUT</code> request to the <code>/signalk/v2/api/vessels/self/autopilots/{id}/target</code> endpoint containing the desired value.</p>
<p><em>Note: The value supplied should be a number within the valid range for the selected <code>mode</code>.</em></p>
<pre><code class="language-typescript">// Set target to 129 degrees
HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target" {"value": 129, "units": "deg"}
// Set target to 0.349066 radians (20 degrees)
HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target" {"value": 0.349066}
</code></pre>
<p>The target value can be adjusted a +/- value by submitting an HTTP <code>PUT</code> request to the <code>/signalk/v2/api/vessels/self/autopilots/{id}/target/adjust</code> endpoint with the value to add to the current <code>target</code> value.</p>
<pre><code class="language-typescript">// Adjust target 2 degrees port
HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target/adjust" {"value": -2, , "units": "deg"}
// Adjust target 0.0349066 radians (2 degrees) starboard
HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target/adjust" {"value": 0.0349066}
</code></pre>
<h3 id="getting-the-current-target-value"><a class="header" href="#getting-the-current-target-value">Getting the current Target value</a></h3>
<p>The current autopilot target value <em>(in radians)</em> can be retrieved by submitting an HTTP <code>GET</code> request to the <code>target</code> endpoint.</p>
<pre><code class="language-typescript">HTTP GET "/signalk/v2/api/vessels/self/autopilots/{id}/target"
</code></pre>
<p><em>Response:</em></p>
<pre><code class="language-JSON">{
"value": 2.2345,
}
</code></pre>
<h3 id="engaging--disengaging-the-autopilot"><a class="header" href="#engaging--disengaging-the-autopilot">Engaging / Disengaging the Autopilot</a></h3>
<h4 id="engaging-the-autopilot"><a class="header" href="#engaging-the-autopilot">Engaging the autopilot</a></h4>
<p>An autopilot can be engaged by <a href="#setting-the-state">setting it to a speciifc <code>state</code></a> but it can also be engaged more generically by submitting an HTTP <code>POST</code> request to the <code>/signalk/v2/api/vessels/self/autopilots/{id}/engage</code> endpoint.</p>
<pre><code class="language-typescript">HTTP POST "/signalk/v2/api/vessels/self/autopilots/{id}/engage"
</code></pre>
<p><em>Note: The resultant <code>state</code> into which the autopilot is placed will be determined by the <strong>provider plugin</strong> and the autopilot device it is communicating with.</em></p>
<h4 id="disengaging-the-autopilot"><a class="header" href="#disengaging-the-autopilot">Disengaging the autopilot</a></h4>
<p>An autopilot can be disengaged by <a href="#setting-the-state">setting it to a speciifc <code>state</code></a> but it can also be disengaged more generically by submitting an HTTP <code>POST</code> request to the <code>/signalk/v2/api/vessels/self/autopilots/{id}/disengage</code> endpoint.</p>
<pre><code class="language-typescript">HTTP POST "/signalk/v2/api/vessels/self/autopilots/{id}/disengage"
</code></pre>
<p><em>Note: The resultant <code>state</code> into which the autopilot is placed will be determined by the <strong>provider plugin</strong> and the autopilot device it is communicating with.</em></p>
<h3 id="perform-a-tack"><a class="header" href="#perform-a-tack">Perform a Tack</a></h3>
<p>To send a command to the autopilot to perform a tack in the required direction, submit an HTTP <code>POST</code> request to <code>./autopilots/{id}/tack/{direction}</code> where <em>direction</em> is either <code>port</code> or <code>starboard</code>.</p>
<p><em>Example: Tack to Port</em></p>
<pre><code class="language-typescript">HTTP POST "/signalk/v2/api/vessels/self/autopilots/{id}/tack/port"
</code></pre>
<p><em>Example: Tack to Starboard</em></p>
<pre><code class="language-typescript">HTTP POST "/signalk/v2/api/vessels/self/autopilots/{id}/tack/starboard"
</code></pre>
<h3 id="perform-a-gybe"><a class="header" href="#perform-a-gybe">Perform a Gybe</a></h3>
<p>To send a command to the autopilot to perform a gybe in the required direction, submit an HTTP <code>POST</code> request to <code>/signalk/v2/api/vessels/self/autopilots/{id}/gybe/{direction}</code> where <em>direction</em> is either <code>port</code> or <code>starboard</code>.</p>
<p><em>Example: Gybe to Port</em></p>
<pre><code class="language-typescript">HTTP POST "/signalk/v2/api/vessels/self/autopilots/{id}/gybe/port"
</code></pre>
<p><em>Example: Gybe to Starboard</em></p>
<pre><code class="language-typescript">HTTP POST "/signalk/v2/api/vessels/self/autopilots/{id}/gybe/starboard"
</code></pre>
<h3 id="dodging-obstacles"><a class="header" href="#dodging-obstacles">Dodging Obstacles</a></h3>
<p>To address the various methods that the <code>dodge</code> function could be invoked on pilot devices, the API provides the following endpoints to provide the widest coverage possible:</p>
<p><strong>To enter dodge mode at the current course</strong></p>
<pre><code class="language-javascript">POST /signalk/v2/api/vessels/self/autopilots/{id}/dodge
</code></pre>
<p><strong>To enter dodge mode and change course by 5 degrees starboard</strong></p>
<pre><code class="language-javascript">PUT /signalk/v2/api/vessels/self/autopilots/{id}/dodge {"value": 5, "units": "deg"}
</code></pre>
<p><strong>To enter dodge mode and change course by 5 degrees port</strong></p>
<pre><code class="language-javascript">PUT /signalk/v2/api/vessels/self/autopilots/{id}/dodge {"value": -5, "units": "deg"}
</code></pre>
<p><strong>To cancel dodge mode</strong></p>
<pre><code class="language-javascript">DELETE /signalk/v2/api/vessels/self/autopilots/{id}/dodge
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../../develop/rest-api/notifications_api.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/rest-api/anchor_api.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/notifications_api.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/rest-api/anchor_api.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>