Additional Applications Setup
Additional apps¶
A few useful applications can be installed on the robot's computer, which may help with development or general usage.
Jupyter Lab¶
Jupyter Lab will serve a web editor for jupyter notebooks.
This is one of the best ways to operate the robot programatically.
Warning
If you install Jupyter Hub, you don't need to install Jupyter Lab.
"If you want to use Jupyter Notebook, just use Jupyter Notebook. If you want multiple users to juse their own Jupyter encapsulated in the same machine, Jupyter Hub." (src).
Note
We are working on integrating pipettin with PLR, which is a hardware-agnostic-ish python API for liquid handling robots.
Jupyter can be installed and setup with pip:
- Jupyter Lab: https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html#pip
- Jupyter Hub: https://jupyterhub.readthedocs.io/en/stable/tutorial/quickstart.html#installation
# Create a vitual environment.
python -m venv ~/venv-jupyter
source ~/venv-jupyter/bin/activate
# JupyterLab and Notebook are also needed by Jupyter Hub.
python3 -m pip install jupyterlab notebook
Set a password and launch the server:
# Set a new password.
jupyter notebook password
# Launch the server.
jupyter lab --ip="0.0.0.0" --no-browser # --port 8000 # Optionally change the port
Open the notebook's address on a web browser, using port 8888. If you see the Jupyter Lab web page, all is worlking well.
Token and passoword
A token will be printed to the console. Save it in case you need it at some point.
Jupyter Lab can be opened with a token in the URL (as shown), or a shorter one without the token, which will request the password you just set.
Now close the browser, and shut down the server by pressing Ctrl+c, and answering y when prompted for confirmation.
To auto-start Jupyter Lab on boot, install our systemd unit:
# Inspect
cat ~/pipettin-bot/code/systemd.units/jupyter.service
# Install
sudo ln -s ~/pipettin-bot/code/systemd.units/jupyter.service /etc/systemd/system/
sudo systemctl daemon-reload
# Enable
sudo systemctl enable --now jupyter.service
sudo systemctl status jupyter.service
Open the notebook's address on a web browser. It should now start automatically on boot.
Jupyter Hub¶
Jupyter Hub is a managed frontend to Jupyter Lab notebooks.
Warning
If you install Jupyter Hub, you don't need to install Jupyter Lab.
"If you want to use Jupyter Notebook, just use Jupyter Notebook. If you want multiple users to juse their own Jupyter encapsulated in the same machine, Jupyter Hub." (src).
Jupyter Hub has an additional dependency on an npm package. If this is unavailable to you, just use Jupyter Lab, which will always run as the pi user.
To install Jupyter Hub (and its dependencies) follow this guide: https://jupyterhub.readthedocs.io/en/1.2.2/installation-guide-hard.html#part-1-jupyterhub-and-jupyterlab
Excerpts from that guide have been included here for reference.
Install:
# Create a vitual environment.
sudo python3 -m venv /opt/jupyterhub/
sudo /opt/jupyterhub/bin/python3 -m pip install wheel
sudo /opt/jupyterhub/bin/python3 -m pip install jupyterhub jupyterlab
sudo /opt/jupyterhub/bin/python3 -m pip install ipywidgets
# Install this.
sudo npm install -g configurable-http-proxy
Create and edit a Jupyter Hub configuration file:
sudo mkdir -p /opt/jupyterhub/etc/jupyterhub/
cd /opt/jupyterhub/etc/jupyterhub/
sudo /opt/jupyterhub/bin/jupyterhub --generate-config
sudo nano /opt/jupyterhub/bin/jupyterhub/jupyterhub_config.py
You may need to edit the file to allow certain "origins", and be able to connect to the Jupyter Hub server remotely. See https://stackoverflow.com/a/43500232 for details. Set the following values to allow all:
c.Spawner.default_url = '/lab' # Base path for the website
c.NotebookApp.allow_origin = '*' # allow all origins
c.NotebookApp.ip = '0.0.0.0' # listen on all IPs
c.Authenticator.allow_all = True # allow all users
Test that it works by starting the server and opening its public url on a browser (i.e. the one on port 8000):
Our systemd unit file for jupyter hub will launch the service as the pi user, with a user-editable config file.
To install and enable the service:
# Install
sudo mkdir -p /opt/jupyterhub/etc/systemd
sudo cp ~/pipettin-bot/code/systemd.units/jupyter_hub.service /opt/jupyterhub/etc/systemd/jupyterhub.service
sudo ln -s /opt/jupyterhub/etc/systemd/jupyterhub.service /etc/systemd/system/jupyterhub.service
sudo systemctl daemon-reload
# Enable and start
sudo systemctl enable --now jupyterhub.service
sudo systemctl status jupyterhub.service
Now try connecting to the Pi's IP at port 8000.
Jupyter Hub config and port
The output of the sudo systemctl status jupyterhub.service command will show the port (e.g. --port 8000) and the config file in use (e.g. --config=/opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py).
You may need to allow connections from IPs other then the local-host, by editing Jupyter's config. Our config was found at /opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py.
Mini display¶
Connect the 128x64 monochrome OLED to the Raspberry Pi's I2C pins, on the GPIO header.
The I2C address is expected to be 0x3C.
The reset pin is expected to be D4.
Setting up I2C on the Pi¶
I had Ubuntu on this Pi, here is a guide on enabling I2C in Ubuntu.
lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 20.04.6 LTS
Release: 20.04
Codename: focal
Use raspi-config to enable I2C.
# Check that I2C shows up enabled too:
cat /boot/firmware/config.txt | grep i2c
cat /boot/firmware/syscfg.txt | grep i2c
cat /boot/firmware/usercfg.txt | grep i2c
For an I2C speed boost, see: https://learn.adafruit.com/monochrome-oled-breakouts/python-setup
Add pi to the relevant groups, reboot and check:
sudo usermod -a -G gpio pi
sudo usermod -a -G i2c pi
sudo usermod -a -G dialout pi
sudo reboot # Reboot and reconnect.
groups # Should list all groups.
ls -l /dev/gpio* # Check.
Install dependencies:
sudo apt-get install python3-dev python3-pil python3-numpy python3-rpi.gpio rpi.gpio-common
sudo apt install i2c-tools
Check that I2C is enabled:
sudo i2cdetect -y 1 # Works, shows "3c" somewhere in the grid.
sudo i2cdetect -y 0 # Fails.
sudo ls -l /dev/i2c*
Install python dependencies¶
See: https://learn.adafruit.com/monochrome-oled-breakouts/python-setup
System packages:
sudo apt-get install python3-pil python3-numpy
sudo apt install python3-dev python3-netifaces # installs python netifaces
python -m venv venv-display --system-site-packages # makes netifaces available in the venv
Python packages:
source venv-display/bin/activate
python3 -m pip install --upgrade pip
pip3 install pillow # --upgrade # pillow==9.5
pip3 install psutil
pip3 install adafruit-circuitpython-ssd1306 # installs python digitalio
Usage¶
Install, enable, and start the systemd units for the mini display:
# For the mini OLED display.
sudo ln -s /home/pi/pipettin-bot/code/systemd.units/mini_display.service /etc/systemd/system/
sudo ln -s /home/pi/pipettin-bot/code/systemd.units/mini_display_prepare.service /etc/systemd/system/
# Reload the units.
sudo systemctl daemon-reload
# Enable and start.
sudo systemctl enable --now mini_display_prepare.service
sudo systemctl status mini_display_prepare.service
sudo systemctl enable --now mini_display.service
sudo systemctl status mini_display.service
Cockpit¶
Cockpit is a web application for system monitoring. It is useful to check if the system has any issues, access its terminal, and manage systemd services.
Good guides are available for this on the internet:
- Official install instructionsÑ https://cockpit-project.org/running#debian
- https://pimylifeup.com/raspberry-pi-cockpit/
- https://opensource.com/article/21/5/raspberry-pi-cockpit
MkDocs docs¶
Warning
TO-DO: write a systemd unit to start the mkdocs site at boot.
GitBuilding docs¶
Warning
This is deprecated. Left here for future reference.
Unit file: gitbuilding.service
Requirements:
- Docs repo at
/home/pi/pipettin-grbl-docs/ - Venv with gitbuilding installed at
/home/pi/pipettin-grbl-docs/bot_venv - Learn more at: https://gitlab.com/pipettin-bot/pipettin-grbl-docs