Skip to content

Software

Note

Page under development. This page is missing:

  • Basic tests on the software, to check that everything is working at each stage.

Software Setup Guide

Required skills and resources:

  • A working local WiFi network, with internet access.
  • Basic proficiency with computers and IP networks.
  • Raspberry Pi and 16GB+ micro SD card, A1 class.

Depending on your background, the Network setup may be the most challenging part of the guide, which depends on your LAN settings and the operating system on your computer - which we do not control.

Hang in there!

Overall steps in this guide:

  • Load the Pi ISO to an SD card.
  • Configure a network connection.
  • Set or find the Pi's IP address on your local network.
  • Install all software components.

Operating System

There are a few options:

Raspberry Pi OS

Follow this guide to load a fresh Raspberry Pi OS Lite 64-bit image to an SD card.

Then continue to the Power Up section.

System Snapshot

Snapshots of a fully configured system for the Raspberry Pi. These are derived from the official Raspberry Pi OS Lite 64-bit image.

To install the OLA system image follow the OS flashing guide.

If you use this method, you may skip most of the guide below and contine with the next steps.

Alternative OS

You can run this software on most Linux dstributions. To use a Linux PC instead of a Raspberry Pi, read the PC setup page.

Other operating systems are unsupported but it should be possible:

  • Windows: achievable but rather complicated, specially the Klipper parts.
  • Mac OS: should be possible, good luck!

Power Up

After installing an operating system to a micro SD card, its time to power up the Pi for the first time.

Power supply selection

Raspberry Pis version 4 and 5 require a (USB-C) power supply, capable of delivering 2A-3A. Supplies with insufficient current ratings are very common, but the Pi may still work (although it may throttle). When mounted on the robot, the Pi will be powered through its GPIO header. If you have not yet assembled the electronics, you may use a regular USB-C power supply for the time being.

To power up the pi:

  1. Insert the SD card with the OS to the slot on the side of the Pi.
  2. Connect a power supply to the Pi thorugh its USB-C port.
  3. Wait for it to power on. The onboard LEDs of the Pi will flash in particular patterns to indicate its status.

If the LEDs flash in a normal pattern, the operating system is up, and its time to connect to the Pi.

Raspberry Pi LED status reference

