Pages

• 1: Getting Started
• 1.1: Powering via NMEA 2000
• 2: Hardeware Description
• 3: Software
• 4: Tutorials and Example Projects
• 4.1: OpenPlotter Server Installation
• 5: Hardware revisions
• 6: Errata

1 - Getting Started

Hardware assembly

SH-RPi is delivered fully assembled. The hardware installation steps are:

1. Mount the Raspberry Pi (not included) in an enclosure of your choice (not included)
2. Plug the SH-RPi on the Raspberry Pi GPIO header (optionally using the hex standoffs)
3. Connect the JST XH power 2-pin power cable
4. Connect the JST XH CAN bus (NMEA 2000) jumper cable

Enclosures

If you are going to use your Raspberry Pi and SH-RPi on a boat, you should always place the device in a waterproof enclosure! Hat Labs offers two different types of waterproof enclosures.

RND 455-00388 is an IP 65 rated aluminum enclosure with dimensions of 200x120x75mm. The size is sufficient for a Raspberry Pi and some peripherals, while not being excessively large. It offers excellent environmental and electromagnetic protection as well as thermal conductivity, but also blocks WiFi signals. Therefore, an external WiFi antenna needs to be used with it. Also, LEDs or status displays are obviously not visible unless LED light pipes or a plastic window aperture are installed.

RND 455-00138 is a polycarbonate plastic box with a clear lid and IP 65 rating. Its outer dimensions are 120x240x60mm, making it spacious enough for more peripherals. Even though it is plastic, it is large enough to provide sufficient surface area to provide adequate heat dissipation even for a Raspberry Pi 4B and some accessories.

Drilling holes

The enclosures don’t have any pre-drilled holes for connectors or wire glands on them. At a very minimum, you need one hole for power or NMEA 2000 input, and on the metal enclosure, another for a WiFi antenna or a wired ethernet connector.

Plan the hole/connector placement to fit your intended installation location. If you are planning to wall-mount the enclosure, place the connectors under the enclosure to minimize the chances for water ingress.

Both aluminum and polycarbonate are relatively soft and can be drilled with a step drill bit (one that looks like a small metal Christmas tree). When drilling plastic, standard metal drill bits may easily bite too hard and crack the wall.

An example of step drill bits.

Suitable hole sizes for different connectors:

• SMA (WiFi antenna): 6.5-7 mm or 1/4"
• PG7 cable gland and M12 (NMEA 2000) panel connector: 12 mm or 1/2"
• SP13 panel connectors (blue-black plastic connectors): 13-14 mm. 1/2" probably works with a bit of wiggling.
• PG9 cable gland: 16 mm or 5/8"
• RJ45 panel connector: 21-22 mm
• USB type A panel connector: 21-22 mm

Mounting the Raspberry Pi

A Raspberry Pi can be mounted on the enclosure with the Raspberry Pi mount adapters and the adhesive spacers.

An exploded view of assembly with the suggested components.

Mount at least one of the adapter screws on the enclosure holes for secure attachment. This will reduce the likelihood of the Raspberry Pi rattling around the enclosure if the adhesives are not firmly attached.

An example mounting of the SH-RPi in an enclosure.

Power and NMEA 2000 connections

SH-RPi can always be powered using a dedicated power connector.

It is also possible to power the SH-RPi via the NMEA 2000 network, provided that there are no galvanic connections to external wired hardware. For details, refer to the NMEA 2000 power page.

If power is provided via a dedicated power connector, install a panel connector on the enclosure and solder the provided JST XH pigtail cable to the panel connector.

JST XH pigtail soldered to an SP13 panel connector.

If you want to power the Raspberry Pi via the NMEA 2000 network, splice the black and red wires of the JST XH pigtail cables together as shown in the following picture:

Two JST XH pigtails spliced together.

The photo below shows the correct pin ordering for the NMEA 2000 connector when soldering the wires.

Note that the official NMEA 2000 wire coloring uses blue for CAN_L. The JST XH pigtail provided substitutes that for a yellow wire instead.

* According to NMEA 2000 standard, shield must not be connected to the device metal enclosure. However, shield must have continuity throughout the network cabling. So, if cables should always have the shield pin connected, but enclosures not.

** NMEA 2000 standard color for CAN_L is blue.

Soldering the panel connectors

When soldering the internal wires to the panel connectors, always use heat shrink tube on the individual wires. Always remember to slide the heat shrink on the wires before soldering… Usually you can first add solder to the connector pin cavity and then re-melt the solder and insert the wire.

Connecting a fan

Placing a fan inside the enclosure is recommended to improve air circulation and heat transfer through the enclosure surfaces. A small 40mm fan can be mounted in the enclosure with two-sided tape or hot glue. For maximal cooling efficiency, it should be pointed to blow air to the space between the Raspberry Pi and the Sailor Hat.

The fan should be connected to the dedicated 5V header on the SH-RPi:

Software installation

Some additional configuration changes and software are required for the Raspberry Pi OS to detect the new CAN bus interface and to run the system service that will automatically initiate system shutdown once the power is cut.

Automated installation

A fully automated installation script is provided. The script is tested on newly flashed Raspberry Pi OS and might fail on a heavily modified system. Installation has not been tested on any other operating systems.

