0
# Output Devices
1

2
GPIO output devices for LEDs, motors, servos, buzzers, and other output components. All output devices support source chaining and can be controlled manually or automatically through event-driven programming.
3

4
## Base Classes
5

6
### OutputDevice
7

8
Base class for all GPIO output devices.
9

10
```python { .api }
11
class OutputDevice(SourceMixin, GPIODevice):
12
    def __init__(self, pin=None, *, active_high=True, initial_value=False, pin_factory=None):
13
        """
14
        Generic GPIO output device.
15
        
16
        Parameters:
17
        - pin: int or str - GPIO pin number or name
18
        - active_high: bool - True if on() sets pin HIGH, False if on() sets pin LOW
19
        - initial_value: bool or None - Initial state (False=off, True=on, None=current)
20
        - pin_factory: Factory or None - Pin factory for advanced usage
21
        """
22

23
    def on(self):
24
        """Turn the device on."""
25

26
    def off(self):
27
        """Turn the device off."""
28

29
    def toggle(self):
30
        """Reverse the current state of the device."""
31

32
    @property
33
    def value(self) -> float:
34
        """Current device value (0.0 for off, 1.0 for on)."""
35

36
    @value.setter
37
    def value(self, value: float): ...
38

39
    @property
40
    def active_high(self) -> bool:
41
        """True if on() sets pin HIGH, False if on() sets pin LOW."""
42

43
    @active_high.setter
44
    def active_high(self, value: bool): ...
45

46
    @property
47
    def is_active(self) -> bool:
48
        """Returns True if device is currently active (on)."""
49
```
50

51
### DigitalOutputDevice
52

53
Base class for simple on/off output devices.
54

55
```python { .api }
56
class DigitalOutputDevice(OutputDevice):
57
    def __init__(self, pin=None, *, active_high=True, initial_value=False, pin_factory=None):
58
        """
59
        Digital output device with simple on/off control.
60
        
61
        Parameters:
62
        - pin: int or str - GPIO pin number or name
63
        - active_high: bool - True if on() sets pin HIGH, False if on() sets pin LOW
64
        - initial_value: bool or None - Initial state
65
        - pin_factory: Factory or None - Pin factory for advanced usage
66
        """
67

68
    def blink(self, on_time: float = 1, off_time: float = 1, n: int = None, background: bool = True):
69
        """
70
        Blink the device on and off repeatedly.
71
        
72
        Parameters:
73
        - on_time: float - Time in seconds to stay on
74
        - off_time: float - Time in seconds to stay off
75
        - n: int or None - Number of blinks (None for infinite)
76
        - background: bool - If True, blink in background thread
77
        """
78
```
79

80
### PWMOutputDevice
81

82
Base class for devices that support PWM (pulse-width modulation).
83

84
```python { .api }
85
class PWMOutputDevice(OutputDevice):
86
    def __init__(self, pin=None, *, active_high=True, initial_value=0, frequency=1000, pin_factory=None):
87
        """
88
        PWM output device with variable intensity control.
89
        
90
        Parameters:
91
        - pin: int or str - GPIO pin number or name
92
        - active_high: bool - True if higher values mean more active
93
        - initial_value: float - Initial PWM value (0.0-1.0)
94
        - frequency: float - PWM frequency in Hz
95
        - pin_factory: Factory or None - Pin factory for advanced usage
96
        """
97

98
    def pulse(self, fade_in_time: float = 1, fade_out_time: float = 1, n: int = None, background: bool = True):
99
        """
100
        Pulse the device by fading in and out repeatedly.
101
        
102
        Parameters:
103
        - fade_in_time: float - Time in seconds to fade in
104
        - fade_out_time: float - Time in seconds to fade out
105
        - n: int or None - Number of pulses (None for infinite)
106
        - background: bool - If True, pulse in background thread
107
        """
108

109
    @property
110
    def frequency(self) -> float:
111
        """PWM frequency in Hz."""
112

113
    @frequency.setter
114
    def frequency(self, value: float): ...
115

116
    @property
117
    def is_active(self) -> bool:
118
        """Returns True if PWM value > 0."""
119
```
120

121
## LED Devices
122

123
### LED
124

125
Simple on/off LED control.
126

