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 a default configuration file for Jupyter Hub:
sudo mkdir -p /opt/jupyterhub/etc/jupyterhub/
cd /opt/jupyterhub/etc/jupyterhub/
sudo /opt/jupyterhub/bin/jupyterhub --generate-config
Edit the Jupyter Hub configuration file using nano:
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.
Add the following values to the end of the file, 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
Enter the superuser's shell:
Test that jupyterhub works by starting the server and opening its public url on a browser (i.e. the one on port 8000):
export PATH=$PATH:/opt/jupyterhub/bin # Temporarily add JupyterHub binaries to the path.
jupyterhub -f /opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py # Start JupyterHub.
Use a browser to open JupyterHub at the pi's IP and the 8000 port (e.g. http://YOURPISIP:8000).
Exit the superuser shell:
Our systemd unit file for Jupyter Hub will launch the service as the root user.
To install and enable the service:
# Install the unit.
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 JupyterHub.
sudo systemctl enable --now jupyterhub.service
sudo systemctl status jupyterhub.service
Now try connecting to the Pi's IP at port 8000.
Jupyter Hub configuration 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¶
Instructions to install and setup a mini OLED display to read system information is available at the mini-display guide.
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
Install components:
. /etc/os-release
echo "deb http://deb.debian.org/debian ${VERSION_CODENAME}-backports main" > /etc/apt/sources.list.d/backports.list
apt update
# Install or update the package:
apt install -y -t ${VERSION_CODENAME}-backports cockpit
Enable Cockpit on boot:
sudo systemctl enable cockpit.service
sudo systemctl start cockpit.service
sudo systemctl status cockpit.service
Access Cockpit on port 9090 with your browser at the Pi's IP. A user and password are required, use the default credentials for the pi user (or for the OS you've installed).
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