To run the automated installation script, copy-paste the following command onto the Raspberry Pi command prompt:

curl -L \
    https://raw.githubusercontent.com/hatlabs/SH-RPi-daemon/main/install-online.sh \
    | sudo bash

The command is three lines and when you paste it to your terminal window, it might show up with line continuation characters. That’s OK.

{:width=“50%”}\

The command will fetch the installation script and execute it automatically.

The automated installation script will:

• enable the I2C and SPI interfaces
• install device tree overlays for the CAN interface
• define the CAN network interface
• if the real-time clock device is detected, configure the Pi to use the RTC
• install the SH-RPi-daemon and its dependencies

Manual installation

Manual installation of the required software is possible as well. The process is described in the Software section.

1.1 - Powering via NMEA 2000

It is possible to power the Raspberry Pi via the NMEA 2000 network. To stay compliant with the NMEA 2000 specification and to ensure safe and uninterrupted operation of the NMEA 2000 network, it is important to observe some restrictions in the device connections.

The following diagrams illustrate the valid powering schemes. In the diagrams, dashed lines illustrate the isolation barrier

Always OK: SH-RPi powered with a dedicated power cable.

OK: SH-RPi powered via the NMEA 2000 network, no external connections.

OK: SH-RPi powered with a dedicated power cable and connected to external devices with a galvanic connection such as USB or unisolated RS-422.

OK: SH-RPi powered via the NMEA 2000 network and connected to external devices with an isolated connection such as Ethernet or isolated NMEA 0183.

OK: SH-RPi powered via the NMEA 2000 network having peripherals such as keyboard, mouse, or a GPS receiver that are powered by the Raspberry Pi and not connected elsewhere.

Not permitted: SH-RPi powered via the NMEA 2000 and connected to external devices with a galvanic connection. This setup will cause a lot of noise and may impact the reliability of the Raspberry Pi or other devices.

2 - Hardeware Description

Tour Around the Board

Different functional blocks of the Sailor Hat for Raspberry Pi are described below.

Functional blocks of the SH-RPi.

1. Power input and protection. Power input is provided through a 2-pin JST XH connector. The permitted voltage range is 8-32V. The protection circuitry at power input includes:
   • 2.5A SMD fuse
   • 33V transient voltage suppressor (5000W peak pulse power capability)
   • Pre-filter for conducted electromagnetic interference
   • Reverse polarity protection
2. Step-down (buck) converter with current limiting. The buck converter transforms the input voltage into a 2.65V potential that the supercapacitor can handle. The step-down converter circuit also includes a separate current limiter that throttles the supercapacitor input current to cap the maximum device current draw to 0.8A (at 12V).
3. A 60F 2.7V supercapacitor. The supercapacitor acts as a power reservoir for the Raspberry Pi. It can power a Raspberry Pi 4B for up to 80 seconds (subject to the amount of additional peripherals, of course), and lower-power models for much longer. The supercapacitor also makes it possible to power the Raspberry Pi using a low-power interface such as the NMEA 2000 bus that limits an individual node current to 1.0A, including high-speed transients.
4. Microcontroller. The SH-RPi operations are controlled by an ATtiny1614 microcontroller. The microcontroller performs the following functions:
   • Measures the input voltage
   • Measures the supercapacitor voltage
   • Controls the Vin, Vcap, and Status leds
   • Controls the boost converter output
   • Receives real-time clock interrupt information (can be used as an external interrupt source as well)
   • Communicates the SH-RPi status to the Raspberry Pi service over I2C
5. Step-up (boost) converter. The boost converter converts the 0.5-2.65V potential stored in the supercapacitor into the 5V Raspberry Pi input voltage. The boost converter operation is controlled by the microcontroller. The microcontroller enables the boost converter when the supercapacitor voltage has risen above 1.8V. During system shutdown or watchdog reboot, the microcontroller disables the boost converter to cut the Raspberry Pi input voltage.
6. Status LEDs. The status LEDs indicate the board operational status LEDs as described in Section LEDs.
7. Real-time clock (optional). The board includes an optional DS3231MZ real-time clock that can keep accurate time even in the absence of internet or GPS connectivity. The RTC communicates with the Raspberry Pi over I2C.
8. CAN bus (NMEA 2000) interface. The SH-RPi includes an MCP2515 CAN controller and an ISO1050DUB CAN transceiver that provide an isolated, NMEA 2000 compliant CAN bus interface. The interface can be used as a generic CAN interface if external power is provided to the CAN connector.

Connectors

SH-RPi connectors.

