CircuitPython PWM

Your board has pulseio support, which means you can PWM LEDs, control servos, beep piezos, and manage "pulse train" type devices like DHT22 and Infrared.

Nearly every pin has PWM support! For example, all ATSAMD21 board have an A0 pin which is 'true' analog out and does not have PWM support.

PWM with Fixed Frequency

This example will show you how to use PWM to fade the little red LED on your board.

Copy and paste the code into code.py using your favorite editor, and save the file.

import time

import board
import pulseio

led = pulseio.PWMOut(board.D13, frequency=5000, duty_cycle=0)

while True:
    for i in range(100):
        # PWM LED up and down
        if i < 50:
            led.duty_cycle = int(i * 2 * 65535 / 100)  # Up
        else:
            led.duty_cycle = 65535 - int((i - 50) * 2 * 65535 / 100)  # Down
        time.sleep(0.01)

Create a PWM Output

led = pulseio.PWMOut(board.D13, frequency=5000, duty_cycle=0)

Since we're using the onboard LED, we'll call the object led, use pulseio.PWMOut to create the output and pass in the D13 LED pin to use.

Main Loop

The main loop uses range() to cycle through the loop. When the range is below 50, it PWMs the LED brightness up, and when the range is above 50, it PWMs the brightness down. This is how it fades the LED brighter and dimmer!

The time.sleep() is needed to allow the PWM process to occur over a period of time. Otherwise it happens too quickly for you to see!

PWM Output with Variable Frequency

Fixed frequency outputs are great for pulsing LEDs or controlling servos. But if you want to make some beeps with a piezo, you'll need to vary the frequency.

The following example uses pulseio to make a series of tones on a piezo.

To use with any of the M0 boards, no changes to the following code are needed.

To use with the Metro M4 Express, you must comment out the piezo = pulseio.PWMOut(board.A2, duty_cycle=0, frequency=440, variable_frequency=True) line and uncomment the piezo = pulseio.PWMOut(board.A1, duty_cycle=0, frequency=440, variable_frequency=True) line. A2 is not a supported PWM pin on the Metro M4 Express!

Remember: To "comment out" a line, put a # and a space before it. To "uncomment" a line, remove the # + space from the beginning of the line.
import time

import board
import pulseio

# For the M0 boards:
piezo = pulseio.PWMOut(board.A2, duty_cycle=0,
                       frequency=440, variable_frequency=True)
# For Metro M4 Express:
# piezo = pulseio.PWMOut(
# board.A1, duty_cycle=0, frequency=440, variable_frequency=True
# )

while True:
    for f in (262, 294, 330, 349, 392, 440, 494, 523):
        piezo.frequency = f
        piezo.duty_cycle = 65536 // 2  # On 50%
        time.sleep(0.25)  # On for 1/4 second
        piezo.duty_cycle = 0  # Off
        time.sleep(0.05)  # Pause between notes
    time.sleep(0.5)

If you have simpleio library loaded into your /lib folder on your board, we have a nice little helper that makes a tone for you on a piezo with a single command.

To use with any of the M0 boards, no changes to the following code are needed.

To use with the Metro M4 Express, you must comment out the simpleio.tone(board.A1, f, 0.25) line and uncomment the simpleio.tone(board.A2, f, 0.25) line. A2 is not a supported PWM pin on the Metro M4 Express!

import time

import board
import simpleio

while True:
    for f in (262, 294, 330, 349, 392, 440, 494, 523):
        # For the M0 boards:
        simpleio.tone(board.A2, f, 0.25)  # on for 1/4 second
        # For the Metro M4 Express:
        # simpleio.tone(board.A1, f, 0.25)  # on for 1/4 second
        time.sleep(0.05)  # pause between notes
    time.sleep(0.5)

As you can see, it's much simpler!

Wire it up

Use the diagrams below to help you wire up your piezo. Attach one leg of the piezo to pin A2 and the other leg to ground. It doesn't matter which leg is connected to which pin. They're interchangeable!

Circuit Playground Express

 

Use alligator clips to attach A2 and any one of the GND to different legs of the piezo.

 

