# Telescoping Joint

Joint with one prismatic and one spherical joint primitive

## Library

Joints

## Description

This block represents a joint with one translational and three rotational degrees of freedom. One prismatic primitive provides the translational degree of freedom. One spherical primitive provides the three rotational degrees of freedom.

**Joint Degrees of Freedom**

The joint block represents motion between the base and follower frames as a sequence of time-varying transformations. Each joint primitive applies one transformation in this sequence. The transformation translates or rotates the follower frame with respect to the joint primitive base frame. For all but the first joint primitive, the base frame coincides with the follower frame of the previous joint primitive in the sequence.

At each time step during the simulation, the joint block applies the sequence of time-varying frame transformations in this order:

Rotation:

About an arbitrary 3-D axis resolved in the Spherical Primitive (S) base frame.

Translation:

Along the Z axis of the Z Prismatic Primitive (Pz) base frame. This frame is coincident with the Spherical Primitive (S) follower frame.

The figure shows the sequence in which the joint transformations occur at a given simulation time step. The resulting frame of each transformation serves as the base frame for the following transformation. Because 3-D rotation occurs as a single rotation about an arbitrary 3-D axis (as opposed to three separate rotations about the X, Y, Z axes), gimbal lock does not occur.

**Joint Transformation Sequence**

To specify the target of the initial state for a joint primitive, use the parameters under
**State Targets**. The targets are specified in the base frame. You can
also set the priority levels for the targets. If the joint is not able to satisfy all the
state targets, the priority level determines which targets to satisfy first and how closely
to satisfy them. For an example, see Guiding Assembly.

To model damping and spring behavior for a joint primitive, use the parameters under
**Internal Mechanics**. Specify the **Damping
Coefficient** parameter to model energy dissipation and the **Spring
Stiffness** parameter to model energy storage. Joint springs attempt to
displace the joint primitive from its equilibrium position. Joint dampers act as energy
dissipation elements. The springs and dampers are strictly linear.

To specify the limits of a joint primitive, use the parameters under
**Limits**. The lower and upper bounds define the width of the free
region. The block applies a force to accelerate the joint position back to the free region
when the position exceeds the bounds. The block uses a smoothed spring-damper method to
compute the force. See the Description section of the
Spatial Contact
Force block for more information about the smoothed spring-damper
method.

The **Force**, **Torque**, and **Motion**
parameters in the **Actuation** section govern the motion of a joint
primitive during simulation. For more information, see Specifying Joint Actuation Inputs.
Additionally, the joint block has ports that output sensing data, such as position,
velocity, acceleration, force, and torque that you can use to perform analytical tasks on a
model. For more information, see Sensing and Force and Torque Sensing.

## Parameters

### Spherical Primitive: State Targets

Specify the desired initial states of the spherical joint primitive and their relative priority levels. States that you can target include position and velocity. Use the priority level to help the assembly algorithm decide which of the state targets in a model to more precisely satisfy should conflicts between them arise.

Even in the absence of state target conflicts, the true initial states may differ from
those specified here. Such discrepancies can occur due to kinematic constraints arising from
other parts of the model. If a state target cannot be satisfied precisely, it is satisfied
approximately. Discrepancies are noted in Simscape Variable Viewer (in the
**Apps** gallery, click **Simscape Variable
Viewer**).

**Specify Position Target**Check to specify the desired rotation of the follower frame relative to the base frame at the start of simulation.

**Priority**Select state target priority. This is the importance level assigned to the state target. If all state targets cannot be simultaneously satisfied, the priority level determines which targets to satisfy first and how closely to satisfy them. This option applies to both position and velocity state targets.

Priority Level Description `High (desired)`

Satisfy state target precisely `Low (approximate)`

Satisfy state target approximately **Note**During assembly, high-priority targets behave as exact guides. Low-priority targets behave as rough guides.

**Value**Select a method to specify the joint primitive state target.

Method Description `None`

Constrain the base and follower frames to share the same orientation. `Aligned Axes`

Set frame rotation by aligning two follower frame axes with two base frame axes. `Standard Axis`

Specify frame rotation as an angle about a standard axis ( *x*,*y*, or*z*).`Arbitrary Axis`

Specify frame rotation as an angle about a general [ *x*,*y*,*z*] axis.`Rotation Sequence`