1. Power connector. The power connector is a JST XH compatible header. The Hat Labs sales kit includes a compatible pigtail cable.
2. CAN bus (NMEA 2000) connector. NMEA 2000 or other CAN bus can be connected to this connector.
3. Wire link. Main power input and CAN section power input pins can be connected together by soldering a wire to the wire link headers. The main use case is to power the Raspberry Pi using a single NMEA 2000 cable without having to splice any wires.
4. Stackable Raspberry Pi GPIO header. This is a standard 2x20 pin Raspberry Pi GPIO header. Additional hats can be placed on top of the Sailor Hat for Raspberry Pi as long as there are no conflicting pins or I2C addresses.
5. 5V output. The 5V output header can be used to power a fan or other peripherals requiring a 5V input.
6. ATtiny1614 breakout header. The pins of the onboard ATtiny1614 microcontroller are broken out to this header. The header can be used to program the microcontroller or to implement new functionality.
7. Reset header. The reset header can be used to forcibly hardware reset the Raspberry Pi. The header is connected to the boost converter Enable pin. Pulling the Reset pin low turns the boost converter off. When the Reset pin is connected to 3.3V, it forces the boost converter to stay on regardless of the microcontroller state. This can come handy for example when programming the microcontroller using the Raspberry Pi itself: you don’t want the Raspberry Pi to shut down during the programming.
8. ATtiny interrupt header. This header is connected to the microcontroller INTerrupt pin. This pin can be used in the future by the optional RTC or an external interrupt source to wake up the Raspberry Pi.
9. CR1220 battery connector for real-time clock. The optional real-time clock requires a CR1220 backup battery to keep time when the system is powered off. The battery must be oriented positive (flatter) side up.

Power Supply

The SH-RPi includes an integrated power supply subsystem that provides a clean power supply to the Raspberry Pi from a noisy power source, like a boat’s “house” battery system. The power supply permits input voltages between 8-32 V (although the output will be disabled if the input is less than 10V, to protect the vessel batteries from deep discharging).

The input current is limited to a maximum of 0.8 A at 12 V. Above that limit, a current limiting circuit starts throttling the buck converter to control the maximum current drawn from the power input.

The power supply output voltage is normally at 5.1 V. The maximum steady-state output current is about 1.2 A, or about twice the current consumption of a Raspberry Pi 4B. Maximum output currents over 3 A can be sustained over several hundred milliseconds.

Peripherals

LEDs

SH-RPi indicator LEDs.

SH-RPi includes a number of LEDs to indicate the state of operation.

1. Main LED array
2. CAN power (on whenever input voltage is present at the CAN power pins)
3. CAN receive and transmit (blink whenever data is received or transmitted over the CAN bus)

The main LED array LEDs are as follows:

• Vin: A green LED that indicates the 12/24V input voltage. The LED states are:
  • Vin < 10 V: LED off
  • 10 V < Vin < 11.5 V: LED blinking 50% on/off
  • Vin > 11.5 V: LED solid on
• 5V: Red LED solid on when 5V is enabled by the microcontroller
• Vcap: Green LED that blinks according to the supercapacitor voltage. 100% off is 0 V, 100% on is 2.75 V.
• Status: Different blink patterns indicate the state of the board as follows.


Different board statuses are:

• Charging: the supercapacitor is charging but the voltage is too low to turn the 5V output on
• On: 5V output is turned on
• Watchdog enabled: 5V output is on, watchdog is enabled
• Watchdog reboot: The daemon has not communicated in 10 seconds; the Raspberry Pi is reset by turning 5V off for two seconds
• Depleting: Input voltage is not present and the supercapacitor is depleting
• Shutting down: The daemon has requested a shutdown; the watchdog is turned off and the firmware waits until the kernel is shut down (as indicated by SDA being set low)
• Off: 5V is turned off and the board is expected to be powered off. If the board remains powered, it will restart in 5 seconds.

CAN Bus (NMEA 2000)

NMEA 2000 is a ubiquitous communications standard used for connecting sensor, control, and display devices on boats and ships. It is based on the Controller Area Network (CAN bus) which is a vehicle bus standard designed to allow devices to communicate with each other without a host computer.

SH-RPi features an isolated CAN interface that allows safe and NMEA 2000 compliant interconnection of devices.

The CAN interface is implemented with an MCP2515 controller and an ISO1050DUB isolated transceiver.

The Raspberry Pi communicates with the MCP2515 over an SPI interface. SH-RPi uses by default Raspberry Pi SPI0 with GPIO6 as a custom Chip Enable (CE) pin. This is done to allow simultaneous operation with other devices reserving the standard SPI pins. The interrupt pin is GPIO5.

I2C

I2C (Inter-Integrated Circuit) is a popular synchronous serial communication bus commonly used for interfacing with a number of different ICs. It uses two data wires in addition to voltage and ground.

The SH-RPi microcontroller communicates with the Raspberry Pi operating system over I2C. The microcontroller uses I2C address 0x6d.

If the optional DS3231 real-time clock is installed, it additionally reserves the I2C address 0x68.

Remapping Peripherals

SH-RPi hardware jumpers.

For advanced use, all GPIO pins used by the Sailor Hat for Raspberry Pi can be disabled or remapped using the hardware jumpers. The hardware jumpers are 0603 size 0 ohm resistors that can be unsoldered from the board. Thin wires can then be soldered to the resistor pads for routing the peripherals to desired GPIO pins.

3 - Software

Introduction

The Sailor Hat for Raspberry Pi requires additional software on the Raspberry Pi Operating System to fully utilize the device functionality. An installation script is provided to automatically install all required software on a fresh Raspberry Pi OS installation. Use of the installation script is described in the Getting Started Section. You will only need to follow the manual installation instructions if you prefer to not have automated scripts modify your system configuration or if you have to troubleshoot your installation.

For manual installation, the required software and configuration changes as well as the firmware software details are described below.

Raspberry Pi device tree changes

Installing the device tree overlays

