# Documentation

## Modeling Degrees of Freedom

### Warning

This content is specific to Simscape™ Multibody™ First Generation software. First-generation features are slated to be deprecated and should be avoided.

A Simscape Multibody joint represents the degrees of freedom (DoF) that one body (the follower) has relative to another body (the base). The base body can be a movable rigid body or a ground. Unlike a physical joint, a Simscape Multibody joint has no mass, although some joints have spatial extension (see Modeling Massless Connectors).

A Simscape Multibody joint does not necessarily imply a physical connection between two bodies. For example, a Simscape Multibody Six-DoF joint allows the follower, e.g., an airplane, unconstrained movement relative to the base, e.g., ground, and does not require that the follower ever come into contact with the base.

Simscape Multibody joints only add degrees of freedom to a machine, because the Body blocks carry no degrees of freedom. Contrast this with physical joints, which both add DoFs (with axes of motion) and remove DoFs (by connecting bodies). For more information, see Counting Model Degrees of Freedom.

The Simscape Multibody Joints library provides an extensive selection of blocks for modeling various types of joints. This section explains how to use these blocks.

### Note

A Simscape Multibody joint represents the relative degrees of freedom of one body relative to another body. Only if a joint is connected on one side to a ground and on the other to a body does the joint represent an absolute DoF of the body with respect to World.

### Modeling Joints

Modeling with Joint blocks requires an understanding of the following key concepts:

• Joint primitives

• Joint types

• Joint axes

• Joint directionality

• Assembly restrictions

#### Joint Primitives

Each Joint block bundles together one or more joint primitives that together specify the degrees of freedom that a follower body has relative to the base body. The following table summarizes the joint primitives found singly or multiply in Joint blocks.

Primitive TypeSymbolDegrees of Freedom
Prismatic`P`One degree of translational freedom along a prismatic axis
Revolute`R`One degree of rotational freedom about a revolute axis
Spherical`S`Three degrees of rotational freedom about a pivot point
Weld`W`Zero degrees of freedom

#### Joint Types

The blocks in the Simscape Multibody Joints library fall into the following categories:

• Primitive joints

Each of these blocks contains a single joint primitive. For example, the Revolute block contains a revolute joint primitive.

• Composite joints

These blocks contain combinations of joint primitives, enabling you to specify multiple rotational and translational degrees of freedom of one body relative to another. Some model idealized real joints, for example, the Gimbal and Bearing joints.

Others specify abstract combinations of degrees of freedom. For example, the Six-DoF block specifies unlimited motion of the follower relative to the base.

The Custom Joint allows you to create joints with any desired combination of rotational and translational degrees of freedom, in any order. The prefabricated composite Joints of the Joints library have the type and order of their primitives fixed. See Axis Order.

• Massless connectors

These blocks represent extended joints with spatially separated joint primitive axes, for example, a Revolute-Revolute Massless Connector.

• Disassembled joints

These blocks represent joints not assembled until simulation starts — for example, a Disassembled Prismatic.

#### Joint Axes

Joint blocks define one or more axes of translation or rotation along which or around which a follower block can move in relation to the base block. The axes of a Joint block are the axes defined by its component primitives:

• A prismatic primitive defines an axis of translation.

• A revolute primitive defines an axis of revolution.

• A spherical primitive defines a pivot point for axis-angle rotation.

For example, a Planar Joint block combines two prismatic axes and hence defines two axes of translation.

Axis Direction.  By default the axes of prismatic and revolute primitives point in the same direction as the z-axis of the World coordinate system (CS). A Joint block's dialog box allows you to point its prismatic and revolute axes in any other direction (see Directing Joint Axes).

Axis Order.  Composite Simscape Multibody Joints execute their motion one joint primitive at a time. A joint that defines more than one axis of motion also defines the order in which the follower body moves along each axis or about a pivot. The order in which the axes and/or pivot appear in the Joint block's dialog box is the order in which the follower body moves.

Different primitive execution orders are physically equivalent, unless the joint includes one spherical or three revolute primitives. Pure translations and pure two-dimensional rotations are independent of primitive ordering.

Axis Span.  The span of the primitive axes is the complete space spanned by their combination. For example, one primitive axis defines a line, and two primitive axes define a plane.

#### Joint Directionality

Directionality is a property of a joint that determines the dependence of the joint on the sign of forces or torques applied to it. A joint's directionality also determines the sign of signals output by sensors attached to the joint. Every Simscape Multibody joint in your model has a directionality. You must be able to determine the directionality of a joint in order to actuate it correctly and to interpret the output of sensors attached to it.

A joint's follower moves relative to the joint's base. The joint's directionality takes into account the joint type and the direction of the joint's axis, as follows.

Directionality of a Prismatic Joint.  If the joint is prismatic, a positive force applied to the joint moves the follower in the positive direction along the axis of translation. A sensor attached to the joint outputs a positive signal if the follower moves in a positive direction along the joint's axis of translation relative to the base.

Directionality of a Revolute Joint.  If the joint is revolute, a positive torque applied to the joint rotates the follower by a positive angle around the joint's axis of rotation, as determined by the right-hand rule. A sensor attached to the revolute joint outputs a positive signal if the follower rotates by a positive angle around the joint's axis of revolution, as determined by the right-hand rule.

Directionality of a Spherical Joint.  Spherical joint directionality means the positive sense of rotation of the three rotational DoFs. Pick a rotation axis, rotating using the right-hand rule from the base Body CS axes. Then rotate the follower Body about that axis in the right-handed sense.

Directionality and Ordering of Composite Joint Primitives.  Each joint primitive separately has its own directionality, based on the primitive's type and the direction of its axis of translation or rotation. In each case, the follower body of the composite joint moves along or around the joint primitive's axis relative to the base body.

The order of primitives in the composite Joint's dialog determines the spatial construction of the joint.

The first listed primitive is attached to the base, the second to the first, and so on, down to the follower, which is attached to the last primitive.

• Moving the first listed primitive moves the subsequent primitives in the list, including the follower, relative to the base.

• Moving any primitive moves the primitives below it in the list (but not those above it), as well as the follower.

• Moving the last listed primitive moves only the follower.

Changing the Directionality of a Joint.  You can change the directionality of a joint by either

• Reversing and reconnecting the Joint block to reverse the roles of the base and follower bodies.

• Reversing the sign (direction) of the joint axis.

#### Assembly Restrictions

Many joints impose one or more restrictions, called assembly restrictions, on the placement of the bodies that they join. The conjoined bodies must satisfy these restrictions at the beginning of simulation and thereafter within assembly tolerances that you can specify (see Controlling Machine Assembly). For example, the Body CSs attached to revolute and spherical joints must coincide within assembly tolerances; the Body CSs attached to a Prismatic joint must lie on the prismatic axis within assembly tolerances; the Body CSs attached to a Planar joint must be coplanar with Planar primitives, etc. Composite joints, e.g., the Six-DoF joint, impose assembly restrictions equal to the most restrictive of its joint primitives. See the block reference for each Joint for information on the assembly restrictions, if any, that it imposes.

Positioning bodies so that they satisfy a joint's assembly restrictions is called assembling the joint.

All Simscape Multibody Joints except blocks in the Disassembled Joints sublibrary require manual assembly. Manual assembly entails your setting the initial positions of conjoined bodies to valid locations (see Assembling Joints). The simulation assembles disassembled joints during the model initialization phase. It assumes that you have already assembled all other joints before the start of simulation. Hence joints that require manual assembly are called assembled joints. During model initialization and at each time step, the simulation also checks to ensure that your model's bodies satisfy all assembly restrictions. If any of your model bodies fails to satisfy assembly restrictions, the simulation stops and displays an error message.

### Creating a Joint

