Serial Wombat Arduino Library
Public Member Functions | Public Attributes | List of all members
SerialWombatPulseTimer Class Reference

A Class which uses a Serial Wombat pin to measure the length of a pulse high and low time. More...

#include <serialWombatPulseTimer.h>

Public Member Functions

 SerialWombatPulseTimer (SerialWombat &serialWombat)
 Class constructor for SerialWombatPulseTimer. More...
 
void begin (uint8_t pin)
 Simple initialization. More...
 
void begin (uint8_t pin, SerialWombatPulseTimerUnits units, bool pullUpEnabled)
 Initialization routine for SerialWombatPulseTimer. More...
 
void refresh ()
 Retreive the latest values for HighCounts, LowCounts, Pulses, and MeasurementOverflowOccured. More...
 
void refreshHighCountsLowCounts ()
 Retreive the High and Low counts from the Serial Wombat in a single transaction. More...
 
void refreshHighCountsPulses ()
 Retreive the High counts and number of pulses Serial Wombat in a single transaction. More...
 
uint16_t readHighCounts ()
 Retreives the most recent Counts in the configured units for the most recent high pulse. More...
 
uint16_t readLowCounts ()
 Retreives the most recent Counts in the configured units for the most recent low pulse. More...
 
uint16_t readPulses ()
 Retreives the number of pulses. More...
 

Public Attributes

uint16_t HighCounts = 0
 Count in selected units of last retreived high pulse. More...
 
uint16_t LowCounts = 0
 Count in selected units of last retreived low pulse. More...
 
uint16_t Pulses = 0
 Count of last retreived pulses. More...
 
bool MeasurementOverflowOccurred = false
 

Detailed Description

A Class which uses a Serial Wombat pin to measure the length of a pulse high and low time.

This class is used to measure the length of pulses in mS or in uS. On the Serial Wombat 4A/B the precision is about 8uS in uS mode, with an accuracy of +/- 2% because of variation in the Serial Wombat's internal oscillator.

One SerialWombatPulseTimer should be declared per Serial Wombat pin in this mode.

A video Tutorial on this pin mode is available:

https://youtu.be/YtQWUub9gYw

This pinmode is useful for measuring RC Servo outputs, PWM frequency and duty cycle, or any other signal where the pulse width is relevant. It is designed to measure repetitive signals. It is not intended to read a number of differing independent pulse widths that come one after another, such as WS2812 or similar output.

Warning
Care must be taken when using this pinmode with high frequency ( > 5 kHz) signals or pins that may be left floating on the Serial Wombat 4A / 4B because the Serial Wombat uses an interrupt internally to capture transition timestamps. Excessively frequent pin transitions may cause the interrupt handler to starve the main processing loop, impacting function of all pin modes and communications.

The Serial Wombat can be queried for overflow frames. If overflow frames are occuring, then the system is overloaded.

The Serial Wombat 4A and 4B can measure a maxium of 8 transitions per mS across all pulse input pins. More frequent transitions than this may result in incorrect measurements. The MeasurementOverflowOccurred flag is set if at any time more than 8 transitions occured without processing.

The number of pulses over time can be used for rough frequency measurements.

Consecutive High and low periods can be used to calculate duty cycle, although there is no indication whether high or low was most recent.

Constructor & Destructor Documentation

◆ SerialWombatPulseTimer()

SerialWombatPulseTimer::SerialWombatPulseTimer ( SerialWombat serialWombat)

Class constructor for SerialWombatPulseTimer.

Parameters
serialWombatThe Serial Wombat on which the SerialWombatPulseTimer pinmode will be run

Member Function Documentation

◆ begin() [1/2]

void SerialWombatPulseTimer::begin ( uint8_t  pin)

Simple initialization.

This initialization takes a Serial Wombat pin as a parameter, sets units to uS and disables pull-ups

Parameters
pinThe Serial Wombat pin used for pulse measurments. All 4 pins on the SW4A/SW4B may be used.

◆ begin() [2/2]

void SerialWombatPulseTimer::begin ( uint8_t  pin,
SerialWombatPulseTimerUnits  units,
bool  pullUpEnabled 
)

Initialization routine for SerialWombatPulseTimer.

Parameters
pinThe Serial Wombat pin used for pulse measurments. All 4 pins on the SW4A/SW4B may be used.
unitsSW_PULSETIMER_uS or SW_PULSETIMER_mS
pullUpEnabledTRUE = Pull Up Enabled, FALSE = Pull Up Disabled

◆ readHighCounts()

uint16_t SerialWombatPulseTimer::readHighCounts ( )

Retreives the most recent Counts in the configured units for the most recent high pulse.

Returns
Counts in mS or uS depending on configuration.

◆ readLowCounts()

uint16_t SerialWombatPulseTimer::readLowCounts ( )

Retreives the most recent Counts in the configured units for the most recent low pulse.

Returns
Counts in mS or uS depending on configuration.

◆ readPulses()

uint16_t SerialWombatPulseTimer::readPulses ( )

Retreives the number of pulses.

This value overflows at 65535. Reading this value does not clear it. This function has a side effect of reading MeasurementOverflowOccured from the Serial Wombat, which clears it for future readings.

Returns
Number of pulses counted (1 count per high/low cycle). Rolls over at 65535 to 0

◆ refresh()

void SerialWombatPulseTimer::refresh ( )

Retreive the latest values for HighCounts, LowCounts, Pulses, and MeasurementOverflowOccured.

This happens in two packets to the Serial Wombat, so data may not be coherent

◆ refreshHighCountsLowCounts()

void SerialWombatPulseTimer::refreshHighCountsLowCounts ( )

Retreive the High and Low counts from the Serial Wombat in a single transaction.

This command will retreive consecutive high and low periods from the serial Wombat. It it not guaranteed which is the most recent.

◆ refreshHighCountsPulses()

void SerialWombatPulseTimer::refreshHighCountsPulses ( )

Retreive the High counts and number of pulses Serial Wombat in a single transaction.

This command will retreive consecutive high and low periods from the serial Wombat. It it not guaranteed which is the most recent.

Member Data Documentation

◆ HighCounts

uint16_t SerialWombatPulseTimer::HighCounts = 0

Count in selected units of last retreived high pulse.

This value is updated by refresh, refreshHighCountsLowCounts, refreshHighCountsPulses, readHighCounts, readLowCounts

◆ LowCounts

uint16_t SerialWombatPulseTimer::LowCounts = 0

Count in selected units of last retreived low pulse.

This value is updated by refresh, refreshHighCountsLowCounts, readHighCounts, readLowCounts

◆ MeasurementOverflowOccurred

bool SerialWombatPulseTimer::MeasurementOverflowOccurred = false

◆ Pulses

uint16_t SerialWombatPulseTimer::Pulses = 0

Count of last retreived pulses.

This value is updated by refresh, and refreshHighCountsPulses