This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation

1 - Getting Started

Hardware Assembly

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

  1. Insert the 40-pin stackthrough header into the SH-RPi through the socket on the bottom side, pins facing upwards.
  2. Plug the SH-RPi onto the Raspberry Pi GPIO header (optionally using the hex standoffs).
  3. Attach appropriate power wires to the terminal plugs. The terminal plugs arrive with the screws tightened, so ensure you loosen them before inserting the wires.

Hardware assembly diagram for SH-RPi v2.0.0.

Power Connection

Connect a 10-32 V power source to the SH-RPi power input connector as shown in the following figure.

Connect the power source to the connector circled in green.

The power source must be rated for at least 1.0 A current at the specified output voltage. All things being equal, a power supply with a higher output voltage, such as 24 V, will result in slightly more efficient operation. Otherwise, 12 V power systems on boats and vehicles, or DC power sources, work well.

Software Installation

Additional software is required for the Raspberry Pi OS to run the system service that will automatically initiate system shutdown when power is cut. An automated installation script is provided to simplify the installation process.

Automated Installation

An automated installation script is provided. The script is tested on newly flashed Raspberry Pi OS and may fail on heavily modified systems. Installation has not been tested on other operating systems.

To run the automated installation script, copy and 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 spans three lines, and when you paste it into your terminal window, it may display line continuation characters. That’s okay. Press “Enter” to run the command.

Installation command in terminal

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

The automated installation script will:

  • enable the I2C interface, required for the SH-RPi to communicate with the Raspberry Pi
  • if support for the NMEA 2000 interface add-on card is selected
    • enable the SPI interface and a device overlay
    • define the CAN network interface
  • if support for the NMEA 0183 interface add-on card is selected
    • enable the SPI interface and a device overlay
  • enable the device overlay for the real-time clock
  • if support for the MAX-M8Q GNSS HAT is selected
    • enable the serial UART interface
    • disable the serial console
    • disable Bluetooth as it conflicts with the serial UART interface
  • install the SH-RPi service software

Enclosures

If you plan to use your Raspberry Pi and SH-RPi outdoors, in a vehicle or on a boat, or in highly condensing environments, always place the device in a waterproof enclosure! Hat Labs offers a variety of waterproof enclosures.

The medium and large enclosures come with a perforated base plate and mount adapters that can be used to mount the Raspberry Pi, additional HATs and other components. Other enclosures are provided with 3D printed sticker mounts.

Medium Enclosure Build

The medium size enclosure is designed to fit the Raspberry Pi 4 Model B, the SH-RPi and multiple HATs in a vertical orientation. Installation is described below.

Assembly

We start with a bare enclosure, shown in the following figure.

Enclosure without any of the components.

First, install all connectors you need. Before installing the connectors, you may need to solder wires to them. Soldering instructions for cup terminals can be found in this YouTube video:

There is no real standard for the power connector pinouts, but we suggest to always connect GND to pin 1 and +12V/24V to pin 2. The following figure shows the power connector installed.

Then, insert the connectors into the enclosure. The following figure shows the connectors installed.

Connectors installed.

If the enclosure is to be used in a condensing environment such as on a boat or outdoors, seal the remaining holes with plugged cable glands. The following figure shows how the plug should be installed in the cable glands.

Cable gland plug.

And the following figure shows the cable glands installed. This makes the enclosure waterproof.

Cable glands installed.

Next, we take the parts we want to install in the enclosure and place them on the base plate. The following figure shows the parts we will install. The black plastic parts are the vertical mounts that hold the PCB stack in place.

Ingredients.

First, the 6mm hex standoffs are screwed into the vertical mounts. Hand tigthen only!.

The following figure shows the vertical mounts with the standoffs installed.

Vertical mounts with hex standoffs.

You can then attach the mounts to the Raspberry Pi or the base board. Use the M2.5 screws to attach the board next to the GPIO pins and the M2.5 16mm hex standoffs on the opposite side.

Next, we install the stack-through header onto the SH-RPi. Press gently and evenly to avoid bending the pins. The optimal header height depends on the HAT ordering. If you insert the SH-RPi directly on top of the Raspberry Pi, remove the spacer from the stack-through header. On the other hand, the spacer is needed if you install the SH-RPi on top of another interface HAT.

Inserting the stack-through header.

The next figure shows the SH-RPi mounted on the base board.

SH-RPi mounted on the base board.

Power Wiring

In this walkthrough, we will also install an additional CAN HAT for NMEA 2000 connectivity. The following figure shows the CAN HAT mounted on the SH-RPi.

