Instrument software

Microscope control software for automated data collection

The instrument software is split into two main parts:

  • The HAL , which directly manages the hardware and collects images.
  • The UI , which coordinates data collection steps at a high level and allows use of the instrument as a manual microscope.

Setup

We will soon make a prebuilt Raspberry Pi image that can be flashed directly to a SD card and used immediately. Until then, or for development purposes, the steps below describe how to set one up from scratch.

Installation

Base operating system image

The HAL requires Raspbian Bullseye 64-bit. This can be installed using the Raspberry Pi Imager as described on the Raspberry Pi website. As of this writing, this OS is a little buried: after opening the “Operating System” menu, open “Raspberry Pi OS (other)” and scroll down to “Raspberry Pi OS (Legacy, 64-bit)”.

We recommend setting up the Pi with only basic peripherals (mouse, keyboard, monitor, and optionally wired network) connected — do not plug in any 454 hardware yet.

Common dependencies

There are a number of packages that will need to be installed to be able to compile and run the UI and HAL. Turn on the Pi, connect it to a network, and in a terminal, run the following:

# Initial setup
sudo apt update
sudo apt upgrade

# Convenience packages
sudo apt install htop tmux mosh git build-essential rsync python3-pip

# Needed to build libcamera-apps
sudo apt install -y libepoxy-dev libjpeg-dev libtiff5-dev
sudo apt install -y qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5
sudo apt install -y libavcodec-dev libavdevice-dev libavformat-dev libswresample-dev
sudo apt install -y cmake libboost-program-options-dev libdrm-dev libexif-dev
sudo apt install -y libboost-dev
sudo apt install -y libgnutls28-dev openssl libtiff5-dev
sudo apt install -y qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5
sudo apt install -y meson
sudo apt install -y libglib2.0-dev libgstreamer-plugins-base1.0-dev
sudo apt install -y libpng-dev
sudo pip3 install jinja2
sudo pip3 install pyyaml ply
sudo pip3 install --upgrade meson

# Pi-specific packages for hardware access
# These *can* be installed on an aarch64 Debian Bullseye installation
# to compile there instead, but they will have to be manually copied from the Pi repo
sudo apt install libcamera-dev libcamera0 libpigpio1 libpigpio-dev raspberrypi-kernel

# Python packages for UI
sudo apt install python3-pyside2.* python3-pil python3-numpy python3-jsonschema

454 software

Now, it’s time to install the 454 software. In a terminal, run the following:

# Create required directories
mkdir -p ~/454/output/manual
sudo mkdir -p /454/hal

# Clone, compile, and install the HAL
git clone https://github.com/454bio/454-hal.git ~/454/hal-src
cd ~/454/hal-src
git submodule update --init --recursive
meson setup builddir
cd builddir
meson compile
rsync -avd ./ /454/hal/

# Clone the UI
git clone https://github.com/454bio/454-ui.git ~/454/ui

Configuration

To configure your specific hardware, first start by copying over the default configuration files:

sudo cp ~/454/hal-src/assets/config/*.{json,ini,yml} /454/

Then the next steps depend on the components in your setup.

Temperature sensor

TODO: I2C vs 1-wire, need to enable in Pi config

Camera

TODO:

  • Pi HQ vs VC, relevant installation steps for each
  • Mention pylablib

Filter wheel

TODO: stepper vs servo

Focus calibration

Finalizing your setup

  • Connect hardware, run manually
  • HAL in systemd
  • Desktop shortcut to UI

Usage

Manual image capture

The manual controls allow realtime control of the sequencer hardware. To use the manual controls, open the UI and click the “Manual controls” button.

The top half configures visible light TIRF. After enabling any number of LEDs using the checkbox on the right, an exposure time in ms and intensity in ‰ (parts per 1000) can be set. These TIRF settings will be used for “Flash”, which flashes the LEDs without capturing an image; “Capture”, which captures one image, saves it in ~/454/output/manual, and displays it in the preview; and “Start live preview”, which continuously captures images and displays them in the preview. The HAL automatically exposes the sensor just long enough for the configured TIRF.

If the filter is anything other than “Any filter”, the filter wheel will be moved to the set position before an image is captured.

The focus buttons nudge the base focus — the focus for all other colors will be adjusted by the same amount.

The “Heater” section will only be present if a temperature sensor is configured. The “Set” and “Disable” buttons respectively set the specified temperature or disable the heater entirely.

The “UV” section allows manual cleaving with the “Cleave”, and the time and intensity behave exactly like the visible light controls.

Automated data collection

To collect data for sequencing automatically, open one of the preset sequencing protocols from the “File –> Open” dialog and then start it by pressing “Start protocol”. It will run until completion unless stopped with the “Stop protocol” button or a hardware error is detected.

TODO: Describe the available protocols

Writing your own data collection protocol

TODO