127
```python { .api }
128
class LED(DigitalOutputDevice):
129
    def __init__(self, pin=None, *, active_high=True, initial_value=False, pin_factory=None):
130
        """
131
        Light Emitting Diode.
132
        
133
        Parameters:
134
        - pin: int or str - GPIO pin number or name
135
        - active_high: bool - True if LED is on when pin is HIGH
136
        - initial_value: bool - Initial state (False=off, True=on)
137
        - pin_factory: Factory or None - Pin factory for advanced usage
138
        """
139
```
140

141
### PWMLED
142

143
LED with brightness control via PWM.
144

145
```python { .api }
146
class PWMLED(PWMOutputDevice):
147
    def __init__(self, pin=None, *, active_high=True, initial_value=0, frequency=1000, pin_factory=None):
148
        """
149
        PWM-controlled LED with brightness control.
150
        
151
        Parameters:
152
        - pin: int or str - GPIO pin number or name
153
        - active_high: bool - True if brighter values mean higher voltage
154
        - initial_value: float - Initial brightness (0.0-1.0)
155
        - frequency: float - PWM frequency in Hz
156
        - pin_factory: Factory or None - Pin factory for advanced usage
157
        """
158

159
    @property
160
    def brightness(self) -> float:
161
        """Current brightness level (0.0-1.0)."""
162

163
    @brightness.setter
164
    def brightness(self, value: float): ...
165
```
166

167
### RGBLED
168

169
RGB LED with individual red, green, and blue control.
170

171
```python { .api }
172
class RGBLED(SourceMixin, CompositeDevice):
173
    def __init__(self, red=None, green=None, blue=None, *, active_high=True, initial_value=(0, 0, 0), pwm=True, pin_factory=None):
174
        """
175
        RGB LED with color control.
176
        
177
        Parameters:
178
        - red: int or str - Red component pin number or name
179
        - green: int or str - Green component pin number or name
180
        - blue: int or str - Blue component pin number or name
181
        - active_high: bool - True if higher values mean brighter colors
182
        - initial_value: tuple - Initial (red, green, blue) values (0.0-1.0 each)
183
        - pwm: bool - True for PWM control, False for digital on/off
184
        - pin_factory: Factory or None - Pin factory for advanced usage
185
        """
186

187
    @property
188
    def color(self) -> tuple:
189
        """Current color as (red, green, blue) tuple (0.0-1.0 each)."""
190

191
    @color.setter
192
    def color(self, value: tuple): ...
193

194
    @property
195
    def red(self) -> float:
196
        """Red component intensity (0.0-1.0)."""
197

198
    @red.setter
199
    def red(self, value: float): ...
200

201
    @property
202
    def green(self) -> float:
203
        """Green component intensity (0.0-1.0)."""
204

205
    @green.setter
206
    def green(self, value: float): ...
207

208
    @property
209
    def blue(self) -> float:
210
        """Blue component intensity (0.0-1.0)."""
211

212
    @blue.setter
213
    def blue(self, value: float): ...
214

215
    def on(self):
216
        """Turn on all color components."""
217

218
    def off(self):
219
        """Turn off all color components."""
220

221
    def toggle(self):
222
        """Toggle all color components."""
223

224
    def pulse(self, fade_in_time: float = 1, fade_out_time: float = 1, n: int = None, background: bool = True):
225
        """Pulse all color components."""
226

227
    def blink(self, on_time: float = 1, off_time: float = 1, fade_in_time: float = 0, fade_out_time: float = 0, n: int = None, background: bool = True):
228
        """Blink all color components with optional fading."""
229
```
230

231
## Motor Devices
232

233
### Motor
234

235
DC motor with forward and reverse control.
236

237
```python { .api }
238
class Motor(SourceMixin, CompositeDevice):
239
    def __init__(self, forward=None, backward=None, *, enable=None, pwm=True, pin_factory=None):
240
        """
241
        DC motor with directional control.
242
        
243
        Parameters:
244
        - forward: int or str - Forward control pin number or name
245
        - backward: int or str - Backward control pin number or name
246
        - enable: int or str or None - Enable pin number or name (for 3-pin control)
247
        - pwm: bool - True for PWM speed control, False for on/off only
248
        - pin_factory: Factory or None - Pin factory for advanced usage
249
        """
250

251
    def forward(self, speed: float = 1):
252
        """Move motor forward at specified speed (0.0-1.0)."""
253

254
    def backward(self, speed: float = 1):
255
        """Move motor backward at specified speed (0.0-1.0)."""
256

257
    def reverse(self):
258
        """Reverse current motor direction."""
259

260
    def stop(self):
261
        """Stop the motor."""
262

263
    @property
264
    def value(self) -> float:
265
        """Current motor speed (-1.0 to 1.0, negative for backward)."""
266

267
    @value.setter
268
    def value(self, speed: float): ...
269

270
    @property
271
    def is_active(self) -> bool:
272
        """Returns True if motor is currently running."""
273
```
274

