Software Setup Guide on a Desktop PC

Software Setup Guide on a Desktop PC¶

Information about the Pipettin Bots software modules can be found on the Development page.

Note

These instructions might be slightly outdated. When in doubt, compare with the ones in the setup guide.

Linux (Ubuntu & Arch Linux)¶

Install Klipper¶

Repo: https://gitlab.com/pipettin-bot/forks/firmware/klipper-stack

You'll need git installed on your system:

# Arch Linux
sudo pacman -Syu git

# Ubuntu/Raspi OS
sudo apt update
sudo apt upgrade -y
sudo apt install -y git

Download components¶

Download stuff!

# Clone the meta-repo, without initializing the submodules.
git clone https://gitlab.com/pipettin-bot/forks/klipper-stack.git
# Then change to the repo's directory.
cd klipper-stack

Unless noted, all commands are meant to be run from the klipper-stack directory.

# Use a bash onliner to clone the default remote branch of the submodules as nested git repos.
# This is needed only because Moonraker does not recongnize submodules as valid repos. :shrug:
# Any deviation from the shape of the .gitmodules file above is on you.
git config --file .gitmodules --get-regexp "path|url" | awk '{ print $2 }' | paste - - | awk '{ system("git clone "$2" "$1) }'

If you do not plan on updating nor managing the processes through Mainsail, simply run:

# Download everything including submodules.
git clone --recurse-submodules -j8 https://gitlab.com/pipettin-bot/forks/klipper-stack.git
cd klipper-stack
# Auto-update submodules on every git pull.
git config submodule.recurse true

Then use the good old git pull command to update everything at any time.

Requirements¶

Klipper: the "scripts" directory in the Klipper repository has dependencies for many Linux distributions.

System dependencies¶

Arch Linux:

sudo pacman -S libffi base-devel ncurses libusb
sudo pacman -S avrdude avr-gcc avr-binutils avr-libc arm-none-eabi-newlib arm-none-eabi-gcc arm-none-eabi-binutils

Ubuntu Linux / Raspberry Pi OS for Klipper and Moonraker:

# System
sudo apt install -y python3 python3-venv
# Klipper
sudo apt install -y virtualenv python3-dev libffi-dev build-essential libncurses-dev libusb-dev
sudo apt install -y avrdude gcc-avr binutils-avr avr-libc stm32flash dfu-util libnewlib-arm-none-eabi gcc-arm-none-eabi binutils-arm-none-eabi libusb-1.0-0
# Moonraker
sudo apt install -y python3-virtualenv python3-dev python3-libgpiod liblmdb-dev libopenjp2-7 libsodium-dev zlib1g-dev libjpeg-dev packagekit wireless-tools curl

Tip

If you are running a slightly old version of Ubuntu or Raspberry Pi OS, you may need to choose a particular version of the avr-libc avrdude binutils-avr gcc-avr packages. See the troubleshooting section "Klipper not flashing the Arduino UNO" below for instructions.

Python dependencies and environments¶

Klippy:

python3 -m venv klippy-env && \
source klippy-env/bin/activate && \
pip install -r klipper/scripts/klippy-requirements.txt && \
deactivate

Moonraker:

python3 -m venv moonraker-env && \
source moonraker-env/bin/activate && \
pip install -r moonraker/scripts/moonraker-requirements.txt && \
deactivate

Mainsail development server¶

Official instructions at: https://docs.mainsail.xyz/overview/developement/environment

Skip/replace this part of the instructions if you'd rather use the docker setup or the "regular" nginx setup. Instructions for those two are at the "Mainsail" section (further down in this file).

Install dependencies:

# Arch Linux
sudo pacman -S npm node

# Debian/Ubuntu
sudo apt install npm node

Setup the development environment file:

cd mainsail
cp .env.development.local.example .env.development.local

Edit .env.development.local and update it if required. Options described here and in the file. For example:

# hostname or ip from the moonraker instance
VUE_APP_HOSTNAME=localhost

