Software Setup

Warning

Under development! See issue: https://gitlab.com/pipettin-bot/pipettin-grbl/-/issues/52

This page is missing:

• Instructions to install piper on Windows.
• Run basic tests on the software and CNC firmware

Software & Firmware Setup Guide

Required skills and resources:

• Basic proficiency with computers and IP networks.

Depending on your background, this may be the most challenging part of the guide, specially because of the:

• Network setup: which depends on your LAN settings and operating system (which we do not control).
• Firmware install and configuration: we provide instructions for Arduino UNO micro-controllers, each with a CNC Shield (v3.0).

Hang in there!

Flash Pipettin OS to a Raspberry Pi

Tip

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

1. Follow the guide here.
2. Skip this section and continue from the Electronics Setup Guide.

Software setup on a Raspberry Pi

This guide is only recommended for advanced Linux users.

Instructions for PCs running other operating systems available below.

Overall steps

Raspberry Pi setup:

• Load the Pi ISO to an SD card.
• Setup network (Wired/WiFi).
• Set or find the Pi's IP address on your local network.
• Install all software components.

Microcontroller firmware:

• Flash Klipper on your CNC boards: https://www.klipper3d.org/Installation.html#building-and-flashing-the-micro-controller

Install Raspberry Pi OS

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

Connect to the RPi through SSH

First, learn the Pi's IP address. There are two alternatives:

• If you do not have a spare display and keyboard, you can follow the headless-setup instructions
• Else go with the simpler option: desktop Pi setup

After learning the Pi's IP, use a program that allows you to have SSH communication with the Pi (eg: Putty in Windows, or just ssh in Linux). For this you'll need the address from the previous step. Once an SSH connection is established, you can interact with the Pi through the local network from your PC (without the need to connect a display to the Pi).

# On Linux, open a terminal and run:
ssh pi@your.pi.s.ip.adress  # the default password is "raspberry".

# On Windows, use "Putty" owr the "WSL".

Once you are logged in, wait patiently until the last line you see is: To run a command as administrator (user "root"), use "sudo ". See "man sudo_root" for details”.

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

Note

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

Install Klipper

Here we will install only the "software" side of Klipper. The Firmware will be installed in another guide (the electronics setup guide) later on.

Info

Klipper is "a 3D-printer firmware", but it is actually several programs.

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.

Note

Instructions adapted from here.

Install KIAUH:

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

We’ll need our Klipper fork to be able to use an endstop for the extruder’s axis, and to synchronize the tool-changer stepper motor,

To set this up, use the following command to copy klipper_repos.txt.example to klipper_repos.txt:

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

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:

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.

How to avoid Klipper

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

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:

• piper: https://gitlab.com/pipettin-bot/pipettin-piper
• Controller: https://gitlab.com/pipettin-bot/pipettin-piper/-/blob/master/piper/controller.py
• KlipperCommander: https://gitlab.com/pipettin-bot/pipettin-piper/-/blob/master/piper/commanders/klipper_commander.py

Install MongoDB

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

Adapted from here

1. Install the MongoDB 4.4 GPG key.

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 the package details for the MongoDB packages.

sudo apt update

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

Tip

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

Tip

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

Note

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

Info

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.

Info

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.

Tip

Our repos are public, and submodules use HTTP/S connections. However, 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

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

Tip

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

# 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

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. Write down the IP address from 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.

Example

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.

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

1. Launch the GUI's development version.

npm run dev

Info

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.

1. Visit http://<<yourpisip>>:3000 on your web browser to open the app.

Info

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.
    },
    // ...

Tip

You might also try connecting through an mDNS/Zeroconf address, such as http://raspberrypi.local:3000 or http://pipettin.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 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.

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) and the GUI (pipettin writer).

First, enable systemd lingering, at least once as the pi user:

sudo loginctl enable-linger pi

Warning

You may need to edit the piper.service and nodegui.service files, to adjust the paths where the controller and nodegui are 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.

You can now install the units:

# Link service files.
mkdir -p ~/.config/systemd/user/
ln -s /home/pi/pipettin-bot/code/systemd.units/piper.service ~/.config/systemd/user/
ln -s /home/pi/pipettin-bot/code/systemd.units/nodegui.service ~/.config/systemd/user/

# Copy all.
# ln -s /home/pi/pipettin-bot/systemd.units/*.service ~/.config/systemd/user/

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

You should observe something similar to this:

Reload the user's units:

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

Start and enable the GUI's unit:

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

Start and enable the controllers's unit:

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

Tip

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

# Restart units and follow logs.
alias piper_restart='clear; systemctl --user restart piper.service; tail -f /tmp/moon.log -n1'
alias gui_restart='systemctl --user restart nodegui.service; journalctl --user-unit nodegui -f'
# Alternative
alias piper_restart2='clear; systemctl --user restart piper.service; journalctl --user-unit piper -f'

Updates

To update to the latest submodules run the following.

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.

# 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

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.
systemctl --user daemon-reload

# Restart components.
systemctl --user restart nodegui.service
systemctl --user restart piper.service

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. The defaults will match each other. This can be changed by updating the database_name option (example below) in the controller's config.yml file.

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.

Extras

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

For example:

• Locally serving this documentation.
• Controlling the machine through Jupyter Lab: https://jupyter.org/
• A web frontend for MongoDB, like this one.

Warning

Work in progress.

Setup instructions can be found over here.

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: sorry no idea, 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.

Congrats!

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

You may now:

• Continue to the object calibration guide: Electronics Setup Guide