Raspberry Pi uses a Device Tree (DT) to describe the hardware present in the Pi. Using the CAN interface on the SH-RPi requires applying two device tree overlays to customize the hardware configuration. The device tree overlays apply the following changes:

1. Add another channel with its own Chip Enable (CE) pin to the SPI0 bus.
2. Define a new CAN controller using the new SPI0 channel.

The device tree overlay source files are located in the SH-RPi-daemon repository. To install them manually, first clone the repository on your Raspberry Pi:

git clone https://github.com/hatlabs/SH-RPi-daemon.git

Then, go to the configs directory:

cd SH-RPi-daemon/configs

The overlays need to be compiled to binary format:

dtc -@ -I dts -O dtb -o spi0-3cs.dtbo spi0-3cs-overlay.dts
dtc -@ -I dts -O dtb -o mcp2515-can2.dtbo mcp2515-can2-overlay.dts

Once compiled, copy the files to /boot/overlays:

sudo install -o root spi0-3cs.dtbo /boot/overlays
sudo install -o root mcp2515-can2.dtbo /boot/overlays

Enabling I2C and SPI

Next, I2C and SPI interfaces need to be enabled. This can be done either by running raspi-config or by editing /boot/config.txt directly.

If you use raspi-config, skip until the end of this subsection.

sudo nano /boot/config.txt

First, enable I2C. Find the following line:

#dtparam=i2c_arm=on

and edit it by removing the comment marker at the beginning:

dtparam=i2c_arm=on

Do the same for SPI by uncommenting the following line:

#dtparam=spi=on

Write the file by pressing Ctrl-O. Then exit Nano by pressing Ctrl-X.

Enabling the new interfaces

Again, edit /boot/config.txt:

sudo nano /boot/config.txt

Scroll down to the [all] section.

You need to add three new lines there. First, enable the RTC (if your device has one):

dtoverlay=i2c-rtc,ds3231

Next, define the new CAN interface:

dtoverlay=mcp2515-can2,oscillator=16000000,interrupt=5,cs2=6

Finally, configure the kernel to signal the Sailor Hat on power off:

dtoverlay=gpio-poweroff,gpiopin=2,input,active_low=17

Again, write the file by pressing Ctrl-O and exit Nano by pressing Ctrl-X.

Raspberry Pi configuration file changes for CAN interface

The I2C kernel module needs to be loaded at boot time:

sudo nano /etc/modules

Add the following line:

i2c-dev

Save and exit.

Next, create a network interface definition for the CAN interface:

sudo nano /etc/network/interfaces.d/can0

Add the following lines:

auto can0
iface can0 can static
    bitrate 250000
    pre-up ip link set can0 type can restart-ms 100
    up /sbin/ifconfig can0 txqueuelen 100

Save and exit.

Raspberry Pi configuration file changes for the RTC

Raspberry Pi doesn’t have a real-time clock by default. Instead, the system implements a “fake hwclock” that fetches the current time from the internet and then saves the time to a file at regular intervals. The time is then set from that file at boot to avoid things such as filesystem checks at every boot.

If your SH-RPi has a real-time clock, this fake hwclock functionality needs to be disabled and replaced with actual hwclock calls. These four commands do the trick:

 sudo apt-get update
 sudo apt-get -y remove fake-hwclock
 sudo update-rc.d -f fake-hwclock remove
 sudo systemctl disable fake-hwclock
 sudo sed -i -e "s,^\(if \[ \-e /run/systemd/system \] ; then\),if  false; then\n#\1," /lib/udev/hwclock-set

Raspberry Pi daemon

To make the Raspberry Pi OS aware of the power state, a daemon (service software) needs to be installed.

If you have cloned the SH-RPi-daemon repository, you can install the daemon by issuing the following commands:

sudo apt-get -y install python3-setuptools
sudo python3 setup.py install

Next, you will have to install the service definition file and enable the service:

sudo install -o root sh-rpi-daemon.service /lib/systemd/system
sudo systemctl daemon-reload
sudo systemctl enable sh-rpi-daemon

That’s it!

Note: The Automated installation script described in the Getting Started Section will perform all software installation steps described above automatically.

Firmware

The program code running on the onboard ATtiny1614 microcontroller is called the SH-RPi firmware.

The firmware repository is at https://github.com/hatlabs/SH-RPi-firmware.

The following subsections describe how to update the firmware to get new features or if you want to hack it yourself.

Updating the firmware

It is possible to update the SH-RPi firmware using the connected Raspberry Pi with the help of one 1 kΩ resistor and some jumper wires.

Flashing is performed over ATtiny’s UPDI interface using pyupdi.

Hardware

UPDI flashing circuit.

First, you need to make sure that the 5V boost converter output isn’t cut when the flashing begins. The boost converter can be forced on by pulling the SH-RPi Reset header to 3.3 V using the red jumper wire.

Next, you need the super-simple serial flashing harness shown in the above picture. Cut two or three jumper wires and solder the bits to the leads of a 1 kΩ resistor. The resistor should be between the Raspberry Pi TX (GPIO 14) and ATtiny RST pins and there should be a direct connection between Raspberry Pi RX (GPIO 15) and the ATtiny RST pins.

The photo below shows what the result should look like.

Photo of a working flashing circuit.