Specify frame rotation as a sequence of three elementary rotations. `Rotation Matrix`

Specify frame rotation as a right-handed orthogonal rotation matrix. `Quaternion`

Specify frame rotation using a unit quaternion vector.

`Aligned Axes`

Select two pairs of base-follower frame axes.

Parameter Description **Pair 1**First pair of base-follower frame axes to align. **Pair 2**Second pair of base-follower frame axes to align. Axis choices depend on **Pair 1**axis selections.`Standard Axis`

Select a standard rotation axis, resolved in the base frame, and specify the follower frame rotation angle.

Parameter Description **Axis**Standard rotation axis (X, Y, or Z) resolved in the base frame. **Angle**Follower frame rotation angle about the rotation axis with respect to the base frame. `Arbitrary Axis`

Select a general 3-D rotation axis, resolved in the base frame, and specify the follower frame rotation angle.

Parameter Description **Axis**General rotation axis [X Y Z] resolved in the base frame. **Angle**Follower frame rotation angle about the rotation axis with respect to the base frame. `Rotation Sequence`

Specify a sequence of three elementary rotations about the selected permutation of x, y, and z axes. These rotation sequences are also known as Euler and Tait-Bryan sequences. The rotations are those of the follower frame relative to the frame selected in the

**Rotate About**parameter.If you set the

**Rotate About**parameter to`Follower Frame`

, the follower frame rotates about its own axes. These axes change orientation with each successive rotation. If you set the**Rotate About**parameter to`Base Frame`

, the follower frame rotates about the fixed base frame axes.Parameter Description **Rotation About**Frame whose axes to rotate the follower frame about. **Sequence**Sequence of axes about which to apply the elementary rotations. **Angles**Three-element vector with elementary rotation angles about the axes specified in the **Sequence**parameter.`Rotation Matrix`

Specify the 3×3 transformation matrix of a proper rotation between the base and follower frames. The matrix must be orthogonal and have determinant 1. The default matrix is

`[1 0 0; 0 1 0; 0 0 1]`

.`Quaternion`

Use a unit quaternion vector to specify the rotation of the follower frame with respect to the base frame. The default value is

`[1 0 0 0]`

. See Rotational Measurements for more information about the quaternion.

**Specify Velocity Target**Check to specify the desired rotational velocity of the follower frame relative to the base frame at the start of simulation.

**Value**Enter the relative rotational velocity of the follower frame against the base frame, as projected on the axes of the selected

**Resolution Frame**(by default`Follower`

). This parameter requires a three-element vector with the [*x**y**z*] components of the resolved relative velocity.**Resolution Frame**Select the frame in which to resolve the components of the velocity target. The resolution frame is not a measurement frame—the specified velocity is always that of the follower frame relative to the base frame. The resolution frame merely provides an alternate set of axes with respect to which to interpret the relative velocity components. The default setting is

`Follower`

.

### Spherical Primitive: Internal Mechanics

Specify the spherical primitive internal mechanics. This includes
linear spring and damping forces, accounting for energy storage and
dissipation, respectively. To ignore internal mechanics, keep spring
stiffness and damping coefficient values at the default value of `0`

.

**Equilibrium Position**Select a method to specify the spring equilibrium position. The equilibrium position is the rotation angle between base and follower port frames at which the spring torque is zero.

Method Description `None`

Constrain the base and follower frames to share the same orientation. `Aligned Axes`

Set frame rotation by aligning two follower frame axes with two base frame axes. `Standard Axis`

Specify frame rotation as an angle about a standard axis ( *x*,*y*, or*z*).`Arbitrary Axis`

Specify frame rotation as an angle about a general [ *x*,*y*,*z*] axis.`Rotation Sequence`

Specify frame rotation as a sequence of three elementary rotations. `Rotation Matrix`

Specify frame rotation as a right-handed orthogonal rotation matrix. `Quaternion`

Specify frame rotation using a unit quaternion vector.

`Aligned Axes`

Select two pairs of base-follower frame axes.

Parameter Description **Pair 1**First pair of base-follower frame axes to align. **Pair 2**Second pair of base-follower frame axes to align. Axis choices depend on **Pair 1**axis selections.`Standard Axis`

Select a standard rotation axis, resolved in the base frame, and specify the follower frame rotation angle.

