Build a BoatKit device

A dedicated BoatKit device keeps the always-on vessel host separate from the phones, tablets, and computers used as displays. Early-access builds can use a Raspberry Pi 5, Raspberry Pi 4, or Raspberry Pi Zero 2 W.

This guide distinguishes three kinds of assurance:

• BoatKit compatibility means BoatKit and Linux can use the documented hardware interface.
• Manufacturer claims apply only to the specific product described by its manufacturer.
• Permanent-installation suitability depends on the complete electrical, mechanical, and environmental installation.

Contact your BoatKit early-access onboarding contact before buying parts. The managed device image is registered and prepared for a particular board and CAN hardware profile. If you do not already have a contact, join the BoatKit Discord community for live help from the developers.

Choose a base device

A Hardware Attached on Top board, usually called a HAT, connects to a Raspberry Pi through its 40-pin header.

Device	Best fit	Networking and expansion	Important requirements
Raspberry Pi 5	Preferred DIY choice for the most performance and expansion room	Onboard RJ45 Ethernet, Wi-Fi, four USB ports, and a 40-pin HAT header	The manufacturer recommends a quality 5 V/5 A USB-C supply such as its 27 W supply, plus active cooling under load
Raspberry Pi 4 Model B	Established general-purpose DIY choice	Onboard RJ45 Ethernet, Wi-Fi, four USB ports, and a 40-pin HAT header	The manufacturer recommends a 15 W USB-C supply; also plan storage, cooling, and an enclosure
Raspberry Pi Zero 2 W	Compact, headless choice	2.4 GHz Wi-Fi, one USB On-The-Go port, no onboard Ethernet, and an unpopulated 40-pin footprint	Has 512 MB RAM and normally needs a soldered header, micro-USB power, and an OTG adapter or hub when wired networking or USB CAN is required

The Pi Zero 2 W reserves its limited memory for BoatKit's core services, so its managed image omits the onboard browser container. Use a phone, tablet, or computer as the Viewer.

With the managed device image, a Pi 4 or Pi 5 can optionally drive an attached HDMI touchscreen using BoatKit's onboard browser. Many touchscreens use HDMI for video, USB for touch input, and a separate power connection. Include every display load in the power, USB-port, cooling, and enclosure plan.

BoatKit has not published minimum RAM or storage capacities or approved DIY storage models for these builds. Confirm the memory configuration and compatible storage with your onboarding contact.

Commercial option: HALPI2

The Hat Labs HALPI2 is a higher-cost, commercial, marine-centered computer based on the Raspberry Pi CM5. It integrates NMEA 2000, power handling, storage, networking, cooling, and an enclosure, making it more out-of-the-box than a DIY Raspberry Pi assembly.

It still requires a BoatKit image and matching hardware profile. Confirm its memory, storage, and display configuration through early-access onboarding before ordering.

Choose an NMEA 2000 interface

NMEA 2000 is a vessel data network based on classic Controller Area Network, or CAN, running at 250 kbit/s. CAN FD is not needed. BoatKit supports three hardware approaches on a Linux device:

Hardware approach	BoatKit connection type	Preparation	Validation status
Raspberry Pi CAN HAT	SocketCAN, Linux's native CAN interface	Requires the correct HAT startup profile	PiCAN2 Duo and Waveshare have named BoatKit profiles; PiCAN-M uses a custom early-access profile
CANable 2.0 over USB	SocketCAN	Flash candleLight firmware before installation	The exact linked CANable purchase has been physically tested with BoatKit on Linux
Actisense NGT-1-USB	Actisense NGT-1, a direct serial gateway	No CANable firmware flashing or board-specific CAN HAT profile	BoatKit software support is implemented, but no physical BoatKit compatibility test is recorded

The Actisense route avoids a board-specific HAT and CANable firmware preparation. It still consumes a USB port and must be mounted and connected according to the Actisense manual.

SK Pang PiCAN2 Duo

The PiCAN2 Duo with 3A SMPS provides two MCP2515 CAN channels. BoatKit uses the pican-duo profile for this HAT.

The current profile exposes the physical SPI channels in the reverse software order, so the HAT's channel numbering does not map intuitively to can0 and can1. Identify each physical connector using live traffic instead of assuming its software number.