Raspberry Pi configuration changes

The next step is to enable the serial UART on the Raspberry Pi. On Bluetooth-enabled Pis, the UART is normally reserved by the onboard Bluetooth circuitry. So, let’s disable Bluetooth.

Add the following line at the end of /boot/config.txt:

dtoverlay=disable-bt

We also need to disable the system service initializing the Bluetooth modem:

sudo systemctl disable hciuart

Finally, prevent the system serial console from attaching to the serial port. Remove the console=serial0,115200 part from the beginning of /boot/cmdline.txt.

Reboot to allow the changes to take place.

Installing flashing software

While it is possible to build the firmware on the Raspberry Pi itself, I normally build the firmware on my laptop and then copy the binary file to the Pi for flashing. Hence, we only need the pyupdi utility on the Pi:

sudo apt update
sudo apt -y install python3-pip
sudo pip3 install https://github.com/mraardvark/pyupdi/archive/master.zip

Flashing

Copy the binary file at .pio/build/attiny1614/firmware.hex to the Raspberry Pi using rsync:

rsync -avP .pio/build/attiny1614/firmware.hex pi@myraspi.lan: 

Finally, upload the firmware using pyupdi:

pyupdi -i -d attiny1614 -c /dev/ttyAMA0 -b 115200 -f firmware.hex

The LEDs should go off (or dim) during the flashing and resume operation immediately afterwards.

Restoring Bluetooth

If you want to keep using Bluetooth, remember to undo the steps you made previously.

4 - Tutorials and Example Projects

SH-RPi tutorials and example projects will be listed on this page.

4.1 - OpenPlotter Server Installation

Introduction

In this tutorial we’ll build an OpenPlotter server using the Sailor Hat for Raspberry Pi (purchasing link) and the OpenPlotter software. The server is compact and waterproof and powered easily through the boat’s 12/24V power system. It also integrates easily with your existing boat electronics.

The included software will log all essential NMEA 2000 traffic on the boat and allows you to visualize the real-time and historical behavior of different values using integrated instrument panels as well as Grafana dashboards. Furthermore, the server can receive and process information from other sources such as SH-ESP32 sensor devices or from various Internet services.

Some visualization examples:

Parts needed

To complete this tutorial, you need the following parts:

• SH-RPi enclosure kit

  SH-RPi is the secret sauce that provides the required hardware interfaces to your boat’s subsystems for the Raspberry Pi. It includes an integrated, protected 12/24V power supply with safe shutdown functionality as well as an isolated NMEA 2000 compatible CAN interface.

  In this tutorial we’ll use the plastic enclosure and power the Pi through an NMEA 2000 panel connector. Additionally, a USB type A panel connector is used to provide easier connectivity when needed, and a cooling fan is added to improve heat dissipation. Feel free to modify your own configuration, though.

  We’ll also use an additional USB WiFi adapter because that will make things easier during the installation (the additional network interface may come handy on the boat as well). If you don’t want the USB WiFi adapter, you can alternatively plug the Pi into wired Ethernet for equivalent results.

• A Raspberry Pi 4B

  A 4 GB memory model is fine. Amazon tends to have unbeatable prices, or you can check the list of distributors on the Raspberry Pi website:

  • amazon.com
  • amazon.de
  • amazon.co.uk
  • Raspberry Pi list of distributors

• MicroSD memory card

  A MicroSD card hosts the Raspberry Pi operating system and data files. I have had good results with Samsung Evo Plus cards. Memory cards are cheap and bigger ones are more reliable in Raspberry Pi use, so get at least a 64 GB one:

  • amazon.com
  • amazon.de
  • amazon.co.uk

• Double-sided tape or hot glue

  A short piece of double-sided tape or a dab of hot glue is needed for mounting the cooling fan.

• Heat shrink tube, 3 mm inner diameter

  While not absolutely necessary, some 3 mm i.d. heat shrink tube is useful to secure the soldered panel connector wires.

• NMEA 2000 female plug

  If you’re doing the initial installation at home, having an extra NMEA 2000 micro plug comes handy for providing input voltage to the device.

Hardware assembly

Drilling holes for the connectors

As always when drilling holes to a perfectly good enclosure, plan very carefully ahead. The panel connectors take surprisingly lot of space and a hole can’t be easily patched, let alone moved.

My preference is to take measurements of the enclosure and create a drilling template in a vector drawing program. A drawing helps you observe the maximum dimensions required by the connector and the nut.

If you have no idea what program to use, Inkscape is a good all-around tool. If you’re more technically inclined, CAD software such as LibreCAD might work as well.

I wanted to have three holes at the short edge of the plastic enclosure. Here’s the template I did for that:

The template is an SVG (vector) file, so you can save it and modify according to your liking. If you don’t know which software to use, you can try for example Inkscape mentioned above. I personally use Affinity Designer that is a low-cost commercial design software available for MacOS.

If you have trouble opening the SVG, the template is also available as a PDF version.

Once you have finished a template, mark the center point on the enclosure and tape the template to the enclosure so that the center points match.

For accurate drilling, it helps to mark the hole centers with a center punch (a sharp nail and a light tap with a hammer is also fine).

