pimoroni-pico/micropython/modules/servo/README.md

Servos and Servo 2040

The Servo library lets you drive 3-pin hobby servo motors from a Raspberry Pi Pico or any other RP2040-based board, such as the Pimoroni Servo 2040.

Table of Content

• Implementations
  • PWM Limitations
  • PIO Limitations
• Servo
  • Getting Started
  • Function Reference
  • Pin
  • Enabling and Disabling
  • Control by Pulse Width
  • Control by Value
  • Frequency Control
  • Useful Values
  • Control by Percent
  • Calibrating
• ServoCluster
  • Getting Started
  • Function Reference
  • Count
  • Pin
  • Enabling and Disabling
  • Control by Pulse Width
  • Control by Value
  • Phase Control
  • Frequency Control
  • Useful Values
  • Control by Percent
  • Calibrating
  • Delayed Loading
• Calibration
  • Getting Started
  • Function Reference

Implementations

This library offers two servo implementations:

• a Servo class that uses hardware PWM to drive a single servo, with support for up to 16 servos.
• a ServoCluster class that uses Programmable IO (PIO) hardware to drive up to 30 servos.

There is also a Calibration class for performing advanced tweaking of each servo's movement behaviour.

PWM Limitations

Although the RP2040 is capable of outputting up to 16 PWM signals, there are limitations of which pins can be used together:

• The PWMs output from pins 0 to 15 are repeated for pins 16 to 29, meaning that those pins share the same signals if PWM is enabled on both. For example if you used pin 3 for PWM and then tried to use pin 19, they would both output the same signal and it would not be possible to control them independently.
• The 16 PWM channels are grouped into 8 PWM slices, each containing A and B sub channels that are synchronised with each other. This means that parameters such as frequency are shared, which can cause issues if you want one servo to operate at a different frequency to it's pin neighbour or to drive an LED with PWM at a high frequency.

The official RP2040 datasheet, includes the handy Table 525 that details the pwm channel for each GPIO pin. This is shown below for convenience:

GPIO	0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15
PWM Channel	0A	0B	1A	1B	2A	2B	3A	3B	4A	4B	5A	5B	6A	6B	7A	7B

GPIO	16	17	18	19	20	21	22	23	24	25	26	27	28	29
PWM Channel	0A	0B	1A	1B	2A	2B	3A	3B	4A	4B	5A	5B	6A	6B

PIO Limitations

The RP2040 features two PIOs with four state machines each. This places a hard limit on how many ServoClusters can be created. As this class is capable of driving all 30 GPIO pins, the only time this limit will be of concern is when servos with different frequencies are wanted, as all the outputs a ServoCluster controls share the same frequency. Relating this to the hardware PWM, think of it as a single PWM slice with up to 30 sub channels, A, B, C, D etc.

When creating a ServoCluster, in most cases you'll use 0 for PIO and 0 for PIO state-machine. You should change these though if you plan on running multiple clusters, or using a cluster alongside something else that uses PIO, such as our Plasma library.

Servo

Getting Started

Constructing a Servo

Servo(
  pin,            # int: the hardware pin to use for the servo
  type=ANGULAR,   # int: the type the servo will start as (options are ANGULAR, LINEAR, CONTINUOUS, and EMPTY)
  freq=50         # float: the frequency the servo will receive pulses at
)

Function Reference

Here is the complete list of functions available on the Servo class:

Servo(pin, type=ANGULAR, freq=50)
pin()
enable()
disable()
is_enabled()
pulse()
pulse(pulse)
value()
value(value)
frequency()
frequency(freq)
min_value()
mid_value()
max_value()
to_min()
to_mid()
to_max()
to_percent(in)
to_percent(in, in_min, in_max)
to_percent(in, in_min, in_max, value_min, value_max)
calibration()
calibration(calibration)

Pin

To get the pin number the servo is assigned to:

pin() # returns int: the hardware pin of the servo

Enabling and Disabling

To enable the servo:

enable()

If the servo has not previously been enabled, it will default to the middle of its range.

To disable the servo:

disable()