Raspberry Pi 5: - Red LED (power): Shows power issues when ON (e.g. there's a problem if its always on). - Green LED (status): Shows SD card activity and blink codes.

Raspberry Pi 4: - Red LED (power): Shows power issues when OFF (e.g. there's a problem if it blinks). - Green LED (activity): Shows SD card activity and blink codes.

Connect to the RPi

To install the software components, you first need access to a terminal on the Pi.

Choose one of these access methods:

  1. SSH 🌐 for networked setups.
    • Follow the headless configuration instructions.
    • It works if you do not have (or want) a display and keyboard for the raspberry pi.
    • It involves network configuration on the pi, and finding its address on the local network (although the pipettin.local mDNS address might just work).
  2. Shell 🖥️ for standalone use.
    • Connect a keyboard and monitor to the Pi.
    • If your Pi is powerful enough to handle everything (including a desktop environment and web browser), you won't need a second computer to use the robot.

Software setup

This section holds instructions to install all software components to a Raspberry Pi, working from a Linux computer.

Instructions for regular Linux systems are outlined in the Software setup on a PC section.

Note

This guide is meant for somewhat experienced Linux users.

Requirements

  • Internet connection.
  • Raspberry Pi computer:
    • Model B, version 3 or greater (must be 64-bit).
    • At least 4GB of RAM for the full experience (or 2GB for basic use).
  • Micro SD card with 16GB capacity or greater with a suitable os installed.
  • Access to the Pi's terminal, through the local network or via keyboard/monitor.

Minimum RAM requirements

A Raspberry Pi with only 1GB or 2GB will run the minimum required software (from firmware to web ui).

However, it will struggle with serving JupyterLab at the same time, or perform any RAM/CPU intensive task.

Keep in mind that a high system load will probably make Klipper crash. It needs some breathing room.

System packages

Run these commands on the Pi's terminal to update its software:

sudo apt update
sudo apt upgrade  # This can take a while...
sudo apt install git git-lfs -y

Optionally install command-line utilities to monitor resource usage:

sudo apt install -y nmon iotop

Klipper

Here we will install only the "software" side of Klipper, that runs on a regular computer (e.g. a Raspberry Pi or Linux PC).

The firmware will be flashed to controller bards in the electronics setup guide later on.

The Klipper software stack

Klipper is "a 3D-printer firmware", but it is actually a stack of several programs; from actual microcontroller code to a web frontend.

These programs are:

  • Klipper: the actual firmware, which runs on micro-controllers only.
  • Klippy: the "host firmware", which runs on a PC, and is responsible for motion planning.
  • Moonraker: a websocket-based "API" for Klippy. It connects to Klippy and manages the PC's operating system.
  • Mainsail (or Fluidd, etc.): front-end user interfaces, used from a web browser.

In contrast, other controller boards implement everything in firmware. For example, the Duet2 board runs the RRF firmware, and also serves a web frontend thorugh WiFi, from the same board, without the need for an additional computer. We use Klipper because it runs on on cheap and expensive hardware alike.

First download the latest version of KIAUH:

cd ~ && git clone https://github.com/dw-0/kiauh.git

We’ll need to configure KIAUH to use our own Klipper fork, called klipper-for-cnc. This is needed to use home the extruder axes, used for pipetting, and the tool-changer motor.

Start KIAUH with the following command:

# Start KIAUH
~/kiauh/kiauh.sh

You should see something like this:

kiauh.png

Use the options to select our Klipper fork for installation:

  1. Settings (S).
  2. Switch Klipper source repository (1).
  3. Add repository (A).
  4. Copy and paste the Klipper for CNC repo URL: https://github.com/naikymen/klipper-for-cnc
  5. Set the branch name to: pipetting
  6. Save repository (Y).
  7. Select the new repostory (e.g. option 2).

Wait for the system dependencies to be updated, and for our klipper fork to be downloaded. Go back to the main menu (use option B twice).

Then use KIAUH to install Klipper, Moonraker, and Mainsail:

  1. From the main menu, select option: 1) [Install]
  2. Install Klipper.
    1. Press 1 to select Klipper.
    2. Press Enter to select the number of Klipper instances (1, the default).
    3. Press Y to create an example printer.cfg (the default).
    4. If prompted to overwrite the repo, answer y (yes).
    5. If prompted to overwrite the virtual environment, answer y (yes).
    6. If prompted to add pi to the serial group, answer Y (yes, default).
  3. Install Moonraker.
    1. Press 2 to select Moonraker.
    2. Press Y to create an example moonraker.cfg (the default).
  4. Install Mainsail.
    1. Press 3 to select Mainsail.
    2. Press Enter to download the recommended config (default).
    3. Press Enter to use the default port (80).
  5. Press B to return to the main menu.

The main KIAUH screen should look like this:

alt text

Press Q to quit.

Using another firmware

At the moment the controller (piper) only streams commands to Moonraker, and thus only works with Klipper.

It would require some coding effort to support, for example, the RepRap firmware (RRF) on the Duet, or Marlin firmware on other boards, with their native firmware.

Originally this project worked with GRBL, which was replaced because it could only drive 3 axes (and we needed at least 5), and code for it can be found in archived branches of OLA's git repos.

The changes mostly involve creating a new controller class in piper, mimicking KlipperCommander in all ways, and replacing KlipperCommander with it in the Controller class.

Here are the main files:

Deprecated klipper_repos.txt

This method no longer works.

Edit the kiauh/klipper_repos.txt file to append naikymen/klipper-for-cnc,pipetting after the last line. For this, you can use the echo command:

echo "naikymen/klipper-for-cnc,pipetting" >> kiauh/klipper_repos.txt

Previous versions of KIAUH included a klipper_repos.txt.example template file.

To use it, we required the following command to copy klipper_repos.txt.example to klipper_repos.txt:

cp kiauh/klipper_repos.txt.example kiauh/klipper_repos.txt

DynamicMacros

Finally, install the DynamicMacros plugin, as explained in its documentation.

Run the following to install:

cd ~
git clone https://github.com/3DCoded/DynamicMacros
cd DynamicMacros
sh install.sh
sudo systemctl restart klipper.service

Then add an entry for DynamicMacros to the ~/printer_data/config/moonraker.conf file with the following contents

# DynamicMacros Update Manager
[update_manager DynamicMacros]
type: git_repo
path: ~/DynamicMacros
origin: https://github.com/3DCoded/DynamicMacros.git
primary_branch: main
is_system_service: False
install_script: install.sh

Finally, restart moonraker to apply the changes:

sudo systemctl restart moonraker.service

MongoDB

Install MongoDB on a Raspberry Pi 4 or 5.

For the Raspberry Pi 3 see this page.

Details

MongoDB has not yet released an official repository dedicated to Debian 13 (Trixie). Using the Ubuntu repository is the standard workaround.

The Ubuntu 24.04 (Noble) APT repository provides the full suite of binaries and is natively compatible with Debian 13.

Installation instructions adapted from the guide at mongodb.com (archived version).

First switch to MongoDB from Ubuntu's Noble repository.

Use only MongoDB's or Ubuntu's APT repositories, never use the distribution's mongodb package.

sudo apt update
sudo apt install -y curl gnupg

curl -fsSL https://pgp.mongodb.com/server-8.0.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-8.0.gpg

# Add Noble ARM64, not the MongoDB Debian repository:
echo "deb [arch=arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg] \
https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse" \
| sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

sudo apt update

# Optional check
# sudo apt install --simulate mongodb-org

Now install mongodb-org:

sudo apt install mongodb-org
mongod --version  # Should print v8.0.29 (or greater)

# Enable
sudo systemctl enable --now mongod
systemctl status mongod  # Must show active, and no errors.

# Verify
mongosh --eval 'db.runCommand({ping:1})'  # Should return: { ok: 1 }

Without further configuration, MongoDB accepts connections from the same host only (e.g. localhost and 127.0.0.1 addreses), and uses port 27017 by default.

# /etc/mongod.conf
# Default allowed network interfaces
net:
  port: 27017
  bindIp: 127.0.0.1

If you need to change this, you can edit Mongo's configuration file. (e.g. at /etc/mongodb.conf or /etc/mongod.conf), and tweak the network settings.

To bind to all IPv4 addresses, set bindIp: 0.0.0.0.

NodeJS

Node and NPM are required to serve the web UI.

Compatible versions

The following versions have been tested to work: v22, v24 (24.19.0).

Installation may result, in old versions. The main incompatibility comes from the libraries needed to connect with mongo 4.15.

You can check the installed version by running node --version and npm --version.

  1. Install NPM.
sudo apt install -y npm
  1. Install LTS NodeJS with the n tool. You may also use nvm.
sudo npm install -g n  # Install the "n" tool globally.

sudo n lts  # Install and default to LTS node globally.

# Run this instead to install a tested version (see note above).
# sudo n 24.19.0  # Install and activate this node version globally.
  1. Double check that the installed LTS version is active. You may need to log out, and then log in again.
node --version
npm --version
Updated version check

After logging in again the version numbers printed by those commands should be higher.

OLA

The main repository tracks all the required repositories of pipettin as git "submodules", and uses git LFS for tracking CAD files, models, and other large files. You may need to install git lfs on your system to use them.

git with an SSH agent

Our repos are public, rely on igt-lfs, and submodules use HTTP/S connections. If you will be using encrypted SSH keys to push, we recommend setting up the ssh agent.

Download the main repository using git:

# Clone the main repo to your home directory.
git clone --single-branch -b master --depth 1 https://gitlab.com/open-la/pipettin-bot.git ~/pipettin-bot

# For the bleeding edge, use this instead:
# git clone --single-branch -b develop --depth 1 https://gitlab.com/open-la/pipettin-bot.git ~/pipettin-bot

To checkout the latest branches of all submodules, we include a helper script:

# Enter the repo and clone all submodules using a helper script.
cd ~/pipettin-bot
python code/scripts/clone.py
Alternative downloads

Alternatively, use git to download the repo and its submodules. Note that this leaves submodules in a detached state.

cd ~/pipettin-bot
git submodules update --init --recursive
#git clone --recurse-submodules https://gitlab.com/open-la/pipettin-bot.git

Writer UI

  1. Enter the GUI's GitLab repository (or clone it).
# Switch to the GUI's submodule in the main repo.
cd ~/pipettin-bot/code/pipettin-gui

# To clone it separately run:
# cd && git clone https://gitlab.com/open-la/pipettin-gui.git
# cd pipettin-gui
  1. Install the app's package dependencies using npm.
# Barebones install, required to serve the pre-built app only.
npm install

# Full development install. This will take a while...
# npm install_dev
  1. Copy the default configuration to a new config.json file.
# Copy the defaults.
cp config_default.json config.json
The config.json file

Configuration options in config.json are explained in the repo's docs: https://gitlab.com/open-la/pipettin-gui/-/blob/develop/doc/Config.md

  1. Edit the config.json file, replacing the IP address in HOST (e.g. 127.0.0.1) with the current local network IP of the Raspberr Pi (otherwise the website may not be accessible).
# You can edit the file with the "nano" editor.
# Press Ctrl+X to exit the editor, and "Y" + "Enter" to save changes.
nano config.json
Example config.json

The config.json file may show the following content initially:

{
    "PORT": 3333,
    "HOST": "127.0.0.1"
}

Adjust the HOST parameter. You can leave the PORT as it is, or change it to your favourite number.

The IP address

Use the following command to show the Pi's current IP addresses. At least one of the printed addresses will be useful to connect to the GUI from another machine.

ip -4 addr | grep -oP '(?<=inet\s)\d+(\.\d+){3}'
Using zeroconf

You might also try connecting through an mDNS/Zeroconf address, such as http://raspberrypi.local:3000 or http://olabot.local:3000 using your browser. It looks nicer and is simpler to remember, but it may not work on your particular LAN or PC without extra configuration (not covered here).

For this to work, the HOST address in the config.json file might need to be updated.

  1. Write down the address set in the previous step. You will need it to configure the robot's controller later on.

  2. If you have an external MongoDB instance, or have changed its default address above, you will need to edit the .env file as well.

# You can edit the file with the "nano" editor.
# Press Ctrl+X to exit the editor, and "Y" + "Enter" to save changes.
nano .env
Example .env

The .env file may show the following content initially:

DATABASE_NAME=pipettin
DATABASE_URI=127.0.0.1:27017

Adjust the DATABASE_URI parameter only if needed. You can leave the DATABASE_NAME as it is, or change it to your favourite DB name.

  1. Launch the GUI's development version.
npm start  # Pre-built version.
  1. Visit http://<<yourpisip>>:3000 on your web browser to open the app.

  2. Back on the terminal, and press Ctrl+C to stop the server.

Changing the UI's port

If you want to run the UI on a different port, edit the client/vite.config.js file. Replace the value in the port key to the value you want the UI to use. Port 80 will conflict with Mainsail's UI unless reconfigured, and requires elevated privileges to be used.

    // ...
    server: {
      host: true,
      port: 3000,  // <-- Change only this number.
    },
    // ...
Development version

A pre-built version is updated every stable release, and is faster. It can be launched by running npm start instead. This is what the systemd unit uses to launch the app. You can use npm run dev to start the development version.

Piper controller

Run the commands below to install piper and its dependencies.

Python version 3.11 (or greater) is required. Check which version you are running with python --version, and update if needed.

You may need to install the venv module first:

# Install "python venv" if not already (python3.11-venv on Debian Bookworm).
sudo apt install -y python3-venv

Create and activate an environment:

# Create and activate the virtual environment on the home directory.
cd
python -m venv venv-piper
source ~/venv-piper/bin/activate

Note

The systemd unit for piper will need piper to be installed in a virtual environment at ~/venv-piper.

Switch to the controllers's directory:

# Switch to the piper submodule in the main repo.
cd ~/pipettin-bot/code/piper

Copy the config.yml file to Klipper's config data as piper.yml, and change any values you need to update (e.g. database name, socket address, etc.).

This file must reside at ~/printer_data/config/piper.yml, this is where piper's systemd unit expects it to be.

cp config.yml ~/printer_data/config/piper.yml

# You can edit the file with the "nano" editor (press Ctrl+X to exit the editor).
nano ~/printer_data/config/piper.yml
Disable dry mode

By default, the configuration file will make the controller operate in "dry mode". this means that the robot will not be commanded to move, and is meant as a debugging feature.

Make sure that dry is set to False in the configuration file if you want the robot to move.

Path to piper.yml

By default, the systemd unit for piper will look for the file at ~/printer_data/config/piper.yml. It is critical that the file resides at this location when piper is started through its systemd unit.

If the piper.yml file must be placed elsewhere for some reason, piper's systemd unit must be updated accordingly and reloaded.

nano ~/pipettin-bot/code/systemd.units/piper.service
sudo systemctl daemon-reload
sudo systemctl restart piper.service
Edit piper.yml from Mainsail

Because the file is stored at ~/printer_data/config/piper.yml, you can use Mainsail editor's instead to set piper's config options.

Install all modules and dependencies in the virtual environment:

# Install the package in editable mode, and its dependencies. It will take a while.
pip install -e .

# Optional dependencies may be installed now (e.g OpenCV).
# pip install -e .[vision]

Test that it starts correctly:

# Note that this will not connect to Klipper/Moonraker or the UI.
# It only tests that piper loads correctly.
python3 -m piper dry verbose ws_address='' sio_address=''

If the UI is running and you set sio_address='localhost', you should see a notification and the controller's status displayed on the web UI.

Stop piper by pressing Ctrl+C, and deactivate its virtual environment:

# Deactivate the virtual envirionment.
deactivate
Installing from git

You can also install Piper into a virtual environment directly from the git repo.

The catch is that you'll need to download an modify the config.yml file separately. You will also need to edit and reload the controller's systemd unit file, such that it uses the python executable from the virtual environment (e.g. to ~/piper_from_pip/bin/python) and to the configuration file you downloaded.

cd
python3 -m venv venv-piper
source ~/venv-piper/bin/activate

wget https://gitlab.com/open-la/pipettin-piper/-/raw/master/piper/config/config.yml

nano config.yml  # Edit the config. Press Ctrl+X to close the editor.

pip install git+https://gitlab.com/open-la/pipettin-piper.git

# Test that it starts:
python3 -m piper config_file='config.yml' ws_address='' sio_address=''

Systemd units

"Systemd units" are small configuration files that tell the system to handle the startup of the GUI's Node.js server, of the Python driver module, and other services at boot. The unit files can be found in the main repository, for reference.

Most of the units should be already installed and enabled at boot (i.e. Mongo, Klipper, Moonraker and Mainsail). You now need to install and enable units for the controller (piper), the GUI (pipettin writer), and others.

User units

We will setup units as "system" units. If instead you want to manage them as user units, you may need to enable systemd lingering. Run this at least once as the pi user:

sudo loginctl enable-linger pi

Then, in the systemctl commands shown here, omit using sudo. Instead use sytemctl --user and journalctl --user-unit, and install units to ~/.config/systemd/user/.

Note

You may need to edit the piper.service and nodegui.service files, to adjust the paths that point to where the controller and nodegui were installed. The systemd files and commands below are meant to work with the setup as detailed in this guide. They can be easily adapted to other setups with minor edits.

To allow restarting the piper unit as a regular user (i.e. without sudo) from the web UI, first setup a polkit rule.

Create and open a new rule file for editing:

sudo mkdir -p /etc/polkit-1/rules.d
sudo nano /etc/polkit-1/rules.d/50-pi.rules

Add the following content, then save and exit:

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.systemd1.manage-units" &&
        action.lookup("unit") == "piper.service" &&
        subject.user == "pi") {
        return polkit.Result.YES;
    }
});