Drill pilot holes with a small drill bit (3 mm or so). Then use a step drill bit to drill the final holes. Take your time and use a slow speed. Smaller holes with odd sizes such as the 6.5 mm one should be finished with a corresponding size metal bit.

Drilling plastic leaves a lot of burrs around the holes. Those can be removed with a sharp knife.

Finally, on the plastic enclosure, the integrated standoffs may block the holes you drilled. I had to remove one of the standoffs. I used a Dremel tool but sturdy pliers might work as well.

Here’s what the end result looks like in my case.

Connecting wires to the NMEA 2000 panel connector

Next, we will solder the JST XH pigtails to the NMEA 2000 panel connector. This same approach also works for soldering the SP13 power connectors if you decide to use one of those instead. We’ll start by filling the connector pin cups with solder.

We want to power both the board itself and the CAN interface using the NMEA 2000 connector. There’s more than one way to do that but let’s use the obvious method and connect both connector pigtails to the NMEA panel connector.

Peel a short length of the red and black wires and wrap them together.

It is recommended to use heat shrink tube to isolate the connector pins and to provide mechanical support to the solder joints. Cut short pieces of the heat shrink tube and slide them on the wires. (Guess who forgot this part again while preparing the photos for this tutorial!)

Solder the wires, both the individual signal wires and the spliced together power wires, to the connector.

The diagram below shows the correct pinout. Yes, it’s a male connector, but because we’re staring at the wrong end of the connector, we’ll use the opposite gender diagram. (Yes, it’s a bit confusing.)

Start by soldering the middle pin first. It’s easier to do now when the other wires are not yet flapping around. The standard color for the CAN_L wire is blue but our harness has yellow instead.

Next, solder the three other wires in place. Shield is left unconnected.

This is what your connector should look like at this stage:

I’m boldly assuming you remembered to slide the heat shrink bits in place before soldering the wires. Now it’s time to slide them on top of your soldered connections and use a hot air gun (or a lighter flame) to shrink them. The end result should be roughly like this:

Screw the finished NMEA 2000 panel connector onto the enclosure.

Yet another photo of a finished connector and the pinout:

Connecting other panel connectors

Now that the hard part is done, the other connectors can be screwed in place. To improve the watertightness of the WiFi antenna connector, you can add a small O-ring or a gasket around the connector before mounting it.

In the end, this is what you should have:

SH-RPi Assembly

Now we want to mount the Raspberry Pi in the enclosure. We’re using the plastic enclosure and the mount adapters that should have arrived with the enclosure.

First, we’ll attach the short standoffs to the mount adapters with the M2.5 nuts. Try to get them tight.

Once the standoffs are in place, the adapters themselves can be mounted to the enclosure with the self-tapping screws.

The Raspberry Pi goes on the standoffs. Fix the upper standoffs with the M2.5 screws and the lower ones with two 16mm hex standoffs.

The Sailor Hat comes next. Press it on the Raspberry Pi GPIO header. Secure it with two M2.5 screws.

NB: Whenever you need to remove the Hat, you might be inclined to wiggle the hat sideways. While this works well, there is also a small risk of bending the Pi header pins at either end of the connector. Instead, wiggle the hat up and down while gently pulling up. It’s a bit slower but the hat will pop off with much less risk of bending the pins.

At this point you can also plug in all USB devices and connect the SH-RPi power and CAN cables. If you’re using a colling fan, mount it as well. Use two-sided tape or a bit of hot glue to fix it next to the Raspberry Pi, with the sticker side facing the Pi.

This is what the finished assembly looks like:

Don’t close the lid yet. You’ll still have to insert the memory card to the Pi.

Software

In this section, we’ll install the OpenPlotter software on the Raspberry Pi. OpenPlotter is a specialized marine software distribution based on the Raspberry Pi OS. It comes in many flavors; in this tutorial, a headless version is used, meaning that no display is directly connected to the Raspberry Pi. For display purposes, web browsers or remote desktop connections are used instead, allowing for more secure placement of the server and screens where you need them.

Installing OpenPlotter

OpenPlotter is installed by writing a disk image to a MicroSD card and inserting that card into the Raspberry Pi.

First, download Raspberry Pi Imager. The Imager is an easy-to-use piece of software that is used to write the downloaded image file to the memory card.

NOTE: The Imager is only available for download for macOS, Windows, and Ubuntu Linux. If you are using some other operating system or Linux distribution, you might need to use some other software to flash the card (but at that point, I assume you are well aware of how to do that).

Once downloaded, install the imager.

Next, download the OpenPlotter image. I am using the Headless image in this tutorial. If you’d rather connect a display to the Pi, you can also get the Starting image. Once the image has been downloaded, you might have to unzip it for flashing. The disk image is quite big, so you should have a few gigabytes of free space on your drive.

Flash the image the the MicroSD card. First, insert the card in a reader connected to your computer. Many laptops also have integrated SD card readers. To use those, use the SD adapter that you received with the card. Then, open the imager. In the operating system menu, select “Use custom” at the bottom of the list, and then select the downloaded image file.

Then select the correct MicroSD card with the Storage button. To avoid any costly mistakes, I recommend removing any other pluggable media from your computer. Click Write. You might have to enter your password at this stage to allow Imager to write to the MicroSD card.

