Skip to content

Servo

RoboBoard X3 Servo motor ports

Servo wire colors:
• Orange = Signal (PWM)
• Red = VCC
• Brown = GND

Motor control interface for RoboBoard 3-pin SERVO ports.
May access specific port or all at once:

  • Servo.A, Servo.B, Servo.C, Servo.D - control single port
  • Servo[0] - control port A [1-B, 2-C, 3-D] (invalid indexes will be ignored)
  • Servo - control all ports (some "get" functions are not available in this case)

Code snippets

Function usage example
// Control all servo ports
Servo.spinPos(0); // Move to center
Servo.spinPos(60); // Move 60% right
Servo.spinPosDuration(0, 1500); // Move to center in 1.5s
Servo.spinPosRPM(60, 30); // Move 60% right at 30RPM speed
Servo.spinAngle(0); // Move left
Servo.spinAngle(90); // Move to 90° (center)
Servo.spinPulse(1500); // Move to 1500µs (center)
Servo.coast(); // Motor free spin (no hold)
// Stop servo port B
Servo[1].stop();
// Configure servo A port
Servo.A.setInvert(true); // Invert spin direction
Servo.A.setSpeedRPM(30); // Set arm speed to 30RPM
Servo.A.setSpeedS60(0.17); // Set arm speed to 0.17s/60°
Servo.A.setTrim(-38, -7, 18); // Map pos to L: -38, C: -7, R: 18
// Change all ports period
Servo.setPeriod(20000); // Set period to 20000µs

Servo arm angles

Most servos can turn its arm 180 degrees. This is controlled by applying range of 500-2500 μs (microseconds) pulse to signal wire. This corresponds to servo arm position. For convenience - there are 3 different control units:

  • spinPos() - set position in percentage of range [-100:100]%. 0 - center.
  • spinAngle() - set position in angle degrees [0:180]°. 90 - center.
  • spinPulse() - set actual microseconds pulse [500:2500]μs. 1500 - center.

In case setInvert(true) is enabled - servo arm will move to different direction, thus "pos" and "angle" values are inverted. "pulse" stays the same.

Calibration / trimming

Servo contains trimming feature to limit motor position to configured range. Mainly used for car steering with calibrated center position and maximum travel to left and right.

RoboCar steering

When configured, function spinPos() [-100:100] can be used to steer robot wheels.

Select motor parameters

Most servos operate in 500 to 2500μsec range and can turn its arm either 180° or 270°.
Set correct parameters if you are using different type of motor:

  • setMotor(180, 500, 2500) - 180°, 500-2500 μs (default)
  • setMotor(180, 1000, 2000) - 180°, 1000-2000 μs
  • setMotor(270, 500, 2500) - 270°, 500-2500 μs
  • setMotor(270, 1000, 2000) - 270°, 1000-2000 μs

These values may be adjusted to match correct (calibrated) motor angle and pulses.
Function spinPulseRaw() can be used to find actual limits.
Can use SerialServoControl.ino example.

Tip

Some RoboBoard X3 kits contain motor with different microseconds range.
Add this configuration line to make it work properly: Servo.A.setMotor(180, 650, 2350)

Change spin direction

Using function spinPos() with negative / positive value [-100:100] will move motor between configured [500:2500] pulse range. If direction should be reversed - use function: setInvert(true).

Trim motor position

Typically, function spinPos() [-100:100] will turn servo motor in its full range. When placed in a robot - most of the times there are mechanical limits that should be accounted for and center position is shifted. Trimming allows to offset center position and specify how far motor should spin to either side.

  1. Use function spinPos() to find center position and maximum turn to left and right
  2. Enter discovered values to function setTrim(-38, -7, 18)

Now function spinPos() [-100:100] will operate inside configured limits.

// Calibrate
Servo.A.setMotor(180, 500, 2500); // angle, usMin, usMax
Servo.A.setInvert(true); // invert
Servo.A.setTrim(-38, -7, 18); // position limits left, center, right
// Move (spin to position)
Servo.A.spinPos(0); // [-100:100] (spins to -7)