A joint must connect exactly two bodies. To create a joint between two bodies:

1. Select the Joint from the Simscape Multibody Joints library that best represents the degrees of freedom of the follower body relative to the base body.

2. Connect the base connector port of the Joint block (labeled B) to the Body CS origin on the base block that serves as the point of reference for specifying the degrees of freedom of the follower block.

3. Connect the follower connector port of the Joint block (labeled F) to the Body CS origin on the follower block that serves as the point of reference for specifying the degrees of freedom of the base block.

4. Specify the directions of the joint's axes (see Directing Joint Axes).

5. If you plan to attach Sensors or Actuators to the Joint, create an additional port for each Sensor and Actuator (see Creating Actuator and Sensor Ports on a Joint).

6. If the joint is an assembled joint, assemble the bodies joined by the joint (see Assembling Joints).

#### Directing Joint Axes

By default the prismatic and revolute axes of a joint point in the same direction as the z-axis of the World coordinate system. To change the direction of the axis of a joint primitive:

1. Open the joint's dialog box and select a reference coordinate system for specifying the axis direction from the coordinate system list associated with the axis primitive.

The options are the World coordinate system or the local coordinate systems of the base or follower attachment point. Choose the coordinate system that is most convenient.

2. Enter in the primitive's axis direction field a vector that points in the desired direction of the axis in the selected coordinate system.

#### Creating Actuator and Sensor Ports on a Joint

To create additional connector ports on a Joint for Actuators and Sensors, open the Joint's dialog box and set the Number of sensor/actuator ports to the number of Actuators and Sensors you plan to attach to the Joint.

Apply the setting by clicking or .

#### Assembling Joints

You must manually assemble all assembled joints in your model. Assembling a joint requires setting the initial positions of its attached base and follower Body CSs such that they satisfy the assembly restrictions imposed by the joint (see Assembly Restrictions). Consider, for example, the Model and Simulate a Closed-Loop Machine.

This model comprises three bars connected by revolute joints to each other and to two ground points. The model collocates the CS origins of the Body CS ports connected to each Joint, thereby satisfying the assembly restrictions imposed by the revolute joints.

Assembled Revolute Joint in the Four Bar Mechanism

### Modeling Massless Connectors

Massless connectors simplify the modeling of machines that use a relatively light body to connect two relatively massive bodies. For example, you could use a Body block to model such a connector. But the resulting equations of motion might be ill-conditioned, because that connecting body's mass is small, and the simulation can be slow or prone to failure. A massless connector also avoids global inconsistencies that can arise if you use a Constraint block to model the connector.

A massless connector consists of a pair of joints located a fixed distance apart. Think of a massless connector as a massless rod with a joint primitive affixed at each end.

The initial orientation and length of the massless connector are defined by a vector drawn from the base attachment point to the follower attachment point. During simulation, the orientation of the massless connector can change but not its length. In other words, the massless connector preserves the initial separation of the base and follower bodies during machine motion.

### Note

You cannot actuate or sense a massless connector.

The Simscape Multibody Joints/Massless Connectors sublibrary contains these Massless Connectors:

• Two revolute primitives (Revolute-Revolute)

• A revolute primitive and a spherical primitive (Revolute-Spherical)

• Two spherical primitives (Spherical-Spherical)

#### Creating a Massless Connector

To create a massless connector between two bodies:

1. Drag an instance of a Massless Connector block from the Massless Connectors sublibrary into your model and connect it to the base and follower blocks.

You can set the direction of the axes of revolute primitives. If necessary, point the axes of the connector's revolute joints in the direction required by the dynamics of the machine you are modeling.

2. Assemble the connector by setting the initial positions of the base and follower body attachment points to the initial positions required by your machine's structure.

During simulation, the massless connector maintains the initial separation between the bodies though not necessarily the initial relative orientation.

#### Massless Connector Example: Triple Pendulum

Consider a triple pendulum comprising massive upper and lower bodies and a middle body of negligible mass. The following model uses a Revolute-Revolute massless connector to model such a pendulum.

