fastcat

C++ EtherCAT Device Command & Control Library

Documentation

To learn more about fastcat, checkout the following documents:

• Fastcat Primer
• Complete list of Fastcat Device Configuration YAML Parameters
• 2021 Aeroconf paper submission Fastcat: An Open-Source Library for Composable EtherCAT Control Systems
• README for build details
• The API documentation

Prerequisites

Fastcat has been tested on Ubuntu 20.04, 22.04 and 24.04, though it should work on older versions of Ubuntu with minor revisions to these steps.

$ sudo apt install libyaml-cpp-dev libreadline-dev doxygen graphviz

The fcviz utility is configured as a uv script, so its Python dependencies do not need to be installed globally:

Install uv using Astral's official installer:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Installation options and other platforms are documented by Astral at https://docs.astral.sh/uv/getting-started/installation/.

$ uv run fcviz/fcviz.py example_configs/paper_examples/paper_faulter_config.yaml

If you do not want to use uv, check the inline dependency metadata at the top of fcviz/fcviz.py and install those packages in your preferred Python environment before running the script directly.

If you need to regenerate code with fcgen, install Ubuntu's python3-cogapp package. On some systems, you may need to enable the universe repository first:

$ sudo add-apt-repository universe
$ sudo apt update
$ sudo apt install python3-cogapp

Building

To build fastcat from source:

$ git clone git@github.com:nasa-jpl/fastcat.git
$ cd fastcat
$ mkdir build
$ cd build
$ cmake ..
$ make

Tests

The following commands will execute the unit tests:

$ cd build
$ cmake ..
$ make
$ make test
$ make memcheck  # note valgrind is required to perform memory checking

API Documentation

# Install dependencies for Ubuntu
$ sudo apt install doxygen graphviz
$ cd build
$ make doc

The output documentation is created in the directory doxygen_html and can be opened by any web browser from the root index.html webpage.

The repository also includes a GitHub Actions workflow that builds this doc target and publishes it to GitHub Pages on pushes to master. Once GitHub Pages is enabled for the repository with GitHub Actions as the source, the published site will be available at https://nasa-jpl.github.io/fastcat/.

Using fastcat in your Project

We recommend using the CMake FetchContent utility to acquire fastcat and its upstream dependencies.

include(FetchContent)
FetchContent_Declare(fastcat
    GIT_REPOSITORY git@github.com:nasa-jpl/fastcat.git
    GIT_TAG v0.13.13
    )
FetchContent_MakeAvailable(fastcat)

It is always recommend you specify your dependency to a tagged reldroppingease (GIT_TAG v0.13.13) so updates to master cannot break your build (NOT GIT_TAG master).

Semantic Versioning

fastcat uses Semantic versioning to help applications reason about the software as updates are continuously rolled out. Tailored to fastcat, the Semver rules are as follows:

• Major Versions will denote changes to the API or YAML Configuration parameters, which may break some user applications.
• Minor Versions will denote new features or driver additions that do not break user applications.
• Patch Versions will denote bug fixes or minor improvements and will not break user applications.

Violations of these rules will be considered errors and should be patched immediately. Please open an issue if you find a violation.