Servo Basics

# labs/servo_math.py
FRAME_MS = 20.0      # a 50 Hz servo expects one pulse every 20 ms
MIN_PULSE_MS = 1.0   # the pulse that means "one end of travel"
MAX_PULSE_MS = 2.0   # the pulse that means "the other end"


def clamp_angle(angle: float) -> float:
    """Pin any request into the 0-180 degree range the caller is allowed to ask for."""
    return max(0.0, min(180.0, angle))


def angle_to_pulse_ms(angle: float) -> float:
    """Map 0-180 degrees onto the standard 1.0-2.0 ms pulse width."""
    fraction = clamp_angle(angle) / 180.0
    return MIN_PULSE_MS + fraction * (MAX_PULSE_MS - MIN_PULSE_MS)


def duty_percent(pulse_ms: float, frame_ms: float = FRAME_MS) -> float:
    """The fraction of each frame the line spends high, as a percentage."""
    return pulse_ms / frame_ms * 100.0


if __name__ == "__main__":
    for deg in (0, 90, 180):
        pulse = angle_to_pulse_ms(deg)
        print(f"{deg:>3} deg -> {pulse:.2f} ms pulse  {duty_percent(pulse):>5.1f}% duty at 50 Hz")

$ uv run python -m labs.servo_math
  0 deg -> 1.00 ms pulse    5.0% duty at 50 Hz
 90 deg -> 1.50 ms pulse    7.5% duty at 50 Hz
180 deg -> 2.00 ms pulse   10.0% duty at 50 Hz

Two vocabularies get mixed together here, and the confusion is expensive. Duty cycle is the fraction of each period the line spends high, and it is the number most PWM explanations lead with, because for an LED or a motor driver the ratio really is the command: half the time at full voltage averages out to half brightness, and the frequency barely matters. A servo does not average anything. Its control circuit times the high part with a timer of its own, so the command is 1.5 milliseconds of absolute duration, and the 7.5 percent is arithmetic that falls out afterwards. Move the frame to 100 Hz and 7.5 percent duty becomes a 0.75 ms pulse, below anything the servo recognises. The frequency and the duty cycle describe the waveform. Only the width describes the angle.

# labs/servo_math.py — added below angle_to_pulse_ms


def angle_to_value(angle: float) -> float:
    """0 deg -> -1.0 (minimum), 90 deg -> 0.0 (centre), 180 deg -> +1.0 (maximum)."""
    return clamp_angle(angle) / 90.0 - 1.0


def value_to_pulse_ms(value: float,
                      min_ms: float = MIN_PULSE_MS,
                      max_ms: float = MAX_PULSE_MS) -> float:
    """Undo the normalisation: turn a -1.0..1.0 value back into a duration."""
    value = max(-1.0, min(1.0, value))
    return min_ms + (value + 1.0) / 2.0 * (max_ms - min_ms)


if __name__ == "__main__":
    for deg in (0, 45, 90, 135, 180):
        value = angle_to_value(deg)
        print(f"{deg:>3} deg  value {value:+.2f}  pulse via value {value_to_pulse_ms(value):.2f} ms"
              f"  via angle {angle_to_pulse_ms(deg):.2f} ms")

$ uv run python -m labs.servo_math
  0 deg  value -1.00  pulse via value 1.00 ms  via angle 1.00 ms
 45 deg  value -0.50  pulse via value 1.25 ms  via angle 1.25 ms
 90 deg  value +0.00  pulse via value 1.50 ms  via angle 1.50 ms
135 deg  value +0.50  pulse via value 1.75 ms  via angle 1.75 ms
180 deg  value +1.00  pulse via value 2.00 ms  via angle 2.00 ms

The library you will actually drive this with, gpiozero, takes neither degrees nor milliseconds. Its Servo takes a normalised value from -1.0 through 0.0 to +1.0 and generates the pulse train underneath. That looks like a third thing to learn and it is not: the two columns on the right agree on every row, because the value scale is the pulse range with its endpoints renamed. Degrees are for humans, the value is for the library, the pulse width is for the servo, and the arithmetic between them is four lines you can read.

Timing is why the library exists at all. Writing the pulse yourself means setting a pin high, sleeping 1.5 ms, setting it low, in a Python loop on a kernel that is entirely free to schedule something else in the middle of that sleep. A pulse meant to be 1.50 ms arrives as 1.7 ms because a transcription thread woke up, and the servo believes every pulse it is given. gpiozero pushes the pulse train down to a pin factory whose only job is keeping it steady, and swapping that factory for pigpio moves the timing off the Python interpreter altogether.

# labs/servo_test.py
import signal
import sys
import time

from gpiozero import Servo

from labs.servo_math import MAX_PULSE_MS, MIN_PULSE_MS, angle_to_pulse_ms, angle_to_value, clamp_angle

SERVO_PIN = 17       # BCM numbering; physical pin 11 on the header