Parameter Description **Axis**Standard rotation axis (X, Y, or Z) resolved in the base frame. **Angle**Follower frame rotation angle about the rotation axis with respect to the base frame. `Arbitrary Axis`

Select a general 3-D rotation axis, resolved in the base frame, and specify the follower frame rotation angle.

Parameter Description **Axis**General rotation axis [X Y Z] resolved in the base frame. **Angle**Follower frame rotation angle about the rotation axis with respect to the base frame. `Rotation Sequence`

Specify a sequence of three elementary rotations about the selected permutation of x, y, and z axes. These rotation sequences are also known as Euler and Tait-Bryan sequences. The rotations are those of the follower frame relative to the frame selected in the

**Rotate About**parameter.If you set the

**Rotate About**parameter to`Follower Frame`

, the follower frame rotates about its own axes. These axes change orientation with each successive rotation. If you set the**Rotate About**parameter to`Base Frame`

, the follower frame rotates about the fixed base frame axes.Parameter Description **Rotation About**Frame whose axes to rotate the follower frame about. **Sequence**Sequence of axes about which to apply the elementary rotations. **Angles**Three-element vector with elementary rotation angles about the axes specified in the **Sequence**parameter.`Rotation Matrix`

Specify the 3×3 transformation matrix of a proper rotation between the base and follower frames. The matrix must be orthogonal and have determinant 1. The default matrix is

`[1 0 0; 0 1 0; 0 0 1]`

.`Quaternion`

Use a unit quaternion vector to specify the rotation of the follower frame with respect to the base frame. The default value is

`[1 0 0 0]`

. See Rotational Measurements for more information about the quaternion.

**Spring Stiffness**Enter the linear spring constant. This is the torque required to displace the joint primitive by a unit angle. The term linear refers to the mathematical form of the spring equation. The default is

`0`

. Select a physical unit. The default is`N*m/deg`

.**Damping Coefficient**Enter the linear damping coefficient. This is the torque required to maintain a constant joint primitive angular velocity between base and follower frames. The default is

`0`

. Select a physical unit. The default is`N*m/(deg/s)`

.

### Spherical Primitive: Limits

Limit the range of motion of the joint primitive. Joint limits use spring-dampers to resist travel past the bounds of the range. A joint primitive can have a lower bound, an upper bound, both, or, in the default state, neither. The stiffer the spring, the harder the stop, or bounce, if oscillations arise. The stronger the damper, the larger the viscous losses that gradually lessen contact oscillations or, in overdamped primitives, keep them from forming altogether.

**Specify Lower Limit**Select to add a lower bound to the range of motion of the joint primitive.

**Specify Upper Limit**Select to add an upper bound to the range of motion of the joint primitive.

**Value**Location past which to resist joint travel. The location is the offset from base to follower, as measured in the base frame, at which contact begins. It is a distance along an axis in prismatic primitives, an angle about an axis in revolute primitives, and an angle between two axes in spherical primitives.

**Spring Stiffness**Resistance of the contact spring to displacement past the joint limit. The spring is linear and its stiffness is constant. The larger the value, the harder the stop. The proportion of spring to damper forces determines whether the stop is underdamped and prone to oscillations on contact.

**Damping Coefficient**Resistance of the contact damper to motion past the joint limit. The damper is linear and its coefficient is constant. The larger the value, the greater the viscous losses that gradually lessen contact oscillations, if any arise. The proportion of spring to damper forces determines whether the stop is underdamped and prone to oscillations on contact.

**Transition Region**Region over which to raise the spring-damper force to its full value. The region is a distance along an axis in prismatic primitives, an angle about an axis in revolute primitives, and an angle between two axes in spherical primitives.

The smaller the region, the sharper the onset of contact and the smaller the time-step required of the solver. In the trade-off between simulation accuracy and simulation speed, reducing the transition region improves accuracy while expanding it improves speed.

### Spherical Primitive: Actuation

Specify actuation options for the spherical joint primitive.
Actuation modes include **Torque** only. Selecting
a torque input adds the corresponding physical signal port to the
block. Use this port to specify the actuation torque signal.

**Torque**Select a source for the actuation torque. The default setting is

`None`

.Actuation Torque Setting Description `None`

Apply no actuation torque. `Provided by Input`