To check the enabled state of the servo:

is_enabled() # returns bool: True if enabled, False if disabled

Control by Pulse Width

Servos operate by receiving a digital signal with specific pulse widths. Typically values are between 500 microseconds and 2500 microseconds.

To read the current pulse the servo is receiving:

pulse() # returns float: the duration of the pulse in microseconds

If the servo is disabled, this will be the last pulse that was provided when enabled.

To set a new pulse for the servo to receive:

pulse(
  pulse   # float: the pulse duration in microseconds
)

If the servo is disabled, this will also enable it. It will also recalculate the related value.

Control by Value

Value is a way to control servos using numbers that have a real-world meaning, rather than with pulse widths. For instance, -90 to +90 degrees for an angular servo, or -1 to +1 for a continous rotation servo. See Calibration for more details.

To read the current value the servo is at:

value() # returns float: the value

If the servo is disabled, this will be the last value that was provided when enabled.

To set the servo to a new value:

value(
  value   # float: the value
)

If the servo is disabled, this will also enable it. The resulting pulse width will also be stored.

Frequency Control

The vast majority of Servos expect to receive pulses with a frequency of 50Hz, so this library uses that as its default. However, there may be cases where this value needs to be changed, such as when using servos that operate up to frequencies of 333Hz.

To read the current servo pulse frequency:

frequency() # returns float: the frequency in Hz

To set a new servo pulse frequency:

frequency(
  freq   # float: the frequency between 10 and 350Hz
)

Useful Values

When performing motion patterns on a servo, it can sometimes be useful to know what a servo's minimum, middle, and maximum values are.

To get the minimum value the servo can reach:

min_value()   # returns float: the minimum value

To get the middle value of the servo:

mid_value()   # returns float: the middle value

To get the maximum value the servo can reach:

mid_value()   # returns float: the maximum value

Similarly, it can be useful to command a servo to one of these values without needing to know the actual number.

To move the servo to its minimum value.

to_min()

To move the servo to its middle value.

to_mid()

To move the servo to its maximum value.

to_max()

Control by Percent

Sometimes there are projects where you want a servo to move based on the reading from a sensor or another device, but the numbers given out are not easy to convert to values the servo accepts. To overcome this the library lets you move the servo to a percent between its minimum and maximum values, or two values you provided, based on that input.

With an input between -1.0 and 1.0, move the servo to a percent between its minimum and maximum values:

to_percent(
  in    # float: the input, from -1.0 to +1.0
)

With an input between a provided min and max, move the servo to a percent between its minimum and maximum values:

to_percent(
  in,     # float: the input, from in_min to in_max
  in_min, # float: the minimum expected input
  in_max  # float: the maximum expected input
)

With an input between a provided min and max, move the servo to a percent between two provided values:

to_percent(
  in,         # float: the input, from in_min to in_max
  in_min,     # float: the minimum expected input
  in_max      # float: the maximum expected input
  value_min,  # float: the value the servo will go to when receiving a minimum input
  value_max   # float: the value the servo will go to when receiving a maximum input
)

Calibrating

There are different types of servos, with angular, linear, and continuous being common. To support these different types, each Servo class contains a calibration object that stores the specific value to pulse mapping needed for its type. This object can be accessed for each servo as well as updated on the fly.

To get the calibration of the servo:

calibration()   # returns Calibration: a copy of the servo's calibration

To update the calibration of the servo.

calibration(
  calibration   # Calibration: the object to update the servo's calibration with
)

ServoCluster

Getting Started

Constructing a ServoCluster

ServoCluster(
  pio,              # int: the pio device to use for the cluster (0 or 1)
  sm,               # int: the state machine on that pio to use for the cluster (0 to 3)
  type=ANGULAR,     # int: the type the servos will start as (options are ANGULAR, LINEAR, CONTINUOUS, and EMPTY)
  freq=50,          # float: the frequency the servos will receive pulses at
  auto_phase=True   # bool: whether to automatically set the servo phases to reduce peak current draw
)

Function Reference

Here is the complete list of functions available on the ServoCluster class:

