diff --git a/docs/guides/README.md b/docs/guides/README.md index bb1d9a916..412eff229 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -4,6 +4,7 @@ children: - anchoralarm/anchoralarm.md - datalogging/datalogging.md - navdataserver/navdataserver.md + - udev.md --- # Signal K Server Guides @@ -13,5 +14,6 @@ These guides will help you understand and use various features of the Signal K s - [Setting up an NMEA 0183 Navigation Data Server](navdataserver/navdataserver.md) - Learn how to set up Signal K as your boat's navigation data server - [Data Logging](datalogging/datalogging.md) - Configure and use Signal K's data logging capabilities - [Anchor Alarm](anchoralarm/anchoralarm.md) - Set up and use the anchor alarm feature +- [Linux udev Rules](udev.md) - Create udev rules to provide consistent device names for USB devices on Linux For questions and support see [Signal K Discussions](https://github.com/SignalK/signalk/discussions) or join [Signal K Discord](https://discord.gg/uuZrwz4dCS). diff --git a/docs/guides/udev.md b/docs/guides/udev.md new file mode 100644 index 000000000..1e98a8880 --- /dev/null +++ b/docs/guides/udev.md @@ -0,0 +1,51 @@ +--- +title: Linux udev Rules +--- + +# Linux udev Rules + +When you connect a USB device to a Linux computer, the kernel will automatically detect it and create a device file in + +Linux assigns device names sequentially to hotplug hardware. Usually, your device will get the same name each time you +connect it or boot your computer, but sometimes the name may change. For this reason, disks and partitions are +typically referenced by UUID and not by device path any more. For our purposes dealing with USB serial adapters, the +assigned device name is typically `/dev/ttyUSB0`. However, if you have more than adapter the device names may not +always be consistent. Therefore, it is a good idea to create a udev rule to provide an alias for your device. + +The example below assumes Debian or Ubuntu as the distribution, but it should be similar for others. + +First, we need to collect some identifiers for the device we want to alias. In a shell, run the `usb-devices` command. + +```sh +$ usb-devices +``` + +This will enumerate all of the USB devices connected to your computer (including internal USB hubs). In our example, +we're looking for Actisense devices. Write down the `Vendor`, `ProdId` and `SerialNumber` values for each of your +devices. + +Then, in your favorite text editor, create a file in `/etc/udev/rules.d/` called `90-actisense.rules`. The 90 ensures +that it processed after other udev rules. + +The contents of the file should be: + +``` +SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="d9aa", ATTRS{serial}=="1B091", SYMLINK+="actisense" +``` + +Replace `0403` with the value you wrote down for `Vendor` (if you are working with and Actisense device, it will likely +be the same). Replace `d9aa` with the value you wrote down for `ProdId` and replace `1B091` with the value you wrote +down for `SerialNumber`. The last change is to give your symlink a name. In the example above it is `actisense`, but +you can call it whatever you want (without spaces or filesystems-reserved characters like `/`). Let's say you have two +USG-1 devices, one for the autopilot and one for your VHF radio. You might want to name these devices `autopilot` and +`vhf`. Then they would be available at `/dev/autopilot` and `/dev/vhf` respectively. + +You can specify multiple rules in one file, one rule per line: + +``` +SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="d9aa", ATTRS{serial}=="1B091", SYMLINK+="autopilot" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="d9aa", ATTRS{serial}=="1B094", SYMLINK+="vhf" +``` + +After creating this file, disconnect your devices and plug them back in. You should see the new entries under `/dev`. +If not, reboot. diff --git a/docs/installation/README.md b/docs/installation/README.md index e619f8172..0ad127f07 100644 --- a/docs/installation/README.md +++ b/docs/installation/README.md @@ -2,129 +2,29 @@ title: Installation children: - raspberry_pi_installation.md + - npm.md + - docker.md + - source.md - updating.md - command_line.md --- -# Getting Started +# Installation -Signal K Server is a NodeJS application which can be installed on a variety of devices and operating systems. +Signal K Server is a [NodeJS](https://nodejs.org/en) application which can run on nearly any computer and operating system, including Window, Linux, and macOS. -It is available for installation via: - -1. NPM package -1. Docker image -1. GitHub repository - -See the relevant section below for instructions based on your target system. +Currently the most cost effective, powerful and best supported hardware platform for a Signal K server is the [Raspberry +Pi](https://www.raspberrypi.com). Any Raspberry Pi (even the very first model) can be used but for best performance we recommend Raspberry Pi 4 model B or 5. If you don't have a Raspberry Pi, any old laptop or computer you have sitting around would make a good initial test platform, although for permanent use on a yacht, more power efficient hardware like a Raspberry Pi is strongly recommended. ## Prerequisites > [!NOTE] -> Signal K server requires [NodeJS](https://nodejs.org) version >= 20 be installed on the target system prior to commencing installation. - ---- - -## Raspberry Pi Installation - -[Install Signal K Server on Raspberry Pi](raspberry_pi_installation.md) outlines the process for getting Signal K Server up and running _(including supporting services)_ on Raspberry Pi OS. - ---- - -## Using Docker - -Signal K Server is available as a Docker image on _Docker Hub_ and _cr.signalk.io/signalk/signalk-server_. - -To simply run a Signal K Server with some sample data on a device with docker installed, enter the following into a terminal: - -```shell -docker run -it --rm --publish 3000:3000 signalk/signalk-server -``` - -This will start an instance of Signal K Server on port 3000 which you can then access via the web based Admin UI by pointing your web browser at `http://localhost:3000`. - -If you are wanting to use docker to deploy Signal K Server on your vessel you will need to: - -1. Specify a location to persist the server's configuration so it is not lost between restarts -1. Run the instance as a background process - -_Example: Run as background process and store server configuration in the current folder:_ - -```shell -docker run -d --init --name signalk-server -p 3000:3000 -v $(pwd):/home/node/.signalk signalk/signalk-server -``` - -You are ready to now **[configure](../setup/configuration.md)** your installation and connect data from devices on your boat. - ---- - -## Installation via NPM - -Signal K Server can be installed directly using NPM. - -_Windows:_ - -- See [Installing on Windows](#installing-on-windows) below. +> Signal K server requires [NodeJS](https://nodejs.org) version >= 20 be installed on the target system. -_Linux / macOS:_ +## Getting Started -```shell -sudo npm install -g signalk-server -``` - -Once installation is complete, enter the following in a terminal window, to generate a settings file and configure the server to start automatically: - -```shell -sudo signalk-server-setup -``` - -If you choose not to use `signalk-server-setup` you can start the server by entering the following in a terminal window: - -```shell -signalk-server -``` - ---- - -## Installing on Windows - -Please use the [Signal K installer for Windows](https://github.com/SignalK/signalk-server-windows) to install Signal K Server on a Windows device. - ---- - -## Install using Git - -Installation from the GitHub repository is useful when developing plugins and components. - -To do this enter the following commands in a terminal window: - -```shell -# Copy the files to your device -git clone https://github.com/SignalK/signalk-server.git - -# change to the folder containing the downloaded files -cd signalk-server - -# install the dependencies -npm install - -# build all packages in the repository -npm run build:all -``` - -To start Signal K Server with a sample configuration file and some sample data, enter the following into a terminal: -_To use NMEA0183 sample data:_ - -```shell -bin/nmea-from-file -``` - -_To use NMEA2000 sample data:_ - -```shell -bin/n2k-from-file -``` - -The server will start playing back data from the specified sample file that can be viewed using the _Data Browser_ in the Admin UI _(`http://localhost:3000`)_ or via REST API / websocket connection. - ---- +- [Installing on Raspberry Pi](raspberry_pi_installation.md) +- [Installing on Windows](https://github.com/SignalK/signalk-server-windows) +- [Installing from NPM](npm.md) +- [Installing from Docker](docker.md) +- [Installing from Source](source.md) diff --git a/docs/installation/docker.md b/docs/installation/docker.md new file mode 100644 index 000000000..a1a5fc636 --- /dev/null +++ b/docs/installation/docker.md @@ -0,0 +1,28 @@ +--- +title: Docker +--- + +# Installing from Docker + +Signal K Server is available as a Docker image on _Docker Hub_ and _cr.signalk.io/signalk/signalk-server_. + +To simply run a Signal K Server with some sample data on a device with docker installed, enter the following into a terminal: + +```shell +docker run -it --rm --publish 3000:3000 signalk/signalk-server +``` + +This will start an instance of Signal K Server on port 3000 which you can then access via the web based Admin UI by pointing your web browser at `http://localhost:3000`. + +If you are wanting to use docker to deploy Signal K Server on your vessel you will need to: + +1. Specify a location to persist the server's configuration so it is not lost between restarts +1. Run the instance as a background process + +_Example: Run as background process and store server configuration in the current folder:_ + +```shell +docker run -d --init --name signalk-server -p 3000:3000 -v $(pwd):/home/node/.signalk signalk/signalk-server +``` + +You are ready to now **[configure](../setup/configuration.md)** your installation and connect data from devices on your boat. diff --git a/docs/installation/npm.md b/docs/installation/npm.md new file mode 100644 index 000000000..b024e8647 --- /dev/null +++ b/docs/installation/npm.md @@ -0,0 +1,31 @@ +--- +title: NPM +--- + +# Installing from NPM + +Signal K Server can be installed directly using NPM. + +## Linux / macOS + +```shell +sudo npm install -g signalk-server +``` + +Once installation is complete, enter the following in a terminal window, to generate a settings file and configure the server to start automatically: + +```shell +sudo signalk-server-setup +``` + +If you choose not to use `signalk-server-setup` you can start the server by entering the following in a terminal window: + +```shell +signalk-server +``` + +You are ready to now **[configure](../setup/configuration.md)** your installation and connect data from devices on your boat. + +## Windows + +See [Installing on Windows](https://github.com/SignalK/signalk-server-windows). diff --git a/docs/installation/raspberry_pi_installation.md b/docs/installation/raspberry_pi_installation.md index e4d468bad..d73e9bf10 100644 --- a/docs/installation/raspberry_pi_installation.md +++ b/docs/installation/raspberry_pi_installation.md @@ -2,7 +2,7 @@ title: Raspberry Pi --- -# Installation on Raspberry Pi +# Installing on Raspberry Pi Installation of Signal K server can consists of the following steps: @@ -12,7 +12,7 @@ Installation of Signal K server can consists of the following steps: _**Important:** If you are updating a Signal K server installation, especially if upgrading an installed version <= 1.40.0, [please check here first](./updating.md)._ -### Prerequisites: +## Prerequisites: Raspberry Pi OS is installed on the device. diff --git a/docs/installation/source.md b/docs/installation/source.md new file mode 100644 index 000000000..7191b5d9f --- /dev/null +++ b/docs/installation/source.md @@ -0,0 +1,40 @@ +--- +title: From Source +--- + +# Installing from source + +Installation from the GitHub repository is useful when developing plugins and components. + +To do this enter the following commands in a terminal window: + +```shell +# Copy the files to your device +git clone https://github.com/SignalK/signalk-server.git + +# change to the folder containing the downloaded files +cd signalk-server + +# install the dependencies +npm install + +# build all packages in the repository +npm run build:all +``` + +To start Signal K Server with a sample configuration file and some sample data, enter the following into a terminal: +_To use NMEA0183 sample data:_ + +```shell +bin/nmea-from-file +``` + +_To use NMEA2000 sample data:_ + +```shell +bin/n2k-from-file +``` + +The server will start playing back data from the specified sample file that can be viewed using the _Data Browser_ in the Admin UI _(`http://localhost:3000`)_ or via REST API / websocket connection. + +--- diff --git a/docs/installation/updating.md b/docs/installation/updating.md index dbc257d84..1e32add56 100644 --- a/docs/installation/updating.md +++ b/docs/installation/updating.md @@ -20,7 +20,7 @@ Updates fall into four categories: ## Update Device Operating System -Instructions will vary depending on your device but for linux based systems such as the Raspberry Pi the following instrctions are used to update the OS. +Instructions will vary depending on your device but for linux based systems such as the Raspberry Pi the following instructions are used to update the OS. From a terminal window enter the following commands: diff --git a/docs/setup/configuration.md b/docs/setup/configuration.md index 206e5c01b..fe93a47ab 100644 --- a/docs/setup/configuration.md +++ b/docs/setup/configuration.md @@ -2,6 +2,7 @@ title: Configuration children: - seatalk/README.md + - nmea.md --- # Configuring Signal K Server diff --git a/docs/setup/nmea.md b/docs/setup/nmea.md new file mode 100644 index 000000000..661c0955f --- /dev/null +++ b/docs/setup/nmea.md @@ -0,0 +1,45 @@ +--- +title: NMEA Connections +--- + +# NMEA Connections + +Most equipment on boats use NMEA 0183, NMEA 2000, or other proprietary interfaces to communicate with each other. A lot of work has been done within the Signal K community to convert these different data formats in to Signal K. + +## NMEA 0183 + +There are a number of NMEA to USB adaptors around, like +[Actisense](http://www.actisense.com/product/usg-2/) and +[Digital Yacht](http://digitalyacht.co.uk/product/usb-nmea-adaptor/), which allow +bi-directional transfer of the NMEA 0183 Serial data (electrically similar to RS-422) and convert it in to a USB +virtual COM Port when plugged in to the Signal K server. + +In Linux the virtual COM Port will be seen as a device called `/dev/ttyUSB0` (the number could be different if there +are multiple USB-to-serial adapters connected). Linux assigns these device names automatically when the device is +connected, so it could change. If you want to ensure that the device always has the same name, you will need to write a +UDEV rule to specify an alias. See [creating UDEV rules](../guides/udev.md) for details. + +To verify that you have a working connection, you can use picocom or another terminal emulator to see if you are +receiving data. The default baud rate for standard NMEA 0183 is 4800, whilst AIS and multiplexers use NMEA 0183(HS) at the "High Speed" 38400 baud rate. + +``` +$ picocom -b 4800 /dev/ttyUSB0 +``` + +You should see NMEA 0183 sentences scrolling off the screen. To exit picocom press `Ctrl-a` followed by `Ctrl-x`. + +Once your NMEA 0183 connection is working, you can [set up data connections the Signal K server](./configuration.md#set-up-data-connections) to read the data. + +## NMEA 2000 + +NMEA 2000 support in Signal K is provided by [canboatjs](https://github.com/canboat/canboatjs), which is a library that can read and write NMEA 2000 data. See the [list of supported devices from canboatjs](https://github.com/canboat/canboatjs#supported-devices) for details of hardware that can be used to connect to NMEA 2000 networks. + +Directions for configuring your hardware will vary by device, so consult the documentation for your hardware for details. Once you have your hardware connected and configured, you can use the `candump` utility from the `can-utils` package to verify that you are receiving NMEA 2000 data. + +```sh +candump can0 +``` + +You should see NMEA 2000 data scrolling off the screen. Press `Ctrl-c` to exit candump. + +After confirming you have NMEA data, you can [set up data connections the Signal K server](./configuration.md#set-up-data-connections) to read the data.