275
### PhaseEnableMotor
276

277
Motor with phase/enable control (single direction pin + enable).
278

279
```python { .api }
280
class PhaseEnableMotor(SourceMixin, CompositeDevice):
281
    def __init__(self, phase=None, enable=None, *, pwm=True, pin_factory=None):
282
        """
283
        Phase/enable motor controller.
284
        
285
        Parameters:
286
        - phase: int or str - Phase (direction) pin number or name
287
        - enable: int or str - Enable (speed) pin number or name
288
        - pwm: bool - True for PWM speed control on enable pin
289
        - pin_factory: Factory or None - Pin factory for advanced usage
290
        """
291

292
    def forward(self, speed: float = 1):
293
        """Move motor forward at specified speed."""
294

295
    def backward(self, speed: float = 1):
296
        """Move motor backward at specified speed."""
297

298
    def reverse(self):
299
        """Reverse current motor direction."""
300

301
    def stop(self):
302
        """Stop the motor."""
303

304
    @property
305
    def value(self) -> float:
306
        """Current motor speed (-1.0 to 1.0)."""
307

308
    @value.setter
309
    def value(self, speed: float): ...
310
```
311

312
## Servo Devices
313

314
### Servo
315

316
Standard servo motor with position control.
317

318
```python { .api }
319
class Servo(PWMOutputDevice):
320
    def __init__(self, pin=None, *, initial_value=0, min_pulse_width=1/1000, max_pulse_width=2/1000, frame_width=20/1000, pin_factory=None):
321
        """
322
        Servo motor with position control.
323
        
324
        Parameters:
325
        - pin: int or str - GPIO pin number or name (PWM capable)
326
        - initial_value: float - Initial position (-1.0 to 1.0)
327
        - min_pulse_width: float - Minimum pulse width in seconds
328
        - max_pulse_width: float - Maximum pulse width in seconds
329
        - frame_width: float - Pulse frame width in seconds
330
        - pin_factory: Factory or None - Pin factory for advanced usage
331
        """
332

333
    def min(self):
334
        """Move servo to minimum position."""
335

336
    def mid(self):
337
        """Move servo to middle position."""
338

339
    def max(self):
340
        """Move servo to maximum position."""
341

342
    @property
343
    def min_pulse_width(self) -> float:
344
        """Minimum pulse width in seconds."""
345

346
    @property
347
    def max_pulse_width(self) -> float:
348
        """Maximum pulse width in seconds."""
349

350
    @property
351
    def frame_width(self) -> float:
352
        """Pulse frame width in seconds."""
353

354
    @property
355
    def pulse_width(self) -> float:
356
        """Current pulse width in seconds."""
357

358
    @pulse_width.setter
359
    def pulse_width(self, value: float): ...
360
```
361

362
### AngularServo
363

364
Servo with angular position measurement.
365

366
```python { .api }
367
class AngularServo(Servo):
368
    def __init__(self, pin=None, *, initial_angle=0, min_angle=-90, max_angle=90, min_pulse_width=1/1000, max_pulse_width=2/1000, frame_width=20/1000, pin_factory=None):
369
        """
370
        Servo with angular position control.
371
        
372
        Parameters:
373
        - pin: int or str - GPIO pin number or name
374
        - initial_angle: float - Initial angle in degrees
375
        - min_angle: float - Minimum angle in degrees
376
        - max_angle: float - Maximum angle in degrees
377
        - min_pulse_width: float - Minimum pulse width in seconds
378
        - max_pulse_width: float - Maximum pulse width in seconds
379
        - frame_width: float - Pulse frame width in seconds
380
        - pin_factory: Factory or None - Pin factory for advanced usage
381
        """
382

383
    @property
384
    def angle(self) -> float:
385
        """Current angle in degrees."""
386

387
    @angle.setter
388
    def angle(self, value: float): ...
389

390
    @property
391
    def min_angle(self) -> float:
392
        """Minimum angle in degrees."""
393

394
    @property
395
    def max_angle(self) -> float:
396
        """Maximum angle in degrees."""
397
```
398

