signalk-server
Version:
An implementation of a [Signal K](http://signalk.org) server for boats.
328 lines (287 loc) • 25 kB
HTML
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Configuration - 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" class="active"><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"><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>
<h2 id="configuring-signal-k-server"><a class="header" href="#configuring-signal-k-server">Configuring Signal K Server</a></h2>
<p>Signal K Server provides an Admin UI to allow you to easily configure your installation.</p>
<p>Open the Admin UI using a web browser on the device where Signal K server is installed (if the defaults have not been changed) by navigating to <code>http://localhost:3000</code>.</p>
<h3 id="create-an-admin-account"><a class="header" href="#create-an-admin-account">Create an Admin account</a></h3>
<p>It is considered good practise to enable security and create an administrator account to controll access to your server and protect your data.</p>
<p>If you ran the <code>signalk-server-setup</code> script, security will be enabled and you will be presented with a login screen when accessing the Admin UI.</p>
<p>If the login screen is not displayed, click <code>Login</code> <em>(top right of screen)</em> to display the prompt to create a user and password.</p>
<p>Alternatively, from the menu select <em>Security -> Users</em> and then:</p>
<ol>
<li>Click <strong>Add</strong></li>
<li>Enter a <strong>user id</strong></li>
<li>Enter a <strong>password</strong> and confirm it</li>
<li>In <strong>Permissions</strong> select <strong>Admin</strong></li>
<li>Click <strong>Apply</strong>.</li>
</ol>
<p>After creating the account, the server needs to be restarted.</p>
<p>How you restart the server will depend on the installation type <em>(i.e. installed from NPM, embedded on a commercial device, etc)</em>. Power cycling the device that Signal K Server is always an option.</p>
<h3 id="set-up-data-connections"><a class="header" href="#set-up-data-connections">Set up data connections</a></h3>
<p>To get data into Signal K server you will need to configure one or more data connections via the <em>Server -> Data Connections</em> menu option.</p>
<p>From this screen you can add connections for various data types including:</p>
<ul>
<li>NMEA2000</li>
<li>NMEA0183</li>
<li>Signal K</li>
<li>SeaTalk</li>
<li>File Stream</li>
</ul>
<p>The options presented will vary based on the data type chosen.</p>
<p><strong><em>NMEA2000</em></strong>: The processing of NMEA2000 PGNs is done by <a href="https://github.com/SignalK/n2k-signalk">n2k-signalk</a> via <a href="https://github.com/canboat/canboatjs">canboatjs</a>.</p>
<p>Please refer to the <a href="https://canboat.github.io/canboat/canboat.html">Canboat PGN database</a> to see what PGNs are supported.</p>
<p><strong><em>NMEA0183</em></strong>: The processing of NMEA0183 sentences is done by <a href="https://github.com/SignalK/signalk-parser-nmea0183">nmea0183-signalk</a></p>
<h4 id="nmea-0183-options"><a class="header" href="#nmea-0183-options">NMEA 0183 Options</a></h4>
<ul>
<li>
<p><em>Suppress nmea0183 event</em> - All incoming NMEA0183 data is made available over TCP on port 10110 by default. This happens by incoming data being emitted as <em>nmea0183</em> events. Selecting this option will prevent data from this connection appearing on the NEMA0183 TCP service.</p>
</li>
<li>
<p><em>Input Event</em> - By default, data received on this connection will cause the nmea0183 event to be emitted. In order to distinguish input from this connection from other NMEA 0183 connections, enter an input event name which will be emitted (in addition to the nmea0183 event) when data is received on this connection.</p>
</li>
<li>
<p><em>Validate checksum</em> - Usually <a href="https://en.wikipedia.org/wiki/NMEA_0183">NMEA 0183 sentences</a> contain a checksum that can be used to check that the data is not garbled so that erroneous data is discarded. However some data sources do not include the checksum or it is simply wrong. Unchecking this option will disable validating the checksum.</p>
</li>
<li>
<p><em>Append Checksum</em> - See previous point. Some data sources do not include a checksum, but for example a mobile app you are using may require them. Activating this option will add checksums to the data.</p>
</li>
<li>
<p><em>Remove NULL characters</em> - Some data sources include superfluous NULL characters in the input data stream, making the data invalid for consumption. This option will remove the NULL characters. It causes additional processing, so not on by default.</p>
</li>
<li>
<p><em>Ignored Sentences</em> - NMEA0183 sentences to throw away from the input data. Sometimes you may want to ignore certain sentences from a connection, because the data is invalid or missing or just not needed.</p>
</li>
<li>
<p><em>Override timestamps</em> - NMEA0183 data may include timestamps in tag blocks. These may be off or when playing back captured data you may want to ignore the data and override them with current time when converting to Signal K.</p>
</li>
</ul>
<p><strong>Connection type "File Stream"</strong></p>
<p>Sample files are available which can be set up as input for the server.</p>
<p>Use below command to get the path to a NMEA 2000 file with navigation data and AIS targets.</p>
<pre><code>sudo find / -name "aava-n2k.data"
</code></pre>
<p>Set up according to picture.</p>
<p><img src="./SK_file_stream_N2K.png" alt="SK_N2K_file" /></p>
<p>To get the path for the sample file, data type NMEA 0183, use below command.</p>
<pre><code>sudo find / -name "plaka.log"
</code></pre>
<h3 id="install-plugins-and-webapps"><a class="header" href="#install-plugins-and-webapps">Install Plugins and Webapps</a></h3>
<p>Signal K server functionality can be extended through the use of plugins and webapps.</p>
<p>Plugins typically extend data acquisition, data processing or enable operations (i.e. protocol conversion, etc).</p>
<p>Webapps provide a user interface to view / interact with data or perform operations enabling full featured solutions such as a Chartplotter.</p>
<p>To install, update or remove plugins and webapps select <em>Appstore</em> from the menu.</p>
<p>Select:</p>
<ul>
<li>
<p><code>Installed</code> to view a list of plugins and webapps currently installed.</p>
</li>
<li>
<p><code>Updates</code> to view a list of plugins and webapps that have updates available.</p>
</li>
<li>
<p><code>Available</code> to view a list of available plugins and webapps that can be filtered by categry.</p>
</li>
</ul>
<p>The entries displayed with a blue icon are webapps, those with a green icon are plugins and those with both blue and green icons are plugins with a webapp providing a user interface.</p>
<p><em>Note: An internet connection is required for Signal K Server to list, install and update AppStore listings.</em></p>
<p>To install, click the <code>download</code> icon on the right hand side of the entry.</p>
<p>To view a list of Plugins and Webapps directly from the NPM registry select the links below.</p>
<ul>
<li><a href="https://www.npmjs.com/search?q=keywords%3Asignalk-node-server-plugin">Plugins</a></li>
<li><a href="https://www.npmjs.com/search?q=keywords:signalk-webapp">Webapps</a></li>
</ul>
<p><strong><em>Note: A restart of the Signal K server is required after plugins or webapps have been installed or updated.</em></strong></p>
<p>Click the <em>Restart</em> button at the top right of the screen to restart the server.</p>
<p>After the server has restarted, the installed plugin(s) can be configued by selecting <em>Server -> Plugin Config</em> menu entry.</p>
<h3 id="trouble-shooting-and-the-server-log"><a class="header" href="#trouble-shooting-and-the-server-log">Trouble shooting and the Server Log</a></h3>
<p>If things are not working as expected after installing a plugin or webapp, select <em>Server -> Server Log</em> to view the server's log. If the errors logged there are not providing the information required, you can enable debugging for individual components and plugins by toggling the switch to activate them.</p>
<p>Enabling the <code>Remember debug setting</code> ensure your selections are remebered after a server restart.</p>
<h2 id="landing-page"><a class="header" href="#landing-page">Landing page</a></h2>
<p>When you access the Signal K server on a web browser you will be redirected to the Admin webapp as the default <code>landing page</code>. You can replace this default with your choice by adding the property <code>landingPage</code> in your <code>settings.json</code>. For example you can redirect the user to Kip or Freeboard.</p>
<h2 id="add-your-logo"><a class="header" href="#add-your-logo">Add your Logo</a></h2>
<p>You can change the logo image displayed at the top left of the Admin UI screen.
To do this, add an SVG file named <code>logo.svg</code> in the settings directory <em>(default: $HOME/.signalk/)</em>.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../setup/generating_tokens.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="../setup/seatalk/seatalk.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="../setup/generating_tokens.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="../setup/seatalk/seatalk.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>