# port from the moonraker instance
VUE_APP_PORT=7125

# reconnect interval in ms
VUE_APP_RECONNECT_INTERVAL=5000

# where should mainsail read the instances from (moonraker, browser or json)
VUE_APP_INSTANCES_DB="moonraker"

# defaults for multi language tests
VUE_APP_I18N_LOCALE=en
VUE_APP_I18N_FALLBACK_LOCALE=en

Install node packages:

npm install

All you need to do to run the app from now on is to run from klipper-stack/mainsail:

npm run serve

Then visit http://localhost:8080 to open Mainsail.

Install MongoDB¶

Instructions to install MongoDB on Ubuntu: https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/

To install MongoDB on Arch Linux: https://wiki.archlinux.org/title/MongoDB

yay -S mongodb-bin mongodb-tools-bin
# yay -S mongodb-tools-bin  # Optional

sudo systemctl start mongodb.service
sudo systemctl status mongodb.service  # Check

Install Node and NPM¶

Install Node (e.g. an LTS version), and the npm package manager on Arch Linux, run:

sudo pacman -S nodejs-lts-gallium npm

Install the Pipettin GUI¶

Prerequisites¶

You will need to have Node.js, npm, and MongoDB already installed.

MongoDB installation guides for each major OS are available online:

Linux distributions:
Ubuntu: https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/
Arch: https://wiki.archlinux.org/title/MongoDB

Install nodemon (optionally globally by adding the -g flag):

# The global flag is not requried.
npm install -g nodemon

1. Clone the repo¶

To do

Link to learning resources for setting up git. Provide alternatives such as "zip" download. Link to setup and updates using Mainsail/Moonraker "update_manager".

Choose a directory where you want to download the app, and start a terminal in that directory. If you are new to Linux, you can search how to do this online. There are many guides, such as this one for Ubuntu Linux.

In the terminal run the following command to download the latest version of the app:

git clone https://gitlab.com/pipettin-bot/pipettin-gui.git

After that, use the cd command to enter the directory that was just created for the app's files, which should be named pipettin-gui. This folder will be referred to as "main folder" below.

cd pipettin-gui

2. Install node dependencies¶

In the main folder, start by running npm install. This will install Concurrently, which enables a smooth project startup. The command also installs all dependencies used in both the front and the backend.

npm install

3. Start the database¶

The GUI expects to connect to MongoDB on port 27017. The database and all the collections will be created when you run the server.

The installation instructions should have left MongoDB running on your system at that port. If you get database errors below or an empty dashboard on the app, revisit those instructions.

To do

Link to learning resources for installing and running MongoDB. Note version compatibility of the "wire" library: https://www.mongodb.com/docs/drivers/node/current/compatibility/

4. Seed the database¶

Open a terminal at the pipettin-gui directory.

If you want to populate the database with default data, you can do so by running the following command:

cd api
npm run seed

This command will add a basic workspace, a few platforms and a protocol to the database.

5. Start the app¶

Use cd .. to change back to the main app directory (i.e. pipettin-gui), or open a new terminal at the pipettin-gui directory.

Back on the main folder of the project, run the following command, which will start the latest development version of both the client (frontend) and the server (backend) simultaneously.

npm run dev

A pre-built version of the app can be started by running the following command:

npm start

Open the protocol designer app by visiting http://localhost:3000 on your browser.

Tip

Have fun messing with the code! You are welcome to share with us your thoughts and ideas. :)

Install the controller (piper) on Linux¶

Run the commands below to install piper and its dependencies.

You need python version 3.9 or greater. Check which version you are running with python --version, and update if needed.

Make sure you are using a virtual environment named .venv. 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 the environment:

# Create and activate the virtual environment on a suitable directory.
python -m venv .venv
source .venv/bin/activate

Piper¶

The main module can be installed form GitLab, and it will pull the inhouse modules as well.

# piper
pip install git+https://gitlab.com/pipettin-bot/pipettin-piper.git

Test that it starts correctly:

Stop it by pressing Ctrl+C.