399
## Buzzer Devices
400

401
### Buzzer
402

403
Simple on/off buzzer.
404

405
```python { .api }
406
class Buzzer(DigitalOutputDevice):
407
    def __init__(self, pin=None, *, active_high=True, initial_value=False, pin_factory=None):
408
        """
409
        Simple buzzer or beeper.
410
        
411
        Parameters:
412
        - pin: int or str - GPIO pin number or name
413
        - active_high: bool - True if buzzer sounds when pin is HIGH
414
        - initial_value: bool - Initial state
415
        - pin_factory: Factory or None - Pin factory for advanced usage
416
        """
417

418
    def beep(self, on_time: float = 1, off_time: float = 1, n: int = None, background: bool = True):
419
        """
420
        Beep the buzzer on and off repeatedly.
421
        
422
        Parameters:
423
        - on_time: float - Time in seconds to stay on
424
        - off_time: float - Time in seconds to stay off  
425
        - n: int or None - Number of beeps (None for infinite)
426
        - background: bool - If True, beep in background thread
427
        """
428
```
429

430
### TonalBuzzer
431

432
Buzzer with tone generation capabilities.
433

434
```python { .api }
435
class TonalBuzzer(PWMOutputDevice):
436
    def __init__(self, pin=None, *, initial_value=None, mid_tone=Tone(440.0), octaves=1, pin_factory=None):
437
        """
438
        Buzzer with tone generation.
439
        
440
        Parameters:
441
        - pin: int or str - GPIO pin number or name (PWM capable)
442
        - initial_value: Tone or None - Initial tone to play
443
        - mid_tone: Tone - Middle tone for value calculations
444
        - octaves: int - Number of octaves above and below mid_tone
445
        - pin_factory: Factory or None - Pin factory for advanced usage
446
        """
447

448
    def play(self, tone: 'Tone'):
449
        """Play a specific tone."""
450

451
    def stop(self):
452
        """Stop playing the current tone."""
453

454
    @property
455
    def tone(self) -> 'Tone':
456
        """Currently playing tone."""
457

458
    @tone.setter
459
    def tone(self, value: 'Tone'): ...
460

461
    @property
462
    def mid_tone(self) -> 'Tone':
463
        """Middle tone for value calculations."""
464

465
    @property
466
    def octaves(self) -> int:
467
        """Number of octaves above and below mid_tone."""
468

469
    @property
470
    def is_active(self) -> bool:
471
        """Returns True if currently playing a tone."""
472
```
473

474
## Musical Tone Class
475

476
### Tone
477

478
Musical tone representation for use with TonalBuzzer.
479

480
```python { .api }
481
class Tone(float):
482
    def __init__(self, value=None, *, frequency=None, midi=None, note=None):
483
        """
484
        Musical tone representation supporting multiple formats.
485
        
486
        Parameters:
487
        - value: float or int - Frequency in Hz or MIDI note number (auto-detected)
488
        - frequency: float - Explicit frequency in Hz
489
        - midi: int - MIDI note number (0-127)
490
        - note: str - Musical note string (e.g., 'A4', 'C#3', 'Bb2')
491
        """
492

493
    @classmethod
494
    def from_frequency(cls, frequency: float) -> 'Tone':
495
        """Create tone from frequency in Hz."""
496

497
    @classmethod
498
    def from_midi(cls, midi: int) -> 'Tone':
499
        """Create tone from MIDI note number (0-127)."""
500

501
    @classmethod
502
    def from_note(cls, note: str) -> 'Tone':
503
        """Create tone from musical note string (e.g., 'A4', 'C#3')."""
504

505
    @property
506
    def frequency(self) -> float:
507
        """Frequency in Hz."""
508

509
    @property
510
    def midi(self) -> int:
511
        """MIDI note number."""
512

513
    @property
514
    def note(self) -> str:
515
        """Musical note string representation."""
516

517
    def up(self, semitones: int = 1) -> 'Tone':
518
        """Return tone stepped up by specified semitones."""
519

520
    def down(self, semitones: int = 1) -> 'Tone':
521
        """Return tone stepped down by specified semitones."""
522
```
523

524
## Usage Examples
525

526
### Basic LED Control
527

