Home

Awesome

<div align = center>

ServoEasing

A library for smooth servo movements.<br/> It uses the standard Arduino Servo library and therefore has its restrictions regarding pins and platform support.

Badge License: GPLv3     Badge Version     Badge Commits since latest     Badge Build Status     Badge Hit Counter <br/> <br/> Stand With Ukraine

Available as Arduino library "ServoEasing". Contains the QuadrupedControl example.

Button Install     Button API     Button Changelog

</div>

If you find this library useful, please give it a star.

🌎 Google Translate

<br/>

YouTube video of ServoEasing in action

Demonstration of different servo easings

Table of content

<br/>

Servo easing library for Arduino

Its purpose is to interpolate the movement between two servo positions set by software.<br/> If your servo control data is e.g. generated by an joystick or other "slow" changing inputs and therefore does not change suddenly or does not jump, you most likely do not need this library!, you may consider to use a digital low pass or simple EMA filters to smooth your values used to control the servos.<br/> ServoEasing works with the Arduino Servo library as well as with PCA9685 servo expanders. The expander in turn requires the Arduino Wire library or a compatible one and is bound to their restrictions.<br/> For ESP32 you need to install the Arduino ESP32Servo library.<br/> <br/> If you require only one or two servos, you may want to use the included LightweightServo library which is like the Adafruit TiCoServo library, but more lightweight and currently only for Uno, Nano, instead of the Arduino Servo library. The LightweightServo library uses the internal Timer1 with no software overhead and therefore has no problems with servo twitching or interrupt blocking libraries like SoftwareSerial, Adafruit_NeoPixel and DmxSimple.<br/> For instructions how to enable these alternatives, see Compile options / macros.

<br/>

Features

List of easing functions

Linear     Quadratic     Cubic     Quartic

Sine     Circular     Back     Elastic     Bounce

Precision     Dummy     User defined

All easing functions can be used in the following variants:

All ease functions are called internally with the value: PercentageOfCompletion / 100 giving a call value from 0 to 1.

All easing types (starting in flavor IN_OUT, then IN, OUT and BOUNCE) in one plot.<br/>

Since the values are computed in a fixed 20 ms raster, the last degree increment or decrement in an easing may be much smaller than the increment/decrement before, resulting in some small discontinuities between adjacent movements.<br/> Arduino Plotter Output for Linear->Quadratic->Cubic->Quartic->Sine-Circular->Back->Elastic

Constraints

To restrict servo movements to a fixed range, you can specify constraints with setMinMaxConstraint(int aMinDegreeOrMicrosecond, int aMaxDegreeOrMicrosecond).<br/>

Arduino Plotter Output with constraints at 5 ° and 175 ° activated.

Arduino Plotter Output with constraints at 5 degree and 175 degree activated

Disable easing temporarily

By setting speed -which is an uint16- to a real high value like e.g. 50000, you can effectively disable easing and get almost the same behavior as if using Servo.write() function directly.

<br/>

API

For floating point constants, use the notation of 123.456f with trailing f (for a floating point constant) to avoid compiler errors. A Doxygen documentation of the sources is available here.

Usage

See also the examples here.<br/>

void setup() {
    Servo1.attach(SERVO1_PIN, 45);
}
void loop() {
    Servo1.setEasingType(EASE_CUBIC_IN_OUT); // EASE_LINEAR is default
    Servo1.easeTo(135, 40);                                 // Blocking call
    Servo1.startEaseTo(45, 40, START_UPDATE_BY_INTERRUPT);  // Non blocking call
    // Now the servo is moving to the end position independently of your program.
    delay(5000);
}

Just call myServo.startEaseTo() instead of myServo.write() and you are done. Or if you want to wait (blocking) until servo has arrived, use myServo.easeTo().<br/>

<br/>

Multiple servo handling

You can handle multiple servos simultaneously by special functions like writeAllServos(), setSpeedForAllServos(), setIntegerDegreeForAllServos(), setEaseToDForAllServos(), updateAndWaitForAllServosToStop(), setEaseToForAllServosSynchronizeAndWaitForAllServosToStop(), setEaseToForAllServosSynchronizeAndStartInterrupt() and much more.<br/> See below.