The linked product includes a manufacturer-specified 7–24 V to 5 V/3 A power converter. Its presence does not establish that it can safely power the complete installation. In particular, do not assume a 3 A HAT supply satisfies the Raspberry Pi 5 manufacturer's 5 V/5 A recommendation. Follow the HAT manual and have the power source, fusing, grounding, connected load, and shutdown behavior reviewed.

SK Pang PiCAN-M

The PiCAN-M with Micro-C, RS422, and 3A SMPS provides one MCP2515 CAN channel through an NMEA 2000 Micro-C connector. BoatKit supports its CAN channel through SocketCAN. The HAT also provides an RS422 connection for NMEA 0183 equipment.

PiCAN-M currently needs a custom CAN hardware profile prepared during early-access onboarding rather than a named public profile.

The linked 3 A version can power a Raspberry Pi from NMEA 2000 network power. Do not use that path until an installer has reviewed the network power budget, fusing, grounding, safe shutdown behavior, and every attached USB or HDMI load. Do not assume it is sufficient for a Raspberry Pi 5 installation.

Waveshare RS485 CAN HAT

The Waveshare RS485 CAN HAT provides one MCP2515 CAN channel. BoatKit uses the waveshare-rs485-can profile. Its compact shape fits the Pi Zero 2 W and it can also be used with a full-size Pi.

Waveshare documents TVS protection and a switchable 120-ohm terminator. Those features do not establish galvanic isolation or NMEA 2000 certification. Have an installer determine how the HAT connects to the backbone and whether its terminator should be enabled.

CANable 2.0 over USB

BoatKit has physically tested this exact CANable 2.0 purchase on a Linux BoatKit device. With candleLight firmware, Linux exposes it as a SocketCAN adapter.

The Openlight Labs CANable 2.0 is the manufacturer's reference product, but that exact vendor unit was not the physical unit recorded in the BoatKit test. Treat the physical validation as specific to the linked tested purchase.

Openlight Labs also documents candleLight/SocketCAN support and galvanic isolation for the CANable Pro. BoatKit has not recorded a physical test of that exact model, so it is not yet a BoatKit-verified purchase option.

Actisense NGT-1-USB

The Actisense NGT-1 is a direct serial gateway rather than a SocketCAN or SLCAN adapter. Actisense describes the NGT-1-USB as its standard bidirectional USB option and the NGT-1 as an NMEA 2000-certified gateway. The manufacturer documents its NMEA 2000 connection, USB power, electrical isolation, mounting, network installation, and status LEDs in the NGT-1 user manual.

BoatKit automatically probes 115200 and 230400 baud. It receives and sends complete NMEA 2000 Parameter Group Number messages, or PGNs, through the gateway. No CANable firmware preparation is required.

The NGT-1 owns its NMEA 2000 source address. BoatKit uses the address claimed by the gateway and does not perform a second address claim. BoatKit enables transmit PGNs in the current gateway session as needed without writing the list to the NGT-1's EEPROM.

This is implemented BoatKit software support backed by the manufacturer's installation information. It is not a recorded BoatKit physical field validation of the NGT-1-USB.

USB CAN option to avoid

BoatKit has a legacy serial path for the Seeed USB-CAN Analyzer, but physical testing observed frequent malformed packets. Do not select it for a new BoatKit device.

Plan the permanent installation

A working BoatKit driver or hardware profile proves that BoatKit and Linux can use an interface. It does not prove that a bare development board, screw-terminal adapter, enclosure, or user-made harness is suitable for permanent vessel service.

Development boards require an installation review

Have a qualified marine electronics installer review galvanic isolation, NMEA 2000 backbone power and ground, fuse and circuit protection, connector pinout, termination, strain relief, heat, moisture, vibration, ignition protection where applicable, and safe shutdown and power-loss behavior.

Do not connect a development board to live vessel power or a live NMEA 2000 backbone until that plan is complete.

Official Raspberry Pi power supplies are useful for assembly and bench testing. A permanent installation needs a correctly sized, regulated, protected vessel DC supply and an appropriate shutdown plan.

No exact DIY enclosure, storage device, regulated vessel supply, fuse, terminal hardware, cooling assembly, or Micro-C harness is currently documented as a BoatKit-approved kit.