528
```python
529
from gpiozero import LED
530
from time import sleep
531

532
led = LED(17)
533

534
# Simple on/off
535
led.on()
536
sleep(1)
537
led.off()
538

539
# Blinking
540
led.blink()  # Blink forever in background
541
sleep(10)
542
led.off()
543

544
# Custom blink pattern
545
led.blink(on_time=0.1, off_time=0.5, n=5)
546
```
547

548
### PWM LED Brightness Control
549

550
```python
551
from gpiozero import PWMLED
552
from time import sleep
553

554
led = PWMLED(17)
555

556
# Fade in and out
557
for brightness in range(100):
558
    led.brightness = brightness / 100.0
559
    sleep(0.01)
560

561
for brightness in range(100, 0, -1):
562
    led.brightness = brightness / 100.0
563
    sleep(0.01)
564

565
# Pulse automatically
566
led.pulse()
567
sleep(10)
568
led.off()
569
```
570

571
### RGB LED Color Control
572

573
```python
574
from gpiozero import RGBLED
575
from time import sleep
576

577
rgb = RGBLED(red=2, green=3, blue=4)
578

579
# Set colors
580
rgb.color = (1, 0, 0)    # Red
581
sleep(1)
582
rgb.color = (0, 1, 0)    # Green  
583
sleep(1)
584
rgb.color = (0, 0, 1)    # Blue
585
sleep(1)
586
rgb.color = (1, 1, 1)    # White
587
sleep(1)
588

589
# Individual components
590
rgb.red = 0.5
591
rgb.green = 0.3
592
rgb.blue = 0.8
593

594
# Color cycling
595
rgb.pulse()
596
sleep(10)
597
rgb.off()
598
```
599

600
### Motor Control
601

602
```python
603
from gpiozero import Motor
604
from time import sleep
605

606
motor = Motor(forward=2, backward=3)
607

608
# Basic movement
609
motor.forward()
610
sleep(2)
611
motor.backward()
612
sleep(2)
613
motor.stop()
614

615
# Speed control (if PWM enabled)
616
motor.forward(0.5)  # Half speed forward
617
sleep(2)
618
motor.backward(0.7)  # 70% speed backward
619
sleep(2)
620
motor.stop()
621

622
# Using value property
623
motor.value = 0.8   # 80% forward
624
sleep(2)
625
motor.value = -0.6  # 60% backward  
626
sleep(2)
627
motor.value = 0     # Stop
628
```
629

630
### Servo Position Control
631

632
```python
633
from gpiozero import Servo, AngularServo
634
from time import sleep
635

636
# Standard servo (-1 to 1)
637
servo = Servo(17)
638
servo.min()
639
sleep(1)
640
servo.mid()
641
sleep(1)
642
servo.max()
643
sleep(1)
644

645
# Angular servo with degrees
646
angular_servo = AngularServo(18, min_angle=-90, max_angle=90)
647
angular_servo.angle = -90
648
sleep(1)
649
angular_servo.angle = 0
650
sleep(1)
651
angular_servo.angle = 90
652
sleep(1)
653
```
654

655
### Buzzer Patterns
656

657
```python
658
from gpiozero import Buzzer, TonalBuzzer
659
from gpiozero.tones import Tone
660
from time import sleep
661

662
# Simple buzzer
663
buzzer = Buzzer(17)
664
buzzer.beep(on_time=0.1, off_time=0.1, n=3)
665
sleep(2)
666

667
# Tonal buzzer with melodies
668
tonal_buzzer = TonalBuzzer(18)
669
notes = [Tone(261.63), Tone(293.66), Tone(329.63), Tone(349.23)]  # C, D, E, F
670

671
for note in notes:
672
    tonal_buzzer.play(note)
673
    sleep(0.5)
674
    
675
tonal_buzzer.stop()
676

677
# Different ways to create tones
678
middle_c = Tone(frequency=261.63)  # Explicit frequency
679
concert_a = Tone(midi=69)          # MIDI note number
680
g_sharp = Tone(note='G#4')         # Musical note string
681

682
# Scale and melody examples
683
c_major_scale = [
684
    Tone('C4'), Tone('D4'), Tone('E4'), Tone('F4'),
685
    Tone('G4'), Tone('A4'), Tone('B4'), Tone('C5')
686
]
687

688
for tone in c_major_scale:
689
    tonal_buzzer.play(tone)
690
    sleep(0.3)
691
    print(f"Playing {tone.note} ({tone.frequency:.1f}Hz, MIDI#{tone.midi})")
692

693
tonal_buzzer.stop()
694
```