<br/>

Comparison between Quadratic, Cubic and Sine easings.

Arduino Serial Plotter result of the SymmetricEasing example. Arduino plot

<br/>

Useful resources

<br/>

Resolution of servo positioning

Mapping of servo positioning

If you want to operate your servo e.g. from -90 ° to +90 °, you have two possibilities to specify this during attach:

  1. Use Servo1.attachWithTrim(SERVO1_PIN, 90, START_DEGREE_VALUE, DEFAULT_MICROSECONDS_FOR_0_DEGREE, DEFAULT_MICROSECONDS_FOR_180_DEGREE) like it is done in the TwoServos example.
  2. Use Servo1.attach(SERVO1_PIN, DEFAULT_MICROSECONDS_FOR_0_DEGREE, DEFAULT_MICROSECONDS_FOR_180_DEGREE, -90, 90).

If your servo has other timing characteristics than the default one -544 µs for 0 and 2400 µs for 180 ° - you have to use Servo1.attach(SERVO1_PIN, <MY_SERVO_MICROSECONDS_FOR_0_DEGREE>, <MY_SERVO_MICROSECONDS_FOR_180_DEGREE>).<br/> You can combine this with variant 2 from above to transparently specify your servo characteristics e.g. like it is done in the RobotArmControl example:

#define PIVOT_MICROS_AT_PLUS_70_DEGREE        2400 // Left - the MG90 servos are not capable of full 180°
#define PIVOT_MICROS_AT_MINUS_70_DEGREE        700 // Right
BasePivotServo.attach(PIVOT_SERVO_PIN, 0, PIVOT_MICROS_AT_MINUS_70_DEGREE, PIVOT_MICROS_AT_PLUS_70_DEGREE, -70, 70);

Speed of servo positioning

These values are measured with the SpeedTest example.

These are the fastest values for my SG90 servos at 5 volt (4.2 volt with servo active).

DegreeDurationSpeed
180400 ms450 degree per second
90300 ms300 degree per second
45180 ms250 degree per second
30150 ms200 degree per second
20130 ms150 degree per second
1080 ms125 degree per second

Values for the MG90Sservos servos at 5 volt (4.2 volt with servo active).

DegreeDurationSpeed
180330 ms540 degree per second
90220 ms410 degree per second
45115 ms390 degree per second
<br/>

Minimum number of pulses for reliable servo positioning

After disconnected, my SG90 servo requires 4 pulses for a 180 degree turn. It may be less, if the turn is smaller.<br/> After disconnected, myMG90 servo requires 1 pulse for a 110 degree turn. the second pulse (after 20 ms) adds around 10 degree to it, so it takes around 6 to 7 pulses (120 ms to 140 ms) for a complete 180 degree turn.<br/> These values seems to be independent of the turn direction.

These values are measured with the UnitTest example with TEST_FIXED_PULSE_NUMBERS defined. <br/>

Why *.hpp instead of *.cpp?

Every *.cpp file is compiled separately by a call of the compiler exclusively for this cpp file. These calls are managed by the IDE / make system. In the Arduino IDE the calls are executed when you click on Verify or Upload.<br/> And now our problem with Arduino is: How to set compile options for all *.cpp files, especially for libraries used?<br/> IDE's like Sloeber or PlatformIO support this by allowing to specify a set of options per project. They add these options at each compiler call e.g. -DTRACE.<br/> But Arduino lacks this feature. So the workaround is not to compile all sources separately, but to concatenate them to one huge source file by including them in your source. This is done by e.g. #include "ServoEasing.hpp". <br/> But why not #include "ServoEasing.cpp"?<br/> Try it and you will see tons of errors, because each function of the *.cpp file is now compiled twice, first by compiling the huge file and second by compiling the *.cpp file separately, like described above. So using the extension cpp is not longer possible, and one solution is to use hpp as extension, to show that it is an included *.cpp file. Every other extension e.g. cinclude would do, but hpp seems to be common sense.

