pulseio – 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.

Warning

PWMOut is moving to pwmio and will be removed from pulseio in CircuitPython 7.

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.

class pulseio.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.

Parameters:
  • pin (Pin) – Pin to read pulses from.
  • maxlen (int) – Maximum number of pulse durations to store at once
  • idle_state (bool) – 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)
maxlen :int

The maximum length of the PulseIn. When len() is equal to maxlen, it is unclear which pulses are active and which are idle.

paused :bool

True when pulse capture is paused as a result of pause() or an error during capture such as a signal that is too fast.

deinit(self)

Deinitialises the PulseIn and releases any hardware resources for reuse.

__enter__(self)

No-op used by Context Managers.

__exit__(self)

Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

pause(self)

Pause pulse capture

resume(self, trigger_duration: int = 0)

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.

Parameters:trigger_duration (int) – trigger pulse duration in microseconds
clear(self)

Clears all captured pulses

popleft(self)

Removes and returns the oldest read pulse.

__bool__(self)
__len__(self)

Returns the current pulse length

This allows you to:

pulses = pulseio.PulseIn(pin)
print(len(pulses))
__getitem__(self, index: int)

Returns the value at the given index or values in slice.

This allows you to:

pulses = pulseio.PulseIn(pin)
print(pulses[0])
class pulseio.PulseOut(carrier: pwmio.PWMOut)

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 PWMout object.

Parameters:carrier (PWMOut) – PWMOut that is set to output on the desired pin.

Send a short series of pulses:

import array
import pulseio
import pwmio
import board

# 50% duty cycle at 38kHz.
pwm = pwmio.PWMOut(board.D13, frequency=38000, duty_cycle=32768)
pulse = pulseio.PulseOut(pwm)
#                             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)
deinit(self)

Deinitialises the PulseOut and releases any hardware resources for reuse.

__enter__(self)

No-op used by Context Managers.

__exit__(self)

Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

send(self, pulses: ReadableBuffer)

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.

Parameters:pulses (array.array) – pulse durations in microseconds