pulseio

Support for pulse based protocols

The pulseio 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 pulseio
import time
from board import *

pwm = pulseio.PWMOut(D13)
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.

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

duty_cycle :Any

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 :Any

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(self)

Deinitialises the PWMOut 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.

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.

maxlen :Any

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

paused :Any

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.

__len__(self)

Returns the current pulse length

This allows you to:

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

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

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: array.array)

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