`pwmio` – Support for PWM based protocols¶

The pwmio module contains classes to provide access to basic pulse IO.

All classes change hardware state and should be deinitialized when they are no longer needed if the program continues after use. To do so, either call deinit() or use a context manager. See Lifetime and ContextManagers for more info.

For example:

import time
import pwmio
import board

pwm = pwmio.PWMOut(board.LED)
pwm.duty_cycle = 2 ** 15
time.sleep(0.1)

This example will initialize the the device, set duty_cycle, and then sleep 0.1 seconds. CircuitPython will automatically turn off the PWM when it resets all hardware after program completion. Use deinit() or a with statement to do it yourself.

Available on these boards

8086 Commander
@sarfata shIRtty
AITHinker ESP32-C3S_Kit
ARAMCON Badge 2019
ARAMCON2 Badge
ATMegaZero ESP32-S2
Adafruit CLUE nRF52840 Express
Adafruit Circuit Playground Bluefruit
Adafruit Circuit Playground Express 4-H
Adafruit CircuitPlayground Express
Adafruit CircuitPlayground Express with Crickit libraries
Adafruit CircuitPlayground Express with displayio
Adafruit EdgeBadge
Adafruit Feather Bluefruit Sense
Adafruit Feather ESP32-S2 TFT
Adafruit Feather ESP32S2
Adafruit Feather M0 Adalogger
Adafruit Feather M0 Basic
Adafruit Feather M0 Express
Adafruit Feather M0 Express with Crickit libraries
Adafruit Feather M0 RFM69
Adafruit Feather M0 RFM9x
Adafruit Feather M4 CAN
Adafruit Feather M4 Express
Adafruit Feather MIMXRT1011
Adafruit Feather RP2040
Adafruit Feather STM32F405 Express
Adafruit Feather nRF52840 Express
Adafruit FunHouse
Adafruit Gemma M0
Adafruit Gemma M0 PyCon 2018
Adafruit Grand Central M4 Express
Adafruit Hallowing M4 Express
Adafruit ItsyBitsy M0 Express
Adafruit ItsyBitsy M4 Express
Adafruit ItsyBitsy RP2040
Adafruit ItsyBitsy nRF52840 Express
Adafruit KB2040
Adafruit LED Glasses Driver nRF52840
Adafruit Macropad RP2040
Adafruit MagTag
Adafruit Matrix Portal M4
Adafruit Metro ESP32S2
Adafruit Metro M0 Express
Adafruit Metro M4 Airlift Lite
Adafruit Metro M4 Express
Adafruit Metro nRF52840 Express
Adafruit Monster M4SK
Adafruit PyGamer
Adafruit PyPortal
Adafruit PyPortal Pynt
Adafruit PyPortal Titano
Adafruit PyRuler
Adafruit Pybadge
Adafruit QT Py ESP32S2
Adafruit QT Py M0
Adafruit QT Py M0 Haxpress
Adafruit QT Py RP2040
Adafruit QT2040 Trinkey
Adafruit Trellis M4 Express
Adafruit Trinket M0
AloriumTech Evo M51
Arduino MKR Zero
Arduino MKR1300
Arduino Nano 33 BLE
Arduino Nano 33 IoT
Arduino Nano RP2040 Connect
Arduino Zero
Artisense Reference Design RD00
AtelierDuMaker nRF52840 Breakout
BDMICRO VINA-D21
BDMICRO VINA-D51
BLE-SS dev board Multi Sensor
BastBLE
BastWiFi
BlueMicro840
CP Sapling M0
CP Sapling M0 w/ SPI Flash
CP32-M4
Capable Robot Programmable USB Hub
Cedar Grove StringCar M0 Express
Challenger NB RP2040 WiFi
Challenger RP2040 LTE
Challenger RP2040 WiFi
Circuit Playground Express Digi-Key PyCon 2019
CircuitBrains Basic
CircuitBrains Deluxe
CrumpS2
Cytron Maker Nano RP2040
Cytron Maker Pi RP2040
DynOSSAT-EDU-EPS
DynOSSAT-EDU-OBC
DynaLoRa_USB
ESP 12k NodeMCU
Electronic Cats Bast Pro Mini M0
Electronic Cats CatWAN USBStick
Electronic Cats Hunter Cat NFC
Electronic Cats NFC Copy Cat
Electronut Labs Blip
Electronut Labs Papyr
EncoderPad RP2040
Escornabot Makech
Espruino Pico
Espruino Wifi
Feather ESP32S2 without PSRAM
Feather MIMXRT1011
Feather MIMXRT1062
FeatherS2
FeatherS2 Neo
FeatherS2 PreRelease
Fluff M0
Franzininho WIFI w/Wroom
Franzininho WIFI w/Wrover
Gravitech Cucumber M
Gravitech Cucumber MS
Gravitech Cucumber R
Gravitech Cucumber RS
HMI-DevKit-1.1
Hacked Feather M0 Express with 8Mbyte SPI flash
HalloWing M0 Express
HiiBot BlueFi
IMXRT1010-EVK
IkigaiSense Vita nRF52840
J&J Studios datum-Distance
J&J Studios datum-IMU
J&J Studios datum-Light
J&J Studios datum-Weather
Kaluga 1
LILYGO TTGO T8 ESP32-S2 w/Display
LoC BeR M4 base board
MDBT50Q-DB-40
MDBT50Q-RX Dongle
MEOWBIT
MORPHEANS MorphESP-240
MakerDiary nRF52840 MDK
MakerDiary nRF52840 MDK USB Dongle
Makerdiary M60 Keyboard
Makerdiary Pitaya Go
Makerdiary nRF52840 M.2 Developer Kit
Melopero Shake RP2040
Metro MIMXRT1011
MicroDev microC3
MicroDev microS2
Mini SAM M4
NUCLEO STM32F746
NUCLEO STM32F767
Oak Dev Tech BREAD2040
Oak Dev Tech PixelWing ESP32S2
Open Hardware Summit 2020 Badge
PCA10056 nRF52840-DK
PCA10059 nRF52840 Dongle
PCA10100 nRF52833 DK
PYB LR Nano V2
Particle Argon
Particle Boron
Particle Xenon
PewPew 10.2
PewPew 13
PicoPlanet
Pimoroni Interstate 75
Pimoroni Keybow 2040
Pimoroni PGA2040
Pimoroni Pico LiPo (16MB)
Pimoroni Pico LiPo (4MB)
Pimoroni PicoSystem
Pimoroni Plasma 2040
Pimoroni Tiny 2040
PyCubedv04
PyCubedv04-MRAM
PyCubedv05
PyCubedv05-MRAM
PyKey60
PyboardV1_1
RP2040 Stamp
Raspberry Pi Pico
Robo HAT MM1 M4
S2Mini
S2Pico
SAM E54 Xplained Pro
SAM32v26
SPRESENSE
ST STM32F746G Discovery
STM32F411E_DISCO
STM32F412G_DISCO
STM32F4_DISCO
Saola 1 w/Wroom
Saola 1 w/Wrover
Seeeduino Wio Terminal
Seeeduino XIAO
Seeeduino XIAO KB
Serpente
Silicognition LLC M4-Shim
Simmel
SparkFun LUMIDrive
SparkFun MicroMod RP2040 Processor
SparkFun MicroMod SAMD51 Processor
SparkFun MicroMod nRF52840 Processor
SparkFun Pro Micro RP2040
SparkFun Pro nRF52840 Mini
SparkFun Qwiic Micro
SparkFun RedBoard Turbo
SparkFun SAMD21 Dev Breakout
SparkFun SAMD21 Mini Breakout
SparkFun STM32 MicroMod Processor
SparkFun Thing Plus - RP2040
SparkFun Thing Plus - SAMD51
Sprite_v2b
StackRduino M0 PRO
Swan R5
TG-Boards' Datalore IP M4
TG-Watch
THUNDERPACK_v11
THUNDERPACK_v12
Targett Module Clip w/Wroom
Targett Module Clip w/Wrover
Teensy 4.0
Teensy 4.1
Teknikio Bluebird
The Open Book Feather
Thingz - Galaxia
TinkeringTech ScoutMakes Azul
TinyS2
Trinket M0 Haxpress
UARTLogger II
WarmBit BluePixel nRF52840
Winterbloom Big Honking Button
Winterbloom Sol
XinaBox CC03
XinaBox CS11
iMX RT 1020 EVK
iMX RT 1060 EVK
keithp.com snekboard
micro:bit v2
nanoESP32-S2 w/Wrover
nanoESP32-S2 w/Wroom
ndGarage[n°] Bit6: FeatherSnow-v2
ndGarage[n°]Bit6:FeatherSnow
nice!nano
senseBox MCU
stm32f411ce-blackpill
stm32f411ce-blackpill-with-flash
uChip
uGame10