# This will not connect to other programs. It only tests that piper loads correctly.
python3 -m piper dry verbose ws_address='' sio_address=''

To start piper with full functionality, run:

This requires that Moonraker and the UI are running.

python3 -m piper

Dependencies¶

Python module dependencies are installed automatically. The commands are left below for reference.

Inhouse modules:

# newt
pip install git+https://gitlab.com/pipettin-bot/pipettin-newt.git

# mix
pip install git+https://gitlab.com/pipettin-bot/pipettin-mix.git

# coorder
pip install git+https://gitlab.com/pipettin-bot/pipettin-coorder.git

Windows¶

Install Klipper¶

Instructions to install Klipper on Windows using WSL: https://3dpandme.com/2022/08/25/tutorial-running-klipper-on-a-windows-pc-using-wsl/

Install MongoDB¶

Instructions to install MongoDB on Windows: https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-windows/

Install the Pipettin GUI¶

Before installing Pipettin GUI, open a terminal.
Check the installed versions of the following tools:
Node: node --version.
GIT: git --version.
MongoDB: mongod --version.
If the command returns nothing, it means that the program is not installed. If the command returns a number, it means that the program is already installed.

Once you have verified that none of the programs are installed on your computer, you can proceed with the installation process.

Software requirements:

Node.js
Git
MongoDB

Optional:

Mongo Shell
Mongo Compass

As programs are installed, keep track of the paths where they were installed.

Info

Mongo Shell and Mongo Compass are optional but recommended to interact with the DB.

Installation:

Download and install Node.js, Git, and MongoDB.
Node + npm: https://nodejs.org/en/download (LTS)
GIT: https://gitforwindows.org/
Mongo Community: https://www.mongodb.com/try/download/community (it has to say package msi)
If you are installing Mongo Shell or Mongo Compass, download and install those programs as well.
Mongo Shell (opctonal): https://www.mongodb.com/try/download/shell (in the Platform option it has to say Windows MSI)
Mongo Compass (optional): https://www.mongodb.com/docs/compass/current/install/
Edit your environment variables to include the paths to the following folders:
Node.js: C:\Program Files\nodejs\
Git: C:\Program Files\Git\cmd
MongoDB: C:\Program Files\MongoDB\Server\6.0\bin
Mongo Shell (if installed): C:\Program Files\mongosh
Mongo Compass (if installed): C:\Program Files\MongoDB\Compass

Running Pipettin GUI:

Create a folder where you want to store the Pipettin GUI repository.
Open Git Bash in the folder you created.
Clone the Pipettin GUI repository:

git clone https://gitlab.com/pipettin-bot/pipettin-gui.git

Change into the Pipettin GUI directory:

cd pipettin-gui

Install the Pipettin GUI dependencies:

npm install

Install the Pipettin GUI development dependencies:

npm run install-deps

Seed the Pipettin GUI database:

cd api
    npm run seed
    cd..

Start the Pipettin GUI server:

npm start

Open Pipettin GUI in your web browser: http://localhost:3000

To reopen Pipettin GUI at a later time:

Open Git Bash in the Pipettin GUI directory.
Start the Pipettin GUI server:

# Pre-built version.
npm start

# Start the latest development version.
npm run dev

Open Pipettin GUI in your web browser: http://localhost:3000

Notes:

If you are using Mongo Compass, you can connect to the Pipettin GUI database by clicking the Connect button and entering the following information:
Host: localhost
Port: 27017
If you are using the terminal to start the Pipettin GUI server, you can use the following command to start in development mode:

npm run dev

Info

The development mode will enable hot reloading, so you can see changes to your code reflected in the Pipettin GUI UI without having to restart the server.

Install the controller (piper)¶

To do

Explanation on how to install piper on Windows is missing.

The main difference with the Linux instructions is in the shell commands for virtual environments and executing a python module.

Until we complete these instructions, you can probably manage by asking you favourite AI "how do i do this on windows?" and feed it the commands from the Linux section.