** This module is under constructions and installation instructions and integration tests will not work yet **

Cockpit ROS 2 Diagnostics

This is a Cockpit module that is intended to be installed alongside Cockpit and connects to the foxglove bridge

This module is built on the cockpit starter kit: https://github.com/cockpit-project/starter-kit and using modified code files from https://github.com/tier4/roslibjs-foxglove.

Installation instructions

This is installed and running automatically on Clearpath Robots without any manual installation required.

The following instructions should be completed on the computer that is to be monitored and managed using the cockpit interface. In most cases this will be the robot computer.

1. Install cockpit: https://cockpit-project.org/running.html#ubuntu

2. Add the Clearpath Robotics Package Server:

   wget https://packages.clearpathrobotics.com/public.key -O - | sudo apt-key add -
   sudo sh -c 'echo "deb https://packages.clearpathrobotics.com/stable/ubuntu $(lsb_release -cs) main" > /etc/apt/sources.list.d/clearpath-latest.list'
   sudo apt update

3. Install this module and the foxglove bridge

   sudo apt install cockpit-ros2-diagnostics ros-$ROS_DISTRO-foxglove-bridge

4. In order to open the UI on a remote computer and connect to the foxglove bridge, either this has to happen over an unsecured connection (http) or cockpit must be placed behind a reverse proxy. The currently supported option is to set cockpit up for an unsecure connection. Allow an unencrypted HTTP connection by creating the cockpit.conf file and set AllowUnencrypted=true in the WebService section.

   echo "[WebService]
   AllowUnencrypted=true" | sudo tee /etc/cockpit/cockpit.conf

Usage Instructions

1. If not using with a Clearpath Robot then you will need to start your foxglove bridge manually. It must be launched with the default port (8765):

   ros2 launch foxglove_bridge foxglove_bridge_launch.xml

2. Open a supported browser and go to http://<ip-address>:9090 but replace <ip-address> with the ip address or hostname of your robot computer. Remember to use the IP address for the network that over which you are connecting to the robot. In order for the websocket connection to work and successfully receive the ROS 2 topics, cockpit must be accessed over http. This is an unsecure connection but it is the simplest to configure. If a secure connection is required then cockpit must be setup behind a reverse proxy.

3. Go to the ROS 2 Diagnostics tab

Development and Source Instructions

Development dependencies

On Ubuntu:

sudo apt install gettext nodejs npm make

Getting and building the source

These commands check out the source and build it into the dist/ directory:

git clone https://github.com/clearpathrobotics/cockpit-ros2-diagnostics.git
cd cockpit-ros2-diagnostics
make

Installing

make install compiles and installs the package in /usr/local/share/cockpit/. The convenience targets srpm and rpm build the source and binary rpms, respectively. Both of these make use of the dist target, which is used to generate the distribution tarball. In production mode, source files are automatically minified and compressed. Set NODE_ENV=production if you want to duplicate this behavior.

For development, you usually want to run your module straight out of the git tree. To do that, run make devel-install, which links your checkout to the location were cockpit-bridge looks for packages. If you prefer to do this manually:

mkdir -p ~/.local/share/cockpit
ln -s `pwd`/dist ~/.local/share/cockpit/cockpit-ros2-diagnostics

After changing the code and running make again, reload the Cockpit page in your browser.

You can also use watch mode to automatically update the bundle on every code change with

./build.js -w

or

make watch

When developing against a virtual machine, watch mode can also automatically upload the code changes by setting the RSYNC environment variable to the remote hostname.

RSYNC=c make watch

When developing against a remote host as a normal user, RSYNC_DEVEL can be set to upload code changes to ~/.local/share/cockpit/ instead of /usr/local.

RSYNC_DEVEL=example.com make watch

To "uninstall" the locally installed version, run make devel-uninstall, or remove manually the symlink:

rm ~/.local/share/cockpit/cockpit-ros2-diagnostics

Running eslint

Cockpit Starter Kit uses ESLint to automatically check JavaScript/TypeScript code style in .js[x] and .ts[x] files.

eslint is executed as part of test/static-code, aka. make codecheck.

For developer convenience, the ESLint can be started explicitly by:

npm run eslint

Violations of some rules can be fixed automatically by:

npm run eslint:fix

Rules configuration can be found in the .eslintrc.json file.

Running stylelint

Cockpit uses Stylelint to automatically check CSS code style in .css and scss files.

styleint is executed as part of test/static-code, aka. make codecheck.

For developer convenience, the Stylelint can be started explicitly by:

npm run stylelint

Violations of some rules can be fixed automatically by:

npm run stylelint:fix

Rules configuration can be found in the .stylelintrc.json file.

Running tests locally

To run the tests locally you must install:

```bash
sudo apt install chromium-browser chromium-chromedriver
sudo snap install chomium
```

Run make check to build a package, install it into a standard Cockpit test VM (set to Ubuntu for this repo), and run the test/check-application integration test on it. This uses Cockpit's Chrome DevTools Protocol based browser tests, through a Python API abstraction. Note that this API is not guaranteed to be stable, so if you run into failures and don't want to adjust tests, consider checking out Cockpit's test/common from a tag instead of main (see the test/common target in Makefile).

After the test VM is prepared, you can manually run the test without rebuilding the VM, possibly with extra options for tracing and halting on test failures (for interactive debugging):

TEST_OS=centos-9-stream test/check-application -tvs

It is possible to setup the test environment without running the tests:

TEST_OS=centos-9-stream make prepare-check

You can also run the test against a different Cockpit image, for example:

TEST_OS=fedora-40 make check

Running tests in CI

These tests can be run in Cirrus CI, on their free Linux Containers environment which explicitly supports /dev/kvm. Please see Quick Start how to set up Cirrus CI for your project after forking from starter-kit.

The included .cirrus.yml runs the integration tests for two operating systems (Fedora and CentOS 8). Note that if/once your project grows bigger, or gets frequent changes, you may need to move to a paid account, or different infrastructure with more capacity.

Tests also run in Packit for all currently supported Fedora releases; see the packit.yaml control file. You need to enable Packit-as-a-service in your GitHub project to use this. To run the tests in the exact same way for upstream pull requests and for Fedora package update gating, the tests are wrapped in the FMF metadata format for using with the tmt test management tool. Note that Packit tests can not run their own virtual machine images, thus they only run @nondestructive tests.

Automated release of tarballs on Github

Once your cloned project is ready for a release, you should consider automating that. The intention is that the only manual step for releasing a project is to create a signed tag for the version number, which includes a summary of the noteworthy changes:

123

- this new feature
- fix bug #123

Pushing the release tag triggers the release.yml GitHub action workflow. This creates the official release tarball and publishes as upstream release to GitHub. The workflow is disabled by default -- to use it, edit the file as per the comment at the top, and rename it to just *.yml.

The Fedora and COPR releases are done with Packit, see the packit.yaml control file.

Automated maintenance

It is important to keep your NPM modules up to date, to keep up with security updates and bug fixes. This happens with dependabot, see configuration file.

Further reading

• The Starter Kit announcement blog post explains the rationale for this project.
• Cockpit Deployment and Developer documentation
• Make your project easily discoverable