ServoCluster(pio, sm, pins, type=ANGULAR, freq=50, auto_phase=True)
count()
pin(servo)
enable(servo, load=True)
disable(servo, load=True)
is_enabled(servo)
pulse(servo)
pulse(servo, pulse, load=True)
value(servo)
value(servo, value, load=True)
phase(servo)
phase(servo, phase, load=True)
frequency()
frequency(freq)
min_value(servo)
mid_value(servo)
max_value(servo)
to_min(servo, load=True)
to_mid(servo, load=True)
to_max(servo, load=True)
to_percent(servo, in, load=True)
to_percent(servo, in, in_min, in_max, load=True)
to_percent(servo, in, in_min, in_max, value_min, value_max, load=True)
calibration(servo)
calibration(servo, calibration)
load()

Count

To get the number of servos assigned to this cluster:

count() # returns int: the number of servos

Pin

To get the pin number a servo on the cluster is assigned to:

pin(
  servo   # int: the servo to get the pin of
) # returns int: the hardware pin of the servo

Enabling and Disabling

To enable a servo on the cluster:

enable(
  servo,      # int: the servo to enable
  load=True   # bool: whether to load the change immediately
)

If the servo has not previously been enabled, it will default to the middle of its range.

To disable a servo on the cluster:

disable(
  servo,      # int: the servo to disable
  load=True   # bool: whether to load the change immediately
)

To check the enabled state of a servo on the cluster:

is_enabled(
  servo,      # int: the servo to check the enabled state of
) # returns bool: True if enabled, False if disabled

Control by Pulse Width

Servos operate by receiving a digital signal with specific pulse widths. Typically values are between 500 microseconds and 2500 microseconds.

To read the current pulse the servo is receiving:

pulse(
  servo       # int: the servo to read the pulse of
) # returns float: the duration of the pulse in microseconds

If the servo is disabled, this will be the last pulse that was provided when enabled.

To set a new pulse for the servo to receive:

pulse(
  servo,      # int: the servo to set the pulse of
  pulse,      # float: the pulse duration in microseconds
  load=True   # bool: whether to load the change immediately
)

If the servo is disabled, this will also enable it. It will also recalculate the related value.

Control by Value

Value is a way to control servos using numbers that have a real-world meaning, rather than with pulse widths. For instance, -90 to +90 degrees for an angular servo, or -1 to +1 for a continous rotation servo. See Calibration for more details.

To read the current value the servo is at:

value(
  servo       # int: the servo to read the value of
) # returns float: the value

If the servo is disabled, this will be the last value that was provided when enabled.

To set the servo to a new value:

value(
  servo,      # int: the servo to set the value of
  value,      # float: the value
  load=True   # bool: whether to load the change immediately
)

If the servo is disabled, this will also enable it. The resulting pulse width will also be stored.

Phase Control

When dealing with many servos, there can often be large current draw spikes caused by them all responding to pulses at the same time. To minimise this, a servo cluster allows for the start time of a servo's pulses to be delayed by a percentage of the available time period. This is called their phase.

To read the current phase of a servo on the cluster:

phase(
  servo       # int: the servo to read the phase of
) # returns float: the phase, between 0.0 and 1.0

To set the phase of a servo on the cluster:

phase(
  servo,      # int: the servo to set the phase of
  phase,      # float: the phase, between 0.0 and 1.0
  load=True   # bool: whether to load the change immediately
)

Frequency Control

The vast majority of Servos expect to receive pulses with a frequency of 50Hz, so this library uses that as its default. However, there may be cases where this value needs to be changed, such as when using servos that operate up to frequencies of 333Hz. All servos on a cluster share the same frequency.

To read the current servo cluster pulse frequency:

frequency() # returns float: the frequency in Hz

To set a new servo cluster pulse frequency:

frequency(
  freq   # float: the frequency between 10 and 350Hz
)

Note, currently the frequency changes immediately, even if part-way through a pulse. It is recommended to disable all servos first before changing the frequency.

Useful Values