Using the new *.hpp files

In order to support compile options more easily, the line #include <ServoEasing.h> must be changed to #include <ServoEasing.hpp> in your main program (aka *.ino file with setup() and loop()).

In all other files you must use #include <ServoEasing.h>, to prevent multiple definitions linker errors:

If you forget to include ServoEasing.hpp, you will see errors like Simple.ino:57: undefined reference to ServoEasing::attach(int, int).

Ensure that all macros in your main program are defined before any #include <ServoEasing.hpp>.<br/> The following macros will definitely be overridden with default values otherwise:

<br/>

Compile options / macros for this library

To customize the library to different requirements, there are some compile options / macros available.<br/> These macros must be defined in your program before the line #include <ServoEasing.hpp> to take effect.<br/> Modify them by enabling / disabling them, or change the values if applicable.

NameDefault valueDescription
USE_PCA9685_SERVO_EXPANDERdisabledEnables the use of the PCA9685 I2C expander chip/board.
PCA9685_ACTUAL_CLOCK_FREQUENCY25000000LChange it, if your PCA9685 has another than the default 25 MHz internal clock. See chapter 2 and 5 of the PCA9685 Datasheet "25 MHz typical internal oscillator requires no external components". This value is taken for all attached PCA9685 expanders!
USE_SOFT_I2C_MASTERdisabledSaves up to 1756 bytes program memory and 218 bytes RAM for PCA9685 I2C communication compared with Arduino Wire.
USE_SERVO_LIBdisabledUse of PCA9685 normally disables use of regular servo library. You can force additional using of regular servo library by defining USE_SERVO_LIB. See below.
USE_USER_PROVIDED_SERVO_LIBdisabledIf you have a different servo implementation, e.g. this M5Stack Servo expander you can provide your own servo library by activating this macro.<br/>You must also include the .h file of your library e.g. #include "DummyServo.h".
PROVIDE_ONLY_LINEAR_MOVEMENTdisabledDisables all but LINEAR movement. Saves up to 1540 bytes program memory.
DISABLE_COMPLEX_FUNCTIONSdisabledDisables the SINE, CIRCULAR, BACK, ELASTIC, BOUNCE and PRECISION easings. Saves up to 1850 bytes program memory.
MAX_EASING_SERVOS12, 16(for PCA9685)Saves 4 byte RAM per servo. If this value is smaller than the amount of servos declared, attach() will return error and other library functions will not work as expected.<br/>Then of course all AllServos() functions and isOneServoMoving() also can't work correctly!
DISABLE_MICROS_AS_DEGREE_PARAMETERdisabledDisables passing also microsecond values as (target angle) parameter. Saves up to 128 bytes program memory.
DISABLE_MIN_AND_MAX_CONSTRAINTSdisabledDisables servo movement constraints. Saves 4 bytes RAM per servo but strangely enough no program memory.
DISABLE_PAUSE_RESUMEdisabledDisables pause and resume functionality. Saves 5 bytes RAM per servo.
PRINT_FOR_SERIAL_PLOTTERdisabledGenerate serial output for Arduino Plotter (Ctrl-Shift-L).
DEBUGdisabledGenerates lots of lovely debug output for this library.
USE_LEIGHTWEIGHT_SERVO_LIBdisabledAvailable only for ATmega328. Supports only servos at pin 9 and 10. Makes the servo pulse generating immune to other libraries blocking interrupts for a longer time like SoftwareSerial, Adafruit_NeoPixel and DmxSimple. See below. Saves up to 742 bytes program memory and 42 bytes RAM.
MINIMUM_PULSE_WIDTH400The shortest pulse which can be sent to a servo by this library. This value is smaller than the value used by the Arduino Servo library, which is 544 us (MIN_PULSE_WIDTH), to be more versatile.
MAXIMUM_PULSE_WIDTH3500The shortest pulse which can be sent to a servo by this library. This value is greater than the value used by the Arduino Servo library, which is 2400 us (MAX_PULSE_WIDTH), to be more versatile.
<br/>

