Skip to content

Getting Started with Artefacts

Creating an account

You will need an email address or a Google account. Then go to https://app.artefacts.com and proceed.

The Artefacts client is relatively lightweight and so any hardware requirements will be based on the simulation that is being attempted, rather than Artefacts itself.

We support what ROS2 supports, i.e:

  • Ubuntu 22.04 (Recommended for ROS2 Humble projects)
  • Ubuntu 24.04 (Recommended for ROS2 Jazzy projects)

On MacOS or Windows, we recommend using a virtual machine with Ubuntu 22.04 or 24.04.

Our general recommendations for running simulations are:

  • minimum of 8G of RAM (depending on the complexity of the simulation)
  • minimum of 4 CPU cores (depending on the complexity of the simulation and your robotic application)
  • at least 20G of free disk space (to work with simulation assets, rosbags...)

CLI installation

Using python3 (version 3.9 or above):

pip install artefacts-cli

We recommend using a virtual environment, but note that working with a virtual environment and ROS2 can be tricky. You are likely to need to export the PYTHONPATH to include the virtual environment's site-packages directory, for example.

export PYTHONPATH=$PYTHONPATH:/home/[USER]/.pyenv/versions/[VENV-NAME]/lib/python3.10/site-packages

Usage reference

For CLI usage, refer to the CLI reference

For the YAML configuration, refer to the Configuration file syntax

deprecated For reference about naming and file placement when writing tests with ROS1, see Writing ROS1 Tests and ROS1 Configuration Syntax

Tutorials

For writing tests with ROS2, see the ros-2-simulation-workflows repository

deprecated For writing tests with ROS1, see Automating Regression tests and Tuning Parameters with Artefacts

General Troubleshooting

We have a general troubleshooting section for working (specifically with testing) with ROS that we hope you may find useful while you are developing.