Software Setup

Once your hardware setup done, you will have to:

Install Mariner 2
Setup the USB Gadget driver so that the printer can see uploaded files
Enable the serial port so the Raspberry Pi can send commands to the printer

This section will guide you through those steps.

Installing Mariner 2

There are several ways to install Mariner 2 depending on your platform.

Debian / Ubuntu / Raspberry Pi OS (apt)

Published .deb packages are built per Debian release codename (currently bookworm and trixie). The install script selects the matching suite from /etc/os-release (VERSION_CODENAME). Pure Ubuntu releases use their own codenames (for example noble); those are not published here unless they match a supported suite—use Docker, the RPM instructions below, or a Debian-bookworm/trixie-based image (many Raspberry Pi OS releases do).

The APT repository also publishes a stable suite that carries the same packages as bookworm, so older sources.list lines that still use stable keep working. Trixie machines should use the trixie suite (or re-run setup.sh) so they install the build that matches their Python stack.

Published .deb files use a Debian revision suffix such as +bookworm or +trixie so the same upstream version can coexist in the repository without pool file clashes.

First, enable the repository:

$ curl -fsSL https://amd989.github.io/mariner/setup.sh | sudo bash

Then install mariner:

$ sudo apt install mariner3d

On Debian-derived systems without a supported codename, the script exits with an error; use Docker or install from source until a build exists for your suite.

Or set up the repository manually (replace CODENAME with bookworm or trixie, matching your distro):

$ curl -fsSL https://amd989.github.io/mariner/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/mariner3d.gpg
$ CODENAME=$(. /etc/os-release && echo "$VERSION_CODENAME")
$ echo "deb [signed-by=/usr/share/keyrings/mariner3d.gpg] https://amd989.github.io/mariner ${CODENAME} main" | sudo tee /etc/apt/sources.list.d/mariner3d.list
$ sudo apt update
$ sudo apt install mariner3d

Rocky Linux / RHEL / Fedora (dnf)

Quick install:

$ curl -fsSL https://amd989.github.io/mariner/setup-rpm.sh | sudo bash
$ sudo dnf install mariner3d

Or set up the repository manually:

$ sudo rpm --import https://amd989.github.io/mariner/gpg.key
$ sudo tee /etc/yum.repos.d/mariner3d.repo <<EOF
[mariner3d]
name=Mariner 2 - MSLA 3D Printer Controller
baseurl=https://amd989.github.io/mariner/rpm/
enabled=1
gpgcheck=1
gpgkey=https://amd989.github.io/mariner/gpg.key
EOF
$ sudo dnf install mariner3d

Docker

Mariner 2 is available as a multi-architecture Docker image:

$ docker run -d \
    --name mariner \
    --device /dev/ttyUSB0 \
    -v /mnt/usb_share:/mnt/usb_share \
    -p 5000:5000 \
    amd989/mariner3d

The image is also available from GitHub Container Registry:

$ docker pull ghcr.io/amd989/mariner

Note

When using Docker, you still need to configure the USB Gadget and serial port on the host system as described below. Pass the serial device and USB share volume into the container.

Automated setup

The package ships a helper script that performs all of the boot-partition, USB gadget, and serial port steps described in the rest of this page. It works on Raspberry Pi OS and Armbian:

$ sudo mariner3d-setup-pi

The script is idempotent — safe to re-run — and backs up each file it edits to <file>.mariner.bak on the first run.

On Raspberry Pi OS it auto-detects your Pi model (using dr_mode=peripheral where needed) and the boot partition location (/boot vs /boot/firmware on Bookworm and newer).

On Armbian it configures /boot/armbianEnv.txt instead and adds an /etc/fstab entry for the USB container file.

Useful flags:

$ sudo mariner3d-setup-pi --size 4096   # 4 GB container instead of 2 GB
$ sudo mariner3d-setup-pi --dry-run     # show changes without applying
$ sudo mariner3d-setup-pi --help

Once it finishes, reboot and skip ahead to Wrapping up. The remaining sections on this page document the same steps manually, in case you prefer to run them yourself.

Note

The package includes a mariner-usb-gadget.service systemd unit that handles loading g_mass_storage at boot. If you previously followed the manual instructions and used /etc/rc.local, you can remove the modprobe g_mass_storage line from it — the unit handles that now.

USB Gadget Setup

In order to make the printer see the files uploaded to mariner, we need to setup the USB Gadget driver as a Mass Storage device. This section will guide you through that process.

Raspberry Pi OS

Enable the USB gadget driver by adding a line to /boot/config.txt (or /boot/firmware/config.txt on Bookworm and newer).

For a Pi Zero W or Pi 4B:

dtoverlay=dwc2

For a Pi 3A+, the port requires explicit peripheral mode since it does not support auto-sensing OTG:

dtoverlay=dwc2,dr_mode=peripheral

Enable the dwc2 kernel module by adding the following to /boot/cmdline.txt just after rootwait:

modules-load=dwc2

Armbian

Add the overlay and module load to /boot/armbianEnv.txt:

overlays=dwc2
extraargs=modules-load=dwc2

If an overlays= or extraargs= line already exists, append the value to it rather than adding a duplicate line.

Note

USB gadget support requires OTG-capable hardware. Not all Armbian boards support dwc2 gadget mode — check your board’s documentation.

Container file and mount point

Create the FAT32 container file that the printer will see as a USB drive. The count= value is in MB; use multiples of 1024 for whole gigabytes:

$ sudo dd bs=1M if=/dev/zero of=/piusb.bin count=2048
$ sudo mkdosfs /piusb.bin -F 32 -I

Create the mount point:

$ sudo mkdir -p /mnt/usb_share

Armbian only — add an /etc/fstab entry so the container is mounted at boot (replace <gid> with the numeric GID of the mariner group, which you can find with getent group mariner | cut -d: -f3):

/piusb.bin /mnt/usb_share vfat users,gid=<gid>,umask=002 0 2

On Raspberry Pi OS the mariner-usb-gadget.service unit handles the mount via losetup directly; no fstab entry is needed.

Enabling the systemd unit

The package includes a mariner-usb-gadget.service unit that runs at boot to set up the loop device, mount /piusb.bin, and load g_mass_storage. Enable it once:

$ sudo systemctl enable --now mariner-usb-gadget.service

After a reboot the printer should see the contents of /mnt/usb_share.

Setting up the serial port

First, enable UART by adding this to /boot/config.txt:

enable_uart=1

In order for the Pi to communicate with the printer’s mainboard over serial, you also need to disable the Pi’s console over the serial port:

$ sudo systemctl stop serial-getty@ttyS0
$ sudo systemctl disable serial-getty@ttyS0

Lastly, remove the console from cmdline.txt by removing this from it:

console=serial0,115200