mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
240 lines
7.4 KiB
Markdown
240 lines
7.4 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/HeartBeat/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/HeartBeat/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/HeartBeat/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/HeartBeat/releases)
|
|
|
|
|
|
# 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
|
|
|
|
```cpp
|
|
#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
|
|
```cpp
|
|
#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
|
|
```cpp
|
|
#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
|
|
|
|
#### must
|
|
- test HeartBeatDiag version in more detail.
|
|
|
|
#### should
|
|
- add examples
|
|
- ACS712 current sensor
|
|
- buffer % filled (e.g. stream)
|
|
|
|
#### could
|
|
- investigate a pattern recognizer (fun)
|
|
- e.g. with an LDR or lux sensor.
|
|
|