You can now install the units by adding symlinks to /etc/systemd/system/. This has the advantage that any updates to the repo will apply automatically after a reboot.

# Controller service files.
sudo ln -s /home/pi/pipettin-bot/code/systemd.units/piper.service /etc/systemd/system/
sudo ln -s /home/pi/pipettin-bot/code/systemd.units/piper_update.service /etc/systemd/system/

# UI service files.
sudo ln -s /home/pi/pipettin-bot/code/systemd.units/nodegui.service /etc/systemd/system/

# The "host updater" unit keeps the UI's "config.json" file updated with the current IP.
sudo ln -s /home/pi/pipettin-bot/code/systemd.units/host_updater/ip-monitor.service /etc/systemd/system/

Now reload the units, such that systemd finds the changes:

# Reload the units.
sudo systemctl daemon-reload

# Check that the units are detected and are not in a "bad" state.
sudo systemctl list-unit-files

You should observe something similar to this:

alt text

Start and enable the GUI's unit:

# Note that you need a proper npm installation for Writer to work.
sudo systemctl enable --now nodegui.service
sudo systemctl status nodegui.service

Start and enable the controllers's unit:

# Note that you need a proper virtual environment setup for Piper to work.
sudo systemctl enable --now piper_update.service
sudo systemctl enable --now piper.service
sudo systemctl status piper.service

