Note: Under development!
¶ List of To-Do's
See issue: https://gitlab.com/pipettin-bot/pipettin-grbl/-/issues/52.
Will cover:
- Set up the Rapsberry Pi ✅
- Linux ✅
- Windows ✅
- Software setup on a PC ✅ instructions to install piper are missing
- Setup the Arduino with CNC firmware ✅
- Configure the CNC firmware (Klipper config files) assigned to electronics team
- Run basic tests on the software and CNC firmware
- End-stop adjustments assigned to electronics team
- Vref adjustment ✅
- Required skills and resources ✅
- Links to knowledgebase
Required skills and resources:
Depending on your setup, this may be the most frustrating 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 flashing and configuration: we provide instructions for Arduino UNO microcontrollers, each with a CNC Shield (v3.0).
Hang in there!
¶ Flash Pipettin OS to a Raspberry Pi
This is the recommended way of installing pipettin's software.
- Follow the guide at: https://docs.openlabautomata.xyz/en/Mini-Docs/Software/System-Images#raspberry-pi-os-flashing
- Skip this section and continue from the electronics setup section below: https://docs.openlabautomata.xyz/en/Software&Electronics-Setup#electronics-setup
¶ Software setup on a Raspberry Pi
Instructions for PCs running other operating systems available below.
Overall steps:
Raspberry Pi:
- 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.
Flash 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 adress 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”.
¶ Install Klipper
Adapted from here
Run these commands to update the Pi's software:
sudo apt update
sudo apt upgrade # This can take a while...
sudo apt-get install git -y
Now 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 toolchanger 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:
- Choose option "6- [Settings]".
- Choose option "1- Set custom Klipper repository".
- Choose the option corresponding to "naikymen/klipper-for-cnc -> pipetting"
Now you'll use KIAUH's interface to install Klipper, Moonraker, and Mainsail.
If any warning window appears, select OK.
-
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.
- Press 2 to select Klipper.
- Press 1 to select the recommended python version.
- Press 1 to select the numer of Klipper instances.
-
Install Mainsail
- Press
bto go back to the main menu of KIAUH. - Press 1 to Install.
- Press 3 to select Mainsail.
- Press
yto acept installing Mainsail.
- Press
-
Install Moonraker
- Press
bto go back to the main menu of KIAUH. - Press 1 to install .
- Press 4 to select Moonraker.
- Press
¶ Install MongoDB
Install MongoDB version 4.4.15, this requires a 64-bit Raspberry Pi (version 3 or greater).
Retrived from here
- Install the MongoDB 4.4 GPG key.
wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add -
- 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
- Download the package details for the MongoDB packages:
sudo apt-get update
- Install the correct version (4.4.15)
sudo apt-get 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
- Check the version
mongod --version # Should print 4.4.15
- 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
¶ Install the Pipettin software Stack
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.
If you are using SSH to pull or push changes with an encrypted SSH private key, the use the ssh agent may make things simpler for you. To set it up only temporarily for a new terminal, run the following.
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa # Adjust to match your key's path.
You can download all files using git and git lfs, with the following commands.
# To download only the model files, uncomment the line below to run a bare git clone, and skip the next.
# git clone https://gitlab.com/pipettin-bot/pipettin-bot.git
# 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
# Enter the repo's directory.
cd pipettin-bot
# Activate git LFS, and download the CAD files.
git lfs install
git lfs pull
To update to the latest and greatest version of everything:
# Optionally, configure git to auto-update submodules on every git pull.
# git config submodule.recurse true
# Pull the latest commit of the main repo.
git pull
git lfs pull
# Fetch latest submodules (optionally).
git submodule foreach --recursive git checkout -
git submodule foreach --recursive git pull
¶ Further setup
- Copy Klipper configuration files and adjust them (using Mainsail).
- Copy and enable systemd units for Piper and the UI.
¶ Install the Pipettin GUI
- Install Node.
sudo apt install npm nodejs
- Install LTS NodeJS with
n.
sudo npm install -g n
sudo n lts
- 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
- Edit the
.envfile, replacing 127.0.0.1 to match the current IP of the Pi (otherwise the website may not work well).
# Print the RPi's IP addresses by using the "ip" command.
# At least one of these 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 "nano".
nano .env
- Install the app's dependencies and launch the GUI.
npm install
npm run install-deps
npm run dev
Visit http://<<yourpisip>>:3000 on your web browser to open the app.
¶ Install the Controller (piper)
Enter the controllers's GitLab repository (or clone it).
# Switch to the GUI's submodule in the main repo.
cd ~/pipettin-bot/code/piper
# To clone it separately run:
# cd && git clone https://gitlab.com/pipettin-bot/pipettin-piper.git
# cd piper
Create a virtual environment named .venv and activate it:
python3 -m venv .venv
source .venv/bin/activate
Install all pipettin modules in the virtual environment:
# Third-party dependencies
pip install -r requirements-unversioned.txt
# 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
Test that it starts correctly:
# This will not connect to other programs. It only tests that piper loads correctly.
python3 -m piper.coroutines_moon dry verbose ws_address=''
Stop it by pressing Ctrl+C.
¶ Systemd units
"Systemd units" handle the startup of the GUI's Node.js server, and of the Python driver module, and other services.
Most of the units shouold be already installed and enabled at boot (i.e. Mongo, Klipper, Moonraker and Mainsail). You now need to install units for the controller (piper) and the GUI (pipettin writer).
You may need to edit piper.service and nodegui.service, to adjust the paths where the controller and nodegui are installed.
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/
# 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
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
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'
Old guide: https://docs.openlabautomata.xyz/en/Mini-Docs/Software/systemd-units
¶ Software setup on a PC
Choose your poison:
- Linux: rather simpler instructions for Arch Linux and Ubuntu.
- Windows: achievable but rather complicated.
- Mac OS: sorry no idea, good luck!
To learn how to install the project's software on a Desktop PC (which replaces the Raspberry Pi entirely) visit here.
There are no system images for this setup.
¶ Electronics setup
¶ Setup the Arduino with CNC firmware
To install Klipper on a Raspberry Pi with an Arduino:
- Connect the Raspberry Pi to the Arduino using a USB-USB-B cable.
- On the Raspberry Pi, run the following commands:
cd ~/klipper/
make menuconfig
make
- In the menuconfig menu, select the microprocessor that corresponds to your Arduino. For most Arduinos, this will be atmega328P. Save and exit menuconfig.
Run the following commands:
make
ls /dev/serial/by-id
This will list the serial device IDs of all connected USB devices. Identify the device ID for your Arduino.
- Run the following command, replacing YOUR-ARDUINO-ID-REPORTED-BEFORE with the serial device ID of your Arduino:
make flash FLASH_DEVICE=/dev/serial/by-id/YOUR-ARDUINO-ID-REPORTED-BEFORE
- Start the Klipper service:
sudo service klipper start
Visit here to access to a guide on how to install Klipper on your Pipettin bot. However, most of the steps are the same for installing Klipper on any 3D printer with an Arduino and some of them may be incomplete.
¶ Vref adjustment
¶ Check connections
¶ List of To-Do's
- Logic: triple-check all electronic connections.
- Power: triple-check that nothing will catch fire, especially the PSU.
¶ Vref adjustment
The reference voltage (Vref) in a stepper driver is what limits current flow through your steppers.
The main trade-off here is the following:
-
Limiting the current is a good idea! Their coils will be damaged by the excess heat produced by excess current. Furthermore, the 3D-printed supports for the steppers may waken or deform under this heat.
-
However, a lower current limit will cause loss of steps during high-force moves (i.e. docking tools and placing/ejecting tips).
¶ How hot is too hot for a stepper motor?
A temperature around 60ºC is not terrible. If you can keep your fingers on it for at least one second, then it's not terrible.
However, since our steppers are secured to the structure using 3D-printed parts, an excess temperature will deform or even melt the plastic parts.
Ideally, you should be able to keep your hand on them for more than 5-10 seconds (circa 50ºC).
Technical details available here: https://3dprinting.stackexchange.com/a/8485
¶ Procedure
Notes on the subject here.
The all3DP and old E3D guides were very helpful:
- E3D's guide archive for the A4988 driver.
- E3D's guide archive for the DRV8825 driver.
- All3DP's Vref calculator.
Procedure:
- Find the maximum current rating of your stepper motors in their specifications.
- Calculate the reference voltage (
Vref) for your stepper drivers and motors (e.g. A4988, DRV8225, and others).- See the linked guides above for details.
- Connect the negative end of a multimeter to the controllers GND pin.
- Connect the positive end of the multimeter to a small Philips screwdriver.
- Locate the Vref adjustment potentiometer on the drivers.
- Connect the controller to the power supply and turn it on.
- Adjust the reference voltage using the screwdriver, while reading the voltage on the multimeter.
- Note: If the voltage reading is 0, you may need to connect the microcontroller (in this case an Arduino) to a USB power supply.
- The reference voltage limits the maximum current, protecting the motors from overheating. This comes at the cost of reduced torque, which may cause loss of steps in some situations (e.g. when changing tools, or placing tips).
- If steps are lost at the maximum Vref/current setting, use larger stepper motors.
- Also consider using a PSU with a voltage that is close to the driver's maximum voltage rating. This helps them produce sharper steps.
¶ Klipper setup for the Pipetting Bot
Work in progress!
GitLab Issues:
The objective is to use this setup:
¶ Configuration
Updated configurations are available here:
- More general alternatives: configuration
- Specific to this project: configuration
¶ CNC-shield pin map
Useful for configuring Klipper to use the CNC-shield V3 (clone): klipper_pin_config.svg
More detailed diagrams are available here: doc/electronica.
Because of budget restrictions, we opted to use the "cloned" CNC shield and Arduino UNOs. If it is within your choices, please support the original developers and the improvement of their products by purchasing "original" open source hardware:
- CNC shield: https://blog.protoneer.co.nz/arduino-cnc-shield/
- Arduino UNO: https://store.arduino.cc/products/arduino-uno-rev3
- Pololu A4988 stepper driver: https://www.pololu.com/product/1182
¶ GCODEs
Klipper GCODE command reference, which follows Marlin's GCODE closely: https://www.klipper3d.org/G-Codes.html
Commands can be sent through an "API", read on for details, its great. The "controller agnosticity" is also wonderful.
Some examples:
STATUS: Klippy status.
Send: STATUS
Recv: // Klipper state: Ready
QUERY_ENDSTOPS: Get endstop trigger status.
Send: QUERY_ENDSTOPS
Recv: manual_stepper p20:TRIGGERED manual_stepper p200:TRIGGERED x:TRIGGERED y:TRIGGERED y1:TRIGGERED z:TRIGGERED
GET_POSITION: Current position.
Send: GET_POSITION
Recv: // mcu: stepper_x:0 stepper_y:0 stepper_y1:0 stepper_z:0
Recv: // stepper: stepper_x:0.000000 stepper_y:0.000000 stepper_y1:0.000000 stepper_z:0.000000
Recv: // kinematic: X:0.000000 Y:0.000000 Z:0.000000
Recv: // toolhead: X:0.000000 Y:0.000000 Z:0.000000 E:0.000000
Recv: // gcode: X:0.000000 Y:0.000000 Z:0.000000 E:0.000000
Recv: // gcode base: X:0.000000 Y:0.000000 Z:0.000000 E:0.000000
Recv: // gcode homing: X:0.000000 Y:0.000000 Z:0.000000
Recv: ok
SET_STEPPER_ENABLE STEPPER=stepper_x ENABLE=1: Enable stepper x.SET_STEPPER_ENABLE STEPPER=stepper_x ENABLE=0: Disable stepper x.G28 X: home the X axis.
Commands for "manual stepper":
MANUAL_STEPPER STEPPER=p20 SET_POSITION=0MANUAL_STEPPER STEPPER=p20 ENABLE=1MANUAL_STEPPER STEPPER=p20 MOVE=20
There are, however, some caveats. Klipper is not a CNC project, it is meant for 3D-printers, and lacks some basic functionality. This is unfortunate, since its logic has overfitted to that particular use case, and the devs are "leery" towards extensions beyond FFD 3D-printing. Only the basic Marlin GCODEs are supported, and some modifications are necessary to add homing to the "extruder" axis (read on).
This is why the klipper-for-cnc fork exists.
¶ Klippy mods
Several modifications were made for compatibility, and are available at the GitLab fork: https://gitlab.com/pipettin-bot/forks/klipper
See: https://gitlab.com/pipettin-bot/pipettin-grbl/-/issues/47
¶ Extruder homing
Klipper can only home the XYZ axes (and un-synced "manual steppers").
We need synched and homeable extruders, in order to support "printing" on petri dishes with micropipettes.
Implemented at: klipper
¶ General probing
Klipper only probes in the Z-direction.
We need probing in all directions to support tip-probing, and tool-change probing.
Implemented at: klipper
¶ APIs
Klipper's API receives commands in JSON format: https://www.klipper3d.org/API_Server.html
There is also an HTTP API available, through the Moonraker program. It has been slightly modified to fit this project, and is published at: https://gitlab.com/pipettin-bot/forks/moonraker
¶ Piper module
A module to:
- Interact with Klipper (through the Moonraker HTTP API) and the Node GUI, using Python.
- Load protocol and workspace data from MongoDB.
- Convert GUI protocols to GCODE.
- Save them to Klipper's
printer_data/gcodedirectory (which can then be run via Mainsail). - Stream them to Klipper via Moonraker.
- Save them to Klipper's
Have a look at the README.md under the piper directory.
¶ Usage examples
Examples on how to use it are available at the notebooks directory, particularly at examples_piper.ipynb.
The available API commands are listed here: https://www.klipper3d.org/API_Server.html#available-endpoints
All GCODEs in the reference can be sent, using the "script" API command.
¶ Electronics tests
¶ List of to-do's
- Motors.
- Direction.- End-stops.
- GRBL: Use UGS / bCNC with a laptop, orminicomfrom SSH to check.
- Klipper: use mainsail.- Update CNC configuration if necessary.
¶ CNC tests
Note: This section is missing a proper tutorial.
- Send some commands to stuff, check that they turn in the expected directions.
- Home the axis.
- Check end-stops, parking sensors, and probe sensors.
- Test torque with a tool-change.
¶ End-stop positions
Note: This section is missing a proper tutorial.
If necessary:
- Adjust the position of the X and Y end-tops.
- Adjust the screw of the Z end-stop.
- Adjust the screw of the tool axis end-stops.
- Adjust the screws of the parking end-stops.
- Adjust the position of the tool's opto-endstops.
¶ Congrats!
You've setup the software and firmware for your robot. That was tough!
You may now:
- Continue to the object calibration guide: Calibration Guide
- Return to the assembly guide: Assembly Guide
- Return to the user guide: User Guide