Introduction
Many of the hardware drivers for the PCI cards used by Pixelator are from the Comedi project, which has been merged into the mainline Linux kernel. One consequence of this change is that the "comedi number" of a device is no longer stable between reboots and we have to switch to using the /sys virtual file system to refer to specific hardware in a stable way. So wherever we used to see things like a "device number", or a "/dev/comedi0", we will now need to set a "deviceName" option with a path string like "/sys/bus/pci/devices/0000:00:00.0/". This has been implemented in commits to the Pixelator repository on October 28th, 2025, and updating your installation after this date will require a change in configuration for both Pixelator and Orocos.
WARNING: This procedure involves compiling a new version of the Orocos modules, which will overwrite the previously compiled ones. Therefore, going back to a previous version will involve more than just switching the stxm-directory link to the previous version since the old Orocos modules will need to be compiled again.
Backup Config Files
It is a good idea to back up your current configuration files (including the start.ops file), just in case things go horribly wrong.
Mapping Addresses
Since you should already have a working configuration, it should be easy to adapt the configuration. The first thing to do is to note the comedi numbers that correspond to the PCI slot numbers using ls /sys/bus/pci/devices/*/comedi. For example, at PolLux:
control@x07da-stxm-1:~$ ls /sys/bus/pci/devices/0000*/comedi/
'/sys/bus/pci/devices/0000:03:01.0/comedi/':
comedi1
'/sys/bus/pci/devices/0000:03:02.0/comedi/':
comedi0
'/sys/bus/pci/devices/0000:03:03.0/comedi/':
comedi3
'/sys/bus/pci/devices/0000:03:04.0/comedi/':
comedi2
Here, references to a "comedi number", "devicePath", or "device number" of "0" (or "comedi0", or "/dev/comedi0") will need to be changed to "/sys/bus/pci/devices/0000:03:02.0/" (or "/sys/bus/pci/devices/0000:03:02.0/comedi/").
Installing a New Version
Please use these instructions to install the new version that uses code that is downloaded after 28.10.2025. Note that the update includes new code in the Orocos modules, so you will need to do the extra compiling for this. Further, be sure to copy across your current config files, in case they are different from what is stored in the repository.
Reconfigure Orocos start.ops
The Orocos start.ops file will need to be updated so that "device_nr" and "deviceNr" declarations are replaced with a "deviceName" declaration. For example, an old config of:
Sensor1.deviceName = "/sys/bus/pci/devices/0000:07:0d.0"
AO1.device_nr = 2
DO1.device_nr = 2
DI1.deviceNr = 2
should be changed to:
Sensor1.deviceName = "/sys/bus/pci/devices/0000:07:0d.0"
AO1.deviceName = "/sys/bus/pci/devices/0000:03:04.0/"
DO1.deviceName = "/sys/bus/pci/devices/0000:03:04.0/"
DI1.deviceName = "/sys/bus/pci/devices/0000:03:04.0/"
Update Pixelator Repository With New Config Files
Pixelator includes some devices that used Comedi configuration that needs to be updated to the new /sys configuration method. Search through your Pixelator config files and replace any "devicePath" : "/dev/comedi0" option (where the "0" can be any integer) with a corresponding deviceName option, e.g. deviceName : "/sys/bus/pci/devices/0000:03:04.0/".
You are likely to find options to change in:
pixelClock.jsonpositioner.jsondetector.json
PolLux examples can be viewed in this commit.
Test
Restart Orocos and look at the output for any text like [Error] or failed. Note which device type has the issue and check that part of the start.ops for mistakes.
Start Pixelator and check the output for issues. If you make it to "Pixelator is ready for client requests" without any bad messages, then it is probably all OK. If a devicePath option is accidentally left in, then it will just give a warning, which you will only see if your log4cpp.properties is configured to show warnings (e.g. the first line looks like log4cpp.rootCategory=WARN, stdout).
Save New Config Files in Gitea Repository
It is strongly recommended to keep the Gitea.psi.ch Pixelator repository up to date with your working config files. If you find git difficult to use, then you might prefer the "without internet access" method.
With Internet Access
- Check your startup script for PixelatorController to see which settings file (probably
settings.json) file is being used (don't assume you know!). - If they are not already there, copy the settings file and any other file that it references into your section of the local git repository. For example,
~/work/stxm/PixelatorController/config/MAXYMUS/ - If it is not already there, copy the
start.opsfile that you are using to your section of the local git repository. For example,~/work/stxm/PixelatorRealtime/startup/Maxymus/ - Use
git add FILE.jsonto select files to be committed to the repository. - Use
git statusto get a list of changed files - files that have been selected will show as green. - Repeat steps 4&5 until all of your changed config files have been selected (don't forget your
start.ops). - Use the
git commit -m "update configs for BEAMLINE"to finalise the set of changes as a "commit". - Use the
git pushcommand to send the "commit" to the central repository on the Gitea.psi.ch server.
Without Internet Access
- Copy the relevant config files onto a PC that does have internet access. Don't forget the
start.opsfile. - Visit the Gitea.psi.cg Pixelator repository.
- Use the web interface to navigate to the appropriate config directory (e.g.
Pixelator/PixelatorController/config/MAXYMUS/). - Near the top of the page, to the left of where it displays the current path, there is a button labelled
Add File. Click this button, then click onUpload Fileoption that appears in the drop-down menu. - Use the interface to upload the set of files that belong in the config directory.
- Click on the
Commit Changesbutton. - Repeat steps 3-6 to upload the
start.opsfile to the appropriate directory inPixelator/PixelatorRealtime/startup/