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:
- Install everything from scratch, starting from current Raspberry Pi OS.
- Flash a system snapshot with all software components pre-installed.
- Install everything from scratch on a Linux PC.
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:
- Insert the SD card with the OS to the slot on the side of the Pi.
- Connect a power supply to the Pi thorugh its USB-C port.
- 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:
- 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).
- 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:
Optionally install command-line utilities to monitor resource usage:
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:
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:
You should see something like this:
Use the options to select our Klipper fork for installation:
- Settings (
S). - Switch Klipper source repository (
1). - Add repository (
A). - Copy and paste the Klipper for CNC repo URL:
https://github.com/naikymen/klipper-for-cnc - Set the branch name to:
pipetting - Save repository (
Y). - 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:
- From the main menu, select option:
1) [Install] - Install Klipper.
- Press
1to select Klipper. - Press
Enterto select the number of Klipper instances (1, the default). - Press
Yto create an exampleprinter.cfg(the default). - If prompted to overwrite the repo, answer
y(yes). - If prompted to overwrite the virtual environment, answer
y(yes). - If prompted to add
pito the serial group, answerY(yes, default).
- Press
- Install Moonraker.
- Press
2to select Moonraker. - Press
Yto create an examplemoonraker.cfg(the default).
- Press
- Install Mainsail.
- Press
3to select Mainsail. - Press
Enterto download the recommended config (default). - Press
Enterto use the default port (80).
- Press
- Press
Bto return to the main menu.
The main KIAUH screen should look like this:
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:
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:
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:
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.
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.
- Install NPM.
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.
- Double check that the installed LTS version is active. You may need to log out, and then log in again.
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.
Writer UI¶
- 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
- 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
- Copy the default configuration to a new
config.jsonfile.
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
- Edit the
config.jsonfile, replacing the IP address inHOST(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.
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.
-
Write down the address set in the previous step. You will need it to configure the robot's controller later on.
-
If you have an external MongoDB instance, or have changed its default address above, you will need to edit the
.envfile 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.
- Launch the GUI's development version.
-
Visit
http://<<yourpisip>>:3000on your web browser to open the app. -
Back on the terminal, and press
Ctrl+Cto 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.
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:
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:
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:
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:
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:
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:
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.
Quick edit
Alternatively, these commands append the correct service names to the file.
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.envfile. This can be changed by updating the controller'spiper.yml(orconfig.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:
- A small OLED display to show the machine's overal status and current IP address.
- Controlling the machine through Jupyter Lab or Jupyter Hub (served at ports
8888and8000, respectively). - A web frontend for system management: Cockpit (server at port
9090) - Locally serving this documentation, and/or the BOM.
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 →


