Versions, Updates and Rollback

All parts of a CPM Lab have to run the same release: the central workstation, the vehicle controller on the muCars, the Lichtblick extensions and, ideally, the planners of the users. The releases are numbered <major>.<minor>.<patch>, e.g. 0.3.0, and listed with their changes in the CHANGELOG.rst of the lab workspace and on the GitLab release pages, see Releasing the CPM Lab. While the major version is 0, every minor release may change messages, so mixing releases is not supported.

Checking the Installed Versions

Part

Command

Central workstation (Debian packages)

apt policy ros-jazzy-cpm-lab

Desktop or simulation image

dpkg-query -W ros-jazzy-cpm-lab inside the container; the image repository is checked out at the tag

Source build

git describe --tags and git submodule status in the workspace

Vehicle controller on the lab PC

cat dist/VERSION in the vehicle workspace, or tar -xOzf /var/www/html/raspberry3/package.tar.gz package/VERSION

Vehicle controller on a car

cat /tmp/package/VERSION on the car (the package is downloaded to /tmp on every boot)

muCar OS

image/fleet.bash status, or cat /etc/mucar-release on the car

Lichtblick extensions

The version in the extension list of Lichtblick, or the tag of the lichtblick repository

VERSION of the vehicle controller lists the commit of the vehicle workspace and of each submodule; they must belong to the release of the central workstation.

Updating to a New Release

Update in a maintenance window, without experiments, and in this order:

  1. Read the changelog of the release, especially interface changes (Changing Messages and Services).

  2. Back up ~/cpm_lab (recordings, calibrations, your maps and IPS configurations), image/secrets.env of the vehicle workspace and the router configuration.

  3. Central workstation: sudo apt update && sudo apt install --only-upgrade 'ros-jazzy-cpm-lab*', or rebuild the desktop image at the new tag (Docker Images), or check out the tag in a source build and make build.

  4. Vehicle controller: in the vehicle workspace, git fetch && git checkout <version> && git submodule update --init --recursive, then ./docker/build.bash and ./docker/deploy.bash (see muCar). Restart the cars; they download the new package on boot.

  5. muCar OS, only if the release changed image/: make -C image os sysroot apt-repo and image/fleet.bash update.

  6. Lichtblick: check out the tag in the lichtblick repository and docker compose up -d --build, and install the new .foxe files in the Lichtblick desktop apps.

  7. Check: run a short simulation, then one muCar alone, as in Experiments with Real Vehicles.

  8. Tell the users to rebuild their planners against the new release.

Rolling Back

Vehicle controller. deploy.bash keeps every deployed package as package-<time>.tar.gz in /var/www/html/raspberry3. To return to a previous one, copy it over package.tar.gz, update the checksum and restart the cars:

cd /var/www/html/raspberry3
ls -t package-*.tar.gz                      # newest first
cp package-<time>.tar.gz package.tar.gz
sha256sum package.tar.gz > package.tar.gz.sha256

Alternatively, check out the previous tag in the vehicle workspace, build and deploy again.

Central workstation. The apt server only keeps the newest version of each package. Older packages are in the GitLab package registry of ros2-workspace-lab (Deploy → Package registry → cpm_lab → version). Download the .deb files of your distribution and architecture into an empty directory and install them over the newer ones:

sudo apt install --allow-downgrades ./ros-jazzy-*.deb

A source build at the previous tag is the other option and does not depend on the package registry.

muCar OS. The cars keep their packages; fleet.bash only upgrades. To roll back the OS, reflash the SD card with the previous image (dist/image/) or put the previous SD card back. Keep the image of every OS version you deployed.

Lichtblick. Check out the previous tag, rebuild with docker compose up -d --build and install the previous .foxe files from its GitLab release.

After a rollback, all parts must again run the same release.