Apply an actuation torque based on a physical signal. The signal specifies the torque acting on the follower frame with respect to the base frame. An equal and opposite torque acts on the base frame. Selecting this option exposes additional parameters. **Torque (X), Torque (Y), Torque (Z)**Select in order to actuate the spherical joint primitive about each standard Cartesian axis (X, Y, Z) separately. The block exposes the corresponding physical signal ports. Use these ports to specify the actuation torque signals. The signals must be scalar values.

**Torque (XYZ)**Select in order to actuate the spherical joint primitive about an arbitrary axis [X Y Z]. The block exposes the corresponding physical signal port. Use this port to specify the actuation torque signal. The signal must be a 3-D vector.

**Frame**Select the frame to resolve the actuation torque signal in. The axes of this frame establish the directions of the X, Y, and Z torque components. The default setting is

`Base`

.

### Spherical Primitive: Sensing

Select the motion variables to sense in the spherical joint primitive. The block adds the corresponding physical signal ports. Use these ports to output the numerical values of the motion variables.

The block measures each motion variable for the follower frame
with respect to the base frame. It resolves that variable in the resolution
frame that you select from the **Frame** drop-down
list.

Motion Variables | Description |
---|---|

Position | Quaternion describing follower frame rotation with respect to base frame. The quaternion coefficients are $$\left[\mathrm{cos}\left(\frac{\theta}{2}\right),{n}_{x}\mathrm{sin}\left(\frac{\theta}{2}\right),{n}_{y}\mathrm{sin}\left(\frac{\theta}{2}\right),{n}_{z}\mathrm{sin}\left(\frac{\theta}{2}\right)\right]$$. The measurement is the same in all measurement frames. |

Velocity (X), Velocity (Y), Velocity
(Z) | Angular velocity components about X, Y, and Z axes. |

Velocity | 3–D angular velocity vector with components about X, Y, and Z axes. |

Acceleration (X), Acceleration
(Y), Acceleration (Z) | Angular acceleration components about X, Y, and Z axes. |

Acceleration | 3–D angular acceleration vector with components about X, Y, and Z axes. |

**Frame**Select the frame to resolve the measurement in. The axes of this frame establish the directions of X, Y, and Z vector components. The default setting is

`Base`

.

### Prismatic Primitive: State Targets

Specify the prismatic primitive state targets and their priority levels. A state target is the desired value for one of the joint state parameters—position and velocity. The priority level is the relative importance of a state target. It determines how precisely the target must be met. Use the Model Report tool in Mechanics Explorer to check the assembly status for each joint state target.

**Specify Position Target**Select this option to specify the desired joint primitive position at time zero. This is the relative position, measured along the joint primitive axis, of the follower frame origin with respect to the base frame origin. The specified target is resolved in the base frame. Selecting this option exposes priority and value fields.

**Specify Velocity Target**Select this option to specify the desired joint primitive velocity at time zero. This is the relative velocity, measured along the joint primitive axis, of the follower frame origin with respect to the base frame origin. It is resolved in the base frame. Selecting this option exposes priority and value fields.

**Priority**Select state target priority. This is the importance level assigned to the state target. If all state targets cannot be simultaneously satisfied, the priority level determines which targets to satisfy first and how closely to satisfy them. This option applies to both position and velocity state targets.

Priority Level Description `High (desired)`

Satisfy state target precisely `Low (approximate)`

Satisfy state target approximately **Note**During assembly, high-priority targets behave as exact guides. Low-priority targets behave as rough guides.

**Value**Enter the state target numerical value. The default is

`0`

. Select or enter a physical unit. The default is`m`

for position and`m/s`

for velocity.

### Prismatic Primitive: Internal Mechanics

Specify the prismatic primitive internal mechanics. Internal
mechanics include linear spring forces, accounting for energy storage,
and damping forces, accounting for energy dissipation. You can ignore
internal mechanics by keeping spring stiffness and damping coefficient
values at `0`

.

**Equilibrium Position**Enter the spring equilibrium position. This is the distance between base and follower frame origins at which the spring force is zero. The default value is

`0`

. Select or enter a physical unit. The default is`m`

.**Spring Stiffness**Enter the linear spring constant. This is the force required to displace the joint primitive by a unit distance. The default is

`0`

. Select or enter a physical unit. The default is`N/m`

.**Damping Coefficient**Enter the linear damping coefficient. This is the force required to maintain a constant joint primitive velocity between base and follower frames. The default is

