GY-63_MS5611/libraries/HeartBeat/README.md

HeartBeat

Arduino library for a HeartBeat with frequency and duty cycle.

Description

HeartBeat

The HeartBeat library offers a simple heart beat by sending pulses to a digital pin. Typical usage is to blink a (built in) LED as indicator a program is running (alive). Besides a LED other devices can be triggered by the heart beat, think of a buzzer, relay, stepper motor or a peristaltic pump.

The library uses no hardware timer and is based upon micros(). The user is responsible to call the beat() function as often as needed. Or better even more often.

The library allows to set the frequency runtime. This allows the HeartBeat to be used as a first level debugging tool. Different frequencies can indicate a different state of the program or a different level of some sensor. No heart beat indicates the program is stuck or blocked.

HeartBeatSL

Since version 0.3.0 a derived class HeartBeatSL is added which can
send specific diagnostic or error patterns. A pattern exists of 1 to 7 HIGH pulses separated by a fixed length LOW pulse. The length of the HIGH pulses can be coded with characters S and L (short and long). An example of an SOS pattern is "SLS". The unit length of the base pulse is determined by the frequency.

If a pattern is started it cannot be overwritten until it is either ready or explicitly stopped. If one wants to repeat a pattern the application has to repeat the call.

HeartBeatDiag

Since version 0.3.0 a derived class HeartBeatDiag is added which can
send specific diagnostic or error patterns. A pattern exists of 1 to 9 HIGH pulses separated by a fixed length LOW pulse. The (relative) length of the HIGH pulses can be coded with the digits 1 to 9. An example of an SOS pattern is 111333111. The unit length of the base pulse is determined by the frequency. The HeartBeatDiag gives some extra control compared to HeartBeatSL.

If a pattern is started it cannot be overwritten until it is either ready or explicitly stopped. If one wants to repeat a pattern the application has to repeat the call.

To keep patterns recognizable one can exaggerate the difference in length. 121 is harder to differentiate than 131, a rule of thumb is to use multiples of 3 (1, 3, 6 and 9) as length as it allows 4 length levels.

Many applications only need 2 lengths, short and long (BIOS alike), but the interface allows more. One could start with an extra long HIGH to indicate the start of a pattern or to get attention (think buzzzzzzzer). The variable length can also be used to indicate a level of a measurement.

HeartBeatDiag uses more RAM and PROGMEM than HeartBeatSL.

For more complex patterns, please check my pulsePattern library.

Interface

#include "HeartBeat.h"

HeartBeat

The interface of the base HeartBeat consists of the following functions:

• HeartBeat() constructor
• void begin(uint8_t pin, float frequency = 1.0) to configure the HeartBeat. The output pin should be unique. The default frequency is 1.0.
• void setFrequency(float frequency = 1.0) change the frequency of the pulsing. The default frequency is 1.0. Setting the frequency will not enable or disable the HeartBeat.
  The frequency must be > 0.001 otherwise it will be constrained to 0.001. On the upper side values beyond 10 Hz are hard for humans but are allowed.
• void setDutyCycle(float dutyCycle = 50) duty cycle in percentage time HIGH. The default duty cycle = 50 %. The duty cycle must be between 0.0 and 100.0 %.
  A value of 0 will put the heartbeat effectively off.
• float getFrequency() returns set frequency (or constrained value).
• float getDutyCycle() returns set duty cycle (or constrained value).
• void enable() enables the heart beat.
• void disable() disable the heart beat. Will switch the pin to LOW.
• bool isEnabled() returns true if the heart beat is enabled (running).
• void beat() the worker; this function checks if the HeartBeat is enabled and the OUTPUT (LED) must be toggled.
  It must be called as often as possible to keep a steady pace, preferably at least 4 times the given frequency.
  Not calling beat() effectively stops the heartbeat.
• uint8_t getState() returns the state of the heartbeat. Useful for debugging.

HeartBeatSL

The interface of HeartBeatSL adds of the following functions to HeartBeat:

• HeartBeatSL() constructor.
• bool code(const char * str) executes the pattern ONE time. Repeating the pattern means repeating the call. The max supported string length is 7.
• void codeOff() explicitly stops the pattern. Forced stop.

Minimal example

#include "HeartBeat.h"

HeartBeatSL HB;

void setup() 
{
  HB.begin(13, 3);  // PIN 13 with frequency 3

  // other setup here
}


void loop()
{
  HB.beat();
  if (some_error) HB.code("LSSLSL");  // ==> L HHHHHH L H L H L HHH 

  // other code here
}


void someOtherfunction()
{
  // ..
  if (other_error) HB.code("LSLSLS");
  // ..
}

Note: a code will be executed, even if the HB is disabled.

HeartBeatDiag

The interface of HeartBeatDiag adds of the following functions:

• HeartBeatDiag() constructor
• bool code(uint32_t pattern) executes the pattern ONE time. Repeating the pattern means repeating the call. The max supported pattern length is 9.
• void codeOff() explicitly stops the pattern. Forced stop.

Minimal example

#include "HeartBeat.h"

HeartBeatDiag HB;

void setup() 
{
  HB.begin(13, 3);  // PIN 13 with frequency 3

  // other setup here
}


void loop()
{
  HB.beat();
  if (some_error) HB.code(6113);  // ==> L HHHHHH L H L H L HHH 

  // other code here
}

Note: a code will be executed, even if the HB is disabled.

Applications

Applications include but are not limited to

• show an alive sign, typical freq of 1 Hz is sufficient.
• show error code by means of different frequencies.
  • 1 Hz = OK
  • 2 Hz = Warning
  • 5 Hz = Error
  • no signal would indicate also an error.
• indicate state of power sensor
  • e.g. freq = round(amps) or duty cycle = round(amps)
  • optional map the range! logarithmic
  • continuous scale vs stair-cased
• indicate the volume by increasing heartBeat
• indicate a changing distant - increasing or decreasing.
• Geiger counter style.

With the HeartBeatDiag and HeartBeatSL one can give different and therefore more specific "(error) messages" depending on the state of the application or a sensor.

Operation

See examples

Future

• add examples
  • SRF05 distance sensor
  • ACS712 current sensor
• test HeartBeatDiag version in more detail.
• investigate a pattern recognizer (fun)
  • e.g. with an LDR or lux sensor.
• separate changelog.md