Functions

🕹 Position control

Servo.A.spinPos(position)

Servo.A.spinPosDuration(position,duration)

Servo.A.spinPosRPM(position,speed)

Move servo to position (%).
Parameter:
position - servo position [-100:100]%
duration - time duration for position to change time in ms
speed - motor speed in rounds per minute (RPM) units [1:~60].

Servo.A.spinAngle(angle)

Servo.A.spinAngleDuration(angle,duration)

Servo.A.spinAngleRPM(angle,speed)

Move servo to angle (°).
Note: maximum angle depends on setMotor() configuration.
Parameter:
angle - servo angle [0:180]°
duration - time duration for position to change time in ms
speed - motor speed in rounds per minute (RPM) units [1:~60]

Servo.A.spinPulse(pulse)

Servo.A.spinPulseDuration(pulse,duration)

Servo.A.spinPulseRPM(pulse,speed)

Move servo to exact pulse (µs).
Parameter:
pulse - time [500:2500]µs (microseconds)
duration - time duration for position to change time in ms
speed - motor speed in rounds per minute (RPM) units [1:~60]

Servo.A.spinPulseRaw(pulse)

Write pulse directly, without any value filter and conversion. Also ignores setInvert().
Parameter:
pulse - time [0:period]µs (microseconds)

Servo.A.coast()

Set motor to free spin (can be moved by hand). Stops PWM signal output.
Note: Some motors may not support this feature (holds position even without PWM signal).

position Servo.A.getPos()

Get current servo position (%).
Returns:
position - servo position [-100:100]%

angle Servo.A.getAngle()

Get current servo angle (°).
Returns:
angle - servo angle [0:180]°

pulse Servo.A.getPulse()

Get current servo pulse (µs).
Returns:
pulse - pulse time [500:2500]µs (microseconds)

Limit trimming

Servo.A.setTrim(left,right)

Servo.A.setTrim(left,center,right)

Set motor rotation limits for spinPos() function. Uses position percentage parameters.
• Parameter values must come in order! left < center < right.
• setInvert() must be set correctly before calling this function. Position values internally are converted to pulses.
• If center parameter is not provided - it is set to middle value between left and right.
Parameter:
left - steer to left limit [-100:100]%
center - center position [-100:100]%
right - steer to right limit [-100:100]%

Servo.A.setTrimPulse(min,max)

Servo.A.setTrimPulse(min,center,max)

Set motor rotation limits for spinPos() function. Uses exact pulse (µs) parameters.
Function spinPulseRaw() can be used to discover required values.
• Parameter values must come in order! min < center < max.
• [usMin:usMax] range depends on setMotor() configuration. Typically [500:2500].
• If center parameter is not provided - it is set to middle value between min and max.
Parameter:
min - minimum pulse limit [usMin:usMax]µs (microseconds)
center - center pulse position [usMin:usMax]µs (microseconds)
max - maximum pulse limit [usMin:usMax]µs (microseconds)

Spin speed

Servo.A.setSpeedRPM(speed)

Servo.A.setSpeedS60(seconds)

Set constant servo speed (to slow it down).
Servo motors are capable ~60 RPM at top. Setting value 0 will use maximum motor speed.
Parameter:
speed - motor speed in rounds per minute (RPM) units [1:~60].
seconds - (float) motor speed in seconds / 60 degree units (e.g. 0.16 = 62.5RPM).
It is commonly found in servo motors description.

speed Servo.A.getSpeedRPM()

seconds Servo.A.getSpeedS60()

Get configured servo speed.
Returns:
speed - motor speed in rounds per minute (RPM) units [1:~60].
seconds - (float) motor speed in seconds / 60 degree units (e.g. 0.16 = 62.5RPM).
It is commonly found in servo motors description.

Move sequences

Run list of predefined servo movements with position and delay. Convenient to use when some repetitive action has to be performed in background. 