Optionally start and enble the host updater unit:

sudo apt install python3-psutil # Required dependency.

sudo systemctl enable --now ip-monitor.service
sudo systemctl status ip-monitor.service

Tip

Handy bash aliases to restart the units can be added to ~/.bashrc by appending the following to it:

# Restart units and follow logs.
alias gui_restart='sudo systemctl restart nodegui.service; sudo journalctl nodegui -f'
alias piper_restart='sudo systemctl restart piper.service; sudo journalctl piper -f'
# To follow piper's logs.
alias piper_logs='tail -f /tmp/piper.log'

Service Manager

These systemd services can be managed by Moonraker, allowing it to start, stop or restart the UI server and Piper controller, in addition to Klipper.

This configuration is required for Moonraker to correctly update OLA's software components.

Additional software

There are optional software components that may require editing these files in the future.

If an [update_manager] section needs to set managed_services, you also need to allow this in with the moonraker.asvc file, as described above.

To enable this feature, open ~/printer_data/moonraker.asvc for editing, and add the services' names to the file.

nano ~/printer_data/config/moonraker.conf
Quick edit

Alternatively, these commands append the correct service names to the file.

echo nodegui >> ~/printer_data/moonraker.asvc
echo piper >> ~/printer_data/moonraker.asvc
echo piper_update >> ~/printer_data/moonraker.asvc

