1. Getting Started

1.1. Download Image

Download SD card image (2.3 Gb file):

1.1.1. 32-bit vs 64-bit images

  • There are pros and cons to each

  • 32-bit takes less memory but runs slower

  • 32-bit is more supported at the moment (Some cameras not supported on 64-bit yet at the time of writing this)

  • QtVlm, wx2img, many OpenCPN plugins are 32-bit only (at the time of writing this)

  • You still can run 64-bit kernel with 32-bit image, user space programs will be 32-bit. (Add arm_64bit=1 into /boot/config.txt)

  • 32-bit is available on more hardware

  • 64-bit OS and OpenCPN are working fine but technically still called 'beta'

  • Most of the open (minor) issues are present in both 32 and 64 bit images

Switch from 32-bit kernel to 64-bit kernel has an impact on java installation. See (workaround): https://github.com/bareboat-necessities/lysmarine_gen/issues/44

1.2. Prepare SD Card

Write the downloaded image to SD card. You can use Raspberry Pi Imager for that:

If your screen resolution is lower than 1024x600 you would need to manually set it in /boot/config.txt file, by mounting /boot partition of your SD card (on windows its done just by inserting it into SD card slot and editing in a plain text editor).

1.3. First Boot from SD Card

Insert SD card into raspberry pi SD card slot and power on. Wait for boot process to run GUI (about 2 mins).

1.4. Setting up Network

1.4.1. Wired Ethernet

If you have wired ethernet router you can just plug-in your raspberry pi ethernet port into the router

1.4.2. WiFi Client

Go into network settings menu and delete WiFi wireless access point.

You need to set up WiFi country

Change /etc/wpa_supplicant/wpa_supplicant.conf to add line for your country (example):

country=US

Change /etc/default/crda to set your country (example):

REGDOMAIN=US

When raspberry pi WiFi card discovers your WiFi router network click to connect to wifi and enter the correct WiFi password.

1.4.3. WiFi Access Point

Wi-Fi connections managed by widely used Gnome NetworkManager. Look for 'nmcli' documentation (command line interface to NetworkManager).

1.4.4. Typical Setup on a Boat

  • Raspberry Pi wired to OpenWrt LTE/4G/WiFi router via ethernet port

  • Raspberry Pi provides 5GHz WiFi 802.11ac local access point for boat local WiFi network

  • OpenWrt LTE/4G/WiFi router provides WiFi connection to marinas

  • OpenWrt LTE/4G/WiFi router provides access to the Intenet via LTE/4G cellular data network

  • OpenWrt LTE/4G/WiFi router provides 2.4GHz (WiFi 802.11n) local access point for boat IoT devices

  • OpenWrt LTE/4G/WiFi router serves as firewall

If you use raspberry pi WiFi it is better to disable WiFi power management:

sudo systemctl unmask wifi_powersave@off.service
sudo systemctl enable wifi_powersave@off.service
sudo systemctl start wifi_powersave@off.service

1.5. Set Timezone / Locale

Open Terminal from GUI and on the terminal command line:

cd ~/add-ons
./timezone-setup.sh

For changing locale (ex: to en_US.UTF-8):

sudo su
perl -pi -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/g' /etc/locale.gen
locale-gen en_US.UTF-8
update-locale en_US.UTF-8

1.6. Change Password

Open Terminal from GUI and on the terminal command line:

cd ~/add-ons
./change-password.sh

1.7. International Keyboard

Keyboard layout controlled by pre-installed ibus application. To add a language:

ibus-setup

I also disable it from showing up in system tray, and I rely on switching languages using onboard keyboard Win-Space key combo.

1.8. SSD Boot

If you have an SSD drive, and you would like to boot from it (which would be a better way, and it would greatly improve the performance of the system) then you can follow the steps below:

The OS image comes with utility called 'rpi-clone' preinstalled. If you have a custom case for your raspberry pi (Ex. DeskPi Pro), then you would need to install vendor drivers for your case per vendor instructions.

