Webots Reference Manual release 6.0.0

	Thanks
1.	Introduction
2.	Node Chart
3.	Nodes and API Functions
4.	Motion Functions
5.	Prototypes
6.	Physics Plugin
7.	Fast2D Plugin
8.	MTN Functions
9.	Webots World Files

3.36 Servo

Derived from Solid.

Servo { SFString type "rotational" SFFloat maxVelocity 10 # (0,inf) SFFloat maxForce 10 # [0,inf) SFFloat controlP 10 # (0,inf) SFFloat acceleration -1 # -1 or (0,inf) SFFloat position 0 SFFloat minPosition 0 # (-inf,0] SFFloat maxPosition 0 # [0,inf) SFFloat minStop 0 # [-pi,0] SFFloat maxStop 0 # [0,pi] SFFloat springConstant 0 # [0,inf) SFFloat dampingConstant 0 # [0,inf) }

3.36.1 Description

A Servo node is used to add one (active or passive) degree of freedom (DOF) in a mechanical simulation. The DOF is created between the parent and child nodes (VRML hierarchy) of the servo and therefore allows moving the servo children with respect to the servo parent. The Servo can be of type rotational or linear. A rotational servo is used to simulate a rotating motion, like most electric motors and hinges. A linear servo is used to simulate a sliding motion, like linear motors, pistons, hydraulic/pneumatic cylinders, springs, or dampers.

Rotational servos units are expressed in radians while linear servos units are expressed in meters. See table 3.2:

Rotational	Linear
Position	rad (radians)	m (meters)
Velocity	rad/s (radians / second)	m/s (meters / second)
Acceleration	rad/s² (radians / second²)	m/s² (meters / second²)
Torque/Force	Nm (Newtons meters)	N (Newtons)

Table 3.2: Servo Units

3.36.2 Field Summary

The type field is a string which specifies the Servo type, and may be either "rotational" (default) or "linear".
The maxVelocity field specifies both the upper limit and the default value for the servo velocity. The velocity can be changed at run-time with the wb_servo_set_velocity() function. The value should always be positive (the default is 10).
The maxForce field specifies both the upper limit and the default value for the servo motor force. The motor force is the torque/force that is available to the motor to perform the requested motions. The wb_servo_set_motor_force() function can be used to change the motor force at run-time. The value of maxForce should always be zero or positive (the default is 10). A small maxForce value may result in a servo being unable to move to the target position because of its weight or other external forces.
The controlP field specifies the initial value of the P parameter, which is the proportional gain of the servo P-controller. A high P results in a large response to a small error, and therefore a more sensitive system. Note that by setting P too high, the system can become unstable. With a small P, more simulation steps are needed to reach the target position, but the system is more stable. The value of P can be changed at run-time with the wb_servo_set_control_p() function.
The acceleration field defines the default acceleration of the P-controller. A value of -1 (infinite) means that the acceleration is not limited by the P-controller. The acceleration can be changed at run-time with the wb_servo_set_acceleration() function.
The position field represents the current position of the Servo. For a "rotational" servo, position represents the current rotation angle in radians. For a "linear" servo, position represents the magnitude of the current translation in meters.
The minPosition and maxPosition fields specify soft limits for the target position. These fields are described in more detail in the section "Servo Limits," see below.
The minStop and maxStop fields specify the position of physical (or mechanical) stops. These fields are described in more detail in the section "Servo Limits," see below.
The springConstant and dampingConstant fields allow the addition of spring and/or damping behavior to the Servo. These fields are described in more detail in the section "Springs and Dampers," see below.

3.36.3 Initial Transformation and Position

The Servo node inherits the translation and rotation fields from the Transform node. These two fields represent the coordinate system transformation between the Servo parent and children. When the Servo is actuated, the values of these fields are automatically modified in order to reflect the current transformation.

In a "rotational" Servo, these fields have the following meaning: The translation field specifies the translation of the axis of rotation. The rotation field specifies the orientation of the axis of rotation. See figure 3.17.

Figure 3.17: Rotational servo

In a "linear" Servo, these fields have the following meaning: The translation field specifies the translation of the sliding axis. The rotation field specifies the orientation of the sliding axis. See figure 3.18.

Figure 3.18: Linear servo

The values of the translation and rotation fields specified in the .wbt file (before the simulation is run) define the initial transformation of the servo. In the initial transformation, the value of the position field is always zero. Then, target positions passed to wb_servo_set_position() are specified with respect to the initial zero-position. The values of the minPosition, maxPosition, minStop and maxStop fields are also defined with respect to the initial zero-position.

3.36.4 Position and Velocity Control

The standard way of operating a Servo is to control the position directly (position control). The user specifies a target position using the wb_servo_set_position() function, then the P-controller takes into account the desired velocity, acceleration and motor force in order to move the servo to the target position. See table 3.3.

In Webots, position control is carried out in three stages, as depicted in figure 3.19. The first stage is performed by the user-specified controller (1) that decides which position, velocity, acceleration and motor force must be used. The second stage is performed by the servo P-controller (2) that computes the current velocity of the servo Vc. Finally, the third stage (3) is carried out by the physics simulator (ODE joint motors).

Figure 3.19: Servo control

At each simulation step, the P-controller (2) recomputes the current velocity Vc according to following algorithm:

Vc = P * (Pt - Pc); if (abs(Vc) > Vd) Vc = sign(Vc) * Vd; if (A != -1) { a = (Vc - Vp) / ts; if (abs(a) > A) a = sign(a) * A; Vc = Vp + a * ts; }

where Vc is the current servo velocity in rad/s or m/s, P is the p-control parameter specified in controlP field or set with wb_servo_set_control_p(), Pt is the target position of the servo set by the function wb_servo_set_position(), Pc is the current servo position as reflected by the position field, Vd is the desired velocity as specified by the maxVelocity field (default) or set with wb_servo_set_velocity(), a is the acceleration required to reach Vc in one time step, Vp is the motor velocity of the previous time step, ts is the duration of the simulation time step as specified by the basicTimeStep field of the WorldInfo node (converted in seconds), and A is the acceleration of the servo motor such as specified by the acceleration field (default) or set with wb_servo_set_acceleration().

Instead of specifying a target position (position control), it is also possible to choose the servo velocity directly. In order to obtain a specific velocity, the user should set the desired velocity with wb_servo_set_velocity(), then call wb_servo_set_position() with WB_SERVO_INFINITY or -WB_SERVO_INFINITY as the parameter. This will initiate a continuous servo motion at the desired speed, while taking into account the specified acceleration and motor force.

position control	velocity control	force control
uses P-controller	yes	yes	no
...set_position()	desired position	+/-WB_SERVO_INFINITY	-
...set_velocity()	desired max velocity	desired velocity	ignored
...set_acceleration()	max acceleration	max acceleration	ignored
...set_motor_force()	max force	max force	max force
...set_force()	-	-	desired force

Table 3.3: Servo Control Summary

3.36.5 Force Control

The position/velocity control described above is performed by the Webots P-controller and ODE's joint motor implementation (see ODE documentation). As an alternative to this mechanism, Webots allows the user to directly specify the amount of torque/force that must be applied by a servo. This is achieved through the wb_servo_set_force() function. See below for a detailed description of this function.

3.36.6 Servo Limits

The position field is a scalar value that represents the current servo "rotational" or "linear" position. For a rotational servo, position represents the difference (in radians) between the initial and the current angle of its rotation field. For a linear servo, position represents the distance (in meters) between the servo's initial and current translation (translation field).

The minPosition and maxPosition fields define the soft limits of the servo. Soft limits specify the software boundaries beyond which the P-controller will not attempt to move. If the controller calls wb_servo_set_position() with a target position that exceeds the soft limits, the desired target position will be clipped in order to fit into the soft limit range. Since the initial position of the servo is always zero, minPosition must always be negative or zero, and maxPosition must always be positive or zero. When both minPosition and maxPosition are zero (the default), the soft limits are deactivated. Note that the soft limits can be overstepped when an external force which exceeds the motor force is applied to the servo. For example, it is possible that the weight of a robot exceeds the motor force that is required to hold it up.

The minStop and maxStop fields define the hard limits of the servo. Hard limits represent physical (or mechanical) bounds that cannot be overrun by any force. Hard limits can be used, for example, to simulate both end caps of a hydraulic or pneumatic piston or to restrict the range of rotation of a hinge. The value of minStop must be in the range [-pi, 0] and maxStop must be in the range [0, pi]. When both minStop and maxStop are zero (the default), the hard limits are deactivated. The servo hard limits use ODE joint stops (for more information see the ODE documentation on dParamLoStop and dParamHiStop).

Finally, note that when both soft and hard limits are activated, the range of the soft limits must be included in the range of the hard limits, such that minStop <= minValue and maxStop >= maxValue.

3.36.7 Springs and Dampers

The springConstant field specifies the value of the spring constant (or spring stiffness), usually denoted as K. The springConstant must be positive or zero. If springConstant is zero (the default), no spring torque/force will be applied to the servo. If the springConstant is greater than zero, then a spring force will be computed and applied to the servo in addition to the other forces (e.g. motor force, damping force, weight). The spring force is calculated according to Hooke's law: F = -K*x, where K is the springConstant and x is the current servo position as represented by the position field. Therefore, the spring force is computed so as to be proportional to the current servo position, and to move the servo back to its initial position. When designing a robot model that uses springs, it is important to remember that the spring's resting position for each servo will correspond to the initial position of the servo.

The dampingConstant field specifies the value of the servo damping constant. The value of dampingConstant must be positive or zero. If dampingConstant is zero (the default), no damping torque/force will be applied to the servo. If dampingConstant is greater than zero, a damping torque/force will be applied to the servo in addition to the other forces (e.g. motor force, spring force, weight). This damping torque/force is proportional to the effective servo velocity: F = -B*v, where B is the damping constant, and v = dx/dt is the effective servo velocity computed by the physics simulator.

When simulating spring and dampers it is usually necessary to turn off the motor force by calling wb_servo_set_motor_force(servo, 0), or by setting a zero default motor force in the maxForce field.

3.36.8 Force Combination

Altogether, three different forces can be applied to a servo: the motor force (set by the P-controller or by wb_servo_set_force()), the spring force and the damping force (see table 3.4). The forces are applied in parallel and can be switched on or off independently (by default the P-controller is on). At each simulation step the three forces are recomputed and added to the two bodies of each servo. In a "linear" servo the force vectors are aligned with the servo sliding axis and are applied to the servo parent and children with equal magnitude but in opposite directions. In a "rotational" servo, the torques are applied to the servo parent and children with equal magnitude but in opposite directions around the servo rotation axis.

Force

Default	Turned on when:	Turned off when:
Motor force	on	servo_set_position() or servo_set_force()	servo_set_motor_force(..., 0) or servo_set_force(..., 0) or maxForce == 0
Spring force	off	springConstant > 0	springConstant == 0
Damping force	off	dampingConstant > 0	dampingConstant == 0

Table 3.4: Servo Forces

3.36.9 Servo Functions

DESCRIPTION

The wb_servo_set_position() function gives a new target position that the P-controller will attempt to reach using the current velocity, acceleration and motor torque/force parameters. The requested motion will be carried out, provided that it is not blocked by soft or hard limits and not impeded by external forces or the servo's own spring and damping forces.

The special values WB_SERVO_INFINITY and -WB_SERVO_INFINITY can be passed as the second argument to the wb_servo_set_position() function in order to enable an endless rotational or linear motion. The current values for velocity, acceleration and motor torque/force are taken into account. The motion may be interrupted by a call to wb_servo_set_position() with a different argument or by a call to wb_servo_set_force(). With WB_SERVO_INFINITY or -WB_SERVO_INFINITY, a linear servo will initiate an endlessly increasing translation between its parent and child nodes.

The wb_servo_set_velocity() function specifies the velocity that servo should reach while moving to the target position. In other words, this means that the servo will accelerate (using the specified acceleration, see below) until the target velocity is reached. The velocity argument passed to this function cannot exceed the limit specified in the maxVelocity field.

The wb_servo_set_acceleration() function specifies the acceleration that the P-controller should use when trying to reach the specified velocity. Note that an infinite acceleration is obtained by passing -1 as the acc argument to this function.

The wb_servo_set_motor_force() function specifies the max torque/force that will be available to the motor to carry out the requested motion. The motor torque/force specified with this function cannot exceed the value specified in the maxForce field.

The wb_servo_set_control_p() function changes the value of the P parameter in the P-controller. P is a parameter used to compute the current servo velocity Vc from the current position Pc and target position Pt, such that Vc = P * (Pt - Pc). With a small P, a long time is needed to reach the target position, while too large a P can make the system unstable. The default value of P is specified by the controlP field of the corresponding Servo node.

Note: In the oriented-object APIs, the WB_SERVO_INFINITY constant is available as static double of the Servo class (Servo::INFINITY).

NAME

wb_servo_enable_position, wb_servo_disable_position, wb_servo_get_position - get the effective position of a servo

C SYNOPSIS

#include <webots/servo.h>

void servo_enable_position(WbDeviceTag servo, int ms);
void servo_disable_position(WbDeviceTag servo);
double servo_get_position(WbDeviceTag servo);

C++ SYNOPSIS

#include <webots/Servo.hpp>

void Servo::enablePosition(int ms);
void Servo::disablePosition();
double Servo::getPosition();

JAVA SYNOPSIS

import com.cyberbotics.webots.controller.Servo;

void Servo.enablePosition(int ms);
void Servo.disablePosition();
double Servo.getPosition();

PYTHON SYNOPSIS

from controller import Servo

none Servo.enablePosition(int ms)
none Servo.disablePosition()
float Servo.getPosition()

DESCRIPTION

The wb_servo_enable_position() function activates position measurements for the specified servo. A new position measurement will be performed each ms milliseconds; the result must be obtained with the wb_servo_get_position() function. The returned value corresponds to the most recent measurement of the servo position. The wb_servo_get_position() function measures the effective position of the servo which, under the effect of external forces, is usually different from the target position specified with wb_servo_set_position(). For a rotational servo, the returned value is expressed in radians, for a linear servo, the value is expressed in meters. The returned value is valid only if the corresponding measurement was previously enabled with wb_servo_enable_position().

The wb_servo_disable_position() function deactivates position measurements for the specified servo. After a call to wb_servo_disable_position(), wb_servo_get_position() will return undefined values.

NAME

wb_servo_enable_motor_force_feedback, wb_servo_get_motor_force_feedback, wb_servo_disable_motor_force_feedback - get the motor force currently used by a servo

C SYNOPSIS

#include <webots/servo.h>

void wb_servo_enable_motor_force_feedback(WbDeviceTag servo, int ms);
void wb_servo_disable_motor_force_feedback(WbDeviceTag servo);
double wb_servo_get_motor_force_feedback(WbDeviceTag servo);

C++ SYNOPSIS

#include <webots/Servo.hpp>

void Servo::enableMotorForceFeedback(int ms);
void Servo::disableMotorForceFeedback();
double Servo::getMotorForceFeedback();

JAVA SYNOPSIS

import com.cyberbotics.webots.controller.Servo;

void Servo.enableMotorForceFeedback(int ms);
void Servo.disableMotorForceFeedback();
double Servo.getMotorForceFeedback();

PYTHON SYNOPSIS

from controller import Servo

none Servo.enableMotorForceFeedback(int ms)
none Servo.disableMotorForceFeedback()
float Servo.getMotorForceFeedback()

DESCRIPTION

The wb_servo_enable_motor_force_feedback() function activates torque/force feedback measurements for the specified servo. A new measurement will be performed each ms milliseconds; the result must be retrieved with the wb_servo_get_motor_force_feedback() function.

The wb_servo_get_motor_force_feedback() function returns the most recent motor force measurement. This function measures the amount of motor force that is currently being used by the servo in order to achieve the desired motion or hold the current position. For a "rotational" servo, the returned value is a torque [N*m]; for a "linear" servo, the value is a force [N]. The returned value is an approximation computed by the physics engine, and therefore it may be inaccurate. The returned value normally does not exceed the available motor force specified with wb_servo_set_motor_force() (the default being the value of the maxForce field). Note that this function measures the current motor force exclusively, all other external or internal forces that may apply to the servo are ignored. In particular, wb_servo_get_motor_force_feedback() does not measure:

The spring and damping forces that apply when the springConstant or dampingConstant fields are non-zero.
The force specified with the wb_servo_set_force() function.
The constraint forces that restrict the servo motion to one degree of freedom (DOF). In other words, the forces applied outside of the servo DOF are ignored. Only the forces applied in the DOF are considered. For example, in a "linear" servo, a force applied at a right angle to the sliding axis is completely ignored. In a "rotational" servo, only the torque applied around the rotation axis is considered.

Note that this function applies only to physics-based simulation. Therefore, the physics and boundingObject fields of the Servo node must be defined for this function to work properly.

If wb_servo_get_motor_force_feedback() was not previously enabled, the return value is undefined.

NAME

wb_servo_set_force - direct force control

C SYNOPSIS

#include <webots/servo.h>

void wb_servo_set_force(WbDeviceTag servo, double force);

C++ SYNOPSIS

#include <webots/Servo.hpp>

void Servo::setForce(double force);

JAVA SYNOPSIS

import com.cyberbotics.webots.controller.Servo;

void Servo.setForce(double force);

PYTHON SYNOPSIS

from controller import Servo

none Servo.setForce(float force)

DESCRIPTION

As an alternative to the P-controller, the wb_servo_set_force() function allows the user to directly specify the amount of torque/force that must be applied by a servo. This function bypasses the P-controller and ODE joint motors; it adds the force to the physics simulation directly. This allows the user to design a custom controller, for example a PID controller. Note that when wb_servo_set_force() is invoked, this automatically resets the force previously added by the P-controller.

In a "rotational" servo, the force parameter specifies the amount of torque that will be applied around the servo rotation axis. In a "linear" servo, the parameter specifies the amount of force [N] that will be applied along the sliding axis. A positive torque/force will move the bodies in the positive direction, which corresponds to the direction of the servo when the position field increases. When invoking wb_servo_set_force(), the specified force parameter cannot exceed the current motor force of the servo (specified with wb_servo_set_motor_force() and defaulting to the value of the maxForce field).

Note that this function applies only to physics-based simulation. Therefore, the physics and boundingObject fields of the Servo node must be defined for this function to work properly.

It is also possible, for example, to use this function to implement springs or dampers with controllable properties. The example in projects/samples/howto/worlds/force_control.wbt demonstrates the usage of wb_servo_set_force() for creating a simple spring and damper system.

^ page top ^

E-mail to webmaster

Last updated: