Using Other Debian-based Distributions¶
Note
Hat Labs cannot provide support for installing and using 3rd party operating systems. The instructions below are provided as a courtesy to users who wish to use HALPI2 with a customized software setup.
HALPI2 will happily run any operating system that supports the Raspberry Pi Compute Module 5. To benefit from the full functionality of the HALPI2 hardware, including power management and monitoring features, the operating system must support the HALPI2 Daemon (halpid) and some configuration is required. These steps are fairly straightforward on Debian-based Linux distributions. This section provides step-by-step instructions for installing Ubuntu on HALPI2. The instructions may need some minor adjustments for other Debian-based distributions.
The Ubuntu distribution has an official Ubuntu image for the Raspberry Pi Compute Module 5, which may be used with HALPI2.
Prerequisites¶
Once your chosen Ubuntu (or other Debian-based) image is installed on the Pi, ensure that you have the latest software updates:
The following packages should then be installed as they are needed for the installation process:
Hat Labs Repository¶
The prebuilt packages for the HALPI2 are provided by Hat Labs, and are available through an apt repository.
To add this repository, you need to run the following commands with root privileges (from sudo bash):
sudo bash
curl -fsSL https://apt.hatlabs.fi/hat-labs-apt-key.asc | gpg --dearmor > /etc/apt/trusted.gpg.d/hatlabs.gpg
cat > /etc/apt/sources.list.d/hatlabs.sources << EOF
Types: deb
URIs: https://apt.hatlabs.fi/
Suites: stable
Components: main
Signed-By: /etc/apt/trusted.gpg.d/hatlabs.gpg
EOF
apt update
exit
HALPI2 Common Firmware¶
The firmware for common devices on the HALPI2 board can be configured by editing /boot/firmware/config.txt and adding the following lines to the [all] section:
Check your boot device before you paste this
The block below ends with dtparam=sd=off. On a Compute Module 5 that line disables the onboard microSD slot and, on a module with eMMC, the eMMC as well. Keep it if you boot from NVMe, which is the standard HALPI2 configuration. Remove it if you boot from microSD or eMMC, or the device will not boot after the next restart.
# --- HALPI2 / Raspberry Pi 5 IO setup ---
# Use antenna path #2 for Wi-Fi/BT
dtparam=ant2
# Enable SPI0 and relocate CS1 to GPIO6 (BCM6) for the CAN controller.
dtoverlay=spi0-2cs,cs1_pin=6
# Attach a Microchip MCP2517FD/2518FD CAN-FD controller to SPI0 Chip-Select 1.
# - spi0-1 : controller is on SPI0, CS1 (wired to GPIO6 by the overlay above)
# - interrupt=26 : MCP251xFD INT pin wired to GPIO26
# - oscillator=40000000 : external crystal is 40 MHz
# Produces a SocketCAN interface (e.g. can0).
dtoverlay=mcp251xfd,spi0-1,interrupt=26,oscillator=40000000
# Enable PL011 UART4. Creates /dev/ttyAMA4 for NMEA 0183 communication.
dtoverlay=uart4-pi5
# Enable the ARM I2C bus. The halpid daemon reaches the power management
# controller over /dev/i2c-1.
dtparam=i2c_arm=on
# Disable the SD interface. Without this, shutdown stalls long enough that the
# supercapacitors can run out before the controller powers the board down.
# This also disables the onboard microSD slot and the eMMC on a CM5 that has
# one, so omit the line if you boot from either.
# See: https://github.com/raspberrypi/linux/issues/7014
dtparam=sd=off
I2C must be enabled
Raspberry Pi OS ships dtparam=i2c_arm=on commented out, and other distributions may do the same. Without it there is no /dev/i2c-1, and halpid cannot reach the power management hardware.
The i2c-dev kernel module also has to be loaded at boot so that the user space halpid daemon can use the bus.
This is done by creating a file /etc/modules-load.d/i2c-dev.conf with:
Reboot to apply the changes, then confirm that the I2C bus is present:
If /dev/i2c-1 does not exist, revisit the config.txt edits before continuing. The halpid daemon cannot start without it.
CAN Bus (NMEA 2000) Setup¶
The following commands enable the CAN Bus for NMEA 2000 communication on the HALPI2:
sudo bash
apt install can-utils
cat > /etc/systemd/network/80-can.network << EOF
[Match]
Name=can*
[CAN]
BitRate=250000
RestartSec=100ms
EOF
chmod 644 /etc/systemd/network/80-can.network
echo 'SUBSYSTEM=="net", KERNEL=="can*", ACTION=="add|change", ATTR{tx_queue_len}="1000"' > /etc/udev/rules.d/80-can.rules
chmod 644 /etc/udev/rules.d/80-can.rules
systemctl enable systemd-networkd
reboot
Once the system has rebooted, you can check that the CAN interface is available with either of the commands:
HALPI2 Daemon¶
The HALPI2 Daemon is used to monitor and control the HALPI2 carrier board and provide the halpi command line tool.
Install the halpid package from the Hat Labs repository:
The HALPI2 Daemon should now be running and the halpi command available. You can check the status of the daemon with:
The daemon socket is only readable by the halpid group. The package adds your user to that group, but the membership applies to new login sessions only. If the command fails to connect, log out and back in, or use sudo halpi status.
HALPI2 Firmware Installation¶
Now that the halpi command is available, install the halpi2-firmware package, which ships the firmware images under /usr/share/halpi2-firmware/:
Flash the firmware yourself
The package tries to flash during installation, but that attempt fails silently on current releases (HALPI2-firmware #40). Apt still reports success, so flash manually and check the result.
Flash the firmware, then power the device off. A reboot does not apply the new firmware:
Power the device back on and confirm the version with halpi status. On a headless installation, make sure you can reach the power switch before you run the shutdown.
The software guide describes the automatic update mechanism and how to disable it.
Signal K Server Setup¶
The Signal K server is a popular choice for marine data management and can interface with both NMEA 2000 and NMEA 0183 data sources. The Signal K server can be installed using npm. The following commands will install the Signal K server and run the initial setup:
You can then access the Signal K server from a browser at the port that you configured.
Signal K NMEA 2000 Connection¶
To setup a NMEA 2000 Connection to the HALPI CAN interface you need to use a Signal K admin account and go to the Server > Data Connections section of the menu.
There you can click the +Add button and create a connector with the following properties:
Data Type: NMEA2000
Enabled: Yes
ID: "HALPI2N2K"
NMEA 2000 Source: Canbus (canboatjs)
Interface: can0
Restart and check the dashboard to see if data is being received.
Signal K NMEA 0183 Connection¶
To setup a NMEA 0183 Connection to the HALPI CAN interface you need to use a Signal K admin account and go to the Server > Data Connections section of the menu.
There you can click the +Add button and create a connector with at least the following properties:
Data Type: NMEA0183
Enabled: Yes
ID: "HALPI2N0183"
NMEA 0183 Source: Serial
Serial Port: /dev/ttyAMA4
Baud Rate: 4800 | 38400
Restart and check the dashboard to see if data is being received.