Purchase checklist by build

Confirm the board, HAT, profile, and storage with your onboarding contact before ordering.

Raspberry Pi 5 with a CAN HAT

• Raspberry Pi 5 in a memory configuration agreed through onboarding
• Reliable storage compatible with the managed image or user-managed Linux installation you selected
• A quality 27 W, 5 V/5 A USB-C supply from the Raspberry Pi power-supply range for bench setup
• For permanent service, an installer-selected regulated and protected vessel DC power system sized for the Pi, HAT, USB devices, and any display
• Active cooling and a HAT-compatible enclosure with adequate airflow
• A PiCAN2 Duo, PiCAN-M, or Waveshare RS485 CAN HAT
• For the managed-image path, the matching BoatKit CAN hardware profile; PiCAN-M currently requires a custom profile. For Podman, a host configuration that exposes the HAT as a Linux CAN interface
• Correct-height standoffs and mounting hardware that secure both boards without stressing the header
• The connector, drop cable, or installer-built harness needed to connect the selected HAT to NMEA 2000
• An Ethernet cable for the ordinary vessel LAN
• An additional USB Ethernet adapter only if a supported marine integration requires a separate wired network
• Optionally, an HDMI touchscreen plus its display cable, USB touch cable, separate power, cooling allowance, and mounting hardware

Do not rely on a HAT's 3 A converter as the Raspberry Pi 5 power plan unless the complete configuration has been reviewed and approved for that use.

Raspberry Pi 4 with a CAN HAT

• Raspberry Pi 4 Model B in a memory configuration agreed through onboarding
• Reliable storage compatible with the selected BoatKit software path
• A quality 15 W USB-C supply from the Raspberry Pi power-supply range for bench setup
• For permanent service, an installer-selected regulated and protected vessel DC power system sized for every connected load
• Cooling and a HAT-compatible enclosure with adequate airflow
• A PiCAN2 Duo, PiCAN-M, or Waveshare RS485 CAN HAT
• For the managed-image path, the matching BoatKit CAN hardware profile; PiCAN-M currently requires a custom profile. For Podman, a host configuration that exposes the HAT as a Linux CAN interface
• Correct-height standoffs and mounting hardware
• The connector, drop cable, or installer-built harness needed to connect the selected HAT to NMEA 2000
• An Ethernet cable for the ordinary vessel LAN
• An additional USB Ethernet adapter only if a supported marine integration requires a separate wired network
• Optionally, an HDMI touchscreen and all video, touch, power, cooling, and mounting hardware it requires

Raspberry Pi Zero 2 W with a compact HAT

• Raspberry Pi Zero 2 W
• A correctly soldered 40-pin header
• Reliable microSD storage compatible with the managed device image
• A quality micro-USB power supply for bench setup
• For permanent service, an installer-selected regulated and protected vessel DC power system sized for the complete assembly
• A Waveshare RS485 CAN HAT and the waveshare-rs485-can BoatKit profile
• A Zero-compatible enclosure, correct-height standoffs, and cooling or ventilation appropriate to the installation
• The connector or installer-built harness needed to connect the Waveshare HAT to NMEA 2000
• Wi-Fi access to the ordinary vessel LAN, or USB Ethernet with the required OTG adapter or powered hub
• A phone, tablet, or computer to use as the Viewer because this build is headless

Using a USB gateway instead

A CANable 2.0 or NGT-1-USB can replace the CAN HAT in a Pi 4 or Pi 5 build. Include the adapter, its USB cable, suitable strain relief and mounting, and the manufacturer-documented NMEA 2000 connector or an installer-approved harness.

A Zero 2 W has only one USB OTG port. A USB CAN adapter or NGT-1 may therefore require a suitable powered OTG hub, particularly when the build also needs USB Ethernet.

Plan networking

Use the ordinary vessel LAN for setup and normal Viewer access.

A Pi 4 or Pi 5 can use its onboard RJ45 Ethernet port. A Pi Zero 2 W normally uses Wi-Fi unless the build includes USB Ethernet. Add another USB Ethernet adapter only when a supported chartplotter integration needs a separate marine network.

