2.1. Linux Installation

Below, we describe how to setup FOBOS 3.0 software and test that everything is working on Linux.

2.1.1. Requirements

  1. A PC with Ubuntu 22.04 installed.

  2. FOBOS 3.0 fobos-v3.0.tgz file.

  3. You must have sudo rights.

2.1.2. Setup Network Sharing (Optional)

If your computer has two network interfaces, you can configure one to access the Internet and the other to connect to the Pynq board and maybe other instruments using a non routable IP address range. We describe here how to do this with Ubuntu 22.04. In the example below, the network interface for the instruments network is enp2s0 and the IP address range is 192.168.2.1 - 192.168.255. You can find the names and the network information of your PC with the ip a show command.

Create the file etc/netplan/20-instruments.yaml with the following contents and adjust the interface name and the IP address range to your requirements.

network:
  ethernets:
    enp2s0:
      dhcp4: false
      addresses: [192.168.2.1/24]
  version: 2

Then apply these changes with sudo netplan apply.

Edit the file /etc/sysclt.conf and uncomment net.ipv4.ip_forward=1 to allow forwarding of packets between interfaces. Now apply these changes with

sudo sysctl -p /etc/sysctl.conf
sudo /etc/init.d/procps restart

Then configure iptables. Adjust the IP address range to match what you used above.

sudo iptables -A FORWARD -j ACCEPT
sudo iptables -t nat -s 192.168.2.0/24 -A POSTROUTING -j MASQUERADE
sudo apt-get install iptables-persistent

The last command will ask whether to apply the new rules, answer yes and then check if they are contained in the file /etc/iptables/rules.v4.

2.1.3. Basic Downloads

Note: The following installation procedure was tested on Linux Ubuntu 22.04.

  1. Download FOBOS from the FOBOS home page.

  2. Extract the archive into a directory of your choice

    tar xvfz fobos-v3.0.tgz

    Note

    You can also clone FOBOS from Github. Then you would skip steps 1 and 2 from above.

  3. Use the following commands to install pip and make:

    sudo apt-get install python3-pip
sudo apt install make

  4. Enter the fobos directory and install the few necessary Python packages:

    cd fobos
sudo pip3 install -r requirements.txt

2.1.4. JupyterLab Installation

These installation instructions are based on Install JupyterLab the Hard Way.

Install JupyterHub and JupyterLab into a virtual environment

  1. Install Python support for virtual environments.

    sudo apt-get install python3-venv

  2. Create a virtual environment for JupyterHub and JupyterLab.

    sudo python3 -m venv /opt/jupyterhub/

  3. Install JupyterHub and JupyterLab into this virtual environment.

    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

  4. Then install nodejs and npm to support the configurable-http-proxy that JupyterHub needs.

    sudo apt install nodejs npm
sudo npm install -g configurable-http-proxy

Create JupyterHub configuration

  1. Create a directory for the configuration files and generate the JupyterHub configuration file.

    sudo mkdir -p /opt/jupyterhub/etc/jupyterhub/
cd /opt/jupyterhub/etc/jupyterhub/
sudo /opt/jupyterhub/bin/jupyterhub --generate-config

  2. Edit the config file we just created as root jupyterhub_config.py and change the following settings.

    c.Spawner.notebook_dir = '~/notebooks/'
c.Spawner.default_url = '/lab'

Configure Systemd to automatically start JupyterHub

  1. Create a folder for the systemd file

    sudo mkdir -p /opt/jupyterhub/etc/systemd

  2. Then create as root the file /opt/jupyterhub/etc/systemd/jupyterhub.service and past the following instructions into the file:

    [Unit]
Description=JupyterHub
After=syslog.target network.target

[Service]
User=root
Environment="PATH=/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/opt/jupyterhub/bin"
ExecStart=/opt/jupyterhub/bin/jupyterhub -f /opt/jupyterhub/etc/jupyterhub/jupyterhub_config.py

[Install]
WantedBy=multi-user.target

  3. Link this file to the Systemd’s directory

    sudo ln -s /opt/jupyterhub/etc/systemd/jupyterhub.service /etc/systemd/system/jupyterhub.service

  4. Have systemd reload the configuration file

    sudo systemctl daemon-reload

  5. Enable this service

    sudo systemctl enable jupyterhub.service

  6. And finally start JupyterHub

    sudo systemctl start jupyterhub.service

  7. You can always check if its running:

    sudo systemctl status jupyterhub.service

    You can quit this status display by pressing q on the keyboard.

2.1.5. Conda Installation

These installation instructions are based on Install JupyterLab the Hard Way. We will use conda to manage the Python environments.

  1. Get the Anaconda public GPG key

    cd
