Skip to content

Software Setup

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 32GB+ micro SD card.

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 Systems

To get started with the software setup on a Raspbery Pi, you need to write an OS to a micro SD card.

Pipettin OS

Pipettin OS is a full system image of a configured OS for the Raspberry Pi, based on either Raspberri Pi OS or Ubuntu for Raspberry Pi.

To install Pipettin OS follow the OS flashing guide.

Tip

This is the recommended way of installing pipettin's software.

If you use Pipettin OS, you may then move on to the Electronics Setup Guide, and skip the rest of this one.

Raspberry Pi OS

Follow this guide to start loading Raspberry Pi OS to an SD card.

Then continue with the software setup below.

Connect to the RPi

To install the software components, you need access a terminal on the Pi. This also involves finding it's IP address on the local network, which is also required to use the robot.

There are two access methods:

  • For network connections, you can follow the headless setup instructions.
    • This option is recommended to operate the robot through the network (i.e. from a different computer).
    • Its great if you do not have a spare display and keyboard.
  • Connect a keyboard and monitor to the Pi, as described in the desktop Pi setup guide.
    • This is great if you don't feel comfortable with networking.
    • If your Pi is powerful enough to handle everything, you won't need a second computer to use the robot.

Software setup on a Raspberry Pi

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

Instructions for regular PCs running other operating systems in the Software setup on a PC section below.

Note

This guide is meant somewhat experienced Linux users.

Requirements

  • Internet connection.
  • Raspberry Pi:
    • Model B, version 3 or greater (must be 64-bit).
    • At least 2GB of RAM for the full experience.
    • Micro SD card with 32GB capacity or greater.
  • Access to the Pi's terminal, through the local netorko or via keyboard/monitor.

Note

A Raspberry Pi with only 1GB will run all 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 room.

Update system packages

Run these commands to update the Pi's software:

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

Optionally install command-line utilities to monitor resource usage:

sudo apt install -y nmon iotop

Install 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.

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

Finally, to start KIAUH, use the command:

./kiauh/kiauh.sh

When KIAUH is running, you should see something like this:

kiauh.png

Use the following options to select our Klipper fork for installation:

  1. Choose option "6- [Settings]".
  2. Choose option "1- Set custom Klipper repository".
  3. Choose the option corresponding to "naikymen/klipper-for-cnc -> pipetting"

Now you'll use KIAUH's interface to install Klipper, Moonraker, and Mainsail.

Info

If any warning window appears, select OK.

  1. Go to the main menu, and select option "1- [Install]". Once on the general installation menu, use the available options to install Klipper, Moonraker, and Mainsail.

    1. Press 2 to select Klipper.
    2. Press 1 to select the recommended python version.
    3. Press 1 to select the number of Klipper instances (just one).

  2. Install Mainsail.

    1. Press b to go back to the main menu of KIAUH.
    2. Press 1 to Install.
    3. Press 3 to select Mainsail.
    4. Press y to accept installing Mainsail.

  3. Install Moonraker.

    1. Press b to go back to the main menu of KIAUH.
    2. Press 1 to install .
    3. Press 4 to select Moonraker.

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

Briefly, run the following:

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

Finally, add an entry to the 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
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:

The above instructions were adapted from th33xitus.

klipper_repos.txt.example

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

Install MongoDB

Install MongoDB version 4.4.15 in the Raspberry Pi. This requires a 64-bit Raspberry Pi (e.g. 3 or greater).

Instructions adapted from Adapted from the guide at mongodb.com.

  1. Install the MongoDB 4.4 GPG key.

Note: Warnings may appear around apt-key, but if an error occurs try this alternative instead: https://itsfoss.com/apt-key-deprecated/

wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add -
  1. Add the source location for the MongoDB packages.
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list
  1. Download details of the MongoDB packages.
sudo apt update
Troubleshooting: invalid signatures

The apt update command can fail with an error similar to the following:

The following signatures were invalid: EXPKEYSIG 656408E390CFB1F5 MongoDB 4.4 Release Signing Key <packaging@mongodb.com>

This is due expired GPG keys from Mongo. The issue can be solved by re-importing the key, as shown above.

  1. Install the correct version (4.4.15).
sudo apt install -y mongodb-org=4.4.15 mongodb-org-server=4.4.15 mongodb-org-shell=4.4.15 mongodb-org-mongos=4.4.15 mongodb-org-tools=4.4.15
Downgrading MongoDB

If you have installed a more recent version of Mongo, it may not work. To downgrade, add the --allow-downgrades flag to the command above.

A more recent version of MongoDB may be installed inadvertedly when running apt upgrade, to update system packages.

  1. Check the installed version.
mongod --version  # Should print 4.4.15
Troubleshooting: Illegal instruction

If you get an error saying Illegal instruction (core dumped), then your MongoDB version is incompatible with your OS.

Make sure that the version you installed is at most 4.4.15, and downgrade if needed (i.e. add --allow-downgrades to the command above and run it again).

  1. Start and enable the MongoDB service at boot.
sudo systemctl daemon-reload
sudo systemctl start mongod.service
sudo systemctl enable mongod.service
sudo systemctl status mongod.service
MongoDB configuration

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, though your mileage may vary), and tweak the network settings.

