docs: Port some documentation from the website, organize install docs

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).

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.

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)

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.

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).

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.
 

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.
+
+---

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:
 

docs/setup/configuration.md

@@ -2,6 +2,7 @@
 title: Configuration
 children:
   - seatalk/README.md
+  - nmea.md
 ---
 
 # Configuring Signal K Server

docs/setup/nmea.md

@@ -0,0 +1,46 @@
+---
+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 from
+[Actisense](http://www.actisense.com/product/usg-2/),
+[Digital Yacht](http://digitalyacht.co.uk/product/usb-nmea-adaptor/) and
+[Shipmodule](http://www.shipmodul.com/en/miniplex-lite.html), 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.