void setup() {
  // Run list of inline servo movements
  Servo.A.run({
    {500, 0},    // delay:500, position:0
    {500, -50},  // delay:500, position:-50
    {1000, 0},   // delay:1s, position:0
    {500, 50},   // delay:500, position:-50
  });
  Servo.A.wait(); // Wait for started sequence to end
  // Define sequence list
  ServoSequence list[] = {
    {500, 40},     // delay:500, position:40
    {500, 0},      // delay:500, position:0
    {500, -40},    // delay:500, position:-40
    {500, 0},      // delay:500, position:0
  };
  // Run specified list 3 times and stop
  Servo.A.run(list, 3);
}
void loop() { }

Maximum of 6 moves in sequence available.

Servo.A.run(sequence[])

Servo.A.run(sequence[], times)

Run provided list of movements in order. Executed in background and does not block code.
Additionally, times parameter can be provided to repeat this list number of times.
Parameter:
sequence[] - array of ServoSequence.
times - number of times to repeat sequence. 0 - repeat. Default: 1.

state Servo.A.isMoving()

Check if servo motor is currently moving. Works in a few cases:
1. Motor is executing servo sequence run().
2. Motor is moving with custom speed setSpeedRPM().
3. Motor is moving with duration/RPM spinPosDuration().
Other cases it will return false!
Returns: state - true if motor is moving, false if stationary.

state Servo.A.wait()

state Servo.A.wait(time)

Wait for motor to stop moving (block code until). Works in a few cases:
1. Motor is executing servo sequence run().
2. Motor is moving with custom speed setSpeedRPM().
3. Motor is moving with duration/RPM spinPosDuration().
Other cases it will return true right away without blocking!
Parameter: time - maximum time to wait (ms) for motor move end. 0 - disabled.
Returns: state - true motor finish moving, false timeout.

Servo.A.stop()

Stop currently moving servo motor:
1. Running servo sequence (started with run()).
2. Moving with configured duration/RPM.

Configuration

Servo.A.setEnable(state)

Enable / disable servo output. Will stop signal generation if disabled.
Parameter:
state - turn motor port on / off [true:false].

Servo.A.setInvert(state)

Invert servo spin direction.
Parameter:
state - invert spin direction [true:false]

Servo.A.setMotor(angle,usMin,usMax)

Set Servo motor configuration. Default: 180deg, 500us, 2500us
Parameter:
angle - maximum motor spin angle (180deg or 270deg)
usMin - min position pulse [0:period]µs (microseconds)
usMax - max position pulse [0:period]µs (microseconds)

state Servo.A.getEnable()

Check if servo output is enabled (yes / no).
Returns:
state - enabled / disabled [true:false].

state Servo.A.getInvert()

Check if motor spin direction is inverted (yes / no).
Returns:
state - yes / no [true:false].

Params Servo.A.getMotor()

Get servo motor configuration of setMotor(). Default (180,500,2500) µs.
Returns:
Params - MotorType structure.

void setup() {
    auto range = Servo.A.getMotor();
    range.angle; // Max angle
    range.usMin; // Min microseconds limit
    range.usMax; // Max microseconds limit
    // Alternative use
    Servo.A.getMotor().angle;
    Servo.A.getMotor().usMin;
    Servo.A.getMotor().usMax;
}

Range Servo.A.getTrim()

Range Servo.A.getTrimPulse()

Get configured position range of setTrim(). Default: [-100:0:100].
Returns:
Range - Range structure.

void setup() {
    auto range = Servo.A.getTrim();
    range.min;
    range.mid;
    range.max;
    // Alternative use
    Servo.A.getTrim().min;
    Servo.A.getTrim().mid;
    Servo.A.getTrim().max;
}

number Servo.getPortsCount()

Get number of servo ports board has.
Returns:
number - servo ports count [2:4]

Change PWM period:

Servo.setPeriod(period)

Set custom servo signal period (default 20000µs (50Hz)) (all ports)
Parameter:
period - signal window time [0:65535]µs (microseconds)

number Servo.getPeriod()

Get configured servo signal period (default 20000µs (50Hz)).
Returns:
number - signal window time [0:65535]µs (microseconds)