CAN HAT mounted on the SH-RPi.

The next step is to install the PCB stack on the base plate. Use the provided M3 screws to secure the stack in place. Do not overtigthen the screws.

PCB stack installed on the base plate.

Next, strip the connector wires. If a separate power connector is used, the NMEA 2000 red wire should be left unstripped or cut off altogether. The following figure shows the stripped wires.

Stripped power and CAN wires.

The next step is to connect the wires to the PCB connectors. The power connector should be connected to the terminal plug as shown in the following figure.

When you plug in the terminal plug, be very careful to plug it to the input connector on the SH-RPi. You may damage all devices on the stack if you plug it to the 5V output connector!

Power connector terminal plug arrangement.

Then, the CAN wires should be connected to the CAN HAT connector CAN0 as shown below. Black is ground, white is CAN high (H) and blue is CAN low (L).

Final wiring arrangement.

Powering from NMEA 2000

When using on a boat, you can also power the system from the NMEA 2000 network. In this case, all wires from the NMEA 2000 connector are used.

When powering the device from the NMEA 2000 network, all wires from the NMEA 2000 connector are used.

The black and red wires are connected to the power terminal plug, with a short piece of black wire spliced to GND terminal as shown in the following figure. The short black wire connects to the GND terminal of the CAN HAT CAN0 connector.

Connect the NMEA 2000 GND wire to both the power terminal plug and the CAN HAT CAN0 connector.

The next figure shows the final wiring arrangement when powering the device from the NMEA 2000 network.

Final wiring arrangement when powering the device from the NMEA 2000 network.

Securing the Stack

Finally, the loose end of the stack can be secured to the base plate using small zip ties, but as an alternative, simple tie wraps are a simple and easy to use alternative. The following two figures show the tie wrap installation.

Tie wraps inserted.

Finished tie wrap installation.

Finishing the Assembly

At this point, the base plate can be inserted into the enclosure.

Base plate in place.

Secure the base plate to the enclosure with the provided screws.

Screwing the base plate to the enclosure.

Finally, the assembly is done. The figure below shows the setup happily blinking away in the enclosure.

The finished setup.

The enclosure can be mounted to a wall or a bulkhead through the corner holes shown in the figure below.

Mounting hole locations.

Drilling Holes

If you’re using an enclosure without pre-drilled holes, you’ll need to drill the holes yourself.

At a minimum, you need one hole for power input and, for any metal enclosure, another for a Wi-Fi antenna or a wired Ethernet connector.

Plan the hole/connector placement to fit your intended installation location. If you’re planning to wall-mount the enclosure, place the connectors facing down 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 (Wi-Fi antenna): 6.5-7 mm or 1/4"
  • PG7 cable gland and M12 (NMEA 2000) panel connector: 12.5 mm or 1/2"
  • SP13 panel connectors (blue-black plastic connectors): 13 mm.
  • 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

The enclosures provided by Hat Labs include mounting adapters that can be used to mount the Raspberry Pi.

Soldering the Panel Connectors

When soldering the internal wires to the panel connectors, always use heat shrink tubing on the individual wires. Always remember to slide the heat shrink onto 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 double-sided tape or hot glue.

The fan should be connected to the generic 5V output connector on the SH-RPi:

Connect the fan to the connector indicated by the red arrow.

Finalizing Installation

Once you have completed drilling holes, mounting the Raspberry Pi, soldering the panel connectors, and connecting the fan, close the enclosure to protect your SH-RPi and Raspberry Pi from the elements. Ensure that all connections are secure and the enclosure is tightly sealed to prevent water ingress.

Testing the System

After completing the installation, power up your Raspberry Pi and SH-RPi system to ensure that everything is functioning correctly. Check that the Raspberry Pi boots up, the fan is operating, and the SH-RPi is communicating with the Raspberry Pi. Once you have verified that everything is working, you can proceed with configuring your software and integrating the system into your intended environment.

Congratulations! You have successfully completed the hardware assembly and enclosure setup for your SH-RPi and Raspberry Pi system.