`0`

. Select or enter a physical unit. The default is`N/(m/s)`

.

### Prismatic Primitive: Limits

Limit the range of motion of the joint primitive. Joint limits use spring-dampers to resist travel past the bounds of the range. A joint primitive can have a lower bound, an upper bound, both, or, in the default state, neither. The stiffer the spring, the harder the stop, or bounce, if oscillations arise. The stronger the damper, the larger the viscous losses that gradually lessen contact oscillations or, in overdamped primitives, keep them from forming altogether.

**Specify Lower Limit**Select to add a lower bound to the range of motion of the joint primitive.

**Specify Upper Limit**Select to add an upper bound to the range of motion of the joint primitive.

**Value**Location past which to resist joint travel. The location is the offset from base to follower, as measured in the base frame, at which contact begins. It is a distance along an axis in prismatic primitives, an angle about an axis in revolute primitives, and an angle between two axes in spherical primitives.

**Spring Stiffness**Resistance of the contact spring to displacement past the joint limit. The spring is linear and its stiffness is constant. The larger the value, the harder the stop. The proportion of spring to damper forces determines whether the stop is underdamped and prone to oscillations on contact.

**Damping Coefficient**Resistance of the contact damper to motion past the joint limit. The damper is linear and its coefficient is constant. The larger the value, the greater the viscous losses that gradually lessen contact oscillations, if any arise. The proportion of spring to damper forces determines whether the stop is underdamped and prone to oscillations on contact.

**Transition Region**Region over which to raise the spring-damper force to its full value. The region is a distance along an axis in prismatic primitives, an angle about an axis in revolute primitives, and an angle between two axes in spherical primitives.

The smaller the region, the sharper the onset of contact and the smaller the time-step required of the solver. In the trade-off between simulation accuracy and simulation speed, reducing the transition region improves accuracy while expanding it improves speed.

### Prismatic Primitive: Actuation

Specify actuation options for the prismatic joint primitive.
Actuation modes include **Force** and **Motion**.
Selecting `Provided by Input`

from the drop-down
list for an actuation mode adds the corresponding physical signal
port to the block. Use this port to specify the input signal. Actuation
signals are resolved in the base frame.

**Force**Select an actuation force setting. The default setting is

`None`

.Actuation Force Setting Description `None`

No actuation force. `Provided by Input`

Actuation force from physical signal input. The signal provides the force acting on the follower frame with respect to the base frame along the joint primitive axis. An equal and opposite force acts on the base frame. `Automatically computed`

Actuation force from automatic calculation. Simscape™ Multibody™ computes and applies the actuation force based on model dynamics. **Motion**Select an actuation motion setting. The default setting is

`Automatically Computed`

.Actuation Motion Setting Description `Provided by Input`

Joint primitive motion from physical signal input. The signal provides the desired trajectory of the follower frame with respect to the base frame along the joint primitive axis. `Automatically computed`

Joint primitive motion from automatic calculation. Simscape Multibody computes and applies the joint primitive motion based on model dynamics.

### Prismatic Primitive: Sensing

Select the variables to sense in the prismatic joint primitive. Selecting a variable exposes a physical signal port that outputs the measured quantity as a function of time. Each quantity is measured for the follower frame with respect to the base frame. It is resolved in the base frame. You can use the measurement signals for analysis or as input in a control system.

**Position**Select this option to sense the relative position of the follower frame origin with respect to the base frame origin along the joint primitive axis.

**Velocity**Select this option to sense the relative velocity of the follower frame origin with respect to the base frame origin along the joint primitive axis.

**Acceleration**Select this option to sense the relative acceleration of the follower frame origin with respect to the base frame origin along the joint primitive axis.

**Actuator Force**Select this option to sense the actuation force acting on the follower frame with respect to the base frame along the joint primitive axis.

### Mode Configuration

Specify the mode of the joint. The joint mode can be normal or disengaged throughout the simulation, or you can provide an input signal to change the mode during the simulation.

- Mode
Select one of the following options to specify the mode of the joint. The default setting is

`Normal`

.Method Description `Normal`

The joint behaves normally throughout the simulation. `Disengaged`

The joint is disengaged throughout the simulation. `Provided by Input`

