signalk-server
Version:
An implementation of a [Signal K](http://signalk.org) server for boats.
463 lines (422 loc) • 31.4 kB
HTML
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Course 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" class="active"><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="working-with-the-course-api"><a class="header" href="#working-with-the-course-api">Working with the Course API</a></h1>
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
<p>The <em>Course API</em> provides common course operations under the path <code>/signalk/v2/api/vessels/self/navigation/course</code> ensuring that all related Signal K data model values are maintained and consistent. This provides a set of data that can be confidently used for <em>course calculations</em> and <em>autopilot operation</em>.</p>
<p>Additionally, the Course API persists course information on the server to ensure data is not lost in the event of a server restart.</p>
<p>Client applications use <code>HTTP</code> requests (<code>PUT</code>, <code>GET</code>,<code>DELETE</code>) to perform operations and retrieve course data.</p>
<p>The Course API also listens for destination information in the NMEA stream and will set / clear the destination accordingly <em>(e.g. NMEA0183 RMB sentence, NMEA2000 PGN 129284)</em>. See <a href="#Configuration">Configuration</a> for more details.</p>
<p><em>Note: You can view the <em>Course API</em> OpenAPI definition in the Admin UI (Documentation => OpenApi).</em></p>
<hr />
<h2 id="setting-a-course"><a class="header" href="#setting-a-course">Setting a Course</a></h2>
<p>The Course API provides endpoints for:</p>
<ol>
<li>Navigate to a location <em>(lat, lon)</em></li>
<li>Navigate to a waypoint <em>(href to waypoint resource)</em></li>
<li>Follow a Route <em>(href to a route resource)</em>.</li>
</ol>
<h3 id="1-navigate-to-a-location"><a class="header" href="#1-navigate-to-a-location">1. Navigate to a Location</a></h3>
<p>To navigate to a point submit a HTTP <code>PUT</code> request to <code>/signalk/v2/api/vessels/self/navigation/course/destination</code> and supply the latitude & longitude of the destination point.</p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/destination' {"position": {"latitude": -60.5, "longitude": -166.7}}
</code></pre>
<h3 id="2-navigate-to-a-waypoint"><a class="header" href="#2-navigate-to-a-waypoint">2. Navigate to a Waypoint</a></h3>
<p>To navigate to a point submit a HTTP <code>PUT</code> request to <code>/signalk/v2/api/vessels/self/navigation/course/destination</code> and supply a reference to a waypoint resource entry under <code>/resources/waypoints</code></p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/destination' {"href": "/resources/waypoints/5242d307-fbe8-4c65-9059-1f9df1ee126f"}
</code></pre>
<h3 id="3-follow-a-route"><a class="header" href="#3-follow-a-route">3. Follow a Route</a></h3>
<p>To follow a route submit a HTTP <code>PUT</code> request to <code>/signalk/v2/api/vessels/self/navigation/course/activeRoute</code> and supply a reference to a route resource entry under <code>/resources/routes</code>.</p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/activeRoute' {"href": "/resources/routes/5242d307-fbe8-4c65-9059-1f9df1ee126f"}
</code></pre>
<p>Additional parameters can be set when following a route including:</p>
<ul>
<li>Defining the point along the route to start at</li>
<li>The direction to follow the route (forward / reverse)</li>
</ul>
<p><em>Example: Following a route in reverse direction:</em></p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/activeRoute'
{
"href": "/resources/routes/5242d307-fbe8-4c65-9059-1f9df1ee126f",
"reverse": true
}
</code></pre>
<h4 id="advancing-along-a-route"><a class="header" href="#advancing-along-a-route">Advancing along a Route</a></h4>
<p>As progress along a route is made, you can use the following endpoints to update the destination.</p>
<p>To set the destination to the next point along the route:</p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/activeRoute/nextPoint'
</code></pre>
<p>To advance the destination to a point <code>n</code> places beyond the current destination point, supply a positive number representing the number of points to advance:</p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/activeRoute/nextPoint' {"value": 2}
</code></pre>
<p><em>Sets destination to the point after the next in sequence.</em></p>
<p>To set the destination to the previous point along the route:</p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/activeRoute/nextPoint' {"value": -1}
</code></pre>
<p>To set the destination to a point <code>n</code> places prior the current destination point, supply a negative number representing the number of points prior:</p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/activeRoute/nextPoint' {"value": -2}
</code></pre>
<p><em>Sets destination to the point two prior to the current destination.</em></p>
<p>To set the destination to a specific point along the route, supply the zero-based index of the point:</p>
<p><em>Example: 4th point along the route.</em></p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/activeRoute/pointIndex' {"value": 3}
</code></pre>
<p><em>Value contains the 'zero-based' index of the point along the route (i.e. 0 = 1st point, 1 = 2nd point, etc.)</em></p>
<p>To reverse the direction along the route:</p>
<pre><code class="language-typescript">HTTP PUT 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/activeRoute/reverse'
</code></pre>
<h4 id="delta-messages"><a class="header" href="#delta-messages">Delta Messages</a></h4>
<p>The Course API emits delta messages with the following paths when course information has been changed.</p>
<p><em>Note: Delta values reflect the relevant property of the Course Information data object as detailed in the
<a href="#retrieving-course-information">Retrieving Course Information</a> section.</em></p>
<ul>
<li><code>navigation.course.startTime</code></li>
<li><code>navigation.course.targetArrivalTime</code></li>
<li><code>navigation.course.arrivalCircle</code></li>
<li><code>navigation.course.activeRoute</code></li>
<li><code>navigation.course.nextPoint</code></li>
<li><code>navigation.course.previousPoint</code></li>
</ul>
<h2 id="retrieving-course-information"><a class="header" href="#retrieving-course-information">Retrieving Course Information</a></h2>
<p>Course information is retrieved by submitting a HTTP <code>GET</code> request to <code>/signalk/v2/api/vessels/self/navigation/course</code>.</p>
<pre><code class="language-typescript">HTTP GET 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course'
</code></pre>
<p>The contents of the response will reflect the operation used to set the current course. The <code>nextPoint</code> & <code>previousPoint</code> sections will always contain values but <code>activeRoute</code> will only contain values when a route is being followed.</p>
<h4 id="1-operation-navigate-to-a-location-lat-lon"><a class="header" href="#1-operation-navigate-to-a-location-lat-lon">1. Operation: Navigate to a location <em>(lat, lon)</em></a></h4>
<p><em>Example response:</em></p>
<pre><code class="language-JSON">{
"startTime": "2023-01-27T01:47:39.785Z",
"targetArrivalTime": "2022-06-10T01:29:27.592Z",
"arrivalCircle": 4000,
"activeRoute": null,
"nextPoint": {
"type": "Location",
"position": {
"latitude": -34.92084502261776,
"longitude": 131.54823303222656
}
},
"previousPoint": {
"type":"VesselPosition",
"position": {
"latitude": -34.82084502261776,
"longitude": 131.04823303222656
}
}
}
</code></pre>
<h4 id="2-operation-navigate-to-a-waypoint-href-to-waypoint-resource"><a class="header" href="#2-operation-navigate-to-a-waypoint-href-to-waypoint-resource">2. Operation: Navigate to a waypoint <em>(href to waypoint resource)</em></a></h4>
<p><em>Example response:</em></p>
<pre><code class="language-JSON">{
"startTime": "2023-01-27T01:47:39.785Z",
"targetArrivalTime": "2022-06-10T01:29:27.592Z",
"arrivalCircle": 4000,
"activeRoute": null,
"nextPoint": {
"href": "/resources/waypoints/f24d72e4-e04b-47b1-920f-66b78e7b033e",
"type": "Waypoint",
"position": {
"latitude": -34.92084502261776,
"longitude": 131.54823303222656
}
},
"previousPoint": {
"type":"VesselPosition",
"position": {
"latitude": -34.82084502261776,
"longitude": 131.04823303222656
}
}
}
</code></pre>
<h4 id="3-operation-follow-a-route-href-to-a-route-resource"><a class="header" href="#3-operation-follow-a-route-href-to-a-route-resource">3. Operation: Follow a Route <em>(href to a route resource)</em>.</a></h4>
<p><em>Example response:</em></p>
<pre><code class="language-JSON">{
"startTime": "2023-01-27T01:47:39.785Z",
"targetArrivalTime": "2022-06-10T01:29:27.592Z",
"arrivalCircle": 1000,
"activeRoute": {
"href": "/resources/routes/e24d72e4-e04b-47b1-920f-66b78e7b0331",
"pointIndex": 0,
"pointTotal": 5,
"reverse": false,
"name": "my route",
"waypoints": [
{
"latitude": -34.92084502261776,
"longitude": 131.54823303222656
},
{
"latitude": -34.86621482446046,
"longitude": 132.10166931152344,
},
{
"latitude": -34.6309479733581,
"longitude": 132.23350524902344
},
{
"latitude": -34.63546778783319,
"longitude": 131.8867492675781
},
{
"latitude": -34.71000915922492,
"longitude": 131.82289123535156
}
]
},
"nextPoint": {
"type": "RoutePoint",
"position": {
"latitude": -34.92084502261776,
"longitude": 131.54823303222656
}
},
"previousPoint": {
"type":"VesselPosition",
"position": {
"latitude": -34.82084502261776,
"longitude": 131.04823303222656
}
}
}
</code></pre>
<h2 id="cancelling-navigation"><a class="header" href="#cancelling-navigation">Cancelling navigation</a></h2>
<p>To cancel the current course navigation and clear the course data.</p>
<pre><code class="language-typescript">HTTP DELETE 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course'
</code></pre>
<p><em>Note: This operation will NOT change the destination information coming from the NMEA input stream! If the NMEA source device is still emitting destination data this will reappear as the current destination.</em></p>
<p>To ignore destination data from NMEA sources see <a href="#configuration">Configuration</a> below.</p>
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
<p>The default configuration of the Course API will accept destination information from both API requests and NMEA stream data sources.</p>
<p>For NMEA sources, Course API monitors the the following Signal K paths populated by both the <code>nmea0183-to-signalk</code> and <code>n2k-to-signalk</code> plugins:</p>
<ul>
<li><em>navigation.courseRhumbline.nextPoint.position</em></li>
<li><em>navigation.courseGreatCircle.nextPoint.position</em></li>
</ul>
<p>HTTP requests are prioritised over NMEA data sources, so making an API request will overwrite the destination information received from and NMEA source.</p>
<p>Note: when the destination cleared using an API request, if the NMEA stream is emitting an active destination position, this will then be used by the Course API to populate course data.</p>
<h4 id="ignoring-nmea-destination-information"><a class="header" href="#ignoring-nmea-destination-information">Ignoring NMEA Destination Information</a></h4>
<p>The Course API can be configured to ignore destination data in the NMEA stream by enabling <code>apiOnly</code> mode.</p>
<p>In <code>apiOnly</code> mode destination information can only be set / cleared using HTTP API requests.</p>
<ul>
<li>
<p><strong><code>apiOnly</code> Mode = Off <em>(default)</em></strong></p>
<ul>
<li>Destination data is accepted from both <em>HTTP API</em> and <em>NMEA</em> sources</li>
<li>Setting a destination using the HTTP API will override the destination data received via NMEA</li>
<li>When clearing the destination using the HTTP API, if destination data is received via NMEA this will then be used as the active destination.</li>
<li>To clear destination sourced via NMEA, clear the destination on the source device.</li>
</ul>
</li>
<li>
<p><strong><code>apiOnly</code> Mode = On</strong></p>
<ul>
<li>Course operations are only accepted via the HTTP API</li>
<li>NMEA stream data is ignored</li>
<li>Switching to <code>apiOnly</code> mode when an NMEA sourced destination is active will clear the destination.</li>
</ul>
</li>
</ul>
<h4 id="retrieving-course-api-configuration"><a class="header" href="#retrieving-course-api-configuration">Retrieving Course API Configuration</a></h4>
<p>To retrieve the Course API configuration settings, submit a HTTP <code>GET</code> request to <code>/signalk/v2/api/vessels/self/navigation/course/_config</code>.</p>
<pre><code class="language-typescript">HTTP GET 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/_config'
</code></pre>
<p><em>Example response:</em></p>
<pre><code class="language-JSON">{
"apiOnly": false
}
</code></pre>
<h4 id="enable--disable-apionly-mode"><a class="header" href="#enable--disable-apionly-mode">Enable / Disable <code>apiOnly</code> mode</a></h4>
<p>To enable <code>apiOnly</code> mode, submit a HTTP <code>POST</code> request to <code>/signalk/v2/api/vessels/self/navigation/course/_config/apiOnly</code>.</p>
<p><em>Enable apiOnly mode:</em></p>
<pre><code class="language-typescript">HTTP POST 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/_config/apiOnly'
</code></pre>
<p>To disable <code>apiOnly</code> mode, submit a HTTP <code>DELETE</code> request to <code>/signalk/v2/api/vessels/self/navigation/course/_config/apiOnly</code>.</p>
<p><em>Disable apiOnly mode:</em></p>
<pre><code class="language-typescript">HTTP DELETE 'http://hostname:3000/signalk/v2/api/vessels/self/navigation/course/_config/apiOnly'
</code></pre>
<h2 id="course-calculations"><a class="header" href="#course-calculations">Course Calculations</a></h2>
<p>Whilst not performing course calculations, the <em>Course API</em> defines the paths to accommodate the values calculated during course navigation.</p>
<p>Click <a href="./course_calculations.html">here</a> for details.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../../develop/rest-api/open_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/course_calculations.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/open_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/course_calculations.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>