def set_angle(servo: Servo, degrees: float) -> float:
    """Command the servo in degrees. Returns the angle actually applied."""
    degrees = clamp_angle(degrees)
    servo.value = angle_to_value(degrees)
    return degrees

# labs/servo_dry_run.py — the same code path, with no Pi in the room
from gpiozero import Device, Servo
from gpiozero.pins.mock import MockFactory, MockPWMPin

from labs.servo_math import angle_to_pulse_ms, angle_to_value
from labs.servo_test import set_angle

Device.pin_factory = MockFactory(pin_class=MockPWMPin)

if __name__ == "__main__":
    servo = Servo(17)
    for requested in (0, 45, 90, 135, 180, 220):
        applied = set_angle(servo, requested)
        note = "  (clamped)" if applied != requested else ""
        print(f"{requested:>3} deg -> value {angle_to_value(applied):+.2f}"
              f" -> {angle_to_pulse_ms(applied):.2f} ms{note}")

$ uv run python -m labs.servo_dry_run
  0 deg -> value -1.00 -> 1.00 ms
 45 deg -> value -0.50 -> 1.25 ms
 90 deg -> value +0.00 -> 1.50 ms
135 deg -> value +0.50 -> 1.75 ms
180 deg -> value +1.00 -> 2.00 ms
220 deg -> value +1.00 -> 2.00 ms  (clamped)

Assign servo.value = 90 because 90 degrees is what you meant, and gpiozero refuses it: OutputDeviceBadValue: Servo value must be between -1 and 1, or None. That refusal is a favour. A library that quietly accepted 90 and saturated at 1.0 would move the servo to a full extreme and never tell you the command was nonsense. Everyone writes that line once, and the cure is to make set_angle the only place in her code that ever touches servo.value.

Chapter 27 set the placement rule when the servo was still a print statement: the clamp belongs inside the function that applies the value, not at the call sites, because call sites multiply and any one of them can be a typo, a stale config, or a language model that decided 220 was a reasonable number. Here the clamp runs in degrees, before the conversion, so the saturation is visible in the units the caller was thinking in. The mock pin factory gives you the whole path without hardware: MockPWMPin is required specifically because a plain mock pin has no PWM to fake.

# labs/servo_test.py — continued
STEP = 0.05          # value increment per step; 0.05 of 2.0 is 25 us of pulse
STEP_DELAY = 0.02    # seconds between steps
CYCLES = 3


def sweep_once(servo: Servo) -> None:
    """One trip to the maximum and back, in fixed integer steps."""
    steps = int(2.0 / STEP)
    for i in range(steps + 1):
        servo.value = max(-1.0, min(1.0, -1.0 + i * STEP))
        time.sleep(STEP_DELAY)
    for i in range(steps + 1):
        servo.value = max(-1.0, min(1.0, 1.0 - i * STEP))
        time.sleep(STEP_DELAY)


def release(servo: Servo) -> None:
    """Stop sending pulses so the servo relaxes instead of holding and buzzing."""
    print("\nDetaching servo...")
    servo.detach()


def main() -> None:
    servo = Servo(SERVO_PIN)

    def on_signal(signum: int, frame: object) -> None:
        release(servo)
        sys.exit(0)

    signal.signal(signal.SIGINT, on_signal)
    signal.signal(signal.SIGTERM, on_signal)

    print(f"Servo sweep on GPIO {SERVO_PIN} (BCM), pulse "
          f"{MIN_PULSE_MS:.2f}-{MAX_PULSE_MS:.2f} ms, step={STEP}, delay={STEP_DELAY}s")
    for cycle in range(1, CYCLES + 1):
        print(f"Cycle {cycle}/{CYCLES}")
        sweep_once(servo)
    print("Sweep complete.")
    release(servo)


if __name__ == "__main__":
    main()

$ uv run python -m labs.servo_test   # measured on the bench — yours will vary
Servo sweep on GPIO 17 (BCM), pulse 1.00-2.00 ms, step=0.05, delay=0.02s
Cycle 1/3
Cycle 2/3
Cycle 3/3
Sweep complete.

Detaching servo...

The loop counts integers and computes the value from the count. Accumulating value += 0.05 forty times instead would drift a hair past 1.0 on the last step, and gpiozero would raise in the middle of a motion. Forty-one assignments in each direction makes 82 per cycle, 1.64 seconds of travel at a 20 ms delay, and the outer max/min catches anything a future edit to STEP might produce.

The signal handlers are the part people leave out and regret. Press Ctrl+C during a sweep without them and the process dies while the pulse train is still configured, so the servo goes on holding whatever position it was last told, warm and drawing current, until you pull the plug. Registering the same handler on SIGINT and SIGTERM means both an impatient keyboard and a service manager stopping the unit end at detach(). Note that servo is created inside main and closed over by the handler, not parked at module level: a module that grabs a GPIO pin on import cannot be imported by the dry run, or by a test, or by anything else that just wants the functions.