Software Build: Packages, Python, Drivers and Utilities#

Prerequisite:

RT Build: Firmware, OS and RT Kernel complete and verified

Next:

run 6. Final Reboot and Verification, then the instrument is ready

Install only what the instrument needs. GUIs are not run locally; they are exported over SSH or VNC and plots are written to disk.

1. System Packages#

Core Build and Runtime#

sudo apt update
sudo apt install -y \
    build-essential \
    cmake \
    git \
    pkg-config \
    software-properties-common \
    wget curl \
    net-tools iproute2 \
    htop \
    tmux \
    rsync \
    libffi-dev libssl-dev zlib1g-dev libbz2-dev liblzma-dev \
    libreadline-dev libsqlite3-dev libncursesw5-dev \
    libxml2-dev libxmlsec1-dev xz-utils llvm \
    python3-pip python3-dev python3-venv \
    libboost-all-dev \
    libcfitsio-dev libccfits-dev \
    libopencv-dev \
    libzmq3-dev libzmqpp-dev \
    nlohmann-json3-dev

Headless GUI Export#

Minimal X client libraries and a lightweight window manager. No display manager, no desktop environment.

sudo apt install -y \
    xauth x11-apps x11-utils \
    tigervnc-standalone-server tigervnc-common \
    openbox \
    xterm \
    fonts-dejavu-core

Note

Without xauth, ssh -X silently fails to set $DISPLAY and every remote GUI dies with cannot open display.

Qt Runtime (only if Qt GUIs run here)#

Prefer running Qt GUIs on an operator workstation.

sudo apt install -y \
    python3-pyqt5 \
    qtbase5-dev qtbase5-dev-tools \
    libxcb-xinerama0 libxkbcommon-x11-0

Warning

qt5-default does not exist on Ubuntu 26.04. Use qtbase5-dev and set QT_SELECT=5 if a legacy build script demands it.

2. Python Environment#

ImageStreamIO#

The tracking camera publishes frames to shared memory through ImageStreamIO, which no distro packages:

git clone https://github.com/milk-org/ImageStreamIO.git
cmake -S ImageStreamIO -B ImageStreamIO/build
cmake --build ImageStreamIO/build -j
sudo cmake --install ImageStreamIO/build
sudo ldconfig

Upstream installs its CMake config straight into /usr/local/lib/cmake, where find_package does not look. Point every build on this host at it, including the ones install.sh runs under sudo:

echo 'ImageStreamIO_ROOT=/usr/local/lib/cmake' | sudo tee -a /etc/environment

Log out and back in for it to take effect.

HISPEC Software#

Install the HISPEC software as described in Installing HISPEC on a host, with the tracking camera module:

sudo /opt/hispec/app/systemd/install.sh hsfei --host-role feiserver --extra atcam --extra scripts

--extra scripts adds what the tracking camera analysis scripts plot with. Both are recorded in /etc/hispec/extras, so later runs keep them without repeating the flags.

Warning

PyQt5 comes from apt, not the venv.

Headless Matplotlib#

Force the non-interactive backend so scripts never block on $DISPLAY:

sudo tee /etc/profile.d/mpl-headless.sh > /dev/null <<'EOF'
export MPLBACKEND=Agg
EOF

Override when tunnelling a GUI: MPLBACKEND=Qt5Agg python plot.py.

3. Remote GUI and Plot Access#

Preferred: write plots, FITS previews and diagnostics to disk and pull them:

rsync -avz hsfei@hispecfei:/data/plots/ ./plots/
scp hsfei@hispecfei:/data/frames/latest.fits .

Occasional GUI applications:

ssh -X hsfei@hispecfei

For persistent graphical sessions, use TigerVNC over an SSH tunnel.

Warning

Never expose VNC ports to the network. Use -localhost yes and SSH port forwarding only, and keep the VNC server off cores 0-5 (5. Real-Time Process Placement).

4. Hardware Drivers and Libraries#

Physik Instrumente (PI) Driver#

  1. Download the Linux driver package from the PI Software Suite on a workstation and scp it over.

  2. Extract and run the installer:

    cd <path_to_unpacked_PI_driver>
sudo ./INSTALL

  3. Installer prompts:

    Prompt

    Answer

    Do you agree to the General Software License Agreement? [yn]

    y

    (license text shown in pager)

    q

    Install the PI ${PI_PRODUCT_NAME} high level GCS library? [ynq]

    y

    To enable the access rights to a user group now press ‘y’

    y

    Enable the access rights to a user group now? [ynq]

    y

    (license text shown again)

    n

    Install ${PIPython} now? [ynq]

    y

    Install ${PI Terminal} now? [ynq]

    y

    Please enter the name of the user group …

    dialout

SPI Driver (libft4222)#

The FT4222 is an external USB-to-SPI board (USB 0403:601c) that links the server to instrument hardware.

  1. Connect the board over USB. In SPI master mode, its Slave Select (SS) pin must be tied high.

  2. Extract and install:

    tar xfvz libft4222-1.4.4.232.tgz
sudo ./install4222.sh
sudo ldconfig
ldconfig -p | grep ft4222

    This installs libft4222.so to /usr/local/lib and headers to /usr/local/include.

  3. Build and run the test binary (no sudo needed):

    cd examples
cc get-version.c -lft4222 -Wl,-rpath,/usr/local/lib -o ft4222-version
./ft4222-version

    Expected: Chip version: 42220400, LibFT4222 version: 010404E8

Note

Link dynamically. If a static build is needed: cc -static get-version.c -lft4222 -ldl -lpthread -lrt -lstdc++ -o ft4222-version-static. Ignore old advice to install binutils-2.26; it does not exist on 26.04.

FT4222 udev Rules#

  1. Create /etc/udev/rules.d/99_HISPEC_spi_ftdi_4222.rules:

    SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="601c", OWNER="hsfei", MODE="0660", GROUP="dialout"

  2. Reload, replug the board, and verify:

    sudo udevadm control --reload-rules
sudo udevadm trigger
lsusb | grep 0403:601c                  # board detected
ls -l /dev/bus/usb/*/* | grep -i 0403   # hsfei dialout 0660

CameraD (camera-interface)#

cd ~
git clone https://github.com/CaltechOpticalObservatories/camera-interface.git
cd camera-interface
git submodule update --init camerad/Instruments/hispec_tracking_camera

cd build
rm -rf ./*
cmake .. -DCONTROLLER=archon -DINSTRUMENT=hispec_tracking_camera
make -j"$(nproc)"

# Record both commits in the as-built log
git -C ~/camera-interface rev-parse --short HEAD
git -C ~/camera-interface/camerad/Instruments/hispec_tracking_camera rev-parse --short HEAD

-DINSTRUMENT loads camerad/Instruments/hispec_tracking_camera, so the submodule must be checked out first. make builds camerad, emulator, listener and socksend into ~/camera-interface/bin. The isolated cores are already excluded from normal scheduling (8. CPU Shielding), so the build stays on housekeeping cores without taskset.

See archongui.rst for Archon-side configuration.

5. Real-Time Process Placement#

Only instrument code runs on the shielded cores 0-5. RT privileges are set up in 10. RT Tooling and Scheduling Privileges.

# Direct affinity
taskset -c 0-5 chrt -f 80 ./camerad

# Or via cpuset shielding
sudo cset shield --cpu 0-5 --kthread=on
sudo cset shield --exec -- chrt -f 80 ./camerad
sudo cset shield --reset      # tear down

Must never run on cores 0-5: VNC / Xvnc / Openbox, SSH sessions and shells, rsync / scp, monitoring tools, and compilation.

Keep login shells off the shielded cores by adding to ~/.bashrc:

taskset -cp 6-13 $$ > /dev/null 2>&1

6. Final Reboot and Verification#

sudo reboot

Check

Command

Expected

HISPEC

hispec doctor

No problems found.

FT4222

./ft4222-version

Chip version: 42220400

udev perms

ls -l /dev/bus/usb/*/* | grep 0403

hsfei dialout 0660

X11 forward

ssh -X hsfei@hispecfei xeyes

window appears

VNC pinning

taskset -cp $(pgrep Xvnc)

not 0-5

Re-run the latency baseline (11. Verification) with the instrument software running.

7. Troubleshooting#

Symptom

Resolution

cannot open display over SSH

Install xauth; confirm X11Forwarding yes in sshd_config; connect with ssh -X. Do not set $DISPLAY manually.

ssh -X fails, -Y works

Untrusted-X restriction. Acceptable on a trusted LAN.

VNC shows a grey screen

~/.vnc/xstartup not executable or openbox missing. Check ~/.vnc/*.log.

VNC refuses remote connections

Expected with -localhost yes. Use the SSH tunnel.

Qt: could not load the Qt platform plugin "xcb"

Install libxcb-xinerama0 and libxkbcommon-x11-0. Debug with QT_DEBUG_PLUGINS=1.

Matplotlib fails with no display

Check echo $MPLBACKEND is Agg (2. Python Environment).

import serial fails

Install pyserial, not serial.

FT4222 not found

lsusb for 0403:601c. Absent: cable/board problem. Present but inaccessible: reload udev rules and replug (FT4222 udev Rules).

FT4222 ABI mismatch on libft4222.so

Usually a stale .so in /usr/local/lib. Remove old copies and run sudo ldconfig.

SPI master mode misbehaves

Slave Select (SS) must be tied high.

8. Pending Tasks#

  • [ ] VNC setup: document the pinned TigerVNC unit and xstartup.

  • [ ] Software stack: track upstream GitHub build notes for Python libraries, C++ sources and hardware drivers.

9. References#