Open Terminal from GUI and your command line for rpi-clone should look like (check usage https://github.com/billw2/rpi-clone as there might be nuances for your particular set up):

sudo rpi-clone sda

Follow the prompts.

1.9. Set up GPS

Plugin your GPS USB mouse and OS should recognize it. Check:

ls -l /dev/ttyLYS*

1.10. Set up AIS

Plugin your dAISy AIS receiver into USB and OS should recognize it. Check:

ls -l /dev/ttyLYS*

1.11. Update OpenCPN Plugins

  • Start OpenCPN

  • Go to Tools/Options/Plugins

  • Update Plugin Catalog

  • Browse plugins list and update plugins when an update available (one by one)

Due to a bug in OpenCPN https://github.com/bareboat-necessities/lysmarine_gen/issues/53 Updating plugins on a system booted with arm64 kernel doesn’t work even if userspace is armhf. As a workaround: boot with armhf kernel, update all plugins and only then switch to arm64 kernel

1.12. Set up Charts

OS image comes with several chartplotters:

  • OpenCPN

  • AvNav

  • Freeboard-SK

with extensive set of plugins as well as weather GRIB file viewers

  • XyGrib

1.12.1. OpenCPN

  • Start OpenCPN. Go into Tools/Options/Charts/Chart Downloader tab.

  • Click 'Add Catalog'. For USA: click USA NOAA & Inland Charts / ENC / By Region.

  • Pick your region, click (or touch) 'OK'

  • Click 'Update' (to update the catalog)

  • Click 'Download Charts…​' tab

  • Right-click (or long touch) in the charts list

  • Click 'Select all' from the pop-up menu

  • Press 'Download selected charts' button, and wait for it to finish

  • Press 'Apply' button

  • Click 'Chart Files' tab

  • Press 'Prepare all ENC Charts' button

  • Press 'OK' button when done

1.12.2. AvNav

When you are online NOAA raster MB tiles should work out of the box.

1.12.3. SignalK, FreeBoard-SK, TukTuk

Follow SignalK documentation to install offline charts for these.

1.13. SignalK

SignalK manages its own updates. Login into SignalK Marine Data Server web UI application and perform updates via its app store.

1.14. PyPilot

Starting PyPilot server:

sudo systemctl enable pypilot@pypilot
sudo systemctl start pypilot@pypilot

1.15. Weather

You can add weather budgie desktop applet. Unfortunately it is linked to a fixed location which is fine for a day-sailor but doesn’t work for others.

Off-shore sailors or even coastal cruisers should focus on using XyGrib and GRIB plugin for OpenCPN.

For real blue water sailors OpenCPN Climatology and OpenCPN weather routing plugins are essential.

1.16. Music Players

The OS image comes with Mopidy, MPD server, MusicBox, Shairport-Sync (AirPlay) server. The default audio output set up to audio jack port.

1.16.1. MusicBox

Start MusicBox web UI. Try pre-configured playlist, or you can search Tune-In or YouTube.

1.16.2. Playing from your iPhone (Spotify, etc)

Play music on iPhone. Select AirPlay on your iPhone and cast to 'lysmarine' airplay target.

1.16.3. Playing from mobile phones with MPD applications

Install MPD compatible media player on your mobile device and from it you can control playing your Mopidy library on your raspberry pi.

1.17. Interfacing with ship systems

The first place to start configuring boat interfaces would be SignalK. SignalK comes with many plugins to talk to many boat devices with the support of various protocols.

1.17.1. NMEA 0183

If you use FTDI USB serial to USB sticks the OS should recognize them right away, and if they are wired correctly to NMEA devices (ex: wind/depth/speed/GPS) their reading should automatically show up in instrument dashboards.

1.17.2. NMEA 2000

Check SignalK plugin settings and SignalK documentation.

1.17.3. IMU

Check PyPilot settings and PyPilot documentation.

General steps are

  • enable i2c (Interface options)

cd ~/add-ons
./os-settings.sh
  • Enable pypilot service

sudo systemctl enable pypilot@pypilot
sudo systemctl start pypilot@pypilot
  • At this point you should be able to see reading of pitch/roll, etc, and magnetic heading in pypilot control. Which you would need to calibrate.

  • Start pypilot calibration. Press 'Boat Level' when the boat leveled. (Your IMU must be obviously mounted hard to the boat, can’t be just hanging). For magnetic heading: IMU doesn’t know how you oriented it inside (where bow is pointing), so you need to adjust it by filling magnetic heading adjustment field.

  • Establish connection from PyPilot to SignalK. To achieve this due to a bug in pypilot zeroconf service auto-discovery you need to shutdown mopidy and avnav temporarily.

sudo systemctl stop mopidy
sudo systemctl stop avnav
sudo systemctl restart pypilot@pypilot
  • Go to SignalK web UI as admin and approve the access request from PyPilot for READ/WRITE access.

  • IMU data should start flowing into SignalK

1.17.4. Barometer / Temperature / Humidity

Check SignalK plugin settings and SignalK documentation.

General steps are:

  • enable i2c (Interface options)

cd ~/add-ons
./os-settings.sh
  • To check if it’s working:

lsmod | grep i2c-dev
i2cdetect 1
  • Login into SignalK Marine Data Server

  • Enable BMP or BME sensor plugin. Give it correct i2c address. Restart SignalK server.

  • At this point you should be able to see barometric pressure and temperature (possibly humidity) in your data feed.

1.17.5. Other

Many other devices are supported (usually via SignalK)

1.18. Marine Radio

OS image comes with many HAM radio applications, decoders for many marine specific signals and protocols. Many SDR products should work. Decoding is also possible using external HAM receivers connected via sound input port (USB sound card required as respberry pi doesn’t have built-in sound input). Proper antennas required for correct reception.

1.19. Cameras

1.19.1. IP Cameras

Should be easy to integrate using pre-installed VLC. See URL in /var/www/bbn-launcher/bbn-launcher.js

1.19.2. MotionEye

By default, motioneye service installed and enabled. To disable:

sudo systemctl disable motioneye
sudo systemctl stop motioneye
sudo systemctl status motioneye

Default user: admin

Password is empty.

1.20. Cruising within Cellular Phone Reception

Adding some OpenWrt LTE/4G router greatly improves your boat connectivity to the world near shore. You should definitely do it to have internet access from your boat.

The OS image gives you internet applications for:

  • Email

  • Chat

  • Facebook

  • YouTube

  • Browser

  • On-Line Weather

  • On-Line Charts

  • Marina Booking

  • Sailing Education

  • SMS

  • and much more

1.21. Offshore Features

For offshore sailors there are number of features pre-loaded into the OS image

  • NavTex

  • Inmarsat Fleet (receiving messages)

  • Using Iridium as modem

  • WeatherFax

  • GRIB (could be over SSB)

  • AirMail / WinLink

  • SDR / HAM Radio Apps

  • AIS

  • Weather Routing / Climatology

  • Celestial Navigation

  • Autopilot (PyPilot)

  • Satellite Weather

  • Radars (several supported)

  • Location Reporting

They do require additional hardware, set up and dedication.

1.22. Watching Movies

Watching on-line (or listening) prepaid copyrighted content (NetFlix, Amazone PrimeVideo, Google, Spotify, etc) in a web browser as Chromium requires closed-source DRM libraries. On arm32 version of the OS you can install it from add-ons folder ~/add-ons/ by running:

./widevine-lib-install.sh
As of moment of writing this procedure doesn’t work on arm64. It does work om arm32, and even on arm32 with 64-bit kernel.

1.23. How it is Made

For those who are comfortable writing software the scripts to create this image stored on the image itself (for the reference) in /install_scripts. The full source code to create the image is available at https://github.com/bareboat-necessities/lysmarine_gen

1.24. Shutting Down / Rebooting

On the desktop click arrow to get to the second set of desktop icons. Click on the 'Commands' icon. You will see a menu from where you can perform restart/shutdown, and more.

1.24.1. Safe Power-Down

Raspberry pi doesn’t have a safe power-off feature. I.e. it doesn’t perform OS shutdown before powering off with a button. There are numerous third-party solutions with raspberry pi hats or custom cases. Make sure you do not forget to install required software for them per vendor documentation.

1.25. Customizing Desktop

Desktop can be customized by editing the JavaScript file in /var/www/bbn-launcher.

1.26. Customizing On First Boot

You can add additional customizations which will be performed on system first boot by mounting OS image and editing /boot/first-boot.sh script. That script as its name suggests executes only once on the first boot.

1.27. Known Issues and Workarounds

1.27.1. Touchscreen

  • Some applications (namely OpenCPN and gtk2 based as well as some Qt) sometimes stop responding to touch events. There is a workaround. With your finger you can toggle maximized mode via window frame icon then you MOVE the window frame by dragging window header few pixels, and switch back to maximized mode if needed. This should restore touch events in that app.

  • Some gtk3 applications menus (ex: terminal) have issues handling touch events. You can select a menu item with touch but to perform a click on it you would actually need to perform similated right click by holding finger a bit longer and letting it go.

1.28. Suggestions

The beauty of Linux is that you can customize it for your needs in infinite ways. While this distro aimed to strike common need, you will find that number of post-install customization steps would be required. The key is to script those steps, make them non-interactive, make the steps requite NO GIU. In that case your set up becomes RE-PRODUCIBLE in case of new OS image releases. You can share your post-install scripts, so the system can be improved and even more fine-tuned.

1.29. HOWTOs

Please send us your HowTo, and we can add it here for everyone to find. Thanks