2 - Hardware 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 Phoenix MC compatible 3.81 mm (0.15") pitch connector. The permitted voltage range is 9-32V. The protection circuitry at power input includes:
    • 4 A SMD fuse
    • 33 V transient voltage suppressor (5000W peak pulse power capability)
    • Reverse polarity protection diode
    • A choke and a pi-filter for controlling conducted electromagnetic interference
  2. First stage step-down (buck) converter with current limiting. The buck converter transforms the input voltage into an 8.8 V potential that the supercapacitor bank can handle. The step-down converter circuit also includes a separate current limiter that throttles the input current to 0.8 A (at the default setting).
  3. Three 20F 3.0 V supercapacitors. The supercapacitor bank acts as a power reservoir for the Raspberry Pi. It can power a Raspberry Pi 4B for up to 70 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 the maximum individual node current to 1.0 A.
  4. Microcontroller. The SH-RPi operations are controlled by an ATtiny1616 microcontroller. The microcontroller performs the following functions:
    • Measures the input voltage
    • Measures the input current
    • Measures the supercapacitor voltage
    • Controls the status LED array
    • Controls the 5V output
    • Receives real-time clock interrupt information
    • Communicates the SH-RPi status to the Raspberry Pi service over I2C
  5. Second stage buck converter. The buck converter converts the supercapacitor bank potential into the 5V Raspberry Pi input voltage. The maximum instantaneous output current capacity is 5 A, with at least 3 A attainable as continuous current without active cooling. The buck converter operation is controlled by the microcontroller. The microcontroller enables the boost converter when the supercapacitor voltage has risen above 8.0 V. During system shutdown or watchdog reboot, the microcontroller disables the boost converter to cut the Raspberry Pi input voltage.
  6. Status LED array. The four status LEDs indicate the board operational status LEDs as described in Section Status LEDs.
  7. Real-time clock. The board includes a PCF8563 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.

Connectors

SH-RPi connectors, top side.

SH-RPi connectors, bottom side.

  1. Power input connector.

    The power connector is a Phoenix MC compatible 3.81 mm (0.15") pitch connector. The sales package includes a compatible screw terminal plug.

  2. 5V output connector. External 5V peripherals can be connected to this connector. The 5V output connector is a Phoenix MC compatible 3.81 mm (0.15") pitch connector as well.

  3. Pass-through Raspberry Pi GPIO header. This is a standard 2x20 pin Raspberry Pi GPIO header. A provided stack-through connector should be inserted to connect the SH-RPi to a Raspberry Pi. Additional hats can be stacked on top of the Sailor Hat.

  4. ATtiny1616 programming and debugging header. The header can be used to program the microcontroller with an external programmer or to enable onboard programming.

  5. Current limiter header. Jumpers can be placed on the current limiter header to change the current limit setting to 1.8 A or 2.8 A (the default is 0.8 A). Place a jumper horizontally on the top row (labelled 2A) to set the current limit to 1.8 A. Place a jumper horizontally on the bottom row (labelled 3A) to set the current limit to 2.8 A.

  6. External interrupt header. Not functional in v2.0.0 hardware.

  7. CR1220 battery connector for real-time clock (on the bottom side). The 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 away from the board.

  8. RTC Enable solder jumper. The Real-time clock is enabled by default. To disable the RTC, cut the traces between the solder jumper pads with a sharp knife. Be careful to not cut any nearby traces.

  9. GPIO4 Enable. Connect the pads to connect Raspberry Pi GPIO4 to onboard microcontroller port PB5. This requires custom firmware functionality to be useful.

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 such as unregulated power supplies or a boat’s “house” battery system. The power supply permits input voltages between 9-32 V, although a potential less than 10 V will be regarded as an undervoltage situation to prevent deep-discharge damage to typical lead-acid batteries.

The operational diagram of the power supply subsystem is shown in the picture below.

The maximum input current is restricted to protect upstream power supplies and wiring. The default current limit is 0.8 A, but the limit can be increased to 1.8 A or 2.8 A by placing jumpers on the current limiter header.

The input voltage is stepped down by the first stage buck converter to charge the supercapacitor bank up to a voltage of 8.8 V. The supercapacitors are used to provide a power reservoir for the Raspberry Pi, both for short-duration glitches and to provide last-resort power during a system shutdown.

The second stage buck converter converts the supercapacitor voltage into the 5 V Raspberry Pi input voltage. The 5 V output is enabled by the microcontroller when the supercapacitor voltage is above 8.0 V and disabled when the supercapacitor voltage drops below 5.0 V. These limits can be configured by the user.

The maximum peak current output to the Raspberry Pi is 5 A. The maximum average current output is subject to the input current limiter setting and ambient temperature. At 0.8 A input current limit, the maximum sustained output current is about 1.4 A. At 2.8 A input current limit setting, the maximum average output current is limited by the system thermal characteristics. In an open space at room temperature, the maximum average 5 V output current is at least 3.0 A. Higher values are possible with active cooling of the SH-RPi board.

At 1.4 A output current, the total power supply efficiency is 79%.

Power supply operation diagram with example current and voltage values.

Status LEDs

The SH-RPi LED array at the left side of the board is used to indicate the operational status of the board. The bar display indicates the charge state of the supercapacitor bank. The first LED begins to light up when the voltage is above 5 V and all LEDs are fully lit at 9 V supercapacitor potential.

Overlaid on the bar display, different blink patterns indicate the state of the board as follows.

PatternDescription
No blinkingCharging/normal operation (1)
Short blip off every 4 sWatchdog active (2)
Roll to leftNo input voltage (3)
Two blips off with 1 s pauseShutting down (4)
Two blinks on with 2 s pauseSleeping (5)
Alternating LEDs blinkingWatchdog reboot (6)
Rapid blinkingFault - contact manufacturer (7)

Detailed description of the states follows:

  1. The supercapacitors are charging and if the supercap voltage is above 8.0 V, the 5 V output is enabled. The Raspberry Pi OS daemon is not active.
  2. The daemon is active and the watchdog is enabled. The operating system has started up and is running normally.
  3. Power input is lost and the supercapacitors are depleting. The 5 V output is enabled.
  4. The daemon has initiated a shutdown. The SH-RPi is waiting for the Raspberry Pi to shut down.
  5. The SH-RPi is in a sleep state. The 5 V output is disabled and the board is waiting for a real-time clock alarm to wake up.
  6. SH-RPi did not receive a heartbeat from the daemon for 10 s, suggesting that the Pi has crashed. The Raspberry Pi is reset by turning 5 V off for two seconds.
  7. The SH-RPi has detected a supercapacitor overvoltage condition. Contact the manufacturer for further assistance.

Watchdog Reboot Functionality

In addition to the power supply, the Sailor Hat for Raspberry Pi incorporates a hardware watchdog timer that can be used to reboot the Raspberry Pi in the case of a software or hardware lockup. The watchdog timer is enabled by default and can be disabled with a solder jumper if needed. When enabled, the watchdog timer will restart the Raspberry Pi if it doesn’t receive a “heartbeat” signal from the Raspberry Pi within a predetermined time interval (typically 10 seconds).

The Raspberry Pi must run a service that sends a periodic heartbeat signal to the SH-RPi. The service can be installed from the provided software package.

If the watchdog timer triggers a reboot, the SH-RPi will disable the 5V output for a short period to force a Raspberry Pi restart. The SH-RPi will then re-enable the 5 V output to allow the Raspberry Pi to boot up again.

Real-Time Clock

The SH-RPi includes a PCF8563 real-time clock (RTC) that can provide accurate timekeeping even when the Raspberry Pi is not connected to the internet or a GPS signal is not available. The RTC is connected to the Raspberry Pi via the I2C bus.

To use the RTC, a CR1220 backup battery must be installed on the bottom side of the board. The positive side (the flatter side) of the battery should be facing away from the board.

When using the SH-RPi board with a built-in RTC, the RTCs may have conflicting I2C addresses. In such a case, the RTC on the SH-RPi can be disabled by cutting the traces between the RTC EN solder jumper pads.

Configuration

The Sailor Hat for Raspberry Pi can be configured by the user to adapt to specific use cases. Configuration options include:

  1. Current limiter setting. The input current limiter can be set to 0.8 A (default), 1.8 A, or 2.8 A by placing jumpers on the current limiter header.
  2. Real-time clock enable. The RTC can be enabled or disabled with a solder jumper.
  3. Watchdog timer enable. The watchdog timer can be enabled or disabled with a solder jumper.
  4. GPIO4 enable. Connect the pads to connect Raspberry Pi GPIO4 to the onboard microcontroller port PB5. This requires custom firmware functionality to be useful.

I2C

Sailor Hat communicates with the Raspberry Pi using I2C bus 1 on GPIO pins 3 and 5. (GPIO2 and GPIO3, respectively). The I2C address is 0x6d.

The PCF8563 real-time clock additionally reserves the I2C address 0x51 on the same bus.

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 not to have automated scripts modify your system configuration or if you have to troubleshoot your installation.

For manual installation, download the code at github.com/hatlabs/SH-RPi-daemon. The required software and configuration changes, as well as the firmware software details, are described below.

Enabling I2C and SPI

The 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

Find the following line:

#dtparam=i2c_arm=on

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

dtparam=i2c_arm=on

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,pcf8563

Then, 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 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 install -y python3-pip
sudo pip3 install .

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

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

That’s it! After a reboot, the daemon will start automatically.

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

Command-line Interface

The command-line interface is a Python script that can be used to control the Sailor Hat for Raspberry Pi from the Raspberry Pi command line. It is installed by the installation script described in the Getting Started Section.

The script, shrpi, can be run with the --help option to get instructions on the different commands. Some main use-cases are described below.

shrpi print

Print the current status and configuration of the Sailor Hat for Raspberry Pi.

shrpi set <option> <value>

Set different configuration values. For example,

shrpi set led 50

will set the LED brightness to 50%.

shrpi sleep 3600

Shut down the Raspberry Pi and turn it back on after 3600 seconds (1 hour).

shrpi sleep 15:00

Shut down the Raspberry Pi and turn it back on at 15:00 (3pm).

shrpi sleep 15:00:00

REST API

shrpid implements a REST API that can be used to query the current status and configuration of the Sailor Hat for Raspberry Pi and to set configuration values. The API is available on a file socket at /var/run/shrpid.sock. An example query with curl is shown below:

curl --unix-socket /var/run/shrpid.sock http://localhost/state

For further details on available commands, see the SH-RPi-daemon source code.

Firmware

The program code running on the onboard ATtiny1616 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 Raspberry Pi itself. This requires some jumpers and a bit of software configuration.

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

Hardware Configuration

Place jumpers on all pins on the PROG header as shown in red in the figure below. This will connect the microcontroller programmer circuitry and the debugging serial interface to the Raspberry Pi. In addition, the 5V output of the buck controller is forced on, so that the Raspberry Pi won’t turn itself off when starting the flashing process.

Set the red jumpers to enable self-flashing.

Note! For proper operation afterwards, it is essential that you remove at least the third jumper from the PROG header. Otherwise, the Raspberry Pi will not be able to turn itself off.

Raspberry Pi configuration changes

The next step is to enable the serial UARTs on the Raspberry Pi. They are used for both the UPDI and serial debugging interfaces. On Bluetooth-enabled Pis, the UART is normally reserved by the onboard Bluetooth circuitry. So, let’s disable Bluetooth.

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

``ìni dtoverlay=disable-bt dtoverlay=uart5


The first one disables the Bluetooth modem. The second one enables the UART5 interface on the GPIOs 12 and 13 on pins 32 and 33. This is the serial interface used by the SH-RPi firmware for debugging.

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

```bash
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

Thanks to the PlatformIO framework, all necessary tools can be downloaded and installed automatically. We just need to get the firmware source code first. Let’s install the git version control system and clone the firmware repository:

sudo apt update
sudo apt -y install git
git clone git@github.com:hatlabs/SH-RPi-firmware.git

Now, we can install the PlatformIO framework:

sudo pip3 install -U platformio

Edit the platformio.ini file and change the upload_port to /dev/ttyAMA0:

[env]
...
upload_port = /dev/ttyAMA0
monitor_port = /dev/ttyAMA1

Flashing

Finally, we can build and upload the firmware. The first time you run this command, it will download and install the necessary tools. This may take a while.

cd SH-RPi-firmware
pio run -t upload

The white status LEDs will turn off during the flashing. After a few seconds, they will turn on again and the flashing is complete. At this point, remove the jumpers from the PROG header.

Restoring Bluetooth

If you want to keep using Bluetooth, remember to undo the steps you made previously. To do this, you’ll need to reverse the changes you made to /boot/config.txt, /boot/cmdline.txt, and re-enable the hciuart service:

  1. Remove the following lines from /boot/config.txt:
dtoverlay=disable-bt
dtoverlay=uart5

  1. Add console=serial0,115200 back to the beginning of /boot/cmdline.txt.

  2. Re-enable the hciuart service by running:

sudo systemctl enable hciuart
  1. Reboot your Raspberry Pi for the changes to take effect.

That’s it! You have successfully updated the firmware on your Sailor Hat for Raspberry Pi and restored Bluetooth functionality if desired.

4 - Frequently Asked Questions

Can I power the Raspberry Pi using the standard USB-C connector while the SH-RPi is connected?

The answer is no. Or at least, this should be avoided. Nothing will happen if the SH-RPi is powered and the supercaps are charged above 5V. However, if the supercaps are discharged, they will be back-powered through the 5V bus. In practice, this will likely overpower the USB power supply and cause it to shut down without any permanent damage. However, this is not a controlled situation and damage is possible to the power supply, the Raspberry Pi, or the SH-RPi itself.

Another aspect is that even with the supercaps charged, the daemon software will not see any input voltage and will trigger a shutdown immediately after booting.

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 2.0.0

Completely redesigned board with a new power management circuit.

  • Standard Raspberry Pi HAT form factor
  • 3x20 F supercapacitors
  • Improved current limiting
  • Improved power output capability

Schematics: SH-RPi-2.0.0-schema.pdf

Version 1.0.0

First version sold at hatlabs.fi.

  • Includes both a supercapacitor power management circuit and an NMEA 2000 interface
  • Single 60F supercapacitor
  • Optional real-time clock

Schematics: SH-RPi-1.0.0-schema.pdf

6 - Errata

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

Version 2.0.0

  • External input pins (2x2 pin header labeled E and P) are shorted to ground and inoperable.

7 - Add-on hardware

Instructions for different add-on hardware will be provided on this page.

7.1 - Compute Module 4

The Compute Module 4 is a small form factor computer module that plugs into a carrier board. Providing CPU performance identical to the Raspberry Pi 4B,tThe CM4 is a powerful, flexible, and low-cost solution for embedded applications. When building embedded computers, the CM4 has several advantages over the Raspberry Pi 4B:

  • Built-in eMMC flash memory: The CM4 boards have, depending on the model, up to 32 GB of eMMC flash memory. This memory is both more reliable and faster than the SD card used in the Raspberry Pi 4B.
  • Option for an external WiFi antenna: The CM4 has a dedicated connector for an external WiFi antenna. This is useful if the signal strength of the internal WiFi antenna is not sufficient.
  • M.2 connector: Many base boards have an M.2 connector that can be used to connect an M.2 SSD or an M.2 WiFi module.
  • Lower power consumption: in informal testing, we have found a CM4 and a base board to consume over 20% less power than a Raspberry Pi 4B.

On the downside, most of the CM4 base boards do not include an USB 3.0 hub, meaning that the USB ports are limited to USB 2.0 speeds. Also, flashing the eMMC is slightly more complicated than flashing an SD card. The process is described below.

Flashing the eMMC Memory on the CM4

First, you need to download a suitable image. We are using the OpenPlotter Headless image as an example, but the process is the same for other images. Note: Always use a 64-bit image! Some software components will have issues when running on a 32-bit system (InfluxDB, in particular).

The eMMC memory can be flashed with the same image as the Raspberry Pi 4B. The flashing process has two extra steps. First, the CM4 needs to be switched into a special BOOT mode which actually prevents the device from booting and allows flashing the eMMC. Second, on the computer used for flashing, a small rpiboot utility needs to be installed and run to allow mounting the eMMC memory on your computer. Once these steps are completed, the flashing process is identical to the one used for the Raspberry Pi 4B.

For Windows, the rpiboot is available as a pre-compiled executable, but for Linux and MacOS, you need to compile it from source. The process for each platform is described in the chapters below.

Notes on the installation process:

  1. To flash the eMMC, the base board needs to be switched to BOOT mode. On the Waveshare CM4-IO-BASE boards, the small BOOT switch next to the HDMI0 connector needs to be turned to the ON position.
  2. The base board needs to be connected to an external power source during the flashing process. Use the SH-RPi board for this purpose!

Windows

  1. To set up the flashing mode on the host computer, follow the instructions provided in the Raspberry Pi documentation.
  2. Follow the installation instructions for OpenPlotter.
  3. Note: Do not boot the system yet! We need to adjust a few settings first, as described in the CM4 Configuration section below.
  4. After changing the configuration settings, switch the BOOT switch back to OFF position and reboot the system. You can then continue with the OpenPlotter instructions.

Mac

On a Mac, you need to compile the rpiboot utility from source.

  1. To compile the utility, you need to have Homebrew installed. Do that first.
  2. Then, follow the steps given in the usbboot repository. When you run the sudo ./rpiboot, you should have the CM4 base board connected to your computer and powered up using the SH-RPi. If you get an error message, check the USB cable and the BOOT switch on the base board.
  3. Follow the installation instructions for OpenPlotter. Note: Do not boot the system yet! We need to adjust a few settings first, as described in the CM4 Configuration section below.
  4. After changing the configuration settings, switch the BOOT switch back to OFF position and reboot the system. You can then continue with the OpenPlotter instructions.

Linux

Like on a Mac, you need to compile the rpiboot utility from source on Linux.

  1. To compile the utility, you need to have Homebrew installed. Do that first.
  2. Then, follow the steps given in the usbboot repository. When you run the sudo ./rpiboot, you should have the CM4 base board connected to your computer and powered up using the SH-RPi. If you get an error message, check the USB cable and the BOOT switch on the base board.
  3. Follow the installation instructions for OpenPlotter. Note: Do not boot the system yet! We need to adjust a few settings first, as described in the CM4 Configuration section below.
  4. After changing the configuration settings, switch the BOOT switch back to OFF position and reboot the system. You can then continue with the OpenPlotter instructions.

CM4 Configuration

Enabling USB Ports

Before you boot the system for the first time, you need to make a few changes to the configuration. By default, the USB ports are disabled on the CM4. Obviously, this can be a major issue if you want to use the system with a keyboard and mouse. To enable the USB ports, you need to edit the config.txt file on the eMMC memory. The Boot partition should already be mounted on your computer as a USB drive. Open the drive and edit the config.txt file. Add the following line to the end of the file:

dtoverlay=dwc2,dr_mode=host

Save the file and close it.

Enable External WiFi Antenna

If you have an external WiFi antenna, you need to edit the config.txt file again. Add the following line to the end of the file:

dtparam=ant2

Other possible values are ant1 for the PCB antenna and noant for disabling both antennas. The default value is ant1.

7.2 - Waveshare 2-Channel Isolated CAN HAT

The Waveshare 2-Channel Isolated CAN HAT provides two isolated CAN interfaces for the Raspberry Pi. The CAN HAT is based on the MCP2515 CAN controller and SI65HVD230/SN65HVD230 CAN transceivers. The HAT can be used to implement a single compliant NMEA 2000 interface or two other CAN interfaces. When used as an NMEA 2000 interface, the second channel should be unused due to NMEA 2000 isolation requirements.

The HAT has an integrated isolated DC/DC transformer and doesn’t require external power input.

This page describes the installation and configuration of the CAN HAT when used together with the Sailor Hat for Raspberry Pi. For further details on the CAN HAT, see the Waveshare wiki page.

Jumper Configuration

The CAN HAT has two jumpers for onboard CAN bus termination resistors. For normal operation, they must be set to the OFF position!

Additionally, the CAN HAT has a voltage selection jumper. It must be set to 3V3 when using with a Raspberry Pi, otherwise damage to the Raspberry Pi may occur.

Connecting the HAT

Carefully insert the stack-through header into the CAN HAT GPIO connector. Then, plug the HAT onto the Raspberry Pi’s or the Sailor Hat’s 40-pin GPIO header. The connector edge should be secured to the board below with the hex standoffs.

When using the HAT with an NMEA 2000 interface, only the CAN0 interface should be used. The CAN1 interface should be left unconnected. The figure below shows the wiring for the NMEA 2000 interface.

Wiring for the NMEA 2000 interface. The red wire is left unconnected.

Software Configuration

The Sailor Hat installation script can be used to configure and enable the CAN interface. If you want do perform a manual installation, see the Waveshare wiki page for details.

Powering the SH-RPi using the NMEA 2000 Interface

It is possible to power the Raspberry Pi using the NMEA 2000 interface. For this, the NMEA 2000 power and ground wirens should be connected to the SH-RPi power input, while the H and L wires should go to the CAN0 header on the CAN HAT. Additionally, a ground connection should be made between the SH-RPi and the CAN HAT as shown in the figure below.

Wiring configuration for powering the SH-RPi using the NMEA 2000 interface.

7.3 - Waveshare 2-Channel Isolated RS485 HAT

The Waveshare 2-Channel Isolated RS485 HAT provides two isolated RS-485 interfaces for the Raspberry Pi. It can be used to implement a bidirectional NMEA 0183 interface or two generic bidirectional RS-485 interfaces. When used as an NMEA 0183 interface, one channel is used for receiving and the other for transmitting data.

The HAT has an integrated isolated DC/DC transformer and doesn’t require external power input.

The RS485 HAT can be used simultaneously with the SH-RPi and the CAN HAT.

This page describes the installation and configuration of the RS485 HAT when used together with the Sailor Hat for Raspberry Pi. For further details on the RS485 HAT, see the Waveshare wiki page.

Jumper Configuration

The RS485 HAT has two jumpers for onboard RS-485 bus termination resistors. NMEA 0183 does not use terminators, and the jumpers must be set to the OFF position!

Connecting the HAT

Carefully insert the stack-through header into the RS-485 HAT GPIO connector. Then, plug the HAT onto the Raspberry Pi’s or the Sailor Hat’s 40-pin GPIO header. The connector edge should be secured to the board below with the hex standoffs.

When using the HAT as an NMEA 0183 interface, Channel 1 is used for receiving data (RX) and Channel 2 for transmitting data (TX). The transmitting device TX A and B wires (or TX+ and TX-) should be connected to the HAT Channel 1 A and B terminals, while the receiving device RX A and B wires (or RX+ and RX-) should be connected to the HAT Channel 2 A and B terminals. The figure below shows the wiring for the NMEA 0183 interface.

Wiring for the NMEA 0183 interface. The wiring colors may vary depending on the device.

Software Configuration

The Sailor Hat installation script can be used to configure and enable the RS-485 interface. The interface will be provided by two serial devices: /dev/ttySC0 and /dev/ttySC1. Of these, /dev/ttySC0 is used for receiving data and /dev/ttySC1 for transmitting data. These can be configured in the Signal K data connections or any other NMEA 0183 application of your choice.

If you want do perform a manual installation, see the Waveshare wiki page for details.

7.4 - Waveshare MAX-M8Q GNSS HAT

The Waveshare MAX-M8Q GNSS HAT provides a high-quality GNSS receiver for the Raspberry Pi, based on the U-blox MAX-M8Q module. MAX-M8Q features a multi-constellation GNSS receiver with a high sensitivity of -167 dBm. It supports GPS, GLONASS, BeiDou and Galileo and can receive concurrently from three of these. Additionally, several augmentation schemes such as SBAS, QZSS, IMES and D-GPS are supported.

This page describes the installation and configuration of the GNSS HAT when used together with the Sailor Hat for Raspberry Pi. For further details on the GNSS HAT, see the Waveshare wiki page.

Connecting the HAT

Insert the stack-through header into the GNSS HAT GPIO connector. Then, plug the HAT onto the Raspberry Pi’s 40-pin GPIO header. The GNSS HAT can be stacked on top of other hats.

Using the GNSS HAT together with the RS485 HAT

The MAX-M8Q GNSS HAT features a TIMEPULSE (PPS) feature that is used to provide a highly accurate GNSS time reference to the Raspberry Pi. Unfortunately, this time pulse feature is connected to a GPIO pin that is also used by the RS485 HAT. If these two devices are used together, the conflicting GPIO pin must be physically disconnected. The easiest way to do this is to cut the respective pin on the stack-through header. The figure below highlights the pin that needs to be cut.

The pin that needs to be cut when using the GNSS HAT together with the RS485 HAT.

To ensure the correct pin is cut, insert the stack-through header partially onto the GNSS HAT GPIO connector. Then, cut the top of the pin that is highlighted in the figure above. Disconnect the stack-through header and then cut the pin at the base of the connector.

Software Configuration

GNSS HAT software installation will be automated using the Sailor Hat installation script. As of now, you need to configure the GNSS HAT manually according to the instructions on the Waveshare MAX-M8Q GNSS HAT wiki page. You do not need the steps beyond gpsd configuration.

Depending on the configuration, the GNSS HAT will provide a serial device /dev/ttyAMA0 or /dev/ttyS0 for NMEA 0183 data. OpenPlotter has a nifty serial device configuration utility which can be used to set up and connect the GNSS HAT to Signal K.

Backup Battery

The GNSS HAT features a backup battery connector. The backup battery is used to store ephemeris information in case the Raspberry Pi is powered off. The backup battery is not mandatory but will speed up the time it takes to get a GNSS fix after powering on the Raspberry Pi.

The backup battery type is ML1220. It is a rechargeable Lithium cell and must not be replaced with a non-rechargeable battery. Doing so will result in a risk of explosion and fire! Advanced users can, at their own risk, remove the R3 resistor to disable the charging functionality to use a non-rechargeable CR1220 battery. The schematics and PCB layout are available at the Waveshare wiki page.

8 - Tutorials and Example Projects

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

8.1 - OpenPlotter Server Installation

This section has not yet been updated to reflect the v2 hardware changes.

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:

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:

  • 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:

  • 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:

Drilling template example.

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.

Drilling template on the box.

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.

Drilled holes.

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.

Soldered cups.

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.

Spliced wires.

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

NMEA 2000 micro C female pinout.

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.

Middle pin soldered.

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

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

All soldered.

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:

Heat shrink applied.

Screw the finished NMEA 2000 panel connector onto the enclosure.

Yet another photo of a finished connector and the pinout:

Finished connector.

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:

Connectors in place.

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.

Adapters with standoffs.

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

Adapters mounted.

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.

Raspberry Pi mounted.

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:

Sailor Hat mounted.

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:

width="50%">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!