In this model, the joint axes of the Revolute-Revolute connector have their default orientation along the World z-axis. As a result, the lower arm (Body1) rotates parallel to the World's x-y plane.

#### Massless Connector Example: Four Bar Mechanism

The following model replaces one of the bars (Bar2) in the `mech_four_bar` model with a Revolute-Revolute massless connector.

This model changes the Body CS origins of Bar3 to the following values.

NameOrigin position vectorTranslated from origin of
`CG``[-0.027 -0.048 0]``CS1`
`CS1``[0.054 0.096 0]``CS2`
`CS2``[0 0 0]``ADJOINING` (Ground_2)

This creates a separation between Bar3 and Bar1 equal to the length of Bar2 in the original model.

Simulate both the original and the modified model. Notice that the massless connector version moves differently, because you eliminated the mass of Bar2 from the model. Notice also that the massless bar does not appear in the visualization of the modified model, but it is called out in this figure for clarity.

### Modeling Disassembled Joints

The Simscape Multibody Joints/Disassembled Joints sublibrary contains a set of joints automatically assembled at the start of simulation; that is, the simulation positions the joints such that they satisfy the assembly restrictions imposed by the type of joint, e.g., prismatic or revolute. Using these joints eliminates the need for you to assemble the joints yourself.

Disassembled joints differ from assembled joints in significant ways. An assembled joint primitive has only one axis of translation or revolution or one spherical pivot point. A disassembled prismatic or revolute primitive has two axes of translation or rotation, one for the base and one for the follower body. A disassembled spherical primitive similarly has two pivot points.

### Caution

Disassembled joints can appear only in closed loops. Each closed loop can contain at most one disassembled joint.

The dialog box for a disassembled joint allows you to specify the direction of each axis. During model assembly, the simulation determines a common axis of revolution or translation that satisfies model assembly restrictions, and aligns the base and follower axes along the common axis.

#### Controlling Automatic Assembly and the Assembled Configuration

If your machine contains Joint Initial Condition Actuator (JICA) blocks, the machine is moved from its home to its initial configuration by applying the initial condition information to the machine's joints first. Then any disassembled joints are assembled, leading to the assembled configuration.

During model assembly, the simulation might move bodies connected by assembled joints from their initial positions in order to assemble the disassembled joints. The Simscape Multibody solution to the assembly problem cannot be predicted beforehand, except in simple cases. If you do not want bodies to move during model assembly, use JICA blocks to specify the initial positions of bodies whose positions you want to remain fixed during the assembly process. The resulting assembly will satisfy the initial conditions specified by the JICA blocks.

#### Disassembled Joint Example: Four Bar Mechanism

This example creates and runs a model of a disassembled four bar machine.

Refer to the tutorial, Model and Simulate a Closed-Loop Machine, and the `mech_four_bar` example:

1. Disconnect the Joint Sensor1 block from the Revolute3 block.

2. Replace Revolute3 with a Disassembled Revolute block from the Joints/Disassembled Joints sublibrary.

3. Open the Disassembled Revolute dialog box and, under Axis of Action for both `Base` and `Follower` axes, enter `[0 0 1]`. Close the dialog.

4. Open the Bar2 dialog box and dislocate the joint by displacing Bar2's CS2 origin from Bar 3's CS1 origin.

Do this by entering a nonzero vector under Origin Position Vector [x y z] for CS2, then changing the Translated from Origin of pull-down entry to `ADJOINING`. CS1 on Bar3 is the Adjoining CS of CS2 of Bar2. Close the dialog.

5. To avoid circular CS referencing, you must check the Bar3 dialog entry for CS1 on Bar3. Be sure that CS1 on Bar3 does not reference CS2 on Bar2. Reference it instead to CS2 on Bar3, which adjoins Ground_2.

6. Rerun the model.

Note that the motion is different from the manually assembled case.