Writing and verifying to MicroSD card will take a bit of time. We can use that time to download and install VNC Viewer. VNC Viewer is a remote desktop software that we will use to access OpenPlotter in the following sections.

Once the MicroSD card is done, insert it in the Raspberry Pi MicroSD card slot. You might have to temporarily unplug the hat to do that. (Yeah, sorry, the tutorial isn’t 100% consistent.)

Finally, power on the device. While it’s possible to plug a 5V USB-C cable in the Raspberry Pi, that will lead you into trouble once you install the SH-RPi daemon software later in this tutorial. So, you should use a 12V power supply (actually, anything between 10-32V goes) and wire it to an NMEA 2000 plug. You can also insert some short female jumper wires directly to the JST XH connectors and use small alligator clips to connect the wires to a power supply. Use your imagination!

OpenPlotter initial configuration

At this point you should have a device with a lot of blinking lights but no way to communicate with it. Luckily, there is a way. If you look at availabe Wi-Fi networks around you, you should see a network called “openplotter”:

Connect to that network (the password is 12345678).

Now, you’re within the reach of the Pi. To access it, we’ll use VNC Viewer we installed previously.

On startup screen, type openplotter.local in the address bar (if that doesn’t work, the try entering the IP address 10.10.10.1). If the server was found, you’ll be greeted with an authentication screen:

Enter username pi and password raspberry.

If everything was successful, you’ll be greeted with a pristine OpenPlotter desktop view:

Great! Go through the initial Pi welcome wizard. You’ll have to first enter a new password and select the country, language, and other basic settings.

If you have plugged in a compatible USB WiFi dongle, you’ll need to select a WiFi network to connect to. This is very handy as it will allow you to connect to the internet to download updates and whatnot.

Note that if you don’t have a WiFi adapter plugged in, the initial setup might be a bit different from what’s described below.

During the initial setup, the Pi will update the system software. It will take a while, so go get a coffee or play with your spouse/kids/pets.

Once the setup is complete, restart the Pi. You were connected to the Pi’s WiFi access point, so your computer’s network connection will revert back to your regular WiFi at this point. If you have the USB WiFi adapter and configured the Pi to use the same network, you can still access the Pi using the same openplotter.local address. See why I recommended getting the extra WiFI adapter? Otherwise, you’ll need to reconnect to the “openplotter” network once it becomes available again.

Anyway. Get back to VNC Viewer and connect to openplotter.local. You changed the pi user password during the initial configuration, so you’ll need to enter the new password in VNC Viewer.

Once you’re back in, we’ll modify the network settings on the OpenPlotter installation. From the Raspberry menu, select OpenPlotter -> Network.

(When opening the Network app, the it might complain that it wants to reconfigure your system. Let it do that and reopen the app once it’s done.)

In the network panel, you’ll see the available network devices on the left and the access point settings on the right.

If you don’t want to have an access point, select “none” in the left side menu. If you want to keep the AP (and I’d recommend that because that provides you a backup access the Pi), it’s important to change the network password:

penplotter_network_password.jpg"){:width=“50%”}](assets/screenshots/14_openplotter_network_password.jpg)

The WiFi client settings can be found at the WiFi symbol in the upper right hand corner of the OpenPlotter desktop. That’s where you configure additional networks such as your boat’s WiFI AP.

After modifying the network settings, reboot OpenPlotter.

Installing SH-RPi-daemon

The most urgent things out of the way, it’s time for us to install the SH-RPi-daemon. (Daemons are benevolent spirits that serve to help define a person’s character or personality. Or in this case, background services for UNIX descendant operating systems.) We could use the VNC Viewer for doing that by opening Accessories -> Terminal from the Raspberry menu, and that is what I recommend Windows users to do, but for Mac and Linux users, I’ll show how to access the OpenPlotter device using SSH.

First, we’ll do a small digression. Instead of just madly ssh’ing in, we’ll first use ssh-copy-id to copy our SSH public key to the device. This will allow subsequent logins to be performed without entering a password.

Mac users may have to install ssh-copy-id first. It is available via Homebrew – if you haven’t installed it yet, do so! It’s great! Once you have that, do:

brew install ssh-copy-id

Linux users, on the other hand, are pampered and have ssh-copy-id already preinstalled.

Next, copy the public key:

ssh-copy-id pi@openplotter.local

And that’s it! Now you can login to the Pi without a password. I recommend to use this method on all systems you’re accessing remotely – it’s more secure than using passwords.

Once you’ve logged with ssh pi@openplotter.local, copy paste the installation command to the command prompt:

curl -L \
https://raw.githubusercontent.com/hatlabs/SH-RPi-daemon/main/install.sh \
| sudo bash

If you have a relatively unmodified system, this command will install the required configuration changes and the daemon software automatically. It should only take a few seconds. All you need to do is to manually reboot once the installation has finished:

sudo reboot

When rebooting, pay attention to the SH-RPi LEDs. The RX led has been solid green and the Status led solid red, but after rebooting, RX led will flicker happily (assuming there’s traffic on the NMEA 2000 bus), and the Status led is red but blinks briefly every second. These changes indicate that the CAN interface and that the daemon watchdog are active. Yay.

When you connect to the VNC after rebooting, you’ll see the following message:

This indicates we now have an active can interface but it isn’t configured in Signal K yet. We’ll do that in the next section.

