Skip to content

Getting Started with Artefacts

pip install artefacts-cli

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 Python version 3.10 or above:

pip install artefacts-cli

Alternative Installation (pipx)

pipx allows for applications to be installed in an isolated environment, but still allowing them to be accessed from anywhere in your shell. This may be beneficial for those working with Python 3.12 due to its stricter environment isolation.

Artefacts can be installed with;

sudo apt install pipx
pipx ensurepath
pipx install artefacts-cli

ROS Users

We recommend using a virtual environment, but note that working with a virtual environment and ROS2 can be tricky, as when ROS is sourced, PYTHONPATH referring to ROS's own python package directory will be created, if it does not already exist.

You are thus likely to need to export the PYTHONPATH to include the virtual environment's site-packages directory, for example:

export PYTHONPATH=$PYTHONPATH:/home/[USER]/<myproject>/venv/lib/python3.10/site-packages

ROS2 Jazzy Users (Ubuntu 24 and Python 3.12)

If you're using Ubuntu 24 with ROS 2 Jazzy (which uses Python 3.12) and want to run Artefacts CLI (or indeed any python packages installed via pip or via apt install python3-xxx) alongside ROS packages, you may well encounter additional challenges due to Python 3.12's stricter environment isolation.

Whether you are installing artefacts in a virtual environment, or via pipx, we would strongly recommend adding the system Python packages directory to PYTHONPATH, in addition to your virtual environment (if using):

export PYTHONPATH=$PYTHONPATH:/usr/lib/python3/dist-packages

Usage reference

For CLI usage, refer to the CLI reference

For configuring the artefacts.yaml file, 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 and example projects

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

Example projects:

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.