When performing motion patterns on a servo, it can sometimes be useful to know what a servo's minimum, middle, and maximum values are.

To get the minimum value a servo on the cluster can reach:

min_value(
  servo,      # int: the servo to get the min value of
)   # returns float: the minimum value

To get the middle value of a servo on the cluster:

mid_value(
  servo,      # int: the servo to get the mid value of
)   # returns float: the middle value

To get the maximum value a servo on the cluster:

mid_value(
  servo,      # int: the servo to get the max value of
)   # returns float: the maximum value

Similarly, it can be useful to command a servo to one of these values without needing to know the actual number.

To move a servo on the cluster to its minimum value.

to_min(
  servo,      # int: the servo to move to its min value
  load=True   # bool: whether to load the change immediately
)

To move a servo on the cluster to its middle value.

to_mid(
  servo,      # int: the servo to move to its mid value
  load=True   # bool: whether to load the change immediately
)

To move a servo on the cluster to its maximum value.

to_max(
  servo,      # int: the servo to move to its max value
  load=True   # bool: whether to load the change immediately
)

Control by Percent

Sometimes there are projects where you want a servo to move based on the reading from a sensor or another device, but the numbers given out are not easy to convert to values the servo accepts. To overcome this the library lets you move the servo to a percent between its minimum and maximum values, or two values you provided, based on that input.

With an input between -1.0 and 1.0, move a servo on the cluster to a percent between its minimum and maximum values:

to_percent(
  servo,      # int: the servo to move to the percent
  in          # float: the input, from -1.0 to +1.0
  load=True   # bool: whether to load the change immediately
)

With an input between a provided min and max, move a servo on the cluster to a percent between its minimum and maximum values:

to_percent(
  servo,      # int: the servo to move to the percent
  in,         # float: the input, from in_min to in_max
  in_min,     # float: the minimum expected input
  in_max      # float: the maximum expected input
  load=True   # bool: whether to load the change immediately
)

With an input between a provided min and max, move a servo on the cluster to a percent between two provided values:

to_percent(
  servo,      # int: the servo to move to the percent
  in,         # float: the input, from in_min to in_max
  in_min,     # float: the minimum expected input
  in_max      # float: the maximum expected input
  value_min,  # float: the value the servo will go to when receiving a minimum input
  value_max   # float: the value the servo will go to when receiving a maximum input
  load=True   # bool: whether to load the change immediately
)

Calibrating

There are different types of servos, with angular, linear, and continuous being common. To support these different types, each Servo class contains a calibration object that stores the specific value to pulse mapping needed for its type. This object can be accessed for each servo as well as updated on the fly.

To get the calibration of a servo on the cluster:

calibration(
  servo,      # int: the servo to get the calibration of
)   # returns Calibration: a copy of the servo's calibration

To update the calibration of a servo on the cluster.

calibration(
  servo,        # int: the servo to set the calibration of
  calibration   # Calibration: the object to update the servo's calibration with
)

Delayed Loading

To match behaviour with the regular Servo class, the ServoCluster automatically applies each change to a servo's state immediately. However, sometimes this may not be wanted, and instead you want all servos to receive updated pulses at the same time, regardless of how long the code ran that calculated the update.

For this purpose, all the functions that modify a servo state include an optional parameter load, which by default is True. To avoid this "loading" include load=False in the relevant function calls. Then either the last call can include load=True, or the following function can be called:

load()

Calibration

Getting Started

Function Reference

Here is the complete list of functions available on the Calibration class:

Calibration(type=ANGULAR)

create_blank_calibration(size)
create_two_point_calibration(min_pulse, max_pulse, min_value, max_value)
create_three_point_calibration(min_pulse, mid_pulse, max_pulse, min_value, mid_value, max_value)
create_uniform_calibration(size, min_pulse, max_pulse, min_value, max_value)
create_default_calibration(type)
size()
point_at(index)
point_at(index, point)
first_point()
first_point(point)
last_point()
last_point(point)
has_lower_limit()
has_upper_limit()
limit_to_calibration(lower, upper)
value_to_pulse(value)
pulse_to_value(pulse)