class pwmio.PWMOut(pin: microcontroller.Pin, *, duty_cycle: int = 0, frequency: int = 500, variable_frequency: bool = False)¶

Output a Pulse Width Modulated signal on a given pin.

Create a PWM object associated with the given pin. This allows you to write PWM signals out on the given pin. Frequency is fixed after init unless variable_frequency is True.

Note

When variable_frequency is True, further PWM outputs may be limited because it may take more internal resources to be flexible. So, when outputting both fixed and flexible frequency signals construct the fixed outputs first.

Paramètres:

pin (Pin) – The pin to output to
duty_cycle (int) – The fraction of each pulse which is high. 16-bit
frequency (int) – The target frequency in Hertz (32-bit)
variable_frequency (bool) – True if the frequency will change over time

Simple LED on:

import pwmio
import board

pwm = pwmio.PWMOut(board.LED)

while True:
    pwm.duty_cycle = 2 ** 15  # Cycles the pin with 50% duty cycle (half of 2 ** 16) at the default 500hz

PWM LED fade:

import pwmio
import board

pwm = pwmio.PWMOut(board.LED)  # output on LED pin with default of 500Hz

while True:
    for cycle in range(0, 65535):  # Cycles through the full PWM range from 0 to 65535
        pwm.duty_cycle = cycle  # Cycles the LED pin duty cycle through the range of values
    for cycle in range(65534, 0, -1):  # Cycles through the PWM range backwards from 65534 to 0
        pwm.duty_cycle = cycle  # Cycles the LED pin duty cycle through the range of values