This option exposes the **mode**port that you can connect to an input signal to change the joint mode during the simulation. The joint mode is normal when the input signal is`0`

and disengaged when the input signal is`-1`

. The joint mode can be changed many times during the simulation.

### Composite Force/Torque Sensing

Select the composite forces and torques to sense. Their measurements encompass all joint primitives and are specific to none. They come in two kinds: constraint and total.

Constraint measurements give the resistance against motion on the locked axes of the joint. In prismatic joints, for instance, which forbid translation on the xy plane, that resistance balances all perturbations in the x and y directions. Total measurements give the sum over all forces and torques due to actuation inputs, internal springs and dampers, joint position limits, and the kinematic constraints that limit the degrees of freedom of the joint.

**Direction**Vector to sense from the action-reaction pair between the base and follower frames. The pair arises from Newton's third law of motion which, for a joint block, requires that a force or torque on the follower frame accompany an equal and opposite force or torque on the base frame. Indicate whether to sense that exerted by the base frame on the follower frame or that exerted by the follower frame on the base frame.

**Resolution Frame**Frame on which to resolve the vector components of a measurement. Frames with different orientations give different vector components for the same measurement. Indicate whether to get those components from the axes of the base frame or from the axes of the follower frame. The choice matters only in joints with rotational degrees of freedom.

**Constraint Force**Dynamic variable to measure. Constraint forces counter translation on the locked axes of the joint while allowing it on the free axes of its primitives. Select to output the constraint force vector through port

**fc**.**Constraint Torque**Dynamic variable to measure. Constraint torques counter rotation on the locked axes of the joint while allowing it on the free axes of its primitives. Select to output the constraint torque vector through port

**tc**.**Total Force**Dynamic variable to measure. The total force is a sum across all joint primitives over all sources—actuation inputs, internal springs and dampers, joint position limits, and kinematic constraints. Select to output the total force vector through port

**ft**.**Total Torque**Dynamic variable to measure. The total torque is a sum across all joint primitives over all sources—actuation inputs, internal springs and dampers, joint position limits, and kinematic constraints. Select to output the total torque vector through port

**tt**.

## Ports

This block has two frame ports. It also has optional physical signal ports for specifying actuation inputs and sensing dynamical variables such as forces, torques, and motion. You expose an optional port by selecting the sensing check box corresponding to that port.

### Frame Ports

B — Base frame

F — Follower frame

### Actuation Ports

The prismatic joint primitive provides the following actuation ports:

fz — Actuation force of the Z prismatic joint primitive

pz — Desired trajectory of the Z prismatic joint primitive

The spherical joint primitive provides the following actuation ports:

t — Actuation torque vector [

*tx*,*ty*,*tz*] acting on the spherical joint primitivetx, ty, tz — X, Y, and Z components of the actuation torque acting on the spherical joint primitive

### Sensing Ports

The prismatic primitive provides the following sensing ports:

pz — Position of the Z prismatic joint primitive

vz — Velocity of the Z prismatic joint primitive

az — Acceleration of the Z prismatic joint primitive

fz — Actuation force acting on the Z prismatic joint primitive

fllz — Force due to contact with the lower limit of the Z prismatic joint primitive

fulz — Force due to contact with the upper limit of the Z prismatic joint primitive

The spherical primitive provides the following sensing ports:

Q — Orientation of the spherical joint primitive in quaternion form

wx, wy, wz — X, Y, and Z angular velocity components of the spherical joint primitive

w — Angular velocity [

*wx*,*wy*,*wz*] of the spherical joint primitivebx, by, bz — X, Y, and Z angular acceleration components of the spherical joint primitive

b — Angular acceleration [

*bx*,*by*,*bz*] of the spherical joint primitivetll — Torque due to contact with the lower limit of the spherical joint primitive, given as the signed magnitude of the torque vector

tul — Torque due to contact with the upper limit of the spherical joint primitive, given as the signed magnitude of the torque vector

The following sensing ports provide the composite forces and torques acting on the joint:

fc — Constraint force

tc — Constraint torque

ft — Total force

tt — Total torque

### Mode Port

Mode configuration provides the following port:

mode — Value of the mode of the joint. If the input is equal to

`0`

, the joint behaves normally. If the input is equal to`-1`

, the joint behaves as disengaged.

## Extended Capabilities

## Version History

**Introduced in R2012a**