Keep a chartplotter, radar, or sonar Ethernet network separate from the ordinary vessel LAN and internet path. Do not configure the BoatKit device as a bridge between a vendor marine network and the internet or vessel LAN. An isolated chartplotter network is not a substitute for the initial LAN or internet connection.

Prepare a CANable 2.0 for Linux

Use candleLight firmware for the Linux device path documented here. The current direct Android USB CAN path uses SLCAN firmware, while the iPad path uses a separate iCAN++ connection. Neither mobile transport applies to this Linux setup.

1. Move the CANable 2.0 boot switch to Boot.
2. Connect it to a Windows or Linux computer.
3. Open the CANable 2.0 web updater and review the alternative firmware guidance.
4. Select candleLight firmware, connect to the adapter, and run the update.
5. Follow the updater's driver or recovery guidance if the browser cannot detect the adapter.
6. Disconnect the adapter and move its boot switch out of Boot.
7. Attach it to the unpowered BoatKit device and secure the USB cable against strain.

After BoatKit starts, Linux should expose the adapter through SocketCAN. Do not flash SLCAN for this documented Linux device path.

Assemble the hardware

1. Confirm the board, storage, CAN interface, networking plan, power plan, and intended BoatKit software path.
2. Disconnect all power. If using a Pi Zero 2 W HAT, have the 40-pin header soldered and inspected before fitting the HAT.
3. Install the storage, heatsink, fan, or other cooling hardware required by the build.
4. Fit the CAN HAT on the 40-pin header using correctly sized standoffs. Do not allow the Pi or HAT to rest against conductive enclosure surfaces.
5. If using USB CAN, prepare the CANable with candleLight firmware before mounting it. An NGT-1-USB requires no CANable firmware preparation.
6. Mount the Pi, interface, and cables so USB, CAN, Ethernet, and display connectors do not carry cable strain.
7. If fitting a touchscreen, install its video, touch, and power connections according to the display manufacturer's instructions.
8. Leave backbone wiring, terminator selection, permanent vessel DC power, and permanent connector work to the reviewed installation plan.
9. Keep the assembly unpowered until its BoatKit software and storage are ready.

Choose how to install BoatKit

BoatKit has two early-access installation paths:

Path	Use it when	What it provides
Managed device image	The Pi will be a dedicated BoatKit appliance, onboarding supplies a HAT profile, or you need the attached BoatKit display on a Pi 4 or Pi 5	A complete, auto-updating BoatKit device image prepared for the selected board and CAN profile
Podman bundle	You intentionally want to install and maintain compatible 64-bit Linux yourself	The auto-updating, headless BoatKit vessel runtime installed on the existing host

For a dedicated Raspberry Pi, use the managed device image. Choose Podman when you intend to own the Linux host and accept BoatKit's privileged-container security boundary.

Managed device image

The managed image dedicates the Pi to BoatKit and includes the board-specific configuration and matching CAN HAT profile supplied during onboarding.

1. Obtain the registered image and flashing instructions from your BoatKit onboarding contact. There is no public managed-image download URL.
2. Confirm that the image matches the board and CAN hardware. PiCAN2 Duo and Waveshare require their named profiles; PiCAN-M requires a custom profile. CANable and NGT-1 builds do not need a HAT profile, but still require the correct board image and device registration.
3. Write the image to the storage target specified by your onboarding contact. Confirm the removable-media target before writing because flashing erases that target.
4. Insert the prepared storage.
5. Connect the Pi 4 or Pi 5 onboard Ethernet port to the ordinary vessel LAN when one is available, then apply bench power or approved vessel power.

For image or profile help, contact your onboarding representative or ask in the BoatKit Discord community.

Podman on user-managed Linux

The Podman bundle installs the headless BoatKit vessel runtime on an existing compatible 64-bit Linux host. Accepted users can obtain the ARM64 bundle from Download BoatKit in Account Web when a Podman release has been published.

The bundle does not install Linux, configure a CAN HAT's device-tree hardware overlay, or install an onboard kiosk browser. The host must meet the current system requirements, and you remain responsible for Linux administration and HAT startup configuration.

