Getting Started

Home -> Getting Started

This guide shows how to get started with the Compliant Joint Toolbox if you are already using MATLAB. If not, you may wish to check out the Compute Capsule on Code Ocean.

Obtain the Toolbox

If you have git installed on your machine, chose a directory, where you wish to keep the Compliant Joint Toolbox code. In that directory call:

git clone https://github.com/geez0x1/CompliantJointToolbox

If you do not have git installed on your machine, we recommend to get it. See e.g.: https://git-scm.com/downloads. Alternatively you can download the toolbox in a ZIP-file.

Set Up the Toolbox Path

Start MATLAB and change the working directory to the Compliant Joint Toolbox root directory. There you will find an m-file:

setCJTPaths.m

Run this script to set up the required paths.

The General Concept

The joint builder mostly works using the well-known factory design pattern, combined with taking advantage of the fact that we can create and instantiate new classes on the fly. This means it builds (almost) self-contained joint classes with the requested parameters, models, and nonlinear components. Built joint class files are placed in the build/ folder, and generated by the jointBuilder class, by first instantiating it:

    jb = jointBuilder;

and then calling the buildJoint method:

   jb.buildJoint(   'parameters_name', ...
                    'linear_model_name', ...
                    '{optional_nonlinear_model(s)}', ...
                    'optional_electrical_model', 
                    'My_joint_name');

which will construct a new joint class with name My_joint_name, parameters from params/parameters_name.m, reference a linear dynamics model model/linear/linear_model_name.m, use nonlinear models specified by a string (one) or a cell of strings (multiple), from model/nonlinear/, and use electrical dynamics model electricalDynamicsName from model/electrical/. The resulting file build/My_joint_name.m will contain your joint class definition.

Build Your First Joint Class

To create your first joints, follow the steps below. You will also find the code described here in the toolbox directory under examples/matlab/EX01_Generate_A_First_Joint.m:

%% Instantiate a jointBuilder
jb = jointBuilder;

%% Build joint model classes
% A model of a TREE Robotics Pomegranate actuator with 9 kNm/rad sensor stiffness Coulomb friction as well as
% electric dynamics including winding inductance and rigid gearbox.
jb.buildJoint(  'cjt_Pomegranate_160_9000', ...    % parameters
                'rigid_gearbox', ...               % linear dynamics
                {'coulomb', 'viscous_asym'},       % nonlinear dynamics
                'electric_dyn', ...                % electro-dynamics
                'My_Pomegranate');                 % class name

% add build directory to search path
addpath(jb.buildDir) 

%% Instantiate an object of the new class
aJoint = My_Pomegranate

Congratulations, you just instantiated the first Compliant Joint Toolbox joint class object! Now it is time to play around and see, what it has to offer. Maybe try to generate, the same model with a different name or alternate parameters. You will find different parameter sets in the params directory. Alternatively try different types of models (model directory) or get the state-space description of its linear dynamics by running mySys = joint.getStateSpace() and its transfer functions by running myTF = joint.getTF(). Feel free and enjoy to experiment with the toolbox.

Eventually, you may wish to clean up your hard disk and remove all generated files.

%% Next, we clean up
% The joint builder can delete all the files it has genereated through a single command. That helps you keep your hard
% disk clean.
jb.purge();

Learn More

A more advanced code example can be found in the m-file `Take_A_Tour.m' in the toolbox root directory. The Wiki holds more information on working with the Compliant Joint Toolbox and its features.