Using PCA9685 16-Channel Servo Expander

Using the PCA9685 expander makes the servo pulse generating immune to other libraries blocking interrupts for a longer time like SoftwareSerial, Adafruit_NeoPixel and DmxSimple.<br/> To enable the use of the expander, activate the line #define USE_PCA9685_SERVO_EXPANDER before #include <ServoEasing.hpp>.<br/> In expander mode, timer1 is only required for the startEaseTo* functions and not for the blocking easeTo* functions, since no servo signal must be generated by it.

The pin number parameter of the attach function determines the port number of the PCA9685 and can be in the range from 0 to 15.

Be aware that the PCA9685 expander is reset at the first attach() and initialized at every further attach().<br/> To control simultaneously servos with the Arduino Servo library i.e. servos which are directly connected to the Arduino board, activate the line #define USE_SERVO_LIB.<br/> In this case you should attach the expander servos first in order to initialize the expander board correctly. And as long as no servo using the Arduino Servo library is attached, the expander servos will not move, which should not be a problem since you normally attach all servos in setup().<br/> Resolution of the is PCA9685 signal is approximately 0.5 °.

On the ESP32 the I2C library is only capable to run at 100 kHz, because it interferes with the Ticker / Timer library used. Even with 100 kHz clock we have some dropouts / NAK's because of sending address again instead of first data.<br/> Since the raw transmission time of 32 Servo positions is 17.4 µs @ 100 kHz, not more than 2 expander boards can be connected to one I2C bus on an ESP32 board, if all servos should move simultaneously.<br/> If you do not use any timer in your program you can increase speed up to 800 kHz. Maybe you have to attach 2 x 2.2 kΩ pullup resistors to the I2C lines to have it working reliably.

<br/>

Using the included Lightweight Servo library for ATmega328

This library is like the Adafruit TiCoServo library, but more lightweight and currently only for Uno, Nano.

Using the Lightweight Servo library reduces sketch size and makes the servo pulse generating immune to other libraries blocking interrupts for a longer time like SoftwareSerial, Adafruit_NeoPixel and DmxSimple.<br/> Up to 2 servos are supported by this library and they must be physically attached to pin 9 and/or 10 of the Arduino board.<br/> To enable it, activate the line #define USE_LEIGHTWEIGHT_SERVO_LIB before the line #include "LightweightServo.hpp" like it is done in the TwoServos example.<br/> If you do not use the Arduino IDE, take care that Arduino Servo library sources are not compiled / included in the project.

<br/>

Handling multiple servos with the internal ServoEasingArray

The ServoEasing library provides two arrays to ease the handling of multiple servos.

Every ServoEasing object is appended to the ServoEasingArray by the attach() function. Only the order of the attach() statements determines the position in the array. So you can access your servo, which you attached secondly, also by ServoEasing::ServoEasingArray[1]->setEaseTo(135) as it is done here.<br/> There are also many other *AllServos* functions like stopAllServos().

To move multiple servo, you can fill up the ServoEasing::ServoEasingNextPositionArray with the desired positions and then use e.g. the function setEaseToForAllServos(). Then you must enable interrupt with enableServoEasingInterrupt() or call updateAllServos() in your main loop until it returns true.<br/> If you want to move all your servos synchronized, i.e. they all stop at the same time, you can use the setEaseToForAllServosSynchronizeAndWaitForAllServosToStop() or setEaseToForAllServosSynchronizeAndStartInterrupt function.<br/> An example can be found here.<br/> The Quadruped example makes heavy use of the *AllServos* functions.

If you detach a servo and then attach another one, the latter will get the index of the former detached one.

<br/>

Examples for this library

The examples are available at File > Examples > Examples from Custom Libraries / ServoEasing.<br/>

DummyServoExample

This is an example for a user provided servo library, which is activated by #define USE_USER_PROVIDED_SERVO_LIB.

<br/>

WOKWI online examples

<br/>

Servo utilities

<br/>

Building breadboard servo adapter

Converting a 10 pin double row pin header with 21 mm pin length to a breadboard servo adapter. Side view Top view