The container runs privileged with host networking and host device access so BoatKit can reach CAN, USB, and serial integrations. It leaves host networking unchanged unless the administrator explicitly enables BoatKit-managed Wi-Fi. Treat the host as a trusted vessel computer even though its operating system remains user-managed.

BoatKit uses HTTP port 80 by default on a Podman host. If the host already uses port 80, /etc/boatkit/boatkit.env can select another port; BoatKit advertises that port to current native and desktop apps through DNS-SD. Browser URLs must include a custom port explicitly.

Follow Install BoatKit with Podman for the current host requirements, installation, provisioning, update, and rollback procedure. Do not assume a particular Linux distribution or a Pi Zero 2 W Podman installation is validated unless that guide says so.

Complete first startup

Use the ordinary vessel LAN for first setup, not an isolated chartplotter or radar network.

For a managed device image:

1. For a Pi 4 or Pi 5, prefer onboard Ethernet when an ordinary vessel LAN port is available. A Pi Zero 2 W needs Wi-Fi unless the build includes USB Ethernet.
2. Open the BoatKit native or desktop app on a device connected to the ordinary vessel network.
3. If the BoatKit device is not already on that network, choose Setup New Device, or Setup Device when the vessel list is empty.
4. Choose Brand New BoatKit Device and follow the BoatKit Setup Wi-Fi flow.
5. When the app reports BoatKit found, open the device and continue through its account and BoatKit Cloud setup.

For Podman, configure the ordinary LAN through the host operating system before installing BoatKit. Keep the app on that LAN and use the discovered Set Up The New BoatKit Device entry. The Podman guide also documents an explicit opt-in that lets BoatKit manage a selected NetworkManager Wi-Fi adapter and provide the same setup network.

Configure and verify NMEA 2000

Wait until the BoatKit device itself is reachable before configuring its NMEA 2000 interface.

1. Open Settings > Integrations.
2. Under NMEA Networking, add NMEA 2000 Network if it is absent.
3. Choose the connection for your hardware:
   • For a CAN HAT or candleLight CANable, set Connection type to SocketCAN, then select the physical CAN adapter.
   • For an NGT-1-USB, set Connection type to Actisense NGT-1, then select the attached gateway under CAN adapter.
4. Enable the integration.
5. Confirm that its status advances from Disabled or Connecting and that a runtime interface appears. There is not one universal final status string for every adapter.
6. Confirm that received NMEA 2000 devices or traffic begin to populate.
7. Check that changing position, heading, depth, engine, tank, or sensor values are believable before changing preferred data sources.

With a PiCAN2 Duo, identify the physical connector from live traffic because the current software can0 and can1 order is reversed from the HAT's physical SPI channel order.

For an NGT-1, Address Claim is fixed to Gateway managed. A claimed gateway address must appear before BoatKit can transmit. BoatKit uses that address rather than claiming another one.

Transmit Alerts/Warnings is a separate operator choice. Enable it only when you deliberately want BoatKit alert and warning PGNs transmitted on that NMEA 2000 network.

Add an optional HDMI touchscreen

With the managed image, a Pi 4 or Pi 5 can use an attached HDMI touchscreen as its local BoatKit display. The onboard browser shows the same interface available to Viewers on the ordinary vessel LAN.

Follow the display manufacturer's power and cabling instructions. Include video, USB touch, display power, mounting, and heat in the installation plan. The Podman bundle does not install an onboard kiosk browser, and the Pi Zero 2 W managed image remains headless.

After mounting the screen, open Settings → Attached Display/Audio → Web Browser as an administrator and choose Display rotation. Select Rotate left (90°) or Rotate right (270°) for portrait mounting; Upside down (180°) is also available. BoatKit rotates the HDMI image and the matching USB touchscreen coordinates together. The change applies while the onboard browser is running and is saved for the next boot. Tap each corner after changing it to verify the touch hardware follows the picture. If touch is offset, use another Viewer on the vessel LAN to restore Normal, then check the display's own touch controller orientation and USB connection.

Connect optional chartplotter Ethernet

A Pi 4 or Pi 5 can use onboard RJ45 for one wired network. A Pi Zero 2 W needs USB Ethernet for any wired network. Add another USB Ethernet adapter only when a supported integration requires a separate vendor marine network.

