Implementing a Heart Beat in your code

What is a Heart Beat?

A heart beat is a program generated 'pulse' at some given frequency that can be used to show that all is well with the overarching code/application into which it is implemented. Heart beats are usually, but not always, indicated by the flashing on/off of an indicator, for example a LED. Whilst the indicator is flashing ('beating'), we know that the code is running, otherwise we may have a problem to be investigated.

Adding a heart beat indicator into your sketches is a simple and low overhead way of providing a visible way of demonstrating that your code is operating, particularly if it is an application that normally provides little visibility of operation. For example, a sketch that monitors sensors and only alerts when thresholds may be reached, etc. In these circumstances, it is reassuring that the code is running.

What Does Heart Beat Code and Components Comprise Of?

There are two parts to implementing a visible heart beat:

1. the hardware components to provide a visible indication of a heart beat, and

2. the software to drive the hardware.

To make life so very simple, the heart beat implementation offered by this article does not require any hardware components other than an Arduino compatible microcontroller as we shall be using the in built LED common to many of these boards. These boards have a built in LED ('LED_BUILTIN') on digital pin 13 which can be accessed directly. So, by using this feature, we do not need any other hardware components at all. That just leaves us to concentrate on the software for the heart beat.

Heart Beat Software/Code

The heart beat software can be considered in four parts:

1. the declaration/definition statements of the variables it requires to operate,

2. the declaration of a heart_beat() function,

3. the setup of the heart beat, and

4. invoking the heart beat anywhere in the end user code required.

The heart beat code is designed as a non-blocking function ('heart_beat()') and it can be included anywhere in the end user code, in any number of locations. As a minimum, and assuming that the main program loop is designed to repeat, the heart_beat() call should appear somewhere in this code section, for example at the start of the main loop.

Let's Look at Each Bit of the Heart Beat Code

1. Declarations and Definition Statements

#define heart_beat_pin   LED_BUILTIN  // digital pin for heart beat LED
long unsigned heart_beat_freq = 1000; // time(milliseconds) of heart beat frequency
long unsigned heart_beat_on_off_time; // the time the LED is on and off - 1/2 frequency
long unsigned last_heart_beat_time;   // time in milliseconds of last heart beat status change
bool heart_beat_status = HIGH;        // current status of heart beat, start high

The heart beat code can be tailored to the end user needs by modifying one of the above declarations and definition, as follows:

Internal or External LED Indicator - If it is that the in built microcontroller LED is not to be used then the definition 'heart_beat_pin' should be set to the digital pin number to be used for the external LED. As it is, out of the box, the code will use the in built LED on pin 13 (known by the constant LED_BUILTIN) thereby obviating any other hardware components or wiring.

Varying the Heart Beat Frequency - the frequency with which the heart beat operates can be set by pre-setting the variable 'heart_beat_freq' to be the number of milliseconds required. Note that the time the LED will be on and off will be one half of the preset frequency. For example, if a frequency of 1 hz or 1000 milliseconds is preset then the heart beat LED will stay on for 500 milliseconds and off for 500 milliseconds, i.e. one half a second each.

All other variables are used internally by the heart beat code and not user definable.

2. The heart_beat() Function

To keep matters simple, the heart beat code is implemented as a non-blocking, uncomplicated function, named 'heart_beat'. It has no parameters and is of type void.

The function is as follows:

//
// Function handles the heart beat cycle.
// May be called from anywhere, but at least every main loop cycle.
//
void heart_beat() {
 if (millis() - last_heart_beat_time >= heart_beat_on_off_time) {
   // time to swap status of the heart beat LED and update it
   last_heart_beat_time = millis();
   heart_beat_status = !heart_beat_status;           // invert current heart beat status value
   digitalWrite(heart_beat_pin, heart_beat_status);  // update LED with new status
 }
}

Simply add it into your code at some suitable point and ensure it is called at least within the main loop section.

3. Setup of the Heart Beat

The heart beat code is initialised within the setup() function, as follows:

 // setup heart beat
 pinMode(heart_beat_pin, OUTPUT);
 heart_beat_on_off_time = heart_beat_freq / 2; // LED is on and off at 1/2 frequency time
 // end of heart beat setup

There is nothing for the end user to do or modify here, simply to include the code within the setup() function.

4. Invoking the Heart Beat

For the heart beat to operate it is necessary and essential that the function 'heart_beat()' is called regularly. It can be inserted anywhere within the overarching end user application code, but it is normally best to insert a call within the main loop section of the code so that it cycles routinely. If it is that the main loop code does not auto-cycle then the heart_beat() function call may need to be included at other routinely visited points in the code. The function may be duplicated as many times as required without any effect on the normal operation of the heart beat.

A main loop example would be:

void loop() {
 heart_beat();
 // add your other code here...
}

And that's it! Keep the technique to hand and include in you sketches as a standard feature.

Further Reading

You might also find these contributions interesting and useful, by the same author:

• A Music & Lights Workbench designed to introduce those new to computer programming to the subject, using easy commands with cool effects. The approach is one of tutor and student

• A flexible, scalable library (ez_SIPO8_lib) supporting the implementation of multiple serial-in/serial-out ICs, 74HC595, either individually or in cascaded banks, up to 255 ICs (2040 output pins)

• A general switch library (ez_switch_lib), suitable for most switch types and wiring schemes, incorporating novel features

• UnderstandIng and UsIng Button SwItches, the basIcs - button switches, a simple but often tricky piece of kit. The tutorial provides in ins and outs of implementing a simple button switch, with flexibility to explore differences in circuit design, different reading methods and debouncing.

• Interrupts Driven Button Switches - an approach and example of tying a button switch to an external interrupt.

• Toggle Switches - how to reliably read a toggle style switch.

• Buttons & Lights Game - a bit of fun using button switches and LEDs.

• External Interrupts, a generic framework supporting concurrent asynchronous multiple interrupts. Configure multiple external interrupts with different characteristics and add code to provide post-interrupt asynchronous processing.

• Programmatic Timed Reminder Alerting, a programmatic framework for both elapsed and real-time asynchronous alerting. Define any number of reminder alerts (sub second to hours) and process asynchronously.