PWM at specific frequency (servos and motors):

import pwmio
import board

pwm = pwmio.PWMOut(board.D13, frequency=50)
pwm.duty_cycle = 2 ** 15  # Cycles the pin with 50% duty cycle (half of 2 ** 16) at 50hz

Variable frequency (usually tones):

import pwmio
import board
import time

pwm = pwmio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=440, variable_frequency=True)
time.sleep(0.2)
pwm.frequency = 880
time.sleep(0.1)

duty_cycle :int¶

16 bit value that dictates how much of one cycle is high (1) versus low (0). 0xffff will always be high, 0 will always be low and 0x7fff will be half high and then half low.

Depending on how PWM is implemented on a specific board, the internal representation for duty cycle might have less than 16 bits of resolution. Reading this property will return the value from the internal representation, so it may differ from the value set.

frequency :int¶

32 bit value that dictates the PWM frequency in Hertz (cycles per second). Only writeable when constructed with variable_frequency=True.

Depending on how PWM is implemented on a specific board, the internal value for the PWM’s duty cycle may need to be recalculated when the frequency changes. In these cases, the duty cycle is automatically recalculated from the original duty cycle value. This should happen without any need to manually re-set the duty cycle.

deinit() → None¶: Deinitialises the PWMOut and releases any hardware resources for reuse.

__enter__() → PWMOut¶: No-op used by Context Managers.

__exit__() → None¶: Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

pwmio – Support for PWM based protocols¶

`pwmio` – Support for PWM based protocols¶