:mod:`pulseio`
==============
.. py:module:: pulseio
.. autoapi-nested-parse::
Support for individual pulse based protocols
The `pulseio` module contains classes to provide access to basic pulse IO.
Individual pulses are commonly used in infrared remotes and in DHT
temperature sensors.
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 :py:meth:`!deinit` or use a context manager. See
:ref:`lifetime-and-contextmanagers` for more info.
.. raw:: html
<p>
<details>
<summary>Available on these boards</summary>
<ul>
<li> AITHinker ESP32-C3S_Kit
<li> ARAMCON Badge 2019
<li> ARAMCON2 Badge
<li> ATMegaZero ESP32-S2
<li> Adafruit CLUE nRF52840 Express
<li> Adafruit Circuit Playground Bluefruit
<li> Adafruit Circuit Playground Express 4-H
<li> Adafruit CircuitPlayground Express
<li> Adafruit CircuitPlayground Express with Crickit libraries
<li> Adafruit CircuitPlayground Express with displayio
<li> Adafruit EdgeBadge
<li> Adafruit Feather Bluefruit Sense
<li> Adafruit Feather ESP32-S2 TFT
<li> Adafruit Feather ESP32S2
<li> Adafruit Feather M0 Express
<li> Adafruit Feather M0 Express with Crickit libraries
<li> Adafruit Feather M4 CAN
<li> Adafruit Feather M4 Express
<li> Adafruit Feather RP2040
<li> Adafruit Feather STM32F405 Express
<li> Adafruit Feather nRF52840 Express
<li> Adafruit FunHouse
<li> Adafruit Grand Central M4 Express
<li> Adafruit Hallowing M4 Express
<li> Adafruit ItsyBitsy M4 Express
<li> Adafruit ItsyBitsy RP2040
<li> Adafruit ItsyBitsy nRF52840 Express
<li> Adafruit KB2040
<li> Adafruit LED Glasses Driver nRF52840
<li> Adafruit Macropad RP2040
<li> Adafruit MagTag
<li> Adafruit Matrix Portal M4
<li> Adafruit Metro ESP32S2
<li> Adafruit Metro M0 Express
<li> Adafruit Metro M4 Airlift Lite
<li> Adafruit Metro M4 Express
<li> Adafruit Metro nRF52840 Express
<li> Adafruit Monster M4SK
<li> Adafruit PyGamer
<li> Adafruit PyPortal
<li> Adafruit PyPortal Pynt
<li> Adafruit PyPortal Titano
<li> Adafruit Pybadge
<li> Adafruit QT Py ESP32S2
<li> Adafruit QT Py M0 Haxpress
<li> Adafruit QT Py RP2040
<li> Adafruit QT2040 Trinkey
<li> Adafruit Trellis M4 Express
<li> AloriumTech Evo M51
<li> Arduino Nano 33 BLE
<li> Arduino Nano RP2040 Connect
<li> Artisense Reference Design RD00
<li> AtelierDuMaker nRF52840 Breakout
<li> BDMICRO VINA-D21
<li> BDMICRO VINA-D51
<li> BLE-SS dev board Multi Sensor
<li> BastBLE
<li> BastWiFi
<li> BlueMicro840
<li> CP Sapling M0 w/ SPI Flash
<li> CP32-M4
<li> Capable Robot Programmable USB Hub
<li> Cedar Grove StringCar M0 Express
<li> Challenger NB RP2040 WiFi
<li> Challenger RP2040 LTE
<li> Challenger RP2040 WiFi
<li> Circuit Playground Express Digi-Key PyCon 2019
<li> CircuitBrains Basic
<li> CircuitBrains Deluxe
<li> CrumpS2
<li> Cytron Maker Nano RP2040
<li> Cytron Maker Pi RP2040
<li> DynOSSAT-EDU-EPS
<li> DynOSSAT-EDU-OBC
<li> ESP 12k NodeMCU
<li> Electronic Cats Hunter Cat NFC
<li> Electronut Labs Blip
<li> Electronut Labs Papyr
<li> EncoderPad RP2040
<li> Espruino Pico
<li> Espruino Wifi
<li> Feather ESP32S2 without PSRAM
<li> FeatherS2
<li> FeatherS2 Neo
<li> FeatherS2 PreRelease
<li> Franzininho WIFI w/Wroom
<li> Franzininho WIFI w/Wrover
<li> Gravitech Cucumber M
<li> Gravitech Cucumber MS
<li> Gravitech Cucumber R
<li> Gravitech Cucumber RS
<li> HMI-DevKit-1.1
<li> Hacked Feather M0 Express with 8Mbyte SPI flash
<li> HalloWing M0 Express
<li> HiiBot BlueFi
<li> IkigaiSense Vita nRF52840
<li> Kaluga 1
<li> LILYGO TTGO T8 ESP32-S2 w/Display
<li> MDBT50Q-DB-40
<li> MDBT50Q-RX Dongle
<li> MEOWBIT
<li> MORPHEANS MorphESP-240
<li> MakerDiary nRF52840 MDK
<li> MakerDiary nRF52840 MDK USB Dongle
<li> Makerdiary M60 Keyboard
<li> Makerdiary Pitaya Go
<li> Makerdiary nRF52840 M.2 Developer Kit
<li> Melopero Shake RP2040
<li> MicroDev microC3
<li> MicroDev microS2
<li> Mini SAM M4
<li> NUCLEO STM32F746
<li> NUCLEO STM32F767
<li> Oak Dev Tech BREAD2040
<li> Oak Dev Tech PixelWing ESP32S2
<li> Open Hardware Summit 2020 Badge
<li> PCA10056 nRF52840-DK
<li> PCA10059 nRF52840 Dongle
<li> PCA10100 nRF52833 DK
<li> PYB LR Nano V2
<li> Particle Argon
<li> Particle Boron
<li> Particle Xenon
<li> Pimoroni Interstate 75
<li> Pimoroni Keybow 2040
<li> Pimoroni PGA2040
<li> Pimoroni Pico LiPo (16MB)
<li> Pimoroni Pico LiPo (4MB)
<li> Pimoroni PicoSystem
<li> Pimoroni Plasma 2040
<li> Pimoroni Tiny 2040
<li> PyCubedv04
<li> PyCubedv04-MRAM
<li> PyCubedv05
<li> PyCubedv05-MRAM
<li> PyKey60
<li> PyboardV1_1
<li> RP2040 Stamp
<li> Raspberry Pi Pico
<li> Robo HAT MM1 M4
<li> S2Mini
<li> S2Pico
<li> SAM E54 Xplained Pro
<li> SAM32v26
<li> SPRESENSE
<li> ST STM32F746G Discovery
<li> STM32F411E_DISCO
<li> STM32F412G_DISCO
<li> STM32F4_DISCO
<li> Saola 1 w/Wroom
<li> Saola 1 w/Wrover
<li> Seeeduino Wio Terminal
<li> Serpente
<li> Silicognition LLC M4-Shim
<li> SparkFun LUMIDrive
<li> SparkFun MicroMod RP2040 Processor
<li> SparkFun MicroMod SAMD51 Processor
<li> SparkFun MicroMod nRF52840 Processor
<li> SparkFun Pro Micro RP2040
<li> SparkFun Pro nRF52840 Mini
<li> SparkFun RedBoard Turbo
<li> SparkFun STM32 MicroMod Processor
<li> SparkFun Thing Plus - RP2040
<li> SparkFun Thing Plus - SAMD51
<li> Sprite_v2b
<li> StackRduino M0 PRO
<li> Swan R5
<li> TG-Boards' Datalore IP M4
<li> TG-Watch
<li> THUNDERPACK_v11
<li> THUNDERPACK_v12
<li> Targett Module Clip w/Wroom
<li> Targett Module Clip w/Wrover
<li> Teknikio Bluebird
<li> The Open Book Feather
<li> Thingz - Galaxia
<li> TinkeringTech ScoutMakes Azul
<li> TinyS2
<li> Trinket M0 Haxpress
<li> UARTLogger II
<li> WarmBit BluePixel nRF52840
<li> Winterbloom Big Honking Button
<li> Winterbloom Sol
<li> keithp.com snekboard
<li> micro:bit v2
<li> nanoESP32-S2 w/Wrover
<li> nanoESP32-S2 w/Wroom
<li> nice!nano
<li> stm32f411ce-blackpill
<li> stm32f411ce-blackpill-with-flash
</ul>
</details>
</p>
.. py:class:: PulseIn(pin: microcontroller.Pin, maxlen: int = 2, *, idle_state: bool = False)
Measure a series of active and idle pulses. This is commonly used in infrared receivers
and low cost temperature sensors (DHT). The pulsed signal consists of timed active and
idle periods. Unlike PWM, there is no set duration for active and idle pairs.
Create a PulseIn object associated with the given pin. The object acts as
a read-only sequence of pulse lengths with a given max length. When it is
active, new pulse lengths are added to the end of the list. When there is
no more room (len() == `maxlen`) the oldest pulse length is removed to
make room.
:param ~microcontroller.Pin pin: Pin to read pulses from.
:param int maxlen: Maximum number of pulse durations to store at once
:param bool idle_state: Idle state of the pin. At start and after `resume`
the first recorded pulse will the opposite state from idle.
Read a short series of pulses::
import pulseio
import board
pulses = pulseio.PulseIn(board.D7)
# Wait for an active pulse
while len(pulses) == 0:
pass
# Pause while we do something with the pulses
pulses.pause()
# Print the pulses. pulses[0] is an active pulse unless the length
# reached max length and idle pulses are recorded.
print(pulses)
# Clear the rest
pulses.clear()
# Resume with an 80 microsecond active pulse
pulses.resume(80)
.. py:attribute:: maxlen
:annotation: :int
The maximum length of the PulseIn. When len() is equal to maxlen,
it is unclear which pulses are active and which are idle.
.. py:attribute:: paused
:annotation: :bool
True when pulse capture is paused as a result of :py:func:`pause` or an error during capture
such as a signal that is too fast.
.. py:method:: deinit() -> None
Deinitialises the PulseIn and releases any hardware resources for reuse.
.. py:method:: __enter__() -> PulseIn
No-op used by Context Managers.
.. py:method:: __exit__() -> None
Automatically deinitializes the hardware when exiting a context. See
:ref:`lifetime-and-contextmanagers` for more info.
.. py:method:: pause() -> None
Pause pulse capture
.. py:method:: resume(trigger_duration: int = 0) -> None
Resumes pulse capture after an optional trigger pulse.
.. warning:: Using trigger pulse with a device that drives both high and
low signals risks a short. Make sure your device is open drain (only
drives low) when using a trigger pulse. You most likely added a
"pull-up" resistor to your circuit to do this.
:param int trigger_duration: trigger pulse duration in microseconds
.. py:method:: clear() -> None
Clears all captured pulses
.. py:method:: popleft() -> int
Removes and returns the oldest read pulse.
.. py:method:: __bool__() -> bool
.. py:method:: __len__() -> int
Returns the number of pulse durations currently stored.
This allows you to::
pulses = pulseio.PulseIn(pin)
print(len(pulses))
.. py:method:: __getitem__(index: int) -> Optional[int]
Returns the value at the given index or values in slice.
This allows you to::
pulses = pulseio.PulseIn(pin)
print(pulses[0])
.. py:class:: PulseOut(pin: microcontroller.Pin, *, frequency: int = 38000, duty_cycle: int = 1 << 15)
Pulse PWM "carrier" output on and off. This is commonly used in infrared remotes. The
pulsed signal consists of timed on and off periods. Unlike PWM, there is no set duration
for on and off pairs.
Create a PulseOut object associated with the given pin.
:param ~microcontroller.Pin pin: Signal output pin
:param int frequency: Carrier signal frequency in Hertz
:param int duty_cycle: 16-bit duty cycle of carrier frequency (0 - 65536)
For backwards compatibility, ``pin`` may be a PWMOut object used as the carrier. This
compatibility will be removed in CircuitPython 8.0.0.
Send a short series of pulses::
import array
import pulseio
import pwmio
import board
# 50% duty cycle at 38kHz.
pwm = pulseio.PulseOut(board.LED, frequency=38000, duty_cycle=32768)
# on off on off on
pulses = array.array('H', [65000, 1000, 65000, 65000, 1000])
pulse.send(pulses)
# Modify the array of pulses.
pulses[0] = 200
pulse.send(pulses)
.. py:method:: deinit() -> None
Deinitialises the PulseOut and releases any hardware resources for reuse.
.. py:method:: __enter__() -> PulseOut
No-op used by Context Managers.
.. py:method:: __exit__() -> None
Automatically deinitializes the hardware when exiting a context. See
:ref:`lifetime-and-contextmanagers` for more info.
.. py:method:: send(pulses: _typing.ReadableBuffer) -> None
Pulse alternating on and off durations in microseconds starting with on.
``pulses`` must be an `array.array` with data type 'H' for unsigned
halfword (two bytes).
This method waits until the whole array of pulses has been sent and
ensures the signal is off afterwards.
:param array.array pulses: pulse durations in microseconds