Configuring Signal K to receive NMEA 2000 traffic

To process the NMEA 2000 data, we need to configure Signal K to receive it. Open the Signal K dashboard at http://openplotter.local:3000/.

To do anything with the server, you need to enable security and create an admin user. Click the “Login” button at the top right:

You’re asked to create a new admin user. I prefer to use admin as the username, and then a suitable easy-to-remember, easy-to-type password as the password. This is only accessible from your internal network.

Next, you might want to upgrade the SK server:

Once you’ve done that, we can get to business and enable can0 on the server. Go to Data Connections and click the Add button:

Then, configure the connection as follows, and scroll down and click Submit:

After you’ve added the data connection, restart the server again. Now, the dashboard should show some connection activity:

Yay. Time to congratulate yourself. You’ve come far!

If you want, you can also open the Data Browser at the left hand side menu and see what data you’re receiving.

Creating Instrument Panels

If you’re receiving data, you can already visualize it by opening the SK Instrument Panel:

You can configure some paths by using the wrench button. The panel sizes and positions can be adjusted by clicking the lock button.

My test lab is just under a metal roof with absolutely now GPS reception, and the only interesting data in my network is coming from the 1-Wire Temperature Sensor. So, my instrument panel now consists of three temperature values:

A little bit sad, but exciting at the same time!

In addition to the standard Instrument Panel, there are a lot of very nice dashboard applications for Signal K. You might want to try KIP (found at the SK server app store) or Wilhelm SK (for iOS devices only, available at the App Store).

Installing InfluxDB and Grafana

In the final steps of this tutorial, we install and configure InfluxDB and Grafana to create a historical log and visualizations of the boat data. It’s a few more steps and some busy-looking screens, but well worth the small effort!

InfluxDB is a time-series database that we’ll use for storing the data. Grafana is a visualization toolkit often used for visualizing IT system health, but due to its versatility, can be used for our marine data visualization purposes as well.

To install InfluxDB and Grafana, go back to VNC Viewer and open OpenPlotter -> Dashboards from the Raspberry menu:

Select InfluxDB and click Install. It’ll take a while but once it’s finished, go back to the Apps tab and select Grafana and click Install. That’s it.

Then we’ll have to create a new database in InfluxDB. Open Chronograf, an InfluxDB web UI in your browser: http://openplotter.local:8889/.

Click through the initial configuration. The Chronograf InfluxDB connection uses username admin, password admin. You can skip dashboard creation and Kapacitor configuration.

Next, create the new database using the InfluxDB Admin screen:

Give the database name signalk, otherwise just click through. Done.

Now that we have the database waiting for us, let’s feed some data to it. Go back to the Signal K dashboard to configure the InfluxDB writer plugin:

Leave the username and password empty. Our database was signalk. If you want, modify the batch write interval and data resolution. The interval is 10 seconds by default, but if you want a bit more real-time display of data, enter 2. Resolution dictates how often a single measurement is written to the DB. The default of 200 ms is probably fine but I wanted even more and chose 100 ms. Also select the checkboxes as shown below.

Scroll down and click Submit to apply the configuration. At this point, we should have measurements flowing into the database. Let’s verify that. Go back to Chronograf, select the Explore view. You should have a source called signalk.autogen at the bottom. Select that, and individual measurement names should appear. Great.

The only thing that remains is to visualize the historical data.

Creating a sample Grafana dashboard

We’ll use Grafana to show some fancy graphs. Open Grafana in your browser: http://openplotter.local:3001.

Grafana requires a new password to be entered, so do that. Once you get to the home screen, configure the InfluxDB data source:

In the configuration, the default URL is shown in dark grey but I found I had to explicitly type it in. Other than that, it’s again the same signalk database and empty user and password. Click “Save and Test” to verify that your data source works.

At this point, let’s recap what we have. We have Signal K receiving the data from NMEA 2000, we have InfluxDB to store that data, and we have connected Grafana to InfluxDB. Finally, we can create a Grafana dashboard and add new data panels.

The panel editor is a bit busy, but the basic steps are straightforward.

Edit the query. First, select a measurement in the FROM row. Second, you have to add a math modifier to convert the measurement units (Grafana isn’t really unit-aware, so by default it always displays the data in the SI units they’re stored in). For example, to get to °C from Kelvin you need to subtract -273.15. Or to get from m/s to kn, multiply by 3600 and divide by 1852.

Finish the panel by giving it a title and applying the changes.

You should now have a single panel with a little bit of time data visible in your dashboard. Add a couple of more panels by clicking the Add Panel button. You can position and resize the panels by dragging their titles and corners. Finally, you can select a suitable time range from the top bar and save the dashboard.

This is what my resulting engine temperature dashboard looks like:

That’s it. Go create awesome dashboards and show them to your marina and yacht club buddies! Also share them at Hat Labs Discussion forum for inspiration!

5 - Hardware revisions

Introduction

This page documents different board revisions and provides links to the schematics. Full design file history is available at the SH-RPi-hardware GitHub repository.

Version 1.0.0

First version sold at hatlabs.fi.

Schematics: SH-RPi-1.0.0-schema.pdf

6 - Errata

This page lists all known hardware bugs for different SH-RPi revisions.

(No issues so far!)