CPX has PWM on the following pins: A1, A2, A3, A6, RX, LIGHT, A8, TEMPERATURE, A9, BUTTON_B, D5, SLIDE_SWITCH, D7, D13, REMOTEIN, IR_RX, REMOTEOUT, IR_TX, IR_PROXIMITY, MICROPHONE_CLOCK, MICROPHONE_DATA, ACCELEROMETER_INTERRUPT, ACCELEROMETER_SDA, ACCELEROMETER_SCL, SPEAKER_ENABLE.

 

There is NO PWM on: A0, SPEAKER, A4, SCL, A5, SDA, A7, TX, BUTTON_A, D4, NEOPIXEL, D8, SCK, MOSI, MISO, FLASH_CS.

Trinket M0

 

Note: A2 on Trinket is also labeled Digital "0"!

 

Use jumper wires to connect GND and D0 to different legs of the piezo.

 

Trinket has PWM available on the following pins: D0, A2, SDA, D2, A1, SCL, MISO, D4, A4, TX, MOSI, D3, A3, RX, SCK, D13, APA102_MOSI, APA102_SCK.

 

There is NO PWM on: A0, D1.

Gemma M0

 

Use alligator clips to attach A2 and GND to different legs on the piezo.

 

Gemma has PWM available on the following pins: A1, D2, RX, SCL, A2, D0, TX, SDA, L, D13, APA102_MOSI, APA102_SCK.

 

There is NO PWM on: A0, D1.

Feather M0 Express

 

Use jumper wires to attach A2 and one of the two GND to different legs of the piezo.

 

Feather M0 Express has PWM on the following pins: A2, A3, A4, SCK, MOSI, MISO, D0, RX, D1, TX, SDA, SCL, D5, D6, D9, D10, D11, D12, D13, NEOPIXEL.

 

There is NO PWM on: A0, A1, A5.

ItsyBitsy M0 Express

 

Use jumper wires to attach A2 and G to different legs of the piezo.

 

ItsyBitsy M0 Express has PWM on the following pins: D0, RX, D1, TX, D2, D3, D4, D5, D6, D7, D8, D9, D10, D11, D12, D13, L, A2, A3, A4, MOSI, MISO, SCK, SCL, SDA, APA102_MOSI, APA102_SCK.

 

There is NO PWM on: A0, A1, A5.

Metro M0 Express

 

Use jumper wires to connect A2 and any one of the GND to different legs on the piezo.

 

Metro M0 Express has PWM on the following pins: A2, A3, A4, D0, RX, D1, TX, D2, D3, D4, D5, D6, D7, D8, D9, D10, D11, D12, D13, SDA, SCL, NEOPIXEL, SCK, MOSI, MISO.

 

There is NO PWM on: A0, A1, A5, FLASH_CS.

Metro M4 Express

 

Use jumper wires to connect A1 and any one of the GND to different legs on the piezo.

 

To use A1, comment out the current pin setup line, and uncomment the line labeled for Metro M4 Express. See the details above!


Metro M4 Express has PWM on: A1, A5, D0, RX, D1, TX, D2, D3, D4, D5, D6, D7, D8, D9, D10, D11, D12, D13, SDA, SCK, MOSI, MISO

 

There is No PWM on: A0, A2, A3, A4, SCL, AREF, NEOPIXEL, LED_RX, LED_TX.

Where's My PWM?

Want to check to see which pins have PWM yourself? We've written this handy script! It attempts to setup PWM on every pin available, and lets you know which ones work and which ones don't. Check it out!

import board
import pulseio

for pin_name in dir(board):
    pin = getattr(board, pin_name)
    try:
        p = pulseio.PWMOut(pin)
        p.deinit()
        print("PWM on:", pin_name)  # Prints the valid, PWM-capable pins!
    except ValueError:  # This is the error returned when the pin is invalid.
        print("No PWM on:", pin_name)  # Prints the invalid pins.
    except RuntimeError:  # Timer conflict error.
        print("Timers in use:", pin_name)  # Prints the timer conflict pins.
Last updated on Apr 19, 2018 Published on May 03, 2017