Keep that marine network distinct from the ordinary vessel LAN and internet path, and do not bridge the two. Review Peripherals and integrations before assigning an interface to vendor equipment.

Confirm it is working

• The BoatKit app finds and opens the device over the ordinary vessel LAN.
• If fitted, the managed-image HDMI touchscreen displays BoatKit and accepts touch input.
• The enabled NMEA 2000 integration shows a runtime interface.
• Received NMEA 2000 devices or traffic populate and vessel values are believable.
• An NGT-1 shows a gateway-managed claimed address before any BoatKit transmission is expected.
• Already configured local Viewers can reach BoatKit directly while BoatKit Cloud or internet access is unavailable.
• When internet access is available, the device connects to BoatKit Cloud and can receive automatic updates.

Do not restart a running BoatKit as a routine verification step.

Updates and offline operation

Managed-image and Podman BoatKit devices update automatically and are intended for continuous service. Keep the device on an approved, stable power source and connected to the internet when you want it to receive updates.

A temporary internet outage does not stop the installed BoatKit version, local vessel data, local integrations, or direct access from already configured Viewers on the ordinary vessel LAN. Initial sign-in, expired credential renewal, remote access, remote notifications, BoatKit Cloud services, and update delivery require connectivity.

A DIY assembly must not be described as waterproof, ignition-protected, NMEA 2000-certified, or approved for production vessel service unless the complete enclosure and installation have evidence for those claims.

Troubleshooting

The app cannot find the device

• Confirm that the app and BoatKit device are on the same ordinary vessel LAN.
• On a Pi 4 or Pi 5, check the onboard Ethernet link indicators and LAN cable.
• On a Pi Zero 2 W, confirm the intended Wi-Fi connection or USB Ethernet hardware.
• If the device has not joined the LAN, return to Setup New Device or Setup Device, choose Brand New BoatKit Device, and repeat the BoatKit Setup flow.
• For an explicitly enabled Podman setup network, confirm that NetworkManager controls the adapter named by GOATKIT_WIFI_INTERFACE and that it supports access-point mode.
• Do not move the setup connection to the chartplotter network to make discovery work.
• Record the device name, board type, software path, image or profile choice, and displayed app message before contacting support.

The expected CAN adapter is not listed

• For a HAT on the managed image, confirm that the image contains the matching CAN hardware profile.
• For a HAT on Podman, confirm that the host's required device-tree hardware overlay was configured before BoatKit started.
• For a CANable, confirm that it is out of boot mode and running candleLight rather than SLCAN.
• For USB hardware, check that the adapter is attached directly or through a powered hub suitable for the load.
• For an NGT-1, check its USB connection and the status LEDs described in the Actisense manual.
• Record the available Connection type, CAN adapter, status, and runtime-interface fields before changing hardware.

The adapter appears but NMEA 2000 data is empty

• Confirm that the integration is enabled and no longer displays Disabled.
• Check that SocketCAN is selected for a HAT or candleLight CANable, or Actisense NGT-1 for an NGT-1-USB.
• Confirm that the intended physical CAN adapter is selected.
• With a PiCAN2 Duo, use live traffic to identify the connected physical channel rather than relying on channel numbering.
• Have the installer verify backbone power, connector pinout, wiring, and termination without changing a live network experimentally.

An NGT-1 receives data but BoatKit cannot transmit

• Look for a gateway-managed claimed address in the NMEA 2000 integration.
• If it shows Address not claimed, check the NGT-1 network installation, backbone power, USB connection, and manufacturer-documented status LEDs.
• Remember that Transmit Alerts/Warnings remains a separate operator choice; enabling the NMEA 2000 connection does not enable alert transmission automatically.

The device restarts or disappears under load

• Check the displayed hardware status and power source before changing software.
• During controlled bench diagnosis, remove optional USB or display loads only when doing so will not interrupt critical vessel equipment.
• Review supply capacity, cable voltage drop, cooling, storage health, and enclosure temperature with the installer.
• Do not repeatedly power-cycle the device. Preserve the observed status and timing for support.

Do not alter a live CAN or marine Ethernet network as a routine troubleshooting experiment. Understand the impact and preserve diagnostics first.

Return to Choose how to use BoatKit to compare this build with an app-hosted vessel.