curl https://repo.anaconda.com/pkgs/misc/gpgkeys/anaconda.asc | gpg --dearmor > conda.gpg
sudo install -o root -g root -m 644 conda.gpg /etc/apt/trusted.gpg.d/
rm conda.gpg

  2. Add Debian repository

    echo "deb [arch=amd64] https://repo.anaconda.com/pkgs/misc/debrepo/conda stable main" | sudo tee /etc/apt/sources.list.d/conda.list

  3. Install conda

    sudo apt update
sudo apt install conda

  4. Make conda easily available by running the setup script on login.

    sudo ln -s /opt/conda/etc/profile.d/conda.sh /etc/profile.d/conda.sh

  5. Install a default conda environment for all users. But first check your version of python by issuing python3 --version on the command line. If necessary edit the version in the code below.

    sudo mkdir /opt/conda/envs/
sudo /opt/conda/bin/conda create --prefix /opt/conda/envs/python python=3.10 ipykernel
sudo /opt/conda/envs/python/bin/python -m ipykernel install --prefix=/opt/jupyterhub/ --name 'python' --display-name "Python (default)"

2.1.6. FOBOS Software Installation

Finally we get to install FOBOS to run in the JupyterLab we just created.

  1. Install required packages

    sudo /opt/jupyterhub/bin/python3 -m pip install numpy
sudo /opt/jupyterhub/bin/python3 -m pip install matplotlib
sudo /opt/jupyterhub/bin/python3 -m pip install scipy
sudo /opt/jupyterhub/bin/python3 -m pip install console-progressbar

  2. Install packages required for PDF export of Jupyter notebooks

    sudo apt-get install pandoc texlive-xetex texlive-fonts-recommended

  3. Install FOBOS into /opt/fobos by simply moving the whole directory tree.

    sudo mv fobos /opt/

  4. Create notebooks folders in all users home directories and copy fobos notebooks into the users notebook directories

    cd /home/username/
mkdir -p notebooks/fobos
cd notebooks/fobos
cp -a /opt/fobos/software/notebooks/* .

2.1.7. Install DUT Support

  1. Chipwhisperer DUTs

    These installation instructions are based on ChipWhisperer Linux Installation. As we only want to program the DUTs we won’t install everything.

    Create a directory for ChipWhisperer and clone it from git into this location

    sudo mkdir /opt/chipwhisperer
sudo chown $USER /opt/chipwhisperer
cd /opt
git clone https://github.com/newaetech/chipwhisperer

    Set the udev rules and make all users members of the corresponding groups so that they can access the Chipwhisperer boards

    sudo cp chipwhisperer/hardware/50-newae.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo usermod -aG dialout $USER
sudo usermod -aG plugdev $USER

    Repeat the last two lines for all users that have to access target boards.

    Warning

    If you don’t have or want a chipshisperer group, replace chipwhisperer with plugdev in the file 50-newae.rules. Then don’t add the user to the chipwhisperer group.

    Optional: Add the all users to the chipwhisperer group

    sudo usermod -aG chipwhisperer $USER

    Add ChipWhisperer to our JupyterHub package directory and install require packages.

    sudo ln -s /opt/chipwhisperer/software/chipwhisperer/ /opt/jupyterhub/lib/python3.10/site-packages/

    Install the additional software packages that ChipWhisperer needs

    sudo /opt/jupyterhub/bin/python3 -m pip install pyusb
sudo /opt/jupyterhub/bin/python3 -m pip install libusb1
sudo /opt/jupyterhub/bin/python3 -m pip install pyserial
sudo /opt/jupyterhub/bin/python3 -m pip install tqdm
sudo /opt/jupyterhub/bin/python3 -m pip install ECPy
sudo /opt/jupyterhub/bin/python3 -m pip install configobj

  2. Digilent DUTs

    FPGA boards from Digilent Inc. require the Digilent Adept tools. Download the latest versions of the following packages for Linux from Digilent Adept Website and install them.

    • Adept for Linux Runtime

    • Adept Utilities

    Make sure that all users are members of the correct groups.

    sudo usermod -aG dialout $USER
sudo usermod -aG plugdev $USER

2.1.8. Install Oscilloscope Support

PicoScope

Go to the Pico Tech Download page and select the latest version of PicoScope for your operating system. Follow the instructions on their webpage to install it.

In order for FOBOS to use a PicoSope you also have to install the Pico SDK. Create a directory sdk in your /opt/picoscope directory and give it your user rights.

sudo mkdir /opt/picoscope/sdk
sudo chown $USER /opt/picoscope/sdk
cd !$

Clone the Pico SDK into this directory and install it.

git clone https://github.com/picotech/picosdk-python-wrappers.git
cd picosdk-python-wrappers
sudo /opt/jupyterhub/bin/python3 -m pip install .

Now the SCA Workstation should be ready.