Install node and npm

  1. Install Node.
sudo apt install npm
Old node versions

This may result, for example, in the installation of node and nodejs version v18.19.0, and npm version 9.2.0.

These are quite old and won't work as intended. 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 LTS NodeJS with the n tool.
sudo npm install -g n  # Install the "n" tool globally.
sudo n lts  # Install and default to LTS node globally.
  1. You now need to log out, and then log in again. Then node --version and npm --version to check that the updated versions have been installed.
Updated node versions

After logging in again the version numbers printed by those commands should be higher. For example, node v20.11.1 with npm 10.2.4.

Install Pipettin

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.

You can download all modules using git:

# Change to the home directory.
cd

# Clone the main repo and enter its directory.
git clone https://gitlab.com/pipettin-bot/pipettin-bot.git pipettin-bot
cd pipettin-bot

# Clone all submodules.
python code/scripts/clone.py

# Download the repo and its submodules. Note that this leaves submodules in a detached state.
# git clone --recurse-submodules https://gitlab.com/pipettin-bot/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/pipettin-bot/pipettin-gui.git
# cd pipettin-gui
  1. Install the app's package dependencies using npm.
# This will take a while...
npm install
  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 use the nano text editor to make these changes.
Configration reference

Configuration options are explained in the repo's docs: https://gitlab.com/pipettin-bot/pipettin-gui/-/blob/develop/doc/Config.md?ref_type=heads

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

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

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

# Copy the defaults.
cp config_default.json config.json

# 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.

  1. 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.
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.

  1. Visit http://<<yourpisip>>:3000 on your web browser to open the app.
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.
    },
    // ...
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. Go back to the terminal, and press Ctrl+C to stop the server.

Piper controller

Run the commands below to install piper and its dependencies.

Python version 3.9 (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 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

Edit the config.yml file, and change any values you need to update (e.g. database name, socket address, etc.).

Important

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.

# You can edit the file with the "nano" editor (press Ctrl+X to exit the editor).
nano config.yml

Install all pipettin modules and dependencies in the virtual environment:

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

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=''
Stop it by pressing Ctrl+C when you're comfortable.

Quick and dirty

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/pipettin-bot/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/pipettin-bot/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, first enable systemd lingering. Run this at least once as the pi user:

sudo loginctl enable-linger pi

Then, in the commands shown elsewhere, omit using sudo, use sytemctl --user and journalctl --user-unit instead, 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.

Before installing the units, you need to setup a polkit rule to allow restarting the piper unit as a regular user (i.e. without sudo) from the UI.

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 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'

Updates

To update to the latest versions of the submodules, run the following commands.

Tip

If you installed "Pipetting OS" you can (and should) update most modules through Mainsail instead.

This will also properly install the updated modules to their respective virtual environments, which the git commands below don't do.

# Enter the repo's directory.
cd ~/pipettin-bot

# Optionally, configure git to auto-update submodules on every git pull.
git config submodule.recurse true

# Pull the latest commit of the main repo and submodules.
git pull

Note

These commands will have no effect if you just ran the commands above.

Warning

Any changes to the configuration files may cause version control conflicts, and prevent you from updating through git pull.

In this case, you can try backing up the files, then use git restore someconfig.yml to checkout the original versions, then git pull, and manually migrate the modified values from your backup.

To update the submodules beyond the commited versions of the submodules, run the following.

Warning

The latest versions may contain untested features, or be incompatible with your current setup. Excercise caution.

# Fetch latest submodules (optionally).
git submodule foreach --recursive git checkout -
git submodule foreach --recursive git pull

Finally, reload the systemd user units, as the may have changed, and restart everything:

# Reload the user's units.
sudo systemctl daemon-reload

# Restart components.
sudo systemctl restart nodegui.service
sudo systemctl restart piper.service
# ...or just reboot.

Configuration

While the defaults should work out of the box, it is worth clarifying which configuration values must match.

  • Server address: The URL and PORT of the Pipettin Writer 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 config.yml file.

Tip

You can set piper's config parameters by editing piper.yml using Mainsail's config editor. Remember to restart the controller after saving any changes.

Example

In this example the initial value of database_name in the config.yml file was commented out, and another one added below to replace it.

database:
    mongo_url: 'mongodb://localhost:27017/'
    #database_name: 'pipettin'
    database_name: '2024-03-19-test'

The database name must match the initial value in the .env file. Look for the examples shown above.

Additional Software

A few extra applications can be installed on the RPi, and be really useful.

Setup instructions can be found at the additional software setup guide.

For example:

Final checks

TO DO

  • MCU connection.
  • compatibility of node/mongo versions.
  • Starting the GUI.

Software setup on a PC

You can run Pipettin on the three major operating systems.

Info

There are no system images for this setup.

Choose your poison:

  • Linux: rather simpler instructions for Arch Linux and Ubuntu.
  • Windows: achievable but rather complicated, specially the Klipper parts.
  • Mac OS: should be possible, good luck!

Guides:

  • To learn how to install the project's software on a Desktop PC (which replaces the Raspberry Pi entirely) visit here.
  • The development guide might also be useful.

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.