Then, add the following configuration entries to the end of the file, and then restart Moonraker (from Mainsail's top-right menu) to apply the changes.

[update_manager piper_update]
type: git_repo
channel: dev
path: ~/pipettin-bot/code/piper
origin: https://gitlab.com/open-la/pipettin-piper.git
primary_branch: master
managed_services: piper_update
virtualenv: ~/venv-piper
requirements: requirements.txt
info_tags:
    desc=Piper Controller

[update_manager nodegui]
type: git_repo
channel: dev
path: ~/pipettin-bot/code/pipettin-gui
origin: https://gitlab.com/open-la/pipettin-gui.git
primary_branch: develop
enable_node_updates: True
managed_services: nodegui
info_tags:
    desc=Protocol Writer

If everything is correct, you should be able to download and install updates through Mainsail's updates widget.

Configuration checks

While the default configuration should work, it is worth clarifying which values must match each other.

  • UI Server address: The URL and PORT of the backend and frontend must match, as explained here. No action is needed on your part under normal circumstances.
  • The database IP address and PORT used by the UI must match the ones from your MongoDB instance. The defaults used in this guide already match each other.
  • Database name: The backend uses a default database named pipettin. The controller must use this database as well, and will do so automatically if configured to read from the UI's .env file. This can be changed by updating the controller's piper.yml (or config.yml) file.

Tip

Configure piper by editing piper.yml using Mainsail's config editor. Remember to restart the controller after saving your changes.

Software updates

To update software components read the maintenance guide.

Additional Software

Additional features can be installed:

Instructions can be found at the additional software page.

Final checks

TO DO

  • MCU connection.
  • Compatibility of mongo versions.
  • Starting the GUI.

Next steps

Congrats! You've setup the software for your robot. That was tough!

You may continue with the Electronics Setup Guide, to install and configure the CNC firmware.


Navigation:
Previous: ← Assembly Guide | Next: Electronics Setup →