<br/>

Internals

The API accepts degrees or microseconds as float or integer values, but internally only microseconds (or units (= 4.88 µs) if using PCA9685 expander) and not degrees are used to speed up things.<br/>

If you do not specify an initial position with attach, the first attach moves servo to DEFAULT_PULSE_WIDTH (90 degree | 1500 us). This behavior is implemented by the underlying Servo library. Following attaches just use the last position of this Servo.

<br/>

Supported Arduino architectures

Every Arduino architecture with a Servo library will work without any modifications in blocking mode.<br/> Non blocking behavior can always be achieved manually by calling update() or updateAllServos() in a loop - see ThreeServos example.<br/> Interrupt based movement (movement without calling update() manually in a loop) is supported for the following Arduino architectures:<br/> avr, megaavr, sam, samd, esp8266, esp32, stm32, STM32F1 and apollo3.<br/> It is not planned to support the ATtiny architecture, but you are invited to do it by yourself and send a pull request.

<br/>

Timer usage for interrupt based movement

On AVR Timer1 is used for the Arduino Servo library. To have non blocking easing functions its unused Channel B is used to generate an interrupt 100 µs before the end of the 20 ms Arduino Servo refresh period. This interrupt then updates all servo values for the next servo signal refresh period.

PlatformTimerLibrary providing the timer
avrTimer1Servo.h
ATmegaTimer5Servo.h
megaavrTCA0
samID_TC8 (TC2 channel 2)
samdTC5
esp8266 + esp32TickerTicker.h
stm32TIM3HardwareTimer.h
STM32F13 or 7HardwareTimer.h
TeensyIntervalTimer
apollo3timer 3 segment A
Mbedmbed::TickerTicker.h
RP2040 / Pi Picodefault alarm pooltime.h
<br/>

Adding a new platform / board

If timer support is available for a platform the library can be ported by adding code for the Timer20ms like is was done for ESP and STM.<br/> To add a new platform, the following steps have to be performed:

  1. If the new platform has an Arduino compatible Servo library, fine, otherwise include the one required for this platform like it is done for ESP32 here.
  2. You need a 20ms interrupt source providing the functions enableServoEasingInterrupt() and (optional) disableServoEasingInterrupt(). Extend these functions with code for the new platform. Place includes and timer definitions at top of ServoEasing.hpp.
  3. If your interrupt source requires an ISR (Interrupt Service Routine) place it after disableServoEasingInterrupt() where all the other ISR are located.
  4. To test the new platform, you may want to enable TRACE output by activating the line #define TRACE in ServoEasing.hpp and enabling interrupt timing feedback by activating the line #define MEASURE_SERVO_EASING_INTERRUPT_TIMING in ServoEasing.hpp.
  5. If it works for you, please issue a Pull Request, to share your efforts with the community.

Good luck!

<br/>

Troubleshooting

If you see strange behavior, you can open the library file ServoEasing.hpp and activate the line #define TRACE or #define DEBUG. This will print internal information visible in the Arduino Serial Monitor which may help finding the reason for it.

<br/>

Revision History

Version 3.3.0

Version 3.2.1

Version 3.2.0

Version 3.1.0

Version 3.0.0

Version 2.4.1

Version 2.4.0

Version 2.3.4

Version 2.3.3

Version 2.3.2

Version 2.3.1

Version 2.3.0

Version 2.2.0

Version 2.1.1

Version 2.1.0

Version 2.0.0

Version 1.6.1

Version 1.6.0

Version 1.5.2

Version 1.5.1

Version 1.5.0

Version 1.4.3

Version 1.4.2

Version 1.4.1

Version 1.4.0

Version 1.3.1

Version 1.3.0

Version 1.2

Version 1.1.0

Version 1.0.0

Initial Arduino library version.

CI

Since Travis CI is slow (5 times slower 17:43 vs. 3:15 minutes), the library examples are now tested with GitHub Actions for this boards.

Requests for modifications / extensions

Please write me a PM including your motivation/problem if you need a modification or an extension.