Structure

The instructions for installing Pixelator involve downloading the code into the /home/control/work/stxm/ directory. To allow the installation of multiple versions, it is best to put each version in a new directory in work/ and make a stxm soft link that points to the one you wish to use such that the startup scripts will still work the same. For example:

control@pixelator-1:~/work$ ls -l
total 20
drwxr-xr-x 14 control control 4096 Jul  7  11:20 stxm-20250520
drwxr-xr-x 14 control control 4096 Aug 22  15:07 stxm-20250822
lrwxrwxrwx  1 control control   13 Jul  4  22:54 stxm -> stxm-20250520

An advantage of this strategy is that one can easily switch back and forth between versions so that one can go back to a previous (working) version if there are problems with the newer version.

At PolLux, we use 2 different links together with startup scripts for a stxm-stable (known to work) and a stxm-test (latest) version:

control@x07da-stxm-1:~/work$ ls -l
total 20
drwxr-xr-x 14 control control 4096 Feb  3  2025 stxm
drwxr-xr-x 14 control control 4096 Jul  7 11:20 stxm-20250520
drwxr-xr-x 14 control control 4096 Aug 13 17:30 stxm-20250702-russ
drwxr-xr-x 14 control control 4096 Aug 13 18:02 stxm-20250813-russ
drwxr-xr-x 14 control control 4096 Aug 22 15:07 stxm-20250822
lrwxrwxrwx  1 control control   13 Jul  4 22:54 stxm-stable -> stxm-20250520
lrwxrwxrwx  1 control control   20 Aug 13 17:33 stxm-test -> ./stxm-20250813-russ

Download New Code

The new code can be downloaded from gitea.psi.ch. There are 3 ways to do this:

Use the git clone command with an https link - requires a token from gitea.psi.ch
```
cd ~/work
git clone https://gitea.psi.ch/MicroSpectro/Pixelator.git stxm-new-version
```
replace stxm-new-version with whatever directory name you wish to use (including the date is useful, e.g. stxm-20250401). When authenticating the git access, give your gitea user name and use the token as the password.
Use the git clone command with an ssh link - requires uploading your public key to gitea.psi.ch
```
cd ~/work
git clone git@gitea.psi.ch:MicroSpectro/Pixelator.git stxm-new-version
```
replace stxm-new-version with whatever directory name you wish to use (including the date is useful, e.g. stxm-20250401).
Log in to gitea.psi.ch and use the blue <> code button menu to download a ZIP or TAR.GZ archive. If you want a special branch (to test a special feature still in development), then be sure to choose the branch before downloading the code. Copy the archive into the work directory.
```
cd ~/work
unzip Pixelator-master.zip
mv pixelator stxm-new-version
rm Pixelator-master.zip
```
or
```
cd ~/work
tar -xfvz Pixelator-master.tar.gz
mv pixelator stxm-new-version
rm Pixelator-master.tar.gz
```
replace stxm-new-version with whatever directory name you wish to use (including the date is useful, e.g. stxm-20250401). Next, you need to copy the commit hash into gen_version_hash.sh into the place where you see lots of zeros. You can extract the commit hash from a ZIP archive (but not a TAR.GZ archive) with:
```
unzip -z Pixelator-master.zip
```
The other way is to copy it from the gitea.psi.ch web page when you are downloading the archive. It is a bit hidden and the easiest way to find it is to right click on the latest commit short-hash and copy the link - to find this, start at the blue <> Code button, go down one line and then left to the set of 10 characters in a box, e.g. f260922198. The link will look like https://gitea.psi.ch/MicroSpectro/Pixelator/commit/f2609221982772e427a1fad28679b16db256bde5 and the hash you need is the last part, e.g. f2609221982772e427a1fad28679b16db256bde5. Open gen_commit_hash.sh in a text editor and replace the set of zeros with your hash. The file should end up looking something like this:
```
#!/bin/sh

if [ -f ".git/HEAD" ]; then 
    v=`git rev-parse HEAD`
else
    v="f2609221982772e427a1fad28679b16db256bde5"
fi
printf %s "$v"
```

Switch Branch (optional)

If you wish to use a feature that is still under development, it might be in a special branch of the code (the standard branch is called master). First, make sure that you are in the git repo directory:

cd ~/work/stxm-new-version

To list the available branches:

git branch -a

The current branch will be marked with an *. To switch to a different branch:

git checkout branch-name

Compiling

To compile Pixelator:

cd ~/work/stxm-new-version
autoreconf -i
mkdir build
cd build
../configure
make
cd PixelatorController/config/
make     #for config files used for the NoHardware version
cd ../../PixelatorGUI/config/
make

The dependencies should already be installed (but it is possible for new ones to be added). If you get errors asking for certain dependencies to be installed, check the installation instructions to see if the dependency is mentioned there. If in doubt, ask one of the PolLux staff for help.

Most of the time, there are no significant changes to the Orocos modules and so there is no need to compile this part again. Further, the Orocos modules are not part of the "parallel versions" scheme that we are using for Pixelator and recompiling the modules will overwrite the previous version. If you are not sure that you want to recompile the Orocos modules, then don't do it. However, if you do wish to compile the Orocos modules:

. ~/orocos/setup.sh
cd ~/work/stxm/PixelatorRealtime/
make
make install

Config files

It typically makes sense to copy the config files from the previously installed version of Pixelator. Check your startup script to see their location, but in a standard installation:

cd ~/work/
cp -r stxm-old-version/PixelatorController/config stxm-new-version/PixelatorController/config

Activate a Different Version

A different version can be made active by redirecting the link to point at the directory of the desired version. From the ~/work/ directory, use the command: ln -sf $TARGET $LINK_NAME where $TARGET is the directory name of the desired version (e.g. stxm-new-version) and $LINK_NAME is the path that your startup scripts expect (e.g. stxm or stxm-test).

This command can be used both to switch to a new version and back to an older version.

If you have compiled a new version of the Orocos modules, then the old version was overwritten and going back to the old version means recompiling the old version of the modules. The set of commands for compiling Orocos modules given in the Compiling section above will accomplish this task - just make sure that the cd command brings you to the directory containing the code version that you want to compile. In almost all cases, the repository will contain compatible Orocos and Pixelator code.