Migration from mc_rtc 1.x to 2.0.0

This page will list the major changes between mc_rtc 1.x and the upcoming version 2.0.0 which will replace Tasks with TVM.

As an example, here is the migration commit for lipm_walking_controller. In general the migration should not be too difficult.

This is a living document that will be regularly updated as mc_rtc 2.0.0 evolves.

A note on YAML/JSON

In order to smooth the transition, we have decided to keep YAML/JSON files compatible compatible between the two versions. Some keys have been deprecated (e.g. surface becomes frame in most cases) but they will continue to work.

If you encounter a YAML/JSON file that is not loaded correctly in mc_rtc 2.0.0 this should be considered a bug, please report it!

C++ standard and version support

• mc_rtc 2.0.0 is built with C++17 (with GCC 7.4.0 as a baseline for compilation feature, this excludes some minor language features and notable STL components such as std::filesystem
• Ubuntu 16.04 will no longer be supported

API changes

All the changes mentioned here are API breaking changes for mc_rtc 2.0.0. In 100% of these cases they are easily replaced.

Surface/Body confusion and Frame introduction

In many instances in mc_rtc 1.x the distinction between a body and a surface was made where it is not strictly necessary. These usage are now joined into the simple Frame concept. A frame is defined by a robot, a parent body in this robot and a transformation relative to the parent body (each body has an associated frame with an identity transformation). This results in major changes wherever body and/or surfaces were involved.

Thus, the following tasks have been renamed:

• EndEffectorTask -> TransformTask
• SurfaceTransformTask -> TransformTask

The following API have been renamed:

• Robot::surfacePose(name) -> Robot::frame(name).position()
• Robot::surfaceWrench(name)/Robot::bodyWrench(name) -> Robot::frameWrench(name) or Robot::frame(name).wrench()
• Robot::surfaceHasForceSensor(name) -> Robot::frameHasForceSensor(name)
• ... in general, any surface-related function in Robot has been replaced with a frame equivalent

Note that surfaces still exist but they are much less prevalent (they are only used to create contacts).

Changes in MetaTask constructor

• Every constructor that took an mc_rbdyn::Robots instance and a robot index now accepts an mc_rbdyn::Robot instead
• Every constructor that took a body/surface name, an mc_rbdyn::Robots instance and a robot index now accepts an mc_rbdyn::Frame instead

Example

mc_rtc 1.x, creating a CoMTask and a SurfaceTransformTask

auto comT = std::make_shared<ComTask>(robots(), 0);
auto surfaceT = std::make_shared<SurfaceTransformTask>("LeftHand", robots(), 0);

mc_rtc 2.x, creating a CoMTask and a SurfaceTransformTask

auto comT = std::make_shared<ComTask>(robot());
auto surfaceT = std::make_shared<SurfaceTransformTask>(robot().frame("LeftHand"));

CoM

Robot::com() now returns an mc_rbdyn::CoM object that can be used to access all CoM related quantities. In particular this changes:

• Robot::com() -> Robot::com().com() returns the current CoM

gui() now returns a reference

In mc_rtc 1.x gui() returned a pointer to the GUI. In mc_rtc 2.x it always return a valid reference (the callbacks are simply never called when the GUI is disabled, similarly to the logger instance).

Example

mc_rtc 1.x

if(gui())
{
  gui()->addElement(...);
}

mc_rtc 2.x

gui().addElement(...);

Default members in mc_control::MCController

Default members have been renamed (their names end in _ now) and moved to protected members. You can bring them back into public members if needed via using

timeStep has been removed, use solver().dt() instead

Removed API

These API are removed without replacement.

Removed task without replacement

The following task is removed:

• RelativeEndEffectorTask, the implementation was sub-par and this could be re-introduced in the future if needed

Removed constraint

The following constraint is removed:

• ContactConstraint has become unnecessary (the type: contact constraint can still be "loaded" via YAML/JSON but it is a no-op)

The following helpers were removed:

• EqualityConstraintRobot/EqualityConstraintLambda/EqualityConstraintForce and the equivalent GenInequalityConstraint* and InequalityConstraint* because new constraints (and in general new tasks) are much easier to write in TVM. See TVM: How to create new TVM functions for a starting guide.

Writing TVM functions that use mc_rtc types

When writing new TVM functions you can depend on signals defined by mc_rtc in the robot to minimize computations that are done within the framework.

You are advised to look at TVM functions already implemented in mc_rtc under the mc_tvm library (i.e. include/mc_tvm and src/mc_tvm).

The following are particularly useful:

• Robot defines a number of signal for dynamic quantities
• mc_rbdyn::CoM defines a node with all CoM-related quantities (obtained via Robot::com())
• mc_rbdyn::Momentum defines a node with all momentum-related quantities (obtained via Robot::